nRF Desktop

The nRF Desktop is a reference design of a Human Interface Device (HID) that is connected to a host through Bluetooth LE or USB, or both. Depending on the configuration, this application can work as desktop mouse, gaming mouse, keyboard, or connection dongle.

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. The firmware can be configured 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 and event-driven. 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 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 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.

Application high-level design overview (click to enlarge)

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

Application configured as a gaming mouse (click to enlarge)

Desktop mouse module set

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

Application configured as a desktop mouse (click to enlarge)

Keyboard module set

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

Application configured as a keyboard (click to enlarge)

Dongle module set

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

Application configured as a dongle (click to enlarge)

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 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:

• Create the event manager events. For more information, see the Event Manager page.

• Temporarily store the HID-related data in the HID state module and HID forward module. For more information, see the documentation pages of these modules.

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

• CONFIG_HEAP_MEM_POOL_SIZE - The size must be big enough to handle the worst possible use case for the given device.

• CONFIG_HEAP_MEM_POOL_MIN_SIZE

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 mouse data forwarding

The nRF Desktop mouse sends HID input reports to 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 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.

7. USB state has precedence if USB is connected.

8. 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. The pipeline is created when the first motion_event is received. The HID state module submits two hid_report_event events. When the first one is sent to the host, the motion sensor sample is triggered.

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 will be 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

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.

Gaming mouse

Desktop mouse

Keyboard

HID dongle

DK

Hardware platforms	PCA	Board name	Build target
nRF52840 Gaming Mouse	PCA20041	nrf52840gmouse_nrf52840	nrf52840gmouse_nrf52840

Hardware platforms	PCA	Board name	Build target
nRF52832 Desktop Mouse	PCA20044	nrf52dmouse_nrf52832	nrf52dmouse_nrf52832
nRF52810 Desktop Mouse	PCA20045	nrf52810dmouse_nrf52810	nrf52810dmouse_nrf52810

Hardware platforms	PCA	Board name	Build target
nRF52832 Desktop Keyboard	PCA20037	nrf52kbd_nrf52832	nrf52kbd_nrf52832

Hardware platforms	PCA	Board name	Build target
nRF52840 Dongle	PCA10059	nrf52840dongle_nrf52840	nrf52840dongle_nrf52840
nRF52833 Dongle	PCA10111	nrf52833dongle_nrf52833	nrf52833dongle_nrf52833
nRF52820 Dongle	PCA10114	nrf52820dongle_nrf52820	nrf52820dongle_nrf52820

Hardware platforms	PCA	Board name	Build target
nRF52840 DK	PCA10056	nrf52840dk_nrf52840	nrf52840dk_nrf52840
nRF52833 DK	PCA10010	nrf52833dk_nrf52833	nrf52833dk_nrf52833

In nRF52840 DK, the application is configured to work as gaming mouse (with motion emulated by using DK buttons) and in nRF52833 DK, the application is configured to work as HID dongle.

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

nRF Desktop build types

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

Build types enable you to use different sets of configuration options for each board. You can create several build type .conf files per board and select one of them when building the application. This means that you do not have to use one prj.conf file for your project and modify it each time to fit your needs.

Note

Selecting a build type is optional. The ZDebug 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 nRF Desktop:

• ZRelease – Release version of the application with no debugging features.

• ZReleaseB0 – ZRelease build type with the support for the B0 bootloader enabled (for background DFU).

• ZReleaseMCUBoot – ZRelease build type with the support for the MCUBoot bootloader enabled (for serial recovery DFU or background DFU).

• ZDebug – Debug version of the application; the same as the ZRelease build type, but with debug options enabled.

• ZDebugB0 – ZDebug build type with the support for the B0 bootloader enabled (for background DFU).

• ZDebugMCUBoot – ZDebug build type with the support for the MCUBoot bootloader enabled (for serial recovery DFU or background DFU).

• ZDebugWithShell – ZDebug build type with the shell enabled.

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 ZDebugWithShell build type is not supported on the selected DK, the following notification appears:

Configuration file for build type ZDebugWithShell is missing.

In addition to the build types mentioned above, some boards can provide more build types, which can be used to generate an application in a specific variant. For example, such additional configurations are used to allow generation of application with different role (such as mouse, keyboard, or dongle on a DK board) or to select a different link layer (such as LLPM capable Nordic SoftDevice LL or standard Zephyr SW LL).

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:

Gaming mouse

Desktop mouse

Keyboard

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.

The switch is located at the bottom of the desktop mouse, close to the optical sensor.

The switch is located at the back of the keyboard.

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.

Gaming mouse

HID dongle

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.

The dongle has an USB connector located at one end of the board. It should be inserted to the USB slot located on the host.

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

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.

Gaming mouse

Desktop mouse

Keyboard

HID dongle

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

• 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

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

The following predefined buttons are assigned to peer control operations for the desktop mouse:

Scroll wheel button

• The scroll wheel must be pressed before the mouse is powered up with the on/off switch. Long-press to initialize and confirm the peer erase.

  

  nRF Desktop desktop mouse - side view

  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.

The following predefined buttons or button combinations are assigned to peer control operations for the keyboard:

Page Down key

• The Page Down key must be pressed while keeping the Fn modifier key pressed.

  

  nRF Desktop keyboard - top view

• Short-press the Page Down key to initialize the peer selection. During the peer selection:

  1. Short-press to toggle between available peers. LED1 blinks rapidly for each peer. The amount of blinks corresponds to the number assigned to a peer: one blink for peer 1, two blinks for peer 2, and so on.

  2. Double-press to confirm the peer selection. The peer is changed after the confirmation. LED1 becomes solid for a short time and then turns itself off.

     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.

The following predefined buttons are assigned to peer control operations for the HID dongle:

SW1 button

• The SW1 button is located on the top of the dongle, on the same side as LED2.

  

  nRF Desktop dongle - top view

• Long-press to initialize peer erase. When LED2 starts blinking rapidly, double-press to confirm the operation. After the confirmation, all the Bluetooth bonds are removed for the dongle.

• Short-press to start scanning for both bonded and non-bonded Bluetooth Peripherals. The scan is interrupted if another peripheral connected to the dongle is in use.

  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.

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

Gaming mouse

HID dongle

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.

LED1 is used for the system state indication. It is located in the bottom right corner of the dongle, next to the USB connector.

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.

Gaming mouse

Desktop mouse

Keyboard

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

The debug slot is located on the side of the desktop mouse. It is accesible through a hole in the casing.

The debug slot is located on the back of the keyboard.

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.

Debug board

Short bypass board

Long bypass board

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

The shorter nRF desktop bypass board can be used with the desktop mouse.

The longer nRF desktop bypass board can be used with the gaming mouse.

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_DESKTOP_POWER_MANAGER_TIMEOUT. By default, this period is set to 120 seconds.

Important

When the gaming mouse is powered from USB, the power down time-out 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.

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.

See Building and programming a sample application for information about how to build and program the application.

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 SES

To select the build type in SEGGER Embedded Studio:

1. Go to File > Open nRF Connect SDK project, select the current project, and specify the board name and build directory.

2. Select Extended Settings.

3. In the Extra CMake Build Options field, specify -DCMAKE_BUILD_TYPE=selected_build_type. For example, for ZRelease set the following value: -DCMAKE_BUILD_TYPE=ZRelease.

4. Do not select Clean Build Directory.

5. Click OK to re-open the project.

Note

You can also specify the build type in the Additional CMake Options field in Tools -> Options -> nRF Connect. However, the changes will only be applied after re-opening the project. Reloading the project is not sufficient.

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 -- -DCMAKE_BUILD_TYPE=selected_build_type to the west build command.

For example, you can build the ZRelease firmware for the PCA20041 board by running the following command in the project directory:

west build -b nrf52840_pca20041 -d build_pca20041 -- -DCMAKE_BUILD_TYPE=ZRelease

The build_pca20041 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 time-out. 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 Guide 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. For information about differences between DTS and Kconfig, see Devicetree versus Kconfig.

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 ZDebug 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 preconfigured build types configure the device with or without the bootloader and in debug or release mode.

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.

