Guide

#Topology and supervision

The model represents twisted-pair lines, couplers, KNXnet/IP routers, and group-address filtering. Filter tables, routing settings, line repeaters, and segment couplers are described in couplers and repeaters.

#Topology levels

Level	Device addresses	Coupler to the next level
Line `A.L`	`A.L.1` through `A.L.255`	Line coupler `A.L.0`
Area main line `A.0`	`A.0.1` through `A.0.255`	Area coupler `A.0.0`
Backbone `0.0`	`0.0.1` through `0.0.255`	—

Declare lines in lines using area and line numbers 1–15. A main line appears when an area has more than one line; a backbone appears when the installation has more than one area. To show either level with a smaller installation, set:

"topology": { "mainLines": true, "backbone": true }

Devices may then connect to a main line (1.0.5) or the backbone (0.0.3). Give areas names with "areas": [{ "address": 1, "name": "Building A" }].

#Power supplies

Each twisted-pair line, and each segment behind a line repeater or segment coupler, needs its own KNX power supply with a choke. powerSupply shows it on the diagram, next to the line name:

"lines": [
  { "address": "1.1", "powerSupply": { "name": "PSU 1.1", "currentMa": 640 },
    "extension": { "address": "1.1.64", "powerSupply": { "currentMa": 320 } } }
]

currentMa is the rated current (common values are 160, 320, 640, and 1280 mA); both fields are optional. The supply has no individual address. BusDiagram does not compute the bus load: the consumption of each device is not modeled. The designer sets the supply of each line in its Topology section.

#KNXnet/IP routers

A KNXnet/IP router replaces a coupler and uses its individual address:

`topology.ip`	Replaces	Router addresses	IP network level
`"areaCouplers"`	Area couplers	`A.0.0`	Backbone
`"lineCouplers"`	Line couplers	`A.L.0`	Main lines and backbone

The model routes through the IP network and applies each router's filter table as it would for a twisted-pair coupler. A device with "medium": "IP", such as a supervisor by default, connects to that network.

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 }
}

For a single-router installation, the legacy "ipRouter": { "address": "1.1.0" } form is also accepted when that address belongs to a coupler.

#What a supervisor sees

An IP supervisor receives the telegrams that couplers route toward the IP network. A supervisor on a twisted-pair line ("medium": "TP") sees traffic on its own line. Coupler filter tables are derived from declared group-address associations. If a supervisor is omitted from those tables, its desired group traffic can be filtered out; "inFilterTables": false reproduces that situation.

A coupler can alternatively route or block all group telegrams in one direction:

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

down controls traffic from the primary to the secondary side; up controls the reverse direction. Each accepts "filter" (default), "route", or "block". Use Filter tables in the diagram toolbar to inspect each coupler.

#Configure topology in the designer

The designer's Topology section edits areas, lines, IP routing, backbone, and main lines without hand-writing JSON. Its coupler panel exposes directional routing and filter tables. A supervisor card controls its medium and filter-table inclusion. See the designer guide.