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. A device capability file contains zero or more capabilities for a single device only and they will not work if applied to another device.

Devices can acquire capabilities in one of three ways:

  • Devices in early phases of the manufacturing process have some capabilities open by default. This is done so that devices still in the manufacturing stage do not need to be connected to the cloud or claimed into tenants, as is required by the process of using device capability files to unlock capabilities. As manufacturing progresses, manufacturers can apply two one-time operations to change the manufacturing state of the device, first to Module1Complete and then to DeviceComplete, to lock down capabilities that are no longer appropriate.

  • Devices may have a capability file sideloaded onto the device. This set of capabilities persists until a new capability file (which may be a blank file with no capabilities) is sideloaded. This is the usual situation during application development, for example, when the command azsphere device enable-development is run. Application development is aided by having the device in an "unlocked" state where the developer can perform operations such as debugging and easily delete and deploy sideloaded versions of the application.

  • Devices can also have capabilities applied on a per-operation basis, which enables those operations but are not persistently stored on the device. This is the recommended way of using capabilities for devices that are in the field, for example, during field servicing of such devices. By using capabilities that are not persistent, the risk of a field engineer accidentally leaving the device in an unsecured state by forgetting to remove the capability is removed. See Create a servicing session.

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 --device-group 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 permits device-to-computer communications on devices that are in the DeviceComplete manufacturing state. With this capability, you can sideload production-signed images, but not delete them. You can start and stop applications, but not debug them. You can also perform routine maintenance tasks such as configuring Wi-Fi. It is intended for short-term use during a servicing session, a limited period during which access to the device is granted on a per-operation basis.

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.

You can download a capability using the azsphere device capability download command. By default, the currently attached device is used. When multiple devices are attached, specify either the IP address, device ID, or Local Connection ID of an attached device in the --device parameter. When downloading a capability for an unattached device, provide a device ID in the --device parameter.

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 following command with the --type and --destination parameters to download a capability file for the attached device. For example:

    azsphere device capability download --type fieldServicing --destination <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 following command with the --device, --type, and --destination parameters to download a capability file for the unattached device. For example:

    azsphere device capability download --device <deviceID> --type fieldServicing --destination <capability-file>
    

    Provide the IP address or Local Connection ID of the device for which you need the capability, and replace <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, enabling the device to perform the command despite its locked state. The capability file is not stored persistently on the device, so the device remains locked and secured. If another computer is later attached to the device without access to the capability file, it will be unable to modify the device.

To create a servicing session:

  • Use the azsphere device capability select command with the --capability-file <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 run 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 run from the current command prompt.

To end the servicing session:

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.