Amazon Sidewalk - SoC Location#

The Location sample application leverages the Amazon Sidewalk protocol to connect to the cloud using either BLE or sub-GHz FSK / CSS modulation (after an initial registration phase over BLE, if necessary). The Sidewalk endpoint connects to a gateway, allowing it to exchange data with the AWS cloud. It also integrates the Amazon Location Services support in Amazon Sidewalk. The user interacts to try location features by issuing CLI commands.

Ⓘ INFO Ⓘ: This application can be used with the KG100S module or Sidewalk-supported EFR32 series 2 SoCs with at least 768kB flash size.

⚠ WARNING ⚠: Sub-GHz communication occurs in the 900MHz band, a frequency open in the US but may be restricted in other regions.

Prerequisites#

To successfully interface with Amazon Sidewalk, this example application requires the preparation of cloud (AWS) resources and the addition of device credentials matched to those resources. To perform these tasks and procure access to a Sidewalk gateway, complete the initial software and hardware setup steps described in Getting Started: Prerequisites.

Ⓘ INFO Ⓘ: Make note of the additional sub-GHz considerations discussed in the Silicon Labs Wireless Development Kit section of the hardware prequisites.

Build the Application#

With prerequisites in place, generate the primary application image as described in Getting Started: Create and Compile your Sidewalk Application.

Prepare the Cloud and Endpoint#

Create AWS resources to interface with your endpoint and couple the application image with device-specific credentials by following the steps in Getting Started: Provision your Amazon Sidewalk Device.

Modulation Control#

By default, the Location application will only start on a default radio layer (BLE for most boards). If you wish to change the default radio layer you can modify the SL_SIDEWALK_COMMON_DEFAULT_LINK_TYPE define value in the config/sl_sidewalk_common_config.h file. Possible values are:

Value

Radio Layer

Comment

SL_SIDEWALK_LINK_BLE

BLE

SL_SIDEWALK_LINK_FSK

FSK

SL_SIDEWALK_LINK_CSS

CSS

Registration is not supported on CSS, you first need to register using either BLE or FSK sample app.

On the first boot with CSS modulation, the device will start on either FSK or BLE (depending on device support) to perform registration and switch back to CSS once registration is valid.

⚠ WARNING ⚠: All radio layer might not be supported by the radio board you are using, in which case the unsupported radio layers are slipped while switching. In case of single radio layer support (eg. xG23 family), the switch action is not available.

Interacting with the Endpoint#

Amazon Sidewalk selects the location method with an effort level. Each level is a single method. The cloud resolves the position for every level except L6, which produces measurements on the device after a cloud aiding downlink.

Level

Method

Availability

1

BLE gateway trigger. The cloud resolves the gateway position.

Every location build. Requires the Sidewalk link to be BLE.

2

FSK gateway trigger. The cloud resolves the gateway position.

Every location build. Requires the Sidewalk link to be FSK.

3

Wi-Fi BSSID scan. The cloud resolves the position from an access-point database.

Full location component.

4

GNSS scan. The cloud resolves the position from the scan.

Full location component.

5

LoRa multilateration. The device broadcasts, and the cloud trilaterates from at least three gateways.

Every location build. Requires the Sidewalk link to be CSS.

6

GPS-assist. The device requests a compact ephemeris downlink and then produces pseudoranges.

Full location component. Requires GPS-assist support in the SDK.

Levels 1, 2, and 5 are trigger methods. The device sends a request and the cloud resolves the position. They are available through location_scan_and_send in every location build. Levels 3, 4, and 6 scan on the device and require the full location component. This example includes that component on boards with an LR1110. location_scan_only, location_send_only, and location_alm_start are available only with the full location component.

To see the available commands, enter the following command in the console:

help

The list of available commands is output on the console with the associated help. Following is an extended description of and examples of how to use each command.

Command

Description

Example

location_init

Initialize the location services on the endpoint.

> location_init

location_deinit

Deinitialize the location services on the endpoint.

> location_deinit

location_scan_and_send <effort level>

Starts a location run and sends the result to the cloud. Levels 1, 2, and 5 are available in every location build. Levels 3, 4, and 6 require the full location component.

> location_scan_and_send 2

location_scan_only <effort level>

Requires the full location component. Starts a location run and stores a device-side scan. Accepts levels 3 (Wi-Fi), 4 (GNSS), and 6 (GNSS).

> location_scan_only 4

location_send_only <effort level>

Requires the full location component. Sends the scan stored by the last matching location_scan_only. Accepts levels 3, 4, and 6. The stored scan must be from the same level.

> location_send_only 4

location_alm_start

Requires the full location component. Start the almanac demodulation service to update over satellite (GNSS only)

> location_alm_start

ble_connect

Connect the BLE link to the gateway, this is necessary to send data (BLE only)

> ble_connect

switch_link

Switch between BLE, FSK and CSS modulation (depending on supported radio, switch order is BLE->FSK->CSS)

> switch_link

send

Connects to GW (BLE only) and sends an updated counter value to the cloud

> send

reset

Unregisters the Sidewalk Endpoint

> reset

Interacting with the Cloud#

To use the location services in the cloud, your device must have location enabled in the cloud as well. You can verify this in the AWS IoT Wireless console by opening your Sidewalk device's details page.

To activate the positioning feature:

  1. Click Edit on the device details page.

  2. Scroll down to the Device Position Configuration section.

  3. Under Geolocation, check Activate positioning.

  4. In Position data destination, choose the destination where you want AWS to send the device’s location information.

    • This rule defines how the location payload will be processed in your cloud application.

Make sure to save your changes before leaving the page.

Gain additional insight on the network activity from the cloud perspective by using the techniques described in Getting Started: Interacting with the Cloud.

Report Bugs & Get Support#

You are always encouraged and welcome to ask any questions or report any issues you found to us via Silicon Labs Community.