Devices

Add, configure, test and discover devices, manage the device modules that drive them, and pin hardware to one machine.

A device is one thing Tangle controls: a projector, a media server, a PC, a DMX universe, a timecode input. Each device uses a device module, which knows how to talk to that kind of device. This page covers adding and configuring devices, testing them, finding them on the network, and installing the modules they need.

#Devices and modules

Every device in a project has:

Module ids follow <manufacturer or misc>.<product or protocol>.<category>[.<version>], for example barco.pulse.projector or dataton.watchout.mediaserver.v7. The Device catalog lists every official module.

#Add a device

#In the designer

1. Click Add device on the Devices page, or right-click a room in the project tree and choose Add device.
2. Type a Name. The Id is filled in from the name; you can change it until the device is created.
3. Pick the Driver. The list shows the drivers installed on the core. To use another one, click Driver library: find, install or share drivers…: search by manufacturer, product or name, and click Use. A driver that is not installed yet is installed first, after you confirm the permissions it asks for (network, serial…). See Driver library.
4. Optionally pick a Room, a Folder and Tags (comma-separated).
5. Fill in Settings. This form is built from the driver's settings schema: text, number, on/off and list fields, with defaults shown as placeholders and required fields marked with *. Settings the form cannot show as a simple field are edited as JSON. A driver with several connections (LAN and RS-232, say) shows the connection list first and only the settings of the chosen connection.
6. Tick Planned (not started yet) for a device that is not on site yet: it stays in the project, its cues and controls can be programmed, and core does not try to reach it.
7. Click Create device.

Tangle checks the settings against the driver's schema when you save. A missing required setting, such as host for a PJLink projector, is refused with an error naming the setting.

When the driver has a setup assistant meant for new devices, it opens right away.

#The device page

Open a device from the project tree or the device list. Beside its settings (with Save, Test connection and Delete…), the page shows:

• Setup: the driver's setup assistants and documentation links (the vendor's protocol reference, compatible models).
• Status: the device's live state, as the driver reports it.
• Controls: the controls the driver offers, ready to use, in a Layout (Compact, Operator, Full, and more for some drivers) and a Look (Classic, Studio, Skeuomorphism, Relief). The same layouts are offered when you add the device to a dashboard.
• Log: see Device log.

Driver can be changed on an existing device. The id and the settings the new driver also has are kept, and Tangle warns about the cues, scenes, automations and dashboard controls that use something the new driver does not offer.

#The device list

Devices (or All devices in the project tree) lists every device with its driver, room, folder, tags and live status, and "Setup recommended" when a device answers but is not set up for Tangle yet.

• Folders on the left, with counts, All devices and No folder. + New folder, rename, and drag devices onto a folder.
• Filters: search, type, driver, room, tag and status.
• Selection: tick devices (or ⌘ / Shift-click them in the project tree) to tag, move to a folder or delete several at once.

A device whose driver is not installed shows its driver id with "(not installed)".

#Delete devices

Delete… first lists everything that uses the devices: scenes, timeline cues, automations, maps, dashboards, lighting, alert rules, maintenance windows and sub-devices. Then choose:

• Delete everything: their timeline cues and dashboard controls go too.
• Keep timeline cues as comments: each cue becomes a note ("Removed device Projector 1: power on") that Point at device… turns back into a cue later, and dashboard controls stay, showing the device as missing.

Either way, scene actions, map placements, lighting values and the automation triggers, conditions and steps that use the devices are removed, since they cannot run without them. An automation left without triggers or steps is deleted; one that lost a condition is turned off, so it never runs more often than intended. The API does the same with POST /api/v1/devices/references and POST /api/v1/devices/remove.

#From the command line

The tangle command edits the project file directly:

tangle device add -p show.yaml pj-1 -m misc.pjlink.projector --room hall --set host=10.0.0.5 --set password=admin
tangle device list -p show.yaml
tangle device remove -p show.yaml pj-1

--set key=value can be repeated. Numbers and booleans are typed from the module's schema. --name sets the display name.

Note: tangle device commands refuse to change a project while tangle-core is running it. Use the designer, the REST API (/api/v1/devices) or MCP instead: they run the same checks.

#Import and export device lists

To add many devices at once, import a CSV or JSON file:

tangle device import -p show.yaml displays.csv
tangle device import -p show.yaml displays.csv --dry-run        # check only
tangle device import -p show.yaml displays.csv --skip-invalid   # add the valid rows anyway
tangle device export -p show.yaml --format csv -o displays.csv

CSV columns are id, name, moduleId, room, tags (separated by ;) and one config.<setting> column per setting, for example config.host. Cells are typed from the module's configSchema. Without --skip-invalid, nothing is added if any row is invalid; errors give the line number. export writes to stdout without -o; --format is csv (default) or json.

