Skip to content

Commit b1c48a3

Browse files
Adam-MaciugaAdam-Maciuga
committed
docs: samples: light switch: initial sample docs
Documentation fot the light swich samples Both the sensor and actuator docs are created Signed-off-by: Adam Maciuga <adam.maciuga@nordicsemi.no>
1 parent 8a4717b commit b1c48a3

2 files changed

Lines changed: 239 additions & 2 deletions

File tree

‎samples/light_switch_actuator/README.rst‎

Lines changed: 120 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,123 @@ KNX IoT: Light Switch Actuator
77
:local:
88
:depth: 2
99

10-
KNX IoT: Light Switch Actuator sample.
10+
This sample demonstrates a KNX IoT light switch actuator built on top of the |addon| for the |NCS|.
11+
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.
12+
13+
When paired with the :ref:`knx_iot_light_switch_sensor_sample` sample running on a second development kit, the actuator turns its load on and off following the switch state transmitted by the sensor.
14+
15+
Requirements
16+
************
17+
18+
The sample supports the following development kits:
19+
20+
.. table-from-sample-yaml::
21+
22+
Currently, a second development kit running the :ref:`knx_iot_light_switch_sensor_sample` sample is required.
23+
24+
Overview
25+
********
26+
27+
The sample acts as a KNX IoT actuator device.
28+
It registers a single device profile that exposes the LSAB functional block (number ``417``) on two switching channels.
29+
Each channel provides the following datapoints:
30+
31+
* Switch on/off (``soo``) - The control input datapoint (``GET`` and ``PUT``, ``if.i``).
32+
The actuator receives group writes on this datapoint and mirrors the new value onto the status output.
33+
* Info on/off (``ioo``) - The status output datapoint (``GET``, ``if.o``).
34+
The actuator announces this value to report its current state back to the group.
35+
36+
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.
37+
The switched load of the first channel is represented by an LED.
38+
39+
Commissioning
40+
=============
41+
42+
The sample currently works only with hardcoded commissioning enabled (the :kconfig:option:`CONFIG_KNX_HARDCODED_COMMISSIONING` Kconfig option).
43+
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 key.
44+
This allows the actuator and sensor to communicate without the ETS tool or a Thread commissioner.
45+
46+
The shared fabric parameters (group address ``1/1/1`` and the group OSCORE key) are defined in the :file:`samples/common/knx_hardcoded.h` file and must be identical on both devices.
47+
The actuator uses the individual address ``1.1.1``.
48+
49+
.. note::
50+
Hardcoded commissioning is intended for development and demonstration only.
51+
52+
User interface
53+
**************
54+
55+
LED 1:
56+
Indicates the network and KNX service status.
57+
The LED turns on when the Thread network is up and the KNX service has been published.
58+
59+
LED 2:
60+
Indicates the switched load (light) state of the first channel.
61+
The LED follows the received ``soo`` value: it turns on when the switch state is on, and off when it is off.
62+
63+
.. note::
64+
Button 1 is reserved for the system button (factory reset) for future use.
65+
66+
Configuration
67+
*************
68+
69+
|config|
70+
71+
The following Kconfig options are most relevant for this sample:
72+
73+
* :kconfig:option:`CONFIG_KNX_HARDCODED_COMMISSIONING` - Applies the hardcoded commissioning profile on boot.
74+
75+
The Thread network configuration is provided through the :file:`samples/common/thread_hardcoded.conf` file.
76+
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.
77+
In the current state of the sample, this file is required for the device to function correctly.
78+
79+
Building and running
80+
********************
81+
82+
Before you start, make sure you have set up the |addon| as described in the :ref:`knx_iot_setup` page.
83+
84+
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:
85+
86+
.. code-block:: console
87+
88+
west build -b board_target -- -DEXTRA_CONF_FILE=../common/thread_hardcoded.conf
89+
90+
For example, to build for the nRF54L15 DK, run the following command:
91+
92+
.. code-block:: console
93+
94+
west build -b nrf54l15dk/nrf54l15/cpuapp -- -DEXTRA_CONF_FILE=../common/thread_hardcoded.conf
95+
96+
After building, program the sample to the development kit:
97+
98+
.. code-block:: console
99+
100+
west flash --erase
101+
102+
Testing
103+
*******
104+
105+
After programming the sample to your development kit, you can test it together with the :ref:`knx_iot_light_switch_sensor_sample` sample running on a second kit.
106+
107+
1. Program the actuator sample to one development kit and the sensor sample to another.
108+
#. Reset both kits.
109+
#. Wait until **LED 1** turns on for both kits, which indicates that the Thread network is up and the KNX service is published.
110+
#. Press **Button 2** on the sensor kit.
111+
112+
The sensor toggles its switch datapoint and transmits it.
113+
114+
#. Observe that **LED 2** on the actuator kit lights up.
115+
#. Press **Button 2** on the sensor kit again.
116+
117+
**LED 2** on the actuator kit turns off.
118+
119+
Dependencies
120+
************
121+
122+
This sample uses the KNX IoT stack provided by the |addon|, together with the following |NCS| components:
123+
124+
* :ref:`dk_buttons_and_leds_readme`
125+
126+
It also uses the following Zephyr libraries:
127+
128+
* :ref:`zephyr:logging_api`
129+
* :ref:`zephyr:kernel_api`

