nRF Desktop

The nRF Desktop is a reference design of a Human Interface Device (HID) that is connected to a host through Bluetooth® Low Energy or USB, or both. Depending on the configuration, this application can work as desktop mouse, gaming mouse, keyboard, or connection dongle. See nRF Desktop reference design page for an overview of supported features.

Tip

To get started with hardware that has pre-configured software, go to the User interface section.

The nRF Desktop application supports common input hardware interfaces like motion sensors, rotation sensors, and buttons scanning module. You can configure the firmware at runtime using a dedicated configuration channel established with the HID feature report. The same channel is used to transmit DFU packets.

Overview: Firmware architecture

The nRF Desktop application design aims at high performance, while still providing configurability and extensibility.

The application architecture is modular, event-driven and build around Common Application Framework. This means that parts of the application functionality are separated into isolated modules that communicate with each other using application events, which are handled by the Application Event Manager. Modules register themselves as listeners of those events that they are configured to react to. An application event can be submitted by multiple modules and it can have multiple listeners.

Module and component overview

The following figure shows the nRF Desktop modules and how they relate with other components and the Application Event Manager. The figure does not present all the available modules. For example, the figure does not include the modules that are used as hotfixes or only for debug or profiling purposes.

nRF Desktop high-level design (overview)

Application high-level design overview

For more information about each of nRF Desktop modules, see the Application internal modules section.

Module event tables

The documentation page of each application module includes a table that shows the event-based communication for the module.

Source Module

Input Event

This Module

Output Event

Sink Module

The module that submits eventA.

eventA

The module described by the table.

Other module that submits eventA.

The module that submits eventB.

eventB

eventC

The module that reacts on eventC.

Each module event table contains the following columns:

Source Module

The module that submits a given application event. Some of these events can have many listeners or sources. These are listed on the Source and sink module lists page.

Input Event

An application event that is received by the module described by the table.

This Module

The module described by the table. This is the module that is the target of the Input Events and the source of Output Events directed to the Sink Modules.

Output Event

An application event that is submitted by the module described by the table.

Sink Module

The module that reacts on the application event. Some of these events can have many listeners or sources. These are listed on the Source and sink module lists page.

Note

Some application modules can have multiple implementations (for example, Motion module). In such case, the table shows the Application Event Manager events received and submitted by all implementations of a given application module.

Module usage per hardware type

Since the application architecture is uniform and the code is shared, the set of modules in use depends on the selected device role. A different set of modules is enabled when the application is working as mouse, keyboard, or dongle. In other words, not all of the Application internal modules need to be enabled for a given reference design.

Gaming mouse module set

The following figure shows the modules that are enabled when the application is working as a gaming mouse:

nRF Desktop high-level design (gaming mouse)

Application configured as a gaming mouse

Desktop mouse module set

The following figure shows the modules that are enabled when the application is working as a desktop mouse:

nRF Desktop high-level design (desktop mouse)

Application configured as a desktop mouse

Keyboard module set

The following figure shows the modules that are enabled when the application is working as a keyboard:

nRF Desktop high-level design (keyboard)

Application configured as a keyboard

Dongle module set

The following figure shows the modules that are enabled when the application is working as a dongle:

nRF Desktop high-level design (dongle)

Application configured as a dongle

Thread usage

The application limits the number of threads in use to the minimum and does not use the user-space threads.

The following threads are kept running in the application:

  • System-related threads

    • Idle thread

    • System workqueue thread

    • Logger thread (on debug build types)

    • Shell thread (on build types with shell enabled)

    • Threads related to Bluetooth® LE (the exact number depends on the selected Link Layer)

  • Application-related threads

    • Motion sensor thread (running only on mouse)

    • Settings loading thread (enabled by default only on keyboard)

    • QoS data sampling thread (running only if Bluetooth® LE QoS feature is enabled)

Most of the application activity takes place in the context of the system work queue thread, either through scheduled work objects or through the Application Event Manager callbacks (executed from the system workqueue thread). Because of this, the application does not need to handle resource protection. The only exception are places where the interaction with interrupts or multiple threads cannot be avoided.

Memory allocation

Most of memory resources that are used by the application are allocated statically.

The application uses dynamic allocation to:

When configuring HEAP, make sure that the values for the following options match the typical event size and the system needs:

Important

The nRF Desktop uses k_heap as the backend for dynamic allocation. This backend is used by default in Zephyr. For more information, refer to Zephyr’s documentation about Memory Heaps.

HID data handling

The nRF Desktop device and the host can exchange HID data using one of the following HID report types:

  • HID input report

  • HID output report

  • HID feature report

The nRF Desktop application uses all of these report types. See sections below for details about handling given HID report type.

HID input reports

The nRF Desktop application uses HID input reports to transmit information about user input from the nRF Desktop device to a host. The user input can be, for example, button press or mouse motion.

The nRF Desktop supports the following HID input reports:

  • HID mouse report

  • HID keyboard report

  • HID consumer control report

  • HID system control report

Every of these reports uses predefined report format and provides the given information. For example, the mouse motion is forwarded as HID mouse report.

An nRF Desktop device supports the selected subset of the HID input reports. For example, the nRF Desktop keyboard reference design (nrf52kbd_nrf52832) supports HID keyboard report, HID consumer control report and HID system control report.

As an example, the following section describes handling HID mouse report data.

HID mouse report handling

The nRF Desktop mouse sends HID input reports to the host after the host connects and subscribes for the HID reports.

The Motion module sensor sampling is synchronized with sending the HID mouse input reports to the host.

The Wheel module and CAF: Buttons module provide data to the HID state module when the mouse wheel is used or a button is pressed, respectively. These inputs are not synchronized with the HID report transmission to the host.

When the mouse is constantly in use, the motion module is kept in the fetching state. In this state, the nRF Desktop mouse forwards the data from the motion sensor to the host in the following way:

  1. USB state (or Bluetooth HIDS) sends a HID mouse report to the host and submits hid_report_sent_event.

  2. The event triggers sampling of the motion sensor.

  3. A dedicated thread is used to fetch the sample from the sensor.

  4. After the sample is fetched, the thread forwards it to the HID state module as motion_event.

  5. The HID state module updates the HID report data, generates new HID input report, and submits it as hid_report_event.

  6. The HID report data is forwarded to the host either by the USB state module or by the HID Service module. The USB state has precedence if the USB is connected.

  7. When the HID input report is sent to the host, hid_report_sent_event is submitted. The motion sensor sample is triggered and the sequence repeats.

If the device is connected through Bluetooth, the HID state module uses a pipeline that consists of two HID reports, which it creates upon receiving the first motion_event. The HID state module submits two hid_report_event events. Sending the first event to the host triggers the motion sensor sample.

For the Bluetooth connections, submitting hid_report_sent_event is delayed by one Bluetooth connection interval. Because of this delay, the HID Service module requires pipeline of two HID reports to make sure that data is sent on every connection event. Such solution is necessary to achieve high report rate.

If there is no motion data for the predefined number of samples, the Motion module goes to the idle state. This is done to reduce the power consumption. When a motion is detected, the module switches back to the fetching state.

The following diagram shows the data exchange between the application modules. To keep it simple, the diagram only shows data related to HID input reports that are sent after the host is connected and the HID subscriptions are enabled.

nRF Desktop mouse HID data sensing and transmission

nRF Desktop mouse HID data sensing and transmission

HID output reports

HID output reports are used to transmit data from host to an nRF Desktop device. The nRF Desktop supports the HID keyboard LED report. The report is used by the host to update the state of the keyboard LEDs, for example to indicate that the Caps Lock key is active.

Note

Only the nrf52840dk_nrf52840 in keyboard configuration has hardware LEDs that can be used to display the Caps Lock and Num Lock state.

The following diagrams show the HID output report data exchange between the application modules.

  • Scenario 1: Peripheral connected directly to the host

    HID output report: Data handling and transmission between host and peripheral

    HID output report: Data handling and transmission between host and peripheral

    In this scenario, the HID output report is sent from the host to the peripheral either through Bluetooth or the USB connection. Depending on the connection, the HID report is received by the HID Service module or USB state module, respectively. The module then sends the HID output report as hid_report_event to the HID state module, which keeps track of the HID output report states and updates state of the hardware LEDs by sending led_event to LEDs module.

  • Scenario 2: Dongle intermediates between the host and the peripheral

    HID output report: Data handling and transmission between host and peripheral through dongle

    HID output report: Data handling and transmission between host and peripheral through dongle

    In this scenario, the HID output report is sent from the host to the dongle using the USB connection and is received by the USB state module. The destination module then sends the HID output report as hid_report_event to the HID forward module, which sends it to the peripheral using Bluetooth.

HID feature reports

HID feature reports are used to transmit data between the host and an nRF Desktop device (in both directions). The nRF Desktop uses only one HID feature report: the user config report. The report is used by the Configuration channel.

Note

The nRF Desktop also uses a dedicated HID output report to forward the Configuration channel data through the nRF Desktop dongle. This report is handled using the configuration channel’s infrastructure and it can be enabled using CONFIG_DESKTOP_CONFIG_CHANNEL_OUT_REPORT. See the Kconfig option’s help for details about the report.

HID protocols

The following HID protocols are supported by nRF Desktop for HID input reports and HID output reports:

  • Report protocol - Most widely used in HID devices. When establishing connection, host reads a HID descriptor from the HID device. HID descriptor describes format of HID reports and is used by the host to interpret data exchanged between HID device and host.

  • Boot protocol - Only available for mice and keyboards data. No HID descriptor is used for this HID protocol. Instead, fixed data packet formats must be used to send data between the HID device and the host.

Requirements

The nRF Desktop application supports several development kits related to the following hardware reference designs. Depending on what development kit you use, you need to select the respective configuration file and build type.

nRF Desktop gaming mouse (top view)

Hardware platforms

PCA

Board name

Build target

nRF52840 Gaming Mouse

PCA20041

nrf52840gmouse_nrf52840

nrf52840gmouse_nrf52840

The application is designed to allow easy porting to new hardware. Check Integrating your own hardware for details.

nRF Desktop build types

The nRF Desktop does not use a single prj.conf file. Configuration files are provided for different build types for each supported board.

Each board has its own prj.conf file, which represents a debug build type. Other build types are covered by dedicated files with the build type added as a suffix to the prj part, as per the following list. For example, the release build type file name is prj_release.conf. If a board has other configuration files, for example associated with partition layout or child image configuration, these follow the same pattern.

When the CONF_FILE variable contains a single file and this file follows the naming pattern prj_<buildtype>.conf, then the build type will be inferred to be <buildtype>. The build type cannot be set explicitly. The <buildtype> can be any string, but it is common to use release and debug.

For information about how to set variables, see Important Build System Variables in the Zephyr documentation.

The Partition Manager’s static configuration can also be made dependent on the build type. When the build type has been inferred, the file pm_static_<buildtype>.yml will have precedence over pm_static.yml.

