doc: add Sidewalk location service information

[KRKNWK-21107]
Add Sidewalk location service doc
including overview, testing and known issues.

Author: ktaborowski

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

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=<wireless-device-id> --transmit-mode 0 --payload-data="<payload-data>" --wireless-metadata "Sidewalk={Seq=<sequence-number>}"
+
+   * ``<wireless-device-id>`` 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.
+
+   * ``<payload-data>`` is base64 encoded.
+   * ``<sequence-number>`` 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] <inf> sid_thread: Message data:
+                                     48 65 6c 6c 6f 20 20 20  53 69 64 65 77 61 6c 6b |Hello    Sidewalk
+                                     21                                               |!

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

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
 *******************************

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

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.