‎samples/light_switch_sensor/README.rst‎

Lines changed: 119 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,122 @@ KNX IoT: Light Switch Sensor
77
:local:
88
:depth: 2
99

10-
KNX IoT: Light Switch Sensor sample.
10+
This sample demonstrates a KNX IoT light switch sensor built on top of the |addon| for the |NCS|.
11+
The sample implements the KNX **Light Switching Sensor Basic** (LSSB) functional block and transmits switch on/off s-mode messages over a Thread network using KNX IoT group communication.
12+
13+
When paired with the :ref:`knx_iot_light_switch_actuator_sample` sample running on a second development kit, pressing a button on the sensor toggles the LED on the actuator.
14+
15+
Requirements
16+
************
17+
18+
The sample supports the following development kits:
19+
20+
.. table-from-sample-yaml::
21+
22+
Currently, a second development kit running the :ref:`knx_iot_light_switch_actuator_sample` sample is required.
23+
24+
Overview
25+
********
26+
27+
The sample acts as a KNX IoT sensor device.
28+
It registers a single device profile that exposes the LSSB functional block (number ``421``) on two switching channels.
29+
Each channel provides the following datapoints:
30+
31+
* Switch on/off (``soo``) - The control output datapoint (``GET``, ``if.o``).
32+
The sensor owns this value and announces it to the group.
33+
* Info on/off (``ioo``) - The status input datapoint (``GET`` and ``PUT``, ``if.i``).
34+
It reflects the status reported back by the bound actuator.
35+
36+
When you press the application button, the sample toggles the ``soo`` datapoint of the first channel and transmits it as an s-mode multicast write to every device bound to the same group address.
37+
A bound actuator receives the s-mode message, drives its output, and announces its own status, which the sensor stores in its ``ioo`` datapoint.
38+
39+
Commissioning
40+
=============
41+
42+
The sample currently works only with hardcoded commissioning enabled (the :kconfig:option:`CONFIG_KNX_HARDCODED_COMMISSIONING` Kconfig option).
43+
On boot, the sample applies a fixed KNX commissioning profile, which includes the individual address, the group object and recipient tables, and a shared group OSCORE key.
44+
This allows the sensor and actuator to communicate without the ETS tool or a Thread commissioner.
45+
46+
The shared fabric parameters (group address ``1/1/1`` and the group OSCORE key) are defined in the :file:`samples/common/knx_hardcoded.h` file and must be identical on both devices.
47+
The sensor uses the individual address ``1.1.2``.
48+
49+
.. note::
50+
Hardcoded commissioning is intended for development and demonstration only.
51+
52+
User interface
53+
**************
54+
55+
LED 1:
56+
Indicates the network and KNX service status.
57+
The LED turns on when the Thread network is up and the KNX service has been published.
58+
59+
Button 2:
60+
Toggles the switch on/off (``soo``) datapoint of the first channel and transmits it to the bound group.
61+
62+
.. note::
63+
Button 1 is reserved for the system button (factory reset) for future use.
64+
65+
Configuration
66+
*************
67+
68+
|config|
69+
70+
The following Kconfig options are most relevant for this sample:
71+
72+
* :kconfig:option:`CONFIG_KNX_HARDCODED_COMMISSIONING` - Applies the hardcoded commissioning profile on boot.
73+
74+
The Thread network configuration is provided through the :file:`samples/common/thread_hardcoded.conf` file.
75+
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.
76+
In the current state of the sample, this file is required for the device to function correctly.
77+
78+
Building and running
79+
********************
80+
81+
Before you start, make sure you have set up the |addon| as described in the :ref:`knx_iot_setup` page.
82+
83+
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:
84+
85+
.. code-block:: console
86+
87+
west build -b board_target -- -DEXTRA_CONF_FILE=../common/thread_hardcoded.conf
88+
89+
For example, to build for the nRF54L15 DK, run the following command:
90+
91+
.. code-block:: console
92+
93+
west build -b nrf54l15dk/nrf54l15/cpuapp -- -DEXTRA_CONF_FILE=../common/thread_hardcoded.conf
94+
95+
After building, program the sample to the development kit:
96+
97+
.. code-block:: console
98+
99+
west flash --erase
100+
101+
Testing
102+
*******
103+
104+
After programming the sample to your development kit, you can test it together with the :ref:`knx_iot_light_switch_actuator_sample` sample running on a second kit.
105+
106+
1. Program the sensor sample to one development kit and the actuator sample to another.
107+
#. Reset both kits.
108+
#. Wait until **LED 1** turns on for both kits, which indicates that the Thread network is up and the KNX service is published.
109+
#. Press **Button 2** on the sensor kit.
110+
111+
The sensor toggles its switch datapoint and transmits it.
112+
113+
#. Observe that **LED 2** on the actuator kit lights up.
114+
#. Press **Button 2** on the sensor kit again.
115+
116+
**LED 2** on the actuator kit turns off.
117+
118+
Dependencies
119+
************
120+
121+
This sample uses the KNX IoT stack provided by the |addon|, together with the following |NCS| components:
122+
123+
* :ref:`dk_buttons_and_leds_readme`
124+
125+
It also uses the following Zephyr libraries:
126+
127+
* :ref:`zephyr:logging_api`
128+
* :ref:`zephyr:kernel_api`

0 commit comments

Comments
 (0)