Skip to content
GitHub

knx

tested on simulator

Tier Tier 3
Protocol KNXnet/IP tunneling, KNXnet/IP tunneling over TCP, KNXnet/IP routing
Covers KNX switch and dimmer actuators, KNX blind actuators, KNX room thermostats, KNX sensors and weather stations, KNX scene and HVAC controllers
Hazard default low
Conformance control
Tested with real xknx tunneling against a fake KNXnet/IP server built from xknx's frame classes, with a simulated room

Estimated reach. Thousands of certified products. KNX is a single standard across hundreds of manufacturers, and every certified device talks in group telegrams with standard datapoint types, which this driver maps from a group address list. KNX Secure devices and device programming are not covered, and the group addresses must come from the installation's ETS project.

The knx driver reads and sets KNX group addresses through a KNXnet/IP interface or router, using xknx. Each channel names a group address and its datapoint type (DPT), so lights, dimmers, blinds, thermostats and sensors from any KNX manufacturer work from a group address list, such as the one ETS exports.

What it supports

  • KNXnet/IP tunneling over UDP or TCP, and KNXnet/IP routing over multicast.
  • Read channels of type bool (DPT 1.x), number (numeric DPTs such as 5.001, 7.x, 9.x, 13.x and 14.x), enum (enum DPTs such as 20.102) and string (DPT 16).
  • Control channels that send a GroupValueWrite, read back from the actuator's status address.
  • Units from the DPT, converted to the channel unit, such as DPT 9.001 in degC to a channel in degF.
  • discover() sends a KNXnet/IP SEARCH_REQUEST, which only requests a description from each interface.

Setup

uv tool install --compile-bytecode "openhal-hub[knx] @ git+https://github.com/sohan-bhat/OpenHAL"

You need a KNXnet/IP interface or router on the network, and the group address list from the ETS project with each address's DPT.

Parameters

ParameterDefaultMeaning
gatewayrequiredThe interface's address for tunneling, or the multicast group for routing. The shorthand knx: 192.168.1.20 sets it
port3671KNXnet/IP port
connectiontunnelingtunneling, tunneling_tcp or routing
local_ipfound automaticallyThe hub's address on the KNX network
individual_addressfrom the interfaceThe hub's own individual address, needed for routing
route_backfalseFor tunneling through NAT
timeout2 sHow long a read waits for a response

KNX Secure isn't supported yet, so a secure interface needs a plain tunnel enabled for the hub.

Channel maps

read:
  temperature: { unit: degC, map: { group_address: 3/1/0, dpt: "9.001" } }
write:
  ceiling_light: { type: bool, map: { group_address: 1/1/0, dpt: "1.001", state_address: 1/1/1 } }
  ceiling_dimmer: { unit: percent, min: 0, max: 100, map: { group_address: 1/1/2, dpt: "5.001", state_address: 1/1/3 } }
KeyMeaning
group_addressThe address the channel reads, or sends to. Three-level (1/2/3), two-level (1/2) or free (4660)
dptThe datapoint type, quoted, such as "9.001". YAML reads an unquoted 5.010 as the number 5.01
state_addressFor control channels, the actuator's status address to read back

Enum channels use the DPT's names in lower case, such as comfort and economy for DPT 20.102.

How reads and commands behave

  • The driver listens to every telegram for its addresses, and a read returns the newest value with the time the value arrived. When nothing has arrived since connecting, the read sends one GroupValueRead and waits timeout. An address whose read flag is off never responds, and reads as no value until a telegram arrives.
  • A command waits for the interface's L_Data.con, which proves that the telegram reached the bus but not that an actuator acted, so read the status address to see whether the actuator acted.
  • Values are rounded to the DPT's resolution. A channel without a status address reads back the value as encoded, such as 51 % for 50.4 %.
  • Because xknx's own reconnect is off, a lost tunnel leaves the device unavailable until the hub reconnects, so nothing goes out late.

Example

openhal/drivers/knx/examples/living-room.hal.yaml switches and dims a ceiling light, sets the heating setpoint and the HVAC mode, and keeps the setpoint low while a window is open.

Errors

  • An interface that refuses the tunnel or can't be reached raises DriverError or TimeoutError.
  • A channel whose DPT doesn't fit its type or unit, an unknown DPT and a malformed group address fail when the device file loads, with DriverError.
  • A command the interface doesn't confirm raises DriverError or TimeoutError naming the group address. A value the DPT can't carry raises DriverError and nothing is sent.

Limitations

  • The driver has no KNX Secure, no device management (programming, individual address changes) and no ETS project import.
  • describe() returns nothing, because KNX devices can't list their group addresses.
  • Because the KNX bus is slow (about 50 telegrams a second), the driver sends one telegram at a time per device file.

Hazard default and safe state

The default hazard is low, because most KNX group addresses switch lights and blinds and set room temperatures. KNX has no emergency command of its own, so safe_state_support is file. The hub sends the device file's safe state like any other telegram, which needs the interface and the bus to be up. Actuators have their own behavior on bus voltage failure and recovery, set in ETS, which is the real fallback.

Sources

OpenHAL is an open protocol, released under Apache 2.0.

OpenHAL is not affiliated with Anthropic or MHS.

Source on GitHub