KNX IoT Router

A KNX IoT Router exchanges group communication messages between a KNX IoT subsystem and a KNX Classic subsystem. The KNX IoT Router maintains a Group Address representation for both sides. It translates messages between the CBOR encoding of the Point API and the frame format of the KNX Classic medium.

On the KNX IoT side, the KNX IoT Router always communicates with CoAP over IPv6. On the KNX Classic side, the KNX IoT Router connects through KNXnet/IP or TP (Twisted-pair). A KNX IoT Router is a normal Point API device. The MaC configures the KNX Classic integration entirely over the Point API. The KNX IoT Router therefore needs no KNX Classic management interface.

Commissioning Context

The router follows the standard Point API commissioning sequence. See Device Bootstrapping for the full sequence, Device Function Point Tables for the group communication tables, and Device Access Control for access token provisioning.

Specification Status

The KNX IoT Router Coupler profile is currently in voting. The Coupler profile parts of this page can still change before the standard reaches approval.

Overview

Aspect	KNXnet/IP medium	TP medium
KNX IoT side	CoAP over IPv6	CoAP over IPv6
KNX Classic side	KNXnet/IP routing on an IP Backbone	Twisted-pair line or Backbone
Device Descriptor Type 0	`0x6900`	`0x6901`
Medium-specific resources	`/f/netip` and `/p/netip`	None. The TP link layer has no configurable settings.
Discovery on the Classic side	`SEARCH_REQUEST` and `SEARCH_REQUEST_EXTENDED`	Device Descriptor read

The specification defines two KNX IoT Router profiles: KNXnet/IP and Coupler. A device complies with exactly one profile. A KNX IoT Router of the Coupler profile sits beneath a TP system, forwards group telegrams, and offers no commissioning access from the KNX Classic side.

System Design

Coupler Profile

The Coupler profile derives its role from the fields of its own Individual Address.

Role	Individual Address	Addresses represented
Backbone Coupler	`x.0.0`	All addresses `x..`
Line Coupler	`x.y.0` (y = 1-15)	All addresses `x.y.*`
Segment Coupler	`x.y.z` (z = 1-255)	Own address plus the entries of `/p/coupling/segment-iatbl`

The Coupler profile is possible in a Line, a Main Line, and a Backbone Line. These devices take Individual Addresses from the address space of that Subnetwork, interleaved with the Classic devices of the same Subnetwork.

Topology Rules

The primary side of the KNX IoT Router is KNXnet/IP or TP, and the secondary side is KNX IoT. For an installation that contains both subsystems, the following rules apply:

KNXnet/IP or TP is the Backbone medium.
KNX IoT does not serve as the Backbone medium.
A KNX IoT area does not contain lines or segments of another medium.
A KNX IoT line does not contain segments of another medium.

A KNX IoT Router and a KNXnet/IP Router remain typically separate entities with separate Individual Addresses and separate database entries. For the system view of these topologies, see Horizontal Interworking and Vertical Integration.

Device Configuration Procedure

The MaC writes the KNX IoT Router resources after device individualization. The following resources apply to every KNX IoT Router, independent of the KNX Classic medium:

/fp/gm, the Group Address Mapping Table.
/f/datasec and /p/datasec, the KNX Data Security resources.
/p/coupling/segment-iatbl, in the Segment Coupler role only.

On a KNX IoT Router whose KNX Classic medium is KNXnet/IP, the MaC also writes /f/netip and /p/netip. A KNX IoT Router whose KNX Classic medium is TP needs no medium-specific resources. The KNX TP standard defines the link-layer behaviour, such as the timing and the retry counts. Every TP device therefore uses the same values, and the MaC configures nothing for that medium.

Group Address Mapping Table (`/fp/gm`)

The Group Address Mapping Table holds the information that the router needs to map Group Addresses between the Point API and KNX Classic. Each item carries a 1:1 Group Address mapping for the range 0 to 65535 and the datapoint type that drives the message translation.

Support column legend: [m] = mandatory, [o] = optional, [c] = conditional

Resource path	Format	Method	Support	Description
`/fp/gm`	CBOR	POST	[m]	Write or update mapping items. An item that contains only `id` deletes the matching entry.
`/fp/gm`	link-format	GET	[m]	Read the mapping item list.
`/fp/gm/{group-map-id}`	CBOR	GET, DELETE	[m]	Read or delete a single mapping item.
`/fp/gma`	link-format	GET	[m]	Read the mapping item list.
`/fp/gma/{group-map-id}`	CBOR	GET	[m]	Read a single mapping item without the `groupKey` material.

The /fp/gma variant returns the same content as /fp/gm but omits the secret key material. A diagnostic client can therefore read the mapping without access to the KNX Classic group key.

Mapping Item CBOR Keys

CBOR Key	Name	Type	M/O	Description
0	`id`	unsigned	[m]	Identifier of the mapping item.
7	`ga`	unsigned array	[m]	Group Address array. The table supports at least 20 array elements and accepts an empty array.
116	`dataType`	unsigned	[m]	Datapoint type main number used for the conversion.
115	`s`	map	[c]	KNX Classic security object. Required for a Group Address secured by KNX Data Security.
28	`secSettings`	map	[c]	KNX Classic security flags inside `s`.
97	`a`	boolean	[c]	Apply authentication for KNX Classic secure group communication.
99	`c`	boolean	[c]	Apply confidentiality for KNX Classic secure group communication.
107	`groupKey`	byte string	[c]	KNX Classic shared group key. The key size is 16 bytes.

The MaC writes the security fields only for a Group Address that KNX Data Security protects. The MaC can write the same group key on the KNX Classic side that it configures for the group in the Point API.

Mapping Table Example

The access token that authorises the write has the if.sec scope.

# POST to /fp/gm — one unsecured and one secured Group Address mapping
[
  {0: 0,
   7: [2305],
   116: 1},
  {0: 1,
   7: [11009],
   116: 1,
   115: {28: {97: True, 99: True},
         107: h'000102030405060708090a0b0c0d0e0f'}}
]

A read of a secured item through /fp/gma returns the security flags without the group key:

# GET /fp/gma/1 — response payload
{0: 1, 7: [11009], 116: 1, 115: {28: {97: True, 99: True}}}

A POST that carries only the id of an item deletes that item, and a DELETE on /fp/gm/{group-map-id} removes a single entry.

KNXnet/IP Resources (`/f/netip` and `/p/netip`)

The KNXnet/IP functional block is mandatory for a router whose KNX Classic medium is KNXnet/IP and absent on a KNX IoT R outer whose medium is TP. The /p/netip/key resource requires the if.sec access rights, whereas the other properties typically need the if.p access rights.

Resource path	Datapoint type	Method	Support	Description
`/f/netip`	`:fb.11`	GET	[m]	Read the property list of the functional block.
`/p/netip/mcast`	`:dpt.IPv4`	GET, PUT	[m]	IPv4 routing multicast address.
`/p/netip/ttl`	`:dpt.value1Ucount`	GET, PUT	[m]	Number of routers that a multicast message can pass before a router discards it.
`/p/netip/key`	`:dpt.varOctet`	PUT	[m]	IPv4 routing Backbone key. The key size is 16 bytes.
`/p/netip/tol`	`:dpt.timePeriodMsec`	GET, PUT	[m]	IPv4 routing latency tolerance.
`/p/netip/fra`	`:dpt.scaling`	GET, PUT	[m]	IPv4 sync latency fraction.
`/p/netip/ipassignmentmethod`	`:dpa.11.55`	GET, (PUT)	[m]	Address assignment method. Manual (1) and DHCP (4) are mandatory. BootP (2) and AutoIP (8) are optional.
`/p/netip/ipaddress`	`:dpt.ipv4`	GET, (PUT)	[m]	Configured IPv4 address of the KNXnet/IP port.
`/p/netip/subnetmask`	`:dpt.ipv4`	GET, (PUT)	[m]	Configured IPv4 subnet mask.
`/p/netip/defaultgateway`	`:dpt.ipv4`	GET, (PUT)	[m]	Configured IPv4 default gateway.
`/p/netip/currentipassignmentmethod`	`:dpa.11.54`	GET	[m]	Assignment method currently in use.
`/p/netip/currentipaddress`	`:dpt.ipv4`	GET	[m]	IPv4 address currently in use.
`/p/netip/currentsubnetmask`	`:dpt.ipv4`	GET	[m]	Subnet mask currently in use.
`/p/netip/currentdefaultgateway`	`:dpt.ipv4`	GET	[m]	Default gateway currently in use.

Multicast Address Example