#Passwords and other secrets

Settings marked "x-secret": true in a module's schema (passwords, PINs, tokens, private keys) never go into the project file. They are stored in the operating system's credential store on the machine that runs the device:

Entries use service tangle and account <deviceId>/<setting>. On Linux, when no credential store answers (a service without a desktop session), secrets go to secrets.json in the Tangle data folder, readable by its owner only. Set TANGLE_SECRETS=file to force that file.

In the designer, secret fields are password boxes ("stored securely; type to change"). On the command line, --set moves secret settings to the store, or use:

tangle device secret pj-1 password            # prompts without echo, or reads stdin when piped
tangle device secret pj-1 password --delete

Because secrets stay on the machine, a project file copied to another computer contains no passwords. Set them again there.

#Test a connection

A connection test starts the device's module on its own, in a separate process, adds the device and waits for it to come online. It never touches the running project's modules. It gives up after 10 seconds.

• Designer: open the device and click Test connection. It tests the settings in the form, without saving. The result shows "Connected" with the status and time, or "Not connected" with the reason.
• Command line: tangle device test -p show.yaml pj-1
• API: POST /api/v1/devices/{id}/test, or the MCP tool test_device.

#Setup assistants

Many devices need something switched on before Tangle can control them: PJLink on a projector, the web interface of VLC, Remote Login on a Mac. A setup assistant walks through it: what to enable on the device, step by step, then does the rest itself where it can (saves the password it was given, installs an SSH key, checks that the device answers).

• An assistant meant for new devices opens right after Create device. Finish later closes it and keeps your progress; Don't set this up dismisses it.
• The Setup card of the device page lists the driver's assistants (Start) and its documentation links.
• A device that answers but is not set up for Tangle yet (remote control off, no password, key refused) shows Setup recommended in the device list and on its page.

Assistants exist for PJLink projectors (network control, password), SSH computers (Remote Login, key, power rights), PowerShell remoting, PsExec, VLC (web interface, preview stream) and Reaper. Progress is saved with the device (setup), never its secrets. API: POST /api/v1/devices/{id}/configurators/{configurator}/run, MCP run_device_setup.

#Device log

Core keeps the last 500 entries of each device: the actions sent to it (by whom: a dashboard, an automation, a timeline, the API) and how they ended, status changes, state changes (changes within 2 seconds are merged) and device events. Each entry has a level: info, warning or error. The log survives a core restart and is deleted with the device.

The Log panel of the device page follows it live, with filters (Actions, Status, State, Events, Notes; Everything, Warnings and errors, Errors), Clear, and Add to write a note ("lamp replaced"). Dashboards show it with the Device log widget, and automations write to it with a Log step.

Some actions take time: a projector warming up reports "warming up", then done or failed. The log shows each step, and automations can wait for the end (see Automations).

API: GET /api/v1/devices/{id}/log (limit, before, kinds, level), GET /api/v1/devices/log?devices=a,b (several merged), DELETE /api/v1/devices/{id}/log; event topic device.log:<deviceId>; MCP get_device_log, add_device_log_note, clear_device_log.

#Network serial ports

Serial devices (RS-232, RS-422, RS-485) are often far from the computer that runs Tangle. Every serial driver, and the device creator's serial connection, accepts a network serial port wherever it asks for a serial port:

In the designer the serial port field is a picker: this computer, gateway TCP, RFC 2217 or UDP, with a search for gateways. Scan the network also finds Moxa, Lantronix and Digi gateways and suggests the generic serial driver with their address.

A gateway on the network also keeps the device reachable when the primary of a cluster changes, which a USB adapter cannot.

#Find devices on the network

Discovery listens for mDNS/DNS-SD services, asks UPnP devices to answer (SSDP), and runs the search of every installed module that has one (for example the PJLink class 2 search, BrightSign players, Art-Net nodes). For each device found it lists the address and, when known, the name, manufacturer and model, plus suggested modules: official modules first, exact model matches before manufacturer-only matches. A module that found the device itself is suggested first.

• Designer: on the Devices page, click Scan the network (5 seconds). Click Add next to a result to open a new device with the suggested module, name and host filled in.
• Command line: tangle discover --seconds 5 (1 to 30 s; --json for machine-readable output).
• API: POST /api/v1/discovery, or the MCP tool discover_devices.

Discovery only runs when someone starts it. tangle-core refuses a scan while a timeline is playing (show mode). tangle discover refuses while any project is running and points you to the core's API.

#Statuses

Every device reports a connection status:

Every module reports at least online, offline and timeout. The status usually carries a detail, such as "no route to host; retrying in 4 s".

What Tangle does on its own:

