Cloud configuration tasks

After the product that contains the Azure Sphere device is finalized but before it is shipped, you must configure the device for network and cloud-loading. Cloud configuration requires the following information:

• The device ID of each Azure Sphere chip
• The product for each connected device
• The intended device group for each connected device

The PC that you use for cloud configuration must be connected to the internet, but it is not required to be connected to each chip.

The following steps are required for cloud configuration:

1. Claim the chip
2. Configure cloud software deployments
3. Verify the cloud configuration

These steps are critical to the continued operation of the device at the customer site.

Claim the chip

Each Azure Sphere chip has a unique and immutable device identifier, called its device ID. The silicon manufacturer creates the device ID, stores it on the chip, and registers it with Microsoft. This device registration ensures that Microsoft is aware of all Azure Sphere chips and that only legitimate chips can be used in connected devices. As part of the factory-floor process, you should record the device IDs of all Azure Sphere chips that your company receives.

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

The Manufacturing Samples package contains sample scripts that claim multiple manufactured devices in parallel and assign them to a device group for cloud-loading, which is required before they ship. Please contact your Microsoft representative if you need this package.

Internet connectivity is not required to obtain device IDs but is required for claiming. You can record the device IDs, store them on the factory floor, and then transfer the IDs to a different computer later for claiming. To claim one or more chips, open a command-line interface using PowerShell, Windows command prompt, or Linux command shell, and run the following command:

azsphere device claim --device <device ID>

azsphere device claim --deviceid <device ID>

Replace <GUID> with the device ID of the chip you want to claim.

Create a cloud deployment

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. To learn about products, device groups, and deployments, see Deployment basics.

Configure cloud deployments

Assign both the product and the device group before shipping the connected device.

If you haven't already created a product for this model of connected device, create one as follows:

azsphere product create --name <product-name> --description <product description>

Replace <product-name> with an alphanumeric name for the product and <product-description> with a human-readable description. Enclose any strings that contain spaces in quotation marks. The product name must be unique within your Azure Sphere tenant. When you create a product, Azure Sphere creates default device groups for the product. You can use these device groups or create your own.

To assign the product to a device and a device group within that product, use the azsphere device update command. The following shows how to add a device to the default Production device group, which enables cloud updates and is appropriate for connected products at end-user sites. For example:

azsphere device update --device-group DW100/Production

azsphere device update --devicegroupname Production --productname DW100

This command assigns a single attached device to the Production group for the DW100 product.

Ensure that sideloaded images are present in the tenant

All images sideloaded to a device on the factory floor (except for temporary applications for testing that are later deleted) must also be present in the tenant that the device is claimed into. Specifically, the tenant must have images with the same image IDs and component IDs. 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 to cope with update failure which relies on those images being present in the Azure Sphere Security Service tenant.

If you are using just one tenant, the process of obtaining 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 obtain 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.

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 this device. To find out which images will be downloaded for a particular device, use the azsphere device image list-targeted command:

azsphere device image list-targeted --device <device ID>

azsphere device image list-targeted --deviceid <device ID>

Replace <device ID> with the device ID for the device you're checking. The targeted images should be the same as the production-signed images that you sideloaded during manufacturing. The output shows the names, types, component IDs and image IDs of the images targeted at the device. For example:

 ----------------------- ------------------------------------ ------------------------------------ ------------
 Name                    ComponentId                          ImageId                              ImageType
 ==============================================================================================================
 HelloWorld_HighLevelApp 1689d8b2-c835-2e27-27ad-e894d6d15fa9 50419cb6-a33b-4cbe-8bd0-425048664b6f Applications
 ----------------------- ------------------------------------ ------------------------------------ ------------