# PUT to /p/netip/mcast — IPv4 routing multicast address 224.0.23.12
{1: 0xE000170D}

KNX Data Secure Resources (`/f/datasec` and `/p/datasec`)

The KNX Data Security functional block is mandatory on every router. It holds the sequence number state that KNX Data Security needs on the KNX Classic side.

Resource path	Datapoint type	Method	Support	Description
`/f/datasec`	`:fb.17`	GET	[m]	Read the property list of the functional block.
`/p/datasec/iatbl`	`:dpa.17.54`	GET, PUT	[m]	Security Individual Address Table.
`/p/datasec/seq`	`:dpa.17.59`	GET, PUT	[m]	Sequence number for sending.

KNX Data Secure Individual Address Table CBOR Keys

CBOR Key	Name	Type	M/O	Description
0	`id`	unsigned	[m]	Identifier of the table item.
4	`sia`	unsigned	[m]	Individual Address that the item describes.
110	`seqCntr`	unsigned	[m]	Last valid sequence number received from that device.

KNX Data Secure Table Example

# PUT to /p/datasec/iatbl — one entry for Individual Address 0.0.64
[{0: 1, 4: 64, 110: 0}]

Coupler Profile Resources (`/f/coupling` and `/p/coupling`)

The KNX IoT Router Coupler profile functional block is medium-independent and applies to the KNX Classic media. It configures the Individual Addresses that a Coupler Profile represents on its segment.

Resource path	Datapoint type	Method	Support	Description
`/f/coupling`	`:fb.6`	GET	[o]	Read the property list of the functional block.
`/p/coupling/segment-iatbl`	`:dpa.6.68`	GET, PUT	[o]	Segment Individual Address Table.

A KNX IoT Router that does not support the Coupler profile does not expose /f/coupling or /p/coupling/segment-iatbl. Absence of the resource means that the device does not support the profile. A KNX IoT Router that supports the profile exposes both resources.

Each entry holds the low order octet of one Individual Address of the segment, because every address lies in the Subnetwork of the KNX IoT Router itself. The table supports 254 entries, which covers the range x.y.1 to x.y.255 minus the address of the router. The KNX IoT Router defends its own Individual Address implicitly, so the table excludes that address. The device accepts an entry for its own address, ignores it, and does not include it in the capacity count.

Segment Coupler Table Example

# PUT to /p/coupling/segment-iatbl — represent x.y.3, x.y.4, x.y.7 and x.y.8
[3, 4, 7, 8]

Load State and Configuration Fingerprint

The router evaluates the router-specific tables only when the Load State Machine reaches the loaded state. In any other state, the device ignores /fp/gm, /f/datasec, and /p/coupling/segment-iatbl.

The configuration fingerprint under /.well-known/knx/f covers the standard Point API resources plus /fp/gm, /f/datasec without the sequence counters, and /p/coupling/segment-iatbl.

Runtime Interworking

Discovery

The KNX IoT Router supports the Point API discovery mechanisms and advertises AAAA records for every IPv6 address that it accepts for commissioning or runtime communication. On the KNX Classic side, the discovery depends on the medium:

KNXnet/IP: the router answers SEARCH_REQUEST and SEARCH_REQUEST_EXTENDED. The response carries the Device Information DIB and the Supported Service Families DIB. The extended response adds the Secured Service Families DIB and the Extended Device Information DIB. The KNX Medium field returns 0x06 and the Device Descriptor Type 0 returns 0x6900.
TP: the router answers the Device Descriptor read that targets its Individual Address without a transport connection. The Device Descriptor Type 0 returns 0x6901.

Message Routing

The KNX IoT Router acts as a Message Broker between the two subsystems. It decrypts and encrypts secured messages on both sides, translates the payload, and forwards the message to the configured destination Group Address. The KNX IoT Router supports subscription entries in the Publisher Table. An integrator can therefore configure the KNX IoT Router with Endpoint Subscription Message Exchange. For the message exchange patterns, see Group Communication.

The following steps describe a group event message that arrives from KNX Classic:

Receive the message and, for the KNXnet/IP medium, check KNX IP Secure.
Verify that the Load State Machine is in the loaded state.
Look up the Group Address in /fp/gm and ignore the message without a match.
Check KNX Data Security. Accept a plain message only when the item configures no security, and decrypt the message when the item configures security.
Convert the payload to the KNX IoT representation based on dataType.
Continue with the Point API sending procedure through /fp/r.

