# AWS IoT Core for Amazon Sidewalk
AWS IoT Core for Amazon Sidewalk provides the cloud services that you can use to connect your Sidewalk-enabled devices to the AWS Cloud and use other AWS services.
Amazon Sidewalk is a secure community network that uses Amazon Sidewalk Gateways (also called Sidewalk Bridges), such as compatible Amazon Echo and Ring devices, to provide cloud connectivity for IoT; endpoint devices. Amazon Sidewalk enables low-bandwidth and long-range connectivity at home and beyond using Bluetooth Low Energy for short-distance communication and LoRa and FSK radio protocols at 900MHz frequencies to cover longer distances.
AWS IoT Core for AWS IoT Core for Amazon Sidewalk acts as a bridge to move data between your Sidewalk -enabled devices and AWS Cloud services.
**Topics**
+ [Features of AWS IoT Core for Amazon Sidewalk](#sidewalk-features)
+ [Accessing AWS IoT Core for Amazon Sidewalk](#sidewalk-how-use)
+ [AWS IoT Core for Amazon Sidewalk Regions and endpoints](#sidewalk-regions-endpoints)
+ [AWS IoT Core for Amazon Sidewalk pricing](#iot-sidewalk-pricing)
+ [What is AWS IoT Core for Amazon Sidewalk?](what-is-iot-sidewalk.md)
+ [Get started using AWS IoT Core for Amazon Sidewalk](sidewalk-getting-started.md)
+ [Connecting to AWS IoT Core for Amazon Sidewalk](iot-sidewalk-onboard.md)
+ [Bulk provisioning devices with AWS IoT Core for Amazon Sidewalk](sidewalk-bulk-provisioning.md)
## Features of AWS IoT Core for Amazon Sidewalk
Using AWS IoT Core for Amazon Sidewalk, you can:
+ Onboard your Sidewalk end devices to AWS IoT using the AWS IoT console, AWS IoT Core for Amazon Sidewalk API operations, or AWS CLI commands.
+ Leverage the capabilities offered by the AWS Cloud.
+ Create a destination that uses AWS IoT rules to process incoming payload messages and to route the messages to over 20 AWS services and third-party applications.
+ Enable event notifications to receive messages about events such as when your Sidewalk end device has been provisioned or registered, or whether a downlink message has been successfully delivered to your device.
+ Log and monitor your Sidewalk end devices in real time, obtain useful insights, and identify and troubleshoot errors.
+ Associate your Sidewalk end devices with an AWS IoT thing, which helps you store a representation of your device on the cloud. Things in AWS IoT make it easier to search and manage your features, and access other AWS IoT Core features.
+ Enable "Position" to resolve the location data of your Amazon Sidewalk enabled devices in the cloud. For more information, see [Introduction to onboarding your Sidewalk devices](sidewalk-getting-started.md#sidewalk-gs-workflow)..
## Accessing AWS IoT Core for Amazon Sidewalk
You can onboard your Sidewalk end devices to AWS IoT by using the console or the AWS IoT Wireless API operations. After your devices are onboarded, their messages are sent to AWS IoT Core. You can then start developing your business applications on the AWS Cloud, which uses the data from your Amazon Sidewalk end devices.
**Using the console**
To onboard your Sidewalk end devices, sign in to the AWS Management Console and navigate to the [Devices](https://console.aws.amazon.com//iot/home#/wireless/devices) page on the AWS IoT console. After your devices are onboarded, you can view and manage them on this page of the IoT console.
**Using the API or CLI**
You can onboard both Sidewalk and LoRaWAN devices by using the [AWS IoT Wireless API operations](https://docs.aws.amazon.com/iot-wireless/latest/apireference/). The AWS IoT Wireless APIs are part of the AWS IoT Core and are supported by the AWS SDK. For more information, see [AWS SDKs and Toolkits](https://aws.amazon.com/developer/tools/).
You can use the AWS CLI to run commands for onboarding and managing your Sidewalk end devices. For more information, see [AWS IoT Wireless CLI reference](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/index.html).
## AWS IoT Core for Amazon Sidewalk Regions and endpoints
Amazon Sidewalk is only available in the `us-east-1` AWS Region. AWS IoT Core for Amazon Sidewalk provides support for control plane and data plane API endpoints in this Region. The data plane API endpoints are specific to your AWS account. For more information, see see [AWS IoT Wireless Service endpoints](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#iot-wireless_region) in the *AWS General Reference*.
AWS IoT Core for Amazon Sidewalk has quotas that apply to device data that is transmitted between the device and the AWS Cloud, and the maximum TPS for the AWS IoT Wireless API operations. For more information, see [AWS IoT Wireless quotas](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#wireless-limits) in the *AWS General Reference*.
## AWS IoT Core for Amazon Sidewalk pricing
When you sign up for AWS, you can get started with AWS IoT Core for Amazon Sidewalk for no charge by using the [AWS Free Tier](https://aws.amazon.com/free/).
For more information about general product overview and pricing, see [AWS IoT Core pricing](https://aws.amazon.com/iot-core/pricing/).
# What is AWS IoT Core for Amazon Sidewalk?
With AWS IoT Core for Amazon Sidewalk, you can onboard your Amazon Sidewalk end devices to AWS IoT and manage and monitor them. It also manages the destinations that send device data to other AWS services.
The following topics will help you learn about Amazon Sidewalk and AWS IoT Core for Amazon Sidewalk.
**Topics**
+ [What is Amazon Sidewalk?](#amazon-sidewalk-overview)
+ [How AWS IoT Core for Amazon Sidewalk works](#iot-sidewalk-works)
+ [Get started using AWS IoT Core for Amazon Sidewalk](#sidewalk-doc-using)
+ [Learn more about AWS IoT Core for Amazon Sidewalk](#iot-sidewalk-learn-more)
## What is Amazon Sidewalk?
### Features of Amazon Sidewalk
The following are features of Amazon Sidewalk.
+ Amazon Sidewalk creates a low-bandwidth network using Sidewalk gateways (including Ring and select Echo devices) which share a portion of their internet bandwidth. This bandwidth is used to connect your Sidewalk-enabled devices to the Amazon Sidewalk network using the AWS IoT Core for Amazon Sidewalk service.
+ Amazon Sidewalk offers a secure networking mechanism with multiple layers of encryption and security.
+ Amazon Sidewalk offers a simple mechanism to enable or disable participation in Sidewalk.
### Amazon Sidewalk concepts
The following are some key concepts of Amazon Sidewalk.
**Sidewalk gateways**
[Sidewalk gateways](https://docs.sidewalk.amazon/introduction/sidewalk-gateways), or Amazon Sidewalk bridges, route data between your Sidewalk end devices and the cloud. Gateways are Amazon devices, such as the Echo device or the Ring Floodlight Cam, that support SubG-CSS (asynchronous, LDR), SubG-FSK (synchronous, HDR), or Bluetooth LE for Sidewalk communication. Sidewalk gateways share a portion of your internet bandwidth with the Sidewalk community to provide connectivity to a group of Sidewalk-enabled devices.
**Sidewalk end devices**
Sidewalk end devices roam on Amazon Sidewalk by connecting to Sidewalk gateways. The end devices are low-bandwidth, low-power smart products, such as Sidewalk-enabled lights or door locks.
Certain Sidewalk gateways can also act as end devices.
**Sidewalk Network Server**
The Sidewalk Network Server, operated by Amazon, verifies the incoming packets and routes uplink and downlink messages to the desired destination, while keeping the Sidewalk network time-synchronized.
### Learn more about Amazon Sidewalk
For more information about Amazon Sidewalk, see the following web pages:
+ [Amazon Sidewalk](https://www.amazon.com/Amazon-Sidewalk/b?ie=UTF8&node=21328123011)
+ [Amazon Sidewalk documentation](https://docs.sidewalk.amazon/introduction/)
+ [AWS IoT Core for Amazon Sidewalk](https://aws.amazon.com/iot-core/sidewalk/)
## How AWS IoT Core for Amazon Sidewalk works
With AWS IoT Core for Amazon Sidewalk, you can onboard your Amazon Sidewalk end devices to AWS IoT and manage and monitor them. It also manages the destinations that send device data to other AWS services
AWS IoT Core for Amazon Sidewalk provides the cloud services that you can use to connect your Sidewalk end devices to the AWS Cloud and use other AWS services. You can also use AWS IoT Core for Amazon Sidewalk to manage your Sidewalk devices, and monitor and build applications on them.
Sidewalk end devices communicate with AWS IoT Core through Sidewalk gateways. AWS IoT Core for Amazon Sidewalk manages the service and device policies that AWS IoT Core requires to manage and communicate with the Sidewalk end devices and gateways. It also manages the destinations that send device data to other AWS services.
![\[\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/images/iot-sidewalk.png)
## Get started using AWS IoT Core for Amazon Sidewalk
You can use the AWS IoT console, the AWS IoT Core for Amazon Sidewalk API, or the AWS CLI to create and onboard Sidewalk end devices and connect them to the Sidewalk network. For information about getting started with Amazon Sidewalk and onboarding end devices to AWS IoT, see the following topics.
+
**[Get started using AWS IoT Core for Amazon Sidewalk](sidewalk-getting-started.md)**
This topic walks through the prerequisites for onboarding your Sidewalk end devices, illustrates the workflow using a sensor monitoring application, and provides an overview of how to onboard your device using AWS CLI commands.
+
**[Connecting to AWS IoT Core for Amazon Sidewalk](iot-sidewalk-onboard.md)**
This section describes the different steps in the onboarding workflow introduction, and walks through onboarding your end devices using the console, and the API operations. You'll also connect your device and view messages that are exchanged between your device and AWS IoT Core for Amazon Sidewalk.
+
**[Bulk provisioning devices with AWS IoT Core for Amazon Sidewalk](sidewalk-bulk-provisioning.md)**
This section provides a detailed step-by-step tutorial for bulk provisioning your Sidewalk end devices using AWS IoT Core for Amazon Sidewalk. You'll learn the bulk provisioning workflow, and how to onboard a large number of Sidewalk devices.
## Learn more about AWS IoT Core for Amazon Sidewalk
For more information about AWS IoT Core for Amazon Sidewalk, see the following web pages:
+ [Amazon Sidewalk](https://www.amazon.com/Amazon-Sidewalk/b?ie=UTF8&node=21328123011)
+ [Amazon Sidewalk documentation](https://docs.sidewalk.amazon/introduction/)
+ [AWS IoT Core for Amazon Sidewalk](https://aws.amazon.com/iot-core/sidewalk/)
# Get started using AWS IoT Core for Amazon Sidewalk
This section shows you how to get started with connecting your Sidewalk end devices to AWS IoT Core for Amazon Sidewalk. It explains how you can connect an end device to Amazon Sidewalk and pass messages between them. You'll also learn about the Sidewalk sample application and an overview of how to perform sensor monitoring using AWS IoT Core for Amazon Sidewalk. The sample application provides you with a dashboard to view and monitor changes to the sensor temperature.
![\[AWS account and environment set up for connecting devices to AWS IoT Core for Amazon Sidewalk.\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/images/sidewalk-getting-started.png)
The following topics will help you get started with AWS IoT Core for Amazon Sidewalk.
**Topics**
+ [Try the sensor monitoring tutorial](#sidewalk-gs-tutorial)
+ [Introduction to onboarding your Sidewalk devices](#sidewalk-gs-workflow)
## Try the sensor monitoring tutorial
This section provides you an overview of the Amazon Sidewalk sample application on GitHub that shows you how to monitor the temperature of a sensor. In this tutorial, you use scripts that programmatically create the required wireless resources, provision the end device and flash the binaries, and then connect your end device to the application. The scripts that use the AWS CLI and Python commands create an AWS CloudFormation stack and wireless resources, and then flash the binaries and deploy the application onto your hardware development kit (HDK).
The following diagram shows the steps are involved when you run the [sample application](https://github.com/aws-samples/aws-iot-core-for-amazon-sidewalk-sample-app) and connect your Sidewalk end device to the application. For detailed instructions including pre-requisites and configuration for this tutorial, see the [README document](https://github.com/aws-samples/amazon-sidewalk-sample-iot-app/blob/main/README.md) in *GitHub*.
![\[Application to monitor sensor temperature using AWS IoT Core for Amazon Sidewalk.\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/images/sidewalk-sensor-monitoring.png)
## Introduction to onboarding your Sidewalk devices
This section shows you how to onboard your Sidewalk end devices to AWS IoT Core for Amazon Sidewalk. To onboard your devices, first add your Sidewalk device, then provision and register your device, and then connect your hardware to the cloud application. Before running this tutorial, review and complete [Installing Python and Python3-pip](getting-started.md#wireless-onboard-prereq).
The following steps show you how to onboard and connect your Sidewalk end devices to AWS IoT Core for Amazon Sidewalk. If you want to onboard devices using the AWS CLI, you can refer to the sample commands provided in this section. For information about onboarding devices using the AWS IoT console, see [Connecting to AWS IoT Core for Amazon Sidewalk](iot-sidewalk-onboard.md).
**Important**
To perform the entire onboarding workflow, you must provision and register your end device, and connect your hardware development kit (HDK). For more information, see [Provisioning and registering your end device](https://docs.sidewalk.amazon/provisioning/) in the *Amazon Sidewalk documentation*.
**Topics**
+ [Step 1: Create a destination for your Sidewalk end device](#iot-sidewalk-qsg-step2)
+ [Step 2: Add your Sidewalk device to AWS IoT Core for Amazon Sidewalk](#iot-sidewalk-qsg-step1)
+ [Step 3: Provision and register the end device](#iot-sidewalk-qsg-step2)
+ [Step 4: Connect to Sidewalk end device and exchange messages](#iot-sidewalk-qsg-step4)
### Step 1: Create a destination for your Sidewalk end device
Here's an overview of the steps that you'll perform to add your destination to AWS IoT Core for Amazon Sidewalk. Using the AWS Management Console, or the AWS IoT Wireless API operations, or the AWS CLI, you run the following steps to create a destination which can be an AWS IoT rule or an MQTT topic. You can then connect to the hardware platform, and view and exchange messages. For a sample IAM role and AWS IoT rule used for the AWS CLI examples in this section, see [Create an IAM role and IoT rule for your destination](sidewalk-destination-rule-role.md).
Store the destination name you create in this step. You'll use this information when you create a wireless device.
1.
**Create IAM role**
Create an IAM role that grants AWS IoT Core for Amazon Sidewalk permission to send data to the AWS IoT rule. To create the role, use the [https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateRole.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateRole.html) API operation or [https://docs.aws.amazon.com/cli/latest/reference/iam/create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role) CLI command. You can name the role as *`SidewalkRole`*.
```
aws iam create-role --role-name lambda-ex \
--assume-role-policy-document file://lambda-trust-policy.json
```
1.
**Create an AWS IoT rule for the destination**
Create an AWS IoT rule that will process the device's data and specify the topic to which messages are published. You'll observe messages on this topic after connecting to the hardware platform. Use the AWS IoT Core API operation, [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRule.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRule.html), or the AWS CLI command, [https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html), to create a rule for the destination.
**Note**
You can also use an MQTT topic as a destination. For more information about how to create an MQTT topic, see [MQTT topics](https://docs.aws.amazon.com/iot/latest/developerguide/topics).
```
aws iot create-topic-rule --rule-name Sidewalkrule \
--topic-rule-payload file://myrule.json
```
1.
**Create a destination**
Create a destination that associates your Sidewalk device with the IoT rule (or MQTT topic) that processes it for use with other AWS services. You can add a destination using the [Destinations hub](https://console.aws.amazon.com/iot/home#/wireless/destinations) of the AWS IoT console, or the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateDestination.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateDestination.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/create-destination.html](https://docs.aws.amazon.com/cli/latest/reference/create-destination.html) CLI command. You'll send your Sidewalk end device's uplink data and location data to these destinations.
```
aws iotwireless create-destination --name SidewalkDestination \
--expression-type RuleName --expression SidewalkRule \
--role-arn arn:aws:iam::123456789012:role/SidewalkRole
```
Alternatively, if you want to provide an MQTT topic as the destination, replace the `expression-type` option with `MqttTopic` instead of `RuleName`. Replace *SidewalkRule* with the topic name.
### Step 2: Add your Sidewalk device to AWS IoT Core for Amazon Sidewalk
Here's an overview of the steps that you'll perform to add your Sidewalk end device to AWS IoT Core for Amazon Sidewalk. Store the information you obtain about the device profile and the wireless device that you create. You'll use this information to provision and register the end device. For more information about these steps, see [Add your device to AWS IoT Core for Amazon Sidewalk](iot-sidewalk-create-device.md).
1.
**Create a device profile**
Create a device profile that contains the shared configurations for your Sidewalk devices. When creating the profile, specify a *name* for the profile as an alphanumeric string. To create a profile, either go to the [Sidewalk tab of the Profiles hub](https://console.aws.amazon.com/iot/home#/wireless/profiles?tab=sidewalk) in the AWS IoT console and choose **Create profile**, or use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateDeviceProfile.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateDeviceProfile.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/create-device-profile.html](https://docs.aws.amazon.com/cli/latest/reference/create-device-profile.html) CLI command as shown in this example.
```
// Add your device profile using a name and the sidewalk object.
aws iotwireless create-device-profile --name sidewalk_profile --sidewalk {}
```
1.
**Create your Sidewalk end device and optionally get the device location**
1.
**Create your Sidewalk end device**
Create your Sidewalk end device with AWS IoT Core for Amazon Sidewalk. Specify a destination name and the ID of the device profile obtained from the previous step. To add a device, either go to the [Sidewalk tab of the Devices hub](https://console.aws.amazon.com/iot/home#/wireless/devices?tab=sidewalk) in the AWS IoT console and choose **Provision device**, or use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateWirelessDevice.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateWirelessDevice.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/create-wireless-device.html](https://docs.aws.amazon.com/cli/latest/reference/create-wireless-device.html) CLI command as shown in this example.
**Note**
Specify a name for your destination that's unique to your AWS account and AWS Region. You'll use the same destination name when you add your destination to AWS IoT Core for Amazon Sidewalk.
```
// Add your Sidewalk device by using the device profile ID.
aws iotwireless create-wireless-device
--type "Sidewalk"
--name "sidewalk_device" \
--destination-name "SidewalkDestination" \
--sidewalk DeviceProfileId="12345678-234a-45bc-67de-e8901234f0a1"
```
1.
**(Optional) Create your Sidewalk end device and get the Sidewalk device location**
If you want to enable location data when you create your Sidewalk end device with AWS IoT Core for Amazon Sidewalk, enable positioning. Replace *LocationDestination* with the destination to which you want to send the device location data to. The destination can either be an AWS AWS IoT rule or an MQTT topic. You can use the destination you created in Step 1 above as your UplinkDestination. Alternatively, you can specify a different destination as LocationDestination.
AWS IoT Core for Amazon Sidewalk resolves the location of your Sidewalk end device using Bluetooth Low Energy (BLE), Wi-Fi, or GNSS uplink messages published by your Sidewalk end device. For more information on AWS IoT's location resolution capabilities, see [AWS IoT Core Device Location](https://docs.aws.amazon.com/iot/latest/developerguide/device-location.html).
**Note**
You must enable positioning to use the device location feature.
If you enable device location for the Sidewalk-enabled device, your raw uplink payload won't be propagated to the destination.
```
// Add your Sidewalk device by using the device profile ID.
aws iotwireless create-wireless-device --type "Sidewalk" --name ""sidewalk_device" \
--description "My Sidewalk Device Description" \
--positioning "Enabled" \
--destination-name "UplinkDestination" \
--sidewalk DeviceProfileId="12345678-234a-45bc-67de-e8901234f0a1",Positioning={DestinationName="LocationDestination"}
```
**Note**
For Bluetooth Low Energy based location, AWS IoT returns location coordinates based on the approximate location of nearby Sidewalk Gateways that are connected to Amazon Sidewalk and have the Community Finding feature enabled. Gateway Location Data is AWS Content and is provided to you solely for the purpose of assisting you in locating your devices that are connected to Amazon Sidewalk, and you must only use the data for that purpose. You must only use and access location data via the interface and functionality that we generally make available to you, and you must not attempt to re-identify, reverse engineer, or re-map any Gateway location data provided by us to you.
1.
**(Optional) Update your existing Sidewalk end device and get the device's location data**
If you've already provisioned a Sidewalk end device in AWS IoT Wireless, you can update the device to get the device location data.
**Note**
You must enable positioning to use the device location feature.
Replace *LocationDestination* with the destination name from the destination to which you want to send the device location data to.
```
aws iotwireless update-wireless-device --id wireless-device-id \
--positioning "Enabled" \
--sidewalk Positioning={DestinationName="LocationDestination"}
```
1.
**Get device profile and wireless device information**
Get the device profile and wireless device information as a JSON. The JSON will contain information about the device details, device certificates, private keys, `DeviceTypeId`, and the Sidewalk manufacturing serial number (SMSN).
+ If you're using the AWS IoT console, you can use the [Sidewalk tab of the Devices hub](https://console.aws.amazon.com/iot/home#/wireless/devices?tab=sidewalk) to download a combined JSON file for your Sidewalk end device.
+ If you're using the API operations, store the responses obtained from the API operations [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetDeviceProfile.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetDeviceProfile.html) and [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateWirelessDevice.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateWirelessDevice.html) as separate JSON files, such as *`device_profile.json`* and `wireless_device.json`.
```
// Store device profile information as a JSON file.
aws iotwireless get-device-profile \
--id "12345678-a1b2-3c45-67d8-e90fa1b2c34d" > device_profile.json
// Store wireless device information as a JSON file.
aws iotwireless get-wireless-device --identifier-type WirelessDeviceId \
--identifier "23456789-abcd-0123-bcde-fabc012345678" > wireless_device.json
```
### Step 3: Provision and register the end device
Using Python commands, you can provision and register your end device. The provisioning script uses the device JSON data that you obtained to generate a manufacturing binary image, which is then flashed on the hardware board. You then register your end device for connecting to the hardware platform. For more information, see [Provisioning and registering your end device](https://docs.sidewalk.amazon/provisioning/) in the *Amazon Sidewalk documentation*.
**Note**
When registering your Sidewalk end device, your gateway must be opted in to Amazon Sidewalk, and your gateway and device must be in range of each other.
### Step 4: Connect to Sidewalk end device and exchange messages
After you've registered your end device, you can then connect your end device and start exchanging messages and device data.
1.
**Connect your Sidewalk end device**
Connect the HDK to your computer and follow the instructions provided by the vendor documentation to connect to your HDK. For more information, see [Provisioning and registering your end device](https://docs.sidewalk.amazon/provisioning/) in the *Amazon Sidewalk documentation*.
1.
**View and exchange messages**
Use the MQTT client to subscribe to the topic specified in the rule and view the message received. You can also use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_SendDataToWirelessDevice.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_SendDataToWirelessDevice.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/send-data-to-wireless-device.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/send-data-to-wireless-device.html) CLI command to send a downlink message to your device and verify the connectivity status.
(Optional) You can enable the message delivery status event to check whether the downlink message was successfully received.
```
aws iotwireless send-data-to-wireless-device \
--id "" \
--payload-data "SGVsbG8gVG8gRGV2c2lt" \
--wireless-metadata Sidewalk={Seq=1,AckModeRetryDurationSecs=10}
```
# Connecting to AWS IoT Core for Amazon Sidewalk
This section shows you how to onboard your Sidewalk end device and then connect your device to the Sidewalk network. It describes the steps that you perform in the onboarding tutorial, as mentioned in [Introduction to onboarding your Sidewalk devices](sidewalk-getting-started.md#sidewalk-gs-workflow). You'll learn how to onboard devices by using the AWS IoT console and the AWS IoT Core for Amazon Sidewalk API operations. You'll also learn about the AWS CLI commands that perform these operations.
## Prerequisites
To add your end device and destination to AWS IoT Core for Amazon Sidewalk, you must set up your AWS account. To perform these operations using the AWS IoT Wireless API or the AWS CLI commands, you must also set up the AWS CLI. For more information about the prerequisites and setting up, see [Installing Python and Python3-pip](getting-started.md#wireless-onboard-prereq).
**Note**
To perform the entire onboarding workflow for provisioning and registering your end device, and connecting to your hardware development kit (HDK), you must also set up your Sidewalk gateway and HDK. For more information, see [Setting up the hardware development kit (HDK)](https://docs.sidewalk.amazon/getting-started/sidewalk-onboard-prereq-hdk.html) and [Setting up a Sidewalk gateway](https://docs.sidewalk.amazon/getting-started/sidewalk-onboard-prereq-gateway.html) in the *Amazon Sidewalk documentation*.
## Describing your Sidewalk resources
Before you get started and create the resources, we recommend that you consider the naming convention of your Sidewalk end devices, device profiles, and destinations. AWS IoT Core for Amazon Sidewalk assigns a unique identifier to the resources that you create. However, you can give them more descriptive names, add a description, or add optional tags to help identify and manage them.
**Note**
The destination name can't be changed after it's created. Use a name that's unique to your AWS account and AWS Region.
For more information, see [Describing your AWS IoT Wireless resources](getting-started.md#iotwireless-describe-resources).
**Topics**
+ [Prerequisites](#sidewalk-connect-prereq)
+ [Describing your Sidewalk resources](#sidewalk-connect-resources)
+ [Add your device to AWS IoT Core for Amazon Sidewalk](iot-sidewalk-create-device.md)
+ [Add a destination for your Sidewalk end device](iot-sidewalk-qsg-destination.md)
+ [Connect your Sidewalk device and view uplink metadata format](iot-sidewalk-connect-uplink-metadata.md)
+ [Using AWS Location with Sidewalk Devices](iot-device-location-feature-sidewalk-device.md)
# Add your device to AWS IoT Core for Amazon Sidewalk
Before creating a wireless device, first create a device profile. Device profiles define the device capabilities and other parameters for your Sidewalk devices. A single device profile can be associated with multiple devices.
After you create a device profile, when you retrieve information about the profile, it returns a `DeviceTypeId`. When you provision your end device, you'll use this ID, the device certificates, application server public key, and the SMSN.
## How to create and add your device
1. Create a device profile for your Sidewalk end devices. Specify a profile name to use for your Sidewalk devices as an alphanumeric string. The profile will help identify the devices to associate it with.
+ (Console) When adding your Sidewalk device, you can also create a new profile. This helps you quickly add your device to AWS IoT Core for Amazon Sidewalk and associate it with a profile.
+ (API) Use the `CreateDeviceProfile` API operation by specifying a profile name and the Sidewalk object, `sidewalk {}`. The API response will contain a profile ID and ARN (Amazon Resource Name).
1. Add your wireless device to AWS IoT Core for Amazon Sidewalk. Specify a destination name and choose the device profile that you created in the previous step.
+ (Console) When adding your Sidewalk device, enter a destination name, and choose the profile that you created.
+ (API) Use the `CreateWirelessDevice` API operation. Specify a destination name and the ID of the device profile obtained previously.
**Wireless device parameters**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/iot-sidewalk-create-device.html)
1. Obtain the JSON file that contains the required information for provisioning your end device.
+ (Console) Download this file from the details page of the Sidewalk device that you created.
+ (API) Use the `GetDeviceProfile` and `GetWirelessDevice` API operations to retrieve information about your device profile and wireless device. Store the API response information as JSON files, such as *`device_profile.json`* and *`wireless_device.json`*.
# Add your device profile and Sidewalk end device
This section shows how you can create a device profile. It also shows how you can use the AWS IoT console and the AWS CLI to add your Sidewalk end device to AWS IoT Core for Amazon Sidewalk.
## Add your Sidewalk device (console)
To add your Sidewalk device using the AWS IoT console, go to the [Sidewalk tab of the Devices hub](https://console.aws.amazon.com/iot/home#/wireless/devices?tab=sidewalk), choose **Provision device**, and then perform the following steps.
![\[Workflow for adding, provisioning, and registering your Sidewalk device to connect to the cloud.\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/images/iot-sidewalk-provision-device.PNG)
1.
**Specify device details**
Specify the configuration information for your Sidewalk device. You can also create a new device profile, or choose an existing profile for your Sidewalk device.
1. Specify a device name and optional description. The description can be up to 2,048 characters long. These fields can be edited after you create the device.
1. Choose a device profile to associate with your Sidewalk device. If you have any existing device profiles, you can choose your profile. To create a new profile, choose **Create new profile**, and then enter a name for the profile.
**Note**
To attach tags to your device profile, after you create your profile, go to the [Profiles hub](https://console.aws.amazon.com/iot/home#/wireless/profiles) and then edit your profile to add this information.
1. Specify the name of your destination that will route messages from your device to other AWS services. If you haven't already created a destination, go to the [Destinations hub](https://console.aws.amazon.com/iot/home#/wireless/destinations) to create your destination. You can then choose that destination for your Sidewalk device. For more information, see [Add a destination for your Sidewalk end device](iot-sidewalk-qsg-destination.md).
1. Choose **Next** to continue adding your Sidewalk device.
1.
**Associate Sidewalk device with AWS IoT thing (Optional)**
You can optionally associate your Sidewalk device to an AWS IoT thing. IoT things are entries in the AWS IoT device registry. Things make it easier to search and manage your devices. Associating a thing with your device lets your device access other AWS IoT Core features.
To associate your device with a thing, choose **Automatic thing registration**.
1. Enter a unique name for the IoT thing that you want to associate your Sidewalk device. Thing names are case sensitive and must be unique in your AWS account and AWS Region.
1. Provide any additional configurations for your IoT thing, such as using a thing type, or searchable attributes that can be used to filter from a list of things.
1. Choose **Next** and verify the information about your Sidewalk device, and then choose **Create**.
## Add your Sidewalk device (CLI)
To add your Sidewalk device and download the JSON files that will be used to provision your Sidewalk device, perform the following API operations.
**Topics**
+ [Step 1: Create a device profile](#iot-sidewalk-profile-create)
+ [Step 2: Add your Sidewalk device](#iot-sidewalk-device-create)
### Step 1: Create a device profile
To create a device profile in your AWS account, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateDeviceProfile.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateDeviceProfile.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/create-device-profile.html](https://docs.aws.amazon.com/cli/latest/reference/create-device-profile.html) CLI command. When creating your device profile, specify the name and provide any optional tags as name-value pairs.
For example, the following command creates a device profile for your Sidewalk devices:
```
aws iotwireless create-device-profile \
--name sidewalk_profile --sidewalk {}
```
Running this command returns the Amazon Resource Name (ARN) and the ID of the device profile as output.
```
{
"DeviceProfileArn": "arn:aws:iotwireless:us-east-1:123456789012:DeviceProfile/12345678-a1b2-3c45-67d8-e90fa1b2c34d",
"DeviceProfileId": "12345678-a1b2-3c45-67d8-e90fa1b2c34d"
}
```
### Step 2: Add your Sidewalk device
To add your Sidewalk device to your account for AWS IoT Core for Amazon Sidewalk, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateWirelessDevice.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateWirelessDevice.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/create-wireless-device.html](https://docs.aws.amazon.com/cli/latest/reference/create-wireless-device.html) CLI command. When creating your device, specify the following parameters, in addition to an optional name and description for your Sidewalk device.
**Note**
If you want to associate your Sidewalk device with an AWS IoT thing, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_AssociateWirelessDeviceWithThing.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_AssociateWirelessDeviceWithThing.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/associate-wireless-device-with-thing.html](https://docs.aws.amazon.com/cli/latest/reference/associate-wireless-device-with-thing.html) CLI command.
The following command shows an example of creating a Sidewalk device:
```
aws iotwireless create-wireless-device \
--cli-input-json "file://device.json"
```
The following shows the contents of the file `device.json`.
**Contents of device.json**
```
{
"Type": "Sidewalk",
"Name": "SidewalkDevice",
"DestinationName": "SidewalkDestination",
"Sidewalk": {
"DeviceProfileId": "12345678-a1b2-3c45-67d8-e90fa1b2c34d"
}
}
```
Running this command returns the device ID and Amazon Resource Name (ARN) as output.
```
{
"Arn": "arn:aws:iotwireless:us-east-1:123456789012:WirelessDevice/23456789-abcd-0123-bcde-fabc012345678",
"Id": "23456789-abcd-0123-bcde-fabc012345678"
}
```
#### (Optional) Create your Sidewalk end device and get the Sidewalk device location
If you want to enable location data when you create your Sidewalk end device with AWS IoT Core for Amazon Sidewalk, enable positioning. Replace *LocationDestination* with the destination name to which you want to send the device location data to.
**Note**
You must enable positioning to use the device location feature. If you enable device location for the Sidewalk-enabled device, your raw uplink payload won't be propagated to the destination.
```
// Add your Sidewalk device by using the device profile ID.
aws iotwireless create-wireless-device
--type "Sidewalk"
--name "sidewalk_device" \
--description "My Sidewalk Device Description" \
--destination-name "UplinkDestination" \
--positioning "Enabled" \
--sidewalk DeviceProfileId="12345678-234a-45bc-67de-e8901234f0a1",Positioning={DestinationName="LocationDestination"}
```
**Note**
For Bluetooth Low Energy based location, AWS IoT returns location coordinates based on the approximate location of nearby Sidewalk Gateways that are connected to Amazon Sidewalk and have the Community Finding feature enabled. Gateway Location Data is AWS Content and is provided to you solely for the purpose of assisting you in locating your devices that are connected to Amazon Sidewalk, and you must only use the data for that purpose. You must only use and access location data via the interface and functionality that we generally make available to you, and you must not attempt to re-identify, reverse engineer, or re-map any Gateway location data provided by us to you.
# Obtain device JSON files for provisioning
After you've added your Sidewalk device to AWS IoT Core for Amazon Sidewalk, download the JSON file that contains the information required to provision your end device. You can retrieve this information using the AWS IoT console or the AWS CLI. For more information about how to provision the device, see [Provisioning and registering your end device](https://docs.sidewalk.amazon/provisioning/) in the *Amazon Sidewalk documentation*.
## Obtain JSON file (console)
To obtain the JSON file for provisioning your Sidewalk device:
1. Go to the [Sidewalk devices hub](https://console.aws.amazon.com/iot/home#/wireless/devices?tab=sidewalk).
1. Choose the device that you added to AWS IoT Core for Amazon Sidewalk to view its details.
1. Obtain the JSON file by choosing **Download device JSON file** in the details page of the device that you added.
A `certificate.json` file will be downloaded that contains the required information for provisioning your end device. The following shows a sample JSON file. It contains the device certificates, private keys, the Sidewalk manufacturing serial number (SMSN), and the `DeviceTypeID`.
```
{
"p256R1": "grg8izXoVvQ86cPVm0GMyWuZYHEBbbH ... DANKkOKoNT3bUGz+/f/pyTE+xMRdIUBZ1Bw==",
"eD25519": "grg8izXoVvQ86cPVm0GMyWuZYHEBbbHD ... UiZmntHiUr1GfkTOFMYqRB+Aw==",
"metadata": {
"devicetypeid": "fe98",
"applicationDeviceArn": "arn:aws:iotwireless:us-east-1:123456789012:WirelessDevice/897ce68e-3ca2-4ed0-85a2-30b0666c4052",
"applicationDeviceId": "897ce68e-3ca2-4ed0-85a2-30b0666c4052",
"smsn": "82B83C8B35E856F43CE9C3D59B418CC96B996071016DB1C3BE5901F0F3071A4A",
"devicePrivKeyP256R1": "3e704bf8d319b3a475179f1d68c60737b28c708f845d0198f2d00d00c88ee018",
"devicePrivKeyEd25519": "17dacb3a46ad9a42d5c520ca5f47f0167f59ce54d740aa13918465faf533b8d0"
},
"applicationServerPublicKey": "5ce29b89c2e3ce6183b41e75fe54e45f61b8bb320efbdd2abd7aefa5957a316b"
}
```
In the details page of your Sidewalk device, you'll also see information about:
+ The device ID, its Amazon Resource Name (ARN), and details about any AWS IoT thing that the device is associated with.
+ The device profile and destination details.
+ The time at which the last uplink message was received from the device.
+ The status that indicates whether your device has been provisioned or registered.
## Obtain JSON file (CLI)
To obtain the JSON files for provisioning your Sidewalk end device using the AWS IoT Core for Amazon Sidewalk API or the AWS CLI, save the API response from retrieving information about your device profile and wireless device as JSON files, such as *`wireless_device.json`* and *`device_profile.json`* temporarily. You'll use them for provisioning your Sidewalk device.
The following shows how to retrieve the JSON files.
**Topics**
+ [Step 1: Get device profile information as JSON file](#iot-sidewalk-profile-get)
+ [Step 2: Get Sidewalk device information as JSON file](#iot-sidewalk-get-device)
### Step 1: Get device profile information as JSON file
Use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetDeviceProfile.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetDeviceProfile.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/get-device-profile.html](https://docs.aws.amazon.com/cli/latest/reference/get-device-profile.html) CLI command to get information about your device profile that you added to your account for AWS IoT Core for Amazon Sidewalk. To retrieve information about your device profile, specify the profile ID.
The API will then return information about the device profile matching the specified identifier and the device ID. You save this response information as a file, and give it a name such as *`device_profile.json`*.
The following shows an example CLI command:
```
aws iotwireless get-device-profile \
--id "12345678-a1b2-3c45-67d8-e90fa1b2c34d" > device_profile.json
```
Running this command returns the parameters of your device profile, the application server public key, and the `DeviceTypeID`. The following shows a JSON file that contains a sample response information from the API. For more information about the parameters in the API response, see [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetDeviceProfile.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetDeviceProfile.html).
**`GetDeviceProfile` API response (Contents of `device_profile.json`)**
```
{
"Arn": "arn:aws:iotwireless:us-east-1:123456789012:DeviceProfile/12345678-a1b2-3c45-67d8-e90fa1b2c34d",
"Id": "12345678-a1b2-3c45-67d8-e90fa1b2c34d",
"Name": "Sidewalk_profile",
"LoRaWAN": null,
"Sidewalk":
{
"ApplicationServerPublicKey": "a123b45c6d78e9f012a34cd5e6a7890b12c3d45e6f78a1b234c56d7e890a1234",
"DAKCertificateMetadata": [
{
"DeviceTypeId: fe98,
"CertificateId": "43564A6D2D50524F544F54595045",
"FactorySupport": false,
"MaxAllowedSignature": 1000
}
],
"QualificationStatus": false
}
}
```
### Step 2: Get Sidewalk device information as JSON file
Use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetWirelessDevice.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetWirelessDevice.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/get-wireless-device.html](https://docs.aws.amazon.com/cli/latest/reference/get-wireless-device.html) CLI command to get information about your Sidewalk device that you added to your account for AWS IoT Core for Amazon Sidewalk. To get information about your end device, provide the identifier of the wireless device that you obtained when adding your device.
The API will then return information about the device matching the specified identifier and the device ID. Save this response information as a JSON file. Give the file a meaningful name, such as *`wireless_device.json`*.
The following shows an example of running the command using the CLI:
```
aws iotwireless get-wireless-device --identifier-type WirelessDeviceId \
--identifier "23456789-abcd-0123-bcde-fabc012345678" > wireless_device.json
```
Running this command returns the device details, device certificates, private keys, and the Sidewalk manufacturing serial number (SMSN). The following shows an example output of running this command. For more information about the parameters in the API response, see [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetWirelessDevice.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetWirelessDevice.html).
**`GetWirelessDevice` API response (Contents of `wireless_device.json`)**
```
{
"Arn": "arn:aws:iotwireless:us-east-1:123456789012:WirelessDevice/23456789-abcd-0123-bcde-fabc012345678",
"Description": "test-description",
"DestinationName": "SidewalkDestination",
"Id": "23456789-abcd-0123-bcde-fabc012345678",
"LoRaWAN": "null",
"Name" : "test-name",
"Positioning": "Enabled"
"Sidewalk": {
"CertificateId": "4C7438772D50524F544F54595045",
"DeviceCertificates": [
{
"SigningAlg": "Ed25519",
"Value": "WUqB/E50VP7oZpHtYoBgpzJXYvhv51y/DBIfzNhrleo4UzOWCsIzbaJwft
+IPBSUQthDifJDYik0DuU1jLvuR8cpK7YyI7cUD/oZG+4Pro/s3nAIhy
XmhUlepmbveVxM8boiTiaUlL4iB9DoKrB41pWdHeg7hR8BDrE1m4sf5Q
9ZUwDy5BqMafeW0RUKZMVunpChji0dwC5VoSSb8IT7V+bKTJXXdZ8lP1
1jsiuJfwF64Eq1NCe2qKb7gql5u+qBE7vatDOSonwN56I6Ah8HWYRSyJ
Tk7DSJKknSY7KGyLjs0qMI8L8AeJ++UIO/jOsGnhC6Ku1ba62bEPmIBr
+889NhOngiIt1+1DrSOO59a1PLYqfVa5ejKq0tzzbyNG/m/oW72kkGGH
Ruec2zOXEO86kf4X0qzFfTKoo/6lt67XfXIQkO4wApCgJ8AHwHa3xz+d
h+W6mFwYFRqrQQT8s0SjSuDtLCaqZhnch47MZk7E/itqP4JnJ7RsJHWx
XsG2gTNlRghfG+zhpKzVVdvVVZeZ22f2WZ2QoGlzXxrW0/b7mqpO2l+8
fzRYYdqAp1AAADGz+gFBeX/ZNN8VJwnsNfgzj4me1HgVJdUo4W9kvx9c
r2jHWkC3Oj/bdBTh1+yBjOC53yHlQK/l1GHrEWiWPPnE434LRxnWkwr8
EHD4oieJxC8fkIxkQfj+gHh"
},
{
"SigningAlg": "P256r1",
"Value": "hDdkJw9L2uMCORjImjMHqzNR6nYYh6QKncSl5GthQNmHmGU8a+SOqDXWwDNt3
VSntpbTTQl7cMIusqweQo+JPXXWElbGh7eaxPGz4ZeF5yM2cqVNUrQr1l
X/6lZ+OLuycrFrLzzB9APi0NIMLqV/Rt7XJssHQs2RPcT1ul/2XVpa6zt
ULJeQi2JwhTb/k48wbh/EvafG/ibrIp4O3ZDa4f+5SVWvbY5eyDDXcohv
z/OcCtuRjAkzKBCvIjBDnCv1McjVdCO3+utizGntfhAo1RZstnOoRkgVF
2WuMT9IrUmzYximuTXUmWtjyFSTqgNBZwHWUTlMmjlpLCVzZQWM4zOisX
UAAALPsP34BS6EzJO5AsS5pC7QTpjBtAbLN9SdXOT9w4H1x8Nkp0ujLxW
RN37IEy0V9DrPK2w1g74uqWPfUPnSBjtvM55JnQpmm23WQNvHa1Vr6zmW
DjzjHpcNirPbzXyBlKEhkX4xylaSMnm4UrVXtAMaAJ/csC4HPTKr3dazd
vEkhwGAAAIFByCjSp/5WHc4AhsyjMvKCsZQiKgiI8ECwjfXBaSZdY4zYs
RlO3FC428H1atrFChFCZT0Bqt5LPXD38bMSB+vAUJiP8XqiEdXeqf2mYM
J5ykoDpwkve/cUQfPpjzFQlQfvwjBwiJDANKkOKoNT3bUGz+/f/pyTE+x
MRdIUBZ1Bw=="
}
],
"DeviceProfileId":"0ff5b0c6-f149-4498-af34-21993acd52a7",
"Positioning": {
"DestinationName": SidewalkLocationDestination,
},
"PrivateKeys": [
{
"SigningAlg": "Ed25519",
"Value": "2c24d4572327f23b9bef38097137c29224a9e979081b3d90124ac9dfa477934e"
},
{
"SigningAlg": "P256r1",
"Value": "38d526f29cfaf142f596deca187bd809ef71bc13435eedc885b63bb825d63def"
}
],
"SidewalkManufacturingSn": "843764270F4BDAE3023918C89A3307AB3351EA761887A40A9DC
4A5E46B6140D9",
"Status": "PROVISIONED"
},
"Type": "Sidewalk",
...
}
```
## Next steps
Store the JSON files, *`wireless_device.json`* and *`device_profile.json`* temporarily, as you'll use them in the next step to provision and register your end device for connecting to the hardware platform. For more information, see [Provisioning and registering your end device](https://docs.sidewalk.amazon/provisioning/) in the *Amazon Sidewalk documentation*.
# Add a destination for your Sidewalk end device
**Note**
For Bluetooth Low Energy based location, AWS IoT returns location coordinates based on the approximate location of nearby Sidewalk Gateways that are connected to Amazon Sidewalk and have the Community Finding feature enabled. Gateway Location Data is AWS Content and is provided to you solely for the purpose of assisting you in locating your devices that are connected to Amazon Sidewalk, and you must only use the data for that purpose. You must only use and access location data via the interface and functionality that we generally make available to you, and you must not attempt to re-identify, reverse engineer, or re-map any Gateway location data provided by us to you.
AWS IoT Core for Amazon Sidewalk destinations describe the AWS IoT rule or MQTT topic that processes a device's data for use by other AWS services and applications. Use AWS IoT rules or MQTT topics to process the data and device messages and route it to other services.
Because most Sidewalk devices don't send data to AWS IoT Core for Amazon Sidewalk in a format that can be used by AWS services, an AWS IoT rule must process it first. The AWS IoT rule contains the SQL statement that interprets the device's data and the topic rule actions that send the result of the SQL statement to the services that will use it.
The AWS IoT rule processes binary messages received from a device and converts the messages to other formats that make other services easy to use them. Destinations associate your Sidewalk end device with the rule that processes the device data to send to other AWS services. For more information about rules, see [Rules for AWS IoT](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html) in the *AWS IoT Core documentation*.
## How to create and use a destination
1. Create an AWS IoT rule and an IAM role for the destination. The AWS IoT rule specifies the rules that will process the device's data and routes it for use by other AWS services and your applications. The IAM role grants permission to access the rule.
1. Create a destination for your Sidewalk devices using the `CreateDestination` API operation. Specify the destination name, rule name, role name, and any optional parameters. The API will return a unique identifier for the destination, which you can specify when adding your end device to AWS IoT Core for Amazon Sidewalk.
The following shows how to create a destination, and an AWS IoT rule and IAM role for the destination.
**Topics**
+ [How to create and use a destination](#iot-sidewalk-destination-how)
+ [Create a destination for your Sidewalk device](iot-sidewalk-destination-create.md)
+ [Create an IAM role and IoT rule for your destination](sidewalk-destination-rule-role.md)
# Create a destination for your Sidewalk device
You can add a destination to your account for AWS IoT Core for Amazon Sidewalk either from the using the [Destinations hub](https://console.aws.amazon.com/iot/home#/wireless/destinations) or using the `CreateDestination`. When creating your destination, specify:
+ A unique name for the destination to use for your Sidewalk end device.
**Note**
If you already add your device using a destination name, you must use that name when creating your destination. For more information, see [Step 2: Add your Sidewalk device](iot-sidewalk-add-device.md#iot-sidewalk-device-create).
+ The name of the AWS IoT rule that will process the device's data, and the topic to which messages are published.
+ An IAM role that grants the device's data permission to access the rule.
The following sections describe how to create the AWS IoT rule and IAM role for your destination.
## Create a destination (console)
To create a destination using the AWS IoT console, go to the [Destinations hub](https://console.aws.amazon.com/iot/home#/wireless/destinations) and choose **Add destination**.
![\[Add a Sidewalk destination using the AWS IoT console.\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/images/iot-sidewalk-add-destination.PNG)
To process a device's data, specify the following fields when creating a destination, and then choose **Add destination**.
+
**Destination details**
Enter a **Destination name** and an optional description for your destination.
+
**Rule name**
The AWS IoT rule that is configured to evaluate messages sent by your device and process the device's data. The rule name will be mapped to your destination. The destination requires the rule to process the messages that it receives. You can choose for the messages to be processed by either invoking an AWS IoT rule or by publishing to the AWS IoT message broker.
+ If you choose **Enter a rule name**, enter a name, and then choose **Copy** to copy the rule name that you'll enter when creating the AWS IoT rule. You can either choose **Create rule** to create the rule now or navigate to the [Rules](https://console.aws.amazon.com/iot/home#/create/rule) Hub of the AWS IoT console and create a rule with that name.
You can also enter a rule and use the **Advanced** setting to specify a topic name. The topic name is provided during rule invocation and is accessed by using the `topic` expression inside the rule. For more information about AWS IoT rules, see [AWS IoT rules](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html).
+ If you choose **Publish to AWS IoT message broker**, enter a topic name. You can then copy the MQTT topic name and multiple subscribers can subscribe to this topic to receive messages published to that topic. For more information, see [MQTT topics](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html).
For more information about AWS IoT rules for destinations, see [Create rules to process LoRaWAN device messages](https://docs.aws.amazon.com/iot-wireless/latest/developerguide/lorawan-destination-rules.html).
+
**Role name**
The IAM role that grants the device's data permission to access the rule named in **Rule name**. In the console, you can create a new service role or select an existing service role. If you're creating a new service role, you can either enter a role name (for example, **SidewalkDestinationRole**), or leave it blank for AWS IoT Core for LoRaWAN to generate a new role name. AWS IoT Core for LoRaWAN will then automatically create the IAM role with the appropriate permissions on your behalf.
## Create a destination (CLI)
To create a destination, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateDestination.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateDestination.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-destination.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-destination.html) CLI command. For example, the following command creates a destination for your Sidewalk end device:
```
aws iotwireless create-destination --name SidewalkDestination \
--expression-type RuleName --expression SidewalkRule \
--role-arn arn:aws:iam::123456789012:role/SidewalkRole
```
Running this command returns the destination details, which include the Amazon Resource Name (ARN) and the destination name.
```
{
"Arn": "arn:aws:iotwireless:us-east-1:123456789012:Destination/SidewalkDestination",
"Name": "SidewalkDestination"
}
```
For more information about creating a destination, see [Create rules to process LoRaWAN device messages](https://docs.aws.amazon.com/iot/latest/developerguide/connect-iot-lorawan-destination-rules.html).
# Create an IAM role and IoT rule for your destination
Your destination can be an MQTT topic or an AWS IoT rule. In this example, you configure an AWS IoT rule as a destination.
AWS IoT rules send device messages to other services. AWS IoT rules can also process the binary messages received from a Sidewalk end device for other services to use. AWS IoT Core for Amazon Sidewalk destinations associate a wireless device with the rule that processes the device's message data to send to other services. The rule acts on the device's data as soon as AWS IoT Core for Amazon Sidewalk receives it. For all devices that send their data to the same service, you can create a destination that can be shared by all devices. You must also create an IAM role that grants permission to send data to the rule.
## Create an IAM role for your destination
Create an IAM role that grants AWS IoT Core for Amazon Sidewalk permission to send data to the AWS IoT rule. To create the role, use the [https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateRole.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateRole.html) API operation or [https://docs.aws.amazon.com/cli/latest/reference/iam/create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role) CLI command. You can name the role as *`SidewalkRole`*.
```
aws iam create-role --role-name SidewalkRole \
--assume-role-policy-document '{"Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": {"Service": "lambda.amazonaws.com"}, "Action": "sts:AssumeRole"}]}'
```
You can also define the trust policy for the role using a JSON file.
```
aws iam create-role --role-name SidewalkRole \
--assume-role-policy-document file://trust-policy.json
```
The following shows the contents of the JSON file.
**Contents of trust-policy.json**
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
## Create a rule for your destination
Use the AWS IoT Core API operation, [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRule.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRule.html), or the AWS CLI command, [https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html), to create a rule. The topic rule will be used by your destination to route the data received from your Sidewalk end device to other AWS services. For example, you can create a rule action that sends a message to a Lambda function. You can define the Lambda function such that it receives the application data from your device and uses base64 to decode the payload data so that it can be used by other applications.
The following steps show how you create the Lambda function and then a topic rule that sends a message to this function.
1.
**Create execution role and policy**
Create an IAM role that grants your function permission to access AWS resources. You can also define the trust policy for the role using a JSON file.
```
aws iam create-role --role-name lambda-ex \
--assume-role-policy-document file://lambda-trust-policy.json
```
The following shows the contents of the JSON file.
**Contents of lambda-trust-policy.json**
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
1.
**Create and test Lambda function**
Perform the following steps to create a AWS Lambda function that base64 decodes the payload data.
1. Write the code for decoding the payload data. For example, you can use the following sample Python code. Specify a name for the script, such as *`base64_decode.py`*.
**Contents of base64\$1decode.py**
```
// -----------------------------------------------------------
// ----- Python script to decode incoming binary payload -----
// -----------------------------------------------------------
import json
import base64
def lambda_handler(event, context):
message = json.dumps(event)
print (message)
payload_data = base64.b64decode(event["PayloadData"])
print(payload_data)
print(int(payload_data,16))
```
1. Create a deployment package as a zip file that contains the Python file and name it as `base64_decode.zip`. Use the `CreateFunction` API or the `create-function` CLI command to create a Lambda function for the sample code, *`base64_decode.py`*.
1.
```
aws lambda create-function --function-name my-function \
--zip-file fileb://base64_decode.zip --handler index.handler \
--runtime python3.9 --role arn:aws:iam::123456789012:role/lambda-ex
```
You should see the following output. You'll use the Amazon Resource Name (ARN) value from the output, `FunctionArn`, when creating the topic rule.
```
{
"FunctionName": "my-function",
"FunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:my-function",
"Runtime": "python3.9",
"Role": "arn:aws:iam::123456789012:role/lambda-ex",
"Handler": "index.handler",
"CodeSha256": "FpFMvUhayLkOoVBpNuNiIVML/tuGv2iJQ7t0yWVTU8c=",
"Version": "$LATEST",
"TracingConfig": {
"Mode": "PassThrough"
},
"RevisionId": "88ebe1e1-bfdf-4dc3-84de-3017268fa1ff",
...
}
```
1. To get logs for an invocation from the command line, use the `--log-type` option with the `invoke` command. The response includes a LogResult field that contains up to 4 KB of base64-encoded logs from the invocation.
```
aws lambda invoke --function-name my-function out --log-type Tail
```
You should receive a response with a `StatusCode` of 200. For more information about creating and using Lambda functions from the AWS CLI, see [Using Lambda with the AWS CLI](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-awscli.html).
1. Create a topic rule
Use the `CreateTopicRule` API or the `create-topic-rule` CLI command to create a topic rule that sends a message to this Lambda function. You can also add a second rule action that republishes to an AWS IoT topic. Name this topic rule as `Sidewalkrule`.
```
aws iot create-topic-rule --rule-name Sidewalkrule \
--topic-rule-payload file://myrule.json
```
You can use the `myrule.json` file to specify more details about the rule. For example, the following JSON file shows how to republish to an AWS IoT topic and send a message to a Lambda function.
```
{
"sql": "SELECT * ",
"actions": [
{
// You obtained this functionArn when creating the Lambda function using the
// create-function command.
"lambda": {
"functionArn": "arn:aws:lambda:us-east-1:123456789012:function:my-function"
}
},
{
// This topic can be used to observe messages exchanged between the device and
// AWS IoT Core for Amazon Sidewalk after the device is connected.
"republish": {
"roleArn": "arn:aws:iam::123456789012:role/service-role/SidewalkRepublishRole",
"topic": "project/sensor/observed"
}
}
],
}
```
# Connect your Sidewalk device and view uplink metadata format
In this tutorial, you'll use the MQTT test client to test the connectivity and see messages exhanged between your end device and the AWS Cloud. To receive messages, in the MQTT test client, subscribe to the topic specified when creating the IoT rule for your destination. You can also send a downlink message from AWS IoT Core for Amazon Sidewalk to your device using the `SendDataToWirelessDevice` API operation. You can verify that the message was delivered by enabling the message delivery status event notification.
**Note**
For information about connecting your hardware platform and setting it up, see [Provisioning and registering your end device](https://docs.sidewalk.amazon/provisioning/) and [Setting up the hardware development kit (HDK)](https://docs.sidewalk.amazon/getting-started/sidewalk-onboard-prereq-hdk.html) in the *Amazon Sidewalk documentation*.
## Send downlink messages to your end device
Use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_SendDataToWirelessDevice.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_SendDataToWirelessDevice.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/send-data-to-wireless-device.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/send-data-to-wireless-device.html) CLI command to send downlink messages from AWS IoT Core for Amazon Sidewalk to your Sidewalk end device. Following shows an example of how to run this command. The payload data is the binary to be sent, encoded in base64.
```
aws iotwireless send-data-to-wireless-device \
--id "" \
--payload-data "SGVsbG8gVG8gRGV2c2lt" \
--wireless-metadata Sidewalk={Seq=1,AckModeRetryDurationSecs=10}
```
Following shows a sample output of running this command, which is an ID of the downlink message sent to the device.
```
{
MessageId: "6011dd36-0043d6eb-0072-0008"
}
```
**Note**
The `SendDataToWirelessDevice` API can return a message ID but the message might not be successfully delivered. To check the status of the message that was sent to the device, you can enable message delivery status events for your Sidewalk accounts and devices. For information about how to enable this event, see [Event notifications for Sidewalk resources](iot-wireless-events-notifications.md#iot-sidewalk-events). For more information about this event type, see [Message delivery events](https://docs.aws.amazon.com/iot/latest/developerguide/iot-sidewalk-message-delivery-events.html).
## View format of uplink messages from the device
After you've connected your device, you can subscribe to the topic (for example, *`project/sensor/observed`*) that you specified when creating the destination rule, and observe uplink messages from the device.
If you specified a topic name when creating your destination, you can subscribe to the topic to monitor uplink messages from your end device. Go to the [MQTT test client](https://console.aws.amazon.com/iot/home#/test) on the **Test** page of the AWS IoT console, enter the topic name (for example, *`project/sensor/observed`*), and then choose **Subscribe**.
The following example shows the format of the uplink messages that are sent from Sidewalk devices to AWS IoT. The `WirelessMetadata` contains metadata about the message request.
```
{
"PayloadData":"ZjRlNjY1ZWNlNw==",
"WirelessDeviceId":"wireless_device_id",
"WirelessMetadata":{
"Sidewalk":{
"CmdExStatus":"Cmd",
"SidewalkId":"device_id",
"Seq":0,
"MessageType":"messageType",
"Timestamp": "2024-10-21T19:33:01.295912052Z",
"Rssi": -22,
"LinkType": "LoRa"
}
}
}
```
The following table shows a definition of the different parameters in the uplink metadata. The `device-id` is the ID of the wireless device, such as `ABCDEF1234` and the `messageType` is the type of uplink message that's received from the device.
**Sidewalk uplink metadata parameters**
| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
| PayloadData | The message payload that is sent from the wireless device. | String | Yes |
| WirelessDeviceID | The identifier of the wireless device that's sending the data | String | Yes |
| Sidewalk.CmdExStatus | Command runtime status. Response-type messages shall include the status code, `COMMAND_EXEC_STATUS_SUCCESS`. However, notifications might not include the status code. | Enumeration | No |
| Seq | The message sequence number. | Integer | Yes |
| Sidewalk.NackExStatus | Response nack status, which can be `RADIO_TX_ERROR` or `MEMORY_ERROR`. | Array of strings | No |
| Timestamp | The time when the Sidewalk device sent an uplink request. | Timestamp | Yes |
| Rssi | Received Signal Strength Indicator, which is a measurement of a wireless network's signal strength | Integer | No |
| LinkType | The type of link that was used to perform the uplink which can be one of `LoRa`, `BLE`, or `FSK` | String | No |
# Using AWS Location with Sidewalk Devices
AWS IoT Core for Amazon Sidewalk provides location capabilities for your Sidewalk devices, enabling you to track and monitor device positions. Geolocation is handled by the Amazon Sidewalk stack on the end device and triggered by the end device itself. The device collects location data and sends it to AWS IoT Core for Amazon Sidewalk, where you can retrieve it using AWS services.
**Note**
To use location capabilities with Sidewalk devices, ensure you are using Amazon Sidewalk SDK version 1.19 or later on your end device. For details on implementing geolocation on the device side, see the [Amazon Sidewalk Location Library Developer Guide](https://docs.sidewalk.amazon/assets/pdf/Amazon_Sidewalk_Location_Library_Developer_Guide-1.0-rev-A.pdf).
## Location resolution methods
Sidewalk devices support three methods for resolving device location:
WiFi-based location
The device scans nearby WiFi access points and sends their BSSID information and signal strengths. AWS uses this information to estimate the device's location based on known WiFi access point locations.
GNSS (Global Navigation Satellite System)
The device captures raw GNSS signals from GPS or other satellite navigation systems and sends this data to the cloud, where AWS solves for the device's position.
BLE (Bluetooth Low Energy) based location
AWS IoT returns location coordinates based on the approximate location of nearby Amazon Sidewalk Gateways that are connected to Amazon Sidewalk and have the Community Finding feature enabled. Gateway Location Data is AWS Content and is provided to you solely for the purpose of assisting you in locating your devices that are connected to Amazon Sidewalk, and you must only use the data for that purpose. You must only use and access location data via the interface and functionality that we generally make available to you, and you must not attempt to re-identify, reverse engineer, or re-map any Gateway location data provided by us to you.
The location resolution method used depends on your device's capabilities and configuration. Your end device determines which method to use based on its hardware capabilities and the Amazon Sidewalk SDK configuration.
## Enable location for Sidewalk devices
You can enable location capabilities when creating a new Sidewalk device or update an existing device to enable positioning. When you enable positioning, you must also specify a destination for the location data.
**Important**
If you enable device location for the Sidewalk-enabled device, your raw uplink payload won't be propagated to the uplink destination. Location data will be sent to the location destination instead.
### Enable location (console)
You can enable location capabilities for your Sidewalk device using the AWS IoT console when creating a new device or updating an existing device.
#### Create a new device with location enabled
To create a new Sidewalk device with location capabilities:
1. Go to the [Sidewalk devices hub](https://console.aws.amazon.com/iot/home#/wireless/devices?tab=sidewalk) and choose **Provision device**.
1. In the **Specify device details** section, enter the device name, choose a device profile, and specify the uplink destination name.
1. In the **Geolocation** section, select **Activate positioning** to enable location capabilities for the device.
![\[alt text not found\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/images/iot-sidewalk-enable-positioning-console.png)
1. In the **Position data destination** field, select the name of the destination where location data will be sent. This destination must have an AWS IoT rule configured to process location data.
![\[alt text not found\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/images/iot-sidewalk-location-destination.png)
1. Complete the remaining steps to create your device, and then choose **Create**.
#### Update an existing device to enable location
To enable location capabilities for an existing Sidewalk device:
1. Go to the [Sidewalk devices hub](https://console.aws.amazon.com/iot/home#/wireless/devices?tab=sidewalk).
1. Choose the device that you want to update to view its details.
![\[alt text not found\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/images/iot-sidewalk-device-edit.png)
1. In the device details page, choose select **Activate positioning** to enable location capabilities for the device.
![\[alt text not found\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/images/iot-sidewalk-enable-positioning-console.png)
1. In the **Position data destination** field, select the name of the destination where location data will be sent.
![\[alt text not found\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/images/iot-sidewalk-location-destination.png)
1. Choose **Save** to apply the changes.
### Enable location (CLI)
You can enable location capabilities using the AWS CLI when creating a new device or updating an existing device.
#### Create a new device with location enabled
To create a Sidewalk device with location enabled, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateWirelessDevice.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateWirelessDevice.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-wireless-device.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/create-wireless-device.html) CLI command with the `--positioning` parameter set to `Enabled`.
```
aws iotwireless create-wireless-device \
--type "Sidewalk" \
--name "sidewalk_device" \
--destination-name "UplinkDestination" \
--positioning "Enabled" \
--sidewalk DeviceProfileId="12345678-a1b2-3c45-67d8-e90fa1b2c34d",Positioning={DestinationName="LocationDestination"}
```
#### Update an existing device to enable location
To enable location for an existing Sidewalk device, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateWirelessDevice.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateWirelessDevice.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/update-wireless-device.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/update-wireless-device.html) CLI command.
```
aws iotwireless update-wireless-device \
--id "23456789-abcd-0123-bcde-fabc012345678" \
--positioning "Enabled" \
--sidewalk Positioning={DestinationName="LocationDestination"}
```
## Retrieve location data
After enabling location capabilities for your Sidewalk device, you can retrieve location data using two methods: the `GetResourcePosition` API or by subscribing to an MQTT topic.
### Retrieve location using GetResourcePosition API
Use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetResourcePosition.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetResourcePosition.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-resource-position.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-resource-position.html) CLI command to retrieve the most recent location data for your device.
The following example shows how to retrieve location data for a Sidewalk device:
```
aws iotwireless get-resource-position \
--resource-identifier "23456789-abcd-0123-bcde-fabc012345678" \
--resource-type "WirelessDevice"
```
The API returns the device's location coordinates and additional metadata. The following shows an example response:
```
{
"GeoJsonPayload": blob,
"Timestamp": "2024-10-21T19:33:01.295912052Z"
}
```
The `GeoJsonPayload` contains the location data in GeoJSON format, which includes the device's latitude, longitude, and accuracy information.
### Retrieve location using MQTT
You can subscribe to an MQTT topic to receive location data as it becomes available from your Sidewalk device. This method allows you to process location data in real-time using AWS IoT rules.
1.
**Create a destination for location data**
Create a destination with an AWS IoT rule that processes location data. For information about creating destinations, see [Add a destination for your Sidewalk end device](iot-sidewalk-qsg-destination.md).
1.
**Subscribe to the MQTT topic**
Go to the [MQTT test client](https://console.aws.amazon.com/iot/home#/test) on the **Test** page of the AWS IoT console. Enter the topic name that you specified in your location destination rule (for example, *`project/sensor/location`*), and then choose **Subscribe**.
1.
**View location messages**
When your device sends location data, you'll see messages published to the topic. The following shows an example of a location message:
```
{
"type": Point,
"coordinates": [
11.11,
22.22,
33.33
],
"properties": {
"timestamp": 2026-00-00T00:00:00Z
}
}
```
# Bulk provisioning devices with AWS IoT Core for Amazon Sidewalk
You can use bulk provisioning to onboard a large number of end devices to AWS IoT Core for Amazon Sidewalk in bulk. Bulk provisioning is useful especially when you manufacture a large number of devices in a factory and want to onboard these devices to AWS IoT. For more information about manufacturing devices, see [Manufacturing Amazon Sidewalk devices](https://docs.sidewalk.amazon/manufacturing/) in the *Amazon Sidewalk documentation*.
The following topics show you how bulk provisioning works.
+
**[Amazon Sidewalk bulk provisioning workflow](sidewalk-bulk-provisioning-workflow.md)**
This topic shows you some key concepts of bulk provisioning and how it works. It also shows the steps that must be performed so that your Sidewalk devices can be imported to AWS IoT Core for Amazon Sidewalk.
+
**[Creating device profiles with factory support](sidewalk-provision-profile.md)**
This topic explains how to create a device profile and obtain factory support for it. You'll also learn how to retrieve the YubiHSM key and send it to your manufacturer for obtaining the control log after the devices are manufactured.
+
**[Provisioning Sidewalk devices using import tasks](sidewalk-provision-bulk-import.md)**
This topic shows you how to bulk provision your Sidewalk devices by creating and using import tasks. You'll also learn how to update or delete your import tasks, and view the status of the import task and devices in the task.
**Topics**
+ [Amazon Sidewalk bulk provisioning workflow](sidewalk-bulk-provisioning-workflow.md)
+ [Creating device profiles with factory support](sidewalk-provision-profile.md)
+ [Provisioning Sidewalk devices using import tasks](sidewalk-provision-bulk-import.md)
# Amazon Sidewalk bulk provisioning workflow
The following sections show you key concepts of bulk provisioning and how it works. The steps that are involved in bulk provisioning include:
1. Create a device profile using AWS IoT Core for Amazon Sidewalk.
1. Request the Amazon Sidewalk team for a YubiHSM key and to update your device profile with factory support.
1. Send the YubiHSM key to your manufacturer so that AWS IoT Core for Amazon Sidewalk can obtain the control log after the devices are manufactured.
1. Create an import task and provide the serial numbers (SMSN) of the devices to be onboarded to AWS IoT Core for Amazon Sidewalk.
## Components of bulk provisioning
The following concepts show you some key components of bulk provisioning and how to use them as part of bulk provisioning your Sidewalk devices.
### YubiHSM key
Amazon creates one or more HSMs (hardware security modules) for each of your Sidewalk products. Each HSM has a unique serial number, called YubiHSM key, that's printed on the hardware module. This key can be purchased from the [Yubico webpage](https://www.yubico.com/product/yubihsm-2/).
The key is unique to each HSM and tied to each device profile that you create with AWS IoT Core for Amazon Sidewalk. To obtain the YubiHSM key, contact the Amazon Sidewalk team. If you send the YubiHSM key to the manufacturer, after the Sidewalk devices are manufactured in the factory, AWS IoT Core for Amazon Sidewalk will receive a control log file that contains the serial numbers of the devices. It then compares this information with your input CSV file for onboarding the devices to AWS IoT.
### Device attestation key (`DAK`)
When a Sidewalk end device joins the Sidewalk network, it must be provisioned with a Sidewalk device certificate. The certificates that are used for setting up your device include a private device-specific certificate, and the public device certificates, which correspond to the Sidewalk certificate chain. When your Sidewalk devices are manufactured, the YubiHSM signs the device certificates.
The following shows a sample JSON file that contains the device certificates and the private keys. For more information, see [Obtain device JSON files for provisioning](sidewalk-json-get.md).
```
{
"p256R1": "grg8izXoVvQ86cPVm0GMyWuZYHEBbbH ... DANKkOKoNT3bUGz+/f/pyTE+xMRdIUBZ1Bw==",
"eD25519": "grg8izXoVvQ86cPVm0GMyWuZYHEBbbHD ... UiZmntHiUr1GfkTOFMYqRB+Aw==",
"metadata": {
"devicetypeid": "fe98",
...
"devicePrivKeyP256R1": "3e704bf8d319b3a475179f1d68c60737b28c708f845d0198f2d00d00c88ee018",
"devicePrivKeyEd25519": "17dacb3a46ad9a42d5c520ca5f47f0167f59ce54d740aa13918465faf533b8d0"
},
"applicationServerPublicKey": "5ce29b89c2e3ce6183b41e75fe54e45f61b8bb320efbdd2abd7aefa5957a316b"
}
```
The device attestation key (DAK) is a private key that you obtain when creating your device profile. It corresponds to the product certificate, which is a unique certificate that's issued to each Sidewalk product. When you contact the Amazon Sidewalk team, you'll receive the Sidewalk certificate chain, the YubiHSM key, and an HSM provisioned with the product device attestation key (DAK).
Your device profile is also updated with the new device attestation key (DAK), and with factory support enabled. The DAK metadata information of the device profile provides details such as the DAK name, the certificate ID, the ApId (Advertised Product ID), whether factory support is enabled, and the maximum number of signatures that the DAK can sign.
### Advertised product ID (`ApId`)
The `ApId` parameter is an alphanumeric string that identifies the advertised product. This field must be specified when you want to use a given device profile for Sidewalk devices that you bulk provision. AWS IoT Core for Amazon Sidewalk then generates the DAK, and provides it to you through the YubiHSM key. The related DAK information will be presented in the device profile.
To obtain the `ApId`, after you retrieve information about the device profile that you created, contact the Amazon Sidewalk Support team. You can obtain the device profile information from the AWS IoT console, or using the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetDeviceProfile.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetDeviceProfile.html) API operation, or the [https://docs.aws.amazon.com/cli/latest/reference/get-device-profile.html](https://docs.aws.amazon.com/cli/latest/reference/get-device-profile.html) CLI command.
## How bulk provisioning works
This flowchart shows how bulk provision works with AWS IoT Core for Amazon Sidewalk.
![\[Bulk Provisioning flow for your Amazon Sidewalk end devices.\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/images/sidewalk-bulk-provision-flow.png)
The following procedure illustrates the different steps in the bulk provisioning process.
1.
**Create device profile for Sidewalk device**
Before you take your end device to the factory, first create a device profile. You can use this profile to provision individual devices as described in [Add your device profile and Sidewalk end device](iot-sidewalk-add-device.md).
1.
**Request factory support for your profile**
When you're ready to take your end device to factory, ask the Amazon Sidewalk team for the YubiHSM key and for factory support for your device profile.
1.
**Obtain DAK and factory supported profile**
The Amazon Sidewalk Support team will then update your device profile with the product device attestation key (DAK) and factory support. Your device profile will be updated automatically with an advertised product ID (ApID), and a new DAK and certificate information, such as the certificate ID. Sidewalk devices that use this profile are qualified for use with bulk provisioning.
1.
**Send YubiHSM key to manufacturer (CM)**
Your end device is now qualified, so you can send your YubiHSM key to the contract manufacturer (CM) to start the manufacturing process. For more information, see [Manufacturing Amazon Sidewalk devices](https://docs.sidewalk.amazon/manufacturing/) in the *Amazon Sidewalk documentation*.
1.
**Manufacture devices and send control logs and serial numbers**
The CM manufactures the devices and generates control logs. The CM also provides you a CSV file that contains a list of devices to be manufactured and their Sidewalk manufacturing serial numbers (SMSN). The following code shows a sample control log. It contains the serial numbers of the device, the APID, and the public device certificates.
```
{
"controlLogs": [
{
"version": "4-0-1",
"device":
{
"serialNumber": "device1",
"productIdentifier": {
"advertisedProductId": "abCD"
},
"sidewalkData": {
"SidewalkED25519CertificateChain": "...",
"SidewalkP256R1CertificateChain": "..."
}
}
}
]
}
```
1.
**Pass control log information to AWS IoT Core for Amazon Sidewalk**
The Amazon Sidewalk cloud retrieves the control log information from the manufacturer and passes this information to AWS IoT Core for Amazon Sidewalk. The devices can then be created along with their serial numbers.
1.
**Check serial number match and start bulk provisioning**
When you use the AWS IoT console or the AWS IoT Core for Amazon Sidewalk API operation `StartWirelessDeviceImportTask`, AWS IoT Core for Amazon Sidewalk compares the Sidewalk manufacturing serial number (SMSN) of each devices obtained from Amazon Sidewalk with the corresponding serial numbers in your CSV file. If this information matches, it starts the bulk provisioning process and creates the devices to be imported to AWS IoT Core for Amazon Sidewalk.
# Creating device profiles with factory support
Before you can bulk provision your Amazon Sidewalk devices, you must create a device profile and then contact the Amazon Sidewalk support team to request factory support for it. The Amazon Sidewalk team will then update your device profile with a new device attestation key (DAK) and add factory support to it. Sidewalk devices that use this profile are then qualified to be used with AWS IoT Core for Amazon Sidewalk, and can be onboarded for bulk provisioning.
The following steps show you how to create a factory-supported device profile.
1.
**Create a device profile**
First create a device profile. When you create a profile, specify a name and optional tags as name-value pairs. For more information about the parameters required, and creating and using profiles, see [How to create and add your device](iot-sidewalk-create-device.md#iot-sidewalk-device-how).
1.
**Obtain factory support for the profile**
Then obtain factory support for your device profile so that devices that use this profile can be qualified. For qualification, create a ticket with the Amazon Sidewalk team. Once confirmed by the team, you'll receive an ApId (advertised product ID), and your profile will be updated with a factory-issued DAK. Sidewalk end devices that use this profile will be qualified.
You can create a device profile either using the AWS IoT console, the AWS IoT Core for Amazon Sidewalk API operations, or the AWS CLI.
**Topics**
+ [Create a profile (console)](#provision-profile-console)
+ [Create a profile (CLI)](#provision-profile-cli)
+ [Next steps](#provision-profile-next)
## Create a profile (console)
To create a device profile using the AWS IoT console, go to the [Sidewalk tab of the Profiles hub](https://console.aws.amazon.com/iot/home#/wireless/profiles?tab=sidewalk) and choose **Create profile**.
![\[Create a factory supported profile for bulk provisioning Sidewalk devices.\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/images/iot-sidewalk-create-profiles.PNG)
To create a profile, specify the following fields, and then choose **Submit**.
+
**Name**
Enter a **Name** for your profile.
+
**Tags**
Enter optional tags as name-value pairs to help you more easily identify your profile. Tags also make it easier to track billing charges.
**View profile information and qualify profiles**
You'll see the profile that you created in the [Profiles hub](https://console.aws.amazon.com/iot/home#/wireless/profiles?tab=sidewalk). Choose the profile to view its details. You'll see information about:
+ The device profile name and unique identifier, and any optional tags you specified as name value pairs.
+ The application server public key and device type ID of the profile.
+ The qualification status, which indicates that you're using a device profile that is not factory supported. To qualify your device profile so that it's factory supported, contact Amazon Sidewalk Support.
+ The device attestation key (DAK) information. Once your device profile is qualified, a new DAK will be issued and your profile will be updated automatically with the new DAK information.
## Create a profile (CLI)
To create a device profile, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateDeviceProfile.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateDeviceProfile.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/create-device-profile.html](https://docs.aws.amazon.com/cli/latest/reference/create-device-profile.html) CLI command. For example, the following command creates a profile for your Sidewalk end device.
```
aws iotwireless create-device-profile \
--name "sidewalk_device_profile"
--sidewalk {}
```
Running this command returns the profile details, which include the Amazon Resource Name (ARN) and the ID of the profile.
```
{
"DeviceProfileArn": "arn:aws:iotwireless:us-east-1:123456789012:DeviceProfile/12345678-a1b2-3c45-67d8-e90fa1b2c34d",
"DeviceProfileId": "12345678-a1b2-3c45-67d8-e90fa1b2c34d"
}
```
**View profile information and qualify profiles**
Use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetDeviceProfile.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetDeviceProfile.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/get-device-profile.html](https://docs.aws.amazon.com/cli/latest/reference/get-device-profile.html) CLI command to get information about your device profile that you added to your account for AWS IoT Core for Amazon Sidewalk. To retrieve information about your device profile, specify the profile ID. The API will then return information about the device profile matching the specified identifier.
The following shows an example CLI command:
```
aws iotwireless get-device-profile \
--id "12345678-234a-45bc-67de-e8901234f0a1" > device_profile.json
```
Running this command returns the parameters of your device profile, the application server public key, the `DeviceTypeId`, `ApId`, qualification status, and the `DAKCertificate` information.
In this example, the qualification status and DAK information indicate that your device profile is not qualified. To qualify your profile, contact Amazon Sidewalk Support, and your profile will be issued a new DAK with no device limit.
```
{
"Arn": "arn:aws:iotwireless:us-east-1:123456789012:DeviceProfile/12345678-a1b2-3c45-67d8-e90fa1b2c34d",
"Id": "12345678-a1b2-3c45-67d8-e90fa1b2c34d",
"Name": "Sidewalk_profile",
"LoRaWAN": null,
"Sidewalk":
{
"ApplicationServerPublicKey": "a123b45c6d78e9f012a34cd5e6a7890b12c3d45e6f78a1b234c56d7e890a1234",
"DAKCertificateMetadata": [
{
"DeviceTypeId": "fe98",
"CertificateId": "43564A6D2D50524F544F54595045",
"FactorySupport": false,
"MaxAllowedSignature": 1000
}
],
"QualificationStatus": false
}
}
```
Once the Amazon Sidewalk Support team confirms this information, you'll receive the APID and a factory-supported DAK, as shown in the following example.
**Note**
The `MaxAllowedSignature` of `-1` indicates that the DAK doesn't have any device limit. For information about the DAK parameters, see [DAKCertificateMetadata](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_DAKCertificateMetadata.html).
```
{
"Arn": "arn:aws:iotwireless:us-east-1:123456789012:DeviceProfile/12345678-a1b2-3c45-67d8-e90fa1b2c34d",
"Id": "12345678-a1b2-3c45-67d8-e90fa1b2c34d",
"Name": "Sidewalk_profile",
"LoRaWAN": null,
"Sidewalk":
{
"ApplicationServerPublicKey": "a123b45c6d78e9f012a34cd5e6a7890b12c3d45e6f78a1b234c56d7e890a1234",
"DAKCertificateMetadata": [
{
"ApId": "GZBd",
"CertificateId": "43564A6D2D50524F544F54595045",
"FactorySupport": true,
"MaxAllowedSignature": -1
}
],
"QualificationStatus": true
}
}
```
## Next steps
Now that you've created a device profile which has a factory-supported DAK, provide the YubiHSM key that you obtain from the team to your manufacturer. Your devices will then be manufactured in the factory and a control log information will then be passed to Amazon Sidewalk, which contains the serial numbers (SMSN) of the devices. For more information about this workflow, see [Manufacturing Amazon Sidewalk devices](https://docs.sidewalk.amazon/manufacturing/) in the *Amazon Sidewalk documentation*.
You can then bulk provision your Sidewalk devices by providing AWS IoT Core for Amazon Sidewalk the serial numbers of the devices to be onboarded. When AWS IoT Core for Amazon Sidewalk receives the control log, it compares the serial numbers in the control log with the serial numbers that you provided. If the serial numbers match, the import task starts onboarding your devices to AWS IoT Core for Amazon Sidewalk. For more information, see [Provisioning Sidewalk devices using import tasks](sidewalk-provision-bulk-import.md).
# Provisioning Sidewalk devices using import tasks
This section shows how you can provision Sidewalk devices in bulk using the AWS IoT console, or the AWS IoT Core for Amazon Sidewalk API operations, or the AWS CLI. The following sections explain how to bulk provision your Sidewalk devices.
**Topics**
+ [How Sidewalk bulk provisioning works](#provision-bulk-works)
+ [Key considerations for Sidewalk bulk provisioning](#provision-bulk-considerations)
+ [CSV file format](#provision-csv-format)
+ [How to use Sidewalk bulk provisioning](#provision-bulk-use)
+ [Provision Sidewalk devices in bulk](sidewalk-bulk-provision-how.md)
+ [View import task and device onboarding status](sidewalk-bulk-provision-status.md)
## How Sidewalk bulk provisioning works
The following steps illustrate how bulk provisioning works.
1.
**Starting wireless device import task**
To provision Sidewalk devices in bulk, you must create an import task and provide the Sidewalk manufacturing serial number (SMSN) of the devices to be onboarded to AWS IoT Core for Amazon Sidewalk. You obtained the Sidewalk manufacturing serial number (SMSN) of the devices as a CSV file in your email after the manufacturer uploaded the control logs to Amazon Sidewalk. For more information about the workflow and how you obtain the control log, see [Manufacturing Amazon Sidewalk devices](https://docs.sidewalk.amazon/manufacturing/) in the *Amazon Sidewalk documentation*.
1.
**Running import process in background**
When AWS IoT Core for Amazon Sidewalk receives the import task request, it starts setting things up and starts a background process that polls the system frequently. Once the background process receives the import task instruction, it starts reading the CSV file. AWS IoT Core for Amazon Sidewalk simultaneously checks whether the control logs have been received from Amazon Sidewalk.
1.
**Creating wireless device records**
When the control log is received from Amazon Sidewalk, AWS IoT Core for Amazon Sidewalk checks whether the serial numbers in the control log match the SMSN values in the CSV file. If the serial numbers match, AWS IoT Core for Amazon Sidewalk will start creating wireless device records for the Sidewalk devices that correspond to these serial numbers. Once all the devices have been onboarded, the import task is marked as *Completed*.
## Key considerations for Sidewalk bulk provisioning
When provisioning your Sidewalk devices in bulk to AWS IoT Core for Amazon Sidewalk, following are some key considerations.
+ You must perform bulk provisioning using the AWS IoT console or the AWS IoT Core for Amazon Sidewalk API operations in the same AWS account where you created the device profile.
+ Before you bulk provision your Sidewalk devices, your device profile must already contain DAK information that indicates factory support. Otherwise, bulk provisioning using the AWS IoT console, or the bulk provisioning API operations can fail.
+ After you start an import task, it can take at least 10 minutes or longer to process the CSV file, import the wireless devices, and onboard them to AWS IoT Core for Amazon Sidewalk.
+ The wireless device import task will run for 90 days, once started. During this time, it checks whether the control logs have been received from Amazon Sidewalk. If the control log is not received from Amazon Sidewalk before 90 days, the task will be marked as *Completed* with a message indicating that it has expired when you view the task details. The onboarding status of the devices in the import task that were waiting for the control log will be marked as *Failed*.
+ When you attempt to update an import task that you've already created, you can only add additional devices to the task. You can add new devices anytime after creating an import task and before the task has started on devices that were already added to the import task. If the update file contains serial numbers of devices that already exist in the original import task, these serial numbers will be ignored.
+ When you request an update operation, the same IAM role as the one you used when creating the import task will be assumed to access the CSV file in the Amazon S3 bucket.
+ An import task can be deleted only if the task has already completed successfully or if the task failed to update. A task might fail to update in cases such as when an incorrect IAM role was provided or when an Amazon S3 bucket file wasn't found. An import task cannot be updated or deleted if it is in the `PENDING` state.
+ The CSV file that you import to the task must use the format described in the following section.
## CSV file format
The CSV file that's contained in an Amazon S3 bucket that you specify for the import task must use the following format:
+ Row 1 must use the keyword `smsn`, which indicates that the CSV file being imported contains the SMSN of the devices to be imported.
+ Rows 2 and after must contain the SMSN of the devices to be onboarded. The device SMSN must be in the 64 hex character format.
This JSON file shows a sample CSV file format.
```
smsn
1C1A10B0AC0A200C012BBAC2CBB1B21CB12C0CA2AC1C1BB22CAA01C1B0B01122
B122C2B1121BACA2221001AC1B22012AAC11112C11C2A100C1C2B012A1100C10
02B222C110B0A210B0A0C2C112CCCAC21C1C0B0AA1221AB1022A2CC11B1B1122
C2C021CA1C111CCAB1221C0021C1C2AAA0AA1A2A01ABC10CBAACCA2A0121022A
0CB22C01BBC2CA2C0B11001121ACB2ABB0BB0121C2BA101C012CC2B20C011AC0
```
## How to use Sidewalk bulk provisioning
The following steps show you how to use Amazon Sidewalk bulk provisioning.
1.
**Provide device serial numbers**
To provision your Sidewalk devices, you must provide the serial numbers of the devices to be onboarded. You can provision your devices using either of the following methods.
+ Provision each device individually using their Sidewalk manufacturing serial number (SMSN). This method is useful when you want to test the workflow and onboard your device faster without having to upload a CSV file with the appropriate IAM role, or waiting for the devices to be ready to be onboarded to the task.
+ Provision devices in bulk by providing an Amazon S3 bucket URL that contains the SMSN of the devices to be provisioned in a CSV file. This method is especially useful when you have a large number of devices to be onboarded. In this case, onboarding each device individually can be tedious. Instead, you only need to provide the path to the CSV file that has been uploaded to an Amazon S3 bucket, and the IAM role to access the file.
1.
**Obtain import task and device onboarding status**
For each import task that you create, you can retrieve information about the task onboarding status and the onboarding status of devices added to the task. You can also see additional status information, such as a reason as to why a task or device onboarding failed. For more information, see
1.
**(Optional) Update or delete import task**
You can update or delete an import task that you've already created.
+ You can update an import task and add additional devices to the task anytime before the task has started on devices that have already been added. AWS IoT Core for Amazon Sidewalk assumes the same IAM role as the one that you used when creating the import task. When you create the task, specify the new CSV file that contains the serial numbers of devices that you want to add to the task.
**Note**
When you're updating an existing import task, you can only add devices to the task. AWS IoT Core for Amazon Sidewalk performs a union operation between the devices that are already in the import task and the devices that you're attempting to add to the task. If the new file contains serial numbers of devices that already exist in the import task, these serial numbers will be ignored.
+ You can delete an import task that has already completed successfully, or an import task that failed to update in cases such as when the IAM role information is incorrect, or when an S3 bucket file isn't available when creating or updating a task.
**Topics**
+ [How Sidewalk bulk provisioning works](#provision-bulk-works)
+ [Key considerations for Sidewalk bulk provisioning](#provision-bulk-considerations)
+ [CSV file format](#provision-csv-format)
+ [How to use Sidewalk bulk provisioning](#provision-bulk-use)
+ [Provision Sidewalk devices in bulk](sidewalk-bulk-provision-how.md)
+ [View import task and device onboarding status](sidewalk-bulk-provision-status.md)
# Provision Sidewalk devices in bulk
This section shows how you can provision Sidewalk devices in bulk to AWS IoT Core for Amazon Sidewalk using the AWS IoT console and the AWS CLI.
## Provision Sidewalk devices in bulk (console)
To add your Sidewalk device using the AWS IoT console, go to the [Sidewalk tab of the Devices hub](https://console.aws.amazon.com/iot/home#/wireless/devices?tab=sidewalk), choose **Bulk provision devices**, and then perform the following steps.
![\[Use the AWS IoT console to bulk provision Sidewalk devices.\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/images/sidewalk-bulk-provision.PNG)
1.
**Choose import method**
Specify how you want to import the devices to be onboarded in bulk to AWS IoT Core for Amazon Sidewalk.
+ To provision individual devices using their SMSN, choose **Provision individual factory supported device**.
+ To provision devices in bulk by providing a CSV file that contains a list of devices and their SMS, choose **Use S3 bucket**.
1.
**Specify devices to be onboarded**
Depending on the method that you chose to onboard your devices, add the device information and their serial numbers.
1. If you chose **Provision individual factory supported device**, specify the following information:
1. A **Name** for each device to be onboarded. The name must be unique in your AWS account and AWS Region.
1. Their Sidewalk manufacturing serial number (SMSN) in the **Enter SMSN** field.
1. A **Destination** that describes the IoT rule to route messages from the device to other AWS services.
1. (Optional) A **Location Destination** where you want to send the device location data, after you enable location data when you create your Sidewalk end device with AWS IoT Core for Amazon Sidewalk. For more information on AWS IoT's location resolution capabilities, see [AWS IoT Core Device Location](https://docs.aws.amazon.com/iot/latest/developerguide/device-location.html) AWS services.
**Note**
For Bluetooth Low Energy based location, AWS IoT returns location coordinates based on the approximate location of nearby Sidewalk Gateways that are connected to Amazon Sidewalk and have the Community Finding feature enabled. Gateway Location Data is AWS Content and is provided to you solely for the purpose of assisting you in locating your devices that are connected to Amazon Sidewalk, and you must only use the data for that purpose. You must only use and access location data via the interface and functionality that we generally make available to you, and you must not attempt to re-identify, reverse engineer, or re-map any Gateway location data provided by us to you.
**Note**
You must enable positioning to use the device location feature.
If you enable device location for the Sidewalk-enabled device, your raw uplink payload won't be propagated to the destination.
1. If you chose **Use S3 bucket**:
1. Provide the **S3 Bucket** information, which consists of the S3 URL information. To provide your CSV file, choose **Browse S3**, and then choose the CSV file you want to use.
AWS IoT Core for Amazon Sidewalk automatically populates the S3 URL, which is the path to your CSV file in the S3 bucket. The format of the path is `s3://bucket_name/file_name`. To view the file in the [Amazon Simple Storage Service](https://console.aws.amazon.com/s3/) console, choose **View**.
1. Provide the **S3 Provisioning role**, which allows AWS IoT Core for Amazon Sidewalk to access the CSV file in the S3 bucket on your behalf. You can either create a new service role or choose an existing role.
To create a new role, you can either provide a **Role name** or leave it blank to generate a random name automatically.
1. Provide a **Destination** that describes the IoT rule to route messages from the device to other AWS services.
1. (Optional) A **Location Destination** where you want to send the device location data, after you enable location data when you create your Sidewalk end device with AWS IoT Core for Amazon Sidewalk. For more information on AWS IoT's location resolution capabilities, see [AWS IoT Core Device Location](https://docs.aws.amazon.com/iot/latest/developerguide/device-location.html) AWS services.
**Note**
For Bluetooth Low Energy based location, AWS IoT returns location coordinates based on the approximate location of nearby Sidewalk Gateways that are connected to Amazon Sidewalk and have the Community Finding feature enabled. Gateway Location Data is AWS Content and is provided to you solely for the purpose of assisting you in locating your devices that are connected to Amazon Sidewalk, and you must only use the data for that purpose. You must only use and access location data via the interface and functionality that we generally make available to you, and you must not attempt to re-identify, reverse engineer, or re-map any Gateway location data provided by us to you.
**Note**
You must enable positioning to use the device location feature.
If you enable device location for the Sidewalk-enabled device, your raw uplink payload won't be propagated to the destination.
1. Start import task
Provide any optional tags as name-value pairs and choose **Submit** to start your wireless device import task.
## Provision Sidewalk devices in bulk (CLI)
To onboard your Sidewalk devices to your account for AWS IoT Core for Amazon Sidewalk, use any of the following API operations depending on whether you want to add devices individually or by providing the CSV file contained in an S3 bucket.
+
**Upload devices in bulk using an S3 CSV file**
To upload devices in bulk by providing the CSV file in an S3 bucket, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_StartWirelessDeviceImportTask.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_StartWirelessDeviceImportTask.html) API operation, or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/start-wireless-device-import-task.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/start-wireless-device-import-task.html) AWS CLI command. When creating the task, specify the path to the CSV file in the Amazon S3 bucket and the IAM role that grants AWS IoT Core for Amazon Sidewalk permissions to access the CSV file.
Once the task starts to run, AWS IoT Core for Amazon Sidewalk will start reading the CSV file and compare the serial numbers (SMSN) in the file with the corresponding information in the control log received from Amazon Sidewalk. When the serial numbers match, it will start creating wireless device records corresponding to these serial numbers.
The following command shows an example of creating an import task:
```
aws iotwireless start-wireless-device-import-task \
--cli-input-json "file://task.json"
```
The following shows the contents of the file `task.json`.
**Contents of task.json**
```
{
"DestinationName": "Sidewalk_Destination",
"Positioning": "Enabled"
"Sidewalk": {
"DeviceCreationFile": "s3://import_task_bucket/import_file1",
"Role": "arn:aws:iam::123456789012:role/service-role/ACF1zBEI",
"Positioning": {
DestinationName": "Sidewalk_Location_Destination"
}
}
}
```
Running this command returns an ID and ARN for the import task.
```
{
"Arn": "arn:aws:iotwireless:us-east-1:123456789012:ImportTask/a1b234c5-67ef-21a2-a1b2-3cd4e5f6789a"
"Id": "a1b234c5-67ef-21a2-a1b2-3cd4e5f6789a"
}
```
+
**Provision devices individually using their SMSN**
To provision devices individually using their SMSN, use the [https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_StartSingleWirelessDeviceImportTask.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_StartSingleWirelessDeviceImportTask.html) API operation, or the [https://docs.aws.amazon.com/cli/latest/reference/iotwireless/start-single-wireless-device-import-task.html](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/start-single-wireless-device-import-task.html) AWS CLI command. When creating the task, specify the Sidewalk destination and the serial number of the device that you want to onboard.
When the serial number matches the corresponding information in the control log received from Amazon Sidewalk, the task will run and create the wireless device record.
The following command shows an example of creating an import task:
```
aws iotwireless start-single-wireless-device-import-task \
--destination-name sidewalk_destination \
--positioning Enabled \
--sidewalk '{
"SidewalkManufacturingSn": "82B83C8B35E856F43CE9C3D59B418CC96B996071016DB1C3BE5901F
0F3071A4A"}',
"Positioning":{
DestinationName": sidewalk_location_destination
}
}'
```
Running this command returns an ID and ARN for the import task.
```
{
"Arn": "arn:aws:iotwireless:us-east-1:123456789012:ImportTask/e2a5995e-743b-41f2-a1e4-3ca6a5c5249f"
"Id": "e2a5995e-743b-41f2-a1e4-3ca6a5c5249f"
}
```
## Update or delete import tasks
If you want to add additional devices to an import task, you can update the task. You can also delete a task if you no longer require the task or if it failed. For information about when to update or delete a task, see [How to use Sidewalk bulk provisioning](sidewalk-provision-bulk-import.md#provision-bulk-use).
**Warning**
Deletion actions are permanent and can't be undone. Deleting an import task that has already completed successfully will not remove the end devices that have already been onboarded using the task.
To update or delete import tasks:
+
**Using the AWS IoT console**
The following steps explain how to update or delete your import tasks using the AWS IoT console.
**To update an import task:**
1. Go to the [Sidewalk devices hub](https://console.aws.amazon.com/iot/home#/wireless/devices?tab=sidewalk) of the AWS IoT console.
1. Choose the import task that you want to update and then choose **Edit**.
1. Provide another S3 file that contains the serial numbers of devices that you want to add to the task and then choose **Submit**.
**To delete an import task:**
1. Go to the [Sidewalk devices hub](https://console.aws.amazon.com/iot/home#/wireless/devices?tab=sidewalk) of the AWS IoT console.
1. Choose the task that you want to delete and then choose **Delete**.
+
**Using the AWS IoT Wireless API or AWS CLI**
Use the following AWS IoT Wireless API operations or CLI commands to update or delete your import task.
+
**[https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateWirelessDeviceImportTask.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateWirelessDeviceImportTask.html) API or [https://docs.aws.amazon.com/cli/latest/reference/update-wireless-device-import-task.html](https://docs.aws.amazon.com/cli/latest/reference/update-wireless-device-import-task.html) CLI**
This API operation appends the contents of an Amazon S3 CSV file to an existing import task. You can only add serial numbers of devices that were not previously included in the task.
+
**[https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_DeleteWirelessDeviceImportTask.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_DeleteWirelessDeviceImportTask.html) API or [https://docs.aws.amazon.com/cli/latest/reference/delete-wireless-device-import-task.html](https://docs.aws.amazon.com/cli/latest/reference/delete-wireless-device-import-task.html) CLI**
This API operation deletes the import task that was marked for deletion using the import task ID.
# View import task and device onboarding status
Your wireless device import tasks and Sidewalk devices that you've added to the task can have one of the following status messages. You'll see these messages displayed in the AWS IoT console, or when you use any of the AWS IoT Wireless API operations or AWS CLI commands to retrieve information about these tasks and their devices.
## View import task status information
After you've created an import task, you can view the import task that you created and the onboarding status of devices added to the task. The onboarding status indicates the number of devices that are pending onboarding, the number of devices that have been onboarded successfully, and the number of devices that failed to onboard.
When an import task has just been created, the **Pending count** will display a value that corresponds to the number of devices that were added. Once the task starts and reads the CSV file to create the wireless device records, the **Pending count** will decrease, and the **Success count** will increase as the devices are onboarded successfully. If any device fails to onboard, the **Failed count** will increase.
To view the import task and device onboarding status:
+
**Using the AWS IoT console**
In the [Sidewalk devices hub](https://console.aws.amazon.com/iot/home#/wireless/devices?tab=sidewalk) of the AWS IoT console, you can see the import tasks that you created and a count of the summary of the onboarding status information of your devices. If you view the details of any of the import tasks that you created, you can see additional information about the device onboarding status.
+
**Using the AWS IoT Wireless API or AWS CLI**
To view the device onboarding status, use any of the following AWS IoT Wireless API operations or the corresponding AWS CLI command. .
+
**[https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListWirelessDeviceImportTasks.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListWirelessDeviceImportTasks.html) API or [https://docs.aws.amazon.com/cli/latest/reference/list-wireless-device-import-tasks.html](https://docs.aws.amazon.com/cli/latest/reference/list-wireless-device-import-tasks.html) CLI**
This API operation returns information about all the import tasks that have been added to your account for AWS IoT Wireless and their status. It also returns a count of the summary of onboarding status of Sidewalk devices in these tasks.
+
**[https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListDevicesForWirelessDeviceImportTask.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListDevicesForWirelessDeviceImportTask.html) API or [https://docs.aws.amazon.com/cli/latest/reference/list-devices-for-wireless-device-import-task.html](https://docs.aws.amazon.com/cli/latest/reference/list-devices-for-wireless-device-import-task.html) CLI**
This API operation returns information about the specified import task and its status, and information about all Sidewalk devices that have been added to the import task and their onboarding status information.
+
**[https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetWirelessDeviceImportTask.html](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetWirelessDeviceImportTask.html) API or [https://docs.aws.amazon.com/cli/latest/reference/get-wireless-device-import-task.html](https://docs.aws.amazon.com/cli/latest/reference/get-wireless-device-import-task.html) CLI**
This API operation returns information about the specified import task and its status, and a count of the summary of onboarding status of Sidewalk devices in that task.
## Import task status
The import tasks that you have created in your AWS account can have one of the following status messages. The status indicates whether your import task has started processing, or has completed, or failed. You can also use the AWS IoT console or the `StatusReason` parameter of any of the AWS IoT Wireless API operations to retrieve additional status details.
+
**INITIALIZING**
AWS IoT Core for Amazon Sidewalk has received the wireless device import task request and is in the process of setting up the task.
+
**INITIALIZED**
AWS IoT Core for Amazon Sidewalk has completed setting up the import task and is waiting for the control log to arrive so that it can import the devices using their serial numbers (SMSN) and continue processing the task.
+
**PENDING**
The import task is waiting in the queue to be processed. AWS IoT Core for Amazon Sidewalk is evaluating other tasks that are in the processing queue.
+
**COMPLETE**
The import task has been processed and completed.
+
**FAILED**
The import task or device task failed. You can use the `StatusReason` parameter to identify why the import task failed, such as a validation exception.
+
**DELETING**
The import task has been marked for deletion and is in the process of being deleted.
## Device onboarding status
The Sidewalk devices that you added to your import task can have one of the following status messages. The status indicates whether your devices are ready to be onboarded, or has onboarded, or failed to onboard. You can also use the AWS IoT console or the `OnboardingStatusReason` parameter of the AWS IoT Wireless API operation, `ListDevicesForWirelessDeviceImportTask`, to retrieve additional status details.
+
**INITIALIZED**
AWS IoT Core for Amazon Sidewalk has completed setting up the import task and is waiting for the control log to arrive so that it can import the devices using their serial numbers (SMSN) and continue processing the task.
+
**PENDING**
The import task is waiting in the queue to be processed and to start onboarding your devices to the task. AWS IoT Core for Amazon Sidewalk is evaluating other tasks that are in the processing queue.
+
**ONBOARDED**
The Sidewalk device has been successfully onboarded to the import task.
+
**FAILED**
The import task or device task failed, and the Sidewalk device failed to onboard to the task. You can use the `OnboardingStatusReason` parameter to retrieve additional details about why the device onboarding failed.