3. Amazon Sidewalk APIs

Amazon Sidewalk provides APIs for the developer’s application to configure, control and use the services of the Amazon Sidewalk stack on an Endpoint.

For the list of error codes and their values see 5.

API Reference

• sid_platform_init()
• sid_platform_deinit()
• sid_init()
• sid_deinit()
• sid_start()
• sid_stop()
• sid_process()
• sid_put_msg()
• sid_get_error()
• sid_get_mtu()
• sid_option()
• sid_set_factory_reset()
• sid_ble_connection_request()
• sid_set_msg_dest_id()
• sid_get_status()
• sid_get_time()
• sid_set_time()
• sid_bulk_data_transfer_init()
• sid_bulk_data_transfer_deinit()
• sid_bulk_data_transfer_release_buffer()
• sid_bulk_data_transfer_finalize()
• sid_bulk_data_transfer_cancel()
• sid_bulk_data_transfer_get_stats()
• sid_location_init()
• sid_location_deinit()
• sid_location_run()
• sid_location_set_max_mode()
• sid_location_get_effort_mode()
• sid_location_update_almanac()
• sid_serial_registration_init()
• sid_serial_registration_start()
• sid_serial_registration_process()
• sid_serial_registration_deinit()
• sid_device_information_init()
• sid_device_information_deinit()
• sid_device_information_is_region_registerable()

3.1 sid_platform_init

sid_platform_init initializes the platform specific components. These are platform abstraction Layer(PAL) routines that are required by the Sidewalk stack

The sid_platform_init is the first API that is required to be invoked before invoking any other Sidewalk API. The sid_platform_init invocation can be avoided if the each PAL component’s initialization routine is explicitly invoked in the developer’s application prior to calling the sid_init API. The sid_platform_init API accepts a pointer to the platform specific data. Invoking sid_platform_init API multiple times without invocation of sid_platform_deinit would not re-initialize the PALs but would return SID_ERROR_NONE

SID_ERROR_INCOMPATIBLE_PARAMS is returned if the argument passed is invalid for a specific PAL initialization’s implementation.

SID_ERROR_NO_SUPPORT is returned if a specific PAL is not supported by the platform.

SID_ERROR_GENERIC is returned if the error code is specific to a PAL implementation.

SID_ERROR_NONE is returned if the PALs are initialized successfully when sid_platform_init is invoked or PALs are already initialized before the invocation of sid_platform_init.

On a platform built with a sub-GHz link (SID_SDK_CONFIG_ENABLE_LINK_TYPE_2 or SID_SDK_CONFIG_ENABLE_LINK_TYPE_3), platform_init_parameters also selects the region the sub-GHz radio operates in. This sets the band, spreading factor, transmit power and channel-access rules:

1. region (sid_reg_region_code_t): SID_PAL_RADIO_RC_NA (1), SID_PAL_RADIO_RC_EU (2), SID_PAL_RADIO_RC_JP (3) or SID_PAL_RADIO_RC_ANZ (4). These values are numerically equal to the corresponding enum sid_device_region values, see 2.16.1.
2. iso_country (const char *): the ISO 3166-1 alpha-2 code of the country the Endpoint operates in, for example "US". The string is copied during the call and may be NULL.

On a REGION_LITE build, SID_ERROR_UNINITIALIZED is returned if region is SID_PAL_RADIO_RC_NONE (0) or a region the build does not include. A single-region build (REGION_US915 or REGION_EU868) ignores both fields and operates on its fixed region. Calling sid_platform_init again without sid_platform_deinit does not apply a new region. For how the radio region relates to the region the Endpoint reports, see 2.16.3.

/**
 * Initializes the Sidewalk stack platform specific parameters.
 *
 * sid_platform_init() shall only be called once before other Sidewalk
 * stack functions e.g. sid_init().
 *
 * @param[in] platform_init_parameters The required configuration in order
 * to properly initialize platform specific
 * parameters
 *
 * @returns #SID_ERROR_NONE in case of success.
 */
sid_error_t sid_platform_init(const void *platform_init_parameters);

platform_parameters_t platform_parameters = {
    .mfg_store_region.addr_start = 0x71000,
    .mfg_store_region.addr_end = 0x72000,
    .platform_init_parameters.radio_cfg =
        (radio_sx126x_device_config_t *)get_radio_cfg(),
    .platform_init_parameters.region = SID_PAL_RADIO_RC_NA,
    .platform_init_parameters.iso_country = "US",
};
sid_error_t ret_code = sid_platform_init(&platform_parameters);

3.2 sid_platform_deinit

sid_platform_deinit deinitializes the platform specific components.

The sid_platform_deinit shall not be called before calling sid_deinit. The sid_platform_deinit invocation can be avoided if each PAL component’s deinitialization routine is explicitly invoked in the developer’s application after calling the sid_deinit API. Invoking sid_platform_deinit API multiple times without invocation of sid_platform_init would not deinitialize the PALs multiple times but returns SID_ERROR_NONE

SID_ERROR_GENERIC is returned if the error code is specific to a PAL implementation.

SID_ERROR_NONE is returned if the PALs are deinitialized successfully when sid_platform_deinit is invoked or PALs are already deinitialized before the invocation of sid_platform_deinit.

/**
 * Deinitializes the Sidewalk stack platform specific parameters.
 *
 * sid_platform_deinit() shall only be called once after
 * using of Sidewalk stack, i.e. after sid_deinit().
 *
 * @returns #SID_ERROR_NONE in case of success.
 */
sid_error_t sid_platform_deinit(void);

sid_error_t ret_code = sid_platform_deinit();

3.3 sid_init

The Amazon Sidewalk stack can be initialized using the sid_init API. The sid_init API accepts a pointer to the Amazon Sidewalk configuration see 2.11. The sid_init API returns a pointer to its internal handle. This handle needs to be passed to all other APIs. On initialization, the Amazon Sidewalk stack and the link specific initialization sequences are executed. On initialization, message buffers and other control structures are allocated however no radio activity occurs in this state. The config structure contains device capability information that is required to be populated for the Amazon Sidewalk stack to report the device capability to the Sidewalk cloud All features supported by the Amazon Sidewalk stack (such as FFS, Time Synchronization, Security, etc.) are available without requiring further feature-specific initialization.

sid_init should not be called in the context of any sid_event_callbacks to avoid re-entrancy and recursion issues. sid_init does not trigger any notifications to the callbacks that the developer has registered with the Amazon Sidewalk stack.

Re-initializing the Amazon Sidewalk stack without de-initializing causes the sid_init to fail with the API return error code SID_ERROR_ALREADY_INITIALIZED.

The sid_init API returns error code SID_ERROR_INVALID_ARGS if any of the following conditions are met:

1. Pointers to config and handle are NULL.
2. The FFS over FSK periodicity is configured with a value which is not in the valid range.
3. The keep-alive payload length in sub_ghz_link_config->ka_payload.len exceeds SID_KA_PAYLOAD_MAX_SIZE (19). See 2.9.10.

Note that sub_ghz_link_config is optional. If link_mask includes SID_LINK_TYPE_2 (FSK) or SID_LINK_TYPE_3 (LoRa) and sub_ghz_link_config is NULL, sid_init does not return SID_ERROR_INVALID_ARGS: the Amazon Sidewalk stack applies its own default sub-GHz configuration, in which the LoRa link runs at the default data rate. sid_init does not validate the LoRa data rate requested through that structure, so a value the Amazon Sidewalk stack does not recognize, and a request the regulatory region does not permit, both select the default data rate without a return code and without a callback. See 2.11. Passing NULL is not identical to passing a structure. The SID_ERROR_NOSUPPORT conditions below apply in either case, with one exception: the Amazon Sidewalk stack evaluates the condition on FFS registration over FSK only when sub_ghz_link_config is supplied. On a build that is not one of the lite build variants of 2.15 and that disables FFS registration over FSK with a compilation flag, an unregistered Endpoint whose link_mask is SID_LINK_TYPE_2 therefore does not receive SID_ERROR_NOSUPPORT when sub_ghz_link_config is NULL. Supply a sub_ghz_link_config when the developer’s application needs that condition to be evaluated.

The sid_init API returns error code SID_ERROR_NOSUPPORT if any of the following conditions are met:

1. link_mask in the config structure has an unsupported combination of link types. The following list are unsupported combinations. Note for FSK and LoRa a device may have the capability to support both link types, but FSK and LoRa cannot be active at the same time.

   1. SID_LINK_TYPE_3(LoRa) only, if the Endpoint is not registered yet with Amazon Sidewalk cloud and is not a factory-registered Endpoint on a build with SID_SDK_INTERNAL_CONFIG_IS_FACTORY_REGISTERED, see 2.15
2. link_mask is configured to SID_LINK_TYPE_2 (FSK) only, and FFS registration over FSK is disabled either through run time config or through a compilation flag. Please note that FFS registration over FSK can be disabled if link_mask includes BLE. For instance link_mask configured to SID_LINK_TYPE_1 (BLE) and SID_LINK_TYPE_2 (FSK) can have FFS registration over FSK disabled.
3. link_mask is configured to SID_LINK_TYPE_2 (FSK) and SID_LINK_TYPE_2 (LoRa), the Sidewalk stack switches between the two links for every one minute until either one of the link is able to connect to Amazon Sidewalk cloud
4. link_mask is configured to SID_LINK_TYPE_3 (LoRa) only when the Endpoint is registered. In an unregistered state, the developer’s application should configure link_mask with atleast one link that supports registration, unless the Endpoint is factory-registered (2.3.4).
5. The Endpoint is neither registered nor factory-registered and the Amazon Sidewalk stack is a lite build variant (2.15). The lite variants have no over-the-air registration path, so sid_init fails instead of the Endpoint failing later.

The sid_init API returns error code SID_ERROR_NONE when the Amazon Sidewalk stack initialization with the requested configuration is successful.

/**
 * Initializes the Sidewalk library for the chosen link type.
 *
 * sid_init() can only be called once for the given sid_config.link_type
 * unless sid_deinit() is called first.
 *
 * @see sid_deinit
 *
 * @param[in] config The required configuration in order to properly
 * initialize Sidewalk for the chosen link type.
 * @param[out] handle A pointer where the opaque handle type will be
 * stored. `handle` is set to NULL on error.
 *
 * @returns #SID_ERROR_NONE on success.
 * @returns #SID_ERROR_ALREADY_INITIALIZED if Sidewalk was already initialized
 * for the given link type.
 */
sid_error_t sid_init(const struct sid_config *config,
                     struct sid_handle **handle);

// Initialize BLE and LoRa links
struct sid_end_device_characteristics dev_ch = {
    .type = SID_END_DEVICE_TYPE_STATIC,
    .power_type = SID_END_DEVICE_POWERED_BY_BATTERY_AND_LINE_POWER,
    .qualification_id = 0x0001,
};
// Initialize adaptive gcs sync intervals array, values are in hours
static uint16_t sync_intervals_h[MAX_TIME_SYNC_INTERVALS] = {2, 4, 8, 12};
static struct sid_time_sync_config time_sync_config = {
    .adaptive_sync_intervals_h = sync_intervals_h,
    .num_intervals = sizeof(default_sync_intervals_h) / sizeof(default_sync_intervals_h[0])
};
struct sid_config config = {
    .link_mask = (SID_LINK_TYPE_1 | SID_LINK_TYPE_3),
    .dev_ch = dev_ch,
    .callbacks = &event_callbacks,
    .link_config = app_get_ble_config(),         // update the BLE config
    .sub_ghz_link_config = app_get_sub_ghz_config(), // update sub GHz config
    .time_sync_config = &time_sync_config,
};
static struct sid_handle *sidewalk_handle;
sid_error_t ret = sid_init(config, &sid_handle);

3.4 sid_deinit

The Amazon Sidewalk stack can be de-initialized using the sid_deinit API. The sid_deinit API requires the pointer to the internal handle that was provided to the developer’s application during initialization. The sid_deinit API stops the links that are initialized during sid_init by calling sid_stop. The time is reset to zero which means that when the Amazon Sidewalk stack is initialized with the sid_init again, the Amazon Sidewalk stack is required to acquire time synchronization again. There is no separate API required to de-initialize any features, calling the sid_deinit API causes all the routines that de-initialize features to be called.

sid_deinit does not trigger any notifications to the callbacks that the developer has registered with the Amazon Sidewalk stack.

sid_init can be called with a different or the same config after sid_deinit is called. sid_deinit should not be called in the context of any sid_deinit to avoid re-entrancy and recursion issues.

The pointer to the internal handle that the developer’s application receives is set to NULL.

1. The sid_deinit API call returns SID_ERROR_INVALID_ARGS, if the handle passed is NULL.
2. The sid_deinit API call returns SID_ERROR_INVALID_STATE, if the Amazon Sidewalk stack is already de-initialized.
3. The sid_deinit API call return SID_ERROR_NONE, if the Amazon Sidewalk stack is successfully de-initialized.

/**
 * De-initialize the portions of the Sidewalk library associated with the
 * given handle.
 *
 * @see sid_init
 *
 * @param[in] handle A pointer to the handle returned by sid_init()
 *
 * @returns #SID_ERROR_NONE in case of success
 */
sid_error_t sid_deinit(struct sid_handle *handle);

sid_error_t ret = sid_deinit(handle);

3.5 sid_start

The Amazon Sidewalk stack can be started using the sid_start API. The Sidewalk handle provided to the developer’s application during initialization is required to be passed to the sid_start API. The link_mask passed to sid_start can be the same as the link_mask passed to the sid_init API or a subset of the links passed to the sid_init API. The links that are not initialized cannot be started. For example, if SID_LINK_TYPE_1 and SID_LINK_TYPE_2 are initialized, the developer’s application can start only one link or both the links as follows:

1. Setting the link_mask to SID_LINK_TYPE_1 or SID_LINK_TYPE_2 starts one link.
2. Setting the link_mask to SID_LINK_TYPE_1 and SID_LINK_TYPE_2 starts both the links.

A call to sid_start triggers the following behavior:

1. If the Amazon Sidewalk stack is not registered, the Amazon Sidewalk stack starts registration based on the links that have started. If both SID_LINK_TYPE_1 and SID_LINK_TYPE_2 have started, and if FFS over FSK is enabled, the registration procedure starts in SID_LINK_TYPE_2 (FSK), and the registration procedure also starts on SID_LINK_TYPE_1 (BLE). The registration procedure is completed based on whichever Gateway is in range: if an Amazon Sidewalk BLE Gateway is in range, the registration procedure is started and completed on BLE link and if an Amazon Sidewalk FSK Gateway is in range, registration procedure is started and completed on the FSK link. The developer’s application can force the Amazon Sidewalk stack to perform registration on the desired link by starting only that link. The developer’s application can initialize BLE and FSK links, but may then start just the BLE link if the developer requires registration to complete on the BLE link or the developer’s application may start just the FSK link if the developer requires registration to complete on the FSK link. Note that registration is not supported on the LoRa link.

2. If the Amazon Sidewalk stack does not have time synhcronization, the Amazon Sidewalk stack acquires time based on the links that are started. If more than one link has started, the time acquisition procedure is started simultaneously on all links that have started.

   1. On the BLE link, the Amazon Sidewalk stack updates the beacon’s payload requesting the GPS time.
   2. On the FSK link, the Amazon Sidewalk stack synchronizes to an FSK Gateway in range and sends a time request message to Amazon Sidewalk cloud services.
   3. on the LoRa link, the Amazon Sidewalk stack immediately sends the time request message to Amazon Sidewalk cloud services.

3. After sid_start is called the link behaves as follows

   1. on BLE, the Endpoint is always beaconing. If the device has an uplink message to send, the beacon’s payload is updated with the intent to connect with a BLE Gateway to send the uplink message. If there is no uplink message to send, the Endpoint advertises its presence to the Amazon Sidewalk BLE Gateways to receive downlink messages from the Amazon Sidewalk cloud services.
   2. on FSK, the Endpoint synchronizes with the Amazon Sidewalk FSK Gateway and, based on the device profile configured, performs a join procedure through the Amazon Sidewalk FSK Gateway with the Amazon Sidewalk cloud services. For more details on the join procedure and device profiles see the device profile document.
   3. on LoRa, the device performs the join procedure with the Amazon Sidewalk cloud services. For more details on join procedure and device profile, see the device profile document.
4. sid_start should not be called in the context of any sid_event_callbacks to avoid re-entrancy and recursion issues.
5. sid_start uses the on_status_changed callback to notify the developer of the Amazon Sidewalk stack status. The on_status_changed callback notifies the developer’s application of the Sidewalk state on the Endpoint, whether it is registered, whether it has acquired GPS time and the connection status of the links that are being started.
6. If a link that has already started, is started again, SID_ERROR_NONE is returned.

7. The Amazon Sidewalk stack returns SID_ERROR_INVALID_ARGS if any of the following is true:

   1. sid_start is called with a handle that is NULL.
   2. sid_start is called before sid_init has been called at least once
   3. link_mask contains links that are not initialized but are being requested to start.
8. The Amazon Sidewalk stack returns SID_ERROR_NONE, if the requested links can be started successfully.

/**
 * Makes the Sidewalk library start operating.
 *
 * The notifications registered during sid_init() are invoked once sid_start()
 * is called.
 *
 * On an unregistered Sidewalk Endpoint sid_start() will put the Sidewalk
 * library into a state ready for device registration, typically the device is
 * registered with a separate mobile application or MCU SDK tool.
 *
 * After registration the Sidewalk Endpoint will receive a time sync message
 * from an accessible Sidewalk gateway. This is a prerequisite to establish
 * up-link or down-link data connectivity. This is visible to the developer by
 * #SID_STATE_READY and #SID_STATUS_TIME_SYNCED.
 *
 * If sid_stop() is called after receiving #SID_STATE_READY the Sidewalk
 * library will cache the time sync for a minimum of SID_TIME_SYNC_MIN_PERIOD
 * seconds. This value should not be modified by the developer using the API.
 *
 * sid_start() can be used to start one or more links at once.
 * To start a single link, eg #SID_LINK_TYPE_1, link_mask = SID_LINK_TYPE_1,
 * To start more than one link, eg #SID_LINK_TYPE_1 and #SID_LINK_TYPE_3,
 * link_mask = SID_LINK_TYPE_1 | SID_LINK_TYPE_3
 *
 * @note Developer can only start a link_type that was initialized in
 * sid_init()
 *
 * @see sid_stop
 *
 * @param[in] handle A pointer to the handle returned by sid_init()
 * @param[in] link_mask The links that need to started.
 *
 * @returns #SID_ERROR_NONE in case of success.
 */
sid_error_t sid_start(struct sid_handle *handle, uint32_t link_mask);

// To start BLE and FSK links and initializing both BLE and FSK links
uint32_t link_mask = (SID_LINK_TYPE_1 | SID_LINK_TYPE_2);

// To start BLE link only after initializing BLE and FSK links
uint32_t link_mask = SID_LINK_TYPE_1;

// To start FSK link only after initializing BLE and FSK links
uint32_t link_mask = SID_LINK_TYPE_2;

sid_error_t ret = sid_start(handle, link_mask);

3.6 sid_stop

The Amazon Sidewalk stack can be stopped by calling the sid_stop API. The Sidewalk handle provided to the developer’s application during initialization is required to be passed to the sid_stop API.

The link_mask passed to sid_stop can be the same as the link_mask passed to the sid_init API or a subset of the links passed to the sid_init API. The links that are not initialized cannot be stopped. For example, if SID_LINK_TYPE_1 and SID_LINK_TYPE_2 are initialized, the developer’s application can stop one link or both links as follows:

1. To stop one link, set the link_mask to SID_LINK_TYPE_1 or SID_LINK_TYPE_2.
2. To stop both links, set the link_mask to SID_LINK_TYPE_1 and SID_LINK_TYPE_2.

A call to sid_stop triggers the following behavior:

1. The links that are requested to be stopped are handled as follows:

   1. on the BLE link

      1. If the Endpoint was in connected state, calling sid_stop causes the Amazon Sidewalk stack to disconnect
      2. If the Endpoint was in advertisement state, calling sid_stop causes the Endpoint to stop beaconing.

Note that the BLE radio is not set to sleep on called sid_stop.

1. on the FSK link, calling sid_stop causes the Amazon Sidewalk stack to disconnect from the Amazon Sidewalk FSK Gateway and sets the radio to sleep.
2. on the LoRa link, calling sid_stop causes the Amazon Sidewalk stack to set the radio to sleep.
3. sid_stop notifies the Amazon Sidewalk stack status to the developer through the on_status_changed callback. The on_status_changed callback notifies the developer’s application of the Sidewalk state on the Endpoint, whether it is registered, whether it has time synchronization and the connection status of the links that are started.
4. sid_stop should not be called in the context of any sid_event_callbacks to avoid re-entrancy and recursion issues.
5. If a link that is already stopped is stopped again, SID_ERROR_NONE is returned.

6. The Amazon Sidewalk stack returns SID_ERROR_INVALID_ARGS if any of the following is true:

   1. sid_stop is called with a handle that is NULL.
   2. sid_stop is called before sid_init has been called at least one time.
   3. link_mask is set to request links to stop that are not initialized.
7. The Amazon Sidewalk stack returns SID_ERROR_NONE, if the requested links can be stopped successfully.

/**
 * Makes the Sidewalk library stop operating.
 *
 * No messages will be sent or received and no notifications will occur after
 * sid_stop() is called.
 * Link status will be changed to disconnected and time sync status is cached
 * after sid_stop() is called.
 *
 * sid_stop() can be used to stop one or more links at once.
 * To stop a single link, eg #SID_LINK_TYPE_1, link_mask = SID_LINK_TYPE_1,
 * To stop more than one link, eg #SID_LINK_TYPE_1 and #SID_LINK_TYPE_3,
 * link_mask = SID_LINK_TYPE_1 | SID_LINK_TYPE_3
 *
 * @note Developer can only stop a link_type that was initialized in
 * sid_init()
 *
 * @see sid_start
 *
 * @warning sid_stop() should be called in the same caller context as
 * sid_process().
 *
 * @warning sid_stop() must not be called from within the caller context of
 * any of the sid_event_callbacks registered during sid_init() to avoid
 * re-entrancy and recursion problems.
 *
 * @warning RTC should not be stopped after sid_stop() is called.
 *
 * @param[in] handle A pointer to the handle returned by sid_init()
 * @param[in] link_mask The links that need to be stopped.
 *
 * @returns #SID_ERROR_NONE in case of success.
 */
sid_error_t sid_stop(struct sid_handle *handle, uint32_t link_mask);

/** To stop BLE and FSK links and initializing and starting both BLE
 * and FSK links */
uint32_t link_mask = (SID_LINK_TYPE_1 | SID_LINK_TYPE_2);

// To stop BLE link only after initializing BLE and FSK links
uint32_t link_mask = SID_LINK_TYPE_1;

// To start FSK link only after initializing BLE and FSK links
uint32_t link_mask = SID_LINK_TYPE_2;

sid_error_t ret = sid_stop(handle, link_mask);

3.7 sid_process

When the Amazon Sidewalk stack calls the developer’s registered callback of on_event, the developer’s application is required to call sid_process. The event sources for the Amazon Sidewalk stack are timers and the radio. The timer events are generated when the Amazon Sidewalk stack schedules events to occur in the future to maintain its states. The radio events are generated by the radio when a particular low level radio process is complete, for example transmitting a message over the air, receiving a message, radio transmit and receive errors etc. The timer and radio events are generated in the Interrupt Service Routine (ISR) context. sid_process should not be called in the same context in which on_event is notified to the developer’s application. This is because on_event notifies internal events that run and maintain Sidewalk states to the developer’s application. This notification process is a slow operation that must not be performed in ISR context. Note that these internal events are not meaningful to the developer.

SID_ERROR_STOPPED is returned if all the links are stopped.

SID_ERROR_INVALID_ARGS is returned if the Amazon Sidewalk stack is not initialized.

SID_ERROR_NONE is returned if the Amazon Sidewalk stack can successfully process its internal events.

Failure to call sid_process after being notified of an event by on_event causes events of the Amazon Sidewalk stack to remain in an unprocessed state. sid_process should be called before calling sid_stop or sid_deinit.

/**
 * Process Sidewalk events.
 *
 * When there are no events to process, the function returns immediately.
 * When events are present, sid_process() invokes the sid_event_callbacks
 * registered during sid_init() within its calling context. You may not
 * receive any callbacks for internal events.
 *
 * You are required to schedule sid_process() to run within your main-loop or
 * running context when the sid_event_callbacks.on_event callback is received.
 *
 * Although not recommended for efficiency and power usage reasons,
 * sid_process() can also be called even if sid_event_callbacks.on_event has
 * not been received, to support main loops that operate in a polling manner.
 *
 * @warning sid_process() must not be called from within the caller context of
 * any of the sid_event_callbacks registered during sid_init() to avoid
 * re-entrancy and recursion problems.
 *
 * @see sid_init
 * @see sid_start
 * @see sid_event_callbacks
 *
 * @param[in] handle A pointer to the handle returned by sid_init()
 *
 * @returns #SID_ERROR_NONE in case of success.
 * @returns #SID_ERROR_STOPPED if sid_start() has not been called.
 */
sid_error_t sid_process(struct sid_handle *handle);

sid_error_t ret = sid_process(handle);

3.8 sid_put_msg

Messages can be sent over Amazon Sidewalk from an Endpoint by calling the sid_put_msg API. For more details on message’s metadata, attributes to configure message’s metadata, and MTU, see 2.8.

The Amazon Sidewalk stack generates a unique ID for a every message that it accepts to send. The message ID starts from the value zero at the time of reset and incremented by one on every message sent including Amazon Sidewalk internal messages. The maximum value that this unique ID is incremented to is 16383, after which it resets to zero. The message ID is used as follows:

1. For the LoRa link, the Amazon Sidewalk stack uses the message ID to notify the developer’s application of the sent status of the message over the air.
2. For BLE and FSK links, the message ID is used for Gateway acknowledgements.

3. if the call to sid_put_msg configures the message to request an acknowledgement from AWS IoT Core for Amazon Sidewalk. AWS IoT Core for Amazon Sidewalk uses the message ID to notify the message’s acknowledgement status. The notification is as follows:

   1. If the message is sent successfully over the air. This is notified to the developer’s application using the on_msg_sent callback. The on_msg_sent callback has a pointer to the message descriptor that has the same message ID that was provided to it at the call made to sid_put_msg. The on_msg_sent callback does not guarantee that the message has been received successfully by AWS IoT Core for Amazon Sidewalk. For messages sent by BLE and FSK, the on_msg_sent callback only notifies the developer’s application that the message has been sent over the air, and that the mesage was acknowledged by a Gateway. For messages sent by LoRa, the on_msg_sent only indicates that the message has been sent over the air successfully.
   2. If the message can not be sent successfully over the air, the developer’s application is notified using the on_send_error callback. The on_send_error callback has a pointer to the message descriptor that has the same message ID that was provided to it at the call made to sid_put_msg. Note that on_msg_sent and on_send_error notifications are mutually exclusive. For a given message ID, both callbacks will not be notified, only one of them is notified to the developer. on_msg_sent is called for successful transmission and on_send_error is called for failure to transmit.
   3. If the message has been acknowledged by AWS IoT Core for Amazon Sidewalk, if it was configured to receive an acknowledgement in the message’s transmit attributes. A message which has the acknowledgement field set to true in its transmit attributes gets the first notification that the message has been successfully sent using the on_msg_sent callback and also another notification that the message has been successfully acknowledged by AWS IoT Core for Amazon Sidewalk through on_msg_received callback.

The message attributes passed define the behavior the Amazon Sidewalk stack applies to the message. The messages’ transmit attributes play a role only in this API. The developer’s application uses this API to inform the Amazon Sidewalk stack of the following attributes:

1. The message is fire and forget, this message has acknowledgement set to false.
2. The Amazon Sidewalk stack is required to retry the message. The number of retries field governs this setting.
3. The period that the Amazon Sidewalk stack is required to hold the message before reporting error code SID_ERROR_TIMEOUT using the on_msg_sent_error callback.
4. The retry periodicity is linear and is derived from time to live and number of retries. For example: for a message configured with time to live as 60 seconds and number of retries as 3, the Amazon Sidewalk stack attempts to retry the message once every 20 seconds until an acknowledgement is received from the AWS IoT Core for Amazon Sidewalk. Once the acknowledgement is received, the developer’s application is notified using on_msg_received that an acknowledgement has been received for the message. Acknowledgements can be differentiated from regular messages notified through the on_msg_received callback by using the is_msg_ack field in the receive attributes in the message descriptor.

When a call to sid_put_msg is made, the receive message attributes of the message descriptor are disregarded by the Amazon Sidewalk stack. This is because sid_put_msg is used to send messages and receive attributes in the message descriptor are only valid for the downlink messages or for Acknowledgements sent by AWS IoT and notified using the on_msg_received callback.

For fire and forget messages, if the time to live field in the transmit attributes is set to zero, the Amazon Sidewalk stack holds the message in its transmit queue for a maximum period of two minutes. In this period, the Amazon Sidewalk stack tries to send the message over the air. If the message cannot be sent over the air within two minutes, the developer’s application is notified with the error code SID_ERROR_TIMEOUT.

A message can be configured to be sent on a specific link or a combination of the links. This setting is in the link_mask field of the message descriptor. The rules are as follows:

1. If only one link is specified in the link_mask:

   1. If the link is not connected, the Amazon Sidewalk stack will fail to send messages with the error SID_ERROR_INVALID_STATE.
   2. If the link is connected the Amazon Sidewalk stack will accept the message.

2. If more than one link is specified in the link_mask the following rules apply:

   1. If only one link is in the connected state, the Amazon Sidewalk stack will send the message over the link which is in connected state.
   2. If all the links in the link_mask are in disconnected state, sid_put_msg fails with the error code SID_ERROR_INVALID_STATE.
   3. If more than one link specified in the link_mask is in the connected state, then the Amazon Sidewalk stack follows a pre-defined order: BLE has the highest priority, followed by FSK and then LoRa has the lowest priority.

sid_put_msg returns SID_ERROR_OOM when the Amazon Sidewalk stack does not have enough buffers to send the message. Whenever the sid_put_msg is called, the stack allocates a buffer from its pre-allocated memory pool and queues the message for transmission. If the developer’s application requests transmissions of messages at a rate higher than the Amazon Sidewalk stack can transmit messages, the Amazon Sidewalk stack runs out of buffers and messages start to fail with the SID_ERROR_OOM error code. It is recommended that the developer’s application should control the rate at which the messages are requested to be transmitted. When sid_put_msg starts to fail messages with SID_ERROR_OOM, callbacks indicate whether the message was transmitted as follows:

1. For messages that do not require retries the on_msg_sent or on_msg_sent_error callbacks indicate whether the message was transmitted.
2. For messages that are configured to expect an acknowledgement from AWS IoT Core for Amazon Sidewalk the on_msg_received callback gives an additional indication of whether the message was received by AWS IoT Core for Amazon Sidewalk.

sid_put_msg returns SID_ERROR_INVALID_ARGS when one or more of the following conditions occurs:

1. The pointer to the msg structure or the pointer to the Sidewalk handle, or the pointer to the message descriptor is NULL.
2. The message size is zero or the message size is greater than 255 bytes.
3. An acknowledgement was requested from AWS IoT Core for Amazon Sidewalk, but either the number of retries is zero or the time to live is zero.
4. The message type is RESP, and the message id is greater than 16383.

sid_put_msg returns SID_ERROR_INVALID_STATE if any of the following conditions occur:

1. The Sidewalk state is not ready. The Amazon Sidewalk stack can send and receive messages only when it’s state is ready. State ready requires, the Endpoint to be registered, acquired GPS time and at least one link is connected.
2. The link_mask specifies a link that is in disconnected state. For example, when the Amazon Sidewalk stack’s BLE and FSK links are started. and only the FSK link is in connected state, and the BLE link is in disconnected state, if the developer’s application sets the link_mask field in the message descriptor to BLE only, sid_put_msg fails with the SID_ERROR_INVALID_STATE error code.

sid_put_msg returns SID_ERROR_NOSUPPORT if a link mode is not supported on the link the message is being requested to be sent on.

sid_put_msg returns SID_ERROR_NONE when the Amazon Sidewalk stack has successfully accepted the message for transmission. When sid_put_msg returns SID_ERROR_NONE this does not imply that the Endpoint’s Amazon Sidewalk stack has already successfully transferred the message to AWS IoT Core for Amazon Sidewalk, instead it implies that the message has been successfully queued in the Endpoint’s internal transmit queue. The sent status of the message is notified to the developer through on_msg_sent and on_msg_sent_error for fire and forget messages and for messages requiring acknowledgement from AWS IoT Core for Amazon Sidewalk.

/**
 * Queues a message.
 *
 * @note msg_desc can be used to correlate this message with the
 * sid_event_callbacks.on_msg_sent and sid_event_callbacks.on_send_error
 * callbacks.
 *
 * @note When sending #SID_MSG_TYPE_RESPONSE in response to #SID_MSG_TYPE_GET,
 * the developer is expected to fill the id field of message descriptor with
 * the id from the corresponding #SID_MSG_TYPE_GET message descriptor.
 * This allows the sid_api to match each unique #SID_MSG_TYPE_RESPONSE with
 * #SID_MSG_TYPE_GET.
 *
 * @param[in] handle    A pointer to the handle returned by sid_init()
 * @param[in] msg       The message data to send
 * @param[out] msg_desc The message descriptor this function fills which
 *                      identifies this message.
 *                      Only valid when #SID_ERROR_NONE is returned.
 *
 * @returns #SID_ERROR_NONE when the message is successfully placed in the
 * transmit queue.
 * @returns #SID_ERROR_TRY_AGAIN when there is no space in the transmit queue.
 */
sid_error_t sid_put_msg(struct sid_handle *handle,
                        const struct sid_msg *msg,
                        struct sid_msg_desc *msg_desc);

/* send a fire and forget message of length 10 bytes and type notify to
 * AWS IoT, over BLE link with time to live as 60 seconds */
#define MAX_MSG_PAYLOAD_SIZE 255
static uint8_t payload[MAX_MSG_PAYLOAD_SIZE];
struct sid_msg_desc msg_desc = {
    .link_type = SID_LINK_TYPE_1,
    .type = SID_MSG_TYPE_NOTIFY,
    .mode = SID_LINK_MODE_CLOUD,
    .msg_desc_attr = {
        .tx_attr = {
            .request_ack = false,
            .num_retires = 0,
            .ttl_in_seconds = 60,
        },
    },
};

struct sid_msg msg = {
    .data = payload,
    .size = 10,
};

sid_error_t ret;
ret = sid_put_msg(handle, &msg, &msg_desc);

/* send message of length 100 bytes and type set to AWS IoT, over BLE or FSK
 * link with request_ack set to true, number of retries to 3 and time to live
 * as 120 seconds */
#define MAX_MSG_PAYLOAD_SIZE 255
static uint8_t payload[MAX_MSG_PAYLOAD_SIZE];
struct sid_msg_desc msg_desc = {
    .link_type = (SID_LINK_TYPE_1 | SID_LINK_TYPE_2),
    .type = SID_MSG_TYPE_SET,
    .mode = SID_LINK_MODE_CLOUD,
    .msg_desc_attr = {
        .tx_attr = {
            .request_ack = true,
            .num_retires = 3,
            .ttl_in_seconds = 120,
        },
    },
};

struct sid_msg msg = {
    .data = payload,
    .size = 100,
};

sid_error_t ret;
ret = sid_put_msg(handle, &msg, &msg_desc);

3.9 sid_get_error

sid_get_error returns the error code, and is used after the on_status_changed callback has returned with SID_STATE_ERROR.

The sid_get_error API call returns the detail error code. The sid_get_error API call is only valid in the context in which the on_status_changed callback was called

SID_ERROR_INVALID_ARGS is returned if the Amazon Sidewalk stack is not initialized.

/**
 * Get the current error code.
 *
 * When the sid_event_callbacks on_status_changed callback is called
 * with a #SID_STATE_ERROR you can use this function to retrieve the
 * detailed error code. The error code will only be valid in the
 * calling context of the sid_event_callbacks.on_status_changed callback.
 *
 * @param[in] handle A pointer to the handle returned by sid_init()
 *
 * @returns The current error code
 */
sid_error_t sid_get_error(struct sid_handle *handle);

sid_error_t ret = sid_get_error(handle);

3.10 sid_get_mtu

The sid_get_mtu API call gets the MTU of the requested link.

SID_ERROR_INVALID_ARGS is returned if the Amazon Sidewalk stack is not initialized. Note that a specific link type has to be requested to get the MTU and not a combination of link types

SID_ERROR_NOSUPPORT is returned if the link type requested is not initialized. For example: if the BLE link is the only link that is initialized but the MTU of the FSK link is requested, SID_ERROR_NOSUPPORT is returned

SID_ERROR_NONE is returned if the link MTU can be successfully retrieved.

The MTU of a link does not depend on the data rate at which the Amazon Sidewalk stack operates that link, nor on whether a Gateway Session Key is in use; see 2.11.1 and 2.11.2. The developer’s application does not need to query the MTU again, or resize its buffers, when either changes.

/**
 * Gets the MTU associated with the given link_type.
 *
 * @param[in] handle    A pointer to the handle returned by sid_init()
 * @param[in] link_type The link type to query
 * @param[out] mtu      A pointer to store the MTU size for the given
 *                      link_type
 *
 * @returns #SID_ERROR_NONE on success.
 */
sid_error_t sid_get_mtu(struct sid_handle *handle,
                        enum SID_LINK_TYPE link_type,
                        size_t *mtu);

size_t mtu = 0;
sid_error_t ret = sid_get_mtu(handle, SID_LINK_TYPE_1, &mtu);

3.11 sid_option

The sid_option API call is used to configure settings of the Amazon Sidewalk stack. For details of configuration see 2.9.

For SID_OPTION_900MHZ_SET_DEVICE_PROFILE and SID_OPTION_900MHZ_GET_DEVICE_PROFILE, len shall be sizeof(struct sid_device_profile); any other length returns SID_ERROR_INVALID_ARGS. For SID_OPTION_900MHZ_SET_DEVICE_PROFILE, the developer’s application shall initialize every member of struct sid_device_profile, not only the members it intends to change: the Amazon Sidewalk stack compares the whole structure against the profile currently in effect, and a stale value in a member the developer’s application did not intend to set is validated like any other and can cause the call to be rejected with SID_ERROR_INCOMPATIBLE_PARAMS or SID_ERROR_INVALID_ARGS. Zero-initialize the structure and set the members required, or start from the profile returned by SID_OPTION_900MHZ_GET_DEVICE_PROFILE. For the members that may be set, their accepted values, the preconditions of each operation and the error conditions, see 2.9.

/**
 * Set an option
 *
 * @see sid_option
 * @param[in] handle     A pointer to the handle returned by sid_init
 * @param[in] option     The option to set
 * @param[in/out] data   A pointer to the memory for input/output data
 *                       associated with the option
 * @param[in] len        The size of the data array
 *
 * @returns #SID_ERROR_NONE on success.
 */
sid_error_t sid_option(struct sid_handle *handle,
                       enum sid_option option,
                       void *data, size_t len);

// Set FSK device profile to Sync profile with the following settings
struct sid_device_profile target_dev_cfg = {
    .unicast_params = {
        .device_profile_id = SID_LINK2_PROFILE_2,
        .rx_window_count = SID_RX_WINDOW_CNT_INFINITE,
        .unicast_window_interval = {
            .sync_rx_interval_ms = SID_LINK2_RX_WINDOW_SEPARATION_1,
        },
        .wakeup_type = SID_TX_AND_RX_WAKEUP,
    },
};

// Set device profile for FSK
sid_error_t ret = sid_option(sid_handle,
                             SID_OPTION_900MHZ_SET_DEVICE_PROFILE,
                             &target_dev_cfg,
                             sizeof(target_dev_cfg));

// Set LoRa device profile to Profile C (continuous RX mode)
struct sid_device_profile lora_profile_c_cfg = {
    .unicast_params = {
        .device_profile_id = SID_LINK3_PROFILE_C,
        // rx_window_count and async_rx_interval_ms are automatically
        // set by the stack for Profile C:
        // rx_window_count = SID_RX_WINDOW_CONTINUOUS (0xFF)
        // async_rx_interval_ms = SID_LINK3_RX_WINDOW_SEPARATION_CONTINUOUS (0)
        .wakeup_type = SID_TX_AND_RX_WAKEUP,
    },
};
sid_error_t ret = sid_option(sid_handle,
                             SID_OPTION_900MHZ_SET_DEVICE_PROFILE,
                             &lora_profile_c_cfg,
                             sizeof(lora_profile_c_cfg));

// Set LoRa device profile to Profile B, and express a preferred RX window
// interval for use while the stack operates the link at the higher data rate
struct sid_device_profile lora_profile_b_cfg = {
    .unicast_params = {
        .device_profile_id = SID_LINK3_PROFILE_B,
        .rx_window_count = SID_RX_WINDOW_CNT_INFINITE,
        .unicast_window_interval = {
            // At the default data rate, Profile A and Profile B accept only 5000 ms or 0
            .async_rx_interval_ms = SID_LINK3_RX_WINDOW_SEPARATION_3,
        },
        .wakeup_type = SID_TX_AND_RX_WAKEUP,
        // Preference, applied by the stack only while it operates the link
        // at the higher data rate, see section 2.9
        .l3_mdr_rx_window_interval_ms = SID_LINK3_RX_WINDOW_SEPARATION_5,
    },
};
sid_error_t ret = sid_option(sid_handle,
                             SID_OPTION_900MHZ_SET_DEVICE_PROFILE,
                             &lora_profile_b_cfg,
                             sizeof(lora_profile_b_cfg));

// Get current configured device profile
struct sid_device_profile curr_dev_cfg = {
    .unicast_params = {
        .device_profile_id = SID_LINK2_PROFILE_2,
    },
};
sid_error_t ret = sid_option(sid_handle,
                             SID_OPTION_900MHZ_GET_DEVICE_PROFILE,
                             &curr_dev_cfg,
                             sizeof(curr_dev_cfg));

// Set filter duplicates settings to allow all duplicates
bool filter_duplicates = true;
sid_error_t ret = sid_option(sid_handle,
                             SID_OPTION_SET_MSG_POLICY_FILTER_DUPLICATES,
                             &filter_duplicates,
                             sizeof(filter_duplicates));

// Get current configured duplicate setting
bool filter_duplicates;
sid_error_t ret = sid_option(sid_handle,
                             SID_OPTION_GET_MSG_POLICY_FILTER_DUPLICATES,
                             &filter_duplicates,
                             sizeof(filter_duplicates));

3.12 sid_set_factory_reset

The sid_set_factory_reset API shall be called when the application decides to clear the Amazon Sidewalk stack’s configuration and keys that were established during registration from non-volatile storage. The sid_set_factory_reset API places the Amazon Sidewalk stack in pre-registration state. On the lite build variants it returns the Endpoint to the factory-registered state instead, see 2.3.5.

Application usage of this API shall be tied to a button press or other event to trigger a de-registration process. When this API is invoked, if a link is available, the SDK attempts to send notification to the Amazon Sidewalk cloud before clearing the Amazon Sidewalk stack’s configuration and keys.

On completion of clearing the Amazon Sidewalk stack’s configuration and keys, on_factory_reset callback shall be triggered from the SDK.

SID_ERROR_INVALID_ARGS is returned by the API if the Amazon Sidewalk stack is not initialized or if the Sidewalk handle is NULL.

SID_ERROR_STOPPED is returned by the API if the Amazon Sidewalk stack is not started.

/**
 * set factory reset
 *
 * Inform the sidewalk stack the factory reset event.
 * The sidewalk library clears its configuration from the non volatile storage
 * and resets its state accordingly.
 * The device needs to successfully complete device registration with the
 * cloud services for the sidewalk library to sned and receive messages
 *
 * @param[in] handle A pointer to the handle returned by sid_init
 *
 * @returns #SID_ERROR_NONE on success.
 */
sid_error_t sid_set_factory_reset(struct sid_handle *handle);

3.13 sid_ble_connection_request

The sid_ble_connection_request API can only be used on the BLE link.

The sid_ble_connection_request API is called by the developer’s application to request connection from a BLE Gateway, or to cancel a request for a connection.

When the sid_ble_connection_request API is called by the developer’s application to request connection, the Endpoint requests an uplink connection on BLE through a BLE Gateway by updating its beacon’s advertisement payload, requesting a BLE Gateway to connect.

The sid_ble_connection_request API must be called again to stop the request to connect. This is because when the sid_ble_connection_request has requested a connection, the beacons have connect request set to TRUE. The value of connect request then remains set to TRUE until set to FALSE by another call to sid_ble_connection_request.

SID_ERROR_NOSUPPORT is returned by the API if the BLE link is not compiled into the image.

SID_ERROR_INVALID_ARGS is returned if one or more of the following conditions is True:

1. BLE is not initialized.
2. BLE is not started.
3. The Sidewalk handle is NULL.

SID_ERROR_INVALID_STATE is returned if one of the following conditions occurs:

1. The Sidewalk state is un-registered
2. The Sidewalk time sync state is FALSE (indicating that the Endpoint does not have time synchronization)

SID_ERROR_ALREADY_EXISTS is returned if the BLE is already beaconing with the request to connect.

SID_ERROR_NONE is returned if the Amazon Sidewalk stack can successfully handle the request.

/**
 * Using this API, the device can request that the Sidewalk gateway initiates
 * a connection to the device while the device is advertising via BLE
 * (Sidewalk beaconing). After a connection is dropped the developer's
 * application has to set this beacon state again. A Gateway may not always be
 * able to honor this request depending on the number of devices connected to
 * it.
 *
 * @param[in] handle    A pointer to the handle returned by sid_init().
 * @param[in] set       Set or clear the connection request in BLE
 *                      advertising packet.
 *
 * @returns #SID_ERROR_NONE on success.
 * @returns #SID_ERROR_ALREADY_EXISTS when device is already connected to a
 *                                    Sidewalk gateway and connection request
 *                                    is set.
 */
sid_error_t sid_ble_bcn_connection_request(struct sid_handle *handle,
                                           bool set);

// Enable connection request
sid_error_t ret = sid_ble_bcn_connection_request(struct sid_handle *handle,
                                                 true);

// Disable connection request
sid_error_t ret = sid_ble_bcn_connection_request(struct sid_handle *handle,
                                                 false);

3.14 sid_set_msg_dest_id

Amazon Sidewalk currently supports only one destination ID: AWS IoT Core for Amazon Sidewalk When the developer’s application sends a message using the Amazon Sidewalk stack, using link mode cloud, the destination ID is set to 32 (the ID of AWS IoT Core for Amazon Sidewalk). The sid_set_msg_dest_id API configures the destination IDs, for future use when Amazon Sidewalk supports destination IDs other than AWS IoT Core for Amazon Sidewalk.

SID_ERROR_INVALID_ARGS is returned if handle is NULL. SID_ERROR_NONE is returned if the destination ID can be set successfully.

/**
 * Set destination ID for messages.
 *
 * By default, the destination ID is set to #SID_MSG_DESTINATION_AWS_IOT_CORE
 * unless changed by sid_set_msg_dest_id(). The destination ID is retained
 * until the device resets or its changed by another invocation of
 * sid_set_msg_dest_id().
 *
 * @see sid_put_msg().
 *
 * @param[in] handle A pointer to the handle returned by sid_init().
 * @param[in] id     The new destination ID.
 *
 * @returns #SID_ERROR_NONE on success.
 */
sid_error_t sid_set_msg_dest_id(struct sid_handle *handle, uint32_t id);

sid_error_t ret = sid_set_msg_dest_id(handle, 32); // only AWS IoT destination
                                                  // is currently supported

3.15 sid_get_status

The status of the Amazon Sidewalk stack can be polled by calling the sid_get_status API. For details of the sid_status structure, see 2.6.

SID_ERROR_INVALID_ARGS is returned if the Sidewalk handle passed is NULL or if the Amazon Sidewalk stack is not initialized.

SID_ERROR_NONE is returned when the current status can be successfully returned to the developer’s application.

/**
 * Get current status from Sidewalk library.
 *
 * @warning sid_get_status() should be called in the same caller context as
 * sid_process().
 *
 * @warning sid_get_status() must not be called from within the caller context
 * of any of the sid_event_callbacks registered during sid_init() to avoid
 * re-entrancy and recursion problems.
 *
 * @param[in] handle A pointer to the handle returned by sid_init()
 * @param[out] current_status A pointer to store the sdk current status
 *
 * @returns #SID_ERROR_NONE in case of success.
 * @returns #SID_ERROR_INVALID_ARGS when Sidewalk library is not initialized.
 */
sid_error_t sid_get_status(struct sid_handle *handle,
                           struct sid_status *current_status);

struct sid_status current_status;
sid_error_t ret = sid_get_status(handle, &current_status);

3.16 sid_get_time

sid_get_time provides the caller with the GPS time. UTC and local time are not supported.

SID_ERROR_NOSUPPORT is returned when the sid_get_time call requests time other than GPS time.

SID_ERROR_INVALID_ARGS is returned if one or more of the following conditions occurs:

1. The handle is NULL.
2. The pointer to hold the time is NULL
3. The Amazon Sidewalk stack is not initialized

SID_ERROR_NONE is returned if the API can successfully provide GPS time.

/**
 * Get time from the Sidewalk library with the requested format.
 *
 * @warning sid_get_time() should be called in the same caller context as
 * sid_process().
 *
 * @warning sid_get_time() must not be called from within the caller context
 * of any of the sid_event_callbacks registered during sid_init() to avoid
 * re-entrancy and recursion problems.
 *
 * @param[in] handle     A pointer to the handle returned by sid_init().
 * @param[in] format     The time format to query
 * @param[out] curr_time A pointer to store the current time in
 *                       sid_timespec format.
 *
 * @returns #SID_ERROR_NONE in case of success.
 * @returns #SID_ERROR_INVALID_ARGS when sidewalk is not initialized or not
 *          registered or invalid format is supplied.
 * @returns #SID_ERROR_UNINITIALIZED when time is not available.
 */
sid_error_t sid_get_time(struct sid_handle *handle,
                         enum sid_time_format format,
                         struct sid_timespec *curr_time);

struct sid_timespec curr_time;

sid_error_t ret = sid_get_time(handle, SID_GET_GPS_TIME, &curr_time);

3.17 sid_set_time

sid_set_time allows the application to set the time in the Sidewalk stack. This API can be used to provide time synchronization from external sources.

SID_ERROR_INVALID_ARGS is returned if one or more of the following conditions occurs:

1. The handle is NULL.
2. The pointer to the time is NULL
3. The pointer to the drift is NULL
4. The Amazon Sidewalk stack is not initialized

SID_ERROR_INVALID_STATE is returned if the device is not registered.

SID_ERROR_NONE is returned if the API can successfully set the time.

/**
 * Set time in the Sidewalk stack.
 *
 * @warning sid_set_time() should be called in the same caller context as
 * sid_process().
 *
 * @warning sid_set_time() must not be called from within the caller context
 * of any of the sid_event_callbacks registered during sid_init() to avoid
 * re-entrancy and recursion problems.
 *
 * @param[in] handle A pointer to the handle returned by sid_init().
 * @param[in] time   A pointer to the time to set in sid_timespec format.
 * @param[in] drift  A pointer to the time drift in sid_timespec format.
 *
 * @returns #SID_ERROR_NONE in case of success.
 * @returns #SID_ERROR_INVALID_ARGS when Sidewalk is not initialized or not
 *          registered or invalid parameters are supplied.
 * @returns #SID_ERROR_INVALID_STATE when device is not registered.
 */
sid_error_t sid_set_time(struct sid_handle *handle,
                         const struct sid_timespec *time,
                         const struct sid_timespec *drift);

struct sid_timespec time = {.tv_sec = 1640995200, .tv_nsec = 0};  // Example time
struct sid_timespec drift = {.tv_sec = 0, .tv_nsec = 100000000};  // 100 ms drift

sid_error_t ret = sid_set_time(handle, &time, &drift);

3.17.1 Local Time Synchronization Example

Applications can implement local time synchronization to reduce power consumption and network traffic by avoiding frequent cloud time sync requests:

// Note: Users must implement get_application_timestamp(), flash_write_time_data(),
// and flash_read_time_data() functions based on their platform requirements

// Save current time to flash storage for later use
void save_time_to_flash(void) {
    struct sid_timespec current_time, save_timestamp;
    sid_error_t ret = sid_get_time(handle, SID_GET_GPS_TIME, &current_time);
    if (ret == SID_ERROR_NONE) {
        // Save GPS time and current app timestamp
        get_application_timestamp(&save_timestamp);
        flash_write_time_data(&current_time, &save_timestamp);
    }
}

// Restore time from flash and apply drift compensation
void restore_time_from_flash(void) {
    struct sid_timespec saved_time, save_timestamp, restore_timestamp, app_uptime;
    struct sid_timespec adjusted_time;

    // Read saved data from flash
    if (flash_read_time_data(&saved_time, &save_timestamp) == SUCCESS) {
        // Get current application timestamp
        get_application_timestamp(&restore_timestamp);

        // Calculate app uptime = timestamp at restore - timestamp at saving
        app_uptime.tv_sec = restore_timestamp.tv_sec - save_timestamp.tv_sec;
        app_uptime.tv_nsec = restore_timestamp.tv_nsec - save_timestamp.tv_nsec;

        // Calculate adjusted time: saved_time + app_uptime
        adjusted_time.tv_sec = saved_time.tv_sec + app_uptime.tv_sec;
        adjusted_time.tv_nsec = saved_time.tv_nsec + app_uptime.tv_nsec;

        sid_error_t ret = sid_set_time(handle, &adjusted_time, &app_uptime);
        if (ret == SID_ERROR_NONE) {
            // Time sync successful - no cloud request needed
        }
    }
}

3.18 sid_bulk_data_transfer_init

SBDT can be initialized using sid_bulk_data_transfer_init API. The sid_bulk_data_transfer_init API accepts a pointer to the SBDT configuration and sid_handle. On initialization, SBDT registers for SBDT messages from the cloud, and loads any existing ongoing transfers. If there was an ongoing transfer, the memory is requested from the developer’s application to handle said transfers see 2.13.4.

sid_bulk_data_transfer_init should not be called in the context of SBDT Callbacks to avoid re-entrancy and recursion issues. If there was an ongoing transfer sid_bulk_data_transfer_init API will trigger on_transfer_request API call to request memory and to allow developer’s application to either reject or accept the ongoing transfer. If the developer’s application chooses to reject the ongoing transfer then ongoing transfer information is wiped away from the KV store API.

Re-initializing SBDT without de-initializing causes the sid_bulk_data_transfer_init to fail with the API return error code SID_ERROR_ALREADY_INITIALIZED.

The sid_bulk_data_transfer_init API returns error code SID_ERROR_INVALID_ARGS if any of the following conditions are met:

• Pointers to config and handle are NULL.
• Any of the SBDT Callbacks functions are set to NULL.
• Amazon Sidewalk stack is not initialized via the sid_init API.

The sid_bulk_data_transfer_init API will return error code SID_ERROR_STORAGE_READ_FAIL if it is not able to read the status of any ongoing transfer’s from the KV store API.

/**
 * Initializes Sidewalk bulk transfer
 *
 * @see sid_bulk_data_transfer_init
 * @see sid_init
 *
 * @param[in] config Required configuration needed to initialize Sidewalk
 * bulk transfer
 * @param[in] handle A pointer to the handle returned by sid_init()
 *
 * @returns #SID_ERROR_NONE in case of success
 */
sid_error_t sid_bulk_data_transfer_init
              (const struct sid_bulk_data_transfer_config *config,
               struct sid_handle *handle);

// Initialize BLE link
struct sid_config config = {
    .link_mask = SID_LINK_TYPE_1,
    .callbacks = &event_callbacks,
    .link_config = app_get_ble_config(), // update the BLE config
};
static struct sid_handle *sidewalk_handle;
sid_error_t ret = sid_init(config, &sid_handle);

struct sid_bulk_data_transfer_config sbdt_config = {
    .callbacks = &sbdt_event_callbacks,
};
ret = sid_bulk_data_transfer_init(&sbdt_config, sidewalk_handle);

3.19 sid_bulk_data_transfer_deinit

SBDT can be de-initialized using sid_bulk_data_transfer_deinit API.

The sid_bulk_data_transfer_deinit API requires the pointer to the internal handle that was provided to the developer’s application during initialization. The sid_bulk_data_transfer_deinit API deregisters SBDT from handling any incoming SBDT commands and releases the memory that was acquired via on_transfer_request callback using the on_release_scratch callback. Calling sid_deinit API will not de initialize SBDT and it needs to be done separately as well.

• The sid_bulk_data_transfer_deinit return’s SID_ERROR_INVALID_ARGS if the handle passed is NULL or is not initialized.

/**
 * De-initialize Sidewalk bulk transfer
 *
 * @see sid_bulk_data_transfer_init
 *
 * @param[in] handle A pointer to the handle returned by sid_init()
 *
 * @returns #SID_ERROR_NONE in case of success
 */
sid_error_t sid_bulk_data_transfer_deinit(struct sid_handle *handle);

sid_error_t ret = sid_bulk_data_transfer_deinit(sidewalk_handle);

3.20 sid_bulk_data_transfer_release_buffer

The sid_bulk_data_transfer_release_buffer API is called to indicate to SBDT that the developer’s application is done processing the data buffer containing the fragment it received in on_data_recieved callback, and it’s ready to receive the next one. The sid_bulk_data_transfer_release_buffer API in conjunction with on_data_recieved callback can handle the below cases in respect to flash write. The developer’s application can write the data received in on_data_recieved to flash and release the buffer via sid_bulk_data_transfer_release_buffer within the on_data_recieved callback itself. If the write takes too long that it impacts the performance of the system, the write can be scheduled to a later time and sid_bulk_data_transfer_release_buffer can be called once the write is done. This approach gives the developer enough flexibility to handle both cases with respect to writes.

• sid_bulk_data_transfer_release_buffer returns SID_ERROR_INVALID_ARGS if

  • sid_handle is NULL
  • If Sidewalk stack is not initialized

• sid_bulk_data_transfer_release_buffer returns SID_ERROR_NOT_FOUND if

  • file_id is incorrect or it does not find an ongoing transfer corresponding to the given file_id
  • The given buffer does not match the one received in the on_recieved_callback

• sid_bulk_data_transfer_release_buffer returns SID_ERROR_INVALID_STATE if

  • SBDT was not initialized via the sid_bulk_data_transfer_init API call
  • If developer’s application is trying to release a buffer that was never given or already released

/**
 * Release data buffer
 *
 * This API is called to release ownership of the data buffer back to bulk
 * transfer
 *
 * @param[in] handle A pointer to the handle returned by sid_init()
 * @param[in] file_id Identifier of the file transfer whose buffer is being
 * released
 * @param[in] buffer A pointer to the buffer that needs to be released, which
 * is never NULL
 *
 * @returns #SID_ERROR_NONE in case of success
 */
sid_error_t sid_bulk_data_transfer_release_buffer(struct sid_handle *handle,
    uint32_t file_id,
    const struct sid_bulk_data_transfer_buffer *const buffer);

void sbdt_on_data_recieved
    (const struct sid_bulk_data_transfer_desc *const desc,
     const struct sid_bulk_data_transfer_buffer *const buffer,
     void *context) {

    // Illustrative API indicating write to flash
    write_to_flash(buffer->data, buffer->size);

    sid_error_t ret = sid_bulk_data_transfer_release_buffer(sidewalk_handle,
                                                           desc->file_id,
                                                           buffer);
}

3.21 sid_bulk_data_transfer_finalize

The developer’s application calls sid_bulk_data_transfer_finalize to indicate weather the file was fully transferred and it passed any of user’s validation checks, such as CRC32 check or signature verification checks. This API is used in conjunction with on_finalize_request, where once the developer’s application receives the on_finalize_request callback the developer’s application verifies the received file and calls sid_bulk_data_transfer_finalize with the appropriate success or failure response.

The sid_bulk_data_transfer_finalize API can be called within any context.

• sid_bulk_data_transfer_finalize returns SID_ERROR_INVALID_ARGS if

  • sid_handle is NULL
  • If Sidewalk stack is not initialized

• sid_bulk_data_transfer_finalize returns SID_ERROR_NOT_FOUND if

  • file_id is incorrect or it does not find an ongoing transfer corresponding to the given file_id

• sid_bulk_data_transfer_finalize returns SID_ERROR_INVALID_STATE if

  • SBDT was not initialized via the sid_bulk_data_transfer_init API call
  • If developer’s application is trying to finalize a transfer before all of the file is received

/**
 * Complete an ongoing Sidewalk bulk transfer
 *
 * This function is called when on_finalize_request callback is invoked. The
 * purpose of the API is to inform bulk transfer if the transfer was
 * successful (CRC checks/signature is verified), or it was a failure.
 *
 * @see sid_bulk_data_transfer_event_callbacks.on_finalize_request
 *
 * @param[in] handle A pointer to the handle returned by sid_init()
 * @param[in] file_id Identifier of the file being transferred
 * @param[in] status Indicates if the transfer was completed successfully from
 * the user end
 *
 * @returns #SID_ERROR_NONE in case of success
 */
sid_error_t sid_bulk_data_transfer_finalize
           (struct sid_handle *handle, uint32_t file_id,
            enum sid_bulk_data_transfer_final_status status);

void sbdt_on_finalize_request(uint32_t file_id, void *context)
{
    // Illustrative API indicating verification of file
    bool success = validate_recieved_file(file_id);

    sid_error_t ret = sid_bulk_data_transfer_finalize
                      (sidewalk_handle, file_id,
                       success ? SID_BULK_DATA_TRANSFER_FINAL_STATUS_SUCCESS
                               : SID_BULK_DATA_TRANSFER_FINAL_STATUS_FAILURE);
}

3.22 sid_bulk_data_transfer_cancel

The developer’s application can use sid_bulk_data_transfer_cancel API to cancel an ongoing transfer. When the developer’s application calls the sid_bulk_data_transfer_cancel, SBDT informs AWS of the cancellation request and calls on_cancel_request callback and on_release_scratch.

• sid_bulk_data_transfer_cancel returns SID_ERROR_INVALID_ARGS if

  • sid_handle is NULL
  • If Sidewalk stack is not initialized

• sid_bulk_data_transfer_cancel returns SID_ERROR_NOT_FOUND if

  • file_id is incorrect or it does not find an ongoing transfer corresponding to the given file_id

• sid_bulk_data_transfer_cancel returns SID_ERROR_INVALID_STATE if

  • SBDT was not initialized via the sid_bulk_data_transfer_init API call

• sid_bulk_data_transfer_cancel returns SID_ERROR_NO_ROUTE_AVAILABLE if the transfer link is not connected. The developer’s application will then need to re-establish the link again before calling the sid_bulk_data_transfer_cancel again.

/**
 * Cancels any ongoing bulk transfer
 *
 * @param[in] handle A pointer to the handle returned by sid_init()
 * @param[in] file_id Identifier of the file transfer that needs to be
 * cancelled
 * @param[in] reason Reason for cancelling the transfer
 *
 * @return #SID_ERROR_NONE in case of success
 */
sid_error_t sid_bulk_data_transfer_cancel
              (struct sid_handle *handle, uint32_t file_id,
               enum sid_bulk_data_transfer_reject_reason reason);

sid_error_t ret = sid_bulk_data_transfer_cancel
                  (sidewalk_handle, file_id,
                   SID_BULK_DATA_TRANSFER_REJECT_REASON_NONE);

3.23 sid_bulk_data_transfer_get_stats

The developer’s application can use sid_bulk_data_transfer_get_stats API to get the current progress of the file transfer. It returns the fragment size, size of the file transferred and total size of the file. The developer’s application can call this API anytime during the duration of the transfer.

• sid_bulk_data_transfer_get_stats returns SID_ERROR_INVALID_ARGS if

  • sid_handle is NULL
  • If Sidewalk stack is not initialized
  • If the stats argument is NULL

• sid_bulk_data_transfer_get_stats returns SID_ERROR_NOT_FOUND if

  • file_id is incorrect or it does not find an ongoing transfer corresponding to the given file_id

• sid_bulk_data_transfer_get_stats returns SID_ERROR_INVALID_STATE if

  • SBDT was not initialized via the sid_bulk_data_transfer_init API call

/**
 * Get the stats of an ongoing Sidewalk bulk transfer
 *
 * This function is called to get the current stats/progress of an ongoing
 * file transfer
 *
 * @param[in] handle A pointer to the handle returned by sid_init()
 * @param[in] file_id Identifier of the file being transferred
 * @param[in] stats A pointer to the structure that holds the stats
 * information
 *
 * @returns #SID_ERROR_NONE in case of success
 */
sid_error_t sid_bulk_data_transfer_get_stats
              (struct sid_handle *handle, uint32_t file_id,
               struct sid_bulk_data_transfer_stats *const stats);

struct sid_bulk_data_transfer_stats stats = {};
sid_error_t ret = sid_bulk_data_transfer_get_stats(sidewalk_handle, file_id,
                                                   &stats);

3.24 sid_location_init

The Sidewalk Location Library can be initialized using the sid_location_init API. The sid_location_init API accepts a pointer to the location configuration and the Sidewalk handle returned by sid_init. The location library can be initialized after sid_init() and provides a unified interface for multiple location resolution methods including Sidewalk Network Location over BLE, WiFi scanning, and GNSS scanning.

On initialization, the location library configures the supported location methods based on the hardware capabilities and initializes the corresponding Platform Abstraction Layers (PALs) if WiFi and GNSS are enabled. The library automatically manages location effort levels and provides fallback mechanisms to ensure the most power-efficient location method is used first.

sid_location_init should not be called in the context of any location event callbacks to avoid re-entrancy and recursion issues.

Re-initializing the location library without de-initializing returns SID_ERROR_NONE (the existing context is reused).

The sid_location_init API returns error code SID_ERROR_INVALID_ARGS if any of the following conditions are met:

1. Pointer to handle is NULL or the Sidewalk stack is not initialized.
2. Pointer to config is NULL.
3. The max_effort in config is greater than the available hardware capabilities.

The callbacks.on_update function pointer must not be NULL as it is called throughout the location library operations. Passing a NULL callback will result in undefined behavior.

The sid_location_init API returns error code SID_ERROR_NOSUPPORT if any of the following conditions are met:

1. The requested location method types are not supported by the platform.
2. WiFi or GNSS PALs are not available when SID_LOCATION_METHOD_WIFI or SID_LOCATION_METHOD_GNSS are specified.

The sid_location_init API may also return errors from the underlying WiFi or GNSS PAL initialization.

The sid_location_init API returns error code SID_ERROR_NONE when the location library initialization is successful.

The sid_location_init API returns error code SID_ERROR_OOM if memory allocation fails.

The struct sid_location_config contains the following fields:

• sid_location_type_mask - Bitmask of location methods to enable (SID_LOCATION_METHOD_BLE_GATEWAY, SID_LOCATION_METHOD_WIFI, SID_LOCATION_METHOD_GNSS, or SID_LOCATION_METHOD_ALL)
• callbacks - Event callback structure containing on_update function pointer and optional context
• max_effort - Maximum effort mode allowed for location operations
• manage_effort - When true, the library automatically manages effort levels and steps down through different location methods

• stepdowns - Timeout configuration (in milliseconds) for stepping down location levels:

  • l4_to_l3 - Timeout after GNSS scan completes before stepping down to WiFi
  • l3_to_l2 - Timeout after WiFi scan completes before stepping down to L2
  • l2_to_l1 - Timeout before stepping down to BLE

• fragmentation - Configuration for fragmented uplink over LoRa:

  • timeout_ms - Total timeout for fragmentation retries
  • max_retries - Maximum number of retry attempts
• auto_link_pause_resume - When true, automatically pauses Sub-1GHz links (Link Type 2 and 3) during GNSS scans to avoid hardware conflicts, and resumes them after scan completion

/**
 * Initialize sid location library
 *
 * This API will configure and initialize one or more of the supported
 * location libraries available on device.
 *
 * @param[in] handle A pointer to the handle returned by sid_init()
 * @param[in] config Location configuration structure
 *
 * @returns #SID_ERROR_NONE in case of success
 **/
sid_error_t sid_location_init(struct sid_handle *handle,
                              struct sid_location_config *config);

// Initialize location library with BLE-only support
void location_callback(const struct sid_location_result *const result,
                       void *context) {
    // Handle location result
}

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 = {
        .l2_to_l1 = 0,
        .l3_to_l2 = 0,
        .l4_to_l3 = 0,
    },
    .fragmentation = {
        .timeout_ms = 60000,
        .max_retries = 1,
    },
    .auto_link_pause_resume = false,
};

sid_error_t ret = sid_location_init(sidewalk_handle, &cfg);

3.25 sid_location_deinit

The Sidewalk Location Library can be de-initialized using the sid_location_deinit API. The sid_location_deinit API requires the pointer to the Sidewalk handle that was provided during initialization. The sid_location_deinit API deinitializes the enabled location libraries and releases any allocated resources.

sid_location_deinit should not be called in the context of any location event callbacks to avoid re-entrancy and recursion issues.

The sid_location_deinit API call returns SID_ERROR_UNINITIALIZED, if the handle passed is NULL, if the Sidewalk stack is not initialized, or if the location library is not initialized.

The sid_location_deinit API call returns SID_ERROR_BUSY, if there is an ongoing GNSS or WiFi scan operation.

The sid_location_deinit API may also return errors from the underlying GNSS or WiFi PAL deinitialization.

The sid_location_deinit API call returns SID_ERROR_NONE, if the location library is successfully de-initialized.

/**
 * Deinitialize sid location library
 *
 * This API will deinitialize the enabled location libraries.
 *
 * @param[in] handle A pointer to the handle returned by sid_init()
 *
 * @returns #SID_ERROR_NONE in case of success
 **/
sid_error_t sid_location_deinit(struct sid_handle *handle);

sid_error_t ret = sid_location_deinit(sidewalk_handle);

3.26 sid_location_run

The sid_location_run API is used to scan and send available location information to the cloud to resolve coordinates. The API accepts a configuration structure that specifies the location effort mode and run type (scan only, send only, or scan and send). The location library will prioritize the most power and time efficient mechanism based on the configured effort mode.

When manage_effort is enabled in the location configuration, the library automatically manages effort levels and steps down through different location methods based on availability and timeout configurations. If manage_effort is disabled, SID_LOCATION_EFFORT_DEFAULT cannot be used and a specific effort mode must be specified.

The location effort levels are ordered by power consumption:

1. Level 1 (SID_LOCATION_EFFORT_L1): Sidewalk Network Location over BLE - No additional power consumption
2. Level 2 (SID_LOCATION_EFFORT_L2): LoRa location trigger (requires Link Type 3 network sync)
3. Level 3 (SID_LOCATION_EFFORT_L3): WiFi Scan - Low power consumption
4. Level 4 (SID_LOCATION_EFFORT_L4): GNSS Scan - Higher power consumption

The sid_location_run API returns error code SID_ERROR_UNINITIALIZED if the handle is NULL, the Sidewalk stack is not initialized, or the location library is not initialized.

The sid_location_run API returns error code SID_ERROR_INVALID_STATE if the Sidewalk stack is not started.

The sid_location_run API returns error code SID_ERROR_INVALID_ARGS if any of the following conditions are met:

1. For SID_LOCATION_SEND_ONLY operations: the buffer is NULL, size is zero, or mode is not SID_LOCATION_EFFORT_L3 or SID_LOCATION_EFFORT_L4.

The sid_location_run API returns error code SID_ERROR_NO_ROUTE_AVAILABLE if SID_LOCATION_SEND_ONLY is requested but no link is connected.

The sid_location_run API returns error code SID_ERROR_NOSUPPORT if the requested effort mode requires a location method that is not available or not initialized.

The sid_location_run API returns error code SID_ERROR_INSUFFICIENT_RESULTS if the scan completes but does not find sufficient data for location resolution (e.g., insufficient WiFi access points or GNSS satellites).

The sid_location_run API returns error code SID_ERROR_NONE when the location request is successfully queued for processing.

The struct sid_location_run_config contains the following fields:

• mode - The location effort mode to use (SID_LOCATION_EFFORT_L1 through SID_LOCATION_EFFORT_L4, or SID_LOCATION_EFFORT_DEFAULT when manage_effort is enabled)

• type - The run type:

  • SID_LOCATION_SEND_ONLY - Send pre-scanned location data without performing a new scan
  • SID_LOCATION_SCAN_ONLY - Perform a scan but do not send the data to the cloud
  • SID_LOCATION_SCAN_AND_SEND - Perform a scan and send the data to the cloud
• buffer - Pointer to pre-scanned location data (required for SID_LOCATION_SEND_ONLY, NULL otherwise)
• size - Size of the buffer in bytes (required for SID_LOCATION_SEND_ONLY, 0 otherwise)

The maximum payload size for location data is defined by SID_LOCATION_MAX_PAYLOAD_SIZE (106 bytes).

/**
 * API to scan and send available location information to the cloud to resolve
 * coordinates. If effort mode is NOT managed, SID_LOCATION_EFFORT_DEFAULT
 * cannot be used.
 *
 * @param[in] handle A pointer to the handle returned by sid_init()
 * @param[in] config struct containing the configuration for the location request
 * @param[in] delay_s delay to start scan (if applicable) and uplink data
 *
 * @returns #SID_ERROR_NONE in case of success
 **/
sid_error_t sid_location_run(struct sid_handle *handle,
                             struct sid_location_run_config *config,
                             uint32_t delay_s);

// WiFi scan and send uplink
struct sid_location_run_config config = {
    .type = SID_LOCATION_SCAN_AND_SEND,
    .mode = SID_LOCATION_EFFORT_L3,
    .buffer = NULL,
    .size = 0,
};
sid_error_t ret = sid_location_run(sidewalk_handle, &config, 0);

// GNSS scan only (no uplink)
struct sid_location_run_config config = {
    .type = SID_LOCATION_SCAN_ONLY,
    .mode = SID_LOCATION_EFFORT_L4,
    .buffer = NULL,
    .size = 0,
};
sid_error_t ret = sid_location_run(sidewalk_handle, &config, 0);

// Send pre-scanned location data (SEND_ONLY)
uint8_t location_buffer[SID_LOCATION_MAX_PAYLOAD_SIZE];
// ... populate location_buffer with scan data ...
struct sid_location_run_config config = {
    .type = SID_LOCATION_SEND_ONLY,
    .mode = SID_LOCATION_EFFORT_L3, // or SID_LOCATION_EFFORT_L4 for GNSS
    .buffer = location_buffer,
    .size = sizeof(location_buffer),
};
sid_error_t ret = sid_location_run(sidewalk_handle, &config, 0);

3.27 sid_location_set_max_mode

The sid_location_set_max_mode API is used to set the maximum effort mode allowed for location operations. This is useful when the device is in a low power mode and the developer wants to limit location operations to less power-intensive methods. For example, setting the maximum mode to SID_LOCATION_EFFORT_L1 will restrict location operations to BLE-only methods.

The sid_location_set_max_mode API returns error code SID_ERROR_UNINITIALIZED if the handle is NULL, if the Sidewalk stack is not initialized, or if the location library is not initialized.

The sid_location_set_max_mode API returns error code SID_ERROR_PARAM_OUT_OF_RANGE if the mode is invalid (negative or greater than or equal to SID_LOCATION_EFFORT_INVALID).

The sid_location_set_max_mode API returns error code SID_ERROR_NONE when the maximum effort mode is successfully set.

/**
 * API to set the maximum effort mode allowed (ex. if the device is in a low
 * power mode, send messages via mode 1)
 *
 * @param[in] handle A pointer to the handle returned by sid_init()
 * @param[in] mode maximum effort mode allowed.
 *
 **/
sid_error_t sid_location_set_max_mode(struct sid_handle *handle,
                                      enum sid_location_effort_mode mode);

// Limit to BLE-only location methods
sid_error_t ret = sid_location_set_max_mode(sidewalk_handle,
                                            SID_LOCATION_EFFORT_L1);

3.28 sid_location_get_effort_mode

The sid_location_get_effort_mode API retrieves the current location effort mode maintained by the location library. This can be used by the developer’s application to query the current location level and make decisions about when to request location updates.

The sid_location_get_effort_mode API returns SID_LOCATION_EFFORT_INVALID if the handle is NULL or the location library is not initialized.

/**
 * API to retrieve the location mode maintained by the location library
 *
 * @param[in] handle A pointer to the handle returned by sid_init()
 *
 * @returns the current sid location effort mode.
 **/
enum sid_location_effort_mode sid_location_get_effort_mode(struct sid_handle *handle);

enum sid_location_effort_mode current_mode = sid_location_get_effort_mode(sidewalk_handle);
if (current_mode != SID_LOCATION_EFFORT_INVALID) {
    // Use current_mode for decision making
}

3.29 sid_location_update_almanac

The sid_location_update_almanac API is used to sideload GNSS almanac data to the location library. The almanac contains orbital information for GNSS satellites and is used to improve the time to first fix (TTFF) and accuracy of GNSS location resolution. This API provides a mechanism to manually update almanac data from external sources such as the cloud.

Note that some GNSS chips may have a built-in almanac demodulation service that can automatically update almanac data over satellite signals. The sid_location_update_almanac API provides an alternative sideload method for almanac updates.

This API is currently not implemented and always returns SID_ERROR_NOSUPPORT.

/**
 * API to update the GNSS almanac
 *
 * @param[in] handle A pointer to the handle returned by sid_init().
 * @param[in] almanac_buffer a pointer to a buffer containing the almanac.
 * @param[in] almanac_size size of the almanac buffer.
 *
 * @returns #SID_ERROR_NONE in case of success
 **/
sid_error_t sid_location_update_almanac(struct sid_handle *handle,
                                        uint8_t *almanac_buffer,
                                        size_t almanac_size);

uint8_t almanac_data[ALMANAC_SIZE];
// ... populate almanac_data from cloud or other source ...
sid_error_t ret = sid_location_update_almanac(sidewalk_handle,
                                              almanac_data,
                                              sizeof(almanac_data));

3.30 sid_serial_registration_init

sid_serial_registration_init builds the factory registration stack and the wired link (SID_LINK_TYPE_8) and registers the completion callback, see 2.3.4. It does not start the registration exchange. The Amazon Sidewalk stack does not have to be initialized with sid_init; the serial registration stack is independent of it.

The developer’s application initializes the serial transport before calling this API; the transport is not re-initialized by the Amazon Sidewalk stack. The completion callback is called from within the receive path of the registration exchange; it shall only record the completion, for example by setting a flag, and shall not call sid_serial_registration_process or sid_serial_registration_deinit.

SID_ERROR_NULL_POINTER is returned if the configuration pointer or the transport pointer is NULL.

SID_ERROR_ALREADY_INITIALIZED is returned if the serial registration stack is already initialized.

If a component of the serial registration stack fails to initialize, its error code is returned.

SID_ERROR_NONE is returned if the serial registration stack is initialized successfully.

struct sid_serial_registration_config {
    /* Application-provided serial/UART transport. The application must bring the transport up
     * (ifc->serial_init) before calling sid_serial_registration_init(); it is not re-initialized here. */
    const struct serial_ifc_context *ifc;
    /*
     * Invoked when the device becomes factory-registered. PRECONDITION: runs deep inside the RX /
     * handshake dispatch stack while the message manager still owns a live app_cmd (freed on unwind).
     * It MUST only set a flag. It MUST NOT call sid_serial_registration_process(), free resources, or
     * otherwise re-enter the manager or event queue.
     */
    void (*on_registration_done)(void *ctx);
    void *ctx;
};

/* Build the registration stack + wired PHY and register the completion callback. Does not trigger. */
sid_error_t sid_serial_registration_init(const struct sid_serial_registration_config *cfg);

static volatile bool registration_done;

static void on_registration_done(void *ctx)
{
    registration_done = true;
}

// The serial transport is provided by the developer's application, see the reference application
struct sid_serial_registration_config cfg = {
    .ifc = app_serial_registration_uart_get_context(),
    .on_registration_done = on_registration_done,
    .ctx = NULL,
};
sid_error_t ret = sid_serial_registration_init(&cfg);

3.31 sid_serial_registration_start

sid_serial_registration_start triggers the factory registration exchange: it sends the first frame to the host and returns immediately. The exchange is driven to completion by sid_serial_registration_process, and completion is reported through the callback registered with sid_serial_registration_init.

SID_ERROR_UNINITIALIZED is returned if sid_serial_registration_init has not been called.

SID_ERROR_NONE is returned if the first frame was sent; other error codes are those of the registration exchange.

/* Trigger the factory-registration exchange; sends the first frame and returns immediately. */
sid_error_t sid_serial_registration_start(void);

sid_error_t ret = sid_serial_registration_start();

3.32 sid_serial_registration_process

sid_serial_registration_process drives one non-blocking pass of the registration exchange: it receives and decodes the frames from the host, dispatches them, transmits the responses and runs the event queue. The developer’s application calls it from its main loop, from the moment the host may start registration until the completion callback has been called. It is a no-op before sid_serial_registration_init.

/* Drive one non-blocking pass of the registration exchange. Call from the app main loop. */
void sid_serial_registration_process(void);

while (!registration_done) {
    sid_serial_registration_process();
}

3.33 sid_serial_registration_deinit

sid_serial_registration_deinit tears down the serial registration stack and the wired link brought up by sid_serial_registration_init, in the reverse order of initialization. After it returns, sid_serial_registration_start and sid_serial_registration_process are safe no-ops until sid_serial_registration_init is called again. It shall be called from the main loop and never from the completion callback.

SID_ERROR_UNINITIALIZED is returned if the serial registration stack is not initialized.

SID_ERROR_NONE is returned if the serial registration stack is de-initialized successfully.

sid_error_t sid_serial_registration_deinit(void);

sid_error_t ret = sid_serial_registration_deinit();

3.34 sid_device_information_init

The Device Information module, including region reporting for Sidewalk internationalization (2.16), is initialized using the sid_device_information_init API. The API accepts a pointer to struct sid_device_info_config and the Sidewalk handle returned by sid_init. On initialization, the module stores the configuration and registers the GET_DEVICE_INFORMATION and DEVICE_CONFIGURATION command handlers. The configuration passed in config is not copied; the developer’s application shall keep it, and the callback structure and static device information it points to, in static storage for as long as the module is initialized.

sid_device_information_init does not validate handle — it is accepted even if NULL, since it is neither dereferenced nor stored. sid_device_information_init also does not detect or reject being called a second time without an intervening sid_device_information_deinit; a second call simply overwrites the stored configuration and re-registers the command handler table.

The sid_device_information_init API returns error code SID_ERROR_INVALID_ARGS if config is NULL.

The sid_device_information_init API returns error code SID_ERROR_NONE when the module is initialized successfully.

/**
 * Initializes the Device Information module, including region reporting,
 * and registers the GET_DEVICE_INFORMATION / DEVICE_CONFIGURATION command
 * handlers.
 *
 * @param[in] config The device information configuration. Must remain
 * valid for as long as the module is initialized.
 * @param[in] handle A pointer to the handle returned by sid_init()
 *
 * @returns #SID_ERROR_NONE in case of success.
 * @returns #SID_ERROR_INVALID_ARGS if config is NULL.
 */
sid_error_t sid_device_information_init(const struct sid_device_info_config *config,
                                         struct sid_handle *handle);

static struct sid_device_info_callbacks device_info_callbacks = {
    .context  = &g_app_context,
    .get_info = on_device_get_info,
    .set_info = on_device_set_info,
};

static const struct sid_device_info_config device_info_cfg = {
    .info      = &device_static_info,
    .callbacks = &device_info_callbacks,
};

/* After sid_init() returns a handle. The config must stay valid for the app lifetime. */
sid_error_t ret = sid_device_information_init(&device_info_cfg, sidewalk_handle);

3.35 sid_device_information_deinit

The Device Information module can be de-initialized using the sid_device_information_deinit API. The API takes no arguments. It clears the stored configuration and deregisters the GET_DEVICE_INFORMATION and DEVICE_CONFIGURATION command handlers.

The sid_device_information_deinit API always returns SID_ERROR_NONE.

/**
 * Deinitializes the Device Information module and deregisters its
 * command handlers.
 *
 * @returns #SID_ERROR_NONE always.
 */
sid_error_t sid_device_information_deinit(void);

sid_error_t ret = sid_device_information_deinit();

3.36 sid_device_information_is_region_registerable

sid_device_information_is_region_registerable reports whether the configured region permits registration and radio bring-up on the sub-GHz links. It takes no arguments: it reads the region through the get_info callback of the configuration most recently passed to sid_device_information_init, rather than through a Sidewalk handle.

The Amazon Sidewalk stack calls this function internally from sid_start() (3.5), which masks link_mask down to SID_LINK_TYPE_1 (BLE) when this function returns false, rather than refusing to start outright. Integrators do not normally call it directly. See 2.16.4 for the full effect on sid_start(), including the case where masking leaves no link to start.

If the Device Information module was never initialized, sid_device_information_is_region_registerable returns true, matching the legacy, pre-i18n behavior described in 2.16.5.

/**
 * Returns whether the configured region permits registration and radio
 * bring-up on the sub-GHz links. Called internally by the Sidewalk stack
 * from sid_start().
 *
 * @returns true if the region is NA, EU, or ANZ, or if the Device
 * Information module is not initialized.
 * @returns false if the region is unset or unsupported (e.g. Japan).
 */
bool sid_device_information_is_region_registerable(void);