The child image Kconfig configuration can also be made dependent on the build type. The child image Kconfig file is named <child_image>.conf instead of prj.conf, but otherwise follows the same pattern as the parent Kconfig.

Note

Selecting a build type is optional. The debug build type is used by default in nRF Desktop if no build type is explicitly selected.

The following build types are available for various boards in the nRF Desktop:

  • Bootloader-enabled configurations with support for serial recovery DFU or background DFU are set as default if they fit in flash memory. See nRF Desktop board configuration files for details about which boards have bootloader included in their default configuration.

  • release - Release version of the application with no debugging features.

  • debug - Debug version of the application; the same as the release build type, but with debug options enabled.

  • shell - debug build type with the shell enabled.

  • wwcb - debug build type with the support for the B0 bootloader enabled for Works With ChromeBook (WWCB).

In nRF Desktop, not every development kit can support every build type mentioned above. If the given build type is not supported on the selected DK, an error message will appear when Building and running. For example, if the shell build type is not supported on the selected DK, the following notification appears:

File not found: ./ncs/nrf/applications/nrf_desktop/configuration/nrf52dmouse_nrf52832/prj_shell.conf

In addition to these build types, some boards can have additional build type configurations that you can use to generate an application in a specific variant. Such board-specific configurations use dedicated app_*build_type*.conf files, where the name of the configuration replaces the *build_type* part in the file name. Given the potential number of such configurations, they are not listed above and you can read the description of each of them in the respective configuration file. For example, the nRF52840 Development Kit supports the keyboard configuration, which is defined in the prj_keyboard.conf file in the configuration/nrf52840dk_nrf52840 directory. This configuration lets you generate the application with the keyboard role.

See Integrating your own hardware for detailed information about the application configuration and how to create build type files for your hardware.

User interface

The nRF Desktop configuration files have a set of preprogrammed options bound to different parts of the hardware. These options are related to the functionalities discussed in this section.

Turning devices on and off

The nRF Desktop hardware reference designs are equipped with hardware switches to turn the device on and off. See the following figures for the exact location of these switches:

nRF Desktop gaming mouse (bottom view)

The switch is located at the bottom of the gaming mouse, close to the optical sensor. The mouse uses this switch also for changing dongle and Bluetooth LE peers, as described in the Bluetooth LE peer control section.

Connectability

The nRF Desktop devices provide user input to the host in the same way as other mice and keyboards, using connection through USB or Bluetooth LE.

The nRF Desktop devices support additional operations, like firmware upgrade or configuration change. The support is implemented through the Configuration channel. The host can use dedicated Python scripts to exchange the data with an nRF Desktop peripheral. For detailed information, see HID configurator for nRF Desktop.

To save power, the behavior of a device can change in time. For more information, see the Power management section.

Connection through USB

The nRF Desktop devices use the USB HID class. No additional software or drivers are required.

nRF Desktop gaming mouse (top view)

The gaming mouse has the USB connector slot located below the scroll wheel. The connector should slide in the socket along the cut in the mouse base.

Gaming mouse, dongle, and DK support the HID data transmission through USB.

Gaming mouse USB

The gaming mouse can send HID data when connected through USB. When the device is connected both wirelessly and through USB at the same time, it provides input only through the USB connection. If the device is disconnected from USB, it automatically switches to sending the data wirelessly using Bluetooth LE.

The gaming mouse is a battery-powered device. When it is connected through USB, charging of the rechargeable batteries starts.

Dongle USB

The nRF Desktop dongle works as a bridge between the devices connected through standard Bluetooth® Low Energy or Low Latency Packet Mode and the host connected through USB. It receives data wirelessly from the connected peripherals and forwards the data to the host.

The nRF Desktop dongle is powered directly through USB.

DK USB

The DK functionality depends on the application configuration. Depending on the selected configuration options, it can work as a mouse, keyboard, or a dongle.

Connection through Bluetooth LE

When turned on, the nRF Desktop peripherals are advertising until they go to the suspended state or connect through Bluetooth. The peripheral supports one wireless connection at a time, but it can be bonded with multiple peers.

Note

To simplify pairing the nRF Desktop peripherals with Windows 10 hosts, the peripherals include Swift Pair payload in the Bluetooth LE advertising data.

The nRF Desktop Bluetooth Central device scans for all bonded peripherals that are not connected. The scanning is interrupted when any device connected to the dongle through Bluetooth comes in use. Continuing the scanning in such scenario would cause report rate drop.

The scanning starts automatically when one of the bonded peers disconnects. It also takes place periodically when a known peer is not connected.

The peripheral connection can be based on standard Bluetooth LE connection parameters or on Bluetooth LE with Low Latency Packet Mode (LLPM).

LLPM is a proprietary Bluetooth extension from Nordic Semiconductor. It can be used only if it is supported by both connected devices (desktop mice do not support it). LLPM enables sending data with high report rate (up to 1000 reports per second), which is not supported by the standard Bluetooth LE.

Bluetooth LE peer control

A connected Bluetooth LE peer device can be controlled using predefined buttons or button combinations. There are several peer operations available.

The application distinguishes between the following button press types:

  • Short - Button pressed for less than 0.5 seconds.

  • Standard - Button pressed for more than 0.5 seconds, but less than 5 seconds.

  • Long - Button pressed for more than 5 seconds.

  • Double - Button pressed twice in quick succession.

The peer operation states provide visual feedback through LEDs (if the device has LEDs). Each of the states is represented by separate LED color and effect. The LED colors and effects are described in the led_state_def.h file located in the board-specific directory in the application configuration directory.

The assignments of hardware interface elements depend on the device type.

The following predefined hardware interface elements are assigned to peer control operations for the gaming mouse:

Hardware switch

  • The switch is located next to the optical sensor.

nRF Desktop gaming mouse - bottom view

nRF Desktop gaming mouse - bottom view

  • You can set the switch in the following positions:

    • Top position: Select the dongle peer.

    • Middle position: Select the Bluetooth LE peers.

    • Bottom position: Mouse turned off.

When the dongle peer is selected, the peer control is disabled until the switch is set to another position.

Peer control button

  • The button is located on the left side of the mouse, in the thumb area.

nRF Desktop gaming mouse - side view

nRF Desktop gaming mouse - side view

  • Short-press to initialize the peer selection. (The LED1 changes color and starts blinking.) During the peer selection:

    1. Short-press to toggle between available peers. The LED1 changes color for each peer and keeps blinking.

    2. Double-press to confirm the peer selection. The peer is changed after the confirmation. LED1 stops blinking.

      Note

      A breathing LED indicates that the device has entered the advertising mode. This happens when the device is looking for a peer to connect to.

  • Long-press to initialize the peer erase. When LED1 starts blinking rapidly, double-press to confirm the operation. After the confirmation, Bluetooth advertising using a new local identity is started. When a new Bluetooth Central device successfully connects and bonds, the old bond is removed and the new bond is used instead. If the new peer does not connect in the predefined period of time, the advertising ends and the application switches back to the old peer.

  • You can cancel the ongoing peer operation with a standard button press.

System state indication

When available, one of the LEDs is used to indicate the state of the device. This system state LED is kept on when the device is active.

nRF Desktop gaming mouse (top view)

The system state LED of the gaming mouse is located under the transparent section of the cover. The color of the LED changes when the device’s battery is being charged.

In case of a system error, the system state LED will start to blink rapidly for some time before the device is reset.

Debugging

Each of the nRF Desktop hardware reference designs has a slot for the dedicated debug board. See the following figures for the exact location of these slots.

nRF Desktop gaming mouse (top view)

The debug slot is located at the end of the gaming mouse, below the cover.

The boards that you can plug into these slots are shown below. The debug board can be used for programming the device (and powering it). The bypass boards are needed to make the device work when the debug board is not used. Their purpose is to close the circuits, which allows the device to be powered, for example during Testing.

nRF Desktop debug board

The device can be programmed using the J-Link. The J-Link connector slot is located on the top of the debug board.

Power management

Reducing power consumption is important for every battery-powered device.

The nRF Desktop peripherals are either suspended or powered off when they are not in use for a defined amount of time:

  • In the suspended state, the device maintains the active connection.

  • In the powered off state, the CPU is switched to the off mode.

In both cases, most of the functionalities are disabled. For example, LEDs are turned off and advertising is stopped.

Moving the mouse or pressing any button wakes up the device and turns on the disabled functionalities.

You can define the amount of time after which the peripherals are suspended or powered off in CONFIG_CAF_POWER_MANAGER_TIMEOUT. By default, this period is set to 120 seconds.

Important

When the gaming mouse is powered from USB, the power down timeout functionality is disabled.

If a nRF Desktop device supports remote wakeup, the USB connected device goes to suspended state when USB is suspended. The device can then trigger remote wakeup of the connected host on user input.

Configuration

See Configuring your application for information about how to permanently or temporarily change the configuration.

Adding nRF21540 EK shield support

The nRF Desktop application can be used with the nRF21540 EK shield, an RF front-end module (FEM) for the 2.4 GHz range extension. The shield can be used with any nRF Desktop HID application configured for a development kit that is fitted with Arduino-compatible connector (see the DK tab in Requirements). This means that the shield support is not available for nRF Desktop’s dedicated boards, such as nrf52840gmouse_nrf52840, nrf52kbd_nrf52832, or nrf52840dongle_nrf52840. To build the application with the shield support, pass the SHIELD parameter to the build command.

For detailed information about building the nRF Desktop application for the nRF21540 EK, see the Programming section on the nRF21540 EK documentation page.

Note

For the multi-core build, use the hci_rpmsg_ as the childImageName parameter, because in the nRF Desktop application, network core runs using hci_rpmsg_. The command would look as follows:

west build -b nrf5340dk_nrf5340_cpuapp -- -DSHIELD=nrf21540_ek -Dhci_rpmsg_SHIELD=nrf21540_ek

Building and running

The nRF Desktop application is built the same way to any other nRF Connect SDK application or sample.

This sample can be found under applications/nrf_desktop in the nRF Connect SDK folder structure.

To build the sample with Visual Studio Code, follow the steps listed on the Building nRF Connect SDK application quick guide page in the nRF Connect for VS Code extension documentation. See Building and programming an application for other building and programming scenarios and Testing and debugging an application for general information about testing and debugging in the nRF Connect SDK.

Note

Information about the known issues in nRF Desktop can be found in nRF Connect SDK’s Release notes and on the Known issues page.

Selecting a build type

Before you start testing the application, you can select one of the nRF Desktop build types, depending on your development kit and building method.

Selecting a build type in Visual Studio Code

To select the build type in the nRF Connect for VS Code extension:

  1. When Building an application as described in the nRF Connect for VS Code extension documentation, follow the steps for setting up the build configuration.

  2. In the Add Build Configuration screen, select the desired .conf file from the Configuration drop-down menu.

  3. Fill in other configuration options, if applicable, and click Build Configuration.

