Project file

The Tangle project file format in JSON or YAML - rooms, devices, scenes, timelines, dashboards, automations, variables, listeners and Sentinel monitoring.

A Tangle project is one file that holds everything tangle-core runs: rooms, devices, scenes, timelines, dashboards, automations and monitoring. The designer, the REST API, MCP and the tangle command all edit this file; you can also write it by hand. This page describes every section and field.

#Format and loading

• The file is JSON (.json) or YAML (.yaml, .yml). The format follows the extension. Changes made through the API are saved back in the same format.
• Field names are camelCase. Unknown fields are refused.
• Ids (id, deviceId, room and other references) are lowercase: letters, digits, ., _ and -, starting with a letter or digit, at most 128 characters. For example room-a, room-a.projector-1.
• Timestamps are milliseconds since the Unix epoch (UTC). Times of day are "HH:MM" (24 h) in the core machine's local time. Weekdays are mon, tue, wed, thu, fri, sat, sun.

Core checks a project in two steps: first against the contract JSON Schema (Project), then the cross-references the schema cannot express. Every error names the place to fix. Check a file without running it:

tangle-core check --project show.yaml

error: project is invalid:
  scene presentation action 2: unknown device light-3

Cross-reference checks:

• Ids are unique within rooms, devices, scenes, timelines, automations, alert rules, notification channels, maintenance windows and probes.
• A device's room exists.
• Scene actions point at existing devices.
• Cues point at existing devices (action cues) or existing rooms and devices (intent cue targets).
• Automation triggers, conditions and actions point at existing devices, timelines and cues; a scene.recall intent names an existing scene; a cue trigger has a cueId.
• Alert rules point at existing devices, rooms and notification channels; a stale condition has capability and key, or metric.
• Maintenance windows point at existing alert rules, devices and rooms, and have start (once) or from and to (weekly).
• A probe's room exists.

The license also limits what a project may contain (devices, DMX universes, timelines). See Licensing.

#Top level

#Complete example

A meeting room with a projector and two lights, a scene, a short cue list, a dashboard, an automation and a monitoring rule:

{
  "id": "demo",
  "name": "Demo building",
  "contract": "0.2.43",
  "rooms": [{ "id": "room-a", "name": "Room A" }],
  "devices": [
    { "id": "proj-1", "name": "Projector", "moduleId": "misc.pjlink.projector", "room": "room-a", "config": { "host": "10.0.0.20" } },
    { "id": "light-1", "name": "Ceiling light", "moduleId": "tangle.virtual-light-js", "room": "room-a" },
    { "id": "light-2", "name": "Wall light", "moduleId": "tangle.virtual-light-py", "room": "room-a", "tags": ["wall"] }
  ],
  "scenes": [
    {
      "id": "presentation",
      "name": "Presentation",
      "actions": [
        { "deviceId": "proj-1", "capability": "tangle.power", "action": "on" },
        { "deviceId": "light-1", "capability": "tangle.level", "action": "set", "params": { "level": 0.3 } },
        { "deviceId": "light-2", "capability": "tangle.power", "action": "off" }
      ]
    }
  ],
  "timelines": [
    {
      "id": "welcome",
      "name": "Welcome",
      "mode": "cuelist",
      "tracks": [
        {
          "id": "main",
          "name": "Main",
          "cues": [
            { "id": "c1", "name": "House to half", "atMs": 0, "payload": { "kind": "intent", "intent": { "name": "level.set", "target": { "kind": "room", "id": "room-a" }, "params": { "level": 0.5 } } } },
            { "id": "c2", "name": "Presentation", "atMs": 5000, "payload": { "kind": "intent", "intent": { "name": "scene.recall", "target": { "kind": "room", "id": "room-a" }, "params": { "scene": "presentation" } } } }
          ]
        }
      ]
    }
  ],
  "dashboards": [
    {
      "id": "room-a",
      "name": "Room A",
      "access": { "mode": "open" },
      "pages": [
        {
          "id": "main",
          "name": "Main",
          "widgets": [
            {
              "id": "light",
              "type": "toggle",
              "label": "Ceiling light",
              "props": { "value": { "kind": "state", "device": "light-1", "capability": "tangle.power", "key": "on" } },
              "action": { "kind": "intent", "name": "power.on", "target": { "kind": "device", "device": "light-1" } },
              "offAction": { "kind": "intent", "name": "power.off", "target": { "kind": "device", "device": "light-1" } }
            }
          ],
          "layouts": { "tablet": [{ "widget": "light", "x": 0, "y": 0, "w": 3, "h": 2 }] }
        }
      ]
    }
  ],
  "automations": [
    {
      "id": "evening-off",
      "name": "Lights off at night",
      "triggers": [{ "kind": "time", "at": "22:00" }],
      "steps": [{ "kind": "intent", "intent": { "name": "power.off", "target": { "kind": "room", "id": "room-a" } } }]
    }
  ],
  "alertRules": [
    { "id": "offline", "name": "Device offline", "severity": "critical", "condition": { "kind": "status", "rooms": ["room-a"] }, "forSeconds": 30, "channels": ["techs"] }
  ],
  "notificationChannels": [
    { "id": "techs", "name": "Technicians", "kind": "webhook", "settings": { "url": "https://ops.example.com/tangle" } }
  ],
  "maintenanceWindows": [{ "id": "sunday", "name": "Sunday", "days": ["sun"], "from": "02:00", "to": "04:00" }],
  "probes": [{ "id": "switch-1", "name": "Core switch", "kind": "tcp", "host": "10.0.0.2", "port": 22 }]
}

