Firmware Update¶

Overview¶

Device Hub allows to manage the firmware update of your devices. It allows easy organization of firmware images for different product variants and versions.

Additional processing of the firmware images can be configured, such that the same firmware image can be delivered to your device in different formats. Like this, you can use the same firmware image for programming to your device in the factory, or deliver it over-the-air to update your device in the field.

We assume you are already familiar with the concept of Products and Models on Device Hub. For each Model, you can define multiple Channels (see section Channels) to further distinguish the firmware configuration of your devices.

In the scope of each Channel, the set of released Firmwares is defined.

Also in the scope of each Channel, Delivery Methods and Delivery Procedures are defined. Together, they define how to pre-process the firmware image before it is downloaded from the Device Hub. For example, for a specific bootloader defined by the Delivery Method, there can be two Delivery Procedures: One to provide the Firmware as a factory image with bootloader; the other to provide the Firmware as encoded and encrypted FOTA image. See Delivery Methods and Delivery Procedures for more details and examples. There we will also explain what Attachments and Plugins mean in this context.

To make the relation between the objects required for a firmware update more clear, the object hierarchy is shown here:

classDiagram
    direction RL
    class Model
    class Channel
    class Firmware
    class DeliveryMethod
    class Attachment
    class Plugin

    Channel "0..n" --* "1" Model
    Firmware "0..n" --* "1" Channel
    DeliveryMethod "0..n" --* "1" Model
    DeliveryProcedure "0..n" --* "1" DeliveryMethod
    Attachment "0..n" --* "1" DeliveryMethod
    VersionStrategy "1" -- DeliveryProcedure
    Plugin "0..n" -- DeliveryProcedure

Firmware object hierarchy

Channels¶

A Channel adds an additional level to organize devices after the Product and Model level. An instant of a Firmware always belongs to exactly one Channel.

Example

Channels can for example be used to distinguish service areas, customers, or use cases for which firmware updates should be managed separately.

The access rights can be set that such that area managers can approve a new Firmware only on a specific Channel.

Delivery Methods and Delivery Procedures¶

A Delivery Method belongs to a specific Model. For each Delivery Method, one or multiple Delivery Procedures can be defined.

Together, the Delivery Method and the Delivery Procedure define how a Firmware is delivered during a firmware update. This means it chooses the appropriate firmware version and pre-processes the image before delivery.

For each Delivery Method, you can upload files (Attachments). These Attachments can be used by the Plugins which define the behavior of the Delivery Procedure.

How to use Delivery Methods and Delivery Procedures is best explained with an example:

Example

Your company has a Model X. It is a device which contains an immutable bootloader and an updatable firmware. If you release a Firmware for Model X, you want to use it for either factory programming or OTA updates. Therefore, you need one Delivery Method called Custom Bootloader v1, and add the bootloader as an Attachment to it. You need two Delivery Procedures. One is called Factory Programming, and the other is called OTA Upate. These Delivery Procedures are configured with the appropriate Plugins such that they deliver the Firmware combined with the bootloader, or encoded and encrypted for OTA updates, respectively.

If you release a second version or variant of your bootloader, you create a second Delivery Method called Custom Bootloader v2 with that bootloader as an Attachment. The Delivery Procedures for Custom Bootloader v2 would look similar to the ones for Custom Bootloader v1.

When a device asks for a firmware request, it indicates the required Delivery Method and Delivery Procedure, such that it receives the Firmware encoded to match its bootloader encoding scheme.

example_delivery_procedure Example delivery procedures "Factory Programming" and "OTA Update"

Example

Your company has a Model X. It is a device which consists of two MCU's which run different firmware, and have a different bootloader. The two bootloaders (let's say bl-mcu-A_v1.bin and bl-mcu-B_v2.bin) are therefore added as Attachment to your Delivery Method. A released Firmware is the combination of the two firmware images (e.g. as a .zip archive). You create then three Delivery Procedures: MCU A Factory Programming, MCU B Factory Programming, and OTA Update. With MCU A Factory Programming, the bootloader of MCU A is combined with one of the firmware versions for MCU A. With MCU B Factory Programming, the same is done for MCU B. With OTA Update a combination of the firmware for MCU A and MCU B is delivered.

