KNXnet/IP

Commercial building-automation driver for the KNX bus, integrated via an IP router or IP interface using the KNXnet/IP Tunnelling protocol (KNX standard volume 3, chapters 03_08_02 and 03_08_04). This is the same protocol that Gira, Jung, ABB i-bus, Siemens GAMMA, Schneider KNX, MDT, and Zennio interfaces expose on the LAN side, and the same protocol ETS uses to talk to the bus.

A live explorer is available at /admin/knx — once a knxnet_ip device is configured, the explorer exposes a Group Address read/write tool, a Bus Monitor that streams the comm log, and a Diagnostics tab that surfaces watchdog state.

KNX is dominant in European commercial buildings and increasingly common in high-end residential. Touching it is the difference between "we can quote that project" and "we can't."

Prerequisites

• A KNX/IP router (e.g., MDT SCN-IP000.03 / SCN-IP100.03, Gira IP Router 2167-00, Weinzierl KNX IP Router 752, Siemens N146/02, ABB IPR/S 3.5.1) or a KNX/IP interface (Weinzierl 731, MDT SCN-IP110.03, ABB IPS/S 3.1.1, Gira 2169-00) on the LAN, already commissioned into the project.
• UDP port 3671 reachable on the LAN — most routers default to this.
• A current ETS project file (or printed group-address list) so you know which group addresses correspond to which lights / shades / HVAC actuators, and what DPT each one expects.
• A free tunneling slot on the router. Most modern routers expose 4-8 simultaneous tunnels; ETS will use one, GEM will use one, leave at least one free for diagnostics.

Setup

1. Add the device. In /admin/devices, create a new device of driver type knxnet_ip and set:
   • ip — the KNX/IP router or interface IP
   • port — 3671 (default)
2. Confirm the tunnel opens. Within ~5 seconds the device should show connected in /admin/devices. If it doesn't, see Troubleshooting below.
3. Per addressable KNX object, create a GEM zone. Set:
   • address — the KNX group address in 3-level notation (e.g., 1/2/3)
   • dpt — the datapoint type that group object expects. The driver currently ships encoders/decoders for:
     • 1.001 — 1-bit boolean (switch). on/off.
     • 5.001 — 8-bit percent (dimmer position, blind position). 0-100.
     • 9.001 — 2-byte float (°C temperature). Read-only in v1 — the driver decodes inbound but does not currently send setpoints in this DPT.
   • status_address — (optional) second group address the actuator publishes feedback on. Leave blank if the actuator publishes state back on the same group address as the control input (this is common on residential gear; commercial gear tends to use separate status groups).
4. Send commands. From macros, the script console, or the UI:
   • command({device: id, zone: zoneId, action: 'on'}) → 1-bit GroupValue_Write of 1 to the zone's group address.
   • command({device: id, zone: zoneId, action: 'off'}) → 1-bit GroupValue_Write of 0.
   • command({device: id, zone: zoneId, action: 'set_level', args: {level: 60}}) → 8-bit GroupValue_Write of 60% (scaled to 0-255 on the wire).
   • For anything off the zone surface, use set_value directly: {action: 'set_value', args: {group: '4/5/6', value: 1, dpt: '1.001'}}.

Attribute reference

Device

Attribute	Required	Default	Description
ip	yes	—	KNX/IP router or interface IP
port	no	3671	UDP port
heartbeat_interval	no	60000	CONNECTIONSTATE_REQUEST cadence in ms
connect_timeout	no	10000	If no CONNECT_RESPONSE within this many ms, recycle the socket
op_failure_threshold	no	5	Consecutive op failures before the watchdog considers recycling the tunnel. Both this gate AND the staleness gate must clear before a recycle.
op_staleness_ms	no	120000	How long without a successful frame send/receive before the threshold can trigger a recycle.

Zone

Attribute	Required	Default	Description
address	yes	—	KNX group address, 3-level (e.g., 1/2/3)
dpt	yes	1.001	Datapoint type — see Supported DPTs below
status_address	no	—	Optional second group address for state feedback

The driver maintains state (on/off), level (0-100 for percent DPTs), and temperature (°C for float DPTs) on each GEM zone as it sees notifications arrive on the bus.

Zone address format

3-level KNX group address — main/middle/sub where main is 0-31 (5 bits), middle is 0-7 (3 bits), and sub is 0-255 (8 bits). Examples:

