KNX IoT: Light Switch Actuator

This sample demonstrates a KNX IoT light switch actuator built on top of the KNX IoT add-on for the nRF Connect SDK. The sample implements the KNX Light Switching Actuator Basic (LSAB) functional block and drives a load (shown on an LED) in response to switch on/off S-mode messages received over a Thread network using KNX IoT group communication.

When paired with the KNX IoT: Light Switch Sensor sample running on a second development kit, the actuator turns its load on and off following the switch state transmitted by the sensor.

Requirements 

The sample supports the following development kits:

Hardware platforms	PCA	Board name	Board target
nRF54LM20B DK	PCA10184	nrf54lm20dk	`nrf54lm20dk/nrf54lm20b/cpuapp`
nRF54LM20A DK	PCA10184	nrf54lm20dk	`nrf54lm20dk/nrf54lm20a/cpuapp`
nRF54L15 DK	PCA10156	nrf54l15dk	`nrf54l15dk/nrf54l15/cpuapp`

To test the communication with the light sensor, a second development kit running the KNX IoT: Light Switch Sensor sample is required.

Overview 

The sample acts as a KNX IoT actuator device. In this context, the light switch actuator is the device that changes a light state in response to commands from another device, such as a relay, dimmer, smart light bulb, or another output controller. It registers a single device profile that exposes the LSAB functional block (number 417) on two switching channels. Each channel provides the following datapoints:

Switch on/off (soo) - The control input datapoint (GET and PUT, if.i). The actuator receives group writes on this datapoint and mirrors the new value onto the status output.
Info on/off (ioo) - The status output datapoint (GET, if.o). The actuator announces this value to report its current state back to the group.

When the actuator receives an S-mode multicast write on the soo datapoint of a channel, it drives its output, mirrors the value to the ioo datapoint, and announces the new status. The switched load of the first channel is represented by an LED.

Commissioning 

The sample currently works only with hardcoded commissioning enabled (the CONFIG_KNX_HARDCODED_COMMISSIONING Kconfig option). On boot, the sample applies a fixed KNX commissioning profile, which includes the individual address, the group object and publisher tables, and a shared group OSCORE (Object Security for Constrained RESTful Environments) key. OSCORE protects KNX IoT messages by encrypting and authenticating them at the application layer. In this sample, the shared group OSCORE key lets the actuator and sensor exchange protected messages without the ETS6 tool or a Thread commissioner.

The shared fabric parameters (group address 1/1/1 and the group OSCORE key) are defined in the samples/common/knx_hardcoded.h file and must be identical on both devices. The actuator uses the individual address 1.1.1.

Note

Hardcoded commissioning is intended for development and demonstration only.

User interface 

LED 1:: Indicates the network and KNX service status. The LED blinks while the device is waiting to attach to the Thread network. The LED turns on steadily when the Thread network is up and the KNX service has been published.
LED 2:: Indicates the switched load (light) state of the first channel. The LED follows the received soo value: it turns on when the switch state is on, and off when it is off.

Configuration 

See Configuring and building for information about how to permanently or temporarily change the configuration.

The following Kconfig options are most relevant for this sample:

CONFIG_KNX_HARDCODED_COMMISSIONING - Applies the hardcoded commissioning profile on boot.

The Thread network configuration is provided through the samples/common/thread_hardcoded.conf file. This file configures a fixed Thread dataset (network name, PAN ID, channel, and network key) so that every device built with it forms or joins the same Thread network on boot, without a Thread commissioner. In the current state of the sample, this file is required for the device to function correctly.

Building and running 

Before you start, make sure you have set up the KNX IoT add-on as described in the Requirements and setup page.

This sample requires the Thread hardcoded configuration from samples/common/thread_hardcoded.conf. You can build using either the nRF Connect for VS Code extension or the command line.

Open the sample folder in VS Code with the nRF Connect extension installed.
In the extension’s build configuration, add ../common/thread_hardcoded.conf to Extra Kconfig fragments.
Select a supported board target and build or flash the sample.

To build the sample from the command line, run the following command from the sample directory, with board_target replaced by one of the supported board targets:

west build -b board_target -- -DEXTRA_CONF_FILE=../common/thread_hardcoded.conf

For example, to build for the nRF54L15 DK, run the following command:

west build -b nrf54l15dk/nrf54l15/cpuapp -- -DEXTRA_CONF_FILE=../common/thread_hardcoded.conf

After building, program the sample to the development kit:

west flash --erase

To enable verbose KNX stack logging for debugging, add ../common/verbose_logging.conf as an additional Kconfig fragment.

Testing 

After programming the sample to your development kit, you can test it together with the KNX IoT: Light Switch Sensor sample running on a second kit.

Program the actuator sample to one development kit and the sensor sample to another.
Reset both kits.
Wait until LED 1 turns on for both kits, which indicates that the Thread network is up and the KNX service is published.
Press Button 2 on the sensor kit.

The sensor toggles its switch datapoint and transmits it.
Observe that LED 2 on the actuator kit lights up.
Press Button 2 on the sensor kit again.
Observe that LED 2 on the actuator kit turns off.

Dependencies 

This sample uses the KNX IoT stack provided by the KNX IoT add-on, together with the following nRF Connect SDK components:

DK Buttons and LEDs

It also uses the following Zephyr libraries: