Register and test your Sidewalk endpoint

Step 3: Register and test your Sidewalk endpoint

After you’ve provisioned the Sidewalk endpoint, the endpoint must be registered so that it can communicate over the Sidewalk network. In this tutorial, you’ll learn about registering the endpoint using different registration methods.

Sidewalk registration methods

To register your Sidewalk endpoint, either use automatic touchless registration with Sidewalk Frustration Free Networking (FFN), or manually register your device using a Mac or native Ubuntu machine that runs the registration script. The following table shows the differences between the two methods.

FFN and manual registration methods

Criteria	Automatic registration (using Sidewalk FFN)	Manual registration
User and endpoint association	This registration method doesn’t require any association between the Sidewalk endpoint and a user. The endpoint can join the Sidewalk network without being associated with any user.	This registration method requires an association between the Sidewalk endpoint and a user’s Amazon account.
LWA (Login with Amazon)	LWA is not required.	LWA is required to link the user’s Amazon account and the AWS account that’s used by the Sidewalk endpoint developer.

Automatic touchless registration using Sidewalk FFN

Automatic touchless registration using Sidewalk frustration-free networking (FFN) is a registration process that automatically registers your Sidewalk endpoint over BLE. The registration process starts automatically when your Sidewalk gateway and your unregistered endpoint are in close range of each other. Your endpoint sends BLE beacons that are received by the Sidewalk gateway when the devices are in close proximity.

Set up to view FFN logs
To view the logs for the FFN registration process, follow these steps. For more information, see Set up for testing your Sidewalk device.

Connect the hardware development kit (HDK) to your computer using USB.
Power cycle the hardware by toggling the USB switch, and then power it on.
Connect to your hardware by following the instructions in the vendor documentation.

How FFN works
To perform registration using Sidewalk FFN:

Your Sidewalk gateway and endpoint must be powered on.
Your gateway must be opted into Sidewalk, and in close range to your endpoint. We recommend that you keep the devices within 10 meters of each other.

The registration process will start automatically, and a successful registration is indicated with Registration Status of zero, as seen in this log output. The Time Sync Status of zero indicates a successful time sync.

≪info> app: Registration Status = 0, Time Sync Status = 0 and Link Status = 0

If you don’t see this output, try either of the following steps:

Confirm that your Sidewalk endpoint is powered on. If needed, reboot your Sidewalk endpoint.
Confirm that your Sidewalk gateway is powered on, has internet connection, and is registered to a user with Sidewalk consent enabled. If needed, reboot your Sidewalk gateway and wait for 10 minutes for the gateway to be ready to retry the registration process.

De-register your Sidewalk endpoint
In certain cases, you might want to de-register your Sidewalk endpoint. For example, when testing the registration process multiple times, you must de-register your Sidewalk endpoint before attempting to re-register it.

De-registering your Sidewalk endpoint requires a two-way message exchange between the endpoint, gateway, and the cloud. To avoid any out-of-sync issues between your endpoint and the cloud, your Sidewalk gateway must be powered on, and in range of the registered endpoint.

You use the AWS API to de-register the endpoint. To de-register, run the following curl command. Replace:

AWS_ACCESS_KEY and AWS_SECRET_KEY with the credentials you obtained when setting up your account and configuring the AWS CLI.
WIRELESS_DEVICE_ID with the ID of your Sidewalk device.

curl -X PATCH "https://api.iotwireless.us-east-1.amazonaws.com/wireless-devices/WIRELESS_DEVICE_ID/deregister?WirelessDeviceType=Sidewalk" 
     --user <AWS_ACCESS_KEY>:<AWS_SECRET_KEY> 
     --aws-sigv4 "aws:amz:us-east-1:iotwireless"

A successful de-registration is indicated by a status of 200 or 202, and will have the following log output:

<info> app: Registration Status = 1, Time Sync Status = 1 and Link Status = 1

Manual Sidewalk registration

You can also register your Sidewalk endpoint using an Ubuntu machine with a BLE adapter that runs a local registration script. You must associate your registered Sidewalk endpoint with your Amazon account.

How manual registration works
To run the registration process, login to your Amazon account and grant Amazon Sidewalk permissions to complete the Sidewalk registration for your device. You’ll create a Login with Amazon (LWA) security profile and register your device by running the sid_pc_link script. The script sends commands to your device while communicating with the Sidewalk Cloud and the application server to authenticate and register your device. Your device can then connect to Amazon Sidewalk.

