nRF Desktop: fwupd support

fwupd is an open-source project providing tools and daemon for managing the installation of firmware updates on Linux-based systems. Together with the LVFS (Linux Vendor Firmware Service), it provides a solution for vendors to easily distribute firmware for compatible devices.

The fwupd tools can communicate with devices running the nRF Desktop application with the Background Device Firmware Upgrade feature enabled.

Nordic HID plugin

The fwupd project allows communication with multiple types of devices through various communication protocols. The communication protocols are implemented using plugins. The plugin associated with the DFU protocol realized through the Configuration channel is branded as nordic_hid.

Note

The format version of the dfu_application.zip file generated by the build system was updated from 0 to 1 since the nRF Connect SDK v2.7.0 release. The format version 1 is supported by the fwupd since the 1.9.25 release. Older releases do not support the format version of 1.

Adding a new device

The device specifies which protocol is used for the communication by adding the specific device information to the plugin metadata. For the nordic_hid plugin, this file is located at nordic-hid.quirk. The following example shows the information passed to the plugin metadata:

[HIDRAW\VEN_1915&DEV_52DE]
Plugin = nordic_hid
GType = FuNordicHidCfgChannel
NordicHidBootloader = B0

In this console snippet:

  • [HIDRAW\VEN_1915&DEV_52DE] - This line describes the device instance ID provided by the OS, which identifies the device.

  • Plugin = nordic_hid and GType = FuNordicHidCfgChannel - These lines set the plugin that the device uses.

  • NordicHidBootloader - This optional line selects the bootloader that the device is running. If the device does not have the information about the underlying bootloader, the NordicHidBootloader option is used to select a proper bootloader type. If there is no information about the bootloader, both in metadata and from the device, the update procedure fails. The possible values are either B0, MCUBOOT, or MCUBOOT+XIP.

Note

As the nordic_hid plugin communicates with the device using the Configuration channel, the device update is not allowed through the Serial recovery DFU.

To add a new device, a pull request must be opened to the fwupd repository with a new entry to the nordic-hid.quirk file.

LVFS and update image preparation

The LVFS (Linux Vendor Firmware Service) hosts firmware images that can be downloaded by Linux machines and used by the fwupd tool for the firmware update of compatible devices. A vendor account is needed to upload a new firmware archive to the site. Information on how to apply for an account is found at the LVFS Getting an account website.

The nRF Desktop application DFU image is delivered as a zip package, containing a manifest and one or more binary files used for the update. To prepare an image file compatible with the LVFS, you must prepare a CAB file. The CAB archive must contain the DFU package generated by the nRF Connect SDK, that is dfu_application.zip, plus metadata file with information used by the LVFS. For more information, see the LVFS metadata site.

When the CAB archive has been built, it can be uploaded to the LVFS where it is verified and signed. For more information about creating CAB files, signing, and uploading the update package, see the LVFS Uploading Firmware site.

Upgrading firmware using fwupd

Once the update image is uploaded onto the LVFS, you can test the firmware update procedure on HID hosts that support fwupd.

Complete the following steps:

  1. Make sure that the host machine to which the updatable device running the nRF Desktop application is connected has the fwupd tool installed.

  2. Fetch the information about available update images from the LVFS using the following commands:

    fwupdmgr refresh
fwupdmgr get-updates

    • fwupdmgr refresh - This command downloads the latest metadata from the LVFS.

    • fwupdmgr get-updates - This command displays the updates available for the devices on the host system.

  3. Test the update image on a limited number of devices before it goes public. For more information about limiting the visibility of updated images uploaded to the LVFS, see the LVFS testing site.

  4. Run the following command to update the devices:

    fwupdmgr update

When connecting to the device, the application verifies the bootloader type. This is done to ensure a compatible firmware is uploaded to the nRF Desktop device, that is software that can support multiple bootloaders. The device is queried for information about bootloader using the Configuration channel. If the device does not provide information about the bootloader type, such information can optionally be provided inside the nordic-hid.quirk file (see the NordicHidBootloader option under Adding a new device).

fwupd can fail the image update in the following cases:

  • When the bootloader information stored in an updated image does not match the type reported by the device.

  • When there is no information about the bootloader used on the device.

For more information about building the fwupd tool locally, see the LVFS building fwupd site.