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 over-the-air (OTA) software updates. Cloud configuration involves the following tasks, which must be completed in the order specified:

1. Claim the chip into a catalog
2. Configure cloud deployments for over-the-air (OTA) software updates
3. Ensure that sideloaded images are present in the catalog
4. 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 catalog, 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 catalog 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 <DeviceIdValue> 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:

az sphere device claim --resource-group MyResourceGroup --catalog MyCatalog --device <DeviceIdValue>

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 az sphere device assign 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. To find the value of the --targeted-device-group and devicerun the command az sphere device-group list.

The following example shows how to re-assign 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.

To find the value of the --targeted-device-group and devicerun the command az sphere device-group list

az sphere device assign --resource-group MyResourceGroup --catalog MyCatalog --target-product MyProduct --target-device-group MyCurrentDeviceGroup --device <DeviceIdValue>

If the device has never been assigned before, this command can be shortened to exclude --product and --device-group.

az sphere device assign --resource-group MyResourceGroup --catalog MyCatalog --targeted-device-group /subscriptions/GUID/resourceGroups/MyResouceGroup/providers/Microsoft.AzureSphere/catalogs/MyCatalog/products/DW100/deviceGroups/Production --device <DeviceIdValue>

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 catalog

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 catalog that the device is claimed into. If these images are not present in the catalog, 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 catalog.

If you are using just one catalog, the manufacturing preparation steps to Get production-signed images results in the required images being in your catalog.

If you are using more than one catalog, you must retain the original image files that you uploaded to get production-signed images, and upload the same image files to any other catalog 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 catalog and uploaded to another catalog. If you are using multiple catalogs, you must retain the image files that you uploaded to one catalog so that you can upload them to other catalogs.

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 az sphere image list-targeted command as follows. Replace <DeviceIdValue> 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:

az sphere image list-targeted --resource-group MyResourceGroup --catalog MyCatalog --device <DeviceIdValue>

The command displays the names, component IDs, image IDs, and types of the targeted images for the specified device.