diff --git a/doc/includes/include_building_and_running.txt b/doc/includes/include_building_and_running.txt index 974c4ee591..836bc47815 100644 --- a/doc/includes/include_building_and_running.txt +++ b/doc/includes/include_building_and_running.txt @@ -9,26 +9,52 @@ This sample can be found under :file:`samples/sid_end_device`. This step needs to be completed only once. You do not have to repeat it for every sample rebuild. -To build the sample, follow the steps in the `Building and programming an application`_ documentation. +For general instructions on building the sample, follow the steps in the `Building and programming an application`_ documentation. -To build the sample for sub-GHz (LoRa/FSK) operation, use the ``--shield`` option with ``west build``. This configures the correct device tree overlays and pin mappings for the Semtech SX1262 shield, and enables the correct Sidewalk radio configuration. +You can also build the sample with specific configurations: -.. tabs:: +* For Bluetooth LE only operation, use the default build commands. - .. tab:: nrf52840dk/nrf52840 + .. parsed-literal:: + :class: highlight - .. code-block:: console + west build -b *board_target* - west build -b nrf52840dk/nrf52840 --shield semtech_sx1262mb2cas +* For sub-GHz (LoRa and FSK) operation, use the ``--shield`` option with ``west build``. + This configures the correct device tree overlays and pin mappings for the Semtech radio shield, and enables the correct Sidewalk radio configuration. - .. tab:: nrf5340dk/nrf5340/cpuapp + .. tabs:: - .. code-block:: console + .. tab:: nrf52840dk/nrf52840 - west build -b nrf5340dk/nrf5340/cpuapp --shield semtech_sx1262mb2cas + .. code-block:: console - .. tab:: nrf54l15dk/nrf54l15/cpuapp + west build -b nrf52840dk/nrf52840 --shield semtech_sx1262mb2cas - .. code-block:: console + .. tab:: nrf5340dk/nrf5340/cpuapp - west build -b nrf54l15dk/nrf54l15/cpuapp --shield nrf54l15dk_arduino_adapter --shield semtech_sx1262mb2cas + .. code-block:: console + + west build -b nrf5340dk/nrf5340/cpuapp --shield semtech_sx1262mb2cas + + .. tab:: nrf54l15dk/nrf54l15/cpuapp + + .. code-block:: console + + west build -b nrf54l15dk/nrf54l15/cpuapp --shield nrf54l15dk_arduino_adapter --shield semtech_sx1262mb2cas + +* For sub-GHz (LoRa and FSK) operation and location scanning over WiFi and GNSS, use the ``lr1110mb1lcks`` shield. + + .. tabs:: + + .. tab:: nrf52840dk/nrf52840 + + .. code-block:: console + + west build -b nrf52840dk/nrf52840 --shield semtech_lr1110mb1xxs + + .. tab:: nrf54l15dk/nrf54l15/cpuapp + + .. code-block:: console + + west build -b nrf54l15dk/nrf54l15/cpuapp --shield simple_arduino_adapter --shield semtech_lr1110mb1xxs diff --git a/doc/includes/include_testing_receiving_message.txt b/doc/includes/include_testing_receiving_message.txt new file mode 100644 index 0000000000..b6acdd5f9d --- /dev/null +++ b/doc/includes/include_testing_receiving_message.txt @@ -0,0 +1,60 @@ +Receiving message from AWS MQTT +------------------------------- + +#. To be able to use AWS CLI, you must first complete `Installing or updating the latest version of the AWS CLI`_. + +#. Run the following command to send a message to your Sidewalk Endpoint: + + .. code-block:: console + + 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_prototype`. + 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. + * ```` is an integer and should be different for each subsequent request. + +#. Prepare a message payload in the base64 format by running the following command: + + .. code-block:: console + + python -c "import sys,base64;print(base64.b64encode(sys.argv[1].encode('utf-8')).decode('utf-8'))" "Hello Sidewalk!" + SGVsbG8gU2lkZXdhbGsh + +#. Increase a sequence number on every message. + The device will not receive a message with lower or equal sequence number. + + Once you have populated the command with data, it should look similar to the following: + + .. code-block:: console + + aws iotwireless send-data-to-wireless-device --id=5153dd3a-c78f-4e9e-9d8c-3d84fabb8911 --transmit-mode 0 --payload-data="SGVsbG8gU2lkZXdhbGsh" --wireless-metadata "Sidewalk={Seq=1}" + + Successfully sent response should look as follows: + + .. code-block:: console + + { + "MessageId": "eabea2c7-a818-4680-8421-7a5fa322460e" + } + + In case you receive the following error, make sure your IAM user or role has permissions to send data to your wireless device: + + .. 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]" + } + + Data will be received in Sidewalk logs: + + .. code-block:: console + + [00:06:56.338,134] sid_thread: Message data: + 48 65 6c 6c 6f 20 20 20 53 69 64 65 77 61 6c 6b |Hello Sidewalk + 21 |! diff --git a/doc/index.rst b/doc/index.rst index b82aeff1db..fbf0b8f78a 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -43,6 +43,7 @@ Browse the content by referring to the following pages: setting_up_sidewalk_environment/setting_up_environment.rst samples/samples_list.rst + location_services.rst testing.rst compatibility_matrix.rst release_notes_and_migration.rst diff --git a/doc/known_issues.rst b/doc/known_issues.rst index 00a7773870..2a4a054152 100644 --- a/doc/known_issues.rst +++ b/doc/known_issues.rst @@ -22,42 +22,56 @@ A known issue can list one or both of the following entries: List of known issues for v1.1.0 ******************************* -.. warning:: - SDK v1.19 introduces several new issues. Thorough testing is recommended before production use. - -**High Priority Issues:** - KRKNWK-20869: Intermittent downlink message reception issues with multilink configurations When multiple transport types are enabled (multilink), downlink messages from the cloud may not be received by the device. - Sometimes messages arrive via a different transport than expected. Uplink messages work as expected. + Sometimes, messages arrive through a different transport than expected. + Uplink messages work as expected. - - **Affected platforms:** nRF52840, nRF54L15 with LR1110 shield - - **Note:** The exact set of affected platforms that show this behavior is not constant, and reproduction of this issue is not consistent. - - **Impact:** Moderate - affects message reliability in multilink scenarios + **Affected platforms:** nRF52840, nRF54L15 with LR1110 shield (the exact set of affected platforms is not constant, and reproduction is not consistent) -**Lower Priority Issues:** +KRKNWK-20851: Cannot initialize location when LoRa or FSK transport is initialized in Amazon Sidewalk + Device fails to initialize location when using LoRa or FSK transport. + + **Affected platforms:** nRF52840, nRF54L15 with LR1110 shield (issue reproduction is inconsistent) + + **Workaround:** If the device freezes when location initialization fails, restart the device. + Ensure that location services are initialized only after the Sidewalk stack is ready, and deinitialized before Sidewalk stack is deinitialized. KRKNWK-20863: Increased boot time due to bootloader configuration - Boot time increased on all platforms due to recent bootloader configuration changes. - The impact is most noticeable on nRF52840 (~3 seconds vs expected <1 second), but all platforms experience - increased boot time. - - **Root Cause:** The increased boot time is caused by bootloader configuration changes that affect the - initialization sequence across all platforms. - - **Technical Details:** - - **Commit:** `99ed5147cb7543c1f8f9a116da801d3909a92e83` - "use rsa keys for all SoCs" - - **Change:** Sets default config of `BOOT_SIGNATURE_TYPE` to `BOOT_SIGNATURE_TYPE_RSA` - - **Impact:** RSA signature verification is computationally more expensive than the previous default, - causing increased boot time across all platforms - - **Note:** This issue is not related to specific radio configurations (LoRa, BLE, etc.) but affects - the general boot process on all platforms. - - **Affected platforms:** All platforms (most significant impact on nRF52840) + Boot time has increased on all platforms due to bootloader configuration changes. + It now uses RSA keys for signature verification ((the default config of ``BOOT_SIGNATURE_TYPE`` is changed to ``BOOT_SIGNATURE_TYPE_RSA``), significantly increasing the boot time (commit 99ed5147cb7543c1f8f9a116da801d3909a92e83, "use rsa keys for all SoCs"). + The effect is most noticeable on the nRF52840 SoC (around 3 seconds to start up instead of the expected less than 1 second). + This issue is unrelated to specific radio configurations (LoRa, Bluetooth LE) but affects the general boot process. + + **Affected platforms:** All platforms + +KRKNWK-20856: GNSS scan enters endless loop + The GNSS scan operation may enter an endless loop. + Reproduction of the issue is inconsistent. + It does not occur with the location send command. + + **Affected platforms:** nRF52840, nRF54L15 with LR1110 shield + + **Workaround:** Reset device when freezes in endless GNSS loop. + +KRKNWK-20857: Location modem stays busy when scan operation overlaps with deinit + The location modem does not recover if a scan runs concurrently with a deinitialization operation. + + **Affected platforms:** nRF52840, nRF54L15 with LR1110 shield + + **Workaround:** If the location modem stays busy, and cannot perform scan restart the device. + Ensure the location service deinit is triggered when no ongoing scan. + +KRKNWK-21159: Crash in ``sid_location_run`` due to invalid context in Wi-Fi callback + The application may crash if ``sid_location_run`` is called in an invalid context during a Wi-Fi callback. + + **Affected platforms:** nRF52840, nRF54L15 with LR1110 shield + +KRKNWK-21160: Semtech interrupt pin remains high blocking the Wi-Fi scan. + + **Affected platforms:** nRF52840, nRF54L15 with LR1110 shield + + **Workaround:** Clear event pin interrupt in Semtech hal after each occurrence. List of known issues for v1.0.1 ******************************* diff --git a/doc/links.rst b/doc/links.rst index 0b5b16f5e2..cb13f68609 100644 --- a/doc/links.rst +++ b/doc/links.rst @@ -78,10 +78,14 @@ .. _Provision your Sidewalk endpoint and flash the binary image: https://docs.sidewalk.amazon/provisioning/iot-sidewalk-provision-endpoint.html .. _AWS: https://aws.amazon.com/ .. _Setting up a Sidewalk gateway: https://docs.sidewalk.amazon/getting-started/sidewalk-onboard-prereq-gateway.html +.. _Introducing AWS IoT Core Device Location Integration with Amazon Sidewalk: https://aws.amazon.com/blogs/aws/introducing-aws-iot-core-device-location-integration-with-amazon-sidewalk/ +.. _Amazon Sidewalk Location Library Developer Guide: https://docs.sidewalk.amazon/assets/pdf/Amazon_Sidewalk_Location_Library_Developer_Guide-1.0-rev-A.pdf + .. Other links and additional resources .. _SX1262: https://os.mbed.com/components/SX126xMB2xAS/ +.. _LR1110: https://www.semtech.com/products/wireless-rf/lora-edge/lr1110 .. _Semtech SX1262MB2CAS: https://www.semtech.com/products/wireless-rf/lora-transceivers/sx1262mb2cas .. _PICS v2.9.0 - BLE only: https://docs.nordicsemi.com/bundle/Amazon-Sidewalk-Protocol-PICS---BLE-only/resource/Amazon_Sidewalk_Protocol_PICS_-_BLE_only.pdf .. _PICS v2.9.0: https://docs.nordicsemi.com/bundle/Amazon-Sidewalk-Protocol-PICS/resource/Amazon_Sidewalk_Protocol_PICS.pdf diff --git a/doc/location_services.rst b/doc/location_services.rst new file mode 100644 index 0000000000..483d5242c3 --- /dev/null +++ b/doc/location_services.rst @@ -0,0 +1,135 @@ +.. _location_services: + +Location services +################## + +.. contents:: + :local: + :depth: 2 + +The Amazon Sidewalk Location Library provides an API that automatically selects the most power- and time-efficient location mechanism based on available hardware and network conditions. + +Overview +******** + +The Amazon Sidewalk Location Library is available in the Amazon Sidewalk SDK v1.19 and later, and it enables Sidewalk customers to use a range of cloud-based location solvers. +It also provides better control to configure and override the mechanism used to determine location as required. + +Supported Location Methods +=========================== + +The location library supports three types of location resolution methods: + +* Sidewalk Network Location over Bluetooth LE - Uses existing Bluetooth LE connections to determine location through the Sidewalk network. +* Wi-Fi Scan - Scans for nearby Wi-Fi access points and sends MAC addresses to the cloud for location resolution. +* GNSS Scan - Uses Global Navigation Satellite System to collect satellite vehicle data for coordinate resolution. + +These methods are supported on two available link types: + +* Bluetooth LE +* LoRa (Long Range) + +.. note:: + FSK with Wi-Fi and GNSS scanning enabled is not currently supported. + +Wi-Fi and GNSS scanning use the Semtech LoRa Basics Modem middleware to manage and perform scans on the device. + +.. list-table:: Hardware and Library Requirements for Location Methods + :header-rows: 1 + + * - **Location Method** + - **Required Hardware** + - **Supported Sidewalk Library Variants** + * - BLE Location + - nRF chip + - BLE only, or LoRa/FSK + * - Wi-Fi Location + - nRF chip and LR1110 radio + - LoRa and FSK + * - GNSS Location + - nRF chip and LR1110 radio + - LoRa and FSK + +.. note:: + Semtech SX1262 radio does not support Wi-Fi and GNSS scans. + However, you can still use Bluetooth LE location features while using the SX1262 for LoRa and FSK communication. + +Location Levels +=============== + +Location levels are arranged from lowest to highest effort, based on power usage and time required. +The available hardware on the device determines which levels can be used. +If a higher location level fails or times out, the library automatically moves to the next level after a set timeout. + +For more details on integrating device location services with Amazon Sidewalk, refer to the AWS post `Introducing AWS IoT Core Device Location Integration with Amazon Sidewalk`_ + +This article provides guidance on enabling Device Location for Sidewalk devices, configuring geolocation options in AWS IoT Core, and understanding how location data is transmitted and resolved within the AWS ecosystem. + +Level 1: Connected to Sidewalk through BLE +------------------------------------------ + +At this level, the device uses its existing Sidewalk Bluetooth LE connection to resolve location. + +* Power Consumption - No additional power used +* Description - If the device can be located through Bluetooth LE over the Sidewalk network, the device notifies the cloud to resolve the location without extra effort. + If the device is not connected through Bluetooth LE or a location cannot be resolved, the library moves to the next level. + The device’s location is based on the Amazon Hub it is connected to. + +Level 2: Reserved +----------------- + +This level is not yet supported and will default to the next level if reached. + +Level 3: Send Wi-Fi Scan +------------------------ + +At this level, the device tries to find its location using nearby Wi-Fi networks. + +* Power Consumption - Low +* Description - The device scans for nearby Wi-Fi access points and sends the results to the cloud. + It must find at least one access point. + Otherwise, the device will move to the next level. + If the cloud returns a low confidence score or cannot determine the location, the application should proceed to the next level. + +Level 4: Send GNSS Scan +----------------------- + +At this level, the device uses satellite data for location. + +* Power Consumption - Higher power consumption than Wi-Fi scanning +* Description - The device collects and sends GNSS (satellite) data. + At least four satellites must be detected for a valid scan. + +Testing +******* + +The Sidewalk location feature is implemented in the DUT application. +For testing instructions, see :ref:`variant_sidewalk_dut_test_location`. + +Sidewalk libraries +================== + +Location service is supported in Sidewalk libraries in the following range: + +* Sidewalk Sub-GHz library (LoRa and FSK) supports all location methods. + However to build with radio and pal componets for WiFi and GNSS scanning, ``CONFIG_SIDEWALK_SUBGHZ_RADIO_LR1110`` must be enabled. + This config is enabled automatically when sample is build with ``semtech_lr11xxmb1xxs`` shield. + +* Sidewalk Bluetooth LE only library supports only network location method over Bluetooth LE. + +Writing custom application +************************** + +For detailed API documentation and usage guide for developers, refer to the `Amazon Sidewalk Location Library Developer Guide`_. + +.. _location_services_troubleshooting: + +Troubleshooting +*************** + +If you run into problems, the following list includes common issues and their solutions: + +* ``No positioning data in the AWS IoT Core`` - Ensure that positioning is activated for your device in the AWS IoT Core console, and a destination is configured. +* ``Sidewalk not ready`` - Make sure Sidewalk is initialized and started before initializing location services. +* ``Initialization order`` - Always initialize location services after calling ``sid_init()`` and deinitialize before calling ``sid_deinit()``. +* ``BLE location not working`` - Ensure the device is connected to a Sidewalk gateway over Bluetooth LE, and the gateway has location services enabled. diff --git a/doc/releases_and_migration/migration_guide_addon_v110.rst b/doc/releases_and_migration/migration_guide_addon_v110.rst index ca13c49419..a25b549525 100644 --- a/doc/releases_and_migration/migration_guide_addon_v110.rst +++ b/doc/releases_and_migration/migration_guide_addon_v110.rst @@ -8,145 +8,131 @@ This guide assists you in migrating from Amazon Sidewalk Add-On v1.0.x to v1.1.0 Overview ******** -Amazon Sidewalk Add-On v1.1.0 introduces the latest Amazon Sidewalk SDK v1.19 libraries with a new radio architecture based on Zephyr shields for SubGHz radio configuration. +Amazon Sidewalk Add-On v1.1.0 introduces support for the latest Amazon Sidewalk SDK v1.19 and brings several important changes to radio configuration and hardware support. -What's New in v1.1.0 -********************* +Key updates in this release include: -* **Amazon Sidewalk SDK v1.19**: Latest SDK version with new features and API updates -* **New Radio Architecture**: Zephyr shields for SubGHz radio configuration -* **Hardware Abstraction**: Automatic DTS configuration with shield system -* **Performance Regressions**: Boot time increased on some configurations - -Migration Requirements -********************** - -.. note:: - **Recommended:** It is recommended to set all struct fields to known values for better code safety. - New fields in the ``sid_config`` structure should be initialized to NULL to avoid potential issues. +* Upgrading to Amazon Sidewalk SDK v1.19, which adds new features and updates to the API. +* Adopting a new radio architecture that uses Zephyr shields for Sub-GHz radio configuration, simplifying hardware integration. +* Enabling hardware abstraction by automatically configuring device tree settings through the Zephyr shield system. +* Experiencing performance regressions in some configurations, including increased boot time due to changes in the bootloader. Migration Steps *************** -**Step 1: Update your Add-on version** +#. Update your west configuration to use the latest Add-on version: -Update your west configuration to use the latest Add-on version: + .. code-block:: console -.. code-block:: console + west update - west update +#. (Recommended) Update your application code. + Initialize new fields in your ``sid_config`` structure to NULL for better code safety: -**Step 2: Update your application code (RECOMMENDED)** + .. code-block:: c -Initialize new fields in your ``sid_config`` structure to NULL for better code safety: + struct sid_config config = { + .link_mask = persistent_link_mask, + .dev_ch = dev_ch, + .callbacks = &event_callbacks, + .link_config = app_get_ble_config(), + .sub_ghz_link_config = app_get_sub_ghz_config(), + .log_config = NULL, // NEW: Must be set to NULL + .time_sync_config = NULL, // NEW: Must be set to NULL + }; -.. code-block:: c - struct sid_config config = { - .link_mask = persistent_link_mask, - .dev_ch = dev_ch, - .callbacks = &event_callbacks, - .link_config = app_get_ble_config(), - .sub_ghz_link_config = app_get_sub_ghz_config(), - .log_config = NULL, // NEW: Must be set to NULL - .time_sync_config = NULL, // NEW: Must be set to NULL - }; +#. Update build configuration for Sub-GHz support (if applicable). + For applications using SubGHz (LoRa and FSK) radios, use the new shield-based build commands: -**Step 3: Update build configuration for SubGHz support (if applicable)** + .. code-block:: console -For applications using SubGHz (LoRa/FSK) radios, use the new shield-based build commands: + # For SX1262 shield on nRF52840 + west build -b nrf52840dk/nrf52840 samples/sid_end_device --shield simple_arduino_adapter --shield semtech_sx1262mb2cas -.. code-block:: console + # For LR1110 shield on nRF52840 + west build -b nrf52840dk/nrf52840 samples/sid_end_device --shield simple_arduino_adapter --shield semtech_lr1110mb1xxs - # For SX1262 shield on nRF52840 - west build -b nrf52840dk/nrf52840 samples/sid_end_device --shield simple_arduino_adapter --shield semtech_sx1262mb2cas - - # For LR1110 shield on nRF52840 - west build -b nrf52840dk/nrf52840 samples/sid_end_device --shield simple_arduino_adapter --shield semtech_lr1110mb1xxs - - # For SX1262 shield on nRF54L15 - west build -b nrf54l15dk/nrf54l15/cpuapp samples/sid_end_device --shield simple_arduino_adapter --shield semtech_sx1262mb2cas - - # For LR1110 shield on nRF54L15 - west build -b nrf54l15dk/nrf54l15/cpuapp samples/sid_end_device --shield simple_arduino_adapter --shield semtech_lr1110mb1xxs + # For SX1262 shield on nRF54L15 + west build -b nrf54l15dk/nrf54l15/cpuapp samples/sid_end_device --shield simple_arduino_adapter --shield semtech_sx1262mb2cas -**Step 4: Test your application** + # For LR1110 shield on nRF54L15 + west build -b nrf54l15dk/nrf54l15/cpuapp samples/sid_end_device --shield simple_arduino_adapter --shield semtech_lr1110mb1xxs -Thoroughly test your application with the new v1.19 libraries to ensure optimal performance. +#. Test your application with the new v1.19 libraries to ensure optimal performance. New Radio Architecture -*********************** - -The v1.1.0 release introduces a new radio architecture based on Zephyr shields that provides better hardware abstraction and automatic device tree configuration for SubGHz radios. - -**Key Benefits:** +********************** -* **Automatic DTS Configuration**: Shields automatically configure device tree overlays with correct pin mappings -* **Hardware Abstraction**: No need to manually specify GPIO pins or SPI configurations -* **Kconfig Integration**: Shield selection automatically enables the correct radio type in Kconfig -* **Multi-shield Support**: Use multiple shields (e.g., Arduino adapter + radio shield) -* **Simplified Build Process**: Single command builds with automatic configuration +The v1.1.0 release introduces a new radio architecture based on Zephyr shields that provides better hardware abstraction and automatic device tree configuration for Sub-GHz radios: +* Automatic DTS configuration - Shields automatically configure device tree overlays with correct pin mappings. +* Hardware abstraction - No need to manually specify GPIO pins or SPI configurations. +* Kconfig integration - Shield selection automatically enables the correct radio type in Kconfig. +* Multi-shield support - Use multiple shields (for example, Arduino adapter with radio shield). +* Simplified build process - Single command builds with automatic configuration. -**Supported Shields:** +The following shields are supported: -* ``simple_arduino_adapter`` - Arduino header adapter for nRF52840 and nRF54L15 +* ``simple_arduino_adapter`` - Arduino header adapter for nRF52840 and nRF54L15 DK * ``semtech_sx1262mb2cas`` - SX1262 LoRa radio shield * ``semtech_lr1110mb1xxs`` - LR1110 LoRa radio shield -Build Configuration Examples +Build configuration examples **************************** -**BLE-Only Configuration (Minimal Libraries)** -============================================== +The following examples demonstrate how to configure and build the sample for different radio and library combinations. -For applications that only need BLE transport: +Bluetooth LE-Only Configuration (minimal libraries) +=================================================== + +For applications that only need Bluetooth LE transport, run the following command: .. code-block:: console west build -b nrf52840dk/nrf52840 samples/sid_end_device -- -DCONFIG_SID_END_DEVICE_DUT=y -**Resulting Configuration:** +This will result in the following configuration: -* **Libraries**: Minimal BLE-only Sidewalk libraries -* **Transport**: BLE only +* Libraries - Minimal Bluetooth LE-only Sidewalk libraries +* Transport - Bluetooth LE only -**SX1262 Configuration (Full Libraries with LoRa/FSK)** -====================================================== +SX1262 Configuration (Full Libraries with LoRa/FSK) +=================================================== -For applications requiring LoRa and FSK transport with SX1262 radio: +For applications requiring LoRa and FSK transport with SX1262 radio, run the following command: .. code-block:: console west build -b nrf52840dk/nrf52840 samples/sid_end_device --shield simple_arduino_adapter --shield semtech_sx1262mb2cas -**Resulting Configuration:** +This will result in the following configuration: -* **Libraries**: Full Sidewalk libraries (BLE + LoRa + FSK) -* **Transport**: BLE, LoRa, FSK -* **Radio**: SX1262 LoRa transceiver +* Libraries - Full Sidewalk libraries (Bluetooth LE, LoRa, and FSK) +* Transport - Bluetooth LE, LoRa, FSK +* Radio - SX1262 LoRa transceiver -**LR1110 Configuration (Full Libraries)** -========================================= +LR1110 Configuration (Full Libraries) +===================================== -For applications requiring LoRa/FSK transport with LR1110 radio: +For applications requiring LoRa/FSK transport with LR1110 radio, run the following command: .. code-block:: console west build -b nrf52840dk/nrf52840 samples/sid_end_device --shield simple_arduino_adapter --shield semtech_lr1110mb1xxs -**Resulting Configuration:** +This will result in the following configuration: -* **Libraries**: Full Sidewalk libraries (BLE + LoRa + FSK) -* **Transport**: BLE, LoRa, FSK -* **Radio**: LR1110 LoRa transceiver +* Libraries - Full Sidewalk libraries (Bluetooth LE, LoRa, and FSK) +* Transport - Bluetooth LE, LoRa, FSK +* Radio - LR1110 LoRa transceiver -**Library Comparison Summary:** -============================== +Library Comparison Summary: +=========================== +------------------+------------------+------------------+ | Configuration | BLE Libraries | SubGHz Libraries | +==================+==================+==================+ -| BLE-Only | ✓ | ✗ | +| Bluetooth LE-Only| ✓ | ✗ | +------------------+------------------+------------------+ | SX1262 | ✓ | ✓ (LoRa/FSK) | +------------------+------------------+------------------+ @@ -156,106 +142,106 @@ For applications requiring LoRa/FSK transport with LR1110 radio: API Changes for Developers ************************** -This section details the significant API changes between Sidewalk SDK v1.18 and v1.19 that developers need to be aware of when integrating the new version. +This section details significant API changes between Sidewalk SDK v1.18 and v1.19 that you need to be aware of when integrating the new version. -**Enhanced Configuration Structure** -=================================== +Enhanced configuration structure +================================ The ``sid_config`` structure has been enhanced with new optional fields: -**File Path:** ``sidewalk/subsys/sal/common/sid_ifc/sid_api.h`` - -**New Fields Added:** +* File path: ``sidewalk/subsys/sal/common/sid_ifc/sid_api.h`` +* The following, new fields: -* ``const struct sid_diag_log_config *log_config`` - Diagnostic logging configuration -* ``const struct sid_time_sync_config *time_sync_config`` - Time synchronization configuration + * ``const struct sid_diag_log_config *log_config`` - Diagnostic logging configuration + * ``const struct sid_time_sync_config *time_sync_config`` - Time synchronization configuration -**New Supporting Structure:** +* New supporting structure: -* ``struct sid_time_sync_config`` - Adaptive time sync intervals configuration + * ``struct sid_time_sync_config`` - Adaptive time sync intervals configuration -**File Path:** ``sidewalk/subsys/sal/common/sid_ifc/sid_time_sync_config.h`` +* File path: ``sidewalk/subsys/sal/common/sid_ifc/sid_time_sync_config.h`` -**New Configuration Options** -============================ +New configuration options +========================= Two new options have been added to the ``sid_option`` enum: -**File Path:** ``sidewalk/subsys/sal/common/sid_ifc/sid_api.h`` - -**New Options:** +* File path: ``sidewalk/subsys/sal/common/sid_ifc/sid_api.h`` +* Options: -* ``SID_OPTION_DL_ROUTE_VALIDITY = 19`` - Configure downlink route validity settings -* ``SID_OPTION_SUB_GHZ_USER_CONTROL = 20`` - Set user control for SubGHz operations + * ``SID_OPTION_DL_ROUTE_VALIDITY = 19`` - Configure downlink route validity settings + * ``SID_OPTION_SUB_GHZ_USER_CONTROL = 20`` - Set user control for SubGHz operations -**New Supporting Structures:** +* New supporting structures: -* ``struct sid_dlrv_config`` - Downlink route validity configuration -* ``struct sid_link_type_2_gw_discovery_policy_config`` - Gateway discovery policy + * ``struct sid_dlrv_config`` - Downlink route validity configuration + * ``struct sid_link_type_2_gw_discovery_policy_config`` - Gateway discovery policy -**File Path:** ``sidewalk/subsys/sal/common/sid_ifc/sid_900_cfg.h`` +* File path: ``sidewalk/subsys/sal/common/sid_ifc/sid_900_cfg.h`` -**Enhanced Control Events** -=========================== +Enhanced control events +======================= New control event types have been added: -**File Path:** ``sidewalk/subsys/sal/common/sid_ifc/sid_api.h`` +* File path: ``sidewalk/subsys/sal/common/sid_ifc/sid_api.h`` +* New event: ``SID_CONTROL_EVENT_DL_ROUTE_VALIDITY_CONFIG_UPDATE = 3`` (DL route validity configuration changes) -**New Events:** - -* ``SID_CONTROL_EVENT_DL_ROUTE_VALIDITY_CONFIG_UPDATE = 3`` - DL route validity configuration changes +New gateway discovery policies +============================== -**New Gateway Discovery Policies** -================================= +Enhanced gateway discovery options for FSK (Link type 2): -Enhanced gateway discovery options for FSK (Link Type 2): +* File path: ``sidewalk/subsys/sal/common/sid_ifc/sid_900_cfg.h`` -**File Path:** ``sidewalk/subsys/sal/common/sid_ifc/sid_900_cfg.h`` +* New policies: -**New Policies:** + * ``SID_LINK_TYPE_2_GW_DISCOVERY_POLICY_OPTIMIZED_FOR_FAST_CONNECTION = 1`` + * ``SID_LINK_TYPE_2_GW_DISCOVERY_POLICY_OPTIMIZED_FOR_RELIABLE_CONNECTION = 2`` + * ``SID_LINK_TYPE_2_GW_DISCOVERY_POLICY_OPTIMIZED_FOR_POWER_SAVE = 3`` + * ``SID_LINK_TYPE_2_GW_DISCOVERY_POLICY_CUSTOM = 4`` -* ``SID_LINK_TYPE_2_GW_DISCOVERY_POLICY_OPTIMIZED_FOR_FAST_CONNECTION = 1`` -* ``SID_LINK_TYPE_2_GW_DISCOVERY_POLICY_OPTIMIZED_FOR_RELIABLE_CONNECTION = 2`` -* ``SID_LINK_TYPE_2_GW_DISCOVERY_POLICY_OPTIMIZED_FOR_POWER_SAVE = 3`` -* ``SID_LINK_TYPE_2_GW_DISCOVERY_POLICY_CUSTOM = 4`` +Backward compatibility +====================== -**Backward Compatibility** -========================= +The following points outline the backward compatibility considerations when migrating from Sidewalk SDK v1.18 to v1.19. -**API Compatibility:** +* API compatibility: -* All existing function signatures remain unchanged -* Existing data structures are preserved -* All v1.18 code will compile without modification + * All existing function signatures remain unchanged. + * Existing data structures are preserved. + * All v1.18 code will compile without modification. -**Migration Requirements:** +* Migration requirements: -* **Code changes required** - New fields must be explicitly initialized to avoid crashes -* New features are opt-in but require proper initialization to maintain v1.18 behavior + * Code changes required – New fields must be explicitly initialized to avoid crashes. + * New features are opt-in but require proper initialization to maintain v1.18 behavior. -**Integration Notes:** +* Integration notes: -* Time sync configuration is optional (defaults used if not provided) -* New options are backward compatible (can be ignored by existing code) + * Time sync configuration is optional (defaults used if not provided) + * New options are backward compatible (can be ignored by existing code) Troubleshooting *************** -If you encounter issues during migration: +This section provides steps to help resolve common issues that may occur during migration to the new SDK version. -1. **Clean build**: Perform a clean build of your application: +1. Perform a clean build of your application: - .. code-block:: console + .. parsed-literal:: + :class: highlight west build -b *board_target* *your_application* --pristine -2. **Verify dependencies**: Ensure all dependencies are properly updated: +#. Ensure all dependencies are properly updated: .. code-block:: console west update -3. **Check configuration**: Verify that your application configuration is compatible with the new SDK version. +#. Verify that your application configuration is compatible with the new SDK version. + +.. note:: -For additional support, refer to the :ref:`known_issues` page or consult the Amazon Sidewalk documentation. + For additional support, refer to the :ref:`known_issues` page or consult the Amazon Sidewalk documentation. diff --git a/doc/releases_and_migration/release_notes_addon_v110.rst b/doc/releases_and_migration/release_notes_addon_v110.rst index 3b9c0616ec..d2f3eeac88 100644 --- a/doc/releases_and_migration/release_notes_addon_v110.rst +++ b/doc/releases_and_migration/release_notes_addon_v110.rst @@ -13,20 +13,19 @@ Changelog This release introduces the latest Amazon Sidewalk SDK v1.19 libraries. - - * Added: * Latest integration of Amazon Sidewalk v1.19 libraries. - * **LR1110 radio support** as transport for LoRa and FSK. - * **DTS (Device Tree) changes** to accommodate LR1110 radio configuration. - * **New radio architecture** with Zephyr shields for SubGHz radio configuration. - * **Migration guide** for new radio architecture and shield system. + * Support for Sidewalk location service. + * LR1110 radio support as transport for LoRa and FSK. + * New radio architecture with Zephyr shields for Sub-GHz radio configuration. + * Migration guide for new radio architecture and shield system. * Updated: * Amazon Sidewalk MCU SDK from v1.18 to v1.19. - * **Build system** to use Zephyr shields for SubGHz radio configuration. + * Build system to use Zephyr shields for Sub-GHz radio configuration. + * Devicetree to accommodate LR1110 radio configuration. * Fixed: diff --git a/doc/samples/samples_list.rst b/doc/samples/samples_list.rst index 67bfbe4381..4da1ed434d 100644 --- a/doc/samples/samples_list.rst +++ b/doc/samples/samples_list.rst @@ -12,18 +12,18 @@ The following table demonstrates the variants' configuration for the supported d | 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) except `nRF54L15 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 | | +| | over Sidewalk network. | * `nRF5340 DK`_ | * `Semtech SX1262MB2CAS`_ or LR1110MB1xxS (LoRa/FSK only) | * Application partition size = 956 kB | | | | | * `nRF54L15 DK`_ | | | | | | | * nRF54L10 emulating on `nRF54L15 DK`_ | | | | +-----------------------------------+------------------------------------------+-------------------------------------------+---------------------------------------------------------------------------+-----------------------------------------------+---------------------------+ | :ref:`variant_sensor_monitoring` | Demo application of Sidewalk protocol | * `nRF52840 DK`_ | * External flash (included in the DK) except `nRF54L15 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 | | +| | with temperature sensor monitoring. | * `nRF5340 DK`_ | * `Semtech SX1262MB2CAS`_ or LR1110MB1xxS (LoRa/FSK only) | * Application partition size = 956 kB | | | | | * `Thingy53`_ | | | | | | | * `nRF54L15 DK`_ | | | | | | | * nRF54L10 emulating on `nRF54L15 DK`_ | | | | +-----------------------------------+------------------------------------------+-------------------------------------------+---------------------------------------------------------------------------+-----------------------------------------------+---------------------------+ | :ref:`variant_sidewalk_dut` | Device under test generic application | * `nRF52840 DK`_ | * External flash (included in the DK) except `nRF54L15 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 | | +| | having activated CLI. | * `nRF5340 DK`_ | * `Semtech SX1262MB2CAS`_ or LR1110MB1xxS (LoRa/FSK only) | * Application partition size = 956 kB | | | | | * `nRF54L15 DK`_ | | | | | | | * nRF54L10 emulating on `nRF54L15 DK`_ | | | | +-----------------------------------+------------------------------------------+-------------------------------------------+---------------------------------------------------------------------------+-----------------------------------------------+---------------------------+ diff --git a/doc/samples/sid_end_device.rst b/doc/samples/sid_end_device.rst index cf65463f4a..4f005a26a4 100644 --- a/doc/samples/sid_end_device.rst +++ b/doc/samples/sid_end_device.rst @@ -42,6 +42,8 @@ The supported modules are as follows: +============+===============+============+ | `SX1262`_ | SX126xMB2xAS | SPI @ 8Mhz | +------------+---------------+------------+ +| `LR1110`_ | LR1110MB1LCKS | SPI @ 8Mhz | ++------------+---------------+------------+ .. note:: To use sub-GHz radio, the Semtech shield must be connected to the development kit header, and the antenna must be connected to the radio module. diff --git a/doc/samples/variants/dut.rst b/doc/samples/variants/dut.rst index e153794975..751c43a465 100644 --- a/doc/samples/variants/dut.rst +++ b/doc/samples/variants/dut.rst @@ -8,7 +8,7 @@ This sample demonstrates how to use Sidewalk Device Under Test for the testing a Configuration options ********************* -Before building the Device under test application variant of the Sidewalk end device, ensure you have enabled 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. .. include:: ../../includes/include_kconfig_common.txt @@ -20,12 +20,261 @@ Building and running 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 command-line prompt ``uart:~$``. + Rub ``sid help`` to get the list of supported Sidewalk commands. .. code-block:: console - uart$ + uart:~$ sid help -#. To start testing the application, use the Sidewalk CLI (DUT). - Type ``sid help`` and press enter to get the list of supported commands. +#. Initialize Sidewalk in the desired transport mode: + + .. note:: + + To use sub-GHz radio, you need to connect radio over SPI, and build the Sidewalk application with LoRa and FSK library variant. + + a. For Bluetooth LE only mode, run: + + .. code-block:: console + + uart:~$ sid init 1 + + #. For sub-GHz radio, run: + + .. code-block:: console + + uart:~$ sid init 7 + + Use ``2`` for FSK, ``4`` for Bluetooth LE and LoRa, and ``7`` for all transports. + For more available options see ``sid help``. + +#. Start the Sidewalk stack + + .. code-block:: console + + uart:~$ sid start + +#. Wait for Sidewalk to be ready + + .. code-block:: console + + app: Status changed: ready + +#. Send message to cloud. + + You can use `AWS IoT MQTT client`_ to view the received and republished messages from the device. + + #. Enter ``#`` and click :guilabel:`Subscribe to topic`. + You are now subscribed to the republished device messages. + + #. To see the data republished into the subscribed MQTT topic, use the ``send`` command: + + .. code-block:: console + + uart:~$ sid send test_message + app: Message send success + + You should see the message data in the base64 format: + + .. code-block:: json + + { + "MessageId": "4c5dadb3-2762-40fa-9763-8a432c023eb5", + "WirelessDeviceId": "5153dd3a-c78f-4e9e-9d8c-3d84fabb8911", + "PayloadData": "MDA=", + "WirelessMetadata": { + "Sidewalk": { + "CmdExStatus": "COMMAND_EXEC_STATUS_UNSPECIFIED", + "MessageType": "CUSTOM_COMMAND_ID_NOTIFY", + "NackExStatus": [], + "Seq": 2, + "SidewalkId": "BFFFFFFFFF" + } + } + } + + You can use ``last_status`` to check if your device is connected to the cloud. + At least one ``Link status`` must be ``Up``. + + .. code-block:: console + + uart:~$ sid last_status + sid_cli: Device Is registered, Time Sync Success, Link status: {BLE: Up, FSK: Down, LoRa: Down} + sid_cli: Link mode on BLE = {Cloud: True, Mobile: False} + + .. _variant_sidewalk_dut_testing_conn_req: + + #. When operating in Bluetooth LE mode, if Sidewalk is not ready, initiate a Bluetooth LE connection every time you need to send a message. + + .. code-block:: console + + app: Status changed: not ready + app: Device Is registered, Time Sync Success, Link status: {BLE: Down, FSK: Down, LoRa: Down} + uart:~$ sid conn_req 1 + sid_cli: sid_conn_request returned 0 (SID_ERROR_NONE) + sid_ble_conn: BT Connected + app: Status changed: ready + app: Device Is registered, Time Sync Success, Link status: {BLE: Up, FSK: Down, LoRa: Down} + uart:~$ sid send test_message + app: Message send success + +#. Receive message from cloud. + +.. include:: ../../includes/include_testing_receiving_message.txt + +.. _variant_sidewalk_dut_test_location: + +Testing Location Services +========================== + +#. Initialize and start a Sidewalk stack (for example, for Bluetooth LE and LoRa support): + + .. code-block:: console + + uart:~$ sid init 4 + uart:~$ sid start + +#. Initialize location services: + + .. code-block:: console + + uart:~$ location init + location_shell_events: location_event_init returned 0 + + You should see a log message with a success status. + +#. Send the location depending on the protocol used: + + a. For the Bluetooth LE location, check its ``Link status``. + Send ``conn_req`` if Bluetooth LE link is not ``Up``. + + .. code-block:: console + + uart:~$ sid last_status + sid_cli: Device Is registered, Time Sync Success, Link status: {BLE: Down, FSK: Down, LoRa: Down} + uart:~$ sid conn_req 1 + sid_cli: sid_conn_request returned 0 (SID_ERROR_NONE) + sid_ble_conn: BT Connected + app: Status changed: ready + app: Device Is registered, Time Sync Success, Link status: {BLE: Up, FSK: Down, LoRa: Down} + + Send location to cloud based on the current Bluetooth LE connection. + + .. code-block:: console + + uart:~$ location send 1 + location_shell_events: loc send result: 0 + location_shell_events: loc effort mode: 1 + location_shell_events: loc link type: 1 + location_shell_events: location_event_send mode: 1, returned 0 + + #. For Wi-Fi and GNSS location, ensure that the required LR1110 radio hardware is connected. + + .. note:: + + To perform a Wi-Fi or GNSS scan, more time is required. + It may take up to a few minutes to send location data depending on the signal strength. + + Use ``3`` for Wi-Fi and ``4`` for GNSS. + + .. code-block:: console + + uart:~$ location send 3 + sidewalk: mw_wifi_scan_add_task: add task in supervisor at 2393 + 0 s + sidewalk: mw_wifi_scan_service_on_launch + sidewalk: RP: Task #3 enqueue with #11 priority + sidewalk: Enqueued RP task for Wi-Fi scan (hook_id #3) + sidewalk: mw_wifi_scan_service_on_update + location_shell_events: location_event_send mode: 3, returned 0 + sidewalk: sid_pal_hold + sidewalk: INFO: Wi-Fi task launch at 2394270 + sidewalk: + sidewalk: INFO: wifi_rp_task_done at 2396937 (duration:2667 ms) + sidewalk: + sidewalk: Filter and Sort Wi-Fi results: + sidewalk: Raw data: + sidewalk: 1A 2B 3C 4D 5E 6F -- Channel: 1 -- Type: 1 -- RSSI: -86 -- Origin: FIXED + sidewalk: AA BB CC 00 11 22 -- Channel: 1 -- Type: 1 -- RSSI: -92 -- Origin: FIXED + sidewalk: 01 23 45 67 89 AB -- Channel: 6 -- Type: 1 -- RSSI: -90 -- Origin: FIXED + sidewalk: AA BB CC 00 11 22 -- Channel: 6 -- Type: 1 -- RSSI: -82 -- Origin: UNKNOWN + sidewalk: A0 B1 C2 D3 E3 F4 -- Channel: 9 -- Type: 1 -- RSSI: -93 -- Origin: FIXED + sidewalk: 11 AA 22 BB 33 DD -- Channel: 9 -- Type: 1 -- RSSI: -84 -- Origin: FIXED + sidewalk: AB 00 CD 11 EF 22 -- Channel: 9 -- Type: 1 -- RSSI: -86 -- Origin: FIXED + sidewalk: A0 B0 C0 D0 E0 F0 -- Channel: 2 -- Type: 2 -- RSSI: -80 -- Origin: UNKNOWN + sidewalk: + sidewalk: filtered data: + sidewalk: 1A 2B 3C 4D 5E 6F -- Channel: 1 -- Type: 1 -- RSSI: -86 -- Origin: FIXED + sidewalk: AA BB CC 00 11 22 -- Channel: 1 -- Type: 1 -- RSSI: -92 -- Origin: FIXED + sidewalk: 01 23 45 67 89 AB -- Channel: 6 -- Type: 1 -- RSSI: -90 -- Origin: FIXED + sidewalk: A0 B1 C2 D3 E3 F4 -- Channel: 9 -- Type: 1 -- RSSI: -93 -- Origin: FIXED + sidewalk: 11 AA 22 BB 33 DD -- Channel: 9 -- Type: 1 -- RSSI: -84 -- Origin: FIXED + sidewalk: AB 00 CD 11 EF 22 -- Channel: 9 -- Type: 1 -- RSSI: -86 -- Origin: FIXED + sidewalk: + sidewalk: Sorted data: + sidewalk: 11 AA 22 BB 33 DD -- Channel: 9 -- Type: 1 -- RSSI: -84 -- Origin: FIXED + sidewalk: 1A 2B 3C 4D 5E 6F -- Channel: 1 -- Type: 1 -- RSSI: -86 -- Origin: FIXED + sidewalk: AB 00 CD 11 EF 22 -- Channel: 9 -- Type: 1 -- RSSI: -86 -- Origin: FIXED + sidewalk: 01 23 45 67 89 AB -- Channel: 6 -- Type: 1 -- RSSI: -90 -- Origin: FIXED + sidewalk: AA BB CC 00 11 22 -- Channel: 1 -- Type: 1 -- RSSI: -92 -- Origin: FIXED + sidewalk: + sidewalk: Event Received: SMTC_MODEM_EVENT_WIFI_SCAN_DONE + sidewalk: SCAN_DONE info: + sidewalk: -- number of results: 5 + sidewalk: -- power consumption: 8194 nah + sidewalk: -- scan duration: 2905 ms + sidewalk: 11 AA 22 BB 33 DD -- Channel: 9 -- Type: 1 -- RSSI: -84 -- Origin: FIXED + sidewalk: 1A 2B 3C 4D 5E 6F -- Channel: 1 -- Type: 1 -- RSSI: -86 -- Origin: FIXED + sidewalk: AB 00 CD 11 EF 22 -- Channel: 9 -- Type: 1 -- RSSI: -86 -- Origin: FIXED + sidewalk: 01 23 45 67 89 AB -- Channel: 6 -- Type: 1 -- RSSI: -90 -- Origin: FIXED + sidewalk: AA BB CC 00 11 22 -- Channel: 1 -- Type: 1 -- RSSI: -92 -- Origin: FIXED + sidewalk: + sidewalk: Event Received: SMTC_MODEM_EVENT_WIFI_SCAN_DONE + sidewalk: SCAN_DONE info: + sidewalk: -- number of results: 5 + sidewalk: -- power consumption: 8353 nah + sidewalk: -- scan duration: 2667 ms + sidewalk: + sidewalk: mw_wifi_send_add_task: add task in supervisor + sidewalk: mw_wifi_send_add_task: no scan to be sent + sidewalk: Event Received: SMTC_MODEM_EVENT_WIFI_TERMINATED + sidewalk: Calling _app_event_lbm_wifi + location_shell_events: loc send result: 0 + location_shell_events: loc effort mode: 3 + location_shell_events: loc link type: 1 + location_shell_events: loc payload: + location_shell_events: loc payload + da 11 aa 22 bb 33 dd be a0 b0 c0 d0 e0 f0 af ab + 00 cd 11 ef 22 01 23 45 67 89 ab 63 a5 aa bb cc + 00 11 22 + sidewalk: _app_event_lbm_wifi completed + sidewalk: rp_hook_callback task WIFI state RP_TASK_STATE_FINISHED + sidewalk: sid_pal_release + + If you only need to perform a scan without sending your location to the cloud, you can test your location using the ``scan`` command: + + .. code-block:: console + + uart:~$ location scan 3 + + Check the MQTT topic used as Location Destination in `AWS IoT MQTT client`_. + You should see the location data in the following format: + + .. code-block:: json + + { + "coordinates": [ + 13.37607669, + 52.51823043, + 0 + ], + "WirelessDeviceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "type": "Point", + "properties": { + "verticalAccuracy": 0, + "horizontalAccuracy": 100, + "timestamp": "YYYY-MM-DDTHH:MM:SS.ZZZ" + } + } + + If you cannot see the coordinates message, refer to the :ref:`location_services_troubleshooting`. diff --git a/doc/samples/variants/hello.rst b/doc/samples/variants/hello.rst index 48e3457786..4d5c2d49aa 100644 --- a/doc/samples/variants/hello.rst +++ b/doc/samples/variants/hello.rst @@ -348,65 +348,6 @@ Sending message to AWS MQTT .. figure:: /images/Step7-MQTT-Subscribe.png -Receiving message from AWS MQTT -------------------------------- - -#. To be able to use AWS CLI, you must first complete `Installing or updating the latest version of the AWS CLI`_. - -#. Run the following command to send a message to your Sidewalk Endpoint: - - .. code-block:: console - - 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_prototype`. - 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. - * ```` is an integer and should be different for each subsequent request. - -#. Prepare a message payload in the base64 format by running the following command: - - .. code-block:: console - - python -c "import sys,base64;print(base64.b64encode(sys.argv[1].encode('utf-8')).decode('utf-8'))" "Hello Sidewalk!" - SGVsbG8gICBTaWRld2FsayE= - -#. Increase a sequence number on every message. - The device will not receive a message with lower or equal sequence number. - - Once you have populated the command with data, it should look similar to the following: - - .. code-block:: console - - aws iotwireless send-data-to-wireless-device --id=5153dd3a-c78f-4e9e-9d8c-3d84fabb8911 --transmit-mode 0 --payload-data="SGVsbG8gICBTaWRld2FsayE=" --wireless-metadata "Sidewalk={Seq=1}" - - Successfully sent response should look as follows: - - .. code-block:: console - - { - "MessageId": "eabea2c7-a818-4680-8421-7a5fa322460e" - } - - In case you receive the following error, make sure your IAM user or role has permissions to send data to your wireless device: - - .. 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]" - } - - Data will be received in Sidewalk logs: - - .. code-block:: console - - [00:06:56.338,134] sid_thread: Message data: - 48 65 6c 6c 6f 20 20 20 53 69 64 65 77 61 6c 6b |Hello Sidewalk - 21 |! +.. include:: ../../includes/include_testing_receiving_message.txt .. include:: ../../includes/include_testing_nordic_dfu.txt diff --git a/doc/setting_up_sidewalk_environment/setting_up_hardware.rst b/doc/setting_up_sidewalk_environment/setting_up_hardware.rst index a58759dfff..86089e0eaa 100644 --- a/doc/setting_up_sidewalk_environment/setting_up_hardware.rst +++ b/doc/setting_up_sidewalk_environment/setting_up_hardware.rst @@ -21,12 +21,20 @@ Depending on the device, refer to the getting started guide for setup instructio * `Getting started with nRF53 Series`_ * `Getting started with nRF54L Series`_ -Semtech SX1262 -************** +Sub-GHz radio transceivers +************************** Sidewalk samples use sub-GHz radio transceivers to support LoRa and (G)FSK modulation. You will need it to run :ref:`LoRa and FSK applications `. +The following radio shields are supported: + +* Semtech SX1262 - For LoRa and FSK applications +* Semtech LR1110 - For LoRa, FSK, and location services (Wi-Fi and GNSS scanning) + +Semtech SX1262 +============== + For evaluation, use the `Semtech SX1262MB2CAS`_ Arduino Shield. .. figure:: /images/nRF52840-Semtech-SX1262.jpg @@ -132,6 +140,83 @@ Connect the Semtech shield to the Arduino-compatible headers on the development | SPI SCK | P0.3 | +---------------+--------------+ +Semtech LR1110 +============== + +For evaluation, use the Semtech LR1110MB1LCKS Arduino Shield. + +The LR1110 shield supports Wi-Fi and GNSS scanning for location services in addition to LoRa and FSK communication. + +The minimum version of Semtech LR1110 firmware is ``0x0401``. +The version is reported in Sidewalk logs during sub-GHz radio initialization: + +.. code-block:: console + + sidewalk: LR11xx: VER HW 0x22 FW 0x0401 type 1 + +.. _setting_up_hardware_lr1110_pinout: + +Pinout +------ + +Connect the Semtech LR1110 shield to the Arduino-compatible headers on the development kit. + +.. tabs:: + + .. tab:: nRF52840 DK + + Refer to the pinout assignment for the nRF52840 DK: + + +---------------+-------------+ + | LR1110 shield | nRF52840 DK | + +===============+=============+ + | NRESET | P0.3 | + +---------------+-------------+ + | BUSY | P1.11 | + +---------------+-------------+ + | DIO1/Event | P1.13 | + +---------------+-------------+ + | Antenna | P0.26 | + +---------------+-------------+ + | GNSS LNA | P0.29 | + +---------------+-------------+ + | SPI NSS | P1.15 | + +---------------+-------------+ + | SPI MOSI | P1.13 | + +---------------+-------------+ + | SPI MISO | P1.14 | + +---------------+-------------+ + | SPI SCK | P1.15 | + +---------------+-------------+ + + .. tab:: nRF54L15 DK + + The nRF54L15 DK requires the ``simple_arduino_adapter`` shield to connect the LR1110 shield. + + Refer to the pinout assignment for the nRF54L15 DK with Arduino adapter: + + +---------------+-------------+ + | LR1110 shield | nRF54L15 DK | + +===============+=============+ + | NRESET | P2.8 | + +---------------+-------------+ + | BUSY | P2.6 | + +---------------+-------------+ + | DIO1/Event | P1.11 | + +---------------+-------------+ + | Antenna | P2.10 | + +---------------+-------------+ + | GNSS LNA | P1.12 | + +---------------+-------------+ + | SPI NSS | P0.0 | + +---------------+-------------+ + | SPI MOSI | P0.1 | + +---------------+-------------+ + | SPI MISO | P0.2 | + +---------------+-------------+ + | SPI SCK | P0.3 | + +---------------+-------------+ + .. _setting_up_sidewalk_gateway: Sidewalk gateway