Guide

#USB interface panel

The built-in USB interface panel represents a commissioning computer connected to the bus through a USB interface. It sends group-address reads and writes into the same simulated topology as every other device. The panel appears only when the scenario declares an interface.

#Add a USB interface

Place usbInterface/v1 on the desired line. Its address is often at the upper end of the line's address range:

{
  "id": "usbInterface",
  "name": "USB interface",
  "address": "1.1.255",
  "kind": "interface",
  "behavior": "usbInterface/v1",
  "objects": []
}

The designer can add this device through its guided device selector.

#Read and write

The panel uses the group's declared DPT, or a DPT inferred from associated objects. Its telegrams follow the same couplers and filter tables as device telegrams and appear in the bus monitor.

A USB interface has no communication objects, so its addresses are not in the coupler filter tables unless they are assigned to it, as in ETS for a modeled bus interface. List them in the groupAddresses parameter, for example "parameters": { "groupAddresses": "1/1/1 1/4/1" }. Without it, a write to an address used only on another line is filtered by the first coupler, and the response to a read cannot come back. See filter tables.

A read request may use any address associated with the object that should answer; the response is always sent on that object's sending address, its first address. If the sending address is not the one that was read, the response can act on other devices; the KNX training documentation therefore recommends reading on the sending address.

{
  "formatVersion": 2,
  "title": "USB interface panel: write and read a group address",
  "description": "A USB interface (1.1.255) connects a commissioning computer to line 1.1. Write to 1/1/1 in the USB interface panel: the telegram crosses coupler 1.2.0 to reach the actuator. Read 1/4/1: the status object answers because its R flag is set. Read 1/1/1: no object on that sending address has the R flag, so no one answers.",
  "lines": [{ "address": "1.1", "name": "Panel" }, { "address": "1.2", "name": "Floor" }],
  "groupAddresses": [
    { "address": "1/1/1", "name": "Office lighting", "dpt": "1.001" },
    { "address": "1/4/1", "name": "Office lighting status", "dpt": "1.001" }
  ],
  "devices": [
    {
      "id": "usbInterface",
      "name": "USB interface",
      "address": "1.1.255",
      "kind": "interface",
      "behavior": "usbInterface/v1",
      "objects": []
    },
    {
      "id": "pushButton",
      "name": "Push-button",
      "address": "1.1.1",
      "kind": "pushButton",
      "behavior": "pushButton/v1",
      "objects": [
        {
          "id": "key1",
          "name": "Key 1 toggle",
          "ga": ["1/1/1", "1/4/1"],
          "dpt": "1.001",
          "port": "input",
          "flags": { "W": true, "T": true }
        }
      ],
      "buttons": [
        {
          "id": "key1",
          "label": "Key 1",
          "press": { "object": "key1", "value": "toggle" },
          "led": "key1"
        }
      ]
    },
    {
      "id": "switchActuator",
      "name": "Switching actuator",
      "address": "1.2.1",
      "kind": "switchActuator",
      "behavior": "switchActuator/v1",
      "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": false, "T": true }
        }
      ],
      "channels": [{ "id": "s1", "label": "Office", "equipment": { "type": "lamp" } }]
    }
  ],
  "options": { "speed": 1, "filterTables": false }
}

#R and U flags

"flags": { "W": false, "T": true, "R": true }

A command object's U flag is normally off so a read response does not accidentally act as a new command. You can enable U explicitly to inspect that behavior.

To learn the state of an output, read its status address, not its command address. Actuator command objects usually have no R flag, as in product manuals (for example a dimming actuator's switching object is C, W, T, and its switching status object is C, R, T). A read of the command address therefore receives no response from the actuator, and the command object keeps the last command it received even when another command, such as a brightness value, has since changed the output.

#JavaScript API

const diagram = document.querySelector("bus-diagram");
diagram.groupWrite("1/1/1", 1);
diagram.groupRead("1/4/1");

The DOM-free API also exposes groupWrite(interfaceId, groupAddress, value) and groupRead(interfaceId, groupAddress) through createSimulator. Invalid values are rejected before transmission. For example, NaN, infinity, out-of-range values, or a fraction for an integer DPT cause groupWrite to throw RangeError. Accepted values are sent in their encoded DPT form; 30% in DPT 5.001 is represented as about 30.196% after encoding to a byte.