A group event message that arrives from KNX IoT follows the mirrored order. The KNX IoT Router checks the load state and looks up the Group Address in /fp/gm. It then converts the payload to the KNX Classic representation and applies KNX Data Security before it sends the frame.

Message Translation

The KNX IoT Router converts payloads between the Point API encoding and the KNX Classic datapoint types. The conversion needs only the datapoint type main number, so the MaC configures that number without leading zeros for each Group Address in /fp/gm.

Individual Address Defending

The KNX IoT Router defends its own Individual Address and the addresses of the KNX IoT subsegment on the KNX Classic medium. It answers a T_Connect PDU that targets a defended address with a T_Disconnect PDU. The defended set follows the role of the Coupler Profile.

A Coupler defends only its own Individual Address when the Load State Machine is not in the loaded state or when /p/coupling/segment-iatbl is absent or empty.

Medium-Specific Routing

On the KNXnet/IP medium, the KNX IoT Router sends frames according to KNXnet/IP Routing and KNX IP Secure. It sets the cEMI hop count to 6 for frames that it sends to KNX Classic and processes received frames regardless of their hop count.

On the TP medium, the KNX IoT Router acts only as a group-oriented data-link coupler and forwards group-addressed telegrams according to /fp/gm:

The KNX IoT Router acknowledges a received group-addressed frame with a positive link-layer acknowledgement only when /fp/gm contains the destination Group Address. It neither acknowledges nor forwards a frame without a match.
The KNX IoT Router repeats a frame that it sends on the bus until it receives a positive acknowledgement, with up to three repetitions after a NAK, a corrupted acknowledgement, or a time-out, and up to three repetitions after a BUSY acknowledgement.
These values correspond to the data link layer parameters nak_retry and busy_retry. The KNX TP standard defines both values, so a device offers no setting to change them.

Profiles

The netip and coupling functional blocks are the KNX IoT Router-specific additions to the standard Point API resource list. The interface scopes follow the Point API rules, with two router-specific points:

/fp/gm uses the if.sec interface for write and item access, and the if.ll interface for the link-format list.
/fp/gma uses the if.d interface for diagnostic access without the group key.
/p/netip/key uses the if.sec interface instead of if.p.

Every KNX IoT Router complies with the common KNX Classic support and with exactly one medium profile.

Feature	Support
Transport layer, connection-oriented minimal	[m]
Transport layer without a connection	[m]
Device Descriptor service without a connection	[m]
Device Descriptor Type 0	[m]
Maximum APDU length of at least 55 octets	[m]

The KNXnet/IP profile requires KNXnet/IP frames, host protocol independence, the discovery features of this page, the ROUTING_INDICATION service, and the KNX IP Secure security layer with multicast communication.

The Coupler profile requires the TP physical and transceiver layer, the group-oriented data link layer, the link-layer acknowledgement on a mapping table match, and the frame repetition behaviour. All features that the profiles do not list remain optional. For the resource-level requirements of a Point API device, see Device Profile.

Cybersecurity

The Point API security rules apply to the KNX IoT Router without change. Neither the KNXnet/IP medium nor the TP medium can read or write resources on the KNX Classic side, which makes the whole device a secured device in the MaC.

This property makes the router a practical zone boundary. A KNX installation often contains devices from several manufacturers with different security levels and different update cycles, so a micro-segmentation into zones limits the effect of a weak device. The KNX IoT Router serves as the entry point into an installation or into one area of an installation, and it forwards only the Group Addresses that /fp/gm configures.

The boundary works in two directions. Towards another KNX subsystem, the mapping table keeps the group communication of one zone separate from the neighbouring zone. Towards a third-party system in a vertical integration, the router terminates the external session and exposes only the configured Group Objects. The third-party client therefore reaches no device resource behind the boundary. See Vertical Integration for the system view of this pattern.

Manufacturers can equip a KNX IoT Router with two separate Ethernet network interfaces. One interface serves vertical integration, and the other serves horizontal interworking on the KNX Backbone or the KNX IoT area. This separation isolates the KNX devices from other network segments.

A manufacturer-specific implementation can also open IP forwarding between network interfaces for a limited time and for specific devices. A remote MaC can then reach those devices directly over IP for configuration. This forwarding acts as a normal firewall rule with a temporary scope, and it is not a feature of the Point API specification.