Selecting a build type from command line

To select the build type when building the application from command line, specify the build type by adding the following parameter to the west build command:

-- -DCONF_FILE=prj_selected_build_type.conf

For example, you can replace the selected_build_type variable to build the release firmware for nrf52840dk_nrf52840 by running the following command in the project directory:

west build -b nrf52840dk_nrf52840 -d build_nrf52840dk_nrf52840 -- -DCONF_FILE=prj_release.conf

The build_nrf52840dk_nrf52840 parameter specifies the output directory for the build files.

Testing

The application can be built and tested in various configurations. The following procedure refers to the scenario where the gaming mouse (nRF52840 Gaming Mouse) and the keyboard (nRF52832 Desktop Keyboard) are connected simultaneously to the dongle (nRF52840 USB Dongle).

After building the application with or without specifying the build type, test the nRF Desktop application by performing the following steps:

  1. Program the required firmware to each device.

  2. Insert the debug board or bypass board into the mouse to make sure it is powered.

  3. Turn on both mouse and keyboard. LED1 on the keyboard and LED1 on the mouse start breathing.

  4. Plug the dongle to the USB port. The blue LED2 on the dongle starts breathing. This indicates that the dongle is scanning for peripherals.

  5. Wait for the establishment of the Bluetooth connection, which happens automatically. After the Bluetooth connection is established, the LEDs stop breathing and remain turned on. The devices can then be used simultaneously.

    Note

    You can manually start the scanning for new peripheral devices by pressing the SW1 button on the dongle for a short time. This might be needed if the dongle does not connect with all the peripherals before timeout. The scanning is interrupted after the amount of time predefined in CONFIG_DESKTOP_BLE_SCAN_DURATION_S, because it negatively affects the performance of already connected peripherals.

  6. Move the mouse and press any key on the keyboard. The input is reflected on the host.

    Note

    When a configuration with debug features is enabled, for example logger and assertions, the gaming mouse report rate can be significantly lower.

    Make sure that you use the release configurations before testing the mouse report rate. For the release configurations, you should observe a 500-Hz report rate when both the mouse and the keyboard are connected and a 1000-Hz rate when only the mouse is connected.

  7. Switch the Bluetooth peer on the gaming mouse by pressing the Precise Aim button (see User interface). The color of LED1 changes from red to green and the LED starts blinking rapidly.

  8. Press the Precise Aim button twice quickly to confirm the selection. After the confirmation, LED1 starts breathing and the mouse starts the Bluetooth advertising.

  9. Connect to the mouse with an Android phone, a laptop, or any other Bluetooth Central.

After the connection is established and the device is bonded, you can use the mouse with the connected device.

Windows Hardware Lab Kit tests

The nRF Desktop devices have passed the tests from official playlist required for compatibility with Windows 10 by Windows Hardware Compatibility Program (HLK Version 1903 CompatPlaylist x86 x64 ARM64.xml). The tests were conducted using Windows Hardware Lab Kit.

Integrating your own hardware

This section describes how to adapt the nRF Desktop application to different hardware. It describes the configuration sources that are used for the default configuration, and lists steps required for adding a new board.

Configuration sources

The nRF Desktop application uses the following files as configuration sources:

  • Devicetree Specification (DTS) files - These reflect the hardware configuration. See Devicetree for more information about the DTS data structure.

  • _def files - These contain configuration arrays for the application modules and are specific to the nRF Desktop application.

  • Kconfig files - These reflect the software configuration. See Kconfig - Tips and Best Practices for information about how to configure them.

You must modify these configuration sources when Adding a new board, as described below.

For information about differences between DTS and Kconfig, see Devicetree versus Kconfig. For detailed instructions for adding Zephyr support to a custom board, see Zephyr’s Board Porting Guide.

Board configuration

The nRF Desktop application is modular. Depending on requested functions, it can provide mouse, keyboard, or dongle functionality. The selection of modules depends on the chosen role and also on the selected reference design. For more information about modules available for each configuration, see Overview: Firmware architecture.

For a board to be supported by the application, you must provide a set of configuration files at applications/nrf_desktop/configuration/your_board_name. The application configuration files define both a set of options with which the nRF Desktop application will be created for your board and the selected nRF Desktop build types. Include the following files in this directory:

Mandatory configuration files

  • Application configuration file for the debug (prj.conf) build type.

  • Configuration files for the selected modules.

Optional configuration files

  • Application configuration files for other build types.

  • Configuration file for the bootloader.

  • Memory layout configuration.

  • DTS overlay file.

See Adding a new board for information about how to add these files.

nRF Desktop board configuration files

The nRF Desktop application comes with configuration files for the following reference designs:

nRF52840 Gaming Mouse (nrf52840gmouse_nrf52840)

  • The reference design is defined in nrf/boards/arm/nrf52840gmouse_nrf52840 for the project-specific hardware.

  • To achieve gaming-grade performance:

    • The application is configured to act as a gaming mouse, with both Bluetooth LE and USB transports enabled.

    • Bluetooth is configured to use Nordic’s SoftDevice link layer.

  • The configuration with the B0 bootloader is set as default.

nRF52832 Desktop Mouse (nrf52dmouse_nrf52832) and nRF52810 Desktop Mouse (nrf52810dmouse_nrf52810)

  • Both reference designs are meant for the project-specific hardware and are defined in nrf/boards/arm/nrf52dmouse_nrf52832 and nrf/boards/arm/nrf52810dmouse_nrf52810, respectively.

  • The application is configured to act as a mouse.

  • Only the Bluetooth LE transport is enabled. Bluetooth uses Zephyr’s software link layer.

  • The preconfigured build types for both nrf52dmouse_nrf52832 and nrf52810dmouse_nrf52810 boards are without the bootloader due to memory size limits on nrf52810dmouse_nrf52810 board.

Sample mouse, keyboard or dongle (nrf52840dk_nrf52840)

  • The configuration uses the nRF52840 Development Kit.

  • 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.

Sample dongle (nrf52833dk_nrf52833)

  • The configuration uses the nRF52833 Development Kit.

  • The application is configured to act as a dongle that forwards data from both mouse and keyboard.

  • Bluetooth uses Nordic’s SoftDevice link layer and is configured to act as a central. Input data comes from Bluetooth and is retransmitted to USB.

  • The configuration with the MCUboot bootloader is set as default.

Sample dongle (nrf52833dk_nrf52820)

  • The configuration uses the nRF52820 emulation on the nRF52833 Development Kit.

  • The application is configured to act as a dongle that forwards data from both mouse and keyboard.

  • Bluetooth uses Zephyr’s software link layer and is configured to act as a central. Input data comes from Bluetooth and is retransmitted to USB.

  • The preconfigured build types configure the device without the bootloader in debug mode and with MCUboot bootloader in release mode due to memory size limits.

nRF52832 Desktop Keyboard (nrf52kbd_nrf52832)

  • The reference design used is defined in nrf/boards/arm/nrf52kbd_nrf52832 for the project-specific hardware.

  • The application is configured to act as a keyboard, with the Bluetooth LE transport enabled.

  • Bluetooth is configured to use Nordic’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.

  • Use configuration prj_shell.conf to add shell build type. This configuration do not have bootloader due to memory size limits.

nRF52840 USB Dongle (nrf52840dongle_nrf52840) and nRF52833 USB Dongle (nrf52833dongle_nrf52833)

  • Since the nRF52840 Dongle is generic and defined in Zephyr, project-specific changes are applied in the DTS overlay file.

  • The application is configured to act as a dongle that forwards data from both mouse and keyboard.

  • Bluetooth uses Nordic’s SoftDevice link layer and is configured to act as a central. Input data comes from Bluetooth and is retransmitted to USB.

  • The configuration with the B0 bootloader is set as default for nrf52840dongle_nrf52840 board and with the MCUboot bootloader is set as default for nrf52833dongle_nrf52833 board.

nRF52820 USB Dongle (nrf52820dongle_nrf52820)

  • The application is configured to act as a dongle that forwards data from both mouse and keyboard.

  • Bluetooth uses Zephyr’s software link layer and is configured to act as a central. Input data comes from Bluetooth and is retransmitted to USB.

  • The preconfigured build types configure the device without the bootloader in debug mode and with MCUboot bootloader in release mode due to memory size limits.

Sample dongle (nrf5340dk_nrf5340)

  • The application is configured to act as a dongle that forwards data from both mouse and keyboard.

  • Bluetooth uses Nordic’s SoftDevice link layer without LLPM and is configured to act as a central. Input data comes from Bluetooth and is retransmitted to USB.

  • The configuration with the B0 bootloader is set as default.

Adding a new board

When adding a new board for the first time, focus on a single configuration. Moreover, keep the default debug build type that the application is built with, and do not add any additional build type parameters.

Note

  • The following procedure uses the gaming mouse configuration as an example.

  • The first three steps of the configuration procedure are identical to the steps described in Zephyr’s Board Porting Guide.

To use the nRF Desktop application with your custom board:

  1. Define the reference design by copying the nRF Desktop reference design files that are the closest match for your hardware. For example, for gaming mouse use nrf/boards/arm/nrf52840gmouse_nrf52840.

  2. Edit the DTS files to make sure they match the hardware configuration. Pay attention to the following elements:

  3. Edit the reference design’s Kconfig files to make sure they match the required system configuration. For example, disable the drivers that will not be used by your device.

  4. Copy the project files for the device that is the closest match for your hardware. For example, for gaming mouse these are located at applications/nrf_desktop/configure/nrf52840gmouse_nrf52840.

  5. Optionally, depending on the reference design, edit the DTS overlay file. This step is not required if you have created a new reference design and its DTS files fully describe your hardware. In such case, the overlay file can be left empty.

  6. In Kconfig, ensure that the following modules that are specific for gaming mouse are enabled:

  7. For each module enabled, change its _def file to match your hardware. Apply the following changes, depending on the module:

    Motion module

    • The nrf52840gmouse_nrf52840 uses the PMW3360 optical motion sensor. The sensor is configured in DTS, and the sensor type is selected in the application configuration. To add a new sensor, expand the application configuration.

    Wheel module

    • The wheel is based on the QDEC peripheral of the nRF52840 device and the hardware-related part is configured in DTS.

    Buttons module

    • To simplify the configuration of arrays, the nRF Desktop application uses _def files.

    • The _def file of the buttons module contains pins assigned to rows and columns.

    Battery measurement module

    • The _def file of the battery measurement module contains the mapping needed to match the voltage that is read from ADC to the battery level.

    LEDs module

    • The application uses two logical LEDs - one for the peers state, and one for the system state indication.

    • Each of the logical LEDs can have either one (monochromatic) or three color channels (RGB). Such color channel is a physical LED.

    • The project uses Pulse-Width Modulation (PWM) channels to control the brightness of each physical LED. Configure the PWM peripheral in DTS files, and configure the _def file of the LEDs module to indicate which PWM channel is assigned to each LED color. Ensure that PWM channels are correctly configured in DTS and PWM driver is enabled in the Kconfig file.

  8. Review Bluetooth options in Kconfig:

    1. Ensure that the Bluetooth role is properly configured. For mouse, it should be configured as peripheral.

    2. Update the configuration related to peer control. You can also disable the peer control using the CONFIG_DESKTOP_BLE_PEER_CONTROL option. Peer control details are described in the Bluetooth LE bond module documentation.

    Refer to the Bluetooth in nRF Desktop section and Zephyr’s Bluetooth page for more detailed information about the Bluetooth configuration.

  9. Edit Kconfig to disable options that you do not use. Some options have dependencies that might not be needed when these options are disabled. For example, when the LEDs module is disabled, the PWM driver is not needed.

