Reference
#JSON scenario (format 2)
This reference is generated from the authoring schema at schema/scenario-v2.schema.json. The component additionally validates references between objects, channels, addresses, and behavior ports. See error codes.
#Root
BusDiagram scenario, format 2. Generated by npm run schema.
| Field | Type | Required | Description |
|---|---|---|---|
$schema |
string | Schema path for editor completion; ignored by BusDiagram. | |
formatVersion |
2 |
yes | Format version 2. Without this field, the file is read as legacy format 1. |
title |
string | Title displayed in the toolbar. | |
description |
string | Description displayed below the toolbar. | |
lines |
list of Line | yes | Twisted-pair lines. Multiple lines add line couplers and main lines; multiple areas add a backbone. |
clock |
object | Simulated clock: local date and time at simulation start, and acceleration. Clock masters, time switches, and time windows use it. | |
rooms |
list of Room | Rooms: thermal state shared by assigned thermostats, window contacts, and radiators. | |
topology |
object | Topology levels and coupler settings. Without this field, a main line appears with two lines in an area and a backbone with two areas. | |
ipRouter |
object | Legacy single-router IP network setting; prefer topology.ip. The address must belong to a coupler (A.L.0 or A.0.0). | |
groupAddresses |
list of Group address | Declared group addresses: names and DPTs displayed in the monitor and inherited by associated objects. | |
devices |
list of Device | yes | Devices in cable order on their line; order determines propagation delay. |
options |
object | Initial simulation settings. |
#Line
TP line.
| Field | Type | Required | Description |
|---|---|---|---|
address |
string (validated format) | yes | Line address in area.line form, such as 1.1; values 1–15. Main lines and backbone come from topology. |
name |
string | Name displayed under the bus, for example “Example line”. | |
extension |
object | Line extension: repeater or segment coupler to a downstream segment. | |
powerSupply |
Power supply | Bus power supply of the line, shown on the diagram. |
#Power supply
KNX power supply with choke. Shown on the diagram; the bus load is not computed.
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | Name, such as a product reference. | |
currentMa |
number | Rated current in mA, such as 160, 320, 640, or 1280. |
#Room
Room thermal model: heat loss toward outside temperature plus equipment output; an open window increases loss.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (validated format) | yes | ID referenced by room assignments. |
name |
string | Display name; defaults to the ID. | |
temperatureC |
number | Initial indoor temperature in °C; defaults to 20. | |
outsideTemperatureC |
number | Outside temperature in °C; defaults to 5. | |
windowOpen |
boolean | Window initially open. | |
timeConstantMs |
integer | Thermal loss time constant in simulated milliseconds; defaults to 300,000 ms. |
See the HVAC guide for the thermal model and examples.
#Group address
Declared group address.
| Field | Type | Required | Description |
|---|---|---|---|
address |
string (validated format) | yes | Three-level group address (main/middle/subgroup), such as 1/1/1. |
name |
string | Purpose shown in the monitor and tooltips. | |
dpt |
DPT | DPT inherited by objects that do not declare their own. |
#Device
KNX device with an individual address, objects, buttons, inputs, and channels.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (validated format) | yes | ID unique within the scenario. |
name |
string | Name shown on the device card; defaults to the ID. | |
address |
string (validated format) | Individual address in area.line.device form; its line must be declared. | |
kind |
string | yes | Device grouping and rendering: pushButton, switchActuator, shutterActuator, sensor, supervisor, generic… |
behavior |
"pushButton/v1", "switchActuator/v1", "shutterActuator/v1", "display/v1", "passive/v1", "presenceDetector/v1", "usbInterface/v1", "dimmerActuator/v1", "daliGateway/v1", "roomThermostat/v1", "heatingActuator/v1", "windowContact/v1", "temperatureSensor/v1", "logicGate/v1", "weatherStation/v1", "airQualitySensor/v1", "clockMaster/v1", "timeSwitch/v1", "systemGateway/v1", "energyMeter/v1" or string (validated format) |
yes | Versioned ID of the device's registered behavior. |
parameters |
object | Device parameters defined by its behavior. | |
medium |
"TP", "IP" |
Communication medium: TP by default, or IP on the topology.ip network; supervisors default to IP. | |
room |
string (validated format) | Assigned room ID; thermostats, window contacts, and temperature sensors observe that room. | |
inFilterTables |
boolean | false: do not include this virtual device in coupler filter tables. | |
downstream |
boolean | Device on the downstream segment of a line extension. | |
description |
string | Explanation shown when selecting the device card. | |
objects |
list of Communication object | yes | Communication objects in device-card order. |
buttons |
list of Button | Keys (push button, sensor). | |
inputs |
list of Numeric or digital input | Numeric inputs. | |
channels |
list of Channel | Actuator channels (outputs). |
Behavior-specific parameters appear in the behavior reference.
#Communication object
Communication object of a device.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (validated format) | yes | ID unique within the device; buttons, inputs, and indicators may refer to it. |
name |
string | Name shown on the device card; defaults to the ID. | |
ga |
string (validated format) or list of string (validated format) | yes | Associated group addresses: the first is the sending address; others are receive-only. An empty list leaves the object unassociated. |
dpt |
DPT | Object DPT; defaults to the DPT of its first declared group address. | |
port |
"input", "display", "switch", "status", "move", "stopStep"… |
yes | Object role in the device's behavior. |
channel |
string | Channel ID within the device; required by actuator ports. | |
value |
number or null | Initial value (zero by default; unknown for a display port). | |
flags |
object | yes | Modeled flags: W write, T transmit, R read, U update. C communication is always enabled. |
#Button
Button drawn on the device card; use press or a short/long pair.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (validated format) | yes | ID unique among buttons and inputs on this device. |
label |
string | Label on the button; for example “Key 2 · Down” displays Key 2 prominently. | |
icon |
"on", "off", "toggle", "up", "down", "updown"… |
Icon inferred from the action when omitted. | |
press |
object | Action taken immediately on press; cannot be combined with short/long. | |
short |
object | Action on release before the long-press threshold. | |
long |
object | Action after the long-press threshold (0.5 s by default). | |
release |
object | Action on release after a long press, such as stopping DPT 3.007 dimming. | |
led |
string | Object whose value lights the button indicator. |
A button action (press, short, or long) names an object and gives it a number or "toggle", for example { "object": "key1", "value": 1 }.
#Numeric or digital input
Numeric input drawn on the device card.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (validated format) | yes | ID unique among buttons and inputs on this device. |
type |
"number" |
yes | The only input type is number. |
label |
string | Label displayed above the input. | |
object |
string | yes | Input object with a group address; written and transmitted on submission. |
min |
number | Minimum value; defaults to the DPT minimum. | |
max |
number | Maximum value; defaults to the DPT maximum. | |
step |
number | Input step; defaults to 1. |
#Channel
Actuator output channel; declare hardware channels even when unused.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (validated format) | yes | ID unique within the device and referenced by its communication objects. |
label |
string | Load label, such as L1; use “unused” for an unconnected output. | |
parameters |
object | Behavior-specific channel parameters, such as timer or travel time. | |
initialState |
object | Initial application state of the channel. | |
equipment |
Equipment or null | Connected equipment, or null for a free output without a drawn load. | |
scenes |
object | Scene presets: scene number 1–64 maps to a relay state or shutter position. |
#Equipment
Non-KNX equipment connected to a channel output.
| Field | Type | Required | Description |
|---|---|---|---|
type |
"lamp", "shutter", "dimmableLamp", "daliGroup", "radiator", "fan", "appliance" or string (validated format) |
yes | Equipment type: lamp, shutter, or a registered extension type. |
view |
string | View type; defaults to the equipment type, such as an extension's ledStrip view. | |
room |
string (validated format) | Heated or cooled room ID from rooms; required for a radiator. | |
parameters |
object | Equipment parameters, such as a shutter's actualTravelTimeMs. | |
initialState |
object | Initial physical state, such as a shutter's positionPct. |