Skip to content

Firmware Deployment Service

Idea

This service provides an interface for installing firmware to devices.

Extensibility

The Firmware Deployment Service guarantees that it will adhere to the contract specified in the API specification. It will return the listed fields as specified. However, additional fields might be introduced as backwards compatible extensions of the API.
Make sure that your client is able to handle such extensions gracefully.

Access

For accessing this service you need to have the respective roles listed in Firmware Deployment Service roles and scopes.

Download URIs

Download URIs specified in the installation tasks must contain embedded credentials or refer to public resources. Devices access the URIs directly without using Insights Hub credentials.

Basics

The Firmware Deployment Service tracks the status of firmware installation tasks. The typical workflow for installing firmware on a device is:

  1. The user selects a published firmware release via a user interface.
  2. The associated terms and conditions document is presented to the user.
  3. The user has to accept the terms and conditions. This information can be stored and queried using the Firmware Deployment Service.
  4. After accepting the terms and conditions, the user can trigger the firmware installation via the user interface.
  5. The Firmware Deployment Service automatically verifies that the user's device is of the correct device type and sends the task to the device.
  6. The device receives the task.
  7. The device performs the firmware update while sending status messages to the Firmware Deployment Service. Meanwhile, the task can be updated or canceled via the user interface.
  8. The Firmware Deployment Service receives the task's result and records version information of the actual firmware on the device.

State Machine

The Firmware Deployment Service uses a state machine to track the installation progress. For detailed information, refer to the Basics.

Periodic Polls

Devices have to regularly poll for open jobs from this service using the following endpoint:

GET /api/firmwaredeployment/v3/devices/{deviceId}/installation/jobs

Features

The Firmware Deployment Service exposes its API for realizing the following tasks:

  • install firmware releases on devices
  • manage firmware installation tasks
  • record user's acceptance of terms and conditions

Limitations

  • Devices access the download URI as provided. Hence, Insights Hub credentials must either be embedded in the URI or the resource must be publicly accessible.
  • Firmware installation tasks older than 90 days are automatically cleaned up.

Controlled Content

Upload, download and distribution operations of controlled content to Industrial IoT are not allowed. Users are accountable for the content of files they distribute using Edge Services.

Example Scenario

The producer of a sensor, which uploads data to Industrial IoT, wants to regularly provide new versions of their firmware to their customers. They develop an app, which uses the Firmware Deployment Service for uploading the firmware to the devices. The service automatically verifies that the firmware is compatible with the user's device. Before installtion, the app requests that the user accepts the terms and conditions of a release. Their acceptance is recorded using the Firmware Deployment Service, so the user won't be asked again when updating multiple devices of the same type.


Last update: June 15, 2023

Except where otherwise noted, content on this site is licensed under the Development License Agreement.