diff --git a/doc/additional_resources.rst b/doc/additional_resources.rst index ee02ff36d1..0786a5b6b0 100644 --- a/doc/additional_resources.rst +++ b/doc/additional_resources.rst @@ -6,15 +6,16 @@ Additional resources For additional Amazon resources, refer to the following list: * `Introduction to Sidewalk`_ -* `Getting Started Guide`_ -* `Protocol Specification`_ -* `Test Specification`_ -* `API Reference`_ -* `Sidewalk Mobile SDK Developer Guide`_ -* `Manufacturing Provisioning`_ -* `AWS Terms of Use`_ -* `Sidewalk Terms of Use`_ -* `Sidewalk Qualification`_ +* `Getting started guide`_ +* `Protocol specification`_ +* `Test specification`_ +* `API reference`_ +* `Sidewalk mobile SDK developer guide`_ +* `Manufacturing provisioning`_ +* `Registering and testing your Sidewalk endpoint`_ +* `AWS terms of use`_ +* `Sidewalk terms of use`_ +* `Sidewalk qualification`_ .. _Introduction to Sidewalk: https://docs.sidewalk.amazon/introduction/ @@ -24,6 +25,7 @@ For additional Amazon resources, refer to the following list: .. _API Reference: https://docs.aws.amazon.com/iot/latest/developerguide/sidewalk-aws-api-reference.html .. _Sidewalk Mobile SDK Developer Guide: https://docs.sidewalk.amazon/mobile-sdk .. _Manufacturing Provisioning: https://docs.sidewalk.amazon/manufacturing/ +.. _Registering and testing your Sidewalk endpoint: https://docs.sidewalk.amazon/provisioning/iot-sidewalk-register-endpoint.html .. _AWS Terms of Use: https://aws.amazon.com/service-terms/ .. _Sidewalk Terms of Use: https://docs.sidewalk.amazon/sidewalk-terms-and-agreements/ .. _Sidewalk Qualification: https://docs.sidewalk.amazon/qualification/ diff --git a/doc/images/TX_thread_state_machine.svg b/doc/images/TX_thread_state_machine.svg new file mode 100644 index 0000000000..b3dce199d3 --- /dev/null +++ b/doc/images/TX_thread_state_machine.svg @@ -0,0 +1,213 @@ + + + + + + + + + + + + + + + + + Infocenter diagram + + + + + + Sheet.2 + Max 750 px + + + + + Max 750 px + + Sheet.3 + Max 700 px + + + + + Max 700 px + + Sheet.4 + + + + Sheet.5 + + + + Rectangle + Init + + + + + + + Init + + Line Arrow.9 + + + + + + + + + + + Rectangle.10 + Notify_Capacity + + + + + + + Notify_Capacity + + Sheet.11 + Time_sync_success + + + + Time_sync_success + + Rectangle.12 + Notify_Data + + + + + + + Notify_Data + + Arced Line Arrow + + + + + + + + + + + Arced Line Arrow.17 + + + + + + + + + + + Sheet.18 + Capacity_success + + + + Capacity_success + + Sheet.19 + Time_sync_fail + + + + Time_sync_fail + + Straight Line + + + + + + + Straight Line.34 + + + + + + + Line Arrow + + + + + + + + + + + Straight Line.36 + + + + + + + Straight Line.37 + + + + + + + Line Arrow.38 + + + + + + + + + + + Sheet.39 + Action_notify + + + + Action_notify + + Sheet.40 + Action_response + + + + Action_response + + diff --git a/doc/images/sidewalk_thread_state_machine.svg b/doc/images/sidewalk_thread_state_machine.svg new file mode 100644 index 0000000000..67ddc91c68 --- /dev/null +++ b/doc/images/sidewalk_thread_state_machine.svg @@ -0,0 +1,414 @@ + + + + + + + + + + + + + + + + + Infocenter diagram + + + + + + + Sheet.1 + Max 750 px + + Sheet.2 + + + + Sheet.3 + + Sheet.4 + + + + Sheet.5 + + Sheet.6 + + + + Sheet.7 + + + + + + + Sheet.8 + + + + + + Max 750 px + + + + Sheet.9 + Max 700 px + + Sheet.10 + + + + Sheet.11 + + Sheet.12 + + + + Sheet.13 + + Sheet.14 + + + + Sheet.15 + + + + + + + Sheet.16 + + + + + + Max 700 px + + + Sheet.17 + + Sheet.18 + + + + Sheet.19 + + Sheet.20 + + + + Sheet.21 + + Sheet.22 + + + + Sheet.23 + + + + + + + + Sheet.24 + + Sheet.25 + + + + Sheet.26 + + Sheet.27 + + + + Sheet.28 + + Sheet.29 + + + + Sheet.30 + + + + + + + + Rectangle + Sidewalk + + + + + + + Sidewalk + + Circle.14 + + + + + + + + + + + + Line Arrow.19 + + Sheet.34 + + + + Sheet.35 + + + + Sheet.36 + + Sheet.37 + + + + Sheet.38 + + Sheet.39 + + + + Sheet.40 + + Sheet.41 + + + + Sheet.42 + + + + + + + + + + + + + + Arced Line Arrow + + Sheet.44 + + + + Sheet.45 + + Sheet.46 + + + + Sheet.47 + + Sheet.48 + + + + Sheet.49 + + Sheet.50 + + + + Sheet.51 + + + + + + + + Sheet.52 + + + + + Rectangle.21 + FirmwareUpdate + + + + + + + FirmwareUpdate + + + + + + + Arced Line Arrow.23 + + Sheet.55 + + + + Sheet.56 + + Sheet.57 + + + + Sheet.58 + + Sheet.59 + + + + Sheet.60 + + Sheet.61 + + + + Sheet.62 + + + + + + + + Sheet.63 + + + + + Sheet.64 + Event_dfu + + + + + Event_dfu + + Sheet.65 + Event_dfu + + + + + Event_dfu + + Sheet.66 + Event_factory_reset + + + + + Event_factory_reset + + Circle.70 + + + + + + + Sheet.71 + Event_factory_reset + + + + + Reset + + Circle.73 + Init + + + + + + + Init + + + + + + + Line Arrow.94 + + Sheet.95 + + + + Sheet.96 + + + + Sheet.97 + + Sheet.98 + + + + Sheet.99 + + Sheet.100 + + + + Sheet.101 + + Sheet.102 + + + + Sheet.103 + + + + + + + + + diff --git a/doc/images/unify_sample_new.svg b/doc/images/unify_sample_new.svg index 45a5085e3b..14a34420e0 100644 --- a/doc/images/unify_sample_new.svg +++ b/doc/images/unify_sample_new.svg @@ -1,4 +1,441 @@ - - - -
demo app
hello app
sidewalk end device
main
cli
ble only
sidewalk
...
app
echo
app
sensor
buttons
buttons
AWS
demo app
AWS
MQTT
 \ No newline at end of file + + + + + + + + + + + + + + + + + Infocenter diagram + + + + + + + Sheet.1 + Max 750 px + + Sheet.2 + + + + Sheet.3 + + Sheet.4 + + + + Sheet.5 + + Sheet.6 + + + + Sheet.7 + + + + + + + Sheet.8 + + + + + + Max 750 px + + + + Sheet.9 + Max 700 px + + Sheet.10 + + + + Sheet.11 + + Sheet.12 + + + + Sheet.13 + + Sheet.14 + + + + Sheet.15 + + + + + + + Sheet.16 + + + + + + Max 700 px + + + Sheet.17 + + Sheet.18 + + + + Sheet.19 + + Sheet.20 + + + + Sheet.21 + + Sheet.22 + + + + Sheet.23 + + + + + + + + Sheet.24 + + Sheet.25 + + + + Sheet.26 + + Sheet.27 + + + + Sheet.28 + + Sheet.29 + + + + Sheet.30 + + + + + + + + Rectangle + AWS sensor monitoring app + + + + + + + AWS sensor monitoring app + + Rectangle.48 + AWS MQTT + + + + + + + AWS MQTT + + Rectangle.53 + + + + + + + Rectangle.54 + + + + + + + Rectangle.55 + + + + + + + Rectangle.56 + app + + + + + + + app + + Rectangle.57 + sensor + + + + + + + sensor + + Rectangle.60 + buttons + + + + + + + buttons + + Rectangle.61 + buttons + + + + + + + buttons + + Sheet.40 + Sensor monitoring app + + + + + Sensor monitoringapp + + Sheet.41 + Sidewalk end device + + + + + Sidewalk end device + + Rectangle.65 + app + + + + + + + app + + Rectangle.66 + echo + + + + + + + echo + + Sheet.44 + Hello Sidewalk app + + + + + Hello Sidewalk app + + Rectangle.68 + main + + + + + + + main + + Rectangle.69 + sidewalk + + + + + + + sidewalk + + Rectangle.70 + cli + + + + + + + cli + + Rectangle.71 + ble only + + + + + + + ble only + + Rectangle.72 + ... + + + + + + + ... + + + + + + + Line Double Arrow + + Sheet.51 + + + + Sheet.52 + + + + Sheet.53 + + + + Sheet.54 + + Sheet.55 + + + + Sheet.56 + + Sheet.57 + + + + Sheet.58 + + Sheet.59 + + + + Sheet.60 + + + + + + + + + + + + + + Line Double Arrow.74 + + Sheet.62 + + + + Sheet.63 + + + + Sheet.64 + + + + Sheet.65 + + Sheet.66 + + + + Sheet.67 + + Sheet.68 + + + + Sheet.69 + + Sheet.70 + + + + Sheet.71 + + + + + + + + + diff --git a/doc/images/unify_sample_old.svg b/doc/images/unify_sample_old.svg index 01c4c621b6..1dafb29da0 100644 --- a/doc/images/unify_sample_old.svg +++ b/doc/images/unify_sample_old.svg @@ -1,4 +1,485 @@ - - - -
