# 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.