Bluetooth: Peripheral HIDS mouse
The Peripheral HIDS mouse sample demonstrates how to use the GATT Human Interface Device (HID) Service to implement a mouse input device that you can connect to your computer. This sample also shows how to perform directed advertising.
Note
Apart from HID samples, the nRF Connect SDK provides a complete reference application design of Human Interface Device (HID). Depending on the configuration, the application can work as a desktop mouse, gaming mouse, keyboard, or connection dongle. It supports connection over Bluetooth® LE, USB, or both. For details, see the nRF Desktop documentation.
Requirements
The sample supports the following development kits:
Hardware platforms |
PCA |
Board name |
|
|---|---|---|---|
nRF54LV10 DK |
PCA10188 |
|
|
nRF54LS05 DK |
PCA10214 |
nrf54ls05dk |
|
PCA10184 |
|
||
nRF54LC10 DK |
PCA10226 |
nrf54lc10dk |
|
PCA10156 |
|
||
PCA10156 |
|
||
PCA10156 |
|
||
PCA10175 |
|
||
PCA10095 |
|
||
PCA10040 |
|
||
PCA10056 |
|
For more security, it is recommended to use the */ns variant of the board target.
When built for this variant, the sample is configured to compile and run as a non-secure application using security by separation.
Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.
Overview
The sample uses the buttons on a development kit to simulate the movement of a mouse. The four buttons simulate movement to the left, up, right, and down, respectively. Mouse clicks are not simulated.
This sample exposes the HID GATT Service. It uses a report map for a generic mouse.
User interface
- Button 1:
Simulate moving the mouse pointer five pixels to the left.
If Man-In-The-Middle (MITM) protection based on passkey display (
CONFIG_SAMPLE_BT_HIDS_SECURITY_MITM) is enabled, you can press this button while pairing to confirm the passkey value that is printed on the COM listener to pair with the other device.- Button 2:
Simulate moving the mouse pointer five pixels up.
If Man-In-The-Middle (MITM) protection based on passkey display (
CONFIG_SAMPLE_BT_HIDS_SECURITY_MITM) is enabled, you can press this button while pairing to reject the passkey value that is printed on the COM listener to prevent pairing with the other device.- Button 3:
Simulate moving the mouse pointer five pixels to the right.
- Button 4:
Simulate moving the mouse pointer five pixels down.
- Button 0:
Simulate moving the mouse pointer five pixels to the left.
If Man-In-The-Middle (MITM) protection based on passkey display (
CONFIG_SAMPLE_BT_HIDS_SECURITY_MITM) is enabled, you can press this button while pairing to confirm the passkey value that is printed on the COM listener to pair with the other device.- Button 1:
Simulate moving the mouse pointer five pixels up.
If Man-In-The-Middle (MITM) protection based on passkey display (
CONFIG_SAMPLE_BT_HIDS_SECURITY_MITM) is enabled, you can press this button while pairing to reject the passkey value that is printed on the COM listener to prevent pairing with the other device.- Button 2:
Simulate moving the mouse pointer five pixels to the right.
- Button 3:
Simulate moving the mouse pointer five pixels down.
Configuration
See Configuring and building for information about how to permanently or temporarily change the configuration.
Configuration options
The following sample-specific Kconfig options are used in this sample (defined in samples/bluetooth/peripheral_hids_mouse/Kconfig):
- CONFIG_SAMPLE_BT_HIDS_SECURITY
(bool) Bluetooth LE security
Enable Bluetooth LE security support.
- CONFIG_SAMPLE_BT_HIDS_SECURITY_MITM
(bool) Passkey display MITM protection
Enable displaying passkey for Man-In-The-Middle (MITM) protection. Implementation uses the “printk” function to display the passkey.
- CONFIG_SAMPLE_BT_DIRECTED_ADVERTISING
(bool) Directed advertising
- CONFIG_SAMPLE_BT_HIDS_CONTINUOUS_REPORT_SENDING
(bool) Continuous report sending
Enable the continuous report sending feature in the peripheral HIDS sample. Hold down a button for more than 2 seconds to enable continuous report sending.
- CONFIG_SAMPLE_BT_HIDS_CONTINUOUS_REPORT_SENDING_PREPARE_DISTANCE_US
(int) Prepare distance for continuous report sending
The time before the next Bluetooth LE connection event when the report should be prepared. Only supported if the platform supports radio notification connection callbacks. The default value 400 us was arbitrarily chosen, so that the preparation fits in short intervals below 500 us.
See the following sections for more details related to the options.
Bluetooth LE security
By default, the sample enables Bluetooth LE security support through the CONFIG_SAMPLE_BT_HIDS_SECURITY sample-specific Kconfig option.
This allows the sample to encrypt connections and create Bluetooth bonds.
The option also implies Bluetooth privacy (CONFIG_BT_PRIVACY).
You can disable the sample-specific Kconfig option to disable support for Bluetooth security.
Man-In-The-Middle (MITM) protection
By default, the sample also enables MITM protection based on passkey display (CONFIG_SAMPLE_BT_HIDS_SECURITY_MITM).
This is done to prevent Man-In-The-Middle attacks through authentication.
Since the printk() function is used to display the passkey, the feature depends on CONFIG_PRINTK.
HID GATT characteristic attributes permissions
Configurations of the sample require Bluetooth link encryption to access the HID Service (CONFIG_BT_HIDS_DEFAULT_PERM_RW_ENCRYPT).
The HID Service specification does not require encryption, but Bluetooth link encryption is required by the HID over GATT Profile Specification.
The Bluetooth LE security support (CONFIG_SAMPLE_BT_HIDS_SECURITY) is required to encrypt a link.
Some of the HID hosts may not subscribe for HID input reports or disconnect the Bluetooth link if Bluetooth LE security is not supported.
If you disable Bluetooth LE security support (CONFIG_SAMPLE_BT_HIDS_SECURITY), you need to allow access to HID Service without encryption (CONFIG_BT_HIDS_DEFAULT_PERM_RW) too.
This imposes a security risk of, among others, passive eavesdropping of the communication between HID device and HID host.
Because of that it is not recommended for production.
Note
If MITM protection based on passkey display is enabled (CONFIG_SAMPLE_BT_HIDS_SECURITY_MITM) and you want to pair the device with a computer running MacOS, set the CONFIG_BT_HIDS_DEFAULT_PERM_RW_AUTHEN Kconfig option to y.
Continuous report sending
The CONFIG_SAMPLE_BT_HIDS_CONTINUOUS_REPORT_SENDING Kconfig option enables sending HID input reports informing about mouse motion at roughly one for each connection interval.
The feature is enabled if a button is pressed and held for more than two seconds.
It is disabled as soon as all buttons are released.
For best results, only allow a single central connection (set both CONFIG_BT_MAX_CONN and CONFIG_BT_HIDS_MAX_CLIENT_COUNT to 1).
Otherwise, more reports will be skipped or delayed due to other radio traffic, such as advertising events or interfering connection events from other centrals.
Bluetooth direct advertising
By default, the sample enables the CONFIG_SAMPLE_BT_DIRECTED_ADVERTISING sample-specific Kconfig option that enables using Bluetooth direct advertising.
The feature depends on Bluetooth LE security support (CONFIG_SAMPLE_BT_HIDS_SECURITY).
This feature changes the way advertising works in comparison to the other Bluetooth Low Energy samples.
When the device wants to advertise, it starts with directed advertising provided that it has bonding information.
When there is at least one connected peer, low-duty cycle directed advertising is used.
Otherwise, high-duty cycle directed advertising is used.
The low-duty cycle directed advertising is used because scheduling high-duty directed advertising might cause problems with reacting to Bluetooth LE connection events from connected peers, which can result in disconnections.
Each low-duty cycle directed advertising attempt has an application-specified timeout of two seconds.
The high-duty cycle directed advertising has a timeout of 1.28 seconds defined by the Bluetooth specification.
If the timeout occurs, the device starts directed advertising to the next bonded peer.
If all bonding information is used and there is still no connection, the regular advertising starts.
HID Shorter Connection Intervals (SCI)
If you build the sample with -DFILE_SUFFIX=hid_sci, support for HID Shorter Connection Intervals (SCI) is enabled.
This feature allows the device to enter a specific HID SCI mode when requested by the central.
The HID SCI modes are sets of connection parameters that you can use to optimize the connection for a specific use case.
For example, the FAST mode is used to achieve the shortest connection intervals, allowing for minimum latency and maximum throughput.
Building and running
This sample can be found under samples/bluetooth/peripheral_hids_mouse in the nRF Connect SDK folder structure.
For more security, it is recommended to use the */ns variant of the board target (see the Requirements section above.)
When built for this variant, the sample is configured to compile and run as a non-secure application using security by separation.
Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.
To build the sample, follow the instructions in Building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.
Note
When building repository applications in the SDK repositories, building with sysbuild is enabled by default.
If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.
When building this sample with Sysbuild for an SoC that has a network core, the IPC radio firmware is automatically applied to the build.
The IPC radio is one of the companion components in the nRF Connect SDK and allows to use the radio peripheral from another core in a multicore device.
If needed, you can modify the IPC radio configuration in the prj.conf source file in the sample’s sysbuild/ipc_radio directory.
To build the sample with HID SCI support, use -DFILE_SUFFIX=hid_sci.
Bluetooth RPC build
To build this sample with the Bluetooth Low Energy Remote Procedure Call library, add the following parameters:
set the SNIPPET option to
nordic-bt-rpc,set the FILE_SUFFIX option to
bt_rpc.
west build -b board_target -S nordic-bt-rpc -- -DFILE_SUFFIX=bt_rpc
Bluetooth Low Energy app build
To build this sample in the configuration variant that is compatible with Bluetooth Low Energy app, disable the following Bluetooth features:
Privacy (
CONFIG_BT_PRIVACY) - The Bluetooth Low Energy app does not fully support the Bluetooth Privacy feature by disallowing distribution of the Identity Resolving Key (IRK) during the pairing procedure.High-duty directed advertising (
CONFIG_SAMPLE_BT_DIRECTED_ADVERTISING) - High-duty directed advertising with 3.75 ms advertising interval and 1.28 s duration prevents the subsequent undirected advertising from being reported in the scanning list of Bluetooth Low Energy app . As a result, it is only possible to connect to the target DK during the very short interval of high-duty directed advertising.
To build the sample in the compatible configuration, use the following command:
west build -b board_target -- -DCONFIG_SAMPLE_BT_DIRECTED_ADVERTISING=n -DCONFIG_BT_PRIVACY=n
Note
If you want to combine this build configuration with the Bluetooth RPC build, use the following command:
west build -b board_target -S nordic-bt-rpc -- -DFILE_SUFFIX=bt_rpc -DCONFIG_SAMPLE_BT_DIRECTED_ADVERTISING=n -DCONFIG_BT_PRIVACY=n -Dipc_radio_CONFIG_BT_PRIVACY=n
Memory footprint usage
The sample supports a dedicated release configuration that disables debug features like logs or assertions.
You can use the configuration to verify the memory footprint of the sample as it is closer to the configuration used by a final product.
Note
The release configuration does not emit logs (and printk() messages).
Because of that, it cannot enable passkey display MITM protection (CONFIG_SAMPLE_BT_HIDS_SECURITY_MITM).
Use the following command to build the sample in release configuration:
west build -b board_target -- -DFILE_SUFFIX=release
To get the memory footprint, run the following commands from the sample directory (nrf/samples/bluetooth/peripheral_hids_mouse):
west build -d <build_dir>/peripheral_hids_mouse -t rom_report
west build -d <build_dir>/peripheral_hids_mouse -t ram_report
For more information, see the Zephyr’s Optimization Tools documentation.
Testing
After programming the sample to your development kit, you can test it either by connecting the development kit as a mouse device to a Microsoft Windows computer or by connecting to it with the Bluetooth Low Energy app of the nRF Connect for Desktop.
Testing with a Microsoft Windows computer
To test with a Microsoft Windows computer that has a Bluetooth radio, complete the following steps:
Power on your development kit.
On your Windows computer, search for Bluetooth devices and connect to the device named “NCS HIDS mouse”.
Push Button 1 on the kit. Observe that the mouse pointer on the computer moves to the left.
Push Button 2. Observe that the mouse pointer on the computer moves upward.
Push Button 3. Observe that the mouse pointer on the computer moves to the right.
Push Button 4. Observe that the mouse pointer on the computer moves downward.
Disconnect the computer from the device by removing the device from the computer’s devices list.
Power on your development kit.
On your Windows computer, search for Bluetooth devices and connect to the device named “NCS HIDS mouse”.
Push Button 0 on the kit. Observe that the mouse pointer on the computer moves to the left.
Push Button 1. Observe that the mouse pointer on the computer moves upward.
Push Button 2. Observe that the mouse pointer on the computer moves to the right.
Push Button 3. Observe that the mouse pointer on the computer moves downward.
Disconnect the computer from the device by removing the device from the computer’s devices list.
Testing with Bluetooth Low Energy app
To test with Bluetooth Low Energy app, complete the following steps:
Note
To execute the testing steps below, you must build the sample in the configuration that is compatible with Bluetooth Low Energy app. See the Bluetooth Low Energy app build section to learn how to build a compatible sample configuration.
Power on your development kit.
Start nRF Connect for Desktop.
Open the Bluetooth Low Energy app.
Connect to the device from the app. The device is advertising as “NCS HIDS mouse”
Optionally, bond to the device. Click the Settings button for the device in the app, select Pair, check Perform Bonding, and click Pair. Optionally check Enable MITM protection to pair with MITM protection and use a button on the device to confirm or reject passkey value.
Click Match in the app. Wait until the bond is established before you continue.
Observe that the services of the connected device are shown.
Click Play for all HID Report characteristics.
Push Button 1 on the kit. Observe that a notification is received on one of the HID Report characteristics, containing the value
FB0F00.Mouse motion reports contain data with an X-translation and a Y-translation. These are transmitted as 12-bit signed integers. The format used for mouse reports is the following byte array, where LSB/MSB is the least/most significant bit:
[8 LSB (X), 4 LSB (Y) | 4 MSB(X), 8 MSB(Y)].Therefore,
FB0F00denotes an X-translation of FFB = -5 (two’s complement format), which means a movement of five pixels to the left, and a Y-translation of 000 = 0.Push Button 2. Observe that the value
00B0FFis received on the same HID Report characteristic.Push Button 3. Observe that the value
050000is received on the same HID Report characteristic.Push Button 4. Observe that the value
005000is received on the same HID Report characteristic.Disconnect the device in the Bluetooth Low Energy app of nRF Connect for Desktop. Observe that no new notifications are received and the device is advertising.
As bond information is preserved by the Bluetooth Low Energy app, you can immediately reconnect to the device by clicking the Connect button again.
Power on your development kit.
Start nRF Connect for Desktop.
Open the Bluetooth Low Energy app.
Connect to the device from the app. The device is advertising as “NCS HIDS mouse”
Optionally, bond to the device. Click the Settings button for the device in the app, select Pair, check Perform Bonding, and click Pair. Optionally check Enable MITM protection to pair with MITM protection and use a button on the device to confirm or reject passkey value.
Click Match in the app. Wait until the bond is established before you continue.
Observe that the services of the connected device are shown.
Click Play for all HID Report characteristics.
Push Button 0 on the kit. Observe that a notification is received on one of the HID Report characteristics, containing the value
FB0F00.Mouse motion reports contain data with an X-translation and a Y-translation. These are transmitted as 12-bit signed integers. The format used for mouse reports is the following byte array, where LSB/MSB is the least/most significant bit:
[8 LSB (X), 4 LSB (Y) | 4 MSB(X), 8 MSB(Y)].Therefore,
FB0F00denotes an X-translation of FFB = -5 (two’s complement format), which means a movement of five pixels to the left, and a Y-translation of 000 = 0.Push Button 1. Observe that the value
00B0FFis received on the same HID Report characteristic.Push Button 2. Observe that the value
050000is received on the same HID Report characteristic.Push Button 3. Observe that the value
005000is received on the same HID Report characteristic.Disconnect the device in the Bluetooth Low Energy app of nRF Connect for Desktop. Observe that no new notifications are received and the device is advertising.
As bond information is preserved by the Bluetooth Low Energy app, you can immediately reconnect to the device by clicking the Connect button again.
Dependencies
This sample uses the following nRF Connect SDK libraries:
In addition, it uses the following Zephyr libraries:
include/zephyr/types.hlib/libc/minimal/include/assert.hlib/libc/minimal/include/errno.hinclude/sys/printk.hinclude/sys/byteorder.hAPI:
include/bluetooth/bluetooth.hinclude/bluetooth/hci.hinclude/bluetooth/conn.hinclude/bluetooth/uuid.hinclude/bluetooth/gatt.hsamples/bluetooth/gatt/bas.h
The sample also uses the following secure firmware component: