KNXnet/IP Driver
Overview
KNXnet/IP — tunnels the KNX bus, standardized in building automation (lighting / shading / HVAC), over IP. Native rewrite in 2026-07 — the old delegation to Apache PLC4j knxnet-ip has been removed (migrated in 2026-07 P2). It now uses the in-house implementation in plantpulse-plc-protocol (KnxNetIpClient UDP 3671 tunneling + KnxGroupAddress + KnxDpt).
| Item | Value |
|---|---|
opc_type | KNXNET |
| Implementation class | plantpulse.driver.protocol.knxnet.KNXnetDriver |
| Library | In-house native (knx in plantpulse-plc-protocol — UDP tunneling) |
| Inheritance | BaseProtocolDriver (not PLC4j) |
getProtocol() | "knxnet-ip" (old PLC4X scheme notation retained — log/diagnostic compatibility) |
| Default port | 3671 (UDP) |
| Status | Stable (TUNNELING) |
| read | OK (GroupValueRead) |
| write | OK (GroupValueWrite — DPT suffix required) |
| Security | None (KNX Secure not supported) |
The native client supports TUNNELING (unicast) only. Multicast ROUTING is not supported — if connection-type=routing is specified, a warning is logged and the connection proceeds with tunneling.
Class Structure
BaseProtocolDriver
└── KNXnetDriver — connect() 에서 KnxNetIpClient(host, port) tunneling 세션 수립
Wire sequence: CONNECT_REQUEST(0x0205) → RESPONSE(channelId) → TUNNELING_REQUEST(cEMI L_Data.req GroupValueRead) → ACK → L_Data.ind GroupValueResponse from the gateway (+ACK reply) → CONNECTIONSTATE heartbeat (30s) → DISCONNECT. If a read communication fails, the socket is invalidated (connected=false) so that the Edge is prompted to reconnect.
OPC Registration Options
| Field | Meaning | Default |
|---|---|---|
opc_agent_ip | KNX/IP gateway IP | 192.168.1.10 |
opc_agent_port | UDP port | 3671 (normally fixed) |
options.request-timeout | Response timeout (ms) | 2000 (same as the old PLC4X default) |
options.connection-type | tunneling only | tunneling |
Tag plc_address Format (existing contract preserved)
<main>/<middle>/<sub>[:<DPT>] 예) 1/0/5:DPT_Switch / 3/2/0:9.001 / 1/2/10
<main>/<sub>[:<DPT>] 2-level (main 0-31 / sub 0-2047)
The DPT suffix accepts either PLC4X names (DPT_Switch / DPT_Scaling / DPT_Value_Temp / DPT_Value_Length …) or numeric forms (1.001 / 5.001 / 9.001 / 14.056 …).
| Notation | Meaning |
|---|---|
1/0/5:DPT_Switch | 1-bit boolean (DPT 1.001) |
2/1/3:DPT_Scaling | 0..100 % (DPT 5.001) |
3/2/0:DPT_Value_Temp | 2-byte float (DPT 9.001) |
3/2/0:9.001 | Same (numeric DPT) |
1/2/10 | DPT omitted — interpreted as length-based unsigned (RAW) |
Supported decodes: DPT1 bool / 5.001 %scale / 5.x u8 / 7.x u16 / 9.x 2-byte float / 12·13.x u32 / 14.x float32 / 16.x string. When the DPT is omitted, the value is interpreted as length-based unsigned (RAW) — if exact values are required, specify the DPT according to the ETS project.
Support / Not Supported
- read: GroupValueRead → GroupValueResponse — OK.
- write: GroupValueWrite — OK. DPT suffix required — encoding is not possible with RAW, and the DPT determines the encoding (independent of
data_type). - ROUTING (multicast, 224.0.23.12): not supported (TUNNELING only).
- KNX Secure (IP / Data): not supported.
- Automatic mapping via ETS project (
.knxproj) import: not supported — enter the Group Address directly. (Theknxproj-file-path/knxproj-password/group-address-num-levelsoptions in the old form are ignored in the native implementation — removed.) - Direct KNX TP/PL/RF connection: not supported — an IP gateway is assumed.
References
- KNX Standard ISO/IEC 14543-3.
- Code:
plantpulse-edge-driver/src/plantpulse/driver/protocol/knxnet/KNXnetDriver.java+ theknxpackage inplantpulse-plc-protocol. - Operations: watch out for the limited number of tunneling slots on the gateway (Gira / ABB / Siemens N146) — 1 to 5 concurrent connections is typical.