Tutorial: Create a cloud deployment
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.
This quickstart shows how to create your first cloud-based application deployment. Cloud-based deployment delivers an application through a deployment assigned to a device group within the target product.
In this tutorial, you learn how to:
- Create a product
- Enable cloud-based deployment for your device
- Create the deployment
- Trigger deployment
- Re-enable development and debugging
Prerequisites
- Your Azure Sphere device is connected to your computer and to the internet.
- You have completed the Tutorial: Build a high-level application and have an image package file for your application.
Create a product
A product identifies a model of Azure Sphere device that performs a specific function and runs a particular application.
If you do not already have a product, create one using the azsphere product create command.
azsphere product create --name MyProduct --description "My First Product"
Product names must be unique within your Azure Sphere tenant and are not case sensitive. If the name contain spaces, enclose it in double quotation marks in commands, as in the example.
The azsphere product create command automatically creates five default device groups for the new product: Development, Field Test, Production, Field Test OS Evaluation, and Production OS Evaluation. Device groups provide a way for you to organize your devices according to how you're using them.
Enable cloud-based deployment for your device
Before you test the cloud-based deployment process, your Azure Sphere device must be ready to accept cloud-based application updates. Use the azsphere device enable-cloud-test command to prepare your device:
azsphere device enable-cloud-test --product MyProduct
This command:
- Identifies the device as the MyProduct model, which was created in the previous step.
- Assigns the device to the Field Test device group, which enables cloud-based application updates.
- Disables the ability for the SDK to load applications onto the device, so that only cloud-based applications can be loaded.
The Azure Sphere Security Service uses the device group and the product to determine whether to update the application on a device.
Create the deployment
A deployment is a set of images that can be deployed from the Azure Sphere cloud service to the devices within a particular device group.
To create a deployment:
- Upload the image package to your Azure Sphere tenant using azsphere image add.
- Create a new deployment for a device group for the uploaded images using azsphere device-group deployment create.
- Upload the image package:
azsphere image add --image <path-to-image>
The output should show something like the following:
Uploading image from file 'Blink.imagepackage':
--> Image ID: <image-ID>
--> Component ID: <component-ID>
--> Component name: 'Blink'
Removing temporary state for uploaded image.
Successfully uploaded image with ID '<image-id>' and name 'Blink' to component with ID '<component-id>'.
You will use the Image ID in the next step.
- Create a new deployment for a device group:
azsphere device-group deployment create --device-group <device-group-ID> --images <image-ID>
or
azsphere device-group deployment create --device-group '<product-name>/<device-group-name>' --images <image-ID>
For the product MyProduct and device group Field Test, you can use this second form to create your deployment easily:
azsphere device-group deployment create --device-group "MyProduct/Field Test" --images <image-ID>
To provide multiple values for --images enter a list of values separated by spaces.
The --device-group parameter identifies the device group. The device group ID supplies a GUID, which uniquely identifies the device group across all products. Alternatively, you can use the product name and device group name pair in the <product-name>/<device-group-name> format. This pair of names uniquely identifies a device group for a particular product.
Specify the Field Test device group and the name of the product that you created in Create a product.
Replace <image-ID> with the image ID of the image package that you created in Tutorial: Build a high-level application. For Azure Sphere CLI, see azsphere device-group deployment create for information on getting the image ID.
To verify that the deployment is set up, use the azsphere device image list-targeted command.
Trigger the deployment
The previous steps set up all the required deployment elements. To trigger the download immediately, press the Reset button on the Azure Sphere device. The application should download and start within several minutes, and you should see the LED start to blink.
To verify that the application was installed on your device, use the azsphere device image list-installed command. You may not see the results of the deployment immediately. If the deployment is not listed when you run the command, try again in a few minutes. The LED will begin to blink on the Azure Sphere device as soon as the deployment completes.
Next steps
As you continue to develop and test applications, you will probably want to sideload them until you're ready to deploy them more broadly. To reverse the azsphere device enable-cloud-test command and enable the device for development and debugging, use azsphere device enable-development.
Advance to the next article to learn how to:
If you aren't ready to build real-time applications, you might also want to:
- Explore the Azure Sphere samples on GitHub
- Learn more about Azure Sphere deployment basics
Troubleshoot
If you encounter problems with the operations above, refer to troubleshooting guidance.