0/0/1     1/2/3     5/7/255

2-level (main/sub) and freeform 16-bit notations are not parsed in v1; convert in ETS or by hand before pasting.

Supported DPTs (v1)

DPT	Description	GEM mapping
1.001	1-bit switch (on/off)	state attribute (on / off)
5.001	8-bit percent (0-100%)	level attribute (0-100), state reflected from level > 0
9.001	2-byte float, temperature °C	temperature attribute, read-only

The DPT registry is large (KNX defines hundreds). v1 covers the three that show up on virtually every project: switching, dimming/position, and temperature feedback. Additional DPTs (3.x dimming control, 7/8 unsigned/signed ints, 10 time, 11 date, 14 IEEE float, 16 string) are straightforward extensions of encodeDpt / decodeDpt in the driver and have not been wired in this release.

Known limitations

• Tunneling only — no routing mode. Multicast routing on 224.0.23.12 is not implemented. Use a tunneling-capable IP router or IP interface.
• One tunnel per device row. Modern routers allow several concurrent tunnels; if you need GEM, ETS, and a Gira HomeServer connected simultaneously, just verify the router has enough tunnel slots and that GEM is consuming exactly one.
• DPT trust. The driver does not negotiate DPTs with the bus; it trusts the zone.dpt attribute. Setting dpt=5.001 on a group object that is actually a 1.001 switch will write a malformed payload (8 bits to a 1-bit listener) and confuse the actuator. Match dpt to whatever ETS shows for that group object.
• Sequence dedupe. The driver acks every inbound TUNNELING_REQUEST as required by the spec but does not currently dedupe on the receive sequence counter; on a very flaky network you could in theory see a duplicated state notification.
• No discovery (yet). SEARCH_REQUEST on multicast 224.0.23.12 is not implemented. Enter the router IP directly.
• No ETS project import. Group address inventory is manual — paste each group address into a GEM zone. A future enhancement could parse an ETS export.

Troubleshooting

Symptom	Check
CONNECT_REQUEST sent logs but no tunnel open	UDP 3671 is being firewalled, OR the router is on a different VLAN with no IGMP forwarding. From the GEM host, nc -uv <router_ip> 3671 and watch for response.
Tunnel opens, connected=true, but commands have no effect	The zone.dpt doesn't match the actuator's DPT. Open ETS, check the group object's DPT, set zone.dpt accordingly.
Refused with status E_NO_MORE_CONNECTIONS (0x24)	All tunneling slots on the router are taken. Close another supervisor (ETS, Gira HomeServer, another integrator app), or reboot the router.
State notifications never arrive	Confirm the actuator is configured in ETS to send state-update telegrams on writes. Many actuators default to "send on change only" but some have it disabled. Also confirm status_address matches if it differs from the control address.
Heartbeat warnings every minute	The router refused the CONNECTIONSTATE_REQUEST. Usually means the tunnel was force-closed by ETS or another tool while GEM was idle. The driver will recycle the socket after 3-4 missed heartbeats.
Float temperatures look 100× off	DPT 9.001 has a quirky mantissa/exponent encoding. The driver scales mantissa × 0.01 × 2^exp. If your °C readings look off by 10× or 100× the actuator may be sending a non-standard variant — log the raw bytes and confirm against the actuator datasheet.

KNX Explorer (/admin/knx)

Live operator surface for the configured knxnet_ip gateway. Four tabs:

• Group Address Tool — read or write a single group address by hand. The driver coerces stringified values per the chosen DPT, so 'false' on DPT 1.001 sends bit 0 (not bit 1) — typos never silently energize a switch. Quick-action buttons (On / Off / 25-100%) cover the common DPT 1.001 + 5.001 cases.
• Bus Monitor — tails the driver's comm log (last 50 frames) with filters for direction (tx / rx / meta) and group address. Recycle and error rows render highlighted. Auto-refreshes every 2 s.
• Diagnostics — tunnel state, heartbeat-pending count, channel ID, watchdog counters (consecutive failures, recycles, last successful op, last client error). The watchdog recycles the tunnel when consecutive op failures cross the threshold AND no successful op has happened in the staleness window; the keepalive also recycles after 3 status-errors or 4 unacked heartbeats.
• Settings — read-only summary of the gateway's current connection attributes (IP, port, heartbeat interval, connect timeout, watchdog threshold/staleness). Edits happen on the Devices page and require a driver reload to take effect.