Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

application: nrf_desktop: Align docs after upmerge + migration to sysbuild #15998

Merged
merged 5 commits into from
Jun 21, 2024
Merged

application: nrf_desktop: Align docs after upmerge + migration to sysbuild #15998

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
5b3f548
applications: nrf_desktop: Align after upmerge
mkapala-nordic Jun 13, 2024
868a21d
applications: nrf_desktop: Align after migration to sysbuild
mkapala-nordic Jun 13, 2024
d199782
applications: nrf_desktop: Add note about app version config for MCUboot
mkapala-nordic Jun 14, 2024
866db8e
applications: nrf_desktop: Align after migration to ipc_radio
mkapala-nordic Jun 17, 2024
9bef0f7
applications: nrf_desktop: Add note about version bump for B0
mkapala-nordic Jun 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion applications/nrf_desktop/bluetooth.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,7 +168,7 @@ Fast Pair
=========

The nRF Desktop peripheral can be built with Google `Fast Pair`_ support.
The configurations that enable Fast Pair are set in the :file:`prj_fast_pair.conf` and :file:`prj_release_fast_pair.conf` files.
The configurations that enable Fast Pair are specified in the files with filenames ending with the ``fast_pair`` and ``release_fast_pair`` suffixes.

.. note::
The Fast Pair integration in the nRF Desktop is :ref:`experimental <software_maturity>`.
Expand Down Expand Up @@ -201,6 +201,8 @@ After a successful erase advertising procedure, the peripheral removes all of th

Apart from that, the following changes are applied in configurations that support Fast Pair:

* The ``SB_CONFIG_BT_FAST_PAIR`` Kconfig option is enabled in the sysbuild configuration.
For more details about enabling Fast Pair for your application, see the :ref:`ug_bt_fast_pair_prerequisite_ops_kconfig` section in the Fast Pair integration guide.
* The static :ref:`partition_manager` configuration is modified to introduce a dedicated non-volatile memory partition used to store the Fast Pair provisioning data.
* Bluetooth privacy feature (:kconfig:option:`CONFIG_BT_PRIVACY`) is enabled.
* The fast and slow advertising intervals defined in the :ref:`nrf_desktop_ble_adv` are aligned with Fast Pair expectations.
Expand Down
11 changes: 6 additions & 5 deletions applications/nrf_desktop/board_configuration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,12 +17,13 @@ The application configuration files define both a set of options with which the
Include the following files in this directory:

Mandatory configuration files
* Application configuration file for the :ref:`debug build type <nrf_desktop_requirements_build_types>` (:file:`prj.conf`).
* Application configuration file for the :ref:`debug build type <nrf_desktop_requirements_build_types>`.
* Configuration files for the selected modules.

Optional configuration files
* Application configuration files for other build types.
* Configuration file for the bootloader.
* Configuration file for the sysbuild.
* Memory layout configuration.
* DTS overlay file.

Expand All @@ -43,7 +44,7 @@ nRF52840 Gaming Mouse (``nrf52840gmouse``)
* Bluetooth is configured to use Nordic's SoftDevice link layer.

* The configuration with the B0 bootloader is set as default.
* The board supports ``debug`` (:file:`prj_fast_pair.conf`) and ``release`` (:file:`prj_release_fast_pair.conf`) :ref:`nrf_desktop_bluetooth_guide_fast_pair` configurations.
* The board supports the ``debug`` (``fast_pair`` file suffix) and ``release`` (``release_fast_pair`` file suffix) configurations for :ref:`nrf_desktop_bluetooth_guide_fast_pair`.
Both configurations use the MCUboot bootloader built in the direct-xip mode (``MCUBOOT+XIP``), and they support the firmware updates using the :ref:`nrf_desktop_dfu` and the :ref:`nrf_desktop_dfu_mcumgr`.

nRF52832 Desktop Mouse (``nrf52dmouse``) and nRF52810 Desktop Mouse (``nrf52810dmouse``)
Expand All @@ -58,7 +59,7 @@ Sample mouse, keyboard or dongle (``nrf52840dk/nrf52840``)
* The build types allow to build the application as mouse, keyboard or dongle.
* Inputs are simulated based on the hardware button presses.
* The configuration with the B0 bootloader is set as default.
* The board supports ``debug`` :ref:`nrf_desktop_bluetooth_guide_fast_pair` configuration that acts as a mouse (:file:`prj_fast_pair.conf`).
* The board supports ``debug`` :ref:`nrf_desktop_bluetooth_guide_fast_pair` configuration that acts as a mouse (``fast_pair`` file suffix).
The configuration uses the MCUboot bootloader built in the direct-xip mode (``MCUBOOT+XIP``), and supports firmware updates using the :ref:`nrf_desktop_dfu` and the :ref:`nrf_desktop_dfu_mcumgr`.

