Skip to main content Link Menu Expand (external link) Document Search Copy Copied

2. Usage Guide

2.1 Getting Started

2.1.1 Compilation Configuration

To enable the location library in your project, the following CMake variable definitions must be set:

set(SID_SDK_CONFIG_ENABLE_LOCATION 1)
set(SID_SDK_CONFIG_ENABLE_WIFI 1)
set(SID_SDK_CONFIG_ENABLE_GNSS 1)
add_compile_definitions(SID_SDK_CONFIG_ENABLE_LOCATION=1)
add_compile_definitions(SID_SDK_CONFIG_ENABLE_WIFI=1)
add_compile_definitions(SID_SDK_CONFIG_ENABLE_GNSS=1)

SID_SDK_CONFIG_ENABLE_LOCATION enables the location library as part of the build. SID_SDK_CONFIG_ENABLE_WIFI and SID_SDK_CONFIG_ENABLE_GNSS are features that can be enabled if available hardware supports WiFi and GNSS scanning.

Additional configurations may be required depending on the build system of the target.

2.1.2 Library Overview

The Amazon Sidewalk Location Library provides a set of APIs for configuring, initializing, and uplinking location data to the cloud. The library follows a two-phase programming model.

2.1.2.1 Initialization

The location library must be initialized using sid_location_init() after sid_init() with the appropriate handle and location configuration.

  • handle: A pointer to the handle returned by sid_init().
  • config: Location configuration structure containing your desired location methods, effort levels, and callback function.

Key configuration fields for the location config:

  • sid_location_type_mask: Specifies which location methods to enable (BLE, WiFi, GNSS).
  • manage_effort: Whether to allow automatic effort level management.
  • max_effort: Maximum effort level the library can use.
  • callbacks.on_update: Your callback function to receive location results including scan payloads in the case of WiFi or GNSS.
  • callbacks.context: Optional user-defined context pointer passed to the callback.
  • stepdowns: Timeout configurations (in milliseconds) for effort level transitions (only applicable if WiFi or GNSS is enabled).
  • fragmentation: Settings for message fragmentation handling. Setting timeout to 0 will result in default.
  • auto_link_pause_resume: When true, automatically pauses Sub-GHz links (Link Type 2 and 3) during GNSS scans to avoid hardware conflicts, and resumes them after scan completion.

2.1.2.2 Setting Up the Location Callback

The on_update callback provides an asynchronous notification of location operation results. This callback must be implemented to handle the outcomes of location scanning and uplink operations.

Parameters:

  • result: Pointer to struct sid_location_result containing operation results.
  • context: User-defined context pointer (optional, can be NULL).

The sid_location_result structure

The result structure contains the following fields:

  • status: Operation status (enum sid_location_status):
    • SID_LOCATION_LVL1_READY: BLE gateway location service is available on current gateway connection after init.
    • SID_LOCATION_LVL1_UNAVAILABLE: BLE gateway location service is not available on current gateway connection after init.
    • SID_LOCATION_SEND_ONLY_DONE: Send-only operation completed.
    • SID_LOCATION_SCAN_ONLY_DONE: Scan-only operation completed.
    • SID_LOCATION_SCAN_AND_SEND_DONE: Scan-and-send operation completed.
    • SID_LOCATION_RESOLVE_MSG_SENT: Resolve location message sent to gateway via sid_put_msg().
    • SID_LOCATION_RESOLVE_MSG_ACK_RECEIVED: Resolve location message ack received from cloud.
    • SID_LOCATION_RESOLVE_MSG_TIMEOUT: Resolve location message send failed or timed out.
  • err: Error code indicating success or failure (sid_error_t).
  • mode: The effort mode used for this operation (enum sid_location_effort_mode).
  • link: The link type used for uplink (enum sid_link_type).
  • payload: Scan data buffer (WiFi or GNSS formatted scan results), max size SID_LOCATION_MAX_PAYLOAD_SIZE (106 bytes).
  • size: Size of the payload data in bytes.
  • raw_gnss_data: Raw GNSS scan data buffer (GNSS only).
  • raw_gnss_data_size: Size of the raw GNSS data in bytes.

Configuring the callback

// Define your callback function
void location_callback(const struct sid_location_result *const result, void *context)
{
    // Handle location operation results
    // Check result->status, result->err, and process result->payload if applicable
}

static struct sid_location_config cfg = {
    .sid_location_type_mask = SID_LOCATION_METHOD_ALL,
    .manage_effort = true,
    .max_effort = SID_LOCATION_EFFORT_L4,
    .callbacks = {
        .on_update = location_callback,
        .context = &app_ctx,  // Optional context pointer
    },
    // ... other configuration fields
};

The function returns SID_ERROR_NONE in case of success.

2.1.2.3 Runtime

Location operations can be executed using sid_location_run() after the Sidewalk loop has been started (sid_start()). This API initiates location scanning and/or uplink operations.

sid_error_t sid_location_run(struct sid_handle *handle,
                             struct sid_location_run_config *config,
                             uint32_t delay_s);

Parameters:

  • handle: A pointer to the handle returned by sid_init().
  • config: Struct containing the configuration for the location request.
  • delay_s: Delay in seconds to start scan (if applicable) and uplink data.

Configuration fields in struct sid_location_run_config:

  • mode: Effort level for this specific operation (enum sid_location_effort_mode).
  • type: Operation type (enum sid_location_run_type):
    • SID_LOCATION_SEND_ONLY: Send-only operation.
    • SID_LOCATION_SCAN_ONLY: Scan-only operation.
    • SID_LOCATION_SCAN_AND_SEND: Combined scan and send operation.
  • buffer: Pointer to buffer for location data (uint8_t *).
  • size: Size of the buffer (size_t).

The function returns SID_ERROR_NONE in case of success. If effort mode is NOT managed, SID_LOCATION_EFFORT_DEFAULT cannot be used for the mode.

2.1.2.4 Managed Effort Mode

The manage_effort configuration field controls whether the location library automatically selects and adjusts the effort level used for location operations.

When manage_effort is true:

  • The application can pass SID_LOCATION_EFFORT_DEFAULT as the mode in sid_location_run(). The library will use its internally tracked effort level.
  • The library starts at SID_LOCATION_EFFORT_L1 and automatically escalates to higher effort levels if the current level is not supported or returns insufficient results.
  • After a successful scan at a higher effort level (L3 or L4), the library starts a stepdown timer. When the timer expires, the effort level is reduced back toward L1 based on the configured stepdowns timeouts.
  • The maximum effort level the library can escalate to is bounded by max_effort.
  • The application can override the maximum allowed effort at runtime using sid_location_set_max_mode(), for example to limit power consumption during low-battery conditions.

When manage_effort is false:

  • The application must specify an explicit effort level (L1, L2, L3, or L4) in every call to sid_location_run(). Passing SID_LOCATION_EFFORT_DEFAULT will return an error.
  • No automatic escalation or stepdown occurs. The library uses exactly the effort level requested.
  • This mode gives the application full control over which location method is used for each operation.

Effort Level Mapping:

  • SID_LOCATION_EFFORT_L1: BLE gateway location trigger (requires opted-in gateway).
  • SID_LOCATION_EFFORT_L2: LoRa location trigger (requires Link Type 3 network sync).
  • SID_LOCATION_EFFORT_L3: WiFi scan and uplink (requires WiFi PAL).
  • SID_LOCATION_EFFORT_L4: GNSS scan and uplink (requires GNSS PAL).

L2 (LoRa location trigger) can be used explicitly by passing SID_LOCATION_EFFORT_L2 to sid_location_run(). During managed effort escalation, L2 is currently skipped and the library transitions directly between L1 and L3.

2.1.2.5 De-Initialization

The location library must be deinitialized using sid_location_deinit() before calling sid_deinit(). The function takes the following parameter:

  • handle: A pointer to the handle returned by sid_init().

The function returns SID_ERROR_NONE in case of success.

For detailed API documentation including function signatures, parameters, return values, and other available APIs, please refer to the Amazon Sidewalk API Developer Guide.

