Skip to content
GitHub
Specification version v0.1

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 communicates 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 with xknx. Channels come from the ETS group address list, each with a group address and a datapoint type.

Supports

  • Tunneling over UDP or TCP, and routing over multicast.
  • DPT 1.x bools, numeric DPTs such as 5.001, 7.x, 9.x, 13.x and 14.x, enum DPTs such as 20.102 with lower case names like comfort, and DPT 16 strings.
  • DPT units convert to the channel unit.
  • discover() sends a SEARCH_REQUEST, which only requests interface descriptions.

Setup

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

KNX Secure isn't supported yet, so enable a plain tunnel for the hub.

ParameterDefaultMeaning
gatewayrequiredInterface address for tunneling, or the multicast group for routing. knx: 192.168.1.20 is shorthand
port3671KNXnet/IP port
connectiontunnelingtunneling, tunneling_tcp or routing
local_ipautomaticHub address on the KNX network
individual_addressfrom the interfaceHub individual address, needed for routing
route_backfalseTunneling through NAT
timeout2 sRead response deadline

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_addressAddress read or sent to, three-level 1/2/3, two-level 1/2 or free 4660
dptQuoted datapoint type such as "9.001", since YAML reads an unquoted 5.010 as 5.01
state_addressControl channels. Actuator status address for read-back

Behavior

  • Reads return the newest telegram, or send one GroupValueRead when nothing has arrived. An address with the read flag off reads as no value.
  • A command confirms only that the telegram reached the bus, so read the state_address to check the actuator.
  • Values round to the DPT resolution, such as 51 % for 50.4 %.
  • A lost tunnel leaves the device unavailable until the hub reconnects, so nothing goes out late.
  • Bad DPTs and malformed addresses fail at load. Values a DPT can't carry are never sent.

Example

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

Limitations

  • No KNX Secure, device programming or ETS project import.
  • describe() returns nothing, since KNX devices can't list their addresses.
  • One telegram at a time per file, as the bus carries about 50 a second.

Hazard default and safe state

Low. safe_state_support is file. Set each actuator's bus failure behavior in ETS as 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

Specification v0.1