BusDiagram
GitHub Download

Guide

#Couplers and repeaters

Couplers connect the levels of the topology and decide which group telegrams cross them. BusDiagram derives most couplers from the addresses declared in the scenario; line extensions are declared explicitly.

#Types of coupler

Device Address Connects Group telegrams
Line coupler A.L.0 Line A.L and main line A.0 Filtered by its filter table, or routed or blocked as configured.
Area coupler A.0.0 Main line A.0 and the backbone 0.0 Same principle at area level.
KNXnet/IP router A.L.0 or A.0.0 A line or an area and the IP network Replaces a line or area coupler; same filter-table principle.
Line repeater on the line, for example A.L.64 Main segment of a line and a second segment Repeated without filtering.
Segment coupler on the line, for example A.L.64 Main segment of a line and a second segment Filtered: traffic local to one segment does not reach the other.

Line and area couplers appear automatically when the installation has several lines or areas; see topology. KNXnet/IP routers are selected with topology.ip.

#Filter tables and routing counter

A coupler's filter table lists the line-crossing group addresses: those associated with objects on both of its sides. It is derived from the associations declared in the scenario, as ETS does from a project: an address linking a device in line 1.1 and a device in line 15.15 enters the tables of 1.1.0, 1.0.0, 15.0.0, and 15.15.0. The same table applies in both directions. A telegram whose destination is in the table crosses the coupler; the others are filtered.

A device that sends or receives an address without an object in the project, such as a visualisation or a tool connected through a bus interface, is not counted: its telegrams on that address are filtered at the first coupler. Since ETS 6.3, filter tables can no longer be edited by hand; the recommended practice is to model the bus interface and assign it the group addresses it uses, or to add a dummy device with those addresses in its line. In a scenario, list the addresses of a USB interface in its groupAddresses parameter, and set "inFilterTables": false on a supervisor to show one that was not modeled.

Each direction can be set independently in topology.couplers: down for primary to secondary, up for the reverse, each with "filter" (default), "route", or "block":

"topology": {
  "couplers": [{ "address": "1.1.0", "up": "route" }]
}

Every telegram starts with a routing counter of 6. Each coupler, repeater, or router that forwards it decrements the counter; a telegram that arrives with a counter of 0 is not forwarded. The value 7, which disables the counter in some service cases, is not modeled.

In the diagram, Filter tables in the toolbar shows the table of each coupler, and the telegram details list every coupler crossed with its decision and routing counter.

#Line repeaters and segment couplers

A line can be extended by a second segment, connected to its main segment:

"lines": [
  { "address": "2.1", "extension": { "address": "2.1.64", "mode": "repeater" } }
]

A device is placed on the second segment with "downstream": true; the other devices of the line stay on the main segment. Device order within each segment follows the order in devices.

In the designer, each line has a Line extension field (none, line repeater, or segment coupler) and an address field. The form of a device on that line then offers On the segment behind the line extension.

#Rules and model limits

In a twisted-pair installation, up to three line repeaters can extend a line, each connected directly to the main segment. Repeaters are never connected in series, so a line has at most four segments. BusDiagram models one extension per line, always connected to the main segment: repeaters cannot be chained, and a line has at most two segments in a diagram.

Individual-address telegrams, which segment couplers also filter in real installations, are outside the model; see model and limits.

Edit in designer ↗
{
  "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 }
}