HID configurator for nRF Desktop

This Python application uses Configuration channel for communication between a computer and firmware.

The script controls the nRF Desktop firmware parameters at runtime. It can be used for the following purposes:

• Displaying the supported modules and options

• Configuring device runtime options

• Performing DFU

• Rebooting the device

• Getting information about the firmware version

• Playing LED stream

Overview

The script looks for nRF Desktop devices connected to the host through USB, Bluetooth®, or nRF Desktop dongle. The devices are identified based on Vendor ID.

The script exchanges data with the device using Configuration channel. The data is sent using HID feature reports and targets a specific firmware module of the nRF Desktop application.

For more information about the architecture of the nRF Desktop configuration channel, see Configuration channel. The configuration channel uses a cross-platform HIDAPI library to communicate with HID devices attached to the operating system. See Dependencies for more information.

Requirements

To use the HID configurator, you must set up the required Dependencies. Complete the following instructions, depending on your operating system:

• Windows

• Debian/Ubuntu/Linux Mint

Windows

Complete the following steps:

1. Download the HIDAPI library from HIDAPI releases. Use the bundled DLL or build it according to instructions in HIDAPI library.

2. Install pyhidapi Python wrapper and other required libraries with the following command:

   py -3 -m pip install -r requirements.txt
   

3. If you want to display LED stream based on sound data, you must also install the additional requrements using the following command:

   py -3 -m pip install -r requirements_music_led_stream.txt
   

For more detailed information about LED stream functionality, see the Playing LED stream section.

Debian/Ubuntu/Linux Mint

Complete the following steps:

1. Run the following commands to install the basic requirements:

   sudo apt install libhidapi-hidraw0
   pip3 install --user -r requirements.txt
   

   Note

   When using the configuration channel for Bluetooth LE devices on Linux, use the BlueZ version 5.56 or higher. In versions earlier than 5.44, the HID device attached by BlueZ could obtain wrong VID and PID values (ignoring values in Device Information Service), which would stop HIDAPI from opening the device. In versions earlier than 5.56, the HID device attached by BlueZ might provide incomplete HID feature report on get operation.

2. If you don’t want to use the root access to run the python script, copy the provided udev rule from the 99-hid.rules file to the /etc/udev/rules.d and reconnect the device.

3. If you want to connect to a device with a different Vendor or Product ID other than the one specified in the file, use one of the following options:

   • Run the script with the root permission.

   • Complete the following steps to run the script without root permission:

     1. Add a new entry to the 99-hid.rules file with your Vendor and Product ID.

     2. Copy the provided udev rule from the 99-hid.rules file to the /etc/udev/rules.d.

     3. Reconnect the device.

   Vendor and Product ID can be specified in the configuration file related to the nRF Desktop application. The following examples shows the entry to add to the 99-hid.rules file to add device connected with USB and Bluetooth:

   Device connected using USB:
   ATTRS{idVendor}=="my Vendor ID", ATTRS{idProduct}=="my Product ID", MODE="0666", SYMLINK+="nrf52-desktop-my-dev-name"
   
   Device connected using Bluetooth:
   ATTRS{name}=="Name of my Bluetooth device ", SUBSYSTEMS=="input", MODE="0666", SYMLINK+="nrf52-desktop-my-dev-name"
   

4. If you want to display an LED stream based on sound data, you must also install the additional requirements using the following commands:

   sudo apt-get install portaudio19-dev python3-pyaudio
   pip3 install --user -r requirements_music_led_stream.txt
   

For more detailed information about LED stream functionality, see the Playing LED stream section.

Using the script

See the script’s help by running the following command:

python3 configurator_cli.py -h

Display the list of all configurable devices that are connected to the host by running the script without providing additional arguments:

python3 configurator_cli.py

Perform the selected command on the connected device by using the following command syntax:

python3 configurator_cli.py DEVICE COMMAND_NAME ...

Note

The device can be identified by type, board name, or hardware ID (HW ID). The mapping from device type to board list is defined in NrfHidManager.py.

A command may require additional, command-specific arguments.

Displaying the supported modules and options

The script can show the supported configuration channel modules and options for the connected device. Use the following syntax to show the modules and options:

python3 configurator_cli.py DEVICE show

Configuring device runtime options

The script can pass the configuration values to the linked firmware module using the config command. Use the following syntax to display the list of modules that can have device runtime options configured:

python3 configurator_cli.py DEVICE config -h

Note

The list contains all the configurable modules used by nRF Desktop devices. Make sure that the selected module and option combination is supported by the configured device using show command.