2.2 WiFi and GNSS Location Example (LR1110)

The following example shows how to enable GNSS and WiFi with the location library for use with the LR1110 shield.

2.2.1 Example Platform Configuration 

// file: app_location_lr11xx_config.h
#include <lr11xx_gnss_wifi_config.h>
const lr11xx_gnss_wifi_config_t *get_location_cfg(void);

The GNSS configuration supports two key parameters:

Constellation Type:

  • SMTC_MODEM_GNSS_CONSTELLATION_GPS — Use GPS only constellation.
  • SMTC_MODEM_GNSS_CONSTELLATION_BEIDOU — Use BEIDOU only constellation.
  • SMTC_MODEM_GNSS_CONSTELLATION_GPS_BEIDOU — Use both GPS and BEIDOU constellations.

Scan Mode:

  • SMTC_MODEM_GNSS_MODE_STATIC — Scanning mode for non-moving objects.
  • SMTC_MODEM_GNSS_MODE_MOBILE — Scanning mode for moving objects.
// file: app_location_lr11xx_config.c
static lr11xx_gnss_wifi_config_t gnss_wifi_config = {
    .constellation_type = SMTC_MODEM_GNSS_CONSTELLATION_GPS_BEIDOU,
    .scan_mode = SMTC_MODEM_GNSS_MODE_MOBILE
};

const lr11xx_gnss_wifi_config_t *get_location_cfg(void)
{
    return &gnss_wifi_config;
}

// Platform parameters setup
platform_parameters_t platform_parameters = {
    .mfg_store_region = sid_mfg_config_get(),
    .platform_init_parameters.radio_cfg =
        (radio_lr11xx_device_config_t *)get_radio_cfg(),
    .platform_init_parameters.gnss_wifi_cfg =
        (lr11xx_gnss_wifi_config_t *)get_location_cfg(),
};

2.2.2 Location Library Usage 

// Create a location config with user supplied callback
void location_callback(const struct sid_location_result *const result, void *context)
{
    // User can pull the payload for WiFi or GNSS in result->payload
    // Handle different location methods based on result->mode
}

static struct sid_location_config cfg = {
    .sid_location_type_mask = SID_LOCATION_METHOD_ALL,
    .manage_effort = true,
    .max_effort = SID_LOCATION_EFFORT_L4,
    .callbacks = {
        .on_update = location_callback,
        .context = NULL,
    },
    .stepdowns = {  // Timeout (ms) to use before stepping down location level when using managed effort mode.
        .l2_to_l1 = 0,
        .l3_to_l2 = 0,
        .l4_to_l3 = 0,
    },
    .fragmentation = {  // Fragmentation configurations to use for location payload uplinks
        .timeout_ms = 0,  // 0 indicates use default timeout value
        .max_retries = 1,
    },
    .auto_link_pause_resume = true,  // Pause Sub-1 GHz links during GNSS scans
};

// Initialize after sid_init()
sid_error_t res = sid_location_init(*app_context->sidewalk_handle, &cfg);

// WiFi scan and send uplink
struct sid_location_run_config config = {
    .type = SID_LOCATION_SCAN_AND_SEND,
    .mode = SID_LOCATION_EFFORT_L3
};
sid_error_t res = sid_location_run(*app_context->sidewalk_handle, &config, 0);

// GNSS scan and send uplink
config.mode = SID_LOCATION_EFFORT_L4;
sid_error_t res = sid_location_run(*app_context->sidewalk_handle, &config, 0);

2.2.3 Fragmentation Timeout Configuration

If configuring the fragmentation timeout, the timeout_ms parameter should be considered carefully. The current cloud implementation calculates the timeout based on the total message fragmentation requirements and link type characteristics.

The timeout will be calculated automatically if set to 0 and follows the following formula that mirrors the cloud algorithm to wait/reassemble fragments:

timeout = (total_size / MTU) × link_type_duration × 2

