BusDiagram
GitHub Download

Guide

#Push-buttons and actuators

The built-in behaviors cover the examples in this site. See the behavior reference for their parameters. The modeled settings follow common KNX product manuals from ABB, Hager, Schneider Electric, and Theben.

#Push-button: pushButton/v1

Each key can define actions for these gestures:

Action When Typical use
press On activation. Switch, toggle, or recall a scene.
short Released before the long-press threshold. Stop a shutter or turn its slats.
long Held past the threshold. Raise/lower a shutter or start dimming.
release Released after a long press. Stop dimming.

The default long-press threshold is 0.5 s; set "parameters": { "longPressMs": 800 } on a device to change it. press cannot be combined with short or long. A button value can be a number or "toggle": for one-bit objects, toggle inverts the local object value, which may differ from the lamp's actual state. The status feedback example shows why that matters.

Edit in designer ↗
<bus-diagram>
<script type="application/json">
{
  "formatVersion": 2,
  "title": "Toggle controls and status feedback",
  "description": "Key 1 and Key 3 toggle L1; Key 2 toggles L1 through L4. Key 1 listens only to 1/1/1, so it can fall out of sync. Key 3 also listens to status feedback on 1/4/1 and stays synchronized. L1 status feedback also turns on L2.",
  "lines": [{ "address": "1.1", "name": "Example line" }],
  "groupAddresses": [
    { "address": "1/1/1", "name": "L1 lighting", "dpt": "1.001" },
    { "address": "1/1/2", "name": "L1–L4 lighting group", "dpt": "1.001" },
    { "address": "1/4/1", "name": "L1 status feedback", "dpt": "1.001" },
    { "address": "1/4/2", "name": "L2 status feedback", "dpt": "1.001" }
  ],
  "devices": [
    {
      "id": "pushButton",
      "name": "Push-button",
      "address": "1.1.1",
      "kind": "pushButton",
      "behavior": "pushButton/v1",
      "description": "A toggle key sends the inverse of its object value. Without status feedback, that value only reflects the last value sent or received on its own addresses.",
      "objects": [
        {
          "id": "key1",
          "name": "Key 1 toggle",
          "ga": "1/1/1",
          "dpt": "1.001",
          "port": "input",
          "flags": { "W": true, "T": true }
        },
        {
          "id": "key2",
          "name": "Key 2 group",
          "ga": "1/1/2",
          "dpt": "1.001",
          "port": "input",
          "flags": { "W": true, "T": true }
        },
        {
          "id": "key3",
          "name": "Key 3 + status",
          "ga": ["1/1/1", "1/4/1"],
          "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": "button-1",
          "label": "Key 2",
          "press": { "object": "key2", "value": "toggle" },
          "led": "key2"
        },
        {
          "id": "button-2",
          "label": "Key 3",
          "press": { "object": "key3", "value": "toggle" },
          "led": "key3"
        }
      ]
    },
    {
      "id": "switchActuator",
      "name": "Four-output switching actuator",
      "address": "1.1.2",
      "kind": "switchActuator",
      "behavior": "switchActuator/v1",
      "description": "Status objects send the actual output value after each change.",
      "objects": [
        {
          "id": "c1",
          "name": "Channel 1",
          "ga": ["1/1/1", "1/1/2"],
          "dpt": "1.001",
          "port": "switch",
          "channel": "s1",
          "flags": { "W": true, "T": false }
        },
        {
          "id": "e1",
          "name": "Status 1",
          "ga": "1/4/1",
          "dpt": "1.001",
          "port": "status",
          "channel": "s1",
          "flags": { "W": true, "T": true }
        },
        {
          "id": "c2",
          "name": "Channel 2",
          "ga": ["1/1/2", "1/4/1"],
          "dpt": "1.001",
          "port": "switch",
          "channel": "s2",
          "flags": { "W": true, "T": false }
        },
        {
          "id": "e2",
          "name": "Status 2",
          "ga": "1/4/2",
          "dpt": "1.001",
          "port": "status",
          "channel": "s2",
          "flags": { "W": true, "T": true }
        },
        {
          "id": "c3",
          "name": "Channel 3",
          "ga": "1/1/2",
          "dpt": "1.001",
          "port": "switch",
          "channel": "s3",
          "flags": { "W": true, "T": false }
        },
        {
          "id": "c4",
          "name": "Channel 4",
          "ga": "1/1/2",
          "dpt": "1.001",
          "port": "switch",
          "channel": "s4",
          "flags": { "W": true, "T": false }
        }
      ],
      "channels": [
        { "id": "s1", "label": "L1", "equipment": { "type": "lamp" } },
        { "id": "s2", "label": "L2", "equipment": { "type": "lamp" } },
        { "id": "s3", "label": "L3", "equipment": { "type": "lamp" } },
        { "id": "s4", "label": "L4", "equipment": { "type": "lamp" } }
      ]
    }
  ],
  "options": { "speed": 1, "filterTables": false }
}
</script>
</bus-diagram>

