Commissioning in the KNX IoT add-on

A device built with the KNX IoT add-on is commissioned in two independent steps. Thread commissioning connects the device to the Thread network, and KNX commissioning makes it a configured member of the KNX installation. This page describes how the KNX IoT add-on and its samples implement both steps. For the standard KNX IoT commissioning flow, see Commissioning.

Thread commissioning

A device must be attached to a Thread network before KNX commissioning can start. By default, the samples use Thread Joiner commissioning. For step-by-step instructions, see the Quick start guide with ETS.

For development without a Commissioner, the samples provide two options for Thread Out-of-band commissioning enabled by including an additional configuration file:

  1. samples/common/overlay-thread-hardcoded.conf automatically starts Thread with predefined network data.

  2. samples/common/overlay-thread-otshell.conf disables automatic Joiner startup and allows the Thread dataset to be configured manually from the OpenThread shell. After a reboot, the device rejoins the network with the stored dataset.

In installations configured with ETS, a manufacturer-specific Thread Border Router Device Configuration App can configure the Thread Border Router, the Thread subsystem, and device assignment to the Thread network.

ETS commissioning

By default, the KNX IoT samples are commissioned with the ETS tool. ETS identifies devices by their serial number, so it can find an uncommissioned device without programming mode enabled. Each device in the same ETS project needs a unique serial number, which is set with the CONFIG_KNX_SERIAL_NUMBER Kconfig option. Programming mode is not enabled automatically; it can be enabled with the corresponding board button or from the shell. For step-by-step instructions, see the Quick start guide with ETS.

Hardcoded commissioning

For development and testing without ETS, the KNX IoT add-on also provides hardcoded commissioning, enabled with the CONFIG_KNX_HARDCODED_COMMISSIONING Kconfig option. The samples enable it with the samples/common/overlay-knx-hardcoded.conf configuration file. Combined with samples/common/overlay-thread-hardcoded.conf, it lets devices exchange KNX messages without ETS or a Thread Commissioner.

When enabled, a device applies a fixed commissioning profile on boot instead of receiving it from a MaC (usually ETS). The profile includes:

  • The device’s Individual Address.

  • The group object table, with one entry for each bound datapoint, and the recipient and publisher tables derived from it.

  • A shared group OSCORE key, so devices can exchange protected S-Mode messages without a PASE handshake.

The shared parameters are defined in samples/common/knx_hardcoded.h and must be identical on every device that communicates. They include one group address for each switching channel (1/1/1 for the first channel and 1/1/2 for the second) and the group OSCORE key. Each sample defines its group object table in its own preset file, for example samples/light_switch_sensor/knx_sensor_hardcoded.c.

Note

Hardcoded commissioning is intended for development and demonstration only. It is not a substitute for standard, secure commissioning in a production installation.

Device identity in hardcoded setups

Every device in a hardcoded setup must have a unique serial number, because the device’s DNS-SD hostname and the OSCORE ID Context of its group messages are derived from it. Receivers keep a separate security context and replay window for each sender of the shared group key.

The CONFIG_KNX_HARDCODED_IDENTITY Kconfig choice selects where the device takes its serial number and Individual Address from: