Quickstart: Deploy an application over the air
This quickstart shows how to create your first over-the-air (OTA) application deployment. OTA deployment delivers an application through a feed to the devices in a device group that match the target stock-keeping unit (SKU) for the feed.
The steps in this quickstart assume that:
- Your Azure Sphere device is connected to your PC
- You have completed all the steps to install Azure Sphere
- You have completed Quickstart: Build the Blink sample application and retained the image package for the application
Prepare your device for OTA deployment
Before you test the OTA deployment process, your Azure Sphere device must be ready to accept OTA application updates. In effect, you "lock" the device and enable OTA updates, which is how it will operate at a customer site. The azsphere device prep-field command is the simplest way to do this. This command:
- Disables the ability for Visual Studio to load applications onto the device, so that only OTA applications can be loaded
- Assigns a new product SKU to the device
- Assigns the device to a new device group that enables OTA application updates
The azsphere device prep-field command works on the device that is connected to your PC. It has the following form:
azsphere device prep-field --newdevicegroupname <unique-dg-name> --newskuname <unique-sku-name>
The --newdevicegroupname flag specifies a name for the new device group that the command creates. Learn about device groups here. All device groups created by this command support automatic OTA application updates. Supply a descriptive name that is unique among the device group names in your Azure Sphere tenant.
The --newskuname flag specifies a name for the new product SKU that the command creates. A product SKU identifies a model of the connected device that contains an Azure Sphere chip. Each SKU in an Azure Sphere tenant must have a unique name.
The Azure Sphere Security Service uses the device group and the SKU to determine whether to update the application on a device.
Enclose any strings that include spaces in double quotation marks, like "this string".
For example, the following command creates a new device group named FieldGroupOTA that enables OTA application updates and assigns the attached device to it. It also creates a new product SKU named FieldProductSKU and assigns that SKU to the device.
azsphere device prep-field --newdevicegroupname "FieldGroupOTA" --newskuname "FieldProductSKU" Removing applications from device. Successfully removed applications from device. Locking device. Downloading device capability configuration for device ID 'ABCDEF82513B529C45098884F882B2CA6D832587CAAE1A90B1CEC4A376EA2F22A96C4E7E1FC4D2AFF5633B68DB68FF4420A5588B420851EE4F3F1A7DC51399ED'. Successfully downloaded device capability configuration. Applying device capability configuration to device. Successfully applied device capability configuration to device. The device is rebooting. Successfully locked device. Creating a new device group with name 'FieldGroupOTA'. Setting device group ID '655d7b12-07ad-4e8a-b104-c0ec494b8489' for device with ID 'ABCDEF82513B529C45098884F882B2CA6D832587CAAE1A90B1CEC4A376EA2F22A96C4E7E1FC4D2AFF5633B68DB68FF4420A5588B420851EE4F3F1A7DC51399ED'. Creating a new SKU with name 'FieldProductSKU'. Setting product SKU to '946410a0-0057-4b11-af68-d56a684f6681' for device with ID 'ABCDEF82513B529C45098884F882B2CA6D832587CAAE1A90B1CEC4A376EA2F22A96C4E7E1FC4D2AFF5633B68DB68FF4420A5588B420851EE4F3F1A7DC51399ED'. Successfully set up device 'ABCDEF82513B529C45098884F882B2CA6D832587CAAE1A90B1CEC4A376EA2F22A96C4E7E1FC4D2AFF5633B68DB68FF4420A5588B420851EE4F3F1A7DC51399ED' for OTA loading. Command completed successfully in 00:00:15.0013734.
You aren't required to create a new device group and SKU every time you prepare a device for field use. Typically, you would create one SKU for each product model, and one device group for each collection of devices that you want to update together. For additional details, see prep-field.
Link the device to a feed
The next step in deployment is to link your device to a feed that delivers the Blink application. You must supply:
- The ID of Azure Sphere OS feed on which the application depends
- The path to the image package file that Visual Studio created for the Blink application
- A name for the feed that will deliver the application
To link to a feed
Get the feed ID for the Retail Azure Sphere feed, which delivers the Azure Sphere OS. The feeds that you see might differ from those in the example.
azsphere feed list Listing all feeds. Retrieved feeds: --> [3369f0e1-dedf-49ec-a602-2aa98669fd61] 'Retail Azure Sphere OS' --> [82bacf85-990d-4023-91c5-c6694a9fa5b4] 'Retail Evaluation Azure Sphere OS' Command completed successfully in 00:00:03.0017019.
Copy the ID for the Retail Azure Sphere OS feed to use in the next step.
Issue the azsphere device link-feed command to create a feed and associate it with the Blink image package that you created in Quickstart: Build the Blink sample application.
azsphere device link-feed --dependentfeedid 3369f0e1-dedf-49ec-a602-2aa98669fd61 --imagepath <path-to-image> --newfeedname <unique-name>
The --dependentfeedid flag supplies the ID of the Retail feed.
The --imagepath flag provides the path to the image package file for the Blink application. As noted in Quickstart: Build the Blink sample application, the full path to the image file is displayed in the Visual Studio 2017 Build Output window. The azsphere device link-feed command uploads the image package file to the Azure Sphere Security Service and creates an image set with a unique name.
The --newfeedname flag provides a name for the feed that the command creates. Feed names must be unique in an Azure Sphere tenant, so specify a name that distinguishes this feed from any others.
azsphere device link-feed --dependentfeedid 3369f0e1-dedf-49ec-a602-2aa98669fd61 --imagepath "C:\Users\Test\Documents\Visual Studio 2017\Projects\Mt3620Blink2\Mt3620Blink2\bin\ARM\Debug\Mt3620Blink2.imagepackage" --newfeedname "BlinkFeed" Getting the details for device with ID 'ABCDEF82513B529C45098884F882B2CA6D832587CAAE1A90B1CEC4A376EA2F22A96C4E7E1FC4D2AFF5633B68DB68FF4420A5588B420851EE4F3F1A7DC51399ED'. Uploading image from file 'C:\Users\Test\Documents\Visual Studio 2017\Projects\Mt3620Blink2\Mt3620Blink2\bin\ARM\Debug\Mt3620Blink2.imagepackage': --> Image ID: '116c0bc5-be17-47f9-88af-8f3410fe7efa' --> Component ID: '54acba7c-7719-461a-89db-49c807e0fa4d' --> Component name: 'Mt3620Blink2' Create a new feed with name 'BlinkFeed'. Adding feed with ID 'ce680169-d893-49de-bb02-5f2c40c52932' to device group with ID '655d7b12-07ad-4e8a-b104-c0ec494b8489'. Creating new image set with name 'ImageSet-Mt3620Blink2-2018.07.19-18.15.42+01:00' for image with ID '116c0bc5-be17-47f9-88af-8f3410fe7efa'. Adding image set with ID '6e9cdc9d-c9ca-4080-9f95-b77599b4095a' to feed with ID 'ce680169-d893-49de-bb02-5f2c40c52932'. Successfully linked device 'ABCDEF82513B529C45098884F882B2CA6D832587CAAE1A90B1CEC4A376EA2F22A96C4E7E1FC4D2AFF5633B68DB68FF4420A5588B420851EE4F3F1A7DC51399ED' to feed with ID 'ce680169-d893-49de-bb02-5f2c40c52932'. Command completed successfully in 00:00:12.8912364.
This command creates a feed that is linked to the device group to which the attached device belongs—that is, the FieldGroupOTA created earlier in this quickstart. It will deliver the Mt3620Blink2 application to all Azure Sphere devices in the group whose product SKU is FieldProductSKU.
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 a couple of minutes, and you should see LED 1 start to blink.
To verify that the application was installed on your device:
azsphere device image list-installed
This command returns the following information about the installed images:
Installed images: --> gdbserver --> Image type: Application --> Component ID: 8548b129-b16f-4f84-8dbe-d2c847862e78 --> Image ID: 43d2707f-0bc7-4956-92c1-4a3d0ad91a74 --> Mt3620Blink2 --> Image type: Application --> Component ID: 54acba7c-7719-461a-89db-49c807e0fa4d --> Image ID: 116c0bc5-be17-47f9-88af-8f3410fe7efa Command completed successfully in 00:00:01.5159298.
As you continue to develop and test applications, you will probably want to use Visual Studio to load them until you're ready to deploy them more broadly. To reverse the device prep-field command and enable the device for development and debugging, use device prep-debug, as you did when you built the application:
azsphere device prep-debug
- Moves the device to a device group that disables OTA application updates
- Enables the device capability to accept applications from Visual Studio for debugging
We'd love to hear your thoughts. Choose the type you'd like to provide:
Our feedback system is built on GitHub Issues. Read more on our blog.