Guide
#Structure of a scenario
A scenario is a JSON document using format version 2. The JSON reference lists every field; this page explains how the fields fit together.
{
"formatVersion": 2,
"title": "Example installation",
"lines": [{ "address": "1.1" }],
"groupAddresses": [],
"devices": [],
"options": { "speed": 1, "filterTables": false }
}Only formatVersion, lines, and devices are required. The optional fields are title and description (shown above the diagram), groupAddresses (names and DPTs for the monitor), topology (IP routing and coupler settings), rooms (heated rooms), clock (simulated date and time, see time), and options (initial simulation speed and filter table display). For editor completion, set $schema to the published schema, https://ynn.github.io/busdiagram/schema/scenario-v2.schema.json, or to schema/scenario-v2.schema.json in a local copy.
#Topology
The diagram layout is derived from the addresses; you do not need to enter drawing coordinates.
| Declaration | Diagram |
|---|---|
One line, such as 1.1 |
That line and its devices. |
Several lines in one area (1.1, 1.2) |
The main line and line couplers 1.1.0 and 1.2.0. |
Several areas (1.1, 2.1) |
A backbone and area couplers 1.0.0 and 2.0.0. |
topology |
KNXnet/IP routing and coupler settings; see topology. |
An extension on a line |
A downstream segment with a repeater or segment coupler. |
{
"formatVersion": 2,
"title": "KNX topology: couplers, repeater, and KNXnet/IP routers",
"description": "Two areas are connected by an IP network. KNXnet/IP routers 1.0.0 and 2.0.0 act as area couplers. The installation has four lines, a line extension, and a supervisor on the IP network. Compare the route of a local command with that of a status telegram.",
"lines": [
{ "address": "1.1", "powerSupply": { "currentMa": 640 } },
{ "address": "1.2", "powerSupply": { "currentMa": 640 } },
{
"address": "2.1",
"powerSupply": { "currentMa": 640 },
"extension": {
"address": "2.1.64",
"mode": "repeater",
"switchable": true,
"powerSupply": { "currentMa": 320 }
}
},
{ "address": "2.2", "name": "no device", "powerSupply": { "currentMa": 640 } }
],
"topology": { "ip": "areaCouplers" },
"groupAddresses": [
{ "address": "1/1/1", "name": "Living-room lighting", "dpt": "1.001" },
{ "address": "1/3/1", "name": "Corridor lighting", "dpt": "1.001" },
{ "address": "1/4/1", "name": "Living-room lighting status", "dpt": "1.001" },
{ "address": "1/4/2", "name": "Corridor lighting status", "dpt": "1.001" },
{ "address": "2/1/1", "name": "Shutter 1 up/down", "dpt": "1.008" },
{ "address": "2/2/1", "name": "Shutter 1 stop/step", "dpt": "1.007" },
{ "address": "2/4/1", "name": "Shutter 1 position", "dpt": "5.001" }
],
"devices": [
{
"id": "sup",
"name": "Supervisor",
"kind": "supervisor",
"behavior": "display/v1",
"description": "The supervisor listens through the KNX/IP router. It sends no commands; it observes shutter commands and displays status feedback.",
"objects": [
{
"id": "pos",
"name": "Shutter 1 position",
"ga": "2/4/1",
"dpt": "5.001",
"port": "display",
"flags": { "W": true, "T": false }
},
{
"id": "l1",
"name": "Living room",
"ga": "1/4/1",
"dpt": "1.001",
"port": "display",
"flags": { "W": true, "T": false }
},
{
"id": "l2",
"name": "Corridor",
"ga": "1/4/2",
"dpt": "1.001",
"port": "display",
"flags": { "W": true, "T": false }
}
]
},
{
"id": "p1",
"name": "Three-key push-button · living room",
"address": "1.1.10",
"kind": "pushButton",
"behavior": "pushButton/v1",
"description": "One device has a separate object for each key and function. Key 1 raises the shutter and Key 2 lowers it: long presses use 2/1/1; short presses use 2/2/1. Key 3 toggles the light through 1/1/1 and also listens to status feedback on 1/4/1.",
"objects": [
{
"id": "key1Long",
"name": "Key 1 long press",
"ga": "2/1/1",
"dpt": "1.008",
"port": "input",
"flags": { "W": true, "T": true }
},
{
"id": "key1Short",
"name": "Key 1 short press",
"ga": "2/2/1",
"dpt": "1.007",
"port": "input",
"flags": { "W": true, "T": true }
},
{
"id": "key2Long",
"name": "Key 2 long press",
"ga": "2/1/1",
"dpt": "1.008",
"port": "input",
"flags": { "W": true, "T": true }
},
{
"id": "key2Short",
"name": "Key 2 short press",
"ga": "2/2/1",
"dpt": "1.007",
"port": "input",
"flags": { "W": true, "T": true }
},
{
"id": "key3",
"name": "Key 3",
"ga": ["1/1/1", "1/4/1"],
"dpt": "1.001",
"port": "input",
"flags": { "W": true, "T": true }
}
],
"buttons": [
{
"id": "button-0",
"label": "Key 1",
"icon": "up",
"short": { "object": "key1Short", "value": 0 },
"long": { "object": "key1Long", "value": 0 }
},
{
"id": "button-1",
"label": "Key 2",
"icon": "down",
"short": { "object": "key2Short", "value": 1 },
"long": { "object": "key2Long", "value": 1 }
},
{
"id": "button-2",
"label": "Key 3",
"press": { "object": "key3", "value": "toggle" },
"led": "key3"
}
]
},
{
"id": "c1",
"name": "Switching actuator",
"address": "1.1.20",
"kind": "switchActuator",
"behavior": "switchActuator/v1",
"objects": [
{
"id": "cmd",
"name": "Channel 1",
"ga": "1/1/1",
"dpt": "1.001",
"port": "switch",
"channel": "a",
"flags": { "W": true, "T": false }
},
{
"id": "status",
"name": "Status 1",
"ga": "1/4/1",
"dpt": "1.001",
"port": "status",
"channel": "a",
"flags": { "W": true, "T": true }
}
],
"channels": [{ "id": "a", "label": "Living room", "equipment": { "type": "lamp" } }]
},
{
"id": "p2",
"name": "One-key push-button · entrance",
"address": "1.2.10",
"kind": "pushButton",
"behavior": "pushButton/v1",
"description": "One shutter key: a long press reverses direction through 2/1/1; a short press stops through 2/2/1. Its 2/1/1 object listens to the bus. If device 1.1.10 lowers the shutter, the next long press raises it.",
"objects": [
{
"id": "md",
"name": "Key 1 long press",
"ga": "2/1/1",
"dpt": "1.008",
"port": "input",
"flags": { "W": true, "T": true }
},
{
"id": "st",
"name": "Key 1 short press",
"ga": "2/2/1",
"dpt": "1.007",
"port": "input",
"flags": { "W": true, "T": true }
}
],
"buttons": [
{
"id": "button-0",
"label": "Key 1",
"short": { "object": "st", "value": 0 },
"long": { "object": "md", "value": "toggle" }
}
]
},
{
"id": "p3",
"name": "Push-button · corridor",
"address": "2.1.5",
"kind": "pushButton",
"behavior": "pushButton/v1",
"objects": [
{
"id": "key1",
"name": "Key 1",
"ga": ["1/3/1", "1/4/2"],
"dpt": "1.001",
"port": "input",
"flags": { "W": true, "T": true }
}
],
"buttons": [
{
"id": "button-0",
"label": "Key 1",
"press": { "object": "key1", "value": "toggle" },
"led": "key1"
}
]
},
{
"id": "c2",
"name": "Switching actuator",
"address": "2.1.6",
"kind": "switchActuator",
"behavior": "switchActuator/v1",
"objects": [
{
"id": "cmd",
"name": "Channel 1",
"ga": "1/3/1",
"dpt": "1.001",
"port": "switch",
"channel": "a",
"flags": { "W": true, "T": false }
},
{
"id": "status",
"name": "Status 1",
"ga": "1/4/2",
"dpt": "1.001",
"port": "status",
"channel": "a",
"flags": { "W": true, "T": true }
}
],
"channels": [{ "id": "a", "label": "Corridor", "equipment": { "type": "lamp" } }]
},
{
"id": "shutterActuator",
"name": "Shutter actuator",
"address": "2.1.20",
"kind": "shutterActuator",
"behavior": "shutterActuator/v1",
"downstream": true,
"objects": [
{
"id": "md",
"name": "MD 1",
"ga": "2/1/1",
"dpt": "1.008",
"port": "move",
"channel": "shutter1",
"flags": { "W": true, "T": false }
},
{
"id": "st",
"name": "Stop 1",
"ga": "2/2/1",
"dpt": "1.007",
"port": "stopStep",
"channel": "shutter1",
"flags": { "W": true, "T": false }
},
{
"id": "pos",
"name": "Position 1",
"ga": "2/4/1",
"dpt": "5.001",
"port": "positionStatus",
"channel": "shutter1",
"flags": { "W": true, "T": true }
}
],
"channels": [
{
"id": "shutter1",
"label": "Shutter 1",
"parameters": { "estimatedTravelTimeMs": 12000 },
"equipment": { "type": "shutter", "parameters": { "actualTravelTimeMs": 12000 } }
}
]
}
],
"options": { "speed": 1, "filterTables": false }
}Couplers derive their filter tables from group associations: an address crosses a coupler when needed on the other side. The routing counter starts at 6 and decreases as the telegram passes each coupler.
#Rooms
rooms describes heated rooms, including initial and outside temperatures and window state. Assign a thermostat, window contact, or temperature sensor with its room field; assign a radiator through "equipment": { "type": "radiator", "room": "living" }. See heating.
#Device order and propagation
The order of devices in devices follows their order on the cable. It affects propagation time: adjacent devices are 250 ms apart in the simulation. See time and pacing.
#IDs and references
Each device has a unique id. Each object, button, input, and channel has an id unique within its device. Buttons and inputs refer to objects by ID; objects refer to channels through channel. An unknown reference produces a validation error with its JSON path.
#Group addresses
Group addresses use three levels: main group 0–31, middle group 0–7, and subgroup 0–255. 0/0/0 is the broadcast destination and is refused, as it is in commissioning software.
An object can listen on multiple addresses: "ga": ["1/1/1", "1/4/1"]. The first is its sending address; the rest are receive-only. "ga": [] leaves an object unassociated and is allowed unless a control needs it to transmit.
Objects associated with the same group address must have compatible payload sizes. For example, a one-byte DPT 5.001 object cannot share an address with a one-bit DPT 1.001 object. Objects of the same size but different meaning, such as a scene number (17.001) and a percentage (5.001), are accepted but reported by a configuration warning: the bytes pass unchanged, and each receiver reads them with its own DPT.