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 two loads (shown on LEDs) in response to switch on/off S-mode messages received over a Thread network using KNX IoT group communication.
When used with the KNX IoT: Light Switch Sensor sample running on a second development kit, the actuator turns its loads on and off following the switch states transmitted by the sensor.
Requirements
The sample supports the following development kits:
Hardware platforms |
PCA |
Board name |
Board target |
|---|---|---|---|
PCA10184 |
|
||
PCA10184 |
|
||
PCA10226 |
|
||
PCA10156 |
|
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.
Both channels can be configured through ETS or the hardcoded development profile.
Each channel provides the following datapoints:
Switch on/off (
soo) - The control input datapoint (GETandPUT,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 loads of the two channels are represented by LED 2 and LED 3.
Light state persistence
The actuator stores the soo value of each channel in non-volatile memory whenever it changes.
After a reboot, the actuator restores the stored light state and shows it on the channel LED.
A KNX factory reset erases the stored state and switches the loads off.
If the soo group object of a channel has the Read on Init (I) flag set in ETS, the actuator also reads the current light state from the group after it attaches to the network.
This lets an actuator recover a state that was switched while it was turned off, for example when several actuators share one group.
The channel LED blinks while the actuator waits for the response.
If no response arrives, the actuator keeps the stored state.
For more information, see Datapoint persistence and Read on init.
Commissioning
The default configuration uses the OpenThread Joiner and ETS commissioning. To join the Thread network and commission the device with ETS, follow the Quick start guide with ETS.
For a local test without ETS or a Thread Commissioner, build both samples with the hardcoded KNX and Thread profiles:
west build -b board_target -- -DEXTRA_CONF_FILE="../common/overlay-knx-hardcoded.conf;../common/overlay-thread-hardcoded.conf"
The hardcoded KNX profile binds the first channel to group address 1/1/1 and the second channel to group address 1/1/2.
The hardcoded profiles are intended for development and demonstration only.
For more information about the commissioning methods, see Commissioning in the KNX IoT add-on.
User interface
- LED 0:
Indicates the Thread network status. The LED blinks while the device is attaching and remains on when it is attached.
- LED 1:
Indicates the KNX status. The LED blinks in programming mode and remains on after commissioning.
- LED 2 and LED 3:
Indicate the switched load state of the first and second channels. The LED blinks while the actuator waits for the read-on-init response of the channel.
- Button 0:
Short press starts or retries the Thread Joiner. Hold for six seconds to perform a Thread factory reset.
- Button 1:
Short press toggles KNX programming mode. Use it after the device has attached to a Thread network (LED 0 steadily lit). Hold for six seconds to perform a KNX factory reset. Available only with ETS commissioning (
CONFIG_KNX_ETS_COMMISSIONING).
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_SERIAL_NUMBER- Sets the KNX serial number of the device (00fa10020900by default for this sample).CONFIG_KNX_PROGRAMMING_MODE_AUTOSTART- Enables programming mode temporarily after an uncommissioned device joins Thread.CONFIG_KNX_HARDCODED_COMMISSIONING- Applies the development-only hardcoded KNX profile.
SPAKE2+ credentials
Important
During the build, the KNX IoT add-on generates a SPAKE2+ verifier from CONFIG_KNX_IOT_PASSWORD and compiles it into the application.
The stack uses the verifier for PASE authentication, while the samples retain the password to print their onboarding QR code on demand.
The default password and salt are intended for demonstration only. Production applications must use device-specific credentials and a suitable provisioning process. For more information about SPAKE2+, see PASE and SPAKE2+.
The default Thread profile starts the Joiner automatically with PSKd N0RD1C.
Use ../common/overlay-thread-hardcoded.conf for a fixed Thread dataset or ../common/overlay-thread-otshell.conf to configure and start Thread manually.
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.
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.
Select a supported board target.
Optionally add
-DEXTRA_CONF_FILE=release.conf -DFILE_SUFFIX=releaseto Extra CMake arguments in your build configuration to select a power-optimized build without logs.Build and 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
For example, to build for the nRF54L15 DK, run the following command:
west build -b nrf54l15dk/nrf54l15/cpuapp
For a power-optimized release build without logging and shell support, add the release configuration:
west build -b nrf54l15dk/nrf54l15/cpuapp -- -DEXTRA_CONF_FILE=release.conf -DFILE_SUFFIX=release
After building, program the sample to the development kit:
west flash --erase
To enable verbose KNX stack logging for debugging, build the sample with the knx-verbose-logging snippet:
west build -b nrf54l15dk/nrf54l15/cpuapp -S knx-verbose-logging
In the nRF Connect for VS Code extension, add -DSNIPPET=knx-verbose-logging to Extra CMake arguments in your build configuration.
The snippet enables CONFIG_KNX_VERBOSE_STACK_LOGS, enlarges the log buffer, and increases the console UART baud rate from the default 115200 to 1000000 to avoid dropping logs.
Testing
After commissioning both devices with ETS as described in the Quick start guide with ETS, or building both with the hardcoded profiles, test the samples as follows:
Wait until LED 0 and LED 1 are steadily lit on both kits.
Press Button 2 on the sensor kit to test the first channel.
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.
Repeat the previous steps for the second channel with Button 3 on the sensor kit and LED 3 on the actuator kit. When using ETS, the second channel must be linked in the ETS project.
Press Button 2 on the sensor kit to turn on LED 2 on the actuator kit, and then reset the actuator kit.
Observe that LED 2 on the actuator kit lights up again after the actuator restarts.
Dependencies
This sample uses the KNX IoT stack provided by the KNX IoT add-on, together with the following nRF Connect SDK components:
It also uses the following Zephyr libraries: