Provision your Amazon Sidewalk Device#

Firmware running on an embedded device forms only part of an Amazon Sidewalk solution. Cloud resources must be created to recognize and process data moving through the network between AWS Services and your endpoint. Credentials must be generated and written to the device so that it is accepted and granted access to the Sidewalk network by in-range gateways.

AWS CloudFormation#

AWS CloudFormation is a service that helps you model and set up your AWS resources so that you can spend less time managing those resources and more time focusing on your applications that run in AWS. You create a template that describes all the AWS resources that you want (like Amazon EC2 instances or Amazon RDS DB instances), and CloudFormation takes care of provisioning and configuring those resources for you. You do not need to individually create and configure AWS resources and figure out dependencies, because CloudFormation handles that on your behalf.

The Hello Neighbor example depends on AWS resources created using AWS CloudFormation. In the graphic below, green indicates the resources created by the CloudFormation script and yellow indicates the resources strictly associated with a device. The red arrows show the flow of information before an action can be performed on the cloud side.

Sidewalk SDK

Even with helpful task aggregator tools like CloudFormation, many steps are involved with the process to create and interlink these resources. Silicon Labs provides Sidewalk developers with a tool to rapidly accomplish these tasks for our example applications.

Sidewalk Assistant#

After creating your example project, when your new .slcp project file opens an additional tab sidewalk.asconf containing the Sidewalk Assistant tool also appears. If you had closed your project tabs you can reopen them by going to the root of the project folder in Project Explorer view, and double-clicking the .slcp and .asconf files.

The Sidewalk Assistant tool abstracts multiple underlying scripted interactions via AWS CLI (or manual interactions with the AWS Management Console) into an intuitive graphical user interface that vastly simplifies these operations. Using this tool allows you to focus on the high-level results of your development, rather than the details of each step. You can delve deeper into these details later, when you are ready to move beyond the simplistic AWS constructs of our example applications.

Sidewalk Assistant: AWS Credentials & Selected Device#

The sidewalk.asconf file (in /config/sidewalk/ within the project directory) opens in the Sidewalk Assistant on project creation, or you can access the tool by navigating to and opening the .asconf file.

The tool automatically scans your system for appropriate AWS credentials, established when AWS CLI was installed and AWS accounts created previously, and indicates that no target device is yet selected:

Sidewalk SDK

Click Select Device to open the Connection Manager dialog and choose from any of the attached devices (the checkbox at top right filters the list to those devices with Sidewalk support).

Sidewalk SDK

The Sidewalk Assistant contains two primary pages, the Cloud Infrastructure page and the End Device page.

Sidewalk Assistant: Cloud Infrastructure#

Initially, for a new project the Sidewalk Assistant Cloud Infrastructure page may look like this:

Sidewalk SDK

The CloudFormation Template used by this example is described in the top section. The AWS Stack name defined in the project is also visible.

Clicking Create Stack triggers the creation of the stack using AWS CloudFormation. The interface displays 'Creation in Progress' during the process. You may have to click the Refresh Data control multiple times, until the results are ready. When stack creation is successfully completed, the AWS Stack section now displays details about the new stack and a DELETE STACK control.

Sidewalk SDK

Sidewalk Assistant: End Device#

The cloud must be provided with a virtual representation of your device, and a "manufacturing page" must be created from the AWS resources that will equip the endpoint with necessary cryptographic resources to successfully authenticate and encrypt/decrypt traffic to/from your AWS resources in the Sidewalk network.

The manufacturing page is a .s37 binary file containing the keys and certificates for your device that will be flashed to a specific address. (.s37 files contain the program bytes and the target address.) To let the Sidewalk Assistant design your virtual device in the cloud and generate a manufacturing page for your physical endpoint, click the CREATE AWS DEVICE AND MANUFACTURING PAGE button.

Sidewalk SDK

When this first step is complete, the Virtual AWS Device section displays details of the newly-created virtual device.

The GUI also now provides a FLASH TO DEVICE control - click this to flash the manufacturing page to your endpoint. This complements the application image already flashed to the device in a previous step.

Sidewalk SDK

If successful, the End Device page should now display details for both the virtual and physical devices.

Sidewalk SDK

⚠ WARNING ⚠: The FLASH TO DEVICE control used above currently also performs an initial mass-erase operation before writing the manufacturing image to the device. This means the application image flashed in the previous step is NOT retained. To restore the primary application image, repeat the Compile and Flash the Project step in the previous section before continuing with these instructions.

Check the Device Registration and Time Sync#

Recall that in Create and Compile your Sidewalk Application you saw the following log from your device:

00> [00000000] <info> App - sid_ble application started
00> [00000050] <info> MFG NVM3 start info:
00>  OK
00>
00> [00000100] <info> KV NVM3 start info:
00>  OK
00>
00> [00000101] <info> MFG Store opened with 0 objects
00>
00> > [00000102] <error> Sall mgm core create failed: -8
00> [00000103] <error> App - failed to initialize sidewalk: -8
00> [00000103] <error> App - fatal error
...

Now that you've used the Sidewalk Assistant to flash the manufacturing page, if you return to the RTT Viewer (you may need to reset the device and/or reconnect the RTT Viewer), you will see the following log from your device:

[00000000] <info> App - sid_ble application started
[00000011] <info> MFG NVM3 start info:
 OK

[00000022] <info> KV NVM3 start info:
 OK

[00000023] <info> MFG Store opened with 36 objects

> [00000116] <info> DR state [1]
[00000138] <info> App - sidewalk status changed: 1
[00000139] <info> App - registration status: 1, time sync status: 1, link status: 0
...

The following log snippet contains three statuses:

[00000139] <info> App - registration status: 1, time sync status: 1, link status: 0

  • registration status

    Registration status indicates if the device is registered on Amazon's backend or not.

    • 0: the device is registered

    • 1: the device is not registered

  • time sync status

    Time sync status indicates if the device has synchronized its current time with the gateway or not. You need to be time-synchronized in order to send and receive messages.

    • 0: time is synchronized

    • 1: time is not synchronized

  • link status

    Link status displays the currently active communication channel.

    • 0: No connection

    • 1: BLE

    • 2: FSK

    • 4: CSS

For your device to communicate properly, registration status and time sync must be 0. If the endpoint is in-range of a Sidewalk gateway, this process (registration, if a new device, followed by successful time synchronization) should occur within a few minutes. Continue to Interacting with the Cloud to see how to fully exercise this example application in both directions across the Sidewalk network.