Object Life Cycle¶

The object Life Cycle enables to incorporate review processes into the workflow grace to a "draft" state.

The Life Cycle finite state machine has the following states:

Draft: changes to the object are allowed and no review is requested
Pending Approval: object can be deleted, rejected or accepted.
Approved: reviewer accepted the Pending Approval. In this state an object can not be changed any more unless it is deleted.
Pending Deletion: requested for deletion
Deleted: object is deleted

Info

If desired, two-person integrity can be enabled for an Organization. By enabling this feature, the user who published the object is not able to accept its own publish request. In this case, a second person must approve the request. The two-person integrity applies also for deletion.

This is an expert feature. Please contact Leitwert support if you are required to use this feature.

stateDiagram-v2
    draft: Draft
    pending_approval: Pending Approval
    approved: Approved
    pending_delete: Pending Delete
    deleted: Deleted

    [*] --> draft
    draft --> pending_approval: publish
    draft --> [*]: delete
    pending_approval --> draft: reject
    pending_approval --> approved: accept
    pending_approval --> [*]: delete
    approved --> pending_delete: delete
    pending_delete --> approved: reject
    pending_delete --> deleted: accept

The following objects are subjected to the Life Cycle:

Organisation
Token (revoke only)
Product
Model
Classification
Channel
Delivery Method
Delivery Procedure
Firmware

How to's¶

How to create a channel¶

Prerequisites:

Product and Model of the device have been defined

Navigate to Firmware and then to the section Channels. There, select the Product and Model for which you want to create the Channel for. Click the + Channel button.

create_channel
How to create a new channel

Enter a Name and a Textual ID for the Channel. The Textual ID must be unique for each Channel per Model. The Name is for display only. Then click Save.

create_channel_2
Enter Name and Textual ID for the new channel

Info

You need sufficient permission to create Channels. Your user must be associated with a role which has the required permission for Channels (e.g. Edit permission). An Object Authorization for the desired Model instance (or its parent object) must exit such that the role is applicable. See also User Access Management.

How to create a delivery method¶

Prerequistes:

Product and Model of the device have been defined

Navigate to Firmware and then to the section Delivery Methods. There, select the Product and Model for which you want to create the Delivery Method for. Click the + Delivery Method button.

create_delivery_method
How to create a new delivery method

Enter a Name and a Description for the Delivery Method. The Name and Description are for display only. Then click Save.

create_delivery_method_2
Enter name and description for the delivery method

Info

You need sufficient permission to create Delivery Methods. Your user must be associated with a role which has the required permission for Delivery Methods (e.g. Edit permission). An Object Authorization for the desired Model instance (or its parent object) must exit such that the role is applicable. See also User Access Management.

How to create a delivery procedure¶

Prerequisites:

Product and Model of the device have been defined
Delivery Method for the Model has been defined

Navigate to Firmware and then to the section Delivery Procedures. There, select the Product, Model, and Delivery Method for which you want to create the Delivery Procedure for. Click the + Delivery Procedure button.

create_delivery_procedure
How to create a new delivery procedure

The configuration of the Delivery Procedure is organized in six sections:

General
Device
Update Options
Expiration Policy
Parameters
Stages - Expert Mode

create_delivery_procedure_2
Enter configuration for the delivery procedure

Info

You need sufficient permission to create Delivery Procedures. Your user must be associated with a role which has the required permission for Delivery Methods and Delivery Procedures (e.g. Edit, Add procedure permission). An Object Authorization for the desired Delivery Method instance (or its parent object) must exit such that the role is applicable. See also User Access Management.

General¶

In the "General" section, set a Name, Comment and Handle for the Delivery Procedure.

Name and Comment are for display only. The Handle must be unique within the context of the Model.

Device¶

Required: If enabled, firmware requests are required to specify device instance.
Autotracking: If enabled, a device instance is created if its ID is passed in with the firmware request the first time.

Update Options¶

Version Strategy: Specifies the version strategy plugin to use. When not specified, the default simple-semantic-version strategy is selected. The simple-semantic-version strategy selects the latest firmware version.
Max Concurrent Pipelines: Specifies the maximum number of parallel firmware updates in the processing queue.
Retry Time: Wait time responded to a firmware request when the maximum number of parallel firmware updates is exceeded.
Auto Start: If enabled, the firmware request state (see firmware update states) automatically transitions from ready to queued. This reduces the number of required actions by the device.
Enable Confirm Step: If enabled, the firmware update is expected to be confirmed by the device.

Expiration Policy¶

Ready: The expiration time for a firmware update session in ready state.
Up To Date: The expiration time for a firmware update session in up_to_date state.
Success: The expiration time for a firmware update session in success state.
Fail: The expiration time for a firmware update session in fail state.

See firmware update states for more details about the firmware update states.

Parameters¶

Parameters which will be required to be passed from the device for a firmware update request can be defined in this section.

The parameter values will be accessible by the Plugins or the Delivery Procedure.

Note

This is an expert feature. Please contact Leitwert support if you are required to use this feature.

Stages - Expert Mode¶

In the Message field you can specify the sequence of Plugins which process the Firmware (input) during the processing step of the firmware update request.

To simply provide the Firmware image uploaded to Device Hub, the following configuration can be used:

## This plugin creates a download link that will expire in 900s (15min).
# The app can download the firmware this way.
- plugin_id: builtin-download-local
  config:
    expire_in: 900
    version: 1
    input_payloads:
      content: input
    mime_type: application/octet-stream

Note

This is an expert feature. Please contact Leitwert support if you are required to use this feature.

How to add a firmware¶

This is how you can upload firmware to the Device Hub and release it for your devices.

Prerequisites:
- Product and Model of the device have been defined
- Channel for the Model has been defined
- Delivery Method and Delivery Procedure for the Model have been defined

To follow the steps, navigate to Firmware and then again to the section Firmware.

Select the related Product, Model and Channel from the dropdown menu. Enter the version of the firmware you are uploading (numbers up to 64 bit). Enter the publishing date and time, after which the firmware will be made available for your devices.
In Metadata you can enter information that is needed by your Delivery Procedure (e.g. a required minimum version already installed on the device). Additionally, you can add a disclaimer and release notes for your firmware.
Upload the firmware file. The size of the file is limited to 200 MB.
Click Save

Note

Firmware version numbers are limited to 64 bit
Firmware file size is limited to 200 MB

firmware_upload
How to upload firmware to the server

Info

You need sufficient permission to add Firmwares. Your user must be associated with a role which has the required permission for Firmwares (e.g. Edit permission). An Object Authorization for the desired Channel instance (or its parent object) must exit such that the role is applicable. See also User Access Management.

How to approve a firmware¶

The Firmware object follows the Object Life Cycle such that a review process can be incorporated.

When the Firmware instance is added (see How to add a firmware), it is in Draft state.

approve_firmware

Example firmware updates, where versions 0.0.1, 0.0.2, and 0.0.3 are in Approved state, but 0.1.0 is in Draft state

To transition its state to Approved, click the Publish button on the firmware's detail view. If two-person integrity is not enabled, the state will immediately transition to Approved. If two-person integrity is enabled, the state will transition to Pending Approval. A different user must click the Confirm Approval button to transition the state to Approved. If the Reject Approval button is clicked instead, the state transitions back to Draft.

approve_firmware
Click the Publish button to approve a firmware

two_person_integrity_approval
If two-person integrity is enabled, the Firmware must be approved by a second user

Info

A firmware in Draft state will only be visible to a device which indicates that it allows draft firmwares (for example Device API calls for firmware update with allow_draft_firmware set to True).

Info

A firmware can only get approved if its parent objects (i.e. Channel, Model, Product and Organization) have been approved, too.

Warning

If a firmware is in Draft state, the firmware image can be replaced and its metadata can be changed. When it is approved, these cannot be changed anymore, and deletion will just mark it as deleted but not remove it from the database.

It is common sense that production devices must not be allowed to get a firmware in Draft state. Otherwise, someone might change the image for a firmware version without notice!

Info

You need sufficient permission to approve Firmwares. Your user must be associated with a role which has the required permission for Firmwares (e.g. Authorize permission). An Object Authorization for the desired Channel instance (or its parent object) must exit such that the role is applicable. See also User Access Management.

Last update: 2023-05-04