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.

Prerequisites

The steps in this quickstart assume that:

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.

Tip

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 ota-test-3 --newskuname test-sku-3

Removing applications from device.
Component '68c95ce8-e06c-4713-95f2-00cc1861a996' deleted or was not present beforehand.
Removing debugging server from device.
Component '8548b129-b16f-4f84-8dbe-d2c847862e78' deleted or was not present beforehand.
Successfully removed applications from device.
Locking device.
Downloading device capability configuration for device ID <deviceID>.
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 'ota-test-3'.
Setting device group ID 'fee1a5fe-59a3-44fc-8fc1-ab6848e09490' for device with ID <deviceID>.
Creating a new SKU with name 'test-sku-3'.
Setting product SKU to 'ae7927d0-1cbd-4e87-995a-495964e7facf' for device with ID <deviceID>.
Successfully set up device <deviceID> for OTA loading.
Command completed successfully in 00:00:15.5644027.

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.

The next step in deployment is to link your device to a feed that delivers the high-level Blink sample that you build from the template. 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

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

  2. 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 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 application, the full path to the image file is displayed in the Visual Studio 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.

    For example:

    azsphere device link-feed --dependentfeedid 3369f0e1-dedf-49ec-a602-2aa98669fd61 --imagepath "C:\Users\user\Documents\Visual Studio 2017\Projects\AzureSphereBlink3\AzureSphereBlink3\bin\ARM\Debug\AzureSphereBlink3.imagepackage" --newfeedname blink-feed-test-3

    Getting the details for device with ID <deviceID>.
    Uploading image from file 'C:\Users\user\Documents\Visual Studio 2017\Projects\AzureSphereBlink3\AzureSphereBlink3\bin\ARM\Debug\AzureSphereBlink3.imagepackage':
     --> Image ID:       5fae38c5-48ee-4934-96b0-445b4f3e68fa
     --> Component ID:   68c95ce8-e06c-4713-95f2-00cc1861a996
     --> Component name: 'AzureSphereBlink3'
    Removing temporary state for uploaded image.
    Create a new feed with name 'blink-feed-test-3'.
    Adding feed with ID '21b69146-2d6d-4aec-b626-e70b6a19dc2c' to device group with ID 'fee1a5fe-59a3-44fc-8fc1-ab6848e09490'.
    Creating new image set with name 'ImageSet-AzureSphereBlink3-2019.05.07-18.30.00-07:00' for images with these IDs: 5fae38c5-48ee-4934-96b0-445b4f3e68fa.
    Adding image set with ID '607a5a24-c648-40c5-b496-6c5338a263fd' to feed with ID '21b69146-2d6d-4aec-b626-e70b6a19dc2c'.
    Successfully linked device <deviceID> to feed with ID '21b69146-2d6d-4aec-b626-e70b6a19dc2c'.
    Command completed successfully in 00:00:33.3283634.   
    

    This command creates a feed that is linked to the device group to which the attached device belongs—that is, the ota-test-2 group created earlier in this quickstart. It will deliver the AzureSphereBlink3 application to all Azure Sphere devices in the group whose product SKU is test-sku-3.

    If you see an error like the following, someone else who uses your Azure Sphere tenant has already uploaded a component with the same name.

    error: A component with the same name ('Mt3620Blink1') already exists. Change the name in the application manifest and create a new image package. Trace ID: 38749b6a-c64e-4adb-80f4-4dcac8c5be77 error: Command failed in 00:00:05.1624969.

    Change the name of the component in the app_manifest.json file, rebuild the application to create a new image package, and issue the azsphere device link-feed command again.

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:

azsphere device image list-installed

Enable debugging

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

This command:

  • Moves the device to a device group that disables OTA application updates
  • Enables the device capability to accept applications from Visual Studio for debugging

Next steps