• There is no configuration with bootloader available.

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 bootloader is available.

Sample dongle (nrf52833dk_nrf52833)

• The configuration uses the nRF52833 Development Kit.

• The application is configured to act as 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.

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 with or without the bootloader and in debug or release mode.

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 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 preconfigured build types configure the device with or without the bootloader and in debug or release mode.

nRF52820 USB Dongle (nrf52820dongle_nrf52820)

• The application is configured to act as 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 with or without the bootloader and in debug or release mode.

Adding a new board

When adding a new board for the first time, focus on a single configuration. Moreover, keep the default ZDebug 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.

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:

   • Pins that are used.

   • Bus configuration for optical sensor.

   • Changing interrupt priority.

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:

   • Motion module

   • Wheel module

   • Buttons module

   • Battery measurement module

   • LEDs module

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. The PWM peripheral must be configured in DTS files, and the _def file of the LEDs module must be configured 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.

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

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

3. 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";
     sck-pin = <16>;
     mosi-pin = <17>;
     miso-pin = <15>;
     cs-gpios = <&gpio0 13 0>;

     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 (a 1-ms interval), the sensor data readout should take no more then 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.

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

5. Select the new sensor

After all the previous steps are done, the new sensor can be used by the application. Edit the application configuration files for your board to enable it. See Board configuration for details.

At this point, you can start using the new sensor by completing 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 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. In case of 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 case of nRF52840, this is zephyr/dts/arm/nordic/nrf52840.dtsi, which has the following interrupts property for nRF52840:

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:

• Memory layout in DTS (bootloader is not enabled)

• Memory layout in partition manager (bootloader is enabled)

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.

Warning

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_$CMAKE_BUILD_TYPE.yml file to the project’s board configuration directory to define the static partition manager configuration for given board and build type. 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 ZDebugMCUBootQSPI 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 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: The option must be set 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, you must update the LED effects used to represent the Bluetooth connection state. For details, see LED state module.

Link Layer configuration options

The nRF Desktop devices use one of the following Link Layers:

• CONFIG_BT_LL_SW_SPLIT

  This Link Layer does not support the Low Latency Packet Mode (LLPM) and has a lower memory usage, so it can be used by memory-limited devices.

• CONFIG_BT_LL_SOFTDEVICE

  This Link Layer does support the Low Latency Packet Mode (LLPM). If you opt for this Link Layer and enable this option, the CONFIG_DESKTOP_BLE_USE_LLPM is also enabled by default and can be configured further:

  • When CONFIG_DESKTOP_BLE_USE_LLPM is enabled, set the value for CONFIG_SDC_MAX_CONN_EVENT_LEN_DEFAULT to 3000.

    This is required by the nRF Desktop central and helps avoid scheduling conflicts with Bluetooth Link Layer. Such conflicts could lead to a drop in HID input report rate or a disconnection. Setting the value to 3000 also enables the nRF Desktop central to exchange data with up to 2 standard Bluetooth LE peripherals during every connection interval (every 7.5 ms).

  • When CONFIG_DESKTOP_BLE_USE_LLPM is disabled, the device will use only standard Bluetooth LE connection parameters with the lowest available connection interval of 7.5 ms.

    If the LLPM is disabled and more than 2 simultaneous Bluetooth connections are supported (CONFIG_BT_MAX_CONN), you can set the value for CONFIG_SDC_MAX_CONN_EVENT_LEN_DEFAULT to 2500. With this value, the nRF Desktop central is able to exchange the data with up to 3 Bluetooth LE peripherals during every 7.5-ms connection interval. Using the value of 3000 for more than 2 simultaneous Bluetooth LE connections will result in a lower HID input report rate.

Application modules

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

• Bluetooth LE state module - Enables Bluetooth and LLPM (if supported), and handles Zephyr connection callbacks.

• Bluetooth LE bond module - Manages Bluetooth bonds and local identities.

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:

• Bluetooth LE Quality of Service module - Helps achieve better connection quality and higher report rate. The module can be used only with the SoftDevice Link Layer.