Adding a new motion sensor

This procedure describes how to add a new motion sensor into the project. You can use it as a reference for adding other hardware components.

The nRF Desktop application comes with a Motion module that is able to read data from a motion sensor. While nRF Connect SDK provides support for two motion sensor drivers (PMW3360 and PAW3212), you can add support for a different sensor, based on your development needs.

Complete the steps described in the following sections to add a new motion sensor.

Add a new sensor driver

First, create a new motion sensor driver that will provide code for communication with the sensor. Use the two existing nRF Connect SDK sensor drivers as an example.

The communication between the application and the sensor is done through a sensor driver API (see Sensors). For the motion module to work correctly, the driver must support a trigger (see sensor_trigger_set) on a new data (see SENSOR_TRIG_DATA_READY trigger type).

When the motion data is ready, the driver calls a registered callback. The application starts a process of retrieving a motion data sample. The motion module calls sensor_sample_fetch and then sensor_channel_get on two sensor channels, SENSOR_CHAN_POS_DX and SENSOR_CHAN_POS_DY. The driver must support these two channels.

Create a DTS binding

Zephyr recommends to use DTS for hardware configuration (see Devicetree versus Kconfig). For the new motion sensor configuration to be recognized by DTS, define a dedicated DTS binding. See Devicetree bindings for more information, and refer to dts/bindings/sensor for binding examples.

Configure sensor through DTS

Once binding is defined, it is possible to set the sensor configuration. This is done by editing the DTS file that describes the board. For more information, see Introduction to devicetree.

As an example, take a look at the PMW3360 sensor that already exists in nRF Connect SDK. The following code excerpt is taken from boards/arm/nrf52840gmouse_nrf52840/nrf52840gmouse_nrf52840.dts:

&spi1 {
     compatible = "nordic,nrf-spim";
     status = "okay";
     cs-gpios = <&gpio0 13 0>;

     pinctrl-0 = <&spi1_default_alt>;
     pinctrl-1 = <&spi1_sleep_alt>;
     pinctrl-names = "default", "sleep";
     pmw3360@0 {
             compatible = "pixart,pmw3360";
             reg = <0>;
             irq-gpios = <&gpio0 21 0>;
             spi-max-frequency = <2000000>;
             label = "PMW3360";
     };
};

The communication with PMW3360 is done through the SPI, which makes the sensor a subnode of the SPI bus node. SPI pins are defined as part of the bus configuration, as these are common among all devices connected to this bus. In this case, the PMW3360 sensor is the only device on this bus and so there is only one pin specified for selecting chip.

When the sensor’s node is mentioned, you can read @0 in pmw3360@0. For SPI devices, @0 refers to the position of the chip select pin in the cs-gpios array for a corresponding device.

Note the string compatible = "pixart,pmw3360" in the subnode configuration. This string indicates which DTS binding the node will use. The binding should match with the DTS binding created earlier for the sensor.

The following options are inherited from the spi-device binding and are common to all SPI devices:

  • reg - The slave ID number the device has on a bus.

  • label - Used to generate a name of the device (for example, it will be added to generated macros).

  • spi-max-frequency - Used for setting the bus clock frequency.

    Note

    To achieve the full speed, data must be propagated through the application and reach Bluetooth LE a few hundred microseconds before the subsequent connection event. If you aim for the lowest latency through the LLPM (an interval of 1 ms), the sensor data readout should take no more than 250 us. The bus and the sensor configuration must ensure that communication speed is fast enough.

The remaining option irq-gpios is specific to pixart,pmw3360 binding. It refers to the PIN to which the motion sensor IRQ line is connected.

If a different kind of bus is used for the new sensor, the DTS layout will be different.

Include sensor in the application

Once the new sensor is supported by nRF Connect SDK and board configuration is updated, you can include it in the nRF Desktop application.

The nRF Desktop application selects a sensor using the configuration options defined in src/hw_interface/Kconfig.motion. Add the new sensor as a new choice option.

The Motion module of the nRF Desktop application has access to several sensor attributes. These attributes are used to modify the sensor behavior in runtime. Since the names of the attributes differ for each sensor, the Motion module uses a generic abstraction of them. You can translate the new sensor-specific attributes to a generic abstraction by modifying configuration/common/motion_sensor.h .

Tip

If an attribute is not supported by the sensor, it does not have to be defined. In such case, set the attribute to -ENOTSUP.

Select the new sensor

The application can now use the new sensor. Edit the application configuration files for your board to enable it. See Board configuration for details.

To start using the new sensor, complete the following steps:

  1. Enable all dependencies required by the driver (for example, bus driver).

  2. Enable the new sensor driver.

  3. Select the new sensor driver in the application configuration options.

Changing interrupt priority

You can edit the DTS files to change the priority of the peripheral’s interrupt. This can be useful when adding a new custom board or whenever you need to change the interrupt priority.

The interrupts property is an array, where the meaning of each element is defined by the specification of the interrupt controller. These specification files are located at zephyr/dts/bindings/interrupt-controller/ DTS binding file directory.

For example, for nRF52840 the file is arm,v7m-nvic.yaml. This file defines interrupts property in the interrupt-cells list. For nRF52840, it contains two elements: irq and priority. The default values for these elements for the given peripheral can be found in the dtsi file specific for the device. In the case of nRF52840, this is zephyr/dts/arm/nordic/nrf52840.dtsi, which has the following interrupts:

spi1: spi@40004000 {
        /*
         * This spi node can be SPI, SPIM, or SPIS,
         * for the user to pick:
         * compatible = "nordic,nrf-spi" or
         *              "nordic,nrf-spim" or
         *              "nordic,nrf-spis".
         */
        #address-cells = <1>;
        #size-cells = <0>;
        reg = <0x40004000 0x1000>;
        interrupts = <4 1>;
        status = "disabled";
        label = "SPI_1";
};

To change the priority of the peripheral’s interrupt, override the interrupts property of the peripheral node by including the following code snippet in the dts.overlay or directly in the board DTS:

&spi1 {
    interrupts = <4 2>;
};

This code snippet will change the SPI1 interrupt priority from default 1 to 2.

Flash memory layout

Depending on whether the bootloader is enabled, the partition layout on the flash memory is set by defining one of the following options:

The set of required partitions differs depending on configuration:

  • There must be at least one partition where the code is stored.

  • There must be one partition for storing Settings.

  • The bootloader, if enabled, will add additional partitions to the set.

Important

Before updating the firmware, make sure that the data stored in the settings partition is compatible with the new firmware. If it is incompatible, erase the settings area before using the new firmware.

Memory layout in DTS

When using the flash memory layout in the DTS files, define the partitions child node in the flash device node (&flash0).

Since the nRF Desktop application uses the partition manager when the bootloader is present, the partition definition from the DTS files is valid only for configurations without the bootloader.

Note

If you wish to change the default flash memory layout of the board without editing board-specific files, edit the DTS overlay file. The nRF Desktop application automatically adds the overlay file if the dts.overlay file is present in the project’s board configuration directory. See more in the Board configuration section.

Important

By default, Zephyr does not use the code partition defined in the DTS files. It is only used if CONFIG_USE_DT_CODE_PARTITION is enabled. If this option is disabled, the code is loaded at the address defined by CONFIG_FLASH_LOAD_OFFSET and can spawn for CONFIG_FLASH_LOAD_SIZE (or for the whole flash if the load size is set to zero).

Because the nRF Desktop application depends on the DTS layout only for configurations without the bootloader, only the settings partition is relevant in such cases and other partitions are ignored.

For more information about how to configure the flash memory layout in the DTS files, see Flash map.

Memory layout in partition manager

When the bootloader is enabled, the nRF Desktop application uses the partition manager for the layout configuration of the flash memory. The nRF Desktop configurations with bootloader use static configurations of partitions to ensure that the partition layout will not change between builds.

Add the pm_static_$BUILD_TYPE.yml file to the project’s board configuration directory to define the static partition manager configuration for given board and build type. For example, to define the static partition layout for the nrf52840dk_nrf52840 board and release build type, you would need to add the pm_static_release.yml file into the applicatons/nrf_desktop/configuration/nrf52840dk_nrf52840 directory.

Take into account the following points:

  • For the background firmware upgrade, you must define the secondary image partition. This is because the update image is stored on the secondary image partition while the device is running firmware from the primary partition.

  • When you use USB serial recovery, you do not need the secondary image partition. The firmware image is overwritten by the bootloader.

For more information about how to configure the flash memory layout using the partition manager, see Partition Manager.

External flash configuration

The Partition Manager supports partitions in external flash.

Enabling external flash can be useful especially for memory-limited devices. For example, the MCUboot can use it as a secondary image partition for the background firmware upgrade. The MCUboot moves the image data from the secondary image partition to the primary image partition before booting the new firmware.

For an example of the nRF Desktop application configuration that uses an external flash, see the mcuboot_qspi configuration of the nRF52840 Development Kit. This configuration uses the MX25R64 external flash that is part of the development kit.

For detailed information, see the Partition Manager documentation.

Bluetooth in nRF Desktop

The nRF Desktop devices use Zephyr’s Bluetooth API to handle the Bluetooth LE connections.

This API is used only by the application modules that handle such connections. The information about peer and connection state is propagated to other application modules using Application Event Manager events.

The nRF Desktop devices come in the following types:

  • Peripheral devices (mouse or keyboard)

    • Support only the Bluetooth Peripheral role (CONFIG_BT_PERIPHERAL).

    • Handle only one Bluetooth LE connection at a time.

    • Use more than one Bluetooth local identity.

  • Central devices (dongle)

    • Support only the Bluetooth Central role (CONFIG_BT_CENTRAL).

    • Handle multiple Bluetooth LE connections simultaneously.

    • Use only one Bluetooth local identity (the default one).

Both central and peripheral devices have dedicated configuration options and use dedicated modules.

Note

There is no nRF Desktop device that supports both central and peripheral roles.

Common configuration and application modules

Some Bluetooth-related configuration options (including Link Layer configuration options in a separate section) and application modules are common for every nRF Desktop device.

Configuration options

This section describes the most important Bluetooth Kconfig options common for all nRF Desktop devices. For detailed information about every option, see the Kconfig help.

  • CONFIG_BT_MAX_PAIRED

    • nRF Desktop central: The maximum number of paired devices is greater than or equal to the maximum number of simultaneously connected peers.

    • nRF Desktop peripheral: The maximum number of paired devices is equal to the number of peers plus one, where the one additional paired device slot is used for erase advertising.

  • CONFIG_BT_ID_MAX

    • nRF Desktop central: The device uses only one Bluetooth local identity, that is the default one.

    • nRF Desktop peripheral: The number of Bluetooth local identities must be equal to the number of peers plus two.

      • One additional local identity is used for erase advertising.

      • The other additional local identity is the default local identity, which is unused, because it cannot be reset after removing the bond. Without the identity reset, the previously bonded central could still try to reconnect after being removed from Bluetooth bonds on the peripheral side.

  • CONFIG_BT_MAX_CONN

    • nRF Desktop central: Set the option to the maximum number of simultaneously connected devices.

    • nRF Desktop peripheral: The default value (one) is used.

Note

After changing the number of Bluetooth peers for the nRF Desktop peripheral device, update the LED effects used to represent the Bluetooth connection state. For details, see LED state module.

Application modules

Every nRF Desktop device that enables Bluetooth must handle connections and manage bonds. These features are implemented by the following modules:

You need to enable all these modules to enable both features. For information about how to enable the modules, see their respective documentation pages.

Optionally, you can also enable the following module:

Note

The nRF Desktop devices enable CONFIG_BT_SETTINGS. When this option is enabled, the application is responsible for calling the settings_load() function - this is handled by the Settings loader module.

Bluetooth Peripheral

The nRF Desktop peripheral devices must include additional configuration options and additional application modules to comply with the HID over GATT specification.

The HID over GATT profile specification requires Bluetooth Peripherals to define the following GATT Services:

The nRF Desktop peripherals must also define a dedicated GATT Service, which is used to provide the following information:

  • Information whether the device can use the LLPM Bluetooth connection parameters.

  • Hardware ID of the peripheral.

The GATT Service is implemented by the Device description module.

Apart from the GATT Services, an nRF Desktop peripheral device must enable and configure the following application modules:

Optionally, you can also enable the following module:

  • Quality of Service module - Forwards the Bluetooth LE channel map generated by Bluetooth LE Quality of Service module. The Bluetooth LE channel map is forwarded using GATT characteristic. The Bluetooth Central can apply the channel map to avoid congested RF channels. This results in better connection quality and higher report rate.

Bluetooth Central

The nRF Desktop central must implement Bluetooth scanning and handle the GATT operations. The central must also control the Bluetooth connection parameters. These features are implemented by the following application modules:

Bootloader

The nRF Desktop application can use one of the following bootloaders:

Secure Bootloader

In this documentation, the Secure Bootloader is referred as B0. B0 is a small, simple, and secure bootloader that allows the application to boot directly from one of the application slots, thus increasing the speed of the direct firmware upgrade (DFU) process.

This bootloader can be used only for the background DFU through the Configuration channel and Device Firmware Upgrade module. More information about the B0 can be found at the nRF Secure Immutable Bootloader page.

MCUboot

The MCUboot bootloader can be used in the following scenarios:

  • Background DFU. In this scenario, the MCUboot swaps the application images located on the secondary and primary slot before booting the new image. Because of this, the image is not booted directly from the secondary image slot. The swap operation takes additional time, but an external FLASH can be used as the secondary image slot.

    You can use the MCUboot for the background DFU through the Configuration channel and Device Firmware Upgrade module. The MCUboot can also be used for the background DFU over Simple Management Protocol (SMP). The SMP can be used to transfer the new firmware image in the background from an Android device. In that case, the Simple Management Protocol module is used to handle the image transfer.

  • USB serial recovery. In this scenario, the MCUboot bootloader supports the USB serial recovery. The USB serial recovery can be used for memory-limited devices that support the USB connection.

For more information about the MCUboot, see the MCUboot documentation.

Note

The nRF Desktop application can use either B0 or MCUboot. The MCUboot is not used as the second stage bootloader.

Important

Make sure that you use your own private key for the release version of the devices. Do not use the debug key for production.

Configuring the B0 bootloader

To enable the B0 bootloader, select the CONFIG_SECURE_BOOT Kconfig option.

The B0 bootloader requires the following options enabled:

Configuring the MCUboot bootloader

To enable the MCUboot bootloader, select the CONFIG_BOOTLOADER_MCUBOOT Kconfig option.

Configure the MCUboot bootloader with the following options:

  • CONFIG_BOOT_SIGNATURE_KEY_FILE - This option defines the path to the private key that is used to sign the application and that is used by the bootloader to verify the application signature. The key must be defined only in the MCUboot bootloader configuration file.

  • CONFIG_IMG_MANAGER and CONFIG_MCUBOOT_IMG_MANAGER - These options allow the application to manage the DFU image. Enable both of them only for configurations that support background DFU. For these configurations, the Device Firmware Upgrade module uses the provided API to request firmware upgrade and confirm the running image.

Background Device Firmware Upgrade

The nRF Desktop application uses the Configuration channel and Device Firmware Upgrade module for the background DFU process. The firmware update process has three stages, discussed below. At the end of these three stages, the nRF Desktop application will be rebooted with the new firmware package installed.

Note

The background DFU mode requires two application slots in the flash memory. For this reason, the feature is not available for devices with smaller flash size, because the size of the flash memory required is essentially doubled. The devices with smaller flash size can use either Serial recovery DFU or MCUboot bootloader with the secondary image partition located on an external flash.

The background firmware upgrade can also be performed over the Simple Management Protocol (SMP). For more detailed information about the DFU over SMP, read the Simple Management Protocol module documentation.

Update image generation

The update image is generated in the build directory when building the firmware if the bootloader is enabled in the configuration:

  • The zephyr/dfu_application.zip file is used by both B0 and MCUboot bootloader for the background DFU through the Configuration channel and Device Firmware Upgrade module. This package contains firmware images along with additional metadata.

    Note

    By default, the build process for the B0 bootloader will construct an image for the first slot (slot 0 or S0). To ensure that application is built for both slots, select the CONFIG_BUILD_S1_VARIANT Kconfig option.

    When this option is selected, the zephyr/dfu_application.zip file contains both images. The update tool checks if the currently running image runs from either slot 0 or slot 1. It then transfers the update image that can be run from the unused slot.

  • The zephyr/app_update.bin is used for the background DFU through the Simple Management Protocol module.

Update image transfer

The update image is transmitted in the background through the Configuration channel. The configuration channel data is transmitted either through USB or over Bluetooth, using HID feature reports. This allows the device to be used normally during the whole process (that is, the device does not need to enter any special state in which it becomes non-responsive to the user).

Depending on the side on which the process is handled:

  • On the application side, the process is handled by Device Firmware Upgrade module. See the module documentation for how to enable and configure it.

  • On the host side, the process is handled by the HID configurator for nRF Desktop. See the tool documentation for more information about how to execute the background DFU process on the host.

If the MCUboot bootloader is selected, the update image can also be transferred in the background through the Simple Management Protocol module.

Update image verification and swap

Once the update image transfer is completed, the background DFU process will continue after the device reboot. If HID configurator for nRF Desktop is used, the reboot is triggered by the script right after the image transfer completes.

After the reboot, the bootloader locates the update image on the update partition of the device. The image verification process ensures the integrity of the image and checks if its signature is valid. If verification is successful, the bootloader boots the new version of the application. Otherwise, the old version is used.

Serial recovery DFU

The nRF Desktop application also supports the serial recovery DFU mode through USB. In this mode, unlike in background DFU mode, the application is overwritten and only one application slot is used. This mode can so be used on devices with a limited amount of flash memory available.

Note

The serial recovery DFU and the background DFU cannot be enabled at the same time on the same device.

The serial recovery DFU is a feature of the bootloader. For the serial recovery DFU to be performed, the bootloader must be able to access the USB subsystem. This is not possible for the B0, and you have to use MCUboot instead.

As only one application slot is available, the transfer of the new version of the application cannot be done while the application is running. To start the serial recovery DFU, the device should boot into recovery mode, in which the bootloader will be waiting for a new image upload to start. In the serial recovery DFU mode, the new image is transferred through USB. If the transfer is interrupted, the device will not be able to boot the application and automatically start in the serial recovery DFU mode.

Configuring serial recovery DFU

Configure MCUboot to enable the serial recovery DFU through USB. The MCUboot configuration for a given board and build type should be written to applications/nrf_desktop/configuration/your_board_name/mcuboot_buildtype.conf. For an example of the configuration, see the release_mcuboot build type of the nRF52820 or the nRF52833 dongle.

Not every configuration with MCUboot in the nRF Desktop supports the USB serial recovery. For example, the mcuboot_smp configuration for the nRF52840 Development Kit supports the MCUboot bootloader with background firmware upgrade.

Select the following Kconfig options to enable the serial recovery DFU:

  • CONFIG_MCUBOOT_SERIAL - This option enables the serial recovery DFU.

  • CONFIG_BOOT_SERIAL_CDC_ACM - This option enables the serial interface through USB.

    Note

    The USB subsystem must be enabled and properly configured. See USB device support for more information.

The GPIO pin used to trigger the serial recovery mode is configured using Devicetree Specification (DTS). The pin is configured with the mcuboot-button0 alias. The mcuboot-led0 alias can be used to define LED activated in the serial recovery mode. The CONFIG_MCUBOOT_INDICATION_LED Kconfig option must be selected to enable the LED.

By default, both the GPIO pin and the LED are defined in board’s DTS file. See boards/arm/nrf52833dongle_nrf52833/nrf52833dongle_nrf52833.dts for an example of configuration.

Once the device enters the serial recovery mode, you can use the mcumgr to:

  • Query information about the present image.

  • Upload the new image. The mcumgr uses the zephyr/app_update.bin update image file. It is generated by the build system when building the firmware.

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

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

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 the 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.

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 will fail. The possible values are either B0 or MCUBOOT.

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 the image file compatible with the LVFS, the CAB file needs to be prepared. The CAB package 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 the CAB archive 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 was uploaded onto the LVFS, the firmware update procedure can be tested on end machines.

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 by using the following commands:

    fwupdmgr refresh
fwupdmgr get-updates

    In this console snippet:

    • 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.

Dependencies

This application uses the following nRF Connect SDK libraries and drivers:

Application internal modules

The nRF Desktop application uses its own set of internal modules. See Module and component overview for more information. More information about each application module and its configuration details is available on the subpages.

Each module documentation page has a table that shows the relations between module events. Module event tables for some modules include extensive lists of source and sink modules. These are valid for events that have many listeners or sources, and are gathered on the Source and sink module lists subpage.

Subpages:

Application configuration options

Following are the application specific configuration options that can be configured for the nRF desktop and the internal modules:

CONFIG_DESKTOP_INIT_LOG_BATTERY_STATE_EVENT

(bool) Log battery state events

Log battery state events in nRF Desktop application.

CONFIG_DESKTOP_INIT_LOG_BATTERY_LEVEL_EVENT

(bool) Log battery level events

Log battery level events in nRF Desktop application.

CONFIG_DESKTOP_INIT_LOG_BLE_DISC_COMPLETE_EVENT

(bool) Log Bluetooth LE discovery complete events

Log Bluetooth LE discovery complete events in nRF Desktop application.

CONFIG_DESKTOP_INIT_LOG_BLE_QOS_EVENT

(bool) Log Bluetooth LE QoS events

Log Bluetooth LE QoS events in nRF Desktop application.

CONFIG_DESKTOP_INIT_LOG_CPU_LOAD_EVENT

(bool) Log CPU load events

Log CPU load events in nRF Desktop application.

CONFIG_DESKTOP_INIT_LOG_SELECTOR_EVENT

(bool) Log selector events

Log selector events in nRF Desktop application.

CONFIG_DESKTOP_INIT_LOG_PASSKEY_EVENT

(bool) Log passkey events

Log passkey events in nRF Desktop application.

CONFIG_DESKTOP_INIT_LOG_CONFIG_EVENT

(bool) Log config events

Log config events in nRF Desktop application.

CONFIG_DESKTOP_INIT_LOG_HID_SUBSCRIBER_EVENT

(bool) Log HID report subscriber events

Log HID report subscriber events in nRF Desktop application.

CONFIG_DESKTOP_INIT_LOG_HID_SUBSCRIPTION_EVENT

(bool) Log HID report subscription events

Log HID report subscription events in nRF Desktop application.

CONFIG_DESKTOP_INIT_LOG_HID_REPORT_EVENT

(bool) Log HID report events

Log HID report events in nRF Desktop application.

CONFIG_DESKTOP_INIT_LOG_HID_REPORT_SENT_EVENT

(bool) Log HID report sent events

Log HID report sent events in nRF Desktop application.

CONFIG_DESKTOP_INIT_LOG_MOTION_EVENT

(bool) Log motion events

Log motion events in nRF Desktop application.

CONFIG_DESKTOP_INIT_LOG_USB_STATE_EVENT

(bool) Log USB state events

Log USB state events in nRF Desktop application.

CONFIG_DESKTOP_INIT_LOG_USB_HID_EVENT

(bool) Log USB HID events

Log USB HID events in nRF Desktop application.

CONFIG_DESKTOP_INIT_LOG_WHEEL_EVENT

(bool) Log wheel events

Log wheel events in nRF Desktop application.

CONFIG_DESKTOP_INIT_LOG_HID_NOTIFICATION_EVENT

(bool) Log HID notification events

Log HID notification events in nRF Desktop application.

CONFIG_DESKTOP_MOTION_NONE

(bool) Disable motion

If selected, no motion source if defined for the interface.

CONFIG_DESKTOP_MOTION_SENSOR_PMW3360_ENABLE

(bool) Motion from optical sensor PMW3360

If selected, movement data it obtained from PMW3360 optical sensor.

CONFIG_DESKTOP_MOTION_SENSOR_PAW3212_ENABLE

(bool) Motion from optical sensor PAW3212

If selected, movement data it obtained from PAW3212 optical sensor.

CONFIG_DESKTOP_MOTION_BUTTONS_ENABLE

(bool) Motion from buttons

If selected, movement data it obtained from buttons.

CONFIG_DESKTOP_MOTION_SIMULATED_ENABLE

(bool) Simulated motion

If selected, movement data is simulated.

CONFIG_DESKTOP_MOTION_SENSOR_ENABLE

(bool)

None

CONFIG_DESKTOP_MOTION_SENSOR_TYPE

(string)

None

CONFIG_DESKTOP_MOTION_UP_KEY_ID

(int) Up key ID

ID of key use for generating up motion.

CONFIG_DESKTOP_MOTION_DOWN_KEY_ID

(int) Down key ID

ID of key use for generating down motion.

CONFIG_DESKTOP_MOTION_LEFT_KEY_ID

(int) Left key ID

ID of key use for generating left motion.

CONFIG_DESKTOP_MOTION_RIGHT_KEY_ID

(int) Right key ID

ID of key use for generating right motion.

CONFIG_DESKTOP_MOTION_SIMULATED_EDGE_TIME

(int) Time for transition between two points in a trajectory [ms]

The simulated movement data will be tracing predefined path, an eight-sided polygon. Must be power of two (calculations speedup).

CONFIG_DESKTOP_MOTION_SIMULATED_SCALE_FACTOR

(int) Scale factor for given shape

The simulated movement data will be tracing predefined path, an eight-sided polygon. This option defines scale factor for tracked polygon size.

CONFIG_DESKTOP_MOTION_SENSOR_THREAD_STACK_SIZE

(int) Motion module thread stack size

Stack size for motion sensor thread.

CONFIG_DESKTOP_MOTION_SENSOR_EMPTY_SAMPLES_COUNT

(int) Empty sample count before fetching is stopped

Number of sensor readouts with no movement reported after which module will switch from actively fetching samples to waiting for an interrupt from the sensor.

CONFIG_DESKTOP_MOTION_SENSOR_CPI

(int) Motion sensor default CPI

Default CPI value.

CONFIG_DESKTOP_MOTION_SENSOR_SLEEP1_TIMEOUT_MS

(int) Motion sensor default sleep 1 timeout in ms

Time in milliseconds after last motion detection in which sensor enters a low power mode 1.

CONFIG_DESKTOP_MOTION_SENSOR_SLEEP2_TIMEOUT_MS

(int) Motion sensor default sleep 2 timeout in ms

Time in milliseconds after last motion detection in which sensor enters a low power mode 2.

CONFIG_DESKTOP_MOTION_SENSOR_SLEEP3_TIMEOUT_MS

(int) Motion sensor default sleep 3 timeout in ms

Time in milliseconds after last motion detection in which sensor enters a low power mode 3.

CONFIG_DESKTOP_MOTION_SENSOR_SLEEP1_SAMPLE_TIME_DEFAULT

(int) Motion sensor default sleep1 sample time

None

CONFIG_DESKTOP_MOTION_SENSOR_SLEEP2_SAMPLE_TIME_DEFAULT

(int) Motion sensor default sleep2 sample time

None

CONFIG_DESKTOP_MOTION_SENSOR_SLEEP3_SAMPLE_TIME_DEFAULT

(int) Motion sensor default sleep3 sample time

None

CONFIG_DESKTOP_MOTION_SENSOR_SLEEP3_SAMPLE_TIME_CONNECTED

(int) Motion sensor sleep3 sample time when connected

None

CONFIG_DESKTOP_MOTION_SENSOR_SLEEP_DISABLE_ON_USB

(bool) Disable low power modes if powered from USB

Low power modes reduce device power consumption, but increase response time.

CONFIG_DESKTOP_BUTTONS_SIM_ENABLE

(bool) Enable simulated button presses generator

This option enables simulated button presses in nRF Desktop application. Could be used for debugging purposes.

CONFIG_DESKTOP_BUTTONS_SIM_INTERVAL

(int) Interval between subsequent simulated button presses [ms]

Time interval between the subsequent simulated button presses [ms].

CONFIG_DESKTOP_BUTTONS_SIM_LOOP_FOREVER

(bool) Generate buttons in infinite loop

When this option is disabled sequence of buttons is generated once. Enabling this option makes the sequence start from the beginning after it ends.

CONFIG_DESKTOP_BUTTONS_SIM_TRIGGER_KEY_ID

(hex) Button used to start/stop generating button presses

This option defines KEY ID of the button used to start/stop generation of simulated button presses in the nRF Desktop application.

CONFIG_DESKTOP_SELECTOR_HW_ENABLE

(bool) Enable HW based selector

This option enables hardware based selector for nRF Desktop application. If selector state changes, selector_event is sent.

CONFIG_DESKTOP_WHEEL_ENABLE

(bool) Enable wheel hardware interface

This option enables wheel hardware interface for nRF Desktop application. Wheel hardware interface is responsible for generating events related to rotation of the mouse wheel.

CONFIG_DESKTOP_WHEEL_SENSOR_VALUE_DIVIDER

(int) Wheel sensor value divider

A value obtained from the wheel sensor will be divided by provided argument before being processed further.

CONFIG_DESKTOP_WHEEL_SENSOR_IDLE_TIMEOUT

(int) Wheel sensor idle timeout

Time in seconds before sensor goes to idle state. If set to zero sensor is always active.

CONFIG_DESKTOP_WHEEL_INVERT_AXIS

(bool) Invert wheel axis

Switch the orientation of the wheel sensor.

CONFIG_DESKTOP_BATTERY_CHARGER_NONE

(bool) No battery charging

If selected, battery charging is disabled.

CONFIG_DESKTOP_BATTERY_CHARGER_DISCRETE

(bool) Discrete battery charger

If selected, battery charging is enabled.

CONFIG_DESKTOP_BATTERY_MEAS_NONE

(bool) No battery measurement

If selected, battery measurement is disabled.

CONFIG_DESKTOP_BATTERY_MEAS

(bool) Enable battery measurement circuit

If selected, battery measurement is enabled.

CONFIG_DESKTOP_BATTERY_MEAS_MIN_LEVEL

(int) Minimum battery voltage [mV] that corresponds to 0% level

This option specifies battery voltage [mV] that corresponds to 0% battery level.

CONFIG_DESKTOP_BATTERY_MEAS_MAX_LEVEL

(int) Maximum battery voltage [mV] that corresponds to 100% level

This option specifies battery voltage [mV] that corresponds to 100% battery level.

CONFIG_DESKTOP_BATTERY_MEAS_HAS_VOLTAGE_DIVIDER

(bool) Use voltage divider for battery measurement

Enable if voltage divider is used for battery measurement.

CONFIG_DESKTOP_BATTERY_MEAS_VOLTAGE_DIVIDER_UPPER

(int) Upper resistor in battery measurement voltage divider [kOhm]

Upper resistor value [kOhm]. Output voltage is measured on the lower resistor.

CONFIG_DESKTOP_BATTERY_MEAS_VOLTAGE_DIVIDER_LOWER

(int) Lower resistor in battery measurement voltage divider [kOhm]

Lower resistor value [kOhm]. Output voltage is measured on the lower resistor.

CONFIG_DESKTOP_VOLTAGE_TO_SOC_DELTA

(int) Difference between adjacent elements in conversion LUT [mV]

Value used to convert battery voltage [mV] to State of Charge [%].

CONFIG_DESKTOP_BATTERY_MEAS_POLL_INTERVAL_MS

(int) Time between the subsequent battery measurements [ms]

Time interval between the subsequent battery measurements [ms].

CONFIG_DESKTOP_BATTERY_MEAS_HAS_ENABLE_PIN

(bool) Use pin for enabling battery measurement

Enable if dedicated gpio0 pin is used for enabling battery measurement circuit. Pin number is configurable by CONFIG_DESKTOP_BATTERY_MEAS_ENABLE_PIN

CONFIG_DESKTOP_BATTERY_MEAS_ENABLE_PIN

(int) Battery monitoring enable pin

A pin which enables the battery measurement circuit.

CONFIG_DESKTOP_PASSKEY_NONE

(bool) Disable passkey

If selected, passkey is disabled.

CONFIG_DESKTOP_PASSKEY_BUTTONS

(bool) Passkey based on button presses

If selected, the passkey module is used to handle numeric passkey input. The input handling is based on button presses.

CONFIG_DESKTOP_PASSKEY_MAX_LEN

(int) Max number of digits in passkey

Maximum number of digits in a passkey.

CONFIG_DESKTOP_HID_REPORT_DESC

(string) HID report descriptor

This option specifies a path to the HID report descriptor file.

CONFIG_DESKTOP_HID_MOUSE

(bool) Device is a HID mouse

Enable reports needed by a mouse.

CONFIG_DESKTOP_HID_KEYBOARD

(bool) Device is a HID keyboard

Enable reports needed by a keyboard.

CONFIG_DESKTOP_HID_DONGLE

(bool) Device is a HID dongle

Enable reports needed by a dongle.

CONFIG_DESKTOP_HID_REPORT_MOUSE_SUPPORT

(bool) Mouse report support

This option controls if the device supports HID mouse report. Report is added to the report map. It does not need to be generated by the device.

CONFIG_DESKTOP_HID_REPORT_KEYBOARD_SUPPORT

(bool) Keyboard report support

This option controls if the device supports HID keyboard reports. Report is added to the report map. It does not need to be generated by the device.

CONFIG_DESKTOP_HID_REPORT_SYSTEM_CTRL_SUPPORT

(bool) System control report support

This option controls if the device supports HID system control report. Report is added to the report map. It does not need to be generated by the device.

CONFIG_DESKTOP_HID_REPORT_CONSUMER_CTRL_SUPPORT

(bool) Consumer control report support

This option controls if the device supports HID consumer control report. Report is added to the report map. It does not need to be generated by the device.

CONFIG_DESKTOP_HID_BOOT_INTERFACE_DISABLED

(bool) Boot interface disabled

Device will not provide any boot interface.

CONFIG_DESKTOP_HID_BOOT_INTERFACE_MOUSE

(bool) Boot interface mouse

Device will use the mouse boot report.

CONFIG_DESKTOP_HID_BOOT_INTERFACE_KEYBOARD

(bool) Boot interface keyboard

Device will use the keyboard boot report.

CONFIG_DESKTOP_HID_STATE_ENABLE

(bool) Enable HID state

HID events processing module.

CONFIG_DESKTOP_HID_STATE_HID_KEYMAP_DEF_PATH

(string) File defining HID keymap

Location of configuration file that holds information about mapping between buttons and generated reports.

CONFIG_DESKTOP_HID_STATE_HID_KEYBOARD_LEDS_DEF_PATH

(string) File defining HID keyboard LEDs

Location of configuration file that holds information about LEDs associated with HID keyboard LEDs report.

CONFIG_DESKTOP_HID_STATE_PM_ENABLE

(bool) Enable HID power manager integration

This enables small module that blocks power down if HID is active.

CONFIG_DESKTOP_HID_REPORT_EXPIRATION

(int) HID report expiration [ms]

Define the time after which a HID report expires and is not sent again.

CONFIG_DESKTOP_HID_EVENT_QUEUE_SIZE

(int) HID event queue size

Size of the HID event queue.

CONFIG_DESKTOP_LED_STREAM_ENABLE

(bool) Enable LED stream

Enable RGB LED effect streaming.

CONFIG_DESKTOP_LED_STREAM_QUEUE_SIZE

(int) Stream led event queue size

Size of the LED stream event queue.

CONFIG_DESKTOP_USB_ENABLE

(bool) Enable USB module

Enables USB module.

CONFIG_DESKTOP_USB_SELECTIVE_REPORT_SUBSCRIPTION

(bool) Subscribe only for predefined subset of HID reports

By default, every USB HID instance subscribes for all the HID reports. Enable this option to specify a subset of HID reports for every USB HID instance. The subset of HID reports must be specified in usb_state_def.h file in application configuration directory for given board and configuration.

CONFIG_DESKTOP_USB_PM_ENABLE

(bool) Enable USB power manager integration

This enables small module that blocks power down if the USB is active.

CONFIG_DESKTOP_BLE_ENABLE_PASSKEY

(bool) Enable passkey based pairing

Enable passkey based pairing for increased security.

CONFIG_DESKTOP_BLE_BOND_ENABLE

(bool) Enable BLE bond module

Enable app-specific implementation of Bluetooth LE bond module. The module is used to control Bluetooth peers.

The module selects the CAF_BLE_BOND_SUPPORTED option to inform CAF that BLE bond module is supported by the application.

CONFIG_DESKTOP_BLE_USE_DEFAULT_ID

(bool) Use default Bluetooth local identity

Bluetooth default local identity is used as ID 0. This identity cannot be reset. After bond for the default identity is removed, it is no longer used.

CONFIG_DESKTOP_BLE_PEER_CONTROL

(bool) Enable interaction with peer configuration

Let user control Bluetooth peers by pressing a dedicated button.

CONFIG_DESKTOP_BLE_PEER_CONTROL_BUTTON

(hex) Key ID of button used to control peers

Button which should be used to control bonded Bluetooth peers.

CONFIG_DESKTOP_BLE_PEER_SELECT

(bool) Enable switching between peers

Short click to switch peer. Double click to accept choice.

CONFIG_DESKTOP_BLE_NEW_PEER_SCAN_REQUEST

(bool) Enable scanning on request

Short click to start new peer scanning. When enabled the device will look for non-bonded devices only when requested. When disabled the device always search for non-bonded devices while scanning. Regardless of the choice made the device scans periodically for already bonded peers.

CONFIG_DESKTOP_BLE_NEW_PEER_SCAN_ON_BOOT

(bool) Look for peers after boot

When enabled the device will look for new peers also after it was booted.

CONFIG_DESKTOP_BLE_PEER_ERASE

(bool) Enable peer erase

Long click to start erase. Double click to confirm.

CONFIG_DESKTOP_BLE_PEER_ERASE_ON_START

(bool) Enable peer erase (on system start)

Hold dedicated button during system start to start erase advertising.

CONFIG_DESKTOP_BLE_DONGLE_PEER_ENABLE

(bool) Enable dongle peer

Enable additional peer to connect with dongle.

CONFIG_DESKTOP_BLE_DONGLE_PEER_SELECTOR_ID

(int) Dongle peer selector ID

ID of the hardware selector used to select the dongle peer.

CONFIG_DESKTOP_BLE_DONGLE_PEER_SELECTOR_POS

(int) Dongle peer selector position

If the selector is set to this position, the dongle peer is selected. If the selector is set to any other position, other Bluetooth LE peers are selected.

CONFIG_DESKTOP_BLE_DONGLE_PEER_ERASE_BOND_BUTTON

(bool) Allow erasing dongle peer using button

None

CONFIG_DESKTOP_BLE_DONGLE_PEER_ERASE_BOND_CONF_CHANNEL

(bool) Allow erasing dongle peer using config channel

None

CONFIG_DESKTOP_BLE_SCANNING_ENABLE

(bool) Enable BLE scanning

Enable device to scan for peripheral devices.

CONFIG_DESKTOP_BLE_SCAN_START_TIMEOUT_S

(int) Scan start timeout [s]

After disabled, scanning is re-enabled after defined time of connected peripherals inactivity (scanning has negative impact on user experience - e.g. may cause mouse pointer lags).

CONFIG_DESKTOP_BLE_SCAN_DURATION_S

(int) Scan duration [s]

After this time scan is disabled if any peripheral is connected.

CONFIG_DESKTOP_BLE_SCAN_MOUSE_LIMIT

(int) Maximum number of bonded mice

None

CONFIG_DESKTOP_BLE_SCAN_KEYBOARD_LIMIT

(int) Maximum number of bonded keyboards

None

CONFIG_DESKTOP_BLE_SCAN_PM_EVENTS

(bool) Stop and block scanning in the power down mode

Stop and block scanning for peers if the central switched to the power down mode to reduce power consumption.

CONFIG_DESKTOP_BLE_DISCOVERY_ENABLE

(bool) Enable BLE discovery

Enable device to read device description (custom GATT Service), Device Information Service and discover HIDS.

CONFIG_DESKTOP_BLE_SECURITY_FAIL_TIMEOUT_S

(int) Security fail timeout [s]

After this time peripheral device disconnects if security is not established.

CONFIG_DESKTOP_BLE_LOW_LATENCY_LOCK

(bool) Keep the slave latency low for LLPM connections

When this option is selected, the slave latency is kept low for the LLPM connection unless device is in low power mode. This speeds up sending the first HID report after not sending a report for some connection intervals. Enabling this option increases the power consumption of the device.

CONFIG_DESKTOP_BLE_USB_MANAGED_CI

(bool) Manage connection intervals on the USB state change

Manage BLE connection intervals depending on the USB state. Allows reduced power consumption of the USB dongle device by setting a larger connection intervals while the USB enters suspended state. After the USB resumes normal operation, connection interval is set to the previous value.

CONFIG_DESKTOP_BLE_USB_MANAGED_CI_VALUE

(int) BLE connection interval when USB is suspended

Connection interval used for all connected peers while the USB is in suspended state.

CONFIG_DESKTOP_BLE_QOS_ENABLE

(bool) Enable BLE channel map management

Enable device to avoid congested RF channels.

CONFIG_DESKTOP_BLE_QOS_INTERVAL

(int) Processing interval for QoS thread [ms]

Configure processing interval for QoS algorithm. Longer intervals means more time to accumulate CRC stats, and vice versa.

CONFIG_DESKTOP_BLE_QOS_STACK_SIZE

(int) Base stack size for QoS thread

Configure base stack size for QoS processing thread.

CONFIG_DESKTOP_BLE_QOS_STATS_PRINTOUT_ENABLE

(bool) Enable BLE QoS statistics printout

Enable to get real-time QoS information printouts via CDC ACM.

CONFIG_DESKTOP_BLE_QOS_STATS_PRINT_STACK_SIZE

(int) Stack size addition for QoS printout

This size increase is added to the QoS base stack size to facilitate statistics printout.

CONFIG_DESKTOP_HIDS_ENABLE

(bool)

This option enables HID over GATT service.

CONFIG_DESKTOP_HID_PERIPHERAL

(bool)

This option selects required options if device is HID peripheral.

CONFIG_DESKTOP_HIDS_FIRST_REPORT_DELAY

(int) First HID report delay [ms]

