KNX

Driver: knxnet_ip

The KNX Explorer is the operator surface for a KNX bus reached through a KNX/IP router or IP interface. From one page you write and read individual group addresses by hand, bind group addresses to GEM zones, watch bus traffic frame by frame, and check the health of the tunnel.

Open KNX Explorer

The page lives under Integrations > KNX. For the driver reference — every device and zone attribute, the full DPT encoding table, and the protocol-level limitations — see KNXnet/IP.

Licensing

KNX is a premium integration. Adding a knxnet_ip device — and opening this page — requires the KNX product in your license. Existing devices keep running if a license later changes. See License.

How GEM reaches the bus

GEM connects as a KNXnet/IP tunnelling client: unicast UDP to the router or interface on port 3671, carrying cEMI frames for group reads and writes. It opens one tunnel per device record, keeps it alive with a status request every 60 seconds, and reconnects on its own if the socket drops.

Two consequences are worth knowing before you start:

• Tunnelling only. Multicast routing mode (224.0.23.12) is not implemented, so the target must be a tunnelling-capable IP router or IP interface. A multicast-only line coupler will not work.
• Tunnel slots are finite. Each tunnel is a single-client connection, and most routers offer between four and eight. ETS takes one while it is connected, GEM takes one, and a third-party supervisor takes another. If the router runs out, GEM is refused.

There is no network scan on this page — KNXnet/IP discovery is not implemented, so you enter the router's address on the device record.

Prerequisites

• A KNX/IP router or IP interface on the LAN, already commissioned into the ETS project.
• UDP port 3671 reachable from the GEM server.
• A free tunnelling slot on the router.
• A current ETS project or printed group-address list — you need to know which group address drives which actuator, and what datapoint type each group object expects. GEM cannot ask the bus.
• One knxnet_ip device record. In System > Devices, create a device with the driver set to knxnet_ip, set ip to the router or interface address, and enable it. The port defaults to 3671. The tunnel opens automatically within a few seconds — the device shows as connected in Devices.

Only devices using the knxnet_ip driver appear in this page's gateway picker.

Toolbar

The toolbar runs across the top of every tab.

Control	What it does
KNX/IP Gateway	Selects which knxnet_ip device the page operates on. Everything below it is scoped to that gateway.
Gateway	Read-only display of the selected gateway's address and port. Reads (not set) when the device record has no IP — the tunnel cannot open in that state.
Refresh devices	Re-reads the device list. Use it after adding a KNX device in another tab.

Until a gateway is selected the page shows a short prompt instead of the tabs. If no KNX devices exist at all, that prompt links straight to Devices so you can create one.

Group Address Tool

The first tab talks to a single group address directly, without involving a zone. This is the tab to use when commissioning — prove the address and datapoint type against the actuator before you map anything.

Address takes a group address in three-level notation (1/2/3). It is shared by the Read and Write sections below.

Read

Read sends a group read request. KNX answers asynchronously: nothing comes back to this tab. The response arrives as a separate bus telegram, appears in the Bus Monitor, and reflects onto any zone mapped to that address. A toast confirms the request went out.

Write

Pick a DPT, type a Value, and click Write. The picker offers the datapoint types integrators reach for most often:

DPT	Meaning
1.001	Switch (boolean on/off)
1.002	Boolean
1.009	Open/Close
3.007	Dimming control (0-15)
5.001	Percent (0-100)
5.003	Angle (0-360)
5.010	Counter (0-255)
9.001	Temperature °C
9.005	Wind speed m/s
9.007	Humidity %
9.020	Voltage mV

Values are typed as text and encoded according to the datapoint type — false with 1.001 sends a zero bit, 50 with 5.001 sends 128 (50% of 255). A value the datapoint type cannot represent raises an error instead of being silently coerced to zero, so a typo cannot quietly energize a switch.

Quick actions — On, Off, 25%, 50%, 75%, 100% — write the common switch and percent cases against the current address without going through the picker.

Writes made from this tab are listed under Recently written this session. That table is a convenience only; it lives in the browser and is cleared by a page reload. The Bus Monitor holds the authoritative log.

Map to Zone

The second tab binds a group address to a GEM zone, so the actuator behaves like any other zone in macros, schedules and the UI. One group object maps to one zone.

The form is three numbered steps:

1. Group Address — the address to bind, plus the Datapoint Type and an optional Status GA. The datapoint picker here is deliberately narrower than the Group Address Tool's, offering only the three types that map cleanly onto a zone:

   DPT	What the zone tracks
   1.001	state — on/off
   5.001	level 0-100, and state (on whenever level is above zero)
   9.001	temperature in °C

2. Subsystem — which subsystem the zone belongs to (lighting, shades, climate, and so on).

3. Zone — an existing zone, or + New Zone to create one inline. Creating a zone requires a valid group address first, because the address is the zone's address.

Map to Zone then writes the address onto the zone and stores the datapoint type against it.

Before committing, Test Write sends the value in the adjacent box to the address, and Request Read sends a group read — the same asynchronous behavior as the Group Address Tool, so watch the Bus Monitor for the answer.

Warnings the form raises

• Zone not bound to this gateway. A zone only receives bus telegrams if it resolves to this KNX device — either directly, or through its subsystem. When it doesn't, the form says so and offers a one-click Bind button. You can still map without binding; commands and state simply won't reach the zone until it is bound.
• Address change. If the selected zone already carries a different address, the form states the old and new values before you commit. The address is how the driver routes telegrams, so changing it re-points the zone.

Status addresses

Many commercial actuators publish feedback on a second group address rather than echoing the control address. Put that address in Status GA and the driver reflects telegrams from either address onto the zone. Leave it blank when the actuator publishes back on the control address, which is common on residential gear.

One caveat: a blank Status GA is not written, so it does not clear a status address that was set earlier. To remove one, edit the zone's attributes on the Zones page.

Zones already mapped on the selected gateway are listed under Zones on this Gateway, with their address, datapoint type and status address. Edit or unmap them from the Zones page — the mapping lives on the zone, not on this form.

Mapping a whole project

For more than a handful of group objects, the AI Assistant skill map_knx_group_addresses takes a pasted ETS group-address list and creates the zones in one batch, enforcing address grammar, normalizing spellings, rejecting duplicates and flagging datapoint types that cannot round-trip. See KNXnet/IP for how to drive it.

Bus Monitor

The third tab tails the driver's frame log — the last 50 frames sent and received — and refreshes every two seconds by default.

Column	Contents
Time	Timestamp to the millisecond.
Dir	tx for frames GEM sent, rx for frames it received, meta for connection-level events such as a tunnel recycle.
Kind	The frame type — a group write, a group read, a bus confirmation or notification, a keepalive response, and so on.
GA	The group address the frame concerns.
DPT	The datapoint type, where GEM knows it.
Value	The decoded value, where one applies.
Status / Error	The failure reason on a frame that errored, or the status a keepalive returned.

Newest frames are at the top. Error rows and tunnel recycles are highlighted.

Filters narrow the view by direction, or by group address — the address box matches on a prefix, so 1/2 shows everything in that middle group, and it offers the addresses already present in the log as suggestions.

Auto toggles the two-second refresh. It switches itself off and raises the reason when the gateway answers with an error, so a device that has gone away doesn't leave the page polling it every two seconds — click it back on once the tunnel recovers.

Clear empties the log and resets the watchdog counters shown on the Diagnostics tab. It asks first. Clearing before you deliberately exercise a flaky bus gives a clean baseline; clearing casually throws away the failure history you may be about to need.

The log is a fixed-size ring in the driver's memory. It holds the most recent 50 frames, is not written to the database, and starts empty after a restart or a driver reload.

Diagnostics

The fourth tab reports the health of the tunnel. Unlike the Bus Monitor it does not auto-refresh by default — turn Auto-refresh on for a five-second cadence, or refresh by hand.

Health is a row of cards:

Card	Meaning
Tunnel	Up or Down — whether a tunnelling channel is currently open.
Consecutive failures	Failed operations since the last success, against the configured threshold. Highlights at three.
Tunnel recycles	How many times the driver has torn down and rebuilt the tunnel since counters were last reset. Any value above zero is highlighted — a healthy gateway sits at zero.
Last successful op	How long ago a frame was last sent or received successfully.
Heartbeats pending	Keepalives sent without an answer. Highlights at two.
Comm log entries	How many frames are currently in the ring buffer.

When the driver has recorded a client-level error, its message and age appear below the cards.

Tunnel lists the gateway address and port, the channel ID the router assigned, the keepalive interval, and the two watchdog settings.

How the watchdog decides to recycle

Two independent mechanisms can rebuild the tunnel:

• The watchdog recycles only when consecutive failures cross the threshold and no operation has succeeded within the staleness window. Both gates must be satisfied, which is what keeps ordinary bus jitter from dropping a working tunnel.
• The keepalive recycles after three keepalives the router answered with an error, or four the router never answered at all.

Both thresholds are tunable per device — see the driver reference for the attributes.

Settings

The last tab is a read-only summary of the selected gateway: device ID and name, address and port, keepalive interval, connect timeout, and the watchdog threshold and staleness window, each shown in milliseconds and in seconds.

Nothing is editable here. The device name and the link below the table both go to the device's row on the Devices page, which is where connection settings change — and a change takes effect on the next driver reload, not immediately.

Group address notation

GEM parses three-level group addresses only: main/middle/sub, where main is 0-31, middle is 0-7, and sub is 0-255. Two-level and freeform notations are not parsed — convert them in ETS or by hand.

Address boxes on this page do a shape check, not a range check, so an out-of-range address like 45/2/3 can pass the field validation and still come back from the gateway as an invalid group address. If a write is refused the moment you send it, check the bounds above before suspecting the bus.

Leading zeros are worth avoiding. Inbound telegrams are matched numerically, so a zone stored as 01/02/03 still tracks state — but the outbound command path keys on the address exactly as written, which makes two spellings of one address behave like two half-working zones. Store 1/2/3.

Troubleshooting

The device never connects

1. Confirm the device record has an ip and is enabled — the toolbar shows (not set) when it doesn't.
2. Confirm UDP 3671 is reachable from the GEM host, unicast rather than multicast. A firewall or a VLAN boundary is the usual cause.
3. Confirm the router's tunnelling port really is 3671 — some routers are commissioned onto another port in their ETS settings.
4. Confirm a tunnel slot is free. If ETS and another supervisor are both connected, the router can refuse GEM outright.

Commands go out but nothing happens

The datapoint type almost certainly doesn't match what the group object expects. GEM cannot ask the bus what a group object is — it trusts what you configured. A percent write to a one-bit switch is malformed, and a one-bit write to a percent object reads as zero. Check the object in ETS and correct the zone's datapoint type.

Also confirm you are writing the right object: ETS usually exposes switching and brightness as two separate group addresses. A zone mapped to the brightness object will not respond to on and off, because those send a one-bit switch telegram to the brightness address. The driver reference covers wiring both onto one zone.

No state ever arrives

1. Confirm the actuator is configured in ETS to send status telegrams. Some default to sending nothing.
2. Confirm the Status GA matches, if the actuator publishes feedback on a separate address.
3. Confirm the zone resolves to this gateway — the Map to Zone tab warns when it doesn't, and an unbound zone never sees a telegram.
4. Watch the Bus Monitor while operating the actuator from a wall switch. If the telegram appears there but the zone doesn't move, the mapping is wrong; if nothing appears at all, the actuator isn't sending.

State is right but nothing updates after a reconnect

Every reconnect drops the tunnel, and GEM only learns a value when the bus reports one. After a recycle a zone keeps its last known state until the next telegram for that address. Use Request Read on the Map to Zone tab, or the Group Address Tool's Read, to prompt an update.

Heartbeat warnings every minute

The router is refusing the keepalive, which usually means the tunnel was force-closed by ETS or another tool while GEM was idle. The driver rebuilds the tunnel after three refused keepalives or four unanswered ones; a recycle appearing in the Bus Monitor as a highlighted row is the confirmation.

Related documentation

• KNXnet/IP — driver reference: device and zone attributes, the full DPT encoding table, commands, and known limitations.
• Devices — creating and enabling the knxnet_ip device record.
• Zones — editing a zone's address and attributes after mapping.
• AI Assistant — the map_knx_group_addresses skill for bulk mapping.