Device Firmware Update (DFU)

Description

The DFU Update Module is a reference Update Module that demonstrates how to update firmware of a peripheral device using the Device Firmware Update USB device class.

Example use-cases:

  • Deploy firmware updates to peripheral devices using the USB Device Firmware Update (DFU) protocol

Specification

Module name dfu
Supports rollback no
Requires restart no
Artifact generation script yes
Full system updater no
Source code Update Module, Artifact Generator

It is not recommended to install a Mender Artifact on your workstation

Prepare the device

This section describes how to setup your target device, i.e. the device to be updated. This will also be referred to as the device environment.

All commands outlined in this section should be run in the device environment.

Prerequisites

This update module has the following prerequisites for the device environment:

sudo apt install dfu-utils

This Update Module has the following prerequisites for the development environment:

Install the Update Module

Download the latest version of this Update Module by running:

mkdir -p /usr/share/mender/modules/v3 && wget -P /usr/share/mender/modules/v3 https://raw.githubusercontent.com/mendersoftware/mender-update-modules/master/dfu/module/dfu && chmod +x /usr/share/mender/modules/v3/dfu

Prepare the development environment on your workstation

This section describes how to set up your development environment on your workstation.

All commands outlined in this section should be run in the development environment.

Prerequisites

This Update Modules has the following prerequisites for the development environment:

Create Mender Artifacts

For convenience, an Artifact generator tool dfu-artifact-gen is provided with the Update Module. This tool will generate Mender Artifacts in the same format that the Update Module expects them.

Download dfu-artifact-gen, by running the following command:

wget https://raw.githubusercontent.com/mendersoftware/mender-update-modules/master/dfu/module-artifact-gen/dfu-artifact-gen

Make it executable:

chmod +x dfu-artifact-gen

Create example firmware file to deploy:

echo "File created by Mender single-file Update Module!" > firmware.bin

NOTE! Replace firmware.bin with an actual firmware file built for your target device

Now generate a Mender Artifact using the following command:

ARTIFACT_NAME="my-update-1.0"
DEVICE_TYPE="my-device-type"
./dfu-artifact-gen --artifact-name ${ARTIFACT_NAME} \
                   --device-type ${DEVICE_TYPE} \
                   --firmware-file firmware.bin
  • ARTIFACT_NAME - The name of the Mender Artifact
  • DEVICE_TYPE - The compatible device type of this Mender Artifact

You can either deploy this Artifact in managed mode with the Mender server (upload it under Releases in the server UI) or by using the Mender client only in Standalone deployments.

Artifact technical details

The Mender Artifact used by this Update Module has one payload file, the firmware file that will be passed on to dfu-util on the device.

The Mender Artifact contents will look like:

Mender artifact:
  Name: my-update-1.0
  Format: mender
  Version: 3
  Signature: no signature
  Compatible devices: '[my-device-type]'
  Provides group:
  Depends on one of artifact(s): []
  Depends on one of group(s): []
  State scripts:

Updates:
    0:
    Type:   dfu
    Provides: Nothing
    Depends: Nothing
    Metadata: Nothing
    Files:
      name:     firmware.bin
      size:     50
      modified: 2020-03-09 09:45:19 +0100 CET
      checksum: dacba168198af551264861cab663be17f97f6d000aca283003758ff262c2f4a2