template_ble
main
application_thread
sidewalk_callbacks
board_events
template_subghz
main
application_thread
sidewalk_callbacks
board_events
sid_dut
main
sidewalk_thread
shell
sensor monitor
main
tasks
callbacks
buttons and leds
AWS
demo app
AWS
MQTT
 \ No newline at end of file + + + + + + + + + + + + + + + + + Infocenter diagram + + + + + + + Sheet.1 + Max 750 px + + Sheet.2 + + + + Sheet.3 + + + + + Sheet.4 + + + + + + Max 750 px + + + + Sheet.5 + Max 700 px + + Sheet.6 + + + + Sheet.7 + + + + + Sheet.8 + + + + + + Max 700 px + + + Sheet.9 + + Sheet.10 + + + + Sheet.11 + + + + + + Sheet.12 + + Sheet.13 + + + + Sheet.14 + + + + + + Rectangle + AWS sensor monitoring app + + + + + + + AWS sensor monitoring app + + Rectangle.48 + AWS MQTT + + + + + + + AWS MQTT + + Rectangle.54 + + + + + + + Rectangle.61 + main + + + + + + + main + + Sheet.19 + Sensor monitoring app + + + + + Sensor monitoring + + Sheet.20 + Template sub-GHz + + + + + Template sub-GHz + + Sheet.21 + Device under test (DUT) + + + + + Device under test (DUT) + + Rectangle.76 + + + + + + + Rectangle.77 + trasks + + + + + + + trasks + + Rectangle.78 + callbacks + + + + + + + callbacks + + Rectangle.79 + buttons and LEDs + + + + + + + buttons and LEDs + + Rectangle.80 + + + + + + + Rectangle.81 + + + + + + + Sheet.28 + Template Bluetooth LE + + + + + Template Bluetooth LE + + Rectangle.84 + sidewalk_thread + + + + + + + sidewalk_thread + + Rectangle.85 + shell + + + + + + + shell + + Rectangle.86 + main + + + + + + + main + + Rectangle.88 + application_ thread + + + + + + + application_thread + + Rectangle.89 + sidewalk_ callbacks + + + + + + + sidewalk_callbacks + + Rectangle.90 + board_events + + + + + + + board_events + + Rectangle.91 + main + + + + + + + main + + Rectangle.92 + application_ thread + + + + + + + application_thread + + Rectangle.93 + sidewalk_ callbacks + + + + + + + sidewalk_callbacks + + Rectangle.94 + board_events + + + + + + + board_events + + Rectangle.95 + main + + + + + + + main + + + + + + + Line Double Arrow + + Sheet.41 + + + + Sheet.42 + + + + Sheet.43 + + + + Sheet.44 + + Sheet.45 + + + + Sheet.46 + + + + + + + + + + + + Line Double Arrow.97 + + Sheet.48 + + + + Sheet.49 + + + + Sheet.50 + + + + Sheet.51 + + Sheet.52 + + + + Sheet.53 + + + + + + + + + + + + Line Double Arrow.98 + + Sheet.55 + + + + Sheet.56 + + + + Sheet.57 + + + + Sheet.58 + + Sheet.59 + + + + Sheet.60 + + + + + + + + + + + + Line Double Arrow.99 + + Sheet.62 + + + + Sheet.63 + + + + Sheet.64 + + + + Sheet.65 + + Sheet.66 + + + + Sheet.67 + + + + + + + diff --git a/doc/samples/variants/include_building_and_running.txt b/doc/includes/include_building_and_running.txt similarity index 100% rename from doc/samples/variants/include_building_and_running.txt rename to doc/includes/include_building_and_running.txt diff --git a/doc/includes/include_kconfig_common.txt b/doc/includes/include_kconfig_common.txt new file mode 100644 index 0000000000..bc38da42c6 --- /dev/null +++ b/doc/includes/include_kconfig_common.txt @@ -0,0 +1,25 @@ +* ``CONFIG_SIDEWALK`` -- Enables support for the Sidewalk protocol and its dependencies. + +* ``CONFIG_SIDEWALK_SUBGHZ_SUPPORT`` -- Enables using Sidewalk libraries with Bluetooth LE, LoRa and FSK support. + Disabling this option results in using Sidewalk libraries with only Bluetooth LE support. + While this results in a smaller memory footprint for the application, it also limits its functionality, as connectivity over LoRa or FSK is not available. + +* ``CONFIG_SIDEWALK_DFU`` -- Enables the nRF Connect SDK bootloader and DFU service over Bluetooth LE. + +* ``CONFIG_SID_END_DEVICE`` -- Switches between the application variants. + + * ``CONFIG_SID_END_DEVICE_HELLO`` -- Enables the Hello Sidewalk application. + This is the default option. + For more details, see the :ref:`variant_sidewalk_hello` page. + * ``CONFIG_SID_END_DEVICE_SENSOR_MONITORING`` -- Enables the Sidewalk Sensor monitoring application. + For more details, see the :ref:`variant_sensor_monitoring` page. + * ``CONFIG_SID_END_DEVICE_DUT`` -- Enables the Sidewalk device under test application. + For more details, see the :ref:`variant_sidewalk_dut` page. + +* ``CONFIG_SID_END_DEVICE_CLI`` -- Enables Sidewalk CLI. + To see the list of available commands, flash the sample and type ``sid help``. + +* ``CONFIG_SID_END_DEVICE_AUTO_START`` -- Enables an automatic Sidewalk initialization and start. + +* ``CONFIG_SID_END_DEVICE_AUTO_CONN_REQ`` -- Enables an automatic connection request before sending a message. + If needed, the Bluetooth LE connection request is sent automatically. diff --git a/doc/samples/variants/include_testing_nordic_dfu.txt b/doc/includes/include_testing_nordic_dfu.txt similarity index 100% rename from doc/samples/variants/include_testing_nordic_dfu.txt rename to doc/includes/include_testing_nordic_dfu.txt diff --git a/doc/samples/variants/include_user_interface_common.txt b/doc/includes/include_user_interface_common.txt similarity index 100% rename from doc/samples/variants/include_user_interface_common.txt rename to doc/includes/include_user_interface_common.txt diff --git a/doc/migration_guide.rst b/doc/migration_guide.rst index e61d6ca089..827ba25763 100644 --- a/doc/migration_guide.rst +++ b/doc/migration_guide.rst @@ -13,7 +13,7 @@ For an overview of changes, read the following sections. Reasons for change ================== -The samples' model was changed to allow users to easily: +The new sample model allows users to easily: * Adopt new features from the Amazon Sidewalk and nRF Connect SDK. * Maintain samples codebase. @@ -47,12 +47,12 @@ The new approach allows to present the same functionalities through one, unified Aligning your application to the new model ========================================== -To understand how your application might be affected by the new samples' model, see the following list of changes. +To understand how your application might be affected by the new sample model, see the following list of changes. Building -------- -The following table is an example of the new commands used for the `nRF52840 DK`_ with the :file:`{NCS_PATH}/sidewalk/samples` path. +The following table is an example of the new build commands used for the `nRF52840 DK`_ with the :file:`{NCS_PATH}/sidewalk/samples` path. +----------------------------+---------------------------------------------------------+----------------------------------------------------------------------------------------------+ | Sample | Old commands | New commands | @@ -71,7 +71,7 @@ User interface The user interface was changed to better support boards with a smaller amount of buttons and LEDs. -The following table shows button action differences between the old template samples and new :ref:`sidewalk_end_device` application in the :ref:`sidewalk_hello` variant: +The following table shows button action differences between the old template samples and new :ref:`sidewalk_end_device` application in the :ref:`variant_sidewalk_hello` variant: +--------------------------------+--------------------------+-------------------------+ | Button action | Old mapping | New mapping | @@ -93,7 +93,7 @@ The following table shows button action differences between the old template sam | Switch Link Mask | N/A | ``Buttons 3 (long)`` | +--------------------------------+--------------------------+-------------------------+ -The following table shows LED assignment differences between the old template samples and new :ref:`sidewalk_end_device` application in the :ref:`sidewalk_hello` variant: +The following table shows LED assignment differences between the old template samples and new :ref:`sidewalk_end_device` application in the :ref:`variant_sidewalk_hello` variant: +--------------------------------+--------------+--------------+ | LED status | Old | New | @@ -137,7 +137,7 @@ Events ------ In the nRF Connect SDK, you must make all Sidewalk API calls form the same thread where ``sid_process()`` is called. -In case of both old and new samples, communication with the Sidewalk thread was handled by the user-defined events. +In case of both old and new samples, communication with the Sidewalk thread is handled by the user-defined events. To cover all scenarios, the following updates have been made: * Added more events. diff --git a/doc/ncs_links.rst b/doc/ncs_links.rst index 3751450f54..69d1a8f5a3 100644 --- a/doc/ncs_links.rst +++ b/doc/ncs_links.rst @@ -5,8 +5,8 @@ .. _nRF Connect SDK: https://developer.nordicsemi.com/nRF_Connect_SDK/doc/2.5.99-dev1/nrf/index.html .. _nrf52840 DK: https://developer.nordicsemi.com/nRF_Connect_SDK/doc/2.5.99-dev1/nrf/config_and_build/board_support.html#boards-included-in-sdk-zephyr .. _nrf5340 DK: https://developer.nordicsemi.com/nRF_Connect_SDK/doc/2.5.99-dev1/nrf/config_and_build/board_support.html#boards-included-in-sdk-zephyr -.. _Getting started with nRF52 Series: https://developer.nordicsemi.com/nRF_Connect_SDK/doc/2.5.99-dev1/nrf/working_with_nrf/nrf52/gs.html -.. _Getting started with nRF53 Series: https://developer.nordicsemi.com/nRF_Connect_SDK/doc/2.5.99-dev1/nrf/working_with_nrf/nrf53/nrf5340_gs.html +.. _Getting started with nRF52 Series: https://developer.nordicsemi.com/nRF_Connect_SDK/doc/2.5.99-dev1/nrf/device_guides/working_with_nrf/nrf52/gs.html +.. _Getting started with nRF53 Series: https://developer.nordicsemi.com/nRF_Connect_SDK/doc/2.5.99-dev1/nrf/device_guides/nrf53.html .. _Zephyr toolchain: https://developer.nordicsemi.com/nRF_Connect_SDK/doc/2.5.99-dev1/nrf/gs_installing.html#install-a-toolchain .. _nRF Connect SDK Getting started: https://developer.nordicsemi.com/nRF_Connect_SDK/doc/2.5.99-dev1/nrf/getting_started.html .. _nRF52840dk_nrf52840: https://developer.nordicsemi.com/nRF_Connect_SDK/doc/2.5.99-dev1/zephyr/boards/arm/nrf52840dk_nrf52840/doc/index.html diff --git a/doc/ncs_links_update.sh b/doc/ncs_links_update.sh index ab8ca34298..648fca2b45 100755 --- a/doc/ncs_links_update.sh +++ b/doc/ncs_links_update.sh @@ -11,8 +11,8 @@ cd $current_dir links=( ".. _nRF Connect SDK: https://developer.nordicsemi.com/nRF_Connect_SDK/doc//nrf/index.html" ".. _nrf52840 DK: https://developer.nordicsemi.com/nRF_Connect_SDK/doc//nrf/config_and_build/board_support.html#boards-included-in-sdk-zephyr" ".. _nrf5340 DK: https://developer.nordicsemi.com/nRF_Connect_SDK/doc//nrf/config_and_build/board_support.html#boards-included-in-sdk-zephyr" - ".. _Getting started with nRF52 Series: https://developer.nordicsemi.com/nRF_Connect_SDK/doc//nrf/working_with_nrf/nrf52/gs.html" - ".. _Getting started with nRF53 Series: https://developer.nordicsemi.com/nRF_Connect_SDK/doc//nrf/working_with_nrf/nrf53/nrf5340_gs.html" + ".. _Getting started with nRF52 Series: https://developer.nordicsemi.com/nRF_Connect_SDK/doc//nrf/device_guides/working_with_nrf/nrf52/gs.html" + ".. _Getting started with nRF53 Series: https://developer.nordicsemi.com/nRF_Connect_SDK/doc//nrf/device_guides/nrf53.html" ".. _Zephyr toolchain: https://developer.nordicsemi.com/nRF_Connect_SDK/doc//nrf/gs_installing.html#install-a-toolchain" ".. _nRF Connect SDK Getting started: https://developer.nordicsemi.com/nRF_Connect_SDK/doc//nrf/getting_started.html" ".. _nRF52840dk_nrf52840: https://developer.nordicsemi.com/nRF_Connect_SDK/doc//zephyr/boards/arm/nrf52840dk_nrf52840/doc/index.html" diff --git a/doc/samples/samples_list.rst b/doc/samples/samples_list.rst index 34c38cdbba..2ec069c482 100644 --- a/doc/samples/samples_list.rst +++ b/doc/samples/samples_list.rst @@ -5,20 +5,21 @@ Samples overview In the Sidewalk repository, all samples are placed in the :file:`samples` directory. -The following table demonstrates configuration for the supported development kits: - -+-----------------------------+------------------------------------------+-----------------------------+--------------------------------------------------------------------------+-----------------------------------------------+-------------------------------+ -| Sample variant | Description | Development kit | Additional hardware | Bootloader (in release and debug configs) | Application overlays | -+=============================+==========================================+=============================+==========================================================================+===============================================+===============================+ -| :ref:`sidewalk_hello` | Sample application showing communication | * `nRF52840 DK`_ | * External flash (included in the DK) | * MCUboot - DFU partition in external flash | * ``overlay-hello.conf`` | -| | over Sidewalk network. | * `nRF5340 DK`_ | * `Semtech SX1262MB2CAS`_ (only for the configurations with LoRa or FSK) | * Application partition size = 956 kB | | -+-----------------------------+------------------------------------------+-----------------------------+--------------------------------------------------------------------------+-----------------------------------------------+-------------------------------+ -| :ref:`sidewalk_demo` | Demo application of Sidewalk protocol | * `nRF52840 DK`_ | * External flash (included in the DK) | * MCUboot - DFU partition in external flash | * ``overlay-demo.conf`` | -| | with temperature sensor monitoring. | * `nRF5340 DK`_ | * `Semtech SX1262MB2CAS`_ (only for the configurations with LoRa or FSK) | * Application partition size = 956 kB | | -+-----------------------------+------------------------------------------+-----------------------------+--------------------------------------------------------------------------+-----------------------------------------------+-------------------------------+ -| :ref:`sidewalk_dut` | Device under test generic application | * `nRF52840 DK`_ | * External flash (included in the DK) | * MCUboot - DFU partition in external flash | * ``overlay-dut.conf`` | -| | having activated CLI. | * `nRF5340 DK`_ | * `Semtech SX1262MB2CAS`_ (only for the configurations with LoRa or FSK) | * Application partition size = 956 kB | | -+-----------------------------+------------------------------------------+-----------------------------+--------------------------------------------------------------------------+-----------------------------------------------+-------------------------------+ +The current sample structure includes the :ref:`sidewalk_end_device` sample with available variants. +The following table demonstrates the variants' configuration for the supported development kits: + ++-----------------------------------+------------------------------------------+-----------------------------+--------------------------------------------------------------------------+-----------------------------------------------+-------------------------------+ +| Sample variant | Description | Development kit | Additional hardware | Bootloader (in release and debug configs) | Application overlays | ++===================================+==========================================+=============================+==========================================================================+===============================================+===============================+ +| :ref:`variant_sidewalk_hello` | Sample application showing communication | * `nRF52840 DK`_ | * External flash (included in the DK) | * MCUboot - DFU partition in external flash | * ``overlay-hello.conf`` | +| | over Sidewalk network. | * `nRF5340 DK`_ | * `Semtech SX1262MB2CAS`_ (only for the configurations with LoRa or FSK) | * Application partition size = 956 kB | | ++-----------------------------------+------------------------------------------+-----------------------------+--------------------------------------------------------------------------+-----------------------------------------------+-------------------------------+ +| :ref:`variant_sensor_monitoring` | Demo application of Sidewalk protocol | * `nRF52840 DK`_ | * External flash (included in the DK) | * MCUboot - DFU partition in external flash | * ``overlay-demo.conf`` | +| | with temperature sensor monitoring. | * `nRF5340 DK`_ | * `Semtech SX1262MB2CAS`_ (only for the configurations with LoRa or FSK) | * Application partition size = 956 kB | | ++-----------------------------------+------------------------------------------+-----------------------------+--------------------------------------------------------------------------+-----------------------------------------------+-------------------------------+ +| :ref:`variant_sidewalk_dut` | Device under test generic application | * `nRF52840 DK`_ | * External flash (included in the DK) | * MCUboot - DFU partition in external flash | * ``overlay-dut.conf`` | +| | having activated CLI. | * `nRF5340 DK`_ | * `Semtech SX1262MB2CAS`_ (only for the configurations with LoRa or FSK) | * Application partition size = 956 kB | | ++-----------------------------------+------------------------------------------+-----------------------------+--------------------------------------------------------------------------+-----------------------------------------------+-------------------------------+ .. note:: @@ -26,9 +27,9 @@ The following table demonstrates configuration for the supported development kit To see how the changes might affect your application, see the :ref:`migration_guide`. .. toctree:: - :maxdepth: 1 + :maxdepth: 3 :glob: - :caption: List of samples: + :caption: Subpages: sid_end_device.rst diff --git a/doc/samples/sid_end_device.rst b/doc/samples/sid_end_device.rst index 60dd08e12b..afda9a6bf2 100644 --- a/doc/samples/sid_end_device.rst +++ b/doc/samples/sid_end_device.rst @@ -3,9 +3,15 @@ Sidewalk end device ################### +.. contents:: + :local: + :depth: 2 + This sample demonstrates how to implement an end device for the Sidewalk End Device application. -It supports Bluetooth LE, LoRa, and FSK link modes. -External QSPI Flash is used for firmware updates. +It supports Bluetooth® LE, LoRa, and FSK link modes. +It also uses external Quad Serial Peripheral Interface (QSPI) Flash for firmware updates. + +.. _sid_requirements: Requirements ************ @@ -37,73 +43,72 @@ The supported modules are as follows: Overview ******** -You can use this sample as a starting point to implement a Sidewalk device. -The Sidewalk end device demonstrates a simple Sidewalk application that allows you to send and receive messages, as well as update firmware. - -Sample variants -*************** - -Testing application scenarios are different dependent of the Sidewalk configuration was chosen. - -.. toctree:: - :maxdepth: 1 - :glob: - - variants/hello.rst - variants/demo.rst - variants/dut.rst - -.. _sidewalk_end_device_configuration: - -Configuration -************* - -When running the sample, you can use different configuration files depending on the supported features. - -Configuration overlays -====================== +The purpose of the Sidewalk end device sample is to use it as a starting point when implementing a Sidewalk device. +The sample demonstrates a simple Sidewalk application that allows you to send and receive messages, as well as update firmware. +It also has a few variants you can choose from depending on your application needs. -* ``overlay-hello`` -- Configuration for the Hello Sidewalk variant. - It is also a default configuration. -* ``overlay-demo`` -- Configuration for the Sensor monitoring variant. -* ``overlay-dut`` -- Configuration for the Device under test (DUT) variant. - The overlay enables CLI and disables sample automation. +Source file setup +***************** -You can build the end device application with the Sidewalk DUT configuration overlay by running the following command in the project directory: +The application consists of two source files: -.. parsed-literal:: - :class: highlight +* :file:`main.c` -- The main source file. Starts Sidewalk application. +* :file:`app.c` (:file:`app.h`) -- Variant-specific file. + It communicates to the Sidewalk thread using events defined in the :file:`sidewalk.h` file, and receives Sidewalk callbacks defined in the :file:`sid_api.h` file. + An application may consist of multiple ``app_*`` files that are used to define user interface and realize application logic. +* :file:`sidewalk.c` (:file:`sidewalk.h`) -- Sidewalk thread file. + It is a common source file for all sample configurations. + It implements a separate thread that calls the Sidewalk API. + The file also includes support for the DFU state. + The following diagram shows the behavior of the state machine: - $ west build -b *build_target* -- -DOVERLAY_CONFIG="overlay-dut.conf" + .. figure:: ../images/sidewalk_thread_state_machine.svg + :alt: Sidewalk thread state machine -For example: + Sidewalk thread state machine. -.. code-block:: console - $ west build -b nrf52840dk_nrf52840 -- -DOVERLAY_CONFIG="overlay-dut.conf" +.. _sidewalk_end_device_configuration: +Configuration overview +********************** +When running the sample, you can use different configuration files depending on the supported features. Configuration files =================== Configuration files are provided for different build types and are located in the application's root directory. - -The :file:`prj.conf` file represents the ``debug`` build type. -Other build types are covered by dedicated files with the respective build type added to the file name. -For example, the file for the ``release`` build type is named :file:`prj_release.conf`. -The same naming convention is followed if a board has other configuration files that are, for example, associated with the partition layout or child image configuration. +Build types are covered by dedicated files with the respective build type added to the file name. +The same naming convention is followed if a board has other configuration files that are, for example, associated with a partition layout or child image configuration. Before you start testing the application, you can select one of the build types supported by the sample. -Depending on the selected board, a sample supports the following build types: - -* ``debug`` -- Debug version of the application. - It can be used to enable additional features, such as logs or command-line shell, to verify the application behavior. -* ``release`` -- Release version of the application. - It can be used to enable only the necessary application functionalities to optimize its performance. -* ``no_dfu`` -- No DFU version of the application. - It can be used in simple scenarios where DFU is not required. - Additionally, it can be treated as a starting point when integrating the Sidewalk sample with a custom bootloader. +The sample supports the following build types: + +.. list-table:: + :widths: auto + :header-rows: 1 + + * - Build type + - File name + - Supported board + - Description + * - Debug (default) + - :file:`prj.conf` + - All from `Requirements`_ + - Debug version of the application. + It can be used to enable additional features for verifying the application behavior, such as logs or command-line shell. + * - Release + - :file:`prj_release.conf` + - All from `Requirements`_ + - Release version of the application. + It can be used to enable only the necessary application functionalities to optimize its performance. + * - No DFU + - :file:`prj_no_dfu.conf` + - All from `Requirements`_ + - No DFU version of the application. + It can be used in simple scenarios where DFU is not required. + Additionally, it can be treated as a starting point when integrating the Sidewalk sample with a custom bootloader. You can build the ``release`` firmware for ``build_target`` by running the following command in the project directory: @@ -122,93 +127,40 @@ For example: Selecting a build type is optional. However, if the build type is not selected, the ``debug`` build type is used by default. -.. _sidewalk_end_device_config_options: +Selecting a sample variant +************************** -Configuration options for Sidewalk -================================== +You can choose a sample variant depending on your needs. +Testing application scenarios differ depending on the selected Sidewalk configuration: -* ``CONFIG_SIDEWALK`` -- Enables support for the Sidewalk protocol and its dependencies. - -* ``CONFIG_SIDEWALK_SUBGHZ_SUPPORT`` -- Enables use of Sidewalk libraries with Bluetooth LE support only. While this results in a smaller memory footprint for the application, it also limits the functionality (connectivity over LoRa or FSK is not available). - -* ``CONFIG_SIDEWALK_DFU`` -- Enables the nRF Connect SDK bootloader and DFU service over Bluetooth LE. - -* ``CONFIG_SID_END_DEVICE`` -- Switches between the application variants. - - * ``CONFIG_SID_END_DEVICE_HELLO`` -- Enables the Hello Sidewalk application. - This is the default option. - For more details, see the :ref:`sidewalk_hello` page. - * ``CONFIG_SID_END_DEVICE_SENSOR_MONITORING`` -- Enables the Sidewalk Sensor monitoring application. - For more details, see the :ref:`sidewalk_demo` page. - * ``CONFIG_SID_END_DEVICE_DUT`` -- Enables the Sidewalk device under test application. - For more details, see the :ref:`sidewalk_dut` page. - -* ``CONFIG_SID_END_DEVICE_CLI`` -- Enables Sidewalk CLI. - To see the list of available commands, flash the sample and type ``sid help``. - -* ``CONFIG_SID_END_DEVICE_AUTO_START`` -- Enables an automatic Sidewalk initialization and start. - -* ``CONFIG_SID_END_DEVICE_AUTO_CONN_REQ`` -- Enables an automatic connection request before sending a message. - If needed, the Bluetooth LE connection request is sent automatically. +* ``overlay-hello`` -- The default configuration. + Use it to run the Hello Sidewalk variant. +* ``overlay-demo`` -- Use this configuration to run the Sensor monitoring variant. +* ``overlay-dut`` -- Use this configuration to run the Device under test (DUT) variant. + The overlay enables CLI and disables sample automation. -You can build the ``sensor_monitoring`` end device application with Bluetooth LE only libraries by running the following command in the project directory: +You can build an end device application with the selected overlay by running the following command in the project directory: .. parsed-literal:: :class: highlight - $ west build -b *build_target* -- -DCONFIG_SID_END_DEVICE_SENSOR_MONITORING=y -DCONFIG_SIDEWALK_SUBGHZ_SUPPORT=n + $ west build -b *build_target* -- -DOVERLAY_CONFIG="*overlay-name*.conf" -For example: +For example, to build the Sidewalk DUT configuration overlay, run the following command: .. code-block:: console - $ west build -b nrf5340dk_nrf5340_cpuapp -- -DCONFIG_SID_END_DEVICE_SENSOR_MONITORING=y -DCONFIG_SIDEWALK_SUBGHZ_SUPPORT=n - -Source file setup -***************** - -The application consists of two source files: - -* :file:`main.c` -- The main source file. Starts Sidewalk application. -* :file:`app.c` (:file:`app.h`) -- The application specific file. - It communicates to the sidewalk thread using events defined in :file:`sidewalk.h`, and receives Sidewalk callbacks defined in :file:`sid_api.h`. - An application may consist of multiple `app_*` files, to define user interface and realize application logic. -* :file:`sidewalk.c` (:file:`sidewalk.h`) -- Sidewalk thread file. - This is a common source file for all sample configuration. - It implements a separate thread where the Sidewalk API is called. - The file also includes the support for the DFU state. - See the behavior of the state machine outlined in the following diagram: - - .. uml:: - :caption: Sidewalk thread state machine - - [*] --> Sidewalk - Sidewalk --> [*] : event_factory_reset - Sidewalk --> FirmwareUpdate : event_dfu - FirmwareUpdate --> Sidewalk : event_dfu - -.. _registering_sidewalk: - -Registering Sidewalk Endpoint -***************************** - -You can complete Sidewalk registration in one of the two ways: - - * Through an automatic touchless mode that uses Sidewalk Frustration-Free Networking (FFN) where no user interaction is required. - - .. note:: - There are advantages of using automatic FFN registration: - - * There is no association between a user and the Sidewalk Endpoint. - The Endpoint is allowed to connect to network without being associated to any user. - * No Login with Amazon (LWA) is needed. - - * Through a manual process by using a local machine to run a registration script and to connect to the Endpoint over Bluetooth LE. + $ west build -b nrf52840dk_nrf52840 -- -DOVERLAY_CONFIG="overlay-dut.conf" -For the exact instructions on both of these methods, refer to the `Registering and testing your Sidewalk endpoint`_ documentation. +See the details on running and testing individual variants, as well as enabling available Kconfig options: -.. _Registering and testing your Sidewalk endpoint: https://docs.sidewalk.amazon/provisioning/iot-sidewalk-register-endpoint.html +.. toctree:: + :maxdepth: 1 + :glob: + variants/hello.rst + variants/sensor_monitoring.rst + variants/dut.rst .. include:: ../ncs_links.rst .. _SX1262: https://os.mbed.com/components/SX126xMB2xAS/ diff --git a/doc/samples/variants/dut.rst b/doc/samples/variants/dut.rst index 6679ac29e1..c7941c54bb 100644 --- a/doc/samples/variants/dut.rst +++ b/doc/samples/variants/dut.rst @@ -1,27 +1,27 @@ -.. _sidewalk_dut: +.. _variant_sidewalk_dut: -Device Under Test -################# +Device Under Test (DUT) +####################### This sample demonstrates how to use Sidewalk Device Under Test for the testing and evaluation purposes. -Configuration -************* +Configuration options +********************* -.. note:: - To build the Device under test application variant of the Sidewalk end device, use the ``OVERLAY_CONFIG="overlay-dut.conf"`` configuration. +Before building the Device under test application variant of the Sidewalk end device, ensure you have enabled the ``OVERLAY_CONFIG="overlay-dut.conf"`` configuration. -For more configuration option see :ref:`sidewalk_end_device_configuration`. +.. include:: ../../includes/include_kconfig_common.txt Building and running ******************** -.. include:: include_building_and_running.txt +.. include:: ../../includes/include_building_and_running.txt Testing -******* +======= -#. After successfully building and flashing the sample is ready to use. You should see the following command-line prompt: +#. After successfully building and flashing the sample is ready to use. + You should see the following command-line prompt: .. code-block:: console diff --git a/doc/samples/variants/hello.rst b/doc/samples/variants/hello.rst index 9adccef25b..10257195bf 100644 --- a/doc/samples/variants/hello.rst +++ b/doc/samples/variants/hello.rst @@ -1,22 +1,32 @@ -.. _sidewalk_hello: +.. _variant_sidewalk_hello: Hello Sidewalk ############## -This sample demonstrates a simple Sidewalk End Node application. -It can send Hello message to Sidewalk cloud on button press, as well as represent the Sidewalk status by LED state. +This sample demonstrates a simple Sidewalk end node application. +It can send the ``hello`` message to Sidewalk cloud on button press, as well as represent the Sidewalk status through LEDs. + +Configuration options +********************* + +The Hello Sidewalk application variant uses the ``OVERLAY_CONFIG="overlay-hello.conf"`` configuration, which is applied by default. +The sample variant supports the following Kconfig options: + +.. include:: ../../includes/include_kconfig_common.txt + +* ``CONFIG_SID_END_DEVICE_ECHO_MSGS`` -- The sample echoes the received Sidewalk messages (``GET`` and ``SET`` type) to the Sidewalk cloud. .. _sidewalk_hello_user_interface: User Interface ************** -.. include:: include_user_interface_common.txt +.. include:: ../../includes/include_user_interface_common.txt Button 1 (short press): Send Hello - This action queues a message to the cloud. If Sidewalk is not ready, it displays an error without sending the message. - On Bluetooth LE, the application performs Connection Requests before sending. + On Bluetooth LE, the application performs Connection Requests before sending the message. Button 2 (short press): Set Connection Request - The device requests the Sidewalk Gateway to initiate a connection while the device advertises through Bluetooth LE. @@ -27,42 +37,31 @@ Button 3 (short press): A log message informs about the link mask switch and the status of the operation. LED 1: - Application established a link and connected successfully. - It is ready to send and receive Sidewalk messages. + Indicates that the application established a link and connected successfully. + The application is ready to send and receive Sidewalk messages. LED 2: - Application time synced successfully. + Indicates that the application time synced successfully. LED 3: - Application registered successfully. + Indicates that the application registered successfully. LED 4: - Application woke up successfully. - -Configuration -************* - -The hello Sidewalk application supports the following configurations: - -* ``CONFIG_SID_END_DEVICE_ECHO_MSGS`` -- The sample echoes the received Sidewalk messages (``GET`` and ``SET`` type) to the Sidewalk cloud. - -For more configuration options, see :ref:`sidewalk_end_device_configuration`. + Indicates that the application woke up successfully. Building and running ******************** -.. include:: include_building_and_running.txt +.. include:: ../../includes/include_building_and_running.txt Testing -******* +======= See `Testing and debugging an application`_ for information on testing and debugging in the nRF Connect SDK. After successfully building the sample and flashing manufacturing data, the sample is ready to use. To refresh the logs, restart the program by pressing the :guilabel:`RESET` button on your development kit. -Wait for the device to complete the automatic registration. - .. note:: If you have multiple Echo devices registered under a single Amazon account, only one of those devices will be able to operate as an FSK gateway even if other devices have the same capability. If you need to operate multiple FSK gateways, we recommend setting them up under separate Amazon accounts. @@ -73,9 +72,9 @@ Starting Sidewalk To start Sidewalk, do the following: #. Connect your Nordic device to the PC through USB. - Set the power switch on the device to **ON**. + Set the device's power switch to **ON**. -#. Flash the sample application with the manufacturing data as described in the Building and running section of the respective sample. +#. Flash the sample application with the manufacturing data as described in the building and running section of the respective sample. You should see the following logs: @@ -96,7 +95,7 @@ To start Sidewalk, do the following: When Sidewalk sample starts, **LED 4** turns on. -#. Wait for the device to register, or perform registration manually as described in the :ref:`registering_sidewalk` documentation. +#. Wait for the device to complete the registration. You should see the following logs: @@ -117,11 +116,11 @@ To start Sidewalk, do the following: When Sidewalk gets Time Sync, **LED 2** turns on. -#. Wait for status change. +#. Wait for the status change. - a. For a Bluetooth LE device, status change occurs on request. Gateway connects over Bluetooth LE before sending down-link message, and device sends connection request before up-link message. Sidewalk automatically disconnects Bluetooth LE after some inactivity period. + * For a Bluetooth LE device, status change occurs on request. Gateway connects over Bluetooth LE before sending down-link message, and device sends connection request before up-link message. Sidewalk automatically disconnects Bluetooth LE after some inactivity period. - #. For a LoRa and FSK device, the following messages appear in the log: + * For a LoRa and FSK device, the following messages appear in the log: .. code-block:: console @@ -134,7 +133,6 @@ Sending message to AWS MQTT --------------------------- You can use `AWS IoT MQTT client`_ to view the received and republished messages from the device. -Follow the outlined steps: #. Enter ``#`` and click :guilabel:`Subscribe to topic`. You are now subscribed to the republished device messages. @@ -187,12 +185,10 @@ Receiving message from AWS MQTT aws iotwireless send-data-to-wireless-device --id= --transmit-mode 0 --payload-data="" --wireless-metadata "Sidewalk={Seq=}" - * ```` is the Wireless Device ID of your Sidewalk Device. You can find it in the :file:`WirelessDevice.json` file, generated with the :file:`Nordic_MFG.hex` file during :ref:`setting_up_sidewalk_product`. - - You can also find your Wireless Device ID in the message sent form the device to AWS, it you have sent it before. + If you have sent a message before, you can also find your Wireless Device ID in the messages sent from your device to AWS. * ```` is base64 encoded. @@ -223,15 +219,15 @@ Receiving message from AWS MQTT "MessageId": "eabea2c7-a818-4680-8421-7a5fa322460e" } - In case you run into the following error, ensure your IAM user or role has permissions to send data to your wireless device: + * Ensure your IAM user or role has permissions to send data to your wireless device in case you see the following error: - .. code-block:: console + .. code-block:: console - { - "Message": "User: arn:aws:iam::[AWS Account ID]:user/console_user is not authorized to perform: - iotwireless:SendDataToWirelessDevice on resource: arn:aws:iotwireless:us-east-1:[AWS Account ID]: - WirelessDevice/[Wireless Device ID]" - } + { + "Message": "User: arn:aws:iam::[AWS Account ID]:user/console_user is not authorized to perform: + iotwireless:SendDataToWirelessDevice on resource: arn:aws:iotwireless:us-east-1:[AWS Account ID]: + WirelessDevice/[Wireless Device ID]" + } Data will be received in Sidewalk logs: @@ -242,7 +238,7 @@ Receiving message from AWS MQTT 21 |! -.. include:: include_testing_nordic_dfu.txt +.. include:: ../../includes/include_testing_nordic_dfu.txt .. include:: ../../ncs_links.rst .. _SX1262: https://os.mbed.com/components/SX126xMB2xAS/ diff --git a/doc/samples/variants/demo.rst b/doc/samples/variants/sensor_monitoring.rst similarity index 63% rename from doc/samples/variants/demo.rst rename to doc/samples/variants/sensor_monitoring.rst index 00a6195587..fed3e58633 100644 --- a/doc/samples/variants/demo.rst +++ b/doc/samples/variants/sensor_monitoring.rst @@ -1,64 +1,70 @@ -.. _sidewalk_demo: +.. _variant_sensor_monitoring: Sensor monitoring ################# This sample demonstrates how a temperature sensor communicates over the secure Sidewalk network, which is a simple Sidewalk-based IoT use case. It requires an edge device (a sensor). -An application server (cloud backend with web UI) compatible with this sample is provided in `Amazon Sidewalk Sample IoT App`_ repository. +You can find an application server (cloud backend with web UI) compatible with this sample in the `Amazon Sidewalk Sample IoT App`_ repository. +Source file setup +***************** -User Interface -************** +The application consists of two source files: -.. include:: include_user_interface_common.txt +* :file:`app.c` (:file:`app.h`) -- The main application file starts the TX and RX thread, assigns button actions to the buttons on the board, and adds received messages to the received message queue. +* :file:`app_sensor.c`, :file:`app_button.c`, :file:`app_led.c` -- The files implement interface between the hardware and sample application. +* :file:`app_rx.c` (:file:`app.h`) -- RX thread reads messages from the received messages queue, deserializes them, and triggers actions. +* :file:`app_tx.c` (:file:`app.h`) -- TX thread sends messages from the device to cloud. + Depending on the actual state of the device, it sends capability messages or sensor data notifications. -Button 1-4 (short press): - Send button action message - This action works after the application successfully sends capability message. +.. figure:: ../../images/TX_thread_state_machine.svg + :alt: Application TX thread state machine -LED 1-4: - Notify LED action message - This action works after the application successfully sends capability message. + Application TX thread state machine. -Configuration -************* +Configuration options +********************* -.. note:: - To build the Sensor monitoring application variant of the Sidewalk end device, use the ``OVERLAY_CONFIG="overlay-demo.conf"`` configuration. +Before building the Sensor monitoring application variant of the Sidewalk end device, ensure you have enabled the ``OVERLAY_CONFIG="overlay-demo.conf"`` configuration. -The Sidewalk sensor monitoring demo application supports the following configurations: +The sample variant supports the following Kconfig options: + +.. include:: ../../includes/include_kconfig_common.txt * ``CONFIG_SID_END_DEVICE_NOTIFY_DATA_PERIOD_MS`` -- Enables the notify period of the sensor monitoring end device app in milliseconds. -For more configuration options, see :ref:`sidewalk_end_device_configuration`. +You can build the ``sensor_monitoring`` end device application with Bluetooth LE only libraries by running the following command in the project directory: -Source file setup -***************** +.. parsed-literal:: + :class: highlight -The application consists of two source files: + $ west build -b *build_target* -- -DCONFIG_SID_END_DEVICE_SENSOR_MONITORING=y -DCONFIG_SIDEWALK_SUBGHZ_SUPPORT=n -* :file:`app.c` (:file:`app.h`) -- The main application file starts the TX and RX thread, assigns button actions to the board's buttons, and adds received messages to the received message queue. -* :file:`app_sensor.c`, :file:`app_button.c`, :file:`app_led.c` -- The files implement interface between the hardware and sample application. -* :file:`app_rx.c` (:file:`app.h`) -- RX thread reads messages form the received messages queue, deserializes them, and triggers actions. -* :file:`app_tx.c` (:file:`app.h`) -- TX thread sends messages from the device to cloud. - Depending on the actual state of the device, it sends capability messages or sensor data notifications. +For example: + +.. code-block:: console + + $ west build -b nrf5340dk_nrf5340_cpuapp -- -DCONFIG_SID_END_DEVICE_SENSOR_MONITORING=y -DCONFIG_SIDEWALK_SUBGHZ_SUPPORT=n + +User Interface +************** - .. uml:: - :caption: Application TX thread state machine +.. include:: ../../includes/include_user_interface_common.txt - [*] -> Init - Init --> Notify_Capacity : time_syc_success - Notify_Capacity --> Notify_Data : capacity_success - Notify_Data --> Notify_Capacity : time_syc_fail - Notify_Data --> Notify_Data : action_response - Notify_Data --> Notify_Data : action_notify +Button 1-4 (short press): + Send button action message - This action works after the application successfully sends capability message. + +LED 1-4: + Notify LED action message - Works after the application successfully sends capability message. Building and running ******************** -.. include:: include_building_and_running.txt +.. include:: ../../includes/include_building_and_running.txt Testing -******* +======= .. note:: For the full installation guidelines and the application overview, refer to the `Amazon Sidewalk Sample IoT App`_ repository. @@ -85,9 +91,7 @@ You should see the following output: [00:00:00.001,373] application_state: working = true [00:00:00.055,480] sidewalk_app: Sidewalk link switch to BLE -Wait for the device to complete the automatic registration. - -.. include:: include_testing_nordic_dfu.txt +.. include:: ../../includes/include_testing_nordic_dfu.txt .. include:: ../../ncs_links.rst .. _SX1262: https://os.mbed.com/components/SX126xMB2xAS/ diff --git a/doc/setting_up_sidewalk_environment/requirements.rst b/doc/setting_up_sidewalk_environment/requirements.rst index 0cb6469582..6ccd1c5d4c 100644 --- a/doc/setting_up_sidewalk_environment/requirements.rst +++ b/doc/setting_up_sidewalk_environment/requirements.rst @@ -3,6 +3,10 @@ Requirements ############ +.. contents:: + :local: + :depth: 2 + This page outlines the requirements that you need to meet before you start working with the Amazon Sidewalk environment. .. note:: @@ -33,10 +37,9 @@ Ensure you have the following: * A supported Nordic Semiconductor's development kit and, if required, other additional hardware. For the list of the required devices per sample, see :ref:`samples_list`. -* Sidewalk Gateway - - You can use one of the supported `Amazon Sidewalk Gateways`_, for example, `Echo 4th Gen`_. - It is configured with the Alexa App on `iOS`_ or `Android`_ and requires an Amazon account for setup. +* Sidewalk Gateway. + You can use one of the supported `Amazon Sidewalk Gateways`_, for example, `Echo 4th Gen`_. + It is configured with the Alexa App on `iOS`_ or `Android`_ and requires an Amazon account for setup. .. _requirements_memory: @@ -49,41 +52,41 @@ All values are provided in kilobytes (KB). .. tabs:: - .. tab:: `nRF52840 DK`_ - - The following table lists memory requirements for samples running on the `nRF52840 DK`_. - - +-----------------------------------------------------------------------+---------------+-------------------+---------------------+-------------+-------------+ - | Sample | MCUboot ROM | Application ROM | Sidewalk Settings | Total ROM | Total RAM | - +=======================================================================+===============+===================+=====================+=============+=============+ - | :ref:`Sensor monitoring ` (Debug) | 36 | 494 | 28 | 558 | 119 | - +-----------------------------------------------------------------------+---------------+-------------------+---------------------+-------------+-------------+ - | :ref:`End device Bluetooth LE and sub-GHz ` (Debug) | 36 | 494 | 28 | 558 | 109 | - +-----------------------------------------------------------------------+---------------+-------------------+---------------------+-------------+-------------+ - | :ref:`End device Bluetooth LE ` (Debug) | 36 | 409 | 28 | 473 | 89 | - +-----------------------------------------------------------------------+---------------+-------------------+---------------------+-------------+-------------+ - | :ref:`End device Bluetooth LE ` (Release) | 36 | 350 | 28 | 414 | 84 | - +-----------------------------------------------------------------------+---------------+-------------------+---------------------+-------------+-------------+ - | :ref:`End device Bluetooth LE and sub-GHz ` (Release) | 36 | 431 | 28 | 495 | 104 | - +-----------------------------------------------------------------------+---------------+-------------------+---------------------+-------------+-------------+ - - .. tab:: `nRF5340 DK`_ - - The following table lists memory requirements for samples running on the `nRF5340 DK`_. - - +-----------------------------------------------------------------------+---------------+-------------------+---------------------+-------------+-------------+ - | Sample | MCUboot ROM | Application ROM | Sidewalk Settings | Total ROM | Total RAM | - +=======================================================================+===============+===================+=====================+=============+=============+ - | :ref:`Sensor monitoring ` (Debug) | 40 | 430 | 28 | 498 | 109 | - +-----------------------------------------------------------------------+---------------+-------------------+---------------------+-------------+-------------+ - | :ref:`End device Bluetooth LE and sub-GHz ` (Debug) | 40 | 429 | 28 | 497 | 99 | - +-----------------------------------------------------------------------+---------------+-------------------+---------------------+-------------+-------------+ - | :ref:`End device Bluetooth LE ` (Debug) | 40 | 348 | 28 | 416 | 80 | - +-----------------------------------------------------------------------+---------------+-------------------+---------------------+-------------+-------------+ - | :ref:`End device Bluetooth LE ` (Release) | 40 | 286 | 28 | 354 | 75 | - +-----------------------------------------------------------------------+---------------+-------------------+---------------------+-------------+-------------+ - | :ref:`End device Bluetooth LE and sub-GHz ` (Release) | 40 | 364 | 28 | 432 | 94 | - +-----------------------------------------------------------------------+---------------+-------------------+---------------------+-------------+-------------+ + .. tab:: nRF52840 DK + + The following table lists memory requirements for the default variant of the :ref:`Sidewalk_End_device` sample running on the `nRF52840 DK`_. + + +----------------------------------------------------------------------------------+---------------+-------------------+---------------------+-------------+-------------+ + | Sample | MCUboot ROM | Application ROM | Sidewalk Settings | Total ROM | Total RAM | + +==================================================================================+===============+===================+=====================+=============+=============+ + | :ref:`Hello Sidewalk Bluetooth LE and sub-GHz ` (Debug) | 36 | 494 | 28 | 558 | 109 | + +----------------------------------------------------------------------------------+---------------+-------------------+---------------------+-------------+-------------+ + | :ref:`Hello Sidewalk Bluetooth LE ` | 36 | 409 | 28 | 473 | 89 | + | (``CONFIG_SIDEWALK_SUBGHZ_SUPPORT=n``, Debug) | | | | | | + +----------------------------------------------------------------------------------+---------------+-------------------+---------------------+-------------+-------------+ + | :ref:`Hello Sidewalk Bluetooth LE ` | 36 | 350 | 28 | 414 | 84 | + | (``CONFIG_SIDEWALK_SUBGHZ_SUPPORT=n``, Release) | | | | | | + +----------------------------------------------------------------------------------+---------------+-------------------+---------------------+-------------+-------------+ + | :ref:`Hello Sidewalk Bluetooth LE and sub-GHz ` (Release)| 36 | 431 | 28 | 495 | 104 | + +----------------------------------------------------------------------------------+---------------+-------------------+---------------------+-------------+-------------+ + + .. tab:: nRF5340 DK + + The following table lists memory requirements for the default variant of the :ref:`Sidewalk_End_device` sample running on the `nRF5340 DK`_. + + +----------------------------------------------------------------------------------+---------------+-------------------+---------------------+-------------+-------------+ + | Sample | MCUboot ROM | Application ROM | Sidewalk Settings | Total ROM | Total RAM | + +==================================================================================+===============+===================+=====================+=============+=============+ + | :ref:`Hello Sidewalk Bluetooth LE and sub-GHz ` (Debug) | 40 | 429 | 28 | 497 | 99 | + +----------------------------------------------------------------------------------+---------------+-------------------+---------------------+-------------+-------------+ + | :ref:`Hello Sidewalk Bluetooth LE ` | 40 | 348 | 28 | 416 | 80 | + | (``CONFIG_SIDEWALK_SUBGHZ_SUPPORT=n``, Debug) | | | | | | + +----------------------------------------------------------------------------------+---------------+-------------------+---------------------+-------------+-------------+ + | :ref:`Hello Sidewalk Bluetooth LE ` | 40 | 286 | 28 | 354 | 75 | + | (``CONFIG_SIDEWALK_SUBGHZ_SUPPORT=n``, Release) | | | | | | + +----------------------------------------------------------------------------------+---------------+-------------------+---------------------+-------------+-------------+ + | :ref:`Hello Sidewalk Bluetooth LE and sub-GHz ` (Release)| 40 | 364 | 28 | 432 | 94 | + +----------------------------------------------------------------------------------+---------------+-------------------+---------------------+-------------+-------------+ .. include:: ../ncs_links.rst diff --git a/doc/setting_up_sidewalk_environment/setting_up_environment.rst b/doc/setting_up_sidewalk_environment/setting_up_environment.rst index 7efff6728d..8e9b0a5ad6 100644 --- a/doc/setting_up_sidewalk_environment/setting_up_environment.rst +++ b/doc/setting_up_sidewalk_environment/setting_up_environment.rst @@ -1,28 +1,18 @@ -.. _setting_up_the_environment: - -Setting up the Sidewalk environment -################################### - -The documentation will guide you through: - -#. Connecting and setting up your hardware development kit (HDK) to develop and debug embedded applications. -#. Designing your Sidewalk product. -#. Configuring your cloud services and managing your Sidewalk Endpoints. -#. Setting up your Sidewalk Gateway. -#. Provisioning and configuring your Sidewalk Endpoints. -#. Registering and associating with your Sidewalk Endpoints. - -Once completed, you will be able to run a sample application and test it with Sidewalk. - -For the exact steps on setting up your environment, follow the below documentation: - -.. toctree:: - :maxdepth: 1 - :glob: - :caption: Subpages: - - requirements.rst - setting_up_hardware.rst - setting_up_sidewalk_gateway.rst - setting_up_sdk.rst - setting_up_sidewalk_product.rst +.. _setting_up_the_environment: + +Setting up the Sidewalk environment +################################### + +The documentation will guide you through the setup of your Sidewalk environment. +Once completed, you will be able to run a sample application and test it with Sidewalk. + +.. toctree:: + :maxdepth: 1 + :glob: + :caption: Subpages: + + requirements.rst + setting_up_hardware.rst + setting_up_sidewalk_gateway.rst + setting_up_sdk.rst + setting_up_sidewalk_product.rst diff --git a/doc/setting_up_sidewalk_environment/setting_up_hardware.rst b/doc/setting_up_sidewalk_environment/setting_up_hardware.rst index 09b60d8fbc..16a8e55c61 100644 --- a/doc/setting_up_sidewalk_environment/setting_up_hardware.rst +++ b/doc/setting_up_sidewalk_environment/setting_up_hardware.rst @@ -3,6 +3,10 @@ Setting up hardware ################### +.. contents:: + :local: + :depth: 2 + Before setting up the Sidewalk environment, make sure you have correctly set up the required hardware. Development kit diff --git a/doc/setting_up_sidewalk_environment/setting_up_sdk.rst b/doc/setting_up_sidewalk_environment/setting_up_sdk.rst index cafc0e1db1..20fbcf7a03 100644 --- a/doc/setting_up_sidewalk_environment/setting_up_sdk.rst +++ b/doc/setting_up_sidewalk_environment/setting_up_sdk.rst @@ -3,6 +3,10 @@ Setting up the SDK ################## +.. contents:: + :local: + :depth: 2 + See the compatibility between the versions of Amazon Sidewalk and the nRF Connect SDK by referring to the :ref:`compatibility_matrix`. Once confirmed, follow the `Installing the nRF Connect SDK`_ instructions. diff --git a/doc/setting_up_sidewalk_environment/setting_up_sidewalk_product.rst b/doc/setting_up_sidewalk_environment/setting_up_sidewalk_product.rst index 606eaceeb6..3a18f1349b 100644 --- a/doc/setting_up_sidewalk_environment/setting_up_sidewalk_product.rst +++ b/doc/setting_up_sidewalk_environment/setting_up_sidewalk_product.rst @@ -3,45 +3,55 @@ Setting up your Sidewalk product ################################ -To create Sidewalk device follow the Amazon Sidewalk documentation: https://docs.aws.amazon.com/iot/latest/developerguide/sidewalk-gs-workflow.html +.. contents:: + :local: + :depth: 2 -Provisioning generation -*********************** +To correctly set up your Sidewalk device, first you have to onboard it. +Complete the `Onbarding your Sidewalk devices`_ steps described in the Amazon Sidewalk documentation. + +Generate provisioning +********************* -Tools for provisioning are included in the NCS repository in :file:`sidewalk/tools/provision` +The tools required for provisioning are located in the downloaded `sdk-nrf`_ repository under the :file:`sidewalk/tools/provision` path. -Usage of the tool is described at https://docs.sidewalk.amazon/provisioning/iot-sidewalk-provision-endpoint.html +1. Follow the `Provision your Sidewalk endpoint and flash the binary image`_ documentation. -.. note:: - The default address of the mfg.hex in the Amazon instruction is incompatible with NCS applications. - Add '--addr 0xFF000' argument to the provision.py script to generate mfg.hex compatible with NCS memory map. + .. note:: + The default address of the the :file:`mfg.hex` file provided in the official Amazon Sidewalk documentation is incompatible with the nRF Connect SDK applications. + You must add the ``--addr 0xFF000`` argument to the :file:`provision.py` script in order to generate the :file:`mfg.hex` file that is compatible with the nRF Connect SDK memory map. -If you're using the combined device JSON file that you obtained from the AWS IoT console, use the certificate_json parameter to specify this file as input when running the provisioning script. + * If you are using the combined device JSON file obtained from the AWS IoT console, use the ``certificate_json`` parameter. + It will specify this file as an input when running the provisioning script. -python3 provision.py aws --output_bin mfg.bin --certificate_json certificate.json \ - --config config/[device_vendor]/[device]_dk/config.yaml --addr 0xFF000 + .. code-block:: python -If you're using the separate device JSON files that you obtained as responses from the GetDeviceProfile and GetWirelessDevice API operations, use the wireless_device_json and device_profile_json parameters to specify these files as input when running the provisioning script. + python3 provision.py aws --output_bin mfg.bin --certificate_json certificate.json \ + --config config/[device_vendor]/[device]_dk/config.yaml --addr 0xFF000 -python3 provision.py aws --output_bin mfg.bin \ - --wireless_device_json wireless_device.json \ - --device_profile_json device_profile.json \ - --config config/[device_vendor]/[device]_dk/config.yaml --addr 0xFF000 + * If you are using separate device JSON files obtained as responses from the GetDeviceProfile and GetWirelessDevice API operations, use the ``wireless_device_json`` and ``device_profile_json`` parameters. + This will specify both files as input when running the provisioning script. + .. code-block:: python -Flash the generated :file:`nordic_aws_nrf52840.hex` file with the provisioning data: + python3 provision.py aws --output_bin mfg.bin \ + --wireless_device_json wireless_device.json \ + --device_profile_json device_profile.json \ + --config config/[device_vendor]/[device]_dk/config.yaml --addr 0xFF000 - .. code-block:: console + .. note:: + The default name of the :file:`mfg.hex` file generated from the :file:`provision.py` script is :file:`nordic_aws_nrf52840.hex`. + It is, however, compatible with other supported boards. - $ nrfjprog --sectorerase --program nordic_aws_nrf52840.hex --reset +#. Flash the generated :file:`nordic_aws_nrf52840.hex` file with the provisioning data: - .. note:: - If you reflashed the :file:`nordic_aws_nrf52840.hex` file on an already working device, make sure to perform a factory reset (**Button 1** long press) to deregister the previously flashed device. - This will allow you to register a new product (new :file:`nordic_aws_nrf52840.hex`) in the Sidewalk network. + .. code-block:: console - .. note:: - The mfg.hex generated from the provision.py is compatible with all supported boards, even tho the name sugests only nrf52840. + $ nrfjprog --sectorerase --program nordic_aws_nrf52840.hex --reset + * If you reflashed the :file:`nordic_aws_nrf52840.hex` file on an already working device, you need to deregister the previously flashed device. + To do this, perform a factory reset by long pressing **Button 1**. + This will allow you to register a new product (new :file:`nordic_aws_nrf52840.hex`) in the Sidewalk network. Add MQTT to destination *********************** @@ -71,15 +81,18 @@ Add MQTT to destination .. figure:: /images/AWSIoTCoreDestinationTestRole.png -MQTT client -*********** +Use MQTT client +*************** #. Open the MQTT test client. #. Type your MQTT topic in the filter field and click :guilabel:`Subscribe`. .. figure:: /images/AWSIoTCoreMQTT.png +.. _Onbarding your Sidewalk devices: https://docs.aws.amazon.com/iot/latest/developerguide/sidewalk-gs-workflow.html +.. _Provision your Sidewalk endpoint and flash the binary image: https://docs.sidewalk.amazon/provisioning/iot-sidewalk-provision-endpoint.html .. _Amazon Sidewalk Sample IoT App: https://github.com/aws-samples/aws-iot-core-for-amazon-sidewalk-sample-app .. _Amazon Sidewalk IoT Prerequisites: https://github.com/aws-samples/aws-iot-core-for-amazon-sidewalk-sample-app#prerequisites .. _Install virtual environment: https://github.com/aws-samples/aws-iot-core-for-amazon-sidewalk-sample-app#1-install-virtual-environment .. _AWS: https://aws.amazon.com/ +.. _sdk-nrf: https://github.com/nrfconnect/sdk-nrf