Where:

  • total_size / MTU determines the number of fragments required.
  • link_type_duration is the maximum time the specified link type can take to uplink one fragment.
  • The factor of 2 provides additional margin for retries to reach the cloud.

Current supported link type durations:

  • LoRa: Up to 5 seconds per fragment.
  • BLE: BLE does not utilize fragmentation for location as the MTU is large enough. These configurations will not apply.

For example, a message requiring 4 fragments over LoRa would be: 4 × 5000 × 2 = 40000 milliseconds timeout at the cloud. Consider setting timeout_ms appropriately based on your expected use case. Using a timeout independent from the cloud fragmentation timeout may be desirable based on the use case.

2.3 BLE-Only Location Example

The following example shows how to use the location library with just Sidewalk Network Location over BLE.

// Create a location config with user supplied callback
void location_callback(const struct sid_location_result *const result, void *context)
{
    // User can get the results of the uplink here
    // Handle the location result based on status
}

static struct sid_location_config cfg = {
    .sid_location_type_mask = SID_LOCATION_METHOD_BLE_GATEWAY,
    .manage_effort = true,
    .max_effort = SID_LOCATION_EFFORT_L1,
    .callbacks = {
        .on_update = location_callback,
        .context = NULL,
    },
    .stepdowns = {  // Stepdowns are not applicable in the BLE-Only mode.
        .l2_to_l1 = 0,
        .l3_to_l2 = 0,
        .l4_to_l3 = 0,
    },
    .fragmentation = {  // Fragmentation is not applicable in the BLE-Only mode.
        .timeout_ms = 0,
        .max_retries = 0,
    },
    .auto_link_pause_resume = false,  // Not applicable for BLE-only mode
};

// Initialize after sid_init()
sid_error_t res = sid_location_init(*app_context->sidewalk_handle, &cfg);

// Send location request after sid_start()
// (requires BLE connection to opted-in gateway)
struct sid_location_run_config config = {
    .type = SID_LOCATION_SCAN_AND_SEND,
    .mode = SID_LOCATION_EFFORT_DEFAULT
};
sid_error_t res = sid_location_run(*app_context->sidewalk_handle, &config, 0);

2.4 LoRa Location Example

The following example shows how to use the location library to send a LoRa location trigger (Level 2). This requires Link Type 3 to be enabled and network synced.

void location_callback(const struct sid_location_result *const result, void *context)
{
    // result->mode will be SID_LOCATION_EFFORT_L2 for LoRa triggers
    // result->link will be SID_LINK_TYPE_3
}

static struct sid_location_config cfg = {
    .sid_location_type_mask = SID_LOCATION_METHOD_BLE_GATEWAY,  // L1 and L2 do not require WiFi or GNSS
    .manage_effort = false,  // Use explicit effort level
    .max_effort = SID_LOCATION_EFFORT_L2,
    .callbacks = {
        .on_update = location_callback,
        .context = NULL,
    },
    .stepdowns = {0},
    .fragmentation = {0},
    .auto_link_pause_resume = false,
};

// Initialize after sid_init()
sid_error_t res = sid_location_init(*app_context->sidewalk_handle, &cfg);

// Send LoRa location trigger after sid_start()
// (requires LoRa link to be network synced)
struct sid_location_run_config config = {
    .type = SID_LOCATION_SEND_ONLY,
    .mode = SID_LOCATION_EFFORT_L2
};
sid_error_t res = sid_location_run(*app_context->sidewalk_handle, &config, 0);

2.5 Platform Abstraction Layers

If the device supports WiFi and GNSS scanning (levels 3 and 4), the WiFi and GNSS Platform Abstraction Layers (PALs) must be implemented and linked. Reference implementations are provided that utilize the Semtech LoRa Basics Modem middleware APIs.

The implementation available in the Sidewalk MCU SDK combines both WiFi and GNSS PALs as they interface with the LoRa Basics Modem and utilize shared resources.

2.6 Best Practices

  • Use sid_location_set_max_mode() to limit power consumption during low-power modes.
  • Configure appropriate stepdown timeouts based on your application requirements.
  • Always check return values from location API functions.
  • Handle different status codes in your callback function appropriately.
  • Allow the library to manage effort levels automatically when possible.
  • Consider using scan-only operations when immediate uplink is not required.