Sample dongle (``nrf52833dk/nrf52833``)
Expand All @@ -80,7 +81,7 @@ nRF52832 Desktop Keyboard (``nrf52kbd``)
* The application is configured to act as a keyboard, with the Bluetooth LE transport enabled.
* Bluetooth is configured to use Nordic Semiconductor's SoftDevice link layer.
* The preconfigured build types configure the device without the bootloader in debug mode and with B0 bootloader in release mode due to memory size limits.
* The board supports ``release`` :ref:`nrf_desktop_bluetooth_guide_fast_pair` configuration (:file:`prj_release_fast_pair.conf`).
* The board supports ``release`` :ref:`nrf_desktop_bluetooth_guide_fast_pair` configuration (``release_fast_pair`` file suffix).
The configuration uses the MCUboot bootloader built in the direct-xip mode (``MCUBOOT+XIP``), and supports firmware updates using the :ref:`nrf_desktop_dfu` and the :ref:`nrf_desktop_dfu_mcumgr`.

nRF52840 USB Dongle (``nrf52840dongle/nrf52840``) and nRF52833 USB Dongle (``nrf52833dongle``)
Expand All @@ -102,7 +103,7 @@ Sample dongle (``nrf5340dk/nrf5340``)
Input data comes from Bluetooth and is retransmitted to USB.
* The configuration with the B0 bootloader is set as default.

Sample mouse or keyboard (``nrf54l15pdk/nrf54l15/cpuapp``, ``[email protected]/nrf54l15/cpuapp``)
Sample mouse or keyboard (``nrf54l15pdk/nrf54l15/cpuapp``)
MarekPieta marked this conversation as resolved.
Show resolved Hide resolved
* The configuration uses the nRF54L15 Preview Development Kit (PDK).
* The build types allow to build the application as a mouse or a keyboard.
* Inputs are simulated based on the hardware button presses.
Expand Down
66 changes: 44 additions & 22 deletions applications/nrf_desktop/bootloader_dfu.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,27 +72,47 @@ See :ref:`nrf_desktop_memory_layout` for details.
Configuring the B0 bootloader
=============================

To enable the B0 bootloader, select the :kconfig:option:`CONFIG_SECURE_BOOT` Kconfig option in the application configuration.
To enable the B0 bootloader, select the ``SB_CONFIG_SECURE_BOOT_APPCORE`` Kconfig option in the sysbuild configuration.
This setting automatically enables the ``SB_CONFIG_SECURE_BOOT_BUILD_S1_VARIANT_IMAGE`` Kconfig option, which generates application binaries for both slots in non-volatile memory.

The B0 bootloader additionally requires enabling the following options in the application configuration:
The B0 bootloader additionally requires enabling the following options:

* :kconfig:option:`CONFIG_SB_SIGNING_KEY_FILE` - Required for providing the signature used for image signing and verification.
* :kconfig:option:`CONFIG_FW_INFO` - Required for the application versioning information.
* :kconfig:option:`CONFIG_FW_INFO_FIRMWARE_VERSION` - Enable this option to set the version of the application after you enabled :kconfig:option:`CONFIG_FW_INFO`.
The nRF Desktop application with the B0 bootloader configuration builds two application images: one for the S0 slot and the other for the S1 slot.
To generate the DFU package, you need to update this configuration only in the main application image as the ``s1_image`` child image mirrors it.
You can do that by rebuilding the application from scratch or by changing the configuration of the main image through menuconfig.
* :kconfig:option:`CONFIG_BUILD_S1_VARIANT` - Required for the build system to be able to construct the application binaries for both application's slots in non-volatile memory.
* In the sysbuild configuration:

* ``SB_CONFIG_SECURE_BOOT_SIGNING_KEY_FILE`` - Required for providing the signature key file used by the build system (to sign the application update images) and by the bootloader (to verify the application signature).
If this Kconfig option does not specify the signature key file, debug signature key files will be used by default.

* In the application configuration:

* :kconfig:option:`CONFIG_FW_INFO` - Required for providing information about the application versioning.
* :kconfig:option:`CONFIG_FW_INFO_FIRMWARE_VERSION` - Required for updating the application version.
The nRF Desktop application with the B0 bootloader configuration builds two application images: one for the S0 slot and the other for the S1 slot.
To generate the DFU package, update this configuration only in the main application image.
The ``s1_image`` image will mirror it automatically.

