Cloud-configuration tasks
Important
This is the Azure Sphere (Legacy) documentation. Azure Sphere (Legacy) is retiring on 27 September 2027, and users must migrate to Azure Sphere (Integrated) by this time. Use the Version selector located above the TOC to view the Azure Sphere (Integrated) documentation.
After the product that contains the Azure Sphere device is finalized but before it is shipped, you must configure the device for over-the-air (OTA) software updates. Cloud configuration involves the following tasks, which must be completed in the order specified:
- Claim the chip into a tenant
- Configure cloud deployments for over-the-air (OTA) software updates
- Ensure that sideloaded images are present in the tenant
- Verify the cloud configuration for a device
These steps are critical to the continued operation of the device at the deployment site. Sample scripts that claim multiple manufactured devices in parallel and configure them for cloud deployments (tasks 1 and 2, respectively) are included in the Manufacturing Samples package.
Important
You should do some preparation to help ensure that your cloud-configuration tasks can be completed without delays. Preparation includes setting up the cloud-configuration PC and installing the necessary PC software tools. All of the tasks you should do to prepare for a smooth manufacturing process are described in Manufacturing process preparation.
Claim the chip
You must also claim the Azure Sphere chips in all your connected devices. Claiming involves moving the Azure Sphere chip to your organization's cloud tenant, so that both your organization and Microsoft can identify the chip's owner. Claiming ensures that all data associated with the chip resides in your tenant and is protected by your security policies.
A chip must be claimed before it can communicate with the Azure Sphere Security Service. Such communication, in turn, allows the chip to receive the software updates that you specify and to obtain certificates that are required for authentication to an Azure IoT Hub and other cloud-based services.
To claim a chip, run the following command replacing <device ID> with the device ID of the chip you want to claim. Because the device is not attached to the PC for cloud-configuration tasks, you must include the --device parameter to specify the target device:
azsphere device claim --device <device ID>
Important
The chip need not be incorporated into a connected device at the time of claiming. You must claim the Azure Sphere chip before you configure cloud deployments, verify the cloud configuration, and ship the connected device.
Configure cloud deployments
Cloud deployments update the Azure Sphere device OS and your production application software. To receive the correct software updates, a product must be created for the Azure Sphere device and the device must be assigned to a device group within this product. You should have already created a product, as described in Product name and device group in the manufacturing preparation.
To assign a device to a product and device group, use the azsphere device update command. Because the device is not attached to the PC for cloud-configuration tasks, you must include the --device parameter to specify the target device.
The following example shows how to move a device to the Production default device group for the DW100 product. The Production device group enables cloud updates and is appropriate for connected products at deployment sites.
azsphere device update --device-group DW100/Production --device <device-ID>
Important
You must configure cloud deployments before your device is connected to the internet; otherwise, the first time the device is connected to the internet, an application you sideloaded during the factory-floor process will be deleted by the mandatory Azure Sphere OS update.
Ensure that sideloaded images are present in the tenant
All non-temporary images that are sideloaded to a device during the factory-floor process, as described in Load device software, must also be present in the tenant that the device is claimed into. If these images are not present in the tenant, over-the-air update will fail for devices that have the sideloaded image because the over-the-air update process includes a rollback mechanism which relies on those images being present in the Azure Sphere Security Service tenant.
If you are using just one tenant, the manufacturing preparation steps to Get production-signed images results in the required images being in your tenant.
If you are using more than one tenant, you must retain the original image files that you uploaded to get production-signed images, and upload the same image files to any other tenant into which you claim a device with those images sideloaded. This applies to application images and to board configuration images. Note that the image ID is randomly generated during the application build process, so regenerating images from source does not fulfill this requirement.
Note
Images cannot be downloaded from one tenant and uploaded to another tenant. If you are using multiple tenants, you must retain the image files that you uploaded to one tenant so that you can upload them to other tenants.
Verify the cloud configuration
As a final step before shipping, verify the cloud configuration for each device. This step checks that the Azure Sphere Security Service targets the images you expect for a device. The image IDs and component IDs of the targeted images should be the same as those of the production-signed images that you sideloaded during the factory-floor process, as described in Load device software. These IDs should have been recorded during the manufacturing preparation.
To find out which images are targeted by the Azure Sphere Security Service, use the azsphere device image list-targeted command as follows. Replace <device ID> with the device ID for the device you're checking. Because the device is not attached to the PC for cloud-configuration tasks, you must include the --device parameter to specify the target device:
azsphere device image list-targeted --device <device-ID>
The command displays the names, component IDs, image IDs, and types of the targeted images for the specified device, as shown in the following sample output:
----------------------- ------------------------------------ ------------------------------------ ------------
Name ComponentId ImageId ImageType
==============================================================================================================
HelloWorld_HighLevelApp 1689d8b2-c835-2e27-27ad-e894d6d15fa9 50419cb6-a33b-4cbe-8bd0-425048664b6f Applications
----------------------- ------------------------------------ ------------------------------------ ------------