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

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

  1. Get the feed ID for the "Preview MT3620" 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:
    --> [550f4b02-9fab-48c4-98ec-535d3d933e7b] 'Waffle Maker Feed'
    --> [3369f0e1-dedf-49ec-a602-2aa98669fd61] 'Preview MT3620'
    Command completed successfully in 00:00:03.0017019.
    

    Copy the ID for "Preview MT3620" 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 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 "Preview MT3620" 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.

    For example:

    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 information about the installed image in JSON format:

[
  {
    "uid": "54acba7c-7719-461a-89db-49c807e0fa4d",
    "image_type": 10,
    "is_update_staged": false,
    "does_image_type_require_restart": false,
    "name": "Mt3620Blink2",
    "images": [
      {
        "uid": "116c0bc5-be17-47f9-88af-8f3410fe7efa",
        "length_in_bytes": 16580,
        "uncompressed_length_in_bytes": 16580,
        "replica_type": 0
      }
    ]
  }
]
Command completed successfully in 00:00:01.5266994.

The UID at the top of the JSON is the component ID, and the UID in the "images" section is the image ID. Image type 10 denotes a customer application. The other fields are primarily for Microsoft use.

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