Device capabilities and communication

  • Article

The device capabilities determine device-specific OS policies for service-UART communication. All communication between the host computer and an attached device is through the service UART. The host computer communicates with an attached device to perform operations on the device. Manufacturers, software developers, and field service technicians use capabilities to unlock service-UART communication for the operations that they require while ensuring that the device is protected against malicious users.

Device manufacturers and OEMs can lock down service-UART communication to prevent unauthorized use by those who have physical access to the device. Locking down such communication 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 a customer site.

A device capability file contains zero or more capabilities for a single device only. The capability file will not work if applied to a device that is not the one for which it is intended. A device can have the following capabilities, each of which is described later in this topic:

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.

How to determine device capabilities or manufacturing state

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

The device capabilities can be affected by the manufacturing state of the device. To determine the manufacturing state of the device, use the az sphere device manufacturing-state show command. If the command shows that the device is in the DeviceComplete manufacturing state or returns Device access is forbidden, service-UART communication is locked and you need a device capability to communicate with the device from your computer. When a device is in the DeviceComplete manufacturing state, manufacturing operations are permitted only when the device is unlocked via a capability file.

Note

If you install a device at a customer site, you should ensure that the device is finalized to the DeviceComplete manufacturing state before installation. See Finalize the Azure Sphere device.

The DeviceComplete manufacuring state is normally not appropriate for a dev kit. To enable testing of the manufacturing operations being developed by manufacturing engineers, a dev kit should be in either the Blank manufacturing state or the Module1Complete manufacturing state.

How devices acquire capabilities

Devices can acquire capabilities in one of three ways:

  • Opened by default. A device that is in either the Blank manufacturing state or the Module1Complete manufacturing state has 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 catalogs, as is required by the process of using device capability files to unlock capabilities. As manufacturing progresses, manufacturers can change the manufacturing state of the device to lock down capabilities that are no longer appropriate, as described in Factory-floor tasks.

  • Sideloaded onto the device. A device may have a capability file sideloaded onto the device from the host computer. Use the az sphere device capability download command to retrieve the capability file. This sideloaded 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 az sphere device enable-development command 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.

  • Passed to the device with each operation. A device can have locally selected capabilities applied on a per-operation basis. The az sphere device capability apply command selects a capability file that is stored locally on the host computer. Once this command is run, the selected capability is passed from the computer to the device with each subsequent command. This is the recommended way of using capabilities for devices that are in the field because the capabilities are stored on the computer rather than the device. The risk of a field engineer accidentally leaving the device in an unsecured state by forgetting to remove the capability is avoided.

Before a capability file can be sideloaded onto a device or passed to a device with an operation, it must be downloaded from the Azure Sphere Security Service (AS3), as described in Make changes to a device after manufacture. Downloaded capability files are device specific; once downloaded, a capability file can be used repeatedly on the associated device.

The enableRfTestMode capability

The enableRfTestMode capability is present by default on the device when the device's manufacturing state is Blank. This capability enables the programming of e-fuses and the the configuration and testing of RF operation. It is not possible for catalog owners to download this capability to a host computer. If you need this capability, contact your Microsoft representative.

When the device's manufacturing state is Blank, the az sphere device capability show-attached command displays the enableRfTestMode capability.

The appDevelopment capability

The appDevelopment device capability unlocks service-UART 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 service-UART communication to allow the following operations:

  • Sideloading an image package that is built with Visual Studio, Visual Studio Code, the CLI, or the az sphere 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, use the az sphere device enable-development command. This command downloads the appDevelopment capability for the attached device, sideloads the capability onto the device, and moves the device to the default Development device group. To specify a different device group, include the --device-group parameter.

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

The az sphere device enable-development and az sphere 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 az sphere device capability command to download or update a device capability, or to find out which capabilities a device currently has.

The fieldServicing capability

The fieldServicing capability is present on a device by default when the device has a manufacturing state of Blank or Module1Complete. When a device is in the DeviceComplete manufacturing state, the fieldServicing capability can be sideloaded, but is typically passed to the device with each operation during a servicing session. For details about how to start a servicing session, see Make changes to a device after manufacture.

Regardless of the device's manufacturing state, the fieldServicing capability unlocks service-UART communication to allow the following operations:

  • Sideloading a production-signed image package.
  • Starting, stopping, and deleting a production-signed image package that is marked as temporary.
  • Performing routine maintenance tasks such as configuring Wi-Fi.

Although the fieldServicing capability is present by default on the device when the device's manufacturing state is Blank or Module1Complete, the az sphere device capability show-attached command does not display the fieldServicing capability.

Dependency on up-to-date trusted keystore

When a capability file is created by AS3, it is signed using the current image-signing key. Each device has a trusted keystore as part of the OS where those keys are kept. However, if the device is not connected to the internet, then it is possible for a capability to not be trusted by the device it is targeting if that device's trusted keystore is out of date.

To remedy this, one method is to allow the device to connect to the internet so that it updates the trusted keystore. Connect your device to the internet and press Reset to trigger an OS update.

If this is not possible, then you can sideload an updated trusted keystore. To do this, accept the license terms then download the latest OS recovery images, and from this zip file extract just the "trusted-keystore.bin" file. Then you can use the command az sphere device sideload deploy --image-package <path-to-trustedkeystore.bin-file> to sideload the trusted keystore, and the capability should now be trusted by the device.

A third method is Recover the system software to update the Azure Sphere OS to the latest released version, including the latest trusted keystore.