.. note::
To ensure that update image will boot after a successful DFU image transfer, the update image's version number must be higher than the version number of the application image running on device.
Otherwise, the update image can be rejected by the bootloader.

.. _nrf_desktop_configuring_mcuboot_bootloader:

Configuring the MCUboot bootloader
==================================

To enable the MCUboot bootloader, select the :kconfig:option:`CONFIG_BOOTLOADER_MCUBOOT` Kconfig option in the application configuration.
To enable the MCUboot bootloader, select the ``SB_CONFIG_BOOTLOADER_MCUBOOT`` Kconfig option in the sysbuild configuration.

The MCUboot private key path (:kconfig:option:`CONFIG_BOOT_SIGNATURE_KEY_FILE`) must be set only in the MCUboot bootloader configuration file.
You must also set the MCUboot private key path (``SB_CONFIG_BOOT_SIGNATURE_KEY_FILE``) in the sysbuild configuration.
The key is used both by the build system (to sign the application update images) and by the bootloader (to verify the application signature using public key derived from the selected private key).
If this Kconfig option is not overwritten in the sysbuild configuration, debug signature key files located in the MCUboot bootloader repository will be used by default.

To select a specific version of the application, set the :kconfig:option:`CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION` Kconfig option in the application configuration.
If the nRF Desktop application is configured with the MCUboot in the direct-xip mode, the build system builds two application images: one for the primary slot and the other for the secondary slot, named ``mcuboot_secondary_app``.
You need to update this configuration only in the main application image, as the ``mcuboot_secondary_app`` image mirrors it.

.. note::
When the MCUboot bootloader is in the direct-xip mode, the update image must have a higher version number than the application currently running on the device.
This ensures that the update image will be booted after a successful DFU image transfer.
Otherwise, the update image can be rejected by the bootloader.

The MCUboot bootloader configuration depends on the selected way of performing image upgrade.
For detailed information about the available MCUboot bootloader modes, see the following sections.
Expand All @@ -116,12 +136,13 @@ Direct-xip mode

The direct-xip mode is used for the :ref:`background DFU <nrf_desktop_bootloader_background_dfu>`.
In this mode, the MCUboot bootloader boots an image directly from a given slot, so the swap operation is not needed.
To set the MCUboot mode of operations to the direct-xip mode, make sure to enable the :kconfig:option:`CONFIG_MCUBOOT_BOOTLOADER_MODE_DIRECT_XIP` Kconfig option in the application configuration.
This option automatically enables :kconfig:option:`CONFIG_BOOT_BUILD_DIRECT_XIP_VARIANT` to build application update images for both slots.
To set the MCUboot mode of operations to the direct-xip mode, enable the ``SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP`` Kconfig option in the sysbuild configuration.
This option automatically enables the ``SB_CONFIG_MCUBOOT_BUILD_DIRECT_XIP_VARIANT`` Kconfig option, which builds the application update images for both slots.
The nRF Desktop application configurations do not use the direct-xip mode with the revert mechanism (``SB_CONFIG_MCUBOOT_MODE_DIRECT_XIP_WITH_REVERT``).

Enable the ``CONFIG_BOOT_DIRECT_XIP`` Kconfig option in the bootloader configuration to make the MCUboot run the image directly from both image slots.
The nRF Desktop's bootloader configurations do not enable the revert mechanism (``CONFIG_BOOT_DIRECT_XIP_REVERT``).
When the direct-xip mode is enabled (the :kconfig:option:`CONFIG_MCUBOOT_BOOTLOADER_MODE_DIRECT_XIP` Kconfig option is set in the application configuration), the application modules that control the DFU transport do not request firmware upgrades and do not confirm the running image.
The ``CONFIG_BOOT_DIRECT_XIP`` Kconfig option enables MCUboot to run the image directly from both image slots, and it is automatically applied to the bootloader configuration based on the sysbuild configuration.
Similarly, the :kconfig:option:`CONFIG_MCUBOOT_BOOTLOADER_MODE_DIRECT_XIP` Kconfig option, that informs the application about the MCUboot bootloader's mode, is also applied automatically based on the sysbuild configuration.
When the direct-xip mode is enabled, the application modules that control the DFU transport do not request firmware upgrades or confirm the running image.
In that scenario, the MCUboot bootloader simply boots the image with the higher image version.
MarekPieta marked this conversation as resolved.
Show resolved Hide resolved

By default, the MCUboot bootloader ignores the build number while comparing image versions.
Expand All @@ -137,6 +158,7 @@ Serial recovery mode
In the :ref:`USB serial recovery <nrf_desktop_bootloader_serial_dfu>` mode, the MCUboot bootloader uses a built-in foreground DFU transport over serial interface through USB.
The application is not involved in the foreground DFU transport, therefore it can be directly overwritten by the bootloader.
Because of that, the configuration with the serial recovery mode requires only a single application slot.
To set the MCUboot mode of operations to single application slot, enable the ``SB_CONFIG_MCUBOOT_MODE_SINGLE_APP`` Kconfig option in the sysbuild configuration.

Enable the USB serial recovery DFU using the following configuration options:

Expand All @@ -155,12 +177,12 @@ You must select the ``CONFIG_MCUBOOT_INDICATION_LED`` Kconfig option to enable t
By default, both the GPIO pin and the LED are defined in the board's DTS file.
See :file:`boards/nordic/nrf52833dongle/nrf52833dongle_nrf52833.dts` for an example of board's DTS file used by the nRF Desktop application.

For an example of bootloader Kconfig configuration file defined by the application, see the MCUboot bootloader ``debug`` configuration defined for nRF52833 dongle (:file:`applications/nrf_desktop/configuration/nrf52833dongle_nrf52833/child_image/mcuboot/prj.conf`).
For an example of a bootloader Kconfig configuration file defined by the application, see the MCUboot bootloader ``debug`` configuration defined for nRF52833 dongle (:file:`applications/nrf_desktop/configuration/nrf52833dongle_nrf52833/images/mcuboot/prj.conf`).

.. note::
The nRF Desktop devices use either the serial recovery DFU with a single application slot or the background DFU.
Both mentioned firmware upgrade methods are not used simultaneously by any of the configurations.
For example, the ``nrf52840dk/nrf52840`` board in ``prj_mcuboot_smp.conf`` uses only the background DFU and does not enable the serial recovery feature.
For example, the ``nrf52840dk/nrf52840`` board in ``mcuboot_smp`` file suffix uses only the background DFU and does not enable the serial recovery feature.

.. _nrf_desktop_suit:

Expand Down Expand Up @@ -245,13 +267,13 @@ The update image is generated in the build directory when building the firmware
MCUboot and B0 bootloaders
--------------------------

The :file:`zephyr/dfu_application.zip` file is used by both B0 and MCUboot bootloader for the background DFU through the :ref:`nrf_desktop_config_channel` and :ref:`nrf_desktop_dfu`.
The :file:`<build_dir>/dfu_application.zip` file is used by both B0 and MCUboot bootloader for the background DFU through the :ref:`nrf_desktop_config_channel` and :ref:`nrf_desktop_dfu`.
The package contains firmware images along with additional metadata.
If the used bootloader boots the application directly from either slot 0 or slot 1, the host script transfers the update image that can be run from the unused slot.
Otherwise, the image is always uploaded to the slot 1 and then moved to slot 0 by the bootloader before boot.

.. note::
Make sure to properly configure the bootloader to ensure that the build system generates the :file:`zephyr/dfu_application.zip` archive containing all of the required update images.
Make sure to properly configure the sysbuild to ensure that the build system generates the :file:`<build_dir>/dfu_application.zip` archive containing all of the required update images.

SUIT
----
Expand Down Expand Up @@ -369,13 +391,13 @@ Once the device enters the serial recovery mode, you can use the :ref:`mcumgr <z

* Query information about the present image.
* Upload the new image.
The :ref:`mcumgr <zephyr:device_mgmt>` uses the :file:`zephyr/app_update.bin` update image file.
The :ref:`mcumgr <zephyr:device_mgmt>` uses the :file:`<build_dir>/zephyr/nrf_desktop/zephyr.signed.bin` update image file.
It is generated by the build system when building the firmware.

For example, the following line starts the upload of the new image to the device:

.. code-block:: console

mcumgr -t 60 --conntype serial --connstring=/dev/ttyACM0 image upload build-nrf52833dongle/zephyr/app_update.bin
mcumgr -t 60 --conntype serial --connstring=/dev/ttyACM0 image upload build-nrf52833dongle/zephyr/nrf_desktop/zephyr.signed.bin

The command assumes that ``/dev/ttyACM0`` serial device is used by the MCUboot bootloader for the serial recovery.
Loading
Loading