You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/knx-iot/addon.rst
+12-3Lines changed: 12 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -44,17 +44,26 @@ Its main source files are:
44
44
* :file:`knx_app.c`, :file:`knx_stack.c` - Initialize and run the KNX IoT stack, including the event loop.
45
45
* :file:`knx_resources.c` - Register the application's KNX resources (functional blocks and datapoints).
46
46
* :file:`knx_transport.c` - Adapt the stack to the underlying IPv6/Thread transport.
47
-
* :file:`knx_board.c`- Shared board support (status LED, button dispatch), built when :kconfig:option:`CONFIG_DK_LIBRARY` is enabled.
47
+
* :file:`knx_board.c`, :file:`knx_buttons.c`, :file:`knx_leds.c` - Shared board support (status LEDs, button handling), built when :kconfig:option:`CONFIG_DK_LIBRARY` is enabled.
48
48
* :file:`knx_presets.c` - The hardcoded commissioning mechanism, built when :option:`CONFIG_KNX_HARDCODED_COMMISSIONING` is enabled (see :ref:`knx_iot_commissioning`).
49
49
50
50
The stack runs its event loop on a dedicated worker thread whose scheduling priority is set with the :option:`CONFIG_KNX_THREAD_PRIORITY` Kconfig option.
51
51
52
+
SPAKE2+ credentials
53
+
===================
54
+
55
+
During the build, the |addon| generates a SPAKE2+ verifier from :option:`CONFIG_KNX_IOT_PASSWORD` and compiles it into the application.
56
+
The stack uses the verifier for PASE authentication, while the samples retain the password to print their onboarding QR code on demand.
57
+
58
+
The default password and salt are intended for demonstration only.
59
+
Production applications must use device-specific credentials and a suitable provisioning process.
60
+
For more information about SPAKE2+, see :ref:`knx_iot_security`.
52
61
53
62
Relationship to the upstream stack
54
63
**********************************
55
64
56
-
The KNX IoT functionality itself comes from the upstream Point API stack, and it is integrated by the |addon|.
57
-
The |addon| disables the stack's bundled demo applications and replaces them with its own device-agnostic application layer in:file:`subsys/knx/`.
65
+
The KNX IoT functionality comes from the upstream Point API stack.
66
+
The |addon| provides the |NCS| integration and a device-agnostic application layer under:file:`subsys/knx/`.
58
67
For upstream documentation, the protocol specifications, and schemas, see the `KNX IoT documentation`_ and `KNX IoT downloads and schemas`_.
59
68
60
69
For the current feature coverage and limitations, see :ref:`knx_iot_software_maturity` and :ref:`knx_iot_known_issues`.
Copy file name to clipboardExpand all lines: docs/knx-iot/overview/commissioning.rst
+24-10Lines changed: 24 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,7 +8,7 @@ Commissioning
8
8
:depth: 2
9
9
10
10
*Commissioning* is the process of turning a factory-fresh device into a configured member of a KNX installation: giving it an identity, telling it which groups it belongs to, and installing the security material it needs.
11
-
This page explains the standard KNX IoT commissioning flow and how the |addon| currently provides a simplified alternative for development.
11
+
This page explains the standard KNX IoT commissioning flow and the commissioning methods supported by the |addon|.
12
12
For more information, see `KNX IoT device bootstrapping`_.
13
13
14
14
The Management and Commissioning Client
@@ -31,7 +31,8 @@ Part 1: Individualization
31
31
32
32
The MaC authenticates the device and gives it an identity:
33
33
34
-
#. **Discovery** - The installer puts the device into programming mode (typically with a physical button), and the MaC locates it by serial number or Individual Address through discovery (see :ref:`knx_iot_group_communication`).
34
+
#. **Discovery** - The MaC locates the device by serial number or Individual Address.
35
+
Alternatively, the installer can put a device into programming mode and discover it by that state (see :ref:`knx_iot_group_communication`).
35
36
#. **PASE handshake** - The MaC and the device run the password-authenticated SPAKE2+ handshake to establish a temporary secure (OSCORE) session from a shared password. See :ref:`knx_iot_security`.
36
37
#. **Tool key installation** - Over that secure session, the MaC installs a long-lived *tool key* access token, which it will use for all further configuration.
37
38
#. **Address assignment** - The MaC assigns the device its Individual Address and clears programming mode.
@@ -48,11 +49,15 @@ Using the tool-key session, the MaC downloads the actual configuration:
48
49
#. **Security material** - The MaC installs the access tokens and keys the device needs for group communication (see :ref:`knx_iot_security`).
49
50
#. **Loaded** - The device transitions to the loaded state and begins normal operation.
50
51
51
-
Hardcoded commissioning in the |addon|
52
-
**************************************
52
+
Commissioning in the |addon|
53
+
****************************
53
54
54
-
The |addon| does not yet integrate with ETS or a full MaC.
55
-
Instead, it provides *hardcoded commissioning* for development and demonstration, enabled with the :option:`CONFIG_KNX_HARDCODED_COMMISSIONING` Kconfig option.
55
+
The samples use ETS6 commissioning by default.
56
+
ETS can identify an uncommissioned sample by its serial number without programming mode.
57
+
Programming mode is not enabled automatically; it can be enabled with the corresponding board button or from the shell.
58
+
For step-by-step instructions, see :ref:`knx_iot_ets_commissioning`.
59
+
60
+
For development and demonstration without ETS, the |addon| also provides *hardcoded commissioning*, enabled with the :option:`CONFIG_KNX_HARDCODED_COMMISSIONING` Kconfig option.
56
61
57
62
When enabled, a device applies a fixed commissioning profile on boot instead of receiving it from a MaC.
58
63
The profile includes:
@@ -62,15 +67,24 @@ The profile includes:
62
67
* A shared group OSCORE key, so devices can exchange protected S-Mode messages without a PASE handshake.
63
68
64
69
In the samples, these shared parameters (group address ``1/1/1`` and the group OSCORE key) are defined in :file:`samples/common/knx_hardcoded.h` and must be identical on every device that communicates.
65
-
This lets two development kits talk to each other directly, without `ETS6 tool`_ or a Thread commissioner.
70
+
This lets two development kits exchange KNX messages without `ETS6 tool`_.
66
71
67
72
.. note::
68
73
Hardcoded commissioning is intended for development and demonstration only.
69
74
It is not a substitute for standard, secure commissioning in a real installation.
70
75
71
-
The Thread network itself is also fixed for the samples: a hardcoded Thread dataset is provided through :file:`samples/common/thread_hardcoded.conf`, so every device built with it forms or joins the same Thread network on boot without a Thread commissioner.
72
-
See the :ref:`knx_iot_samples` for how this is used in practice.
76
+
Thread commissioning
77
+
********************
78
+
79
+
KNX commissioning and Thread commissioning are configured independently.
80
+
By default, the samples use Thread Joiner commissioning.
81
+
82
+
For development without a Commissioner, the samples provide two options enabled by including an additional configuration file:
83
+
84
+
1. :file:`samples/common/overlay-thread-hardcoded.conf` automatically starts Thread with a predefined network data.
85
+
2. :file:`samples/common/overlay-thread-otshell.conf` disables automatic Joiner startup and allows the Thread dataset to be configured manually from the OpenThread shell.
86
+
87
+
See the :ref:`knx_iot_samples` for build instructions and see :ref:`knx_iot_ets_commissioning` for step-by-step instructions.
73
88
74
-
A more flexible approach is standard Thread commissioning, where a Joiner is authorized by a Commissioner and receives the active operational dataset for the Thread network.
75
89
In ETS-based installations, a manufacturer-specific Thread Border Router Device Configuration App configures the Thread Border Router, the Thread subsystem, and device assignment to the Thread network.
Copy file name to clipboardExpand all lines: docs/knx-iot/overview/group_communication.rst
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -58,8 +58,8 @@ At runtime, a device sends a group notification by POSTing to the ``/k`` resourc
58
58
Subscribers can also use CoAP *Observe* on ``/k`` to receive notifications.
59
59
60
60
.. note::
61
-
In the :ref:`knx_iot_samples`, both devices share a single group address and a single group OSCORE key applied through hardcoded commissioning, so they exchange S-Mode messages directly without a commissioning tool.
62
-
See :ref:`knx_iot_commissioning` and the :ref:`knx_iot_samples`.
61
+
After commissioning, the :ref:`knx_iot_samples` use group addresses and OSCORE keys configured by ETS.
62
+
See :ref:`knx_iot_commissioning` for more information.
The light switch samples use ETS6 commissioning and the OpenThread Joiner by default.
11
+
This page describes how to join the devices to a Thread network and configure their KNX group communication in ETS.
12
+
For an overview of the protocol flow, see :ref:`knx_iot_commissioning`.
13
+
14
+
Requirements
15
+
************
16
+
17
+
You need:
18
+
19
+
* ETS6 with compatible product entries for the light switch actuator and sensor.
20
+
Those entries can be found in the Catalog under `KNX Association`:`KNX Virtual`:`IoT Demo Sensor/Actuator`, or downloaded from the `KNX IoT virtual LSxB product entry`_.
21
+
* An OpenThread Border Router that is reachable from the ETS host and provides a Thread Commissioner.
22
+
* One development kit for each sample.
23
+
24
+
The product entry uses manufacturer code ``0x00FA``, which is assigned to the KNX Association.
25
+
The samples use this code for demonstration purposes.
26
+
The following serial numbers identify the devices:
27
+
28
+
======== ================
29
+
Sample Serial number
30
+
======== ================
31
+
Actuator ``00fa10020900``
32
+
Sensor ``00fa10020700``
33
+
======== ================
34
+
35
+
Build and flash
36
+
***************
37
+
38
+
From the |addon| directory, build and flash the default configuration for each sample:
39
+
40
+
.. code-block:: console
41
+
42
+
west build -b nrf54l15dk/nrf54l15/cpuapp -d build/actuator samples/light_switch_actuator
43
+
west flash -d build/actuator
44
+
45
+
west build -b nrf54l15dk/nrf54l15/cpuapp -d build/sensor samples/light_switch_sensor
46
+
west flash -d build/sensor
47
+
48
+
Join the Thread network
49
+
***********************
50
+
51
+
The samples start the Joiner automatically with PSKd ``N0RD1C``.
52
+
If your Border Router requires the device EUI-64 to authorize the Joiner, run ``ot eui64`` in the device shell to retrieve it.
53
+
Consult your Border Router's documentation for the commissioning procedure.
54
+
If your Border Router provides console access, authorize the Joiner as follows:
55
+
56
+
#. Authorize the Joiner:
57
+
58
+
.. code-block:: console
59
+
60
+
ot-ctl commissioner start
61
+
ot-ctl commissioner joiner add <EUI64> N0RD1C
62
+
63
+
It is also possible to authorize the joiner without knowing the EUI-64.
64
+
Just make sure only one device is trying to join the network in this scenario.
65
+
66
+
.. code-block:: console
67
+
68
+
ot-ctl commissioner joiner add * N0RD1C
69
+
70
+
#. Wait until **LED 0** remains on, indicating that the device has attached to the Thread network.
71
+
If the device does not attach, press **Button 0** to retry the Joiner.
72
+
73
+
If the Commissioner authorization expires before the device joins, repeat the authorization and retry the Joiner.
74
+
75
+
.. note::
76
+
77
+
If your Border Router does not provide a Thread Commissioner, see :ref:`knx_iot_samples` for alternative Thread commissioning methods.
78
+
79
+
Configure the devices in ETS
80
+
****************************
81
+
82
+
#. Create an ETS project and add an IoT line.
83
+
#. Add the actuator and sensor product entries to the line.
84
+
#. Read each device's onboarding QR string from its shell:
85
+
86
+
.. code-block:: console
87
+
88
+
knx_iot qr_code
89
+
90
+
#. Enter the corresponding QR string in ETS when prompted for the device certificate.
91
+
#. Link the switch and status group objects of the sensor and actuator.
92
+
#. In the ETS topology view, right-click each device and select :guilabel:`Download` > :guilabel:`Download All`.
93
+
#. Press **Button 1** to enable programming mode or select an option to program the device via the serial number.
94
+
**LED 1** blinks while programming mode is active.
95
+
You can also enable programming mode from the shell with ``knx_iot pm 1``.
96
+
97
+
After commissioning, **LED 1** remains on.
98
+
Press **Button 2** or **Button 3** on the sensor and verify that the corresponding LED (**LED 2** or **LED 3**) changes state on the actuator.
99
+
100
+
For a local two-board test that does not require ETS or a Thread Commissioner, use the hardcoded KNX and Thread profiles described in the sample documentation.
0 commit comments