If set to non-zero, the peripheral will delay sending first HID report after the connection security was established. This is done to ensure that central will be ready to receive the data. nRF Desktop centrals reenable the subscriptions on every reconnection. HID report is dropped if received before the subscription was reenabled.

CONFIG_DESKTOP_HID_FORWARD_ENABLE

(bool) Enable HID forward

This option enables HID over GATT Client. The reports received from the BLE are forwarded to the USB.

CONFIG_DESKTOP_HID_FORWARD_MAX_ENQUEUED_REPORTS

(int) Enqueued reports limit

A single instance of HID-class USB device can forward one report at a time. If busy the incoming report will be enqueued.

The limit is defined separately for every HID input report type of a given Bluetooth peripheral.

CONFIG_DESKTOP_BAS_ENABLE

(bool)

This option enables battery service.

CONFIG_DESKTOP_QOS_ENABLE

(bool) QoS service

This option enables QoS service.

CONFIG_DESKTOP_CONFIG_CHANNEL_ENABLE

(bool) Enable user configuration channel

Enables user to change firmware parameters at runtime over the configuration channel.

CONFIG_DESKTOP_CONFIG_CHANNEL_OUT_REPORT

(bool) Enable additional HID output report

Use additional HID output report for configuration channel data transfer. The HID output report is used only by nRF Desktop dongle, other hosts use the HID feature report.

For HID output reports, the dongle can use write without response. In that case LLPM peripheral does not have to respond instead of providing HID notification during one connection event.

Using HID output report prevents report rate drops when forwarding configuration channel data, but it increases memory consumption of the peripheral.

The config channel HID output report is handled in a dedicated way. It does not use the same infrastructure as other HID output reports.

CONFIG_DESKTOP_CONFIG_CHANNEL_TIMEOUT

(int) Transaction timeout on configuration channel in seconds

Timeout [s] after which config channel transaction is dropped.

CONFIG_DESKTOP_CONFIG_CHANNEL_DFU_ENABLE

(bool) DFU over the config channel

This option enables DFU over the config channel.

CONFIG_DESKTOP_CONFIG_CHANNEL_DFU_SYNC_BUFFER_SIZE

(int) Size (in words) of sync buffer

Number of words DFU data synchronization buffer will use. The new image data is first transmitted to this RAM located buffer. When host performs progress synchronization the data is moved from RAM to flash. The host must perform progress synchronization at least every synchronization buffer bytes count.

CONFIG_DESKTOP_FN_KEYS_ENABLE

(bool) Enable function keys support

Button remapper adds fn bit to all key ids while fn key is pressed.

CONFIG_DESKTOP_FN_KEYS_SWITCH

(hex) Fn button

Define button used as a function key.

CONFIG_DESKTOP_FN_KEYS_LOCK

(hex) Fn lock button

Define button used as a function key lock.

CONFIG_DESKTOP_STORE_FN_LOCK

(bool) Store Fn lock state

Define if device should store Fn lock state after reboot.

CONFIG_DESKTOP_FN_KEYS_MAX_ACTIVE

(int) Max Fn key pressed

Maximum number of function keys pressed at the same time.

CONFIG_DESKTOP_WATCHDOG_ENABLE

(bool) Enable watchdog support

Enable watchdog to reset the device in case of problems.

CONFIG_DESKTOP_WATCHDOG_TIMEOUT

(int) Watchdog timeout value [ms]

Timeout of watchdog timer. After the time elapse a device will be restarted.

CONFIG_DESKTOP_HFCLK_LOCK_ENABLE

(bool) Keep HF clock enabled

Keeping the HF clock enabled is needed to reduce the latency before the first packet (in a row) is transmitted over the BLE. If disabled a startup delay of around 1.5 ms will be added to overall latency of the first packet. If enabled current consumption is increased.

CONFIG_DESKTOP_CONSTLAT_ENABLE

(bool) Constant latency interrupts

When enabled SoC will use configuration for constant latency interrupts. This reduces interrupt propagation time but increases power consumption.

CONFIG_DESKTOP_CONSTLAT_DISABLE_ON_STANDBY

(bool) Disable constant latency interrupts on standby

When enabled constant latency interrupts will be disabled when the devices switches to standby.

CONFIG_DESKTOP_FAILSAFE_ENABLE

(bool) Enable failsafe

When a device is rebooted by watchdog or due to the CPU lockup, the settings partition will be erased. This is to prevent the broken settings from permanently rendering the device unusable.

CONFIG_DESKTOP_CPU_MEAS_ENABLE

(bool) Enable measuring CPU load

The CPU load is sent periodically using dedicated application event.

CONFIG_DESKTOP_CPU_MEAS_PERIOD

(int) Time between subsequent CPU load events [ms]

The CPU load event is submitted periodically by a delayed work. When the event is submitted, application module resets measurement. According to CPU load subsystem documentation, measurement must be reset at least every 4294 seconds. Otherwise results are invalid.

CONFIG_DESKTOP_NRF_PROFILER_SYNC_GPIO_ENABLE

(bool) Enable nrf_profiler sync based on GPIO

This option can be used to synchronize timestamps for nrf_profiler events on two devices.

When this option is enabled nRF Desktop devices generate nrf_profiler event (sync_event) that is used for synchronization. Central generates square wave using GPIO, peripheral reacts on the edges. Make sure that selected pins of the central and the peripheral are connected together.

CONFIG_DESKTOP_NRF_PROFILER_SYNC_CENTRAL

(bool) Central

This is the default option, the device is central.

CONFIG_DESKTOP_NRF_PROFILER_SYNC_PERIPHERAL

(bool) Peripheral

If selected, the device is peripheral.

CONFIG_DESKTOP_NRF_PROFILER_SYNC_GPIO_PORT

(int) Sync GPIO port

This option defines which GPIO port is to be used to generate/receive synchronization signal. The signal is used to synchronize timestamps between two different devices.

CONFIG_DESKTOP_NRF_PROFILER_SYNC_GPIO_PIN

(int) Sync GPIO pin

This option defines which GPIO pin is to be used to generate/receive synchronization signal. The signal is used to synchronize timestamps between two different devices.

CONFIG_BT_ADV_PROV_FLAGS

(unknown)

None

CONFIG_BT_ADV_PROV_GAP_APPEARANCE

(unknown)

None

CONFIG_BT_ADV_PROV_DEVICE_NAME

(unknown)

None

CONFIG_BT_ADV_PROV_SWIFT_PAIR

(unknown)

None

CONFIG_BT_ADV_PROV_TX_POWER

(unknown)

None

CONFIG_DESKTOP_ADV_PROV_UUID16_ALL

(bool) UUID16 advertising provider

Adds all UUID16 to the advertising payload if used Bluetooth local identity has no bond.

API documentation

Following are the API elements used by the application.

HID reports

Header file: applications/nrf_desktop/configuration/common/hid_report_desc.h
Source file: applications/nrf_desktop/configuration/common/hid_report_desc.c
group nrf_desktop_hid_reports

HID Reports.

Enums

enum report_id

Identification numbers of HID reports.

Values:

enumerator REPORT_ID_RESERVED

Reserved.

enumerator REPORT_ID_MOUSE

Mouse input report.

enumerator REPORT_ID_KEYBOARD_KEYS

Keyboard input report.

enumerator REPORT_ID_SYSTEM_CTRL

System control input report.

enumerator REPORT_ID_CONSUMER_CTRL

Consumer control input report.

enumerator REPORT_ID_KEYBOARD_LEDS

Keyboard output report.

enumerator REPORT_ID_USER_CONFIG

Config channel feature report.

enumerator REPORT_ID_USER_CONFIG_OUT

Config channel output report.

enumerator REPORT_ID_VENDOR_IN

Reserved.

enumerator REPORT_ID_VENDOR_OUT

Reserved.

enumerator REPORT_ID_BOOT_MOUSE

Boot report - mouse.

enumerator REPORT_ID_BOOT_KEYBOARD

Boot report - keyboard.

enumerator REPORT_ID_COUNT

Number of reports.

Variables

static const uint8_t input_reports[] = {REPORT_ID_MOUSE, REPORT_ID_KEYBOARD_KEYS, REPORT_ID_SYSTEM_CTRL, REPORT_ID_CONSUMER_CTRL, REPORT_ID_BOOT_MOUSE, REPORT_ID_BOOT_KEYBOARD,}

Input reports map.

static const uint8_t output_reports[] = {REPORT_ID_KEYBOARD_LEDS,}

Output reports map.

const uint8_t hid_report_desc[]
const size_t hid_report_desc_size

LED states

Header file: applications/nrf_desktop/configuration/common/led_state.h
Source file: applications/nrf_desktop/src/modules/led_state.c
group nrf_desktop_led_state

LED State.

Defines

LED_UNAVAILABLE
LED_PEER_COUNT

Enums

enum led_system_state

System states represented by LED.

Values:

enumerator LED_SYSTEM_STATE_IDLE

Device is idle.

enumerator LED_SYSTEM_STATE_CHARGING

Device is charging.

enumerator LED_SYSTEM_STATE_ERROR

Device in error state.

enumerator LED_SYSTEM_STATE_COUNT

Number of system states.

enum led_peer_state

Peer states represented by LED.

Values:

enumerator LED_PEER_STATE_DISCONNECTED

Peer is disconnected.

enumerator LED_PEER_STATE_CONNECTED

Peer is connected.

Device searches for peer.

enumerator LED_PEER_STATE_CONFIRM_SELECT

Device waits for user to confirm peer switch.

enumerator LED_PEER_STATE_CONFIRM_ERASE

Device waits for user to confirm bond erase.

enumerator LED_PEER_STATE_ERASE_ADV

Device searches for new peer before bond erase.

enumerator LED_PEER_STATE_COUNT

Number of peer states.

enum led_id_nrf_desktop

LED identification.

Values:

enumerator LED_ID_SYSTEM_STATE

LED representing system state.

enumerator LED_ID_PEER_STATE

LED representing peer state.

enumerator LED_ID_COUNT

Number of LEDs.

USB events

Header file: applications/nrf_desktop/src/events/usb_event.h
Source file: applications/nrf_desktop/src/modules/usb_state.c
group nrf_desktop_usb_event

USB Event.

File defines a set of events used to transmit the information about USB state between the application modules.

Enums

enum usb_state

Peer states.

Values:

enumerator USB_STATE_DISCONNECTED

Cable is not attached.

enumerator USB_STATE_POWERED

Cable attached but no communication.

enumerator USB_STATE_ACTIVE

Cable attached and data is exchanged.

enumerator USB_STATE_SUSPENDED

Cable attached but port is suspended.

enumerator USB_STATE_COUNT

Number of states.

struct usb_state_event
#include <usb_event.h>

USB state event.

Public Members

struct app_event_header header

Event header.

enum usb_state state

State of the USB module.

struct usb_hid_event
#include <usb_event.h>

USB HID event.

Public Members

struct app_event_header header

Event header.

const void *id

USB HID device id.

bool enabled

USB HID device enabled state.