The same project start in YAML:

id: demo
name: Demo building
rooms:
  - id: room-a
    name: Room A
devices:
  - id: proj-1
    name: Projector
    moduleId: misc.pjlink.projector
    room: room-a
    config:
      host: 10.0.0.20
scenes:
  - id: presentation
    name: Presentation
    actions:
      - deviceId: proj-1
        capability: tangle.power
        action: "on"

Note: in YAML, quote values such as "on", "off", "yes" and "no", or YAML reads them as booleans.

#Rooms

An intent with target { "kind": "room", "id": "room-a" } reaches every device whose room is room-a.

#Devices

Each device is one module plus one configuration (contract DeviceInstance).

• Secret settings (marked x-secret in the module) are not stored in the project file: they go to the OS credential store when set through the designer, the API or tangle device add. Set one by hand with tangle device secret <device> <setting>.
• A device whose module is not installed is accepted; its status shows the problem.
• DMX modules put the universe a device uses in a universe setting; licensing counts distinct universes.

Every device reports a status: connecting, online, degraded, offline, timeout or error. See Devices.

#Scenes

A scene is recalled with the scene.recall intent (params.scene). Only the actions for devices inside the intent's target run.

Scene action:

#Timelines

#Tracks

#Cues

Payloads:

#Clocks

Timecode values are HH:MM:SS:FF, with ; before the frames for drop-frame. See Timelines.

#Dashboards

The project holds the published version of each dashboard. Drafts and older versions are kept by tangle-core outside the project file. See Dashboards.

Access:

Page:

Screen classes: phone below 600 px wide, tablet below 1024, panel below 1440, desktop above. A layout is a list of { "widget", "x", "y", "w", "h" } on a grid of 12 columns (4 on phone).

Widget:

Bindings (props values):

A device reference is a device id, or a selector among a room's devices: { "room": "<room id>" | "$room", "capability", "tag", "index" } (index: which match in project order, default 0).

Widget actions:

#Automations

Run by tangle-core on the primary (or a standalone node). The Automations guide lists every trigger, condition and step kind with its fields.

Trigger kinds: deviceState, deviceEvent, deviceStatus, time, timeline, variable, control, listener, startup, manual. Condition kinds: state, status, time, timeline, variable, control. Step kinds: intent, action, timeline, delay, if, repeat, while, waitUntil, set, control, automation, call, stop, comment, log; every step takes disabled.

#Alert rules

Monitoring (Sentinel) is part of Tangle Pro and Ultimate. See Sentinel.

Conditions:

Metric names use letters, digits, ., _ and -, for example room.temperature. Labels are string pairs, for example { "room": "server" }.

#Notification channels

Secret settings (marked below) go to the OS credential store when set through the designer or the API; the project keeps ********.

#Maintenance windows

A maintenance window mutes notifications, once or every week.

With no rules, devices or rooms, it applies to everything.

#Probes

A probe checks a network asset that has no device module. It produces the metrics probe.up, probe.latencyMs and, for HTTP, probe.httpStatus, labelled probe=<id>.

#Related files

• tangle.lock next to the project: module versions written by tangle module lock, made active when tangle-core starts. See CLI.
• Secrets, dashboard drafts and history, and alert history live in the Tangle data folder, not in the project. See CLI.