Note

The nRF Destkop 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:

• HID Service - Handled in the HID Service module.

• Battery Service - Handled in the GATT Battery Service module.

• Device Information Service - Implemented in Zephyr and enabled with CONFIG_BT_DIS. It can be configured using Kconfig options with the CONFIG_BT_DIS prefix.

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:

• Bluetooth LE advertising module - Controls the Bluetooth advertising.

• Bluetooth LE latency module - Keeps the connection latency low when the Configuration channel is being used or when an update image is being received by the Simple Management Protocol module. This is done to ensure quick data transfer.

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:

• Bluetooth LE scanning module - Controls the Bluetooth scanning.

• Bluetooth LE connection parameters module - Control the Bluetooth connection parameters and react on connection slave latency update requests received from the connected peripherals.

• Bluetooth LE discovery module - Handles discovering and reading the GATT Characteristics from the connected peripheral.

• HID forward module - Subscribes for HID reports from the Bluetooth Peripherals (HID over GATT) and forwards data using application events.

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 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. The debug key should never be used 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:

• CONFIG_SB_SIGNING_KEY_FILE - Required for providing the signature used for image signing and verification.

• CONFIG_FW_INFO - Required for the application versioning information.

• CONFIG_FW_INFO_FIRMWARE_VERSION - Enable this option to set the version of the application after you enabled CONFIG_FW_INFO.

• CONFIG_BUILD_S1_VARIANT - Required for the build system to be able to construct the application binaries for both application’s slots in flash memory.

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 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 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 transfered 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 MCUboot must be used 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

MCUboot must be configured 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 ZReleaseMCUBoot 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 ZDebugMCUBootSMP 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 stack for more information.

• CONFIG_BOOT_SERIAL_DETECT_PORT and CONFIG_BOOT_SERIAL_DETECT_PIN - These options select the pin used for triggering the serial recovery mode. To enter the serial recovery mode, the pin must be set to a logic value defined by CONFIG_BOOT_SERIAL_DETECT_PIN_VAL when the device boots. By default, the selected GPIO pin should be set to low.

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

Dependencies

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

• Event Manager

• Profiler

• GATT Human Interface Device (HID) Service

• GATT Human Interface Device (HID) Service Client

• Scanning module

• GATT Discovery Manager

• drivers/sensor/paw3212

• drivers/sensor/pmw3360

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 event. 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:

• Basic module (main)
• Battery charger module
• Battery measurement module
• Bluetooth LE advertising module
• Bluetooth LE bond module
• Bluetooth LE connection parameters module
• Bluetooth LE discovery module
• Bluetooth LE latency module
• Bluetooth LE Quality of Service module
• Bluetooth LE scanning module
• Bluetooth LE state module
• Board module
• Buttons module
• Button simulator module
• Click detector module
• Configuration channel
• CPU measurement module
• Device description module
• Device Firmware Upgrade module
• Failsafe module
• Function key module
• GATT Battery Service module
• HID forward module
• HID state module
• HID Service module
• Info module
• LED state module
• LED stream module
• LEDs module
• Motion module
• Passkey module
• Power manager module
• Profiler synchronization module
• Quality of Service module
• Selector module
• Simple Management Protocol module
• Settings loader module
• USB state module
• Watchdog module
• Wheel module
• Constant latency hotfix module
• High frequency clock lock hotfix module
• Source and sink module lists

Application configuration options

CONFIG_DESKTOP_INIT_LOG_BATTERY_STATE_EVENT

(bool) Battery state event

None

CONFIG_DESKTOP_INIT_LOG_BATTERY_LEVEL_EVENT

(bool) Battery level event

None

CONFIG_DESKTOP_INIT_LOG_BLE_PEER_EVENT

(bool) BLE peer event

None

CONFIG_DESKTOP_INIT_LOG_BLE_PEER_SEARCH_EVENT

(bool) BLE peer search event

None

CONFIG_DESKTOP_INIT_LOG_BLE_PEER_OPERATION_EVENT

(bool) BLE peer operation event