• Reconnect. An offline or timeout device is retried after 1 s, then 2 s, 4 s and so on, up to 30 s, until it answers. An error device is not retried until you change its settings.
• Polling. Most modules ask the device for its state every 10 s. One failed poll marks it degraded; two in a row count as a lost connection.
• Actions while unreachable. An action sent to an offline or timeout device fails at once as retryable, so core can try again, instead of waiting.
• Action limits. Actions to the same device run one at a time, in order. An action that takes more than 10 s fails and the next one runs. tangle-core also fails any action its module has not answered within 15 s.

#Driver library

The Driver library on the device page finds a driver and installs it in one step:

• Tangle and this computer: the drivers bundled with Tangle (installed or not) and the ones made on this core with the Device creator.
• My community drivers: the drivers you published on the community repository.
• Also search all community drivers: every driver shared on community.tangle.systems, by manufacturer, product, name or username. Community drivers are named after their author (louis/acme.widget.display) and are not reviewed by the Tangle team. A driver that misbehaves can be reported.

Settings > Modules lists every module the core knows (installed and not installed), with Install and Scan again.

#Install and remove modules

The desktop app includes the official modules, ready to install from the designer. To install a module from a folder (your own, or one you were given):

tangle module add ./barco.pulse.projector
tangle module add ./barco.pulse.projector --yes    # grant the permissions it asks for without asking
tangle module list                                  # --json for details
tangle module rollback barco.pulse.projector        # back to the previous version
tangle module remove barco.pulse.projector

When you add a module, Tangle:

• checks its manifest, that it supports this Tangle's contract version, and that its entry file exists;
• refuses a module that declares a category but whose folder is not named exactly after its id;
• shows the permissions it asks for (network, serial, usb, midi, filesystem) and asks you to confirm, also on updates that add permissions;
• warns that a module installed from a folder is unsigned, and that a community module is not reviewed by the Tangle team;
• checks that its runtime is installed: Node.js or Python at the version it asks for. Set TANGLE_NODE or TANGLE_PYTHON to use a specific interpreter. A Python module with a requirements.txt gets its own virtual environment, built from a bundled wheels/ folder when present, so installing works offline.

Tangle keeps the active and the previous version of each module, so rollback can go back one step. A module used by a running project cannot be removed, and replacing the version a running project uses is refused; projects pick up a new version when they are next loaded.

#Where modules live

Each module has its own folder, modules/<id>/, with one sub-folder per installed version and an install.json recording the active and previous versions. A module folder copied by hand into modules/ also works; it is listed as local. When tangle-core runs as a boot service it uses the machine-wide folders (/Library/Application Support/Tangle on macOS, /var/lib/tangle on Linux). TANGLE_HOME moves everything into one folder.

#Lock module versions per project

To run a project with exactly the same module versions on another machine:

tangle module lock -p show.yaml     # writes tangle.lock next to the project
tangle module sync -p show.yaml     # on the other machine: activates the locked versions

sync reports each module as ok, activated, not installed, or installed with files that differ from the lock. tangle-core also activates the locked versions when it starts a project and reports missing or altered ones.

#Hardware attached to one machine

In a redundant cluster, networked devices are driven by whichever node is primary. Hardware plugged into one computer (a USB DMX interface, a serial port, an LTC sound card output) can only be driven from that computer. Give such a device a node:

devices:
  - id: dmx-usb
    name: USB DMX
    moduleId: misc.usbdmx.lighting
    node: core-b
    config: { port: /dev/tty.usbserial-EN123456 }

Only core-b runs that device's module; the primary reaches it through core-b. If core-b is down, the device is offline. For anything that must survive a machine failure, prefer network gateways (Art-Net or sACN nodes, serial-over-IP adapters). Some modules require a node of a given operating system: microsoft.psexec.computer only runs on a Windows node.

#How modules run

Each module runs as its own process, started by tangle-core:

• One process per module. Ten displays that use the same module share one process, which receives one device.add per display. A crash in one module cannot affect another module or core.
• JSON over stdin and stdout. Core and module exchange JSON-RPC 2.0 messages, one JSON object per line. The module logs to stderr. The protocol is described in Module SDK.
• Supervision. Core pings each module every few seconds. A module that crashes or misses 3 pings is restarted, after 1 s, then with a doubling delay up to 60 s. Five crashes within a minute are reported as an unstable module.
• Latency. A module whose average action latency goes above 500 ms is reported as slow.
• Native modules. Timecode, MIDI and DMX modules are native programs rather than Node.js or Python scripts, because they need steady timing. Modules that share hardware or sockets share one process: all DMX and Art-Net timecode modules run in tangle-dmx, all MIDI modules in tangle-midi, PTP and NTP in tangle-clock. LTC runs alone in tangle-ltc.

Note: Modules run as separate processes, but restricting what a module can reach based on its declared permissions (sandboxing) is not available yet. Permissions are shown for your consent.