docs: samples: light switch: initial sample docs#7
Conversation
ArekBalysNordic
left a comment
ArekBalysNordic
left a comment
There was a problem hiding this comment.
Documentation will be able to build after resolving the following problems and rebased with commit with the code, because one Kconfig is missing.
|
@Adam-Maciuga I've provided the fixes above. However, I did it only to check Doc build. Feel free to do it as you want and remove the last commit. The only one commit that should be left here is the one with documentation build workflows. |
ArekBalysNordic
force-pushed
the
docs
branch
4 times, most recently
from
82424e4 to
337e926
Compare
Adam-Maciuga
force-pushed
the
docs
branch
2 times, most recently
from
1cf52c7 to
52cb0f0
Compare
Documentation PreviewThe documentation has been built successfully. You can view the preview here: preview Generated at: Expand to view changed pages
|
|
|
||
| The sample currently works only with hardcoded commissioning enabled (the :kconfig:option:`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 key. | ||
| OSCORE (Object Security for Constrained RESTful Environments) protects KNX IoT messages by encrypting and authenticating them at the application layer. |
There was a problem hiding this comment.
Let's change a bit shortcut introduction:
"...the group object and publisher tables, and a shared group OSCORE (Object Security for Constrained RESTful Environments) key. The OSCORE protects ..."
| The sample currently works only with hardcoded commissioning enabled (the :kconfig:option:`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 key. | ||
| OSCORE (Object Security for Constrained RESTful Environments) 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 `ETS tool <https://www.knx.org/knx-en/for-professionals/software/ets6/>` or a Thread commissioner. |
There was a problem hiding this comment.
This link does not render properly. You have to add it to docs/links.txt and use ref symbol here.
| Indicates the network and KNX service status. | ||
| The LED turns on when the Thread network is up and the KNX service has been published. | ||
|
|
||
| LED 2: |
There was a problem hiding this comment.
Missing description for button 2 that is used to change the light state.
There was a problem hiding this comment.
It is the sensor that changes the light state:
light_switch_sensor/README.rst
Button 2:
Toggles the switch on/off (``soo``) datapoint of the first channel and transmits it to the bound group.
| LED 1: | ||
| Indicates the network and KNX service status. | ||
| The LED turns on when the Thread network is up and the KNX service has been published. | ||
|
|
There was a problem hiding this comment.
Missing description for LED 2 that represents the light state.
There was a problem hiding this comment.
It is the actuator that represents the light state:
light_switch_actuator/README.rst
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.
| The LED turns on 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. |
There was a problem hiding this comment.
Shouldn't this LED be described for the sensor? I think there is no point to represent light state on the actuator
There was a problem hiding this comment.
You got it the other way around, the actuator is the device that does things (turns on lights or other machinery) so its state is represented as this led, while the sensor, senses the environment (for example button state)
Documentation fot the light swich samples Both the sensor and actuator docs are created Signed-off-by: Adam Maciuga <adam.maciuga@nordicsemi.no>
Signed-off-by: Arkadiusz Balys <arkadiusz.balys@nordicsemi.no>
Excluded documentation changes from triggering building samples. Assigned CODEOWNERS to txt and rst files. Signed-off-by: Arkadiusz Balys <arkadiusz.balys@nordicsemi.no>
| Configuration | ||
| ************* | ||
|
|
||
| |config| |
There was a problem hiding this comment.
the 'configure_application' link does not resolve properly but it is outside the scope of this pr
|
|
||
| The sample supports the following development kits: | ||
|
|
||
| .. table-from-sample-yaml:: |
There was a problem hiding this comment.
Also outside of the scope of this pr - 'Hardware platform' should not display as 'Developing with...' but a concrete DK name.
b-gent
left a comment
b-gent
left a comment
There was a problem hiding this comment.
Docs are good, there are small issues in other doc build files but the readmes look very nice.
I will open a comprehensive doc review PR later where I will modify some of the current doc build files but this sample documentation is good to be merged.
4 participants
Added initial docs to both samples.
More details will be added while adding new features
Stack docs will be added in another PR