None

CONFIG_DESKTOP_INIT_LOG_BLE_PEER_CONN_PARAMS_EVENT

(bool) BLE peer connection parameters event

None

CONFIG_DESKTOP_INIT_LOG_BLE_DISC_COMPLETE_EVENT

(bool) BLE discovery complete event

None

CONFIG_DESKTOP_INIT_LOG_BLE_SMP_TRANSFER_EVENT

(bool) BLE SMP transfer event

None

CONFIG_DESKTOP_INIT_LOG_BLE_QOS_EVENT

(bool) BLE QOS event

None

CONFIG_DESKTOP_INIT_LOG_BUTTON_EVENT

(bool) Button event

None

CONFIG_DESKTOP_INIT_LOG_CPU_LOAD_EVENT

(bool) CPU load event

None

CONFIG_DESKTOP_INIT_LOG_CLICK_EVENT

(bool) Click event

None

CONFIG_DESKTOP_INIT_LOG_SELECTOR_EVENT

(bool) Selector event

None

CONFIG_DESKTOP_INIT_LOG_PASSKEY_EVENT

(bool) Passkey event

None

CONFIG_DESKTOP_INIT_LOG_CONFIG_EVENT

(bool) Config event

None

CONFIG_DESKTOP_INIT_LOG_HID_SUBSCRIBER_EVENT

(bool) HID report subscriber event

None

CONFIG_DESKTOP_INIT_LOG_HID_SUBSCRIPTION_EVENT

(bool) HID report subscription event

None

CONFIG_DESKTOP_INIT_LOG_HID_REPORT_EVENT

(bool) HID report event

None

CONFIG_DESKTOP_INIT_LOG_HID_REPORT_SENT_EVENT

(bool) HID report sent event

None

CONFIG_DESKTOP_INIT_LOG_LED_EVENT

(bool) LED event

None

CONFIG_DESKTOP_INIT_LOG_LED_READY_EVENT

(bool) LED ready event

None

CONFIG_DESKTOP_INIT_LOG_MODULE_STATE_EVENT

(bool) Module state event

None

CONFIG_DESKTOP_INIT_LOG_MOTION_EVENT

(bool) Motion event

None

CONFIG_DESKTOP_INIT_LOG_POWER_DOWN_EVENT

(bool) Power down event

None

CONFIG_DESKTOP_INIT_LOG_WAKE_UP_EVENT

(bool) Wake up event

None

CONFIG_DESKTOP_INIT_LOG_USB_STATE_EVENT

(bool) USB state event

None

CONFIG_DESKTOP_INIT_LOG_USB_HID_EVENT

(bool) USB HID event

None

CONFIG_DESKTOP_INIT_LOG_WHEEL_EVENT

(bool) Wheel event

None

CONFIG_DESKTOP_INIT_LOG_HID_NOTIFICATION_EVENT

(bool) HID notification event

None

CONFIG_DESKTOP_MOTION_NONE

(bool) Disable motion

None

CONFIG_DESKTOP_MOTION_SENSOR_PMW3360_ENABLE

(bool) Motion from optical sensor PMW3360

None

CONFIG_DESKTOP_MOTION_SENSOR_PAW3212_ENABLE

(bool) Motion from optical sensor PAW3212

None

CONFIG_DESKTOP_MOTION_BUTTONS_ENABLE

(bool) Motion from buttons

None

CONFIG_DESKTOP_MOTION_SIMULATED_ENABLE

(bool) Simulated motion

None

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]

Must be power of two (calculations speedup).

CONFIG_DESKTOP_MOTION_SIMULATED_SCALE_FACTOR

(int) Scale factor for given shape

None

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_NONE

(bool) Disable buttons

None

CONFIG_DESKTOP_BUTTONS_ENABLE

(bool) Buttons scanned from key matrix or directly connected GPIO

None

CONFIG_DESKTOP_BUTTONS_SCAN_INTERVAL

(int) Buttons scan interval in ms

Interval at which key matrix is scanned.

CONFIG_DESKTOP_BUTTONS_DEBOUNCE_INTERVAL

(int) Interval before first button scan in ms

Interval before first scan. Introduced for debouncing reasons.

CONFIG_DESKTOP_BUTTONS_POLARITY_INVERSED

(bool) Inverse buttons polarity

When this option is enabled, button is pressed when the GPIO state is low.

CONFIG_DESKTOP_BUTTONS_EVENT_LIMIT

(int) Number of button events in single scan loop

This option specifies the number of button events generated during a single scanning loop. If more keys change state between scanning intervals, subsequent changes will be ignored and picked up during the next scanning.

CONFIG_DESKTOP_BUTTONS_SIM_ENABLE

(bool) Enable simulated button presses generator

None

CONFIG_DESKTOP_BUTTONS_SIM_INTERVAL

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

None

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

None

CONFIG_DESKTOP_CLICK_DETECTOR_ENABLE

(bool) Enable click detector

None

CONFIG_DESKTOP_SELECTOR_HW_ENABLE

(bool) Enable HW based selector

None

CONFIG_DESKTOP_WHEEL_ENABLE

(bool) Enable wheel hardware interface

None

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_LED_ENABLE

(bool) Enable LED hardware interface

None

CONFIG_DESKTOP_LED_COUNT

(int) Number of LEDs in use

None

CONFIG_DESKTOP_LED_COLOR_COUNT

(int) Number of color channels per diode

None

CONFIG_DESKTOP_LED_BRIGHTNESS_MAX

(int) Maximum value for LED brightness

None

CONFIG_DESKTOP_BATTERY_CHARGER_NONE

(bool) No battery charging

None

CONFIG_DESKTOP_BATTERY_CHARGER_DISCRETE

(bool) Discrete battery charger

None

CONFIG_DESKTOP_BATTERY_CHARGER_CSO_PIN

(int) Charging status pin

A pin number to which CSO output is connected.

CONFIG_DESKTOP_BATTERY_CHARGER_CSO_PULL_NONE

(bool) Disable CSO pin pull

None

CONFIG_DESKTOP_BATTERY_CHARGER_CSO_PULL_UP

(bool) Enable CPO pin pull up

None

CONFIG_DESKTOP_BATTERY_CHARGER_CSO_PULL_DOWN

(bool) Enable CSO pin pull down

None

CONFIG_DESKTOP_BATTERY_CHARGER_ENABLE_PIN

(int) Battery charging enable pin

A pin which enables battery charging.

CONFIG_DESKTOP_BATTERY_CHARGER_ENABLE_INVERSED

(bool) Inverse charging enable signal

Set this option if battery is charged when enable signal is set to zero.

CONFIG_DESKTOP_BATTERY_CHARGER_CSO_FREQ

(int) CSO switching frequency (in Hz) on error state

A frequency with which CSO pin switches state when charging error occurs.

CONFIG_DESKTOP_BATTERY_MEAS_NONE

(bool) No battery measurement

None

CONFIG_DESKTOP_BATTERY_MEAS

(bool) Enable battery measurement circuit

None

CONFIG_DESKTOP_BATTERY_MEAS_MIN_LEVEL

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

None

CONFIG_DESKTOP_BATTERY_MEAS_MAX_LEVEL

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

None

CONFIG_DESKTOP_BATTERY_MEAS_HAS_VOLTAGE_DIVIDER

(bool) Use voltage divider for battery measurement

None

CONFIG_DESKTOP_BATTERY_MEAS_VOLTAGE_DIVIDER_UPPER

(int) Upper resistor in battery measurement voltage divider [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]

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]

None

CONFIG_DESKTOP_BATTERY_MEAS_HAS_ENABLE_PIN

(bool) Use pin for enabling battery measurement

None

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

None

CONFIG_DESKTOP_PASSKEY_BUTTONS

(bool) Passkey based on button presses

None

CONFIG_DESKTOP_PASSKEY_MAX_LEN

(int) Max number of digits in passkey

None

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 keyboard

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_SMP_ENABLE

(bool) SMP via BLE

This option enables SMP service allowing DFU via BLE.