Create an LWA security profile
To create a security profile, go to the Login with Amazon Console portal in the developer dashboard and then choose Create a New Security Profile.

To access the dashboard, log in with your Amazon developer credentials. If you don’t have an Amazon developer account, you can create one and then go to the dashboard.

Specify a name and description for your security profile, and the Consent Privacy Notice URL, and then choose Save. The following image shows an example of a security profile added using Amazon’s privacy policy URL. Replace the URL with a link to your own Data Privacy policy.
In Login with Amazon Configurations, choose Show Client ID and Client Secret and copy your Client ID and Client Secret Key. Temporarily store it, as you’ll use it later to complete the Sidewalk endpoint registration.
Choose and then choose Web Settings. In the Web Settings tab, choose Edit and enter the value http://localhost:8000/ for Allowed Origins. Choose Save.

Run the registration script
To run the script, first configure the LWA client information, and then configure the registration script.

Configure LWA client information

To configure LWA client information, perform the following steps:

Navigate to registration folder

Go to the sid_pc_link/apps/device_registration/ folder.

cd ${SIDEWALK_SDK_PATH}/apps/common/sidewalk_sdk/tools/sid_pc_link/apps/device_registration

Retrieve LWA token

Run the following Python commands to open an LWA token, or an LWA token and a Refresh token. To run the commands, you must specify your Client ID and Client Secret Key. You obtained these values when adding the LWA security profile.
- To fetch only an LWA token, use the -lwa option with your Client ID, client_id.
```
 python3 main.py --lwa --client-id client_id
```
- To fetch an LWA token and a Refresh token, use the -lwa-cg option with your Client ID, client_id and your Client Secret Key, client_secret.
```
 python3 main.py --lwa-cg --client-id client_id --client-secret client_secret
```
Running these commands will launch a web browser and request your Amazon Developer account credentials. Choose allow pop-ups. The LWA and Refresh token will be automatically populated in your app_config.json file.
Refresh LWA token

The Refresh token is always valid but the LWA token is valid for only an hour. To refresh the LWA token, use the -refresh-token option with your Client ID, client_id and your Client Secret Key, client_secret.
```
❯ python3 main.py --refresh-token --client-id client_id --client-secret client_secret
```
Configure and run registration script

To configure the registration script perform the following steps:

Set bluetooth adapter and endpoint ID

In the app_config.json file, set the following values:

BLUETOOTH_ADAPTER: To get the adapter value, run hcitool devices.
ENDPOINT_ID: This is the device’s SMSN (Sidewalk Manufacturing Serial Number). The tool uses your device’s SMSN to identify and connect to your Development Kit, as Sidewalk endpoint.

Following shows an example app_config_for_LWA.

{
      
   "REGISTRATION_ENVIRONMENT": "prod",
   "BLUETOOTH_ADAPTER": "hci1",
   "COMMAND_TIMEOUT": "10",
   "GATEWAY_ID": null,         
   "ENDPOINT_ID": "17ED96BEA09BDDA42CE0C9D002AC878FBB7C695E1C0025C3BFE9740A9E3B7BD3",         
   "AUTH_TOKEN": null,         
   "LWA_TOKEN": "Bearer Atza|...",         
   "SCAN_RETRIES": "5",         
   "BLUETOOTH_SCAN_TIMEOUT": "5"
}

Install requirements file

Run the following command to install the requirements file.
```
pip3 install --user -r requirements.txt
```
Run registration script

Run the following command to run the registration script.
```
python3 main.py -r
```

Set up for testing your Sidewalk device

To view the logs for testing your Sidewalk device, perform the following steps to connect to your HDK, and to connect your Sidewalk device.

Connect the HDK to your computer using a USB cable.
Power cycle the hardware by toggling the switch that’s situtated beside the USB port on the HDK, and then set it to the ON position.
Connect to your hardware by following the instructions in the documentation for your HDK. One way to connect to the device and view log messages is using telnet.
- For Nordic Semiconductor’s HDK, see the Nordic Semiconductor documentation.
- For Silicon Laboratories’ HDK, see the Silicon Laboratories documentation.
- For Texas Instruments’ HDK, see the Texas Instruments documentation.
To connect your device to the AWS Cloud and view messages that are exhanged between your device and the cloud, you must create a Sidewalk destination. A destination describes the AWS IoT rules that process and route messages between your devices and other AWS services and other applications.

For more information about adding a destination, see Add a destination to AWS IoT Core for Amazon Sidewalk in the AWS IoT Core Developer Guide.