Stack Structure#
The following figure describes the firmware structure that integrates the Amazon Sidewalk protocol stack and enables Amazon Sidewalk connectivity for the end device. The Platform Abstraction Layer assures communication between Silicon Labs Simplicity SDK and the Amazon Sidewalk protocol stack. The developer creates applications on top of the stack, which Silicon Labs provides as a precompiled library.
The Amazon Sidewalk stack contains the following blocks:
Application Layer Library: Contains API call definitions to be used in application development.
BLE Network Interface: Contains Amazon Sidewalk-specific configuration for the Bluetooth LE (BLE) link layer.
Sub-GHz Network Interface: Contains Amazon Sidewalk-specific configuration for sub-GHz link layer and Semtech drivers.
MAC Layer: Amazon Sidewalk implementation of the MAC layer.
Dependencies#
The following software components are used by the stack:
FreeRTOS: Used as a base to run the stack.
PSA crypto: Used for all cryptographic operation.
BLE stack: Used to access the BLE stack.
SPI driver: Used only in sub-GHz-enabled applications, for communication with a third-party sub-GHz radio module.
RAIL: Used to access the radio and high-precision timers.
Library Files#
Amazon Sidewalk extension contains three library files: one for the Sidewalk stack, one for the BLE stack and the last one for the Semtech chip driver. The Silicon Labs Platform Abstraction Layer is available in source in the extension.
Software Components#
The Amazon Sidewalk extension includes the following software components. Each component can be used in a custom application. Each is described and documented in the following sections.
Sidewalk
Protocol
Amazon Sidewalk: the Amazon Sidewalk stack base component
Sidewalk NVM3 Migrator: a tool to migrate to the new NVM3 architecture starting Sidewalk 2.0.0
Utility
Logs: the component that allows to control the logs level and output
Sidewalk Application Message Structure: an example of lightweight message structure for Sidewalk messages
Sidewalk utils: a toolkit with useful functions to retrieve information on the device (extract SMSN from manufacturing page for example)
Amazon Sidewalk#
Sidewalk NVM3 Migrator#
This component is responsible for automatically handling the changes in the NVM3 structure around the Sidewalk SDK 1.16 release (Sidewalk extension 2.0.0). More precisely, it migrates NVM3 data from the previous unversioned Silabs-specific structure to a new structure which also got a version number, namely 1.0.0.0. This includes migration of manufacturing page (MFG) and Key-Value storage data (the KV storage handles the state of the Sidewalk stack) and other Silabs-specific NVM3 data as well.
The goal is to provide seamless transition to the new structure by simply adding this component, and calling its single API function.
For more information about the latest NVM3 organization, refer to Non-Volatile Memory Management in Sidewalk Context.
You can also refer to the NVM3 Migrator component readme.
The rework of the NVM3 organization has two important advantages:
Reduce the flash usage to store the same information.
The address of the reserved space for the default NVM3 instance can be easily changed, thus changing MFG and KV storage address seamlessly.
The following schema shows the main stages of the memory migration.
Before migration, we see the assumed original NVM3 structure.
NVM3 data is placed at the end of the flash.
The MFG and KV instances are 0x6000 large.
The size of the original NVM3 Default instance is also 0x6000 by default.
When we start migration we expect that the user flashed a new application containing the migrator component, and left the NVM3 data intact.
The new application shall not overlap with the original NVM3 data.
After the migration we see the new NVM3 structure containing MFG and KV storage data.
The full migration process is shown in the following flow diagram:
Logs#
The purpose of this group of software components is to facilitate the redirection of app, stack, or PAL logs to VCOM or separate RTT terminals. It consists of six components, all dependent on the Log component and available in both RTT and UART versions: Sidewalk Log: App, Sidewalk Log: PAL, and Sidewalk Log: stack.
There are three distinct layers (app, stack, and PAL) whose log configurations can be managed independently. This per-layer configuration includes the following three aspects:
Enabling or disabling logs
Changing the severity level
Changing the RTT terminal ID (specific to logs redirected to the RTT interface)
At least one software component (RTT or VCOM) per layer must be selected. To completely disable the logs, the chosen component can be configured accordingly. By default, all applications use the RTT interface to display logs.
To display logs or switch the log output from RTT to UART, refer to Testing and Debugging documentation.
Sidewalk Application Message Structure#
The Sidewalk Application Message component is a software module designed to facilitate the transfer of commands and associated data across the Sidewalk network with minimal metadata. It operates on a TLV (tag-length-value) data protocol, which simplifies the process of sending commands with associated data, making it somewhat analogous to the RPC protocol in functionality.
This component's role is to package the data intended for transmission with essential metadata (such as protocol version, command class, command ID, payload length, etc.). The application is then responsible for sending this packaged data as a Sidewalk application message through the Sidewalk network. The message structure aims to be as lightweight as possible and only adds 4 bytes of metadata to the actual message data.
For instance, consider the process of sending a notification to the cloud application when a user presses a button. The application will invoke the necessary functions to encapsulate the button's state and assign the appropriate metadata for the button press event. After the application data is wrapped in the data protocol, it is transmitted over the Sidewalk network by the application.
Credentials Backup/Restore Feature#
The out-of-the-box (OOB) application provided with the Pro Kit has a feature that allows users to erase the flash memory without losing the device private keys and other device-specific information. The feature relies on the user data partition that is not affected by mass-erase but it can still be erased. This feature can be used alongside Secure Vault seamlessly.
The manufacturing page needs to persist in order for the application to work in the Amazon Sidewalk network. This data can be divided in two groups, one for device-specific information and the other for information common to all devices created under the same device profile. As the capacity of the user data partition is quite limited, the common information is stored in the application code and only the device-specific information is backed up on the user data partition.
The following flow diagram shows the backup/restore feature workflow.
The Backup feature is used to copy device-specific information from the manufacturing page onto the user data partition. There is no need to copy common information as it is hard-coded in the application. Backup takes place when the application cannot detect any backed up data on the user data partition. This implies that, if the user data partition is erased but not the application, then the application will perform a backup process after each boot.
The Restore feature is used to copy device-specific information from the user data partition and common information from the OOB application code onto the manufacturing page. Restore takes place when the application cannot detect any valid manufacturing page. This implies that, if the device is mass-erased, then the application will perform a restore process after each boot and restore the whole manufacturing page.