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.

See the following subsections for more information about the firmware architecture:

Module and component overview

The following figure shows all of nRF Desktop modules and how they relate with other components and the Event Manager.

nRF Desktop high-level design (overview)

Application high-level design overview (click to enlarge)

For more information about each of these 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.

nRF Desktop high-level design (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.

nRF Desktop high-level design (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.

nRF Desktop high-level design (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.

nRF Desktop high-level design (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 on dongle)

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 for creating the event manager events. For more information, see the Event Manager page.

When configuring HEAP, remember to set both CONFIG_HEAP_MEM_POOL_SIZE and CONFIG_HEAP_MEM_POOL_MIN_SIZE to match typical event size and system needs.

Important

Zephyr’s heap allocator divides larger blocks into four smaller blocks. This behavior impacts both the performance and the memory usage. For more information, refer to Zephyr’s documentation at Memory Heaps and Memory Pools.

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

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.

nRF Desktop gaming mouse (top view)

Hardware platforms

PCA

Board name

Build target

nRF52840 Gaming Mouse

PCA20041

nrf52840gmouse_nrf52840

nrf52840gmouse_nrf52840

nRF Desktop desktop mouse (side view)

Hardware platforms

PCA

Board name

Build target

nRF52832 Desktop Mouse

PCA20044

nrf52dmouse_nrf52832

nrf52dmouse_nrf52832

nRF52810 Desktop Mouse

PCA20045

nrf52810dmouse_nrf52810

nrf52810dmouse_nrf52810

nRF Desktop keyboard (top view)

Hardware platforms

PCA

Board name

Build target

nRF52832 Desktop Keyboard

PCA20037

nrf52kbd_nrf52832

nrf52kbd_nrf52832

nRF Desktop dongle (top view)

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

DK

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.

  • ZReleaseB0ZRelease build type with the support for the B0 bootloader enabled (for background DFU).

  • ZReleaseMCUBootZRelease build type with the support for the MCUBoot bootloader enabled (for serial recovery DFU).

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

  • ZDebugB0ZDebug build type with the support for the B0 bootloader enabled.

  • ZDebugMCUBootZDebug build type with the support for the MCUBoot bootloader enabled (for serial recovery DFU).

  • ZDebugWithShellZDebug 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 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 following functionalities:

Turning devices on and off

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

nRF Desktop gaming mouse (bottom view)

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

nRF Desktop desktop mouse (bottom view)

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

nRF Desktop keyboard (back view)

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 the following connection options:

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

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

Connection through USB

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

nRF Desktop gaming mouse (top view)

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

nRF Desktop dongle

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

The following devices 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 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 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.

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

Hardware switch
  • The switch is located next to the optical sensor.

nRF Desktop gaming mouse - bottom view

nRF Desktop gaming mouse - bottom view

  • You can set the switch in the following positions:

    • Top position: Select the dongle peer.

    • Middle position: Select the Bluetooth LE peers.

    • Bottom position: Mouse turned off.

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

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

nRF Desktop gaming mouse - side view

nRF Desktop gaming mouse - side view

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

    1. Short-press to select the next peer. The LED1 changes color and starts blinking.

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

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

    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

    nRF Desktop keyboard - top view

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

    1. Short-press to select the next peer. LED1 changes color to red and starts blinking.

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

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

    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.

nRF Desktop gaming mouse (top view)

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

nRF Desktop dongle

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.

nRF Desktop gaming mouse (top view)

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

nRF Desktop desktop mouse (side view)

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

nRF Desktop keyboard (back view)

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.

nRF Desktop debug board

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

nRF Desktop bypass board (short)

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

nRF Desktop bypass board (long)

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.


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 nRF Connect SDK Release Notes and on the Known issues wiki 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 Tools -> Options… -> nRF Connect.

  2. Set Additional CMake Options to -DCMAKE_BUILD_TYPE=selected_build_type. For example, for ZRelease set the following value: -DCMAKE_BUILD_TYPE=ZRelease.

  3. Reload the project.

The changes will be applied after reloading.

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. Insert the debug board or bypass board into the mouse to make sure it is powered.

  2. Program the required firmware to each device.

  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.


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 proprietary 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 or keyboard (nrf52840dk_nrf52840)
  • The configuration uses the nRF52840 Development Kit.

  • The build types allow to build the application both as mouse or as keyboard.

  • Inputs are simulated based on the hardware button presses.

  • The configuration with bootloader is available.

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 proprietary 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)
  • This configuration uses Nordic’s nRF52840 dongle defined in Zephyr.

  • Since the reference design is generic, 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 proprietary 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:

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

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

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

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

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

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

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

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

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

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

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

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

    • The project uses Pulse-Width Modulation (PWM) channels to control the brightness of each physical LED. 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 following steps 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:

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.

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 Legacy flash partitions.

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 project uses the static configuration of partitions. Add the pm_static_$CMAKE_BUILD_TYPE.yml partition manager configuration file to the project’s board configuration directory to use this configuration.

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

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

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

Application modules

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

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

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:

The nRF Desktop peripherals must also define a dedicated GATT Service, which is used to inform whether the device supports the LLPM Bluetooth extension. 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 Central

The nRF Desktop central must implement Bluetooth scanning and handle the GATT operations. Both these features are implemented by the following application modules:

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

Optionally, you can also enable the following module:

Bootloader

The nRF Desktop application uses Secure Bootloader, referred in this documentation 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. More information about the B0 can be found at the Immutable bootloader page.

Note

The nRF Desktop application does not support MCUboot as a second stage bootloader.

However, MCUboot can be enabled instead of B0. Although the nRF Desktop application does not use MCUboot for the background DFU, it can be the preferred choice for devices where the USB serial recovery is to be used instead (for example, due to flash memory size limitations).

Enabling the bootloader

To enable the B0 bootloader, select the CONFIG_SECURE_BOOT Kconfig option. If this option is not selected, the application will be built without the B0 bootloader, and the background DFU will not be available.

Required options

The B0 bootloader requires the following options enabled:

Background Device Firmware Upgrade

The nRF Desktop application uses the background image transfer for the background DFU process. The firmware update process has the following stages:

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 Serial recovery DFU instead.

Update image generation

The update image is automatically generated if the bootloader is enabled. By default, the build process 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.

After the build process completes, both images can be found in the build directory, in the zephyr subdirectory:

  • signed_by_b0_s0_image.bin is meant to be flashed at slot 0.

  • signed_by_b0_s1_image.bin is meant to be flashed at slot 1.

For the background DFU process, use dfu_application.zip. This package contains both images along with additional metadata. It allows the update tool to select the right image depending on the image that is currently running on the device.

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.

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

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 holding low the GPIO pin while the device boots. This is required to enter the serial recovery mode.

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 update image app_update.bin is generated by the build system and can be found in the zephyr subfolder of the build directory.)

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:


Application internal modules

The nRF Desktop application uses its own set of internal modules. See Module and component overview for more information. For more information about each application module and its configuration details, see the following pages:

Source and sink modules

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 shared from the following page: