Concepts

The building blocks of a Tangle project - rooms, devices, modules, capabilities, state, intents, scenes, timelines, automations, variables, listeners, dashboards and core nodes.

This page explains the words used across Tangle and how the pieces relate. Every part of Tangle (core, modules, dashboards, the designer, the API) shares one set of definitions, the Tangle contract, written as JSON Schema. The current contract version is 0.2.43.

#Project

A project is everything core needs to run one site or one show, in one file (JSON or YAML). It holds:

The smallest valid project:

{ "id": "my-show", "name": "My show" }

Core keeps a library of projects on its computer (Open or new project… in the designer, tangle-core projects on the command line) and runs one at a time. It loads the project at start, checks it against the schema and checks references (a scene that names a missing device is an error). Changes made through the designer, dashboards, REST or MCP are checked the same way, applied live, written back to the file and recorded in audit.log. Passwords and keys never go in the file. See Project file.

#Identifiers

Ids of rooms, devices, scenes, timelines, cues, dashboards and modules are lowercase: letters, digits, ., _ and -, starting with a letter or digit, up to 128 characters. room-a.projector-1 is valid; Room A is not. Times are integer milliseconds since the Unix epoch (UTC).

#Rooms

A room groups devices by place: a meeting room, a gallery, the stage. A room has an id, a name and optional tags. A device belongs to at most one room. Rooms are what you target to control a whole space ("turn the Hall off"), and what room dashboards are generated from.

#Devices

A device is one controlled thing in the project: a projector, a media server, a DSP, a lighting device, a computer. A device is one module plus one configuration:

{
  "id": "hall-projector",
  "name": "Hall projector",
  "moduleId": "misc.pjlink.projector",
  "room": "hall",
  "tags": ["projectors"],
  "config": { "host": "10.0.0.21", "port": 4352 }
}

#Status

Every device reports a connection status:

See Devices.

#Modules

A device module is the driver for a kind of device. It runs as its own process, started and supervised by core, and talks to core over a simple JSON protocol on standard input and output. A crash affects only that module: core restarts it with a backoff. Core also limits every action to 15 seconds.

Module ids follow <manufacturer or misc>.<product or protocol>.<category>[.<version>], for example misc.pjlink.projector, qsc.core.dsp or dataton.watchout.mediaserver.v7. Categories include timecode, projector, display, mediaserver, engine, player, computer, io, dsp, lighting, console, switcher, control, generic, gateway, network, microphone, camera, codec, presentation, avoip, routing, amplifier, building, power and scheduling, plus listener and library for modules that open listeners or add functions.

Each module ships a manifest (tangle-module.json) that declares:

• the runtime: Node.js, Python or a native executable;
• the capabilities its devices support, standard and custom;
• the settings schema, which the designer turns into a form;
• the permissions it needs (network, serial, USB, MIDI, file system);
• optionally, network discovery, ready-made dashboard controls and layouts, setup assistants for the device side, documentation links and several connections (LAN and RS-232, say).

Modules are installed from the designer's Driver library, or with tangle module add, and written with the module SDK or, without code, with the device creator. See the device catalog for the official modules.

#Capabilities

A capability is a reusable set of state keys and actions. Capabilities let core, scenes and dashboards control any device the same way, whatever its protocol: every device with tangle.power turns on with the same action.

Standard capabilities:

A module can add custom capabilities under its own prefix. The PJLink module adds pjlink.lamp (lamp hours), pjlink.status (power including warming and cooling) and pjlink.health (fan, lamp, temperature, cover, filter errors).

State values and action parameters are typed: boolean, number (with optional min, max, step and unit), string, enum or JSON. The designer uses these types to build its pickers, for example a number field limited to 0 to 1 for tangle.level set.

#State

State is what a device reports right now, per capability: tangle.power on: true, tangle.level level: 0.8, pjlink.lamp hours: 1790. Modules push state as it changes or as they poll. Core keeps the latest state of every device and sends changes to clients. Dashboards display state through bindings; automations trigger on it and test it in conditions.

#Actions

An action is one concrete command for one device: device, capability, action name and parameters.

{ "deviceId": "hall-projector", "capability": "tangle.input", "action": "select", "params": { "input": "31" } }

Scenes are lists of actions. Timeline cues and automations can run an action directly or send an intent.

#Events

Core publishes events when something changes. Each event has a topic <type>:<subject id>, and clients subscribe to the topics they need (wildcards such as device.state:* are allowed).

See WebSocket.

#Intents