Use the following syntax to display list of options for the given module that can have device runtime options configured:

python3 configurator_cli.py DEVICE config MODULE_NAME -h

Tip

The available configurable modules and options are defined by the nrf/scripts/hid_configurator/modules/module_config.py file.

You can add another configurable module to the file. Use the existing modules as examples. Make sure to also add the application firmware module as a Configuration channel listener, as described on the configuration channel page.

Customize the command with the following variables:

• MODULE_NAME - The third argument is used to pass the name of the module to be configured.

• OPTION_NAME - The fourth argument is used to pass the name of the option.

• VALUE - Optional fifth argument is used to pass a new value of the selected option.

To read the currently set value, pass the name of the module and the option to the config command, without providing any value:

python3 configurator_cli.py DEVICE config MODULE_NAME OPTION_NAME

To write a new value for the selected option, pass the value as the fifth argument:

python3 configurator_cli.py DEVICE config MODULE_NAME OPTION_NAME VALUE

Important

If the module that is a configuration channel listener specifies its variant, you must refer to the module using the following syntax: module_name/variant. For example, the Motion module variant that depends on the motion sensor model requires the following naming convention:

• motion/paw3212

• motion/pmw3360

Performing DFU

The nRF Desktop application supports background DFU (Device Firmware Upgrade). The image is passed to the device while the device is in normal operation. The new image is stored on a dedicated update partition of the flash memory. When the whole image is transmitted, the update process is completed during the next reboot of the device.

If the DFU process is interrupted, it can be resumed using the same image, unless the device restarts. After the device reboots, the process always starts from the beginning. For more information, see nRF Desktop’s Device Firmware Upgrade module. The DFU functionality on the host computer is implemented in the nrf/scripts/hid_configurator/modules/dfu.py file.

The dfu command reads the version of the firmware and the bootloader variant that are running on the device and compares them with the firmware version and the bootloader variant in the update image at the provided path. If the process is to be continued, the script uploads the image data to the device. When the upload is completed, the script reboots the device.

Customize the command with the following variable:

UPDATE_IMAGE_PATH - Path to the DFU update file.

To perform a DFU operation, run the following command:

python3 configurator_cli.py DEVICE dfu UPDATE_IMAGE_PATH

Note

Only devices with Device Firmware Upgrade module support the dfu command.

Rebooting the device

To perform a device reboot operation, run the following command:

python3 configurator_cli.py DEVICE fwreboot

Note

Only devices with Device Firmware Upgrade module support the fwreboot command.

Getting information about the firmware version

To obtain information about the firmware running on the device, run the following command:

python3 configurator_cli.py DEVICE fwinfo

Note

Only devices with Device Firmware Upgrade module support the fwinfo command.

Playing LED stream

The LED stream is a feature of nRF Desktop that allows you to send a stream of color data to be replayed on the device LED. For more information about its implementation, see nRF Desktop’s LED stream module. The LED stream functionality on the host computer is implemented by the following files:

• nrf/scripts/hid_configurator/modules/led_stream.py

• nrf/scripts/hid_configurator/modules/music_led_stream.py.

HID configurator’s led_stream command starts the LED stream playback on the device.

Customize the command with the following variables:

• LED_ID - The third argument to the script is the ID of the LED on which the stream is to be replayed.

• FREQUENCY - The fourth argument to the script is the frequency at which the data is to be generated. The higher the frequency, the more often the colors change.

• --file WAVE_FILE - Optional argument for opening a wave file and using it to generate the stream of colors based on the sound data.

To start the LED stream payback, run the following command:

python3 configurator_cli.py DEVICE led_stream LED_ID FREQUENCY --file WAVE_FILE

Note

Only devices with LED stream module support the led_stream commands.

Implementation details

Every nRF Desktop device must be discovered by the script before it can be configured. The script fetches the hardware ID and board name and scans for the configurable modules. For each module, it obtains the list of available options. For details about options available within each module, see the module documentation.

From the user perspective, the nRF Desktop device is handled in the same way, regardless of it being connected to the host directly or through the nRF Desktop dongle. During the device discovery, the script asks for the nRF Desktop peripherals connected through Bluetooth. If the currently discovered device has connected peripherals, they are discovered and prepared for configuration.

The device discovery procedure is described on the configuration channel documentation page. An example of implementation is available in the scripts/hid_configurator/NrfHidDevice.py file. The device discovery is implemented in the __init__ function of the NrfHidDevice class.

Dependencies

The configuration channel has the following dependencies:

• HIDAPI library

• pyhidapi Python wrapper