2.7 Location Resolve via sid_put_msg

In addition to the explicit location APIs (sid_location_run()), the location library supports requesting location resolution as part of a user message sent via sid_put_msg(). This is done by setting the resolve_location field in the message descriptor’s TX attributes.

When resolve_location is set to true, the Sidewalk stack includes a location resolve request with the user’s message. The gateway uses this to resolve the device’s location based on its own known position. This works on both BLE and LoRa links.

2.7.1 Prerequisites

  • SID_SDK_CONFIG_ENABLE_LOCATION must be enabled at compile time.
  • sid_location_init() must have been called successfully.
  • The Sidewalk stack must be in SID_STATE_READY state.

2.7.2 Usage 

// Location callback handles both explicit location and resolve_location events
void location_callback(const struct sid_location_result *const result, void *context)
{
    switch (result->status) {
    case SID_LOCATION_RESOLVE_MSG_SENT:
        // Message with location resolve request sent to gateway
        break;
    case SID_LOCATION_RESOLVE_MSG_ACK_RECEIVED:
        // Transport ack received from cloud (only if request_ack was set)
        break;
    case SID_LOCATION_RESOLVE_MSG_TIMEOUT:
        // Message send failed or timed out
        break;
    default:
        // Handle other location statuses (L1 ready, scan done, etc.)
        break;
    }
}

// Initialize location library with callback
static struct sid_location_config loc_cfg = {
    .sid_location_type_mask = SID_LOCATION_METHOD_BLE_GATEWAY,
    .manage_effort = true,
    .max_effort = SID_LOCATION_EFFORT_L1,
    .callbacks = {
        .on_update = location_callback,
    },
};
sid_location_init(handle, &loc_cfg);

// Send a message with location resolve request
struct sid_msg msg = {
    .data = payload_data,
    .size = payload_size,
};
struct sid_msg_desc desc = {
    .type = SID_MSG_TYPE_NOTIFY,
    .link_type = SID_LINK_TYPE_ANY,
    .msg_desc_attr = {
        .tx_attr = {
            .resolve_location = true,
        },
    },
};
sid_error_t ret = sid_put_msg(handle, &msg, &desc);

With transport ack for confirmed delivery:

struct sid_msg_desc desc = {
    .type = SID_MSG_TYPE_NOTIFY,
    .link_type = SID_LINK_TYPE_ANY,
    .msg_desc_attr = {
        .tx_attr = {
            .resolve_location = true,
            .request_ack = true,
            .num_retries = 3,
            .ttl_in_seconds = 60,
        },
    },
};
sid_error_t ret = sid_put_msg(handle, &msg, &desc);
// on_update callback will report SID_LOCATION_RESOLVE_MSG_ACK_RECEIVED on success
// or SID_LOCATION_RESOLVE_MSG_TIMEOUT on failure

2.7.3 Delivery Status Notifications

The location library notifies the application of the resolve message delivery status through the on_update callback registered during sid_location_init(). The following status values are used:

  • SID_LOCATION_RESOLVE_MSG_SENT: The message with the location resolve request was successfully sent to the gateway (link-layer confirmed).
  • SID_LOCATION_RESOLVE_MSG_ACK_RECEIVED: The transport acknowledgement was received from the cloud, confirming end-to-end delivery. This status is only reported when request_ack is set to true in the message descriptor.
  • SID_LOCATION_RESOLVE_MSG_TIMEOUT: The message send failed or timed out (no acknowledgement received within the configured TTL).

2.7.4 Error Handling

sid_put_msg() returns the following errors specific to resolve_location:

  • SID_ERROR_INVALID_STATE: Location library is not initialized (sid_location_init() not called).
  • SID_ERROR_NOSUPPORT: SID_SDK_CONFIG_ENABLE_LOCATION is not enabled.

Back to top

©2023 Amazon.com, Inc. or its affiliates (collectively, “Amazon”). All Rights Reserved.