An intent says what should happen, not how: "power on the Hall", "recall Presentation in room A". Core resolves the target to devices, turns the intent into actions for the devices that support it, and reports the outcome. Dashboards, timelines, automations and API clients all control devices through intents.

{
  "name": "scene.recall",
  "target": { "kind": "room", "id": "hall" },
  "params": { "scene": "presentation" },
  "priority": 30
}

#Intent names

Devices without the capability are skipped and reported, not treated as errors.

#Target kinds

#Priority and holds

Each intent has a priority from 0 to 100. When two intents act on the same device state and overlap, the higher priority wins and the other reports the device as overridden. Defaults depend on the source: system 90, timeline, schedule and automation 50, everything else (users, dashboards, API) 30.

• The holdMs parameter keeps the intent's priority on the state it set for that long.
• An intent with priority 90 or more holds the state until a release intent.

An intent can also carry at (run at a time) and expiresAt.

#Intent status

An intent goes through accepted, scheduled, running, then ends completed, partial, failed, rejected or cancelled. Each device gets an outcome: ok, failed, overridden or skipped. A room intent where one of three devices is offline ends partial and names the offline device.

#Scenes

A scene is a named set of device actions recalled together: "Presentation" turns the projector on, selects HDMI 1 and dims the lights.

{
  "id": "presentation",
  "name": "Presentation",
  "actions": [
    { "deviceId": "hall-projector", "capability": "tangle.power", "action": "on" },
    { "deviceId": "hall-projector", "capability": "tangle.input", "action": "select", "params": { "input": "31" } }
  ]
}

Recall a scene with the scene.recall intent. Only the actions for devices inside the intent's target run, so one scene can be recalled for a whole site or for one room.

#Timelines

A timeline is a show: tracks of cues, each cue at a position in milliseconds. A cue sends an intent or runs a device action, can fire early by a pre-roll to absorb device latency, and can be disabled.

Transport operations are play, pause, stop, seek and go. A timeline's status is stopped, playing, paused or waiting (a cue list waiting for GO, or a chasing timeline waiting for timecode).

Note: The older ltc and mtc clock forms are not played: use a timecode clock with an input device.

See Timelines.

#Automations

An automation is a named list of steps, run when one of its triggers fires and its conditions hold, or whenever something runs it: a dashboard button, a listener, another automation, the API.

• Triggers (any one starts a run): time of day, device state, device event, device status, timeline (started, stopped, cue reached), project variable, dashboard control, listener message, core start, only by hand.
• Conditions (all must hold): device state, device status, time window, timeline status, variable, dashboard control.
• Steps (in order): intent, device action (optionally waiting until the device reports it is done), timeline, wait, wait for a condition, if, repeat, while, set a variable, set a control, run another automation, call a function, stop, comment, log.
• Params pass values in (a slider's level), and mode decides what a trigger does while a run is in progress: single (ignore), restart, queued or parallel.

Automations run on the primary core only. Macros, from older projects, are automations now. See Automations.

#Variables and expressions

A project variable is a value core keeps for the whole project, such as houseMode = "show" or visitors = 12. Automations, listeners, dashboards and the API read and set it, and automations can start when it changes. Steps, bindings and labels read variables and params as {{name}}, and compute values with expressions such as clamp({{level}} * 1.2, 0, 100). See Automations.

#Listeners

A listener opens a port (WebSocket, HTTP, TCP, UDP, OSC) or a serial line for other systems, which send their own messages. Rules match each message and set variables, run steps and automations, and answer. See Listeners.

#Dashboards

A dashboard is a control surface: pages of controls (buttons, toggles, sliders, keypads, scene lists, status, transport, GO, cameras, maps…) laid out on a grid per screen size. Controls read device state, variables, other controls or expressions through bindings, and send intents, timeline commands, run automations or set variables. Each dashboard has a skin (Console or Lobby), a control style (Classic, Studio, Skeuomorphism or Relief), a theme (light, dark or auto) and an access mode (anyone, PIN, or enrolled panels). Screens open it at /d/<id>. See Dashboards.

#Core nodes and clusters

A core node is one running tangle-core. Each node has an id (default core-1) and a role:

For redundancy, two or more nodes run the same project and exchange heartbeats over port 7341. Every node plays timelines on a shared cluster clock; only the primary drives devices. If the primary stops, the next node takes over within a second at the same point in the show. In shared mode, devices are spread across the healthy nodes instead, while the primary still runs timelines and automations. Each failover increases an epoch counter, and the highest epoch wins, so two nodes never both stay primary. Backups compare a log of the cues they computed with the primary's and resync if they differ. With three or more nodes, a node is primary only while it reaches a majority.

See Redundancy.