Bluetooth: Human Interface Device Service Mouse

The Peripheral HIDS mouse sample demonstrates how to use the Human Interface Device Service (HIDS) to implement a mouse input device that you can connect to your computer.

Requirements

The sample supports the following development kits:

Simple board variantsMCUboot board variants

The following board variants do not have DFU capabilities:

S115:

Hardware platform	PCA	Board target
nRF54L15 DK	PCA10156	bm_nrf54l15dk/nrf54l15/cpuapp/s115_softdevice
nRF54L15 DK (emulating nRF54L10)	PCA10156	bm_nrf54l15dk/nrf54l10/cpuapp/s115_softdevice
nRF54L15 DK (emulating nRF54L05)	PCA10156	bm_nrf54l15dk/nrf54l05/cpuapp/s115_softdevice
nRF54LM20 DK	PCA10184	bm_nrf54lm20dk/nrf54lm20a/cpuapp/s115_softdevice
nRF54LS05 DK	PCA10214	bm_nrf54ls05dk/nrf54ls05b/cpuapp/s115_softdevice
nRF54LS05 DK (emulating nRF54LS05A)	PCA10214	bm_nrf54ls05dk/nrf54ls05a/cpuapp/s115_softdevice
nRF54LV10 DK	PCA10188	bm_nrf54lv10dk/nrf54lv10a/cpuapp/s115_softdevice

S145:

Hardware platform	PCA	Board target
nRF54L15 DK	PCA10156	bm_nrf54l15dk/nrf54l15/cpuapp/s145_softdevice
nRF54L15 DK (emulating nRF54L10)	PCA10156	bm_nrf54l15dk/nrf54l10/cpuapp/s145_softdevice
nRF54L15 DK (emulating nRF54L05)	PCA10156	bm_nrf54l15dk/nrf54l05/cpuapp/s145_softdevice
nRF54LM20 DK	PCA10184	bm_nrf54lm20dk/nrf54lm20a/cpuapp/s145_softdevice
nRF54LS05 DK	PCA10214	bm_nrf54ls05dk/nrf54ls05b/cpuapp/s145_softdevice
nRF54LS05 DK (emulating nRF54LS05A)	PCA10214	bm_nrf54ls05dk/nrf54ls05a/cpuapp/s145_softdevice
nRF54LV10 DK	PCA10188	bm_nrf54lv10dk/nrf54lv10a/cpuapp/s145_softdevice

Overview

The sample uses the buttons on the 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.

Allow list

By default, the sample does not use allow-list advertising, which means that any nearby device can connect and bond with the device. Bonded devices are stored in internal non-volatile memory (NVM) and are remembered across power cycles.

You can enable allow-list advertising by setting the CONFIG_BLE_ADV_USE_ALLOW_LIST Kconfig option to y in the base Kconfig fragment (prj.conf). When enabled, only previously bonded devices are allowed to reconnect, which allows faster reconnection and prevents unknown devices from connecting.

When allow-list advertising is enabled and you want to add a new bonded device, existing bonds must first be deleted. This can be done through user interaction, as described in the user interface section.

User interface

Button 0:

Simulate mouse movement to the left.

When pairing with authentication, press this button to confirm the passkey shown in the COM listener and complete pairing with the other device. See Testing.

Button 1:

Simulate mouse movement upwards.

Keep the button pressed while resetting the board to delete bonding information for all peers stored on the device.

When pairing with authentication, press this button to reject the passkey shown in the COM listener to prevent pairing with the other device.

Button 2:

Simulate mouse movement to the right.

Button 3:

Simulate mouse movement downwards.

LED 0:

Lit when the device is initialized.

LED 1:

Lit when a device is connected.

Security

The sample integrates Bluetooth: Peer Manager (backed by Bare Metal Zephyr Memory Storage (BM_ZMS) for persistent storage) to support pairing and bonding.

The following security parameters are configured:

Peer Manager security parameters

Parameter	Value	Effect
Bonding	True	Supports storing of pairing information (bonding data).
MITM protection	False	Man-in-the-middle protection not required.
LE Secure Connections	True	Supports LESC pairing.
I/O capabilities	Display and Yes/No entry	Determines local I/O capability, actual pairing method depends on negotiation with peer.

This sample configures the following services and their characteristics with these specific operation modes and required security levels:

Service	Characteristic	Operation	Required security level	Effect
HID Service	Protocol Mode	Read/Write	Encryption, no authentication	Connection must be encrypted to switch the mouse between Boot Protocol Mode and Report Protocol Mode.
	Input Reports (Buttons, Movement, Advanced Buttons)	Read/Write/Notify	Encryption, no authentication	Connection must be encrypted to send button presses, cursor movement, and advanced button presses, to the host.
	Report Map	Read	Encryption, no authentication	Connection must be encrypted to read the report format the host needs to parse mouse reports.
	Boot Mouse Input Report	Read/Write/Notify	Encryption, no authentication	Connection must be encrypted to send button and movement data with this characteristic when in the boot protocol mode.
	HID Information	Read	Encryption, no authentication	Connection must be encrypted to read the HID version and device capability flags.
	HID Control Point	Write	Encryption, no authentication	Connection must be encrypted to suspend or resume HID report notifications, for example when the host enters low power mode.
Device Information Service	All characteristics	Read	Open, no security	Any connected device can read device information such as the manufacturer name and firmware version.
Battery Service	Battery Level	Read/Notify	Open, no security	Any connected device can read the battery level and subscribe to battery level notifications.

See Testing for the pairing and bonding steps.

Building and running

This sample can be found under samples/bluetooth/ble_hids_mouse/ in the Bare Metal folder structure.

For details on how to create, configure, and program a sample, see Getting Started with the samples.

Testing

You can test this sample using a computer or a smartphone.

1. Compile and program the application.

2. In the Serial Terminal, using the Serial Terminal app or Visual Studio Code, observe that the BLE HIDS Mouse sample initialized message is printed.

3. Observe that the Advertising as nRF_BM_HIDS_MOUSE message is printed. You can configure the advertising name using the CONFIG_SAMPLE_BLE_DEVICE_NAME Kconfig option. For information on how to do this, see Configuring Kconfig.

4. On your computer or mobile phone, open the Bluetooth settings and scan for advertising devices. If the device is not advertising, reset the board with the Reset Board option in Visual Studio Code or by pressing the reset button on the development kit.

5. Connect to your device.

   The terminal output in Visual Studio Code indicates Peer connected.

   After having connected, your computer or mobile phone may attempt to pair or bond with your device in order to encrypt the link.

   You may be prompted to compare or enter a passkey as part of the authentication step. If prompted, provide the passkey from the terminal output, or confirm that the passkey is correct by pressing Button 0 on the kit.

6. Observe that the device is detected as a mouse, and you can move the mouse by pressing the buttons on the DK.