Skip to content

Configuring Edge Xrt Using a Device Twin

Edge Xrt Azure Sphere applications are configured using the IoT Hub Device Twin configuration mechanism. The Xrt component and device service configuration are obtained using the "desired properties" in the device twin JSON document.

Desired Properties Format

The desired properties must provide component configuration and service configuration.

Component Configuration

The component configuration consists of a JSON object named Components. The named objects within the components object will be "main" and names of components referenced by the "main" configuration. The content of the main and component objects is in the same format as a file-based Xrt configuration.

Service Configuration

The service configuration consists of a JSON object named "Services". The named objects within the services object will match the device service's "Name" configuration variable. The content of these objects will be objects named "Devices", "Profiles" and "Schedules". These three objects have the same formats as described in Device Service Components.

An example of the component configuration and service configuration is available here.

Initial State

When an Azure Sphere application is first installed, the initial configuration is built into the application. The initial configuration is defined using a set of JSON configuration files in the usual Xrt format. Typically, this will consist of an AzureSphere Exporter configuration and its dependant components.

The initial configuration will be used be to connect to Azure and obtain the current configuration.

Persisted State

When a new configuration is obtained from the device twin, it is persisted to the Azure Sphere device's mutable storage. When the Azure Sphere device boots, it will use the persisted configuration if no updated configuration is provided by the Azure digital twin.

Configuring a Digital Twin

An Azure Sphere digital twin can be configured using the Microsoft Azure web portal or using the Azure APIs. The following describes how to configure the digital twin using the Azure portal.

  1. Login to the Azure Portal

  2. Navigate to your IoT Hub. This can be found under the "All resource" button or might be shown in the list of "Recent Resources".

  3. Select "Devices" in the left-hand column of the IoT Hub page.

  4. Determine the Device ID of your Azure Sphere development board.

  5. The Device ID can be found using the command

    azsphere device show-attached

  6. Select the device in the portal.

  7. If the matching Device ID is not visible on the IoT Hub | Devices page you can locate it by pasting the Device ID into the "Device name" search box and clicking "Find devices".

  8. Select the "Device twin" tab on the device page.

  9. Edit the "properties" / "desired" object as required.

  10. Example JSON excerpts are provided in the "twin" directory. The can be copied into the "desired" object and modified as needed.

  11. Save the changes using the "Save" button.

Component Re-configuration

If a new component configuration is provided at startup the Azure Sphere device will reboot to ensure the new configuration is applied.

Runtime Re-configuration

If the Components or Services desired properties are updated while the Azure Sphere device is active the new configuration will be persisted and the device rebooted.

Updating the Configuration

The Azure IoT APIs can be used to update device twin configurations. A Python example can be found here.