CONFIG_DESKTOP_POWER_MANAGER_ENABLE

(bool) Enable power management

Enable power management, which will put the device to low-power mode if it is idle.

CONFIG_DESKTOP_POWER_MANAGER_STAY_ON

(bool) Stay on while no connections

If disabled the device will switch SoC to OFF mode after power manager timeout is done. If enabled the device will stay on but remain idle. If the device is connected it will always stay on and maintain the connection, regardless of the setting.

CONFIG_DESKTOP_POWER_MANAGER_TIMEOUT

(int) Power down timeout [s]

Time in seconds after which the device will enter low-power mode.

CONFIG_DESKTOP_POWER_MANAGER_ERROR_TIMEOUT

(int) Power manager timeout on error [s]

Time in seconds after which the device will be turned off after an error.

CONFIG_DESKTOP_HID_STATE_ENABLE

(bool) Enable HID state

HID events processing module.

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

None

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

None

CONFIG_DESKTOP_USB_ENABLE

(bool) Enable USB module

Enables USB module.

CONFIG_DESKTOP_BLE_ENABLE_PASSKEY

(bool) Enable passkey based pairing

Enable passkey based pairing for increased security.

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 not 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_ADVERTISING_ENABLE

(bool) Enable BLE advertising

Make device discoverable via BLE.

CONFIG_DESKTOP_BLE_DIRECT_ADV

(bool) Advertise to bonded peer directly

Device will use direct advertising if bonded.

CONFIG_DESKTOP_BLE_FAST_ADV

(bool) Enable period of fast advertising

Device will initially advertise with shorter interval.

CONFIG_DESKTOP_BLE_FAST_ADV_TIMEOUT

(int) Time of initial fast advertising [s]

Device will initially advertise with shorter interval to enable quicker discovery by hosts. After this time it will shift to normal cadence advertising.

CONFIG_DESKTOP_BLE_SWIFT_PAIR

(bool) Enable Swift Pair feature

Enable quick pairing with Microsoft Swift Pair.

CONFIG_DESKTOP_BLE_SWIFT_PAIR_GRACE_PERIOD

(int) No Swift Pair time gap before suspend [s]

To ensure users will not try to connect to a device which is no longer available, Swift Pair vendor section will be removed before exiting from advertising mode.

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_DISCOVERY_ENABLE

(bool) Enable BLE discovery

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

CONFIG_DESKTOP_BLE_USE_LLPM

(bool) Use LLPM connection parameters

LLPM connection interval is necessary to achieve high report rates (up to 1000 reports/second). With standard BLE connection, the lowest available connection interval is 7.5 ms. LLPM parameters can be used for given connection only if it’s supported by both peripheral and central.

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

CONFIG_DESKTOP_CONFIG_CHANNEL_TIMEOUT

(int) Transaction timeout on configuration channel in seconds

None

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_SETTINGS_LOADER_USE_THREAD

(bool) Enable loading of setting by separate thead

The option enables loading of settings by separate thread in background instead of use of system work queue for that purpose.

CONFIG_DESKTOP_SETTINGS_LOADER_THREAD_STACK_SIZE

(int) Settings module thread stack size

Stack size for thread responsible for loading settings from flash memory.

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_BLE_TX_PWR

(int)

For nrfxlib LL TX power has to be set using HCI commands. Zephyr Kconfig options are ignored.

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. Accodring to CPU load subsystem documentation, measurement must be reset at least every 4294 seconds. Otherwise results are invalid.

CONFIG_DESKTOP_PROFILER_SYNC_GPIO_ENABLE

(bool) Enable profiler sync based on GPIO

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

When this option is enabled nRF Desktop devices generate 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_PROFILER_SYNC_CENTRAL

(bool) Central

None

CONFIG_DESKTOP_PROFILER_SYNC_PERIPHERAL

(bool) Peripheral

None

CONFIG_DESKTOP_PROFILER_SYNC_GPIO_PORT

(int) Sync GPIO port

None

CONFIG_DESKTOP_PROFILER_SYNC_GPIO_PIN

(int) Sync GPIO pin

None