led links a button indicator to an object value: the indicator is lit while that value is not zero. Product manuals describe two ways of making the indicator show the actual state of the load, and both can be modeled:

A "toggle" value inverts the object that sends. With a separate status object, the model toggles from the last value sent, not from the status received; use the first form when the toggle must follow the load.

A numeric input can send a setpoint:

"inputs": [{ "id": "position", "type": "number", "label": "Setpoint (%)", "object": "target", "min": 0, "max": 100, "step": 1 }]

Keyboard controls: Tab focuses a key; Enter or Space activates a short press, and Shift+Enter activates a long press.

#Switching actuator: switchActuator/v1

An actuator has one channel per output. Its object ports include switch (command), status (feedback), scene, and forced.

Edit in designer ↗
<bus-diagram monitor="false">
<script type="application/json">
{
  "formatVersion": 2,
  "title": "Timer, clock, and presence detection",
  "description": "The actuator handles the delay: one on telegram is enough, and it switches off locally. Observe status telegrams in the monitor to measure the elapsed time.",
  "lines": [{ "address": "1.1", "name": "Example line" }],
  "groupAddresses": [
    { "address": "1/1/1", "name": "L1 timer", "dpt": "1.001" },
    { "address": "1/1/2", "name": "L2 clock", "dpt": "1.001" },
    { "address": "1/1/3", "name": "L3 presence", "dpt": "1.001" },
    { "address": "1/4/1", "name": "L1 status feedback", "dpt": "1.001" },
    { "address": "1/4/3", "name": "L3 status feedback", "dpt": "1.001" }
  ],
  "devices": [
    {
      "id": "pushButton",
      "name": "Push-button",
      "address": "1.1.1",
      "kind": "pushButton",
      "behavior": "pushButton/v1",
      "objects": [
        {
          "id": "key1",
          "name": "Key 1",
          "ga": "1/1/1",
          "dpt": "1.001",
          "port": "input",
          "flags": { "W": true, "T": true }
        }
      ],
      "buttons": [{ "id": "button-0", "label": "Key 1", "press": { "object": "key1", "value": 1 } }]
    },
    {
      "id": "clk",
      "name": "Weekly clock",
      "address": "1.1.4",
      "kind": "sensor",
      "behavior": "pushButton/v1",
      "description": "The buttons simulate the clock reaching its scheduled times.",
      "objects": [
        {
          "id": "c1",
          "name": "Channel A",
          "ga": "1/1/2",
          "dpt": "1.001",
          "port": "input",
          "flags": { "W": true, "T": true }
        }
      ],
      "buttons": [
        {
          "id": "button-0",
          "label": "8:00",
          "icon": "clock",
          "press": { "object": "c1", "value": 1 }
        },
        {
          "id": "button-1",
          "label": "8:05",
          "icon": "clock",
          "press": { "object": "c1", "value": 0 }
        }
      ]
    },
    {
      "id": "pir",
      "name": "Presence detector",
      "address": "1.1.5",
      "kind": "sensor",
      "behavior": "pushButton/v1",
      "objects": [
        {
          "id": "p",
          "name": "Presence",
          "ga": "1/1/3",
          "dpt": "1.001",
          "port": "input",
          "flags": { "W": true, "T": true }
        }
      ],
      "buttons": [
        {
          "id": "button-0",
          "label": "Passage",
          "icon": "presence",
          "press": { "object": "p", "value": 1 }
        }
      ]
    },
    {
      "id": "switchActuator",
      "name": "Four-output switching actuator",
      "address": "1.1.2",
      "kind": "switchActuator",
      "behavior": "switchActuator/v1",
      "description": "L1 uses a 10-second timer. L3 has a 30-second delay restarted on each detection. L4 is unused.",
      "objects": [
        {
          "id": "c1",
          "name": "Channel 1",
          "ga": "1/1/1",
          "dpt": "1.001",
          "port": "switch",
          "channel": "s1",
          "flags": { "W": true, "T": false }
        },
        {
          "id": "e1",
          "name": "Status 1",
          "ga": "1/4/1",
          "dpt": "1.001",
          "port": "status",
          "channel": "s1",
          "flags": { "W": true, "T": true }
        },
        {
          "id": "c2",
          "name": "Channel 2",
          "ga": "1/1/2",
          "dpt": "1.001",
          "port": "switch",
          "channel": "s2",
          "flags": { "W": true, "T": false }
        },
        {
          "id": "c3",
          "name": "Channel 3",
          "ga": "1/1/3",
          "dpt": "1.001",
          "port": "switch",
          "channel": "s3",
          "flags": { "W": true, "T": false }
        },
        {
          "id": "e3",
          "name": "Status 3",
          "ga": "1/4/3",
          "dpt": "1.001",
          "port": "status",
          "channel": "s3",
          "flags": { "W": true, "T": true }
        },
        {
          "id": "c4",
          "name": "Channel 4",
          "ga": [],
          "dpt": "1.001",
          "port": "switch",
          "channel": "s4",
          "flags": { "W": true, "T": false }
        }
      ],
      "channels": [
        {
          "id": "s1",
          "label": "L1",
          "parameters": { "timerMs": 10000 },
          "equipment": { "type": "lamp" }
        },
        { "id": "s2", "label": "L2", "equipment": { "type": "lamp" } },
        {
          "id": "s3",
          "label": "L3",
          "parameters": { "timerMs": 30000 },
          "equipment": { "type": "lamp" }
        },
        { "id": "s4", "label": "L4", "equipment": { "type": "lamp" } }
      ]
    }
  ],
  "options": { "speed": 1, "filterTables": false }
}
</script>
</bus-diagram>

A six-output actuator remains one KNX device. Declare six channels, using "equipment": null for unused outputs.

#Energy meter: energyMeter/v1

An independent energy meter measures circuits that it does not switch: the supply of a heat pump or a water heater, a group of sockets, or a circuit switched by another actuator. Each channel is a measured circuit, with a power object (DPT 14.056 in W, or 9.024 in kW) and an energy object (DPT 13.010 in Wh, or 13.013 in kWh); a totalPower object without a channel sends the sum.

The measured power of a circuit is given at start by initialState.powerW and changed by a numeric input on its power object, entered in the unit of that object. initialState.energyWh sets the meter index. Energy is integrated with the same time scale as actuator metering (energyTimeScale, 60 by default); power is sent when it changes by powerSendDeltaW, and energy every meterIntervalMs. The meter does not add the power of the circuits it measures to that of actuators: a sub-meter and the actuator that switches the same load report the same power. See the heat pump example.

#Presence detector: presenceDetector/v1

A detection sends 1 through the input object. Each new detection restarts the hold timer ("parameters": { "holdMs": 10000 }); when it expires, the object sends 0. Set retrigger: false to avoid restarting or sendOnEnd: false to suppress the final 0. To model a detector that only sends 1 and relies on the actuator's timer, use pushButton/v1 as in the timer example. The presence object may use DPT 1.001 or 1.018 (occupancy).

A brightness object (DPT 9.004) sends the brightness measured by the detector, entered by the reader on a numeric input. With brightnessThresholdLux, a detection switches on only while that brightness is below the threshold; a presence already active is still extended. There is no light model: the brightness does not depend on the lamps or on daylight, and constant light regulation is not modeled.

#Weather station: weatherStation/v1

A weather station sends outdoor measurements entered in its numeric inputs: wind speed on a wind object (DPT 9.005 in m/s, or 9.028 in km/h; thresholds stay in m/s), brightness on brightness (DPT 9.004, lux), and temperature on outdoorTemp (DPT 9.001). Two one-bit outputs follow thresholds with hysteresis:

Output port Set when Reset when Parameters
windAlarm wind ≥ windThreshold (10 m/s) wind ≤ threshold − windHysteresis (2 m/s) windThreshold, windHysteresis
sunProtection brightness ≥ brightnessThreshold (40,000 lx) brightness ≤ threshold − brightnessHysteresis (5,000 lx) brightnessThreshold, brightnessHysteresis

An output is transmitted only when its state changes. Link windAlarm to the windAlarm port of a shutter actuator.

#Air quality sensor: airQualitySensor/v1

An air quality sensor sends temperature (temperature, DPT 9.001), relative humidity (humidity, DPT 9.007, or 5.001 in one byte as many sensors do), and CO₂ concentration (co2, DPT 9.008) entered in its numeric inputs. It sets co2Alarm and humidityAlarm at their thresholds, with hysteresis, and its step controller sends a ventilation control value (DPT 5.001):

Parameter Default Meaning
step1Ppm, step2Ppm, step3Ppm 800, 1000, 1200 Thresholds between steps 0–1, 1–2, and 2–3.
stepHysteresisPpm 50 A step changes above threshold + hysteresis or below threshold − hysteresis.
step0Pct … step3Pct 0, 33, 66, 100 Control value sent in each step.
minStepTimeMs 0 Minimum time before the next step change.
co2AlarmPpm, humidityAlarmPct 1500, 70 Alarm thresholds.

Connect the ventilation value to a dimming actuator channel driving a fan load. See the air quality example.

#Logic module: logicGate/v1

A logic module combines the one-bit objects on its logicIn port and sends the result on its logicOut object. The operation parameter selects and, or, xor, or not (which uses the first input). An input that has not received a value counts as 0. By default, the result is sent only when it changes (sendOnChangeOnly).

A daily time window restricts the output: with activeFrom and activeTo (HH:MM, the window may cross midnight) and a time object (DPT 10.001) that receives the time from a clock master, the output is 1 only inside the window. The logic module depends on the time received on the bus: without a clock master, the window stays closed. A logic module without inputs simply follows the window.

An optional enable object (DPT 1.003) blocks the output while it is 0; setting it back to 1 sends the current result. The weather protection example uses AND to apply sun protection only in automatic mode.

#Clock master: clockMaster/v1

A clock master sends the time of day on a time object (DPT 10.001: day of week and time) and the date on a date object (DPT 11.001), from the scenario's simulated clock. It sends shortly after start (sendOnStart, startDelayMs), every sendPeriodMin clock minutes aligned on the clock (1 by default; 0 disables periodic sending), and after the clock is set. Give its objects the R flag so that other devices can read the current time.

#Weekly time switch: timeSwitch/v1

A time switch sends programmed values on its output objects (DPT 1.001, 1.002, 1.003, 1.008, 5.001, 5.010, 17.001, or 20.102) at the programmed times of the simulated clock. The program parameter lists switching points separated by semicolons:

"parameters": { "program": "Mon-Fri 07:00 = 1; Mon-Fri 22:00 = 0; Sat,Sun 08:30 = 1; Sat,Sun 23:00 = 0" }

Days are Mon … Sun, ranges such as Mon-Fri, lists such as Sat,Sun, or Daily. Unreadable entries are ignored and listed in the event log. At start and after the clock is set, the time switch sends the value of the most recent switching point (sendOnStart). It uses the simulated clock directly; it does not synchronize from a clock master.

#Display and supervisor: display/v1

A display receives and shows values through its display port without issuing control commands. With "kind": "supervisor", it connects to the IP network by default. Its access and filtering are explained in the topology guide.

#USB interface: usbInterface/v1

This virtual device connects the USB interface panel to a line for group-address reads and writes.

#Passive device: passive/v1

A passive device stores communication-object values without additional behavior. Use it to represent a KNX device whose internal logic is outside the simulation.

A passive or display device may also use a standard DPT that BusDiagram does not simulate, such as 12.001 (counter), 229.001 (metering value), or 235.001 (tariff), to draw a real installation faithfully. Its size comes from the KNX format of the main number, so group address consistency is still checked. Its value stays unknown until a telegram is received and is then shown as raw bytes. Such objects cannot be written from the USB interface panel.

#Gateway to another system: systemGateway/v1

Heat pumps, hot-water tanks, boilers, and floor heating are often controlled by their own system (Modbus, BACnet, M-Bus) and linked to KNX by a gateway. A systemGateway/v1 device represents that boundary; only its KNX side is modeled.

See the boiler room example.