Device capabilities and communication

Device capabilities determine device-specific OS policies, such as whether computer-to-device communications are allowed. Manufacturers, software developers, and field service technicians use capabilities to unlock access to the device features they require, while ensuring that the device is protected against malicious users. Device capabilities are granted on a per-device basis by the Azure Sphere Security Service.

Note

Device capabilities are not related to application capabilities. Application capabilities specify the resources that an application requires at runtime. See application manifest for more information about application capabilities.

Default device capabilities

Starting with the 20.01 release, connected device manufacturers and OEMs can lock down computer-to-device communications (such as communications over USB) to prevent unauthorized use by those who have physical access to the device. Locking down such access is part of device finalization. After finalization, a user can get the ID of a device, but nothing more; all other operations require a device capability. Finalization is typically performed on the factory floor before the manufacturer ships the device to an end user site, but some dev kit manufacturers may finalize devices as well.

If you have an Azure Sphere dev kit, the operations that you can perform depend on which version of the OS is installed on the kit and whether the manufacturer finalized the device.

  • Dev kits that are shipped with a pre-20.01 OS allow computer-to-device communications to get the device ID, configure Wi-Fi, and get device status. To sideload or remove an image package, or to stop, start, or debug an application, you need to use the appDevelopment capability.

  • Dev kits that are shipped with the 20.01 OS or later may allow computer-to-device communication only to get the device ID, or may allow you to configure Wi-Fi and get device status, depending on the manufacturer. Regardless, if you plan to use the dev kit for application development, you'll need to use the appDevelopment capability.

To determine whether your dev kit unlocks computer-to-device communication, use the azsphere device manufacturing-state show command. If the command shows that the device is in the DeviceComplete state or returns Device access is forbidden, communication is locked and you need a device capability to communicate with the device from your computer.

To determine the capability configuration stored on the attached device, use the azsphere device capability show-attached command. The command displays the capabilities configured using a capability file and some, but not all, capabilities present by default on boards.

For a complete list of the azsphere commands that require a device capability, see Overview of azsphere.

The appDevelopment capability

The appDevelopment device capability unlocks computer-to-device communication and changes the type of signing that the device trusts. It is intended for use during application development.

By default, Azure Sphere devices trust production-signed image packages that are downloaded by the Azure Sphere Security Service, but do not trust SDK-signed image packages. Therefore, you cannot create an image package with the SDK and sideload it onto your Azure Sphere device for debugging unless the device has the appDevelopment capability. The appDevelopment capability causes the device to trust the image package and enables you to start, stop, debug, or remove an application from the device.

In summary, the appDevelopment capability unlocks the following operations:

  • Sideloading an image package that was built with Visual Studio, Visual Studio Code, the CLI, or the azsphere image-package command.
  • Starting, stopping, debugging, or removing an image package from the Azure Sphere device, regardless of how the image package is signed.

To add the appDevelopment capability during application development, use the azsphere device enable-development command. This command unlocks device-to-computer communications, enables sideloading and other development activities, and moves the device to the default Development device group. To specify a different device group, add the --devicegroupid or --devicegroupname parameter.

When you use azsphere device enable-development, the device remains unlocked until you explicitly lock it. To relock the device, use the azsphere device enable-cloud-test command. This command removes the capability and changes the device group, depending on the command-line parameters supplied.

If you later install the device at an end-user site, you should ensure that the device is finalized to the DeviceComplete state before installation. See Finalize the Azure Sphere device and azsphere device manufacturing-state for details.

The azsphere device enable-development and azsphere device enable-cloud-test commands perform a sequence of actions that prepare a device for development and debugging or for cloud deployments, respectively. Instead of using these commands, you can use the azsphere device capability command to download or update a device capability, or to find out which capabilities a device currently has.

Downloaded capabilities are device-specific; once downloaded, they can be used repeatedly on the associated device.

The fieldServicing capability

The fieldServicing capability unlocks device-to-computer communications on devices that are in the DeviceComplete manufacturing state. It does not unlock the ability to manipulate image packages on the device. It is intended for short-term use during a servicing session, a limited period during which access to the device is unlocked.

Internet access is required to download the fieldServicing capability for a device, but a computer-to-device connection is not required. If you need to service a device in a location where internet access is not available, you can download the capability beforehand from an internet-connected computer.

To download the capability for an attached device:

  1. Log in to the Azure Sphere tenant in which the device is claimed.

  2. Use the azsphere device capability download command with the --type and --output parameters to download a capability file for the attached device. For example:

    azsphere device capability download --type fieldServicing --output <capability-file>

    Replace <capability-file> with the location on your computer in which to store the capability file.

To download the capability for an unattached device:

  1. Log in to the Azure Sphere tenant in which the device is claimed.

  2. Use the azsphere device capability download command with the --deviceid, --type, and --output parameters to download a capability file for the attached device. For example:

    azsphere device capability download --deviceid <deviceID> --type fieldServicing --output <capability-file>

    Replace <deviceID> with the ID of the device for which you need the capability, and <capability-file> with the location on your computer in which to store the capability file.

Create a servicing session

To set up or service a device at a customer site, you create a servicing session by selecting a capability. During the servicing session, you can configure Wi-Fi and perform other maintenance tasks. Each time the azsphere command is issued during the session, the selected capability is passed to the device, thus unlocking access. The capability file remains on your computer. When the servicing session ends, so does computer-to-device communication, and the device is locked.

To create a servicing session:

  • Use the azsphere device capability select command with the --filepath <capability-file> parameter. Replace <capability-file> with the file path you specified when you downloaded the capability.

After you select the file, your session starts. Each time the azsphere command is issued during the session, the capability information is passed to the device, thus unlocking communication. The capability is stored on your computer and is associated with your Windows or Linux login data, not with your Azure Sphere login. The servicing session applies to all azsphere commands that are directed at the device from your computer, not just those issued from the current command prompt.

To end the servicing session:

  • Use the azsphere device capability select --none command

When this command succeeds, the capability information is no longer passed to the device. If you do not end the session, the next time you issue an azsphere command from this computer, the current device capability will be passed along with the command, and thus the command will fail if you are working with a different device. We also recommend that you delete the capability file from your computer. If you delete the capability file without ending the servicing session, the next command will warn you that the selected capability file is missing and clear the selection for any further commands.