Deployment basics

Deployment involves grouping the Azure Sphere devices that should run the same applications and OS versions, packaging the applications you want to run on each group of devices, uploading the packages to the Azure Sphere Security Service, and assigning the deployment to a group of devices. This topic defines the fundamental elements involved in deployment.

Naming conventions

Names for products and device groups can only contain alphanumeric characters and spaces. It cannot exceed 50 characters. If you include spaces in names, enclose the names in double quotation marks when used in a command.

Device IDs

An Azure Sphere device ID uniquely identifies an individual Azure Sphere chip. The device ID is stored on the device itself. All the other elements of a deployment are stored with the Azure Sphere Security Service.

Products

A product identifies an Azure Sphere MCU that is incorporated into a connected device to perform a specific function. As the manufacturer, you create a product for each model of a connected device, such as a dishwasher or coffeemaker. For example, Contoso creates a product for its DW100 dishwashers and assigns this product to each DW100 dishwasher during manufacturing. Each product has a GUID that is unique within the tenant and cannot be changed.

Every connected device has a single product, but a single product can be associated with many devices. Each product has a name that must be unique within its tenant, along with a description. The product name and description provide a human-readable way to distinguish one product from another. The name and description of the product can be modified as often as you wish.

Device groups

A device group is a named collection of devices of the same product type. Device groups provide a way to scale application deployment to many devices. Each device belongs to exactly one device group, and each device group belongs to exactly one product. When you create a product, default device groups are created within the product to assist with basic functionality, such as testing and production deployment. Even though the names of the default groups are the same in each product, the device groups are unique. The default device groups are:

  • Development: The Development group is intended for use by developers who sideload applications as part of the development process. By default, devices in this group receive the Retail OS feed; application updates are disabled. To test against a different OS version, you can change the default OS for the group.
  • Field Test: The Field Test group is intended for use by developers who are testing devices in a lab or field trial. By default, devices in this group receive the Retail OS feed and all application updates.
  • Production: The Production group is intended for production devices of a particular product. By default, devices in this group receive the Retail OS feed and all application updates.
  • Field Test OS Evaluation: The Field Test OS Evaluation group is intended for use by developers who are verifying the compatibility of new versions of the Azure Sphere OS with applications on test devices in a lab or field trial. By default, devices in this group receive the Retail Evaluation OS feed and all application updates.
  • Production OS Evaluation: The Production OS Evaluation group is intended for use in verifying the compatibility of new versions of the Azure Sphere OS with production applications. By default, devices in this group receive the Retail Evaluation OS feed and all application updates.

You may choose to create additional device groups to organize your products. For example, Contoso might use the Development group for the devices in its engineering lab and the Field Test group for the devices that its deployment team uses in the corporate operations center. Instead of placing all production devices in the Production group, however, Contoso might create groups for devices in various geographic regions, so that it can easily deploy localized versions of its applications.

To deploy applications to Azure Sphere devices, assign them to device groups. Each device within a device group will automatically receive the applications that are assigned to its group; any other applications will be deleted.

Applications

An application is a program that performs tasks specific to certain connected devices. A deployment delivers the application to the products that are associated with those connected devices.

Images and image packages

An image is a binary file that represents a single version of an application or board configuration. Images are immutable: you cannot modify an image after it has been uploaded. For an application, the image includes the binaries for the application along with its image metadata. An image package is the combination of an image with its metadata that is produced by the build process. Every time the SDK builds or rebuilds an Azure Sphere image package, it uses a new unique image ID.

When Contoso develops an application for its DW100 dishwashers, the SDK creates an image package that can be deployed to any device groups.

Chip SKUs and system software

As a product manufacturer, you develop and manage applications, whereas Microsoft develops and manages system software components. System software components target chip SKUs. The chip SKU (stock keeping unit) identifies a particular type of Azure Sphere-compatible MCU. The chip SKU is assigned by Microsoft and cannot be changed. Microsoft uses this SKU to deliver the correct system software updates to each Azure Sphere device.

Deployment

In the simplest terms, a deployment is the delivery of a set of image packages to one or more devices. You create a deployment by:

  • Creating a product by using azsphere product create
  • Creating additional device groups, if necessary, by using azsphere device-group create
  • Assigning devices to device groups by using azsphere device update
  • Creating image packages by using the Azure Sphere SDK
  • Associating the image packages with a device group by using azsphere device-group deployment create

Create a deployment provides step-by-step instructions for creating cloud deployments.

The Azure Sphere Security Service targets all the members of a device group with the deployments that are associated with that group—and only those deployments. This means that if you move a device from one group to another, the device will receive only the deployment that is associated with the new device group (if any); any other image packages (or board configurations) that are already on the device will be deleted. Thus, the Security Service ensures that each device has all the images that its deployment specifies, and no others.

Deployments cannot be removed or turned off for a device group, but you can update an existing deployment by creating a new deployment for the device group. If you want to remove a deployment from a particular device, you can move the device to another device group that does not have a deployment assigned.

Using CLI v1 and CLI v2 Beta

The CLI v2 Beta is installed alongside the existing CLI on both Windows and Linux, so you have access to either interface. The original v1 CLI continues to work as it always has. To use CLI v2 Beta:

  • On Windows, use PowerShell or a standard Windows command prompt.
  • On Linux, use any command shell. Specify the azsphere command if you set CLI v2 Beta as the default during SDK installation, or the azsphere_v2 command if you set the v1 CLI as the default.

See Azure Sphere CLI v2 Beta for details about the features and commands supported by CLI v2 Beta.

Important

  • On Windows, the Azure Sphere Developer Command Prompt shortcut can be used only with CLI v1.
  • The azsphere reference documentation has been updated to include details of available parameters and examples for both versions. We also present examples for both versions in the Quickstarts and Tutorials. However, examples elsewhere in the documentation still reflect the original CLI v1. We will update those examples when CLI v2 is promoted out of the Beta phase to long-term stable (LTS).