.. _nrf_desktop_fwupd:

nRF Desktop: fwupd support
##########################

.. contents::
   :local:
   :depth: 2

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) <LVFS_>`_, 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 :ref:`nrf_desktop_bootloader_background_dfu` 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 :ref:`nrf_desktop_config_channel` is branded as ``nordic_hid``.

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:

.. code-block:: console

   [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 :file:`nordic-hid.quirk` file.

LVFS and update image preparation
*********************************

The `LVFS (Linux Vendor Firmware Service) <LVFS_>`_ 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 |NCS|, that is :file:`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.
#. Fetch the information about available update images from the LVFS using the following commands:

   .. code-block:: console

      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.

#. 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.
#. Run the following command to update the devices:

   .. code-block:: console

      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 :ref:`nrf_desktop_config_channel`.
If the device does not provide information about the bootloader type, such information can optionally be provided inside the :file:`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.
