Create a cloud deployment

To deploy your applications from the cloud, you upload application images to an Azure Sphere catalog and create a deployment to distribute images to Azure Sphere devices. To create a deployment, you must be signed in to Azure Sphere and you must have the Administrator role. In addition, your devices must be prepared to receive cloud deployments.

To be valid, a deployment must follow these rules:

• The total size of the deployment must be less than 1 MiB.
• The deployment can have no more than one board configuration file.

Prepare devices

Before devices can receive applications from the cloud, they must have a product and belong to a device group, and cannot have the AppDevelopment capability installed.

If you haven't already created a product for your devices, you need to do so before you can create a deployment. To create a product:

Use the portal

1. Sign in to the Azure Portal. To locate the Azure Sphere service, in the top search bar, enter and select Azure Sphere. The Azure Sphere page is displayed.
2. Select the catalog in which you want to create a deployment. Ensure your subscription filter is set appropriately to see all catalogs and resource groups.
3. Select Manage > Products from the left side of the catalog page.
4. Click + Create from the top of the catalog page.
5. Enter a name and description for the product. Mark the checkbox to indicate if default device groups should be created. If marked, the following default device groups will be created: Development, Field Test, Field Test OS Evaluation, Production, Production OS Evaluation.
6. Finally, click Create at the bottom of the page.

If you chose not to create a default device groups, then a device group must be manually created and associated to the product:

1. Select Manage > Device Groups from the left side of the page.
2. Click + Create at the top of the page.
3. Select the product created from the steps above.
4. Enter a name for the device group and a short description.
5. Select the operating system (OS) feed for the device group. The RetailEval feed receives pre-release OS versions ahead of the Retail feed. The RetailEval is therefore not recommended for production devices. Select the Retail feed for production devices.
6. Select the update policy for the device group. UpdateAll means that devices in the group will take OS and application updates when available. No3rdPartyAppUpdates means that devices in the group will only take OS updates.

Use the CLI

Use the az sphere product create command.

az sphere product create --resource-group MyResourceGroup --catalog MyCatalog  --name MyProduct --description "My new product"

Use the az sphere device-group create command to create a device group and associate it with the product.

az sphere device-group create --resource-group MyResourceGroup --catalog MyCatalog   --name "My Development Device Group" --product MyProduct -d "development device group for MyProduct"

Deployments target device groups. Devices will need to be assigned to a device group that has cloud updates enabled before devices can receive deployed applications. By default, each product has five device groups: Production, Field Test, Development, Field Test OS Evaluation, and Production OS Evaluation. You can use one of these device groups or create your own. To find out whether a device group accepts cloud updates, use az sphere device-group show.

Devices within the device group must be prepared for cloud loading. This means that they must not have the appDevelopment capability. Devices shipped direct from the factory typically do not have the appDevelopment capability. The capability is added when az sphere device enable-development command is used.

To remove the appDevelopment capability, use az sphere device enable-cloud-test:

Use the CLI

Use the az sphere device enable-cloud-test command.

az sphere device enable-cloud-test --resource-group MyResourceGroup --catalog MyCatalog

Create a deployment for a device group

Deployments are sets of images to be distributed to all devices within a device group. A deployment can contain both applications and board configurations. Each deployment is linked to a specific device group within a specific product. You must include either the product name and the device group name (as the following example shows) or the device group ID when you create the deployment.

Use the portal

1. Sign in to the Azure Portal. To locate the Azure Sphere service, in the top search bar, enter and select Azure Sphere. The Azure Sphere page is displayed.
2. Select the catalog in which you want to create a deployment. Ensure your subscription filter is set appropriately to see all catalogs and resource groups.
3. Select Manage > Products on the left side of the page.
4. The next page shows a table with all created products listed. Select the product you want to create a deployment for.
5. A table shows all of the device groups associated with the chosen product. Select the device group you want to create a deployment for.
6. Select the Deployments tab.
7. Click +Create underneath the deployments tab.
8. In the view that appears, select and existing image or click +Add to upload a new image.
9. At the bottom of the view click +Create.

Use the CLI

Complete the steps in Prepare devices before proceeding, then:

1. Upload an image package, taking note of the imageId returned by the command:

   az sphere image add --resource-group MyResourceGroup --catalog MyCatalog --image-path myImage.imagepackage
   

2. Use the azsphere image-package show command to get the imageId of the image package:

   azsphere image-package show --image-package myImage.imagepackage
   

   Note

   image-package show is currently not supported in the Azure CLI extension.

   The command returns information about the image package, including the imageId:

   Image package metadata:
     Section: Identity
      Image Type: Application
      Component ID: 1689d8b2-c835-2e27-27ad-e894d6d15fa9
      Image ID: be3f90bd-849f-487e-a170-7fe1ff03fe2d
     Section: Signature
      Signing Type: ECDsa256
      Cert: a8d5cc6958f48710140d7a26160fc1cfc31f5dfO
     Section: Debug 
      Image Name:       myImage
      Built On (UTC):   02/21/22 16:21:58
      Built On (Local): 02/21/22 16:21:58
     Section: Temporary Image
   

3. Create a new deployment for a device group:

   az sphere deployment create --resource-group MyResourceGroup --catalog MyCatalog --product MyProduct --device-group MyDeviceGroup --images <imageId returned from previous step>
   

Multiple images can be provided to the --images parameter using a space separated list of image IDs.

To list devices groups in a catalog, use az sphere device-group list.

To list all images in a catalog, use az sphere image list.

Update a deployment

It is not possible to update a deployment. Instead, a new deployment must be created. Repeat the steps from the previous section, updating parameters where required.