Make changes to a device after manufacture

One of the final steps in the manufacture of an Azure Sphere device is to put the device into the DeviceComplete state, which secures the device against modification. There are, however, situations in which devices that have been put into the DeviceComplete state need to be modified.

The secure mechanism used for such scenarios is to use a device capability. There are two types of device capability, fieldServicing and appDevelopment, and you should use the one that has the minimum set of features required. That is, if the fieldServicing capability meets your needs, then you should use that, but if greater flexibility is required, use the appDevelopment capability instead. While the capabilities were designed for the two scenarios after which they are named, you should check the actual functionalities enabled rather than relying on that name. Only the tenant owner of the device can acquire capabilities for that device, and each capability is restricted to a single device.

When making changes to a DeviceComplete device, you should not sideload those capabilities. This is to eliminate the risk of accidentally leaving the capability present, and thereby leaving the device in an insecure state. Instead, you should use a servicing session.

There are three stages to using capabilities to service devices: downloading the capabilities, applying a trusted keystore update (if necessary), and then creating a servicing session.

Download a capability

You can download a capability using the azsphere device capability download command. You must have access to the tenant that owns the device and internet access to download a capability. 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:

   • Azure Sphere CLI
   • Azure Sphere classic CLI

   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:

   • Azure Sphere CLI
   • Azure Sphere classic CLI

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

   Provide the device 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.

Update the trusted keystore if necessary

If a device is not connected to the internet, then there is a possibility that the device will not trust the capability. This occurs when AS3 has updated its image signing key with which it signs all images including capability images, but the device does not have this updated key in its trusted keystore. Any connected device automatically updates its trusted keystore, but if the device is not connected then that may not have occurred.

To remedy this, see detailed instructions here.

Create a servicing session

To service a device, you create a servicing session by selecting a capability. 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:

1. Connect the device to the PC using the Programming and Debugging Interface.

2. 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, 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. 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.