Bluetooth LE scanning module

The nRF Desktop’s Bluetooth® LE scanning module is based on the nRF Connect SDK’s Bluetooth LE scanning.

Use the Bluetooth LE scanning module for the following purposes:

  • Apply scanning filters.

  • Control the Bluetooth scanning.

  • Initiate the Bluetooth connections.

This module can only be used by an nRF Desktop central.

Module events

Source Module

Input Event

This Module

Output Event

Sink Module

Bluetooth LE discovery module

ble_discovery_complete_event

ble_scan

Bluetooth LE advertising module

ble_peer_event

Bluetooth LE state module

Bluetooth LE bond module

ble_peer_operation_event

HID forward module

hid_report_event

HID state module

HID Service module

USB state module

Source modules for module_state_event

module_state_event

Power manager module

power_down_event

Bluetooth LE advertising module

wake_up_event

Buttons module

HID forward module

Motion module

Power manager module

Wheel module

ble_peer_search_event

LED state module

module_state_event

Sink modules for module_state_event

Note

See the Application overview for more information about the event-based communication in the nRF Desktop application and about how to read this table.

Configuration

Complete the following steps to enable the Bluetooth LE scanning module:

  1. Complete the basic Bluetooth configuration, as described in the nRF Desktop: Bluetooth documentation. Make sure that both CONFIG_DESKTOP_ROLE_HID_DONGLE and CONFIG_DESKTOP_BT_CENTRAL options are enabled. The Bluetooth LE scanning module is enabled by the CONFIG_DESKTOP_BLE_SCAN_ENABLE Kconfig option which is implied by CONFIG_DESKTOP_BT_CENTRAL Kconfig option together with other application modules. These modules that are required for HID dongle that forwards the data from HID peripherals connected over Bluetooth.

  2. Make sure that the number of scan filters based on the Bluetooth address (CONFIG_BT_SCAN_ADDRESS_CNT) is equal to the number of Bluetooth bonds. The number of Bluetooth bonds is defined by the CONFIG_BT_MAX_PAIRED Kconfig option. The Bluetooth LE scanning module uses the Bluetooth address filters to look for bonded peripherals.

  3. Make sure that the number of scan filters based on the Bluetooth name (CONFIG_BT_SCAN_NAME_CNT) is equal to the number of peripheral types the nRF Desktop central connects to. The Bluetooth LE scanning module uses Bluetooth name filters to look for unbonded peripherals. The peripheral type may be either a mouse or a keyboard.

  4. If you want to limit the number of attempts to connect to a device, you can use the connection attempt filter (CONFIG_BT_SCAN_CONN_ATTEMPTS_FILTER). The Kconfig option is enabled by default. After the predefined number of disconnections or connection failures, the nRF Desktop central will no longer try to connect with the given peripheral device. This is done to prevent connecting and disconnecting with a peripheral in a never-ending loop.

    You can further configure this setting with the following Kconfig options:

    The Bluetooth LE scanning counts all disconnections for a peripheral. The Bluetooth LE scanning module uses bt_scan_conn_attempts_filter_clear() to clear all the connection attempt counters on the following occasions:

    • After a successful peripheral discovery takes place (on ble_discovery_complete_event).

    • When you request scan start or peer erase.

    If filters are not cleared by the application, the Bluetooth Central will be unable to reconnect to the peripheral after exceeding the maximum connection attempts.

  5. Configure the maximum number of bonded mice (CONFIG_DESKTOP_BLE_SCAN_MOUSE_LIMIT) and keyboards (CONFIG_DESKTOP_BLE_SCAN_KEYBOARD_LIMIT) for the nRF Desktop central. By default, the nRF Desktop central connects and bonds with only one mouse and one keyboard.

  6. Define the Bluetooth name filters in the ble_scan_def.h file that is located in the board-specific directory in the application configuration directory. You must define a Bluetooth name filter for every peripheral type the nRF Desktop central connects to. For an example, see configuration/nrf52840dongle_nrf52840/ble_scan_def.h.

    Note

    The Bluetooth device name for given peripheral is defined as the CONFIG_BT_DEVICE_NAME Kconfig option in the peripheral’s configuration. For more detailed information about the Bluetooth advertising configuration in the nRF Desktop application, see the Bluetooth LE advertising module documentation.

  7. Set the CONFIG_DESKTOP_BLE_SCAN_PM_EVENTS to block scanning in the power down mode to decrease the power consumption. The Kconfig option is enabled by default.

By default, the nRF Desktop central always looks for both bonded and unbonded peripherals. You can set the CONFIG_DESKTOP_BLE_NEW_PEER_SCAN_REQUEST option to make the device look for unbonded peripherals only on user request. The request is submitted by Bluetooth LE bond module as ble_peer_operation_event with ble_peer_operation_event.op set to PEER_OPERATION_SCAN_REQUEST.

The central always looks for new bonds also after the bond erase (on ble_peer_operation_event with ble_peer_operation_event.op set to PEER_OPERATION_ERASED). If CONFIG_DESKTOP_BLE_NEW_PEER_SCAN_REQUEST is enabled, you can also set the CONFIG_DESKTOP_BLE_NEW_PEER_SCAN_ON_BOOT option to make the central scan for new peers after every boot.

The following scanning scenarios are possible:

  • If no peripheral is connected, the central scans for the peripheral devices without interruption.

  • If a peripheral is connected, the scanning is triggered periodically. If none of the connected peripherals is in use for at least CONFIG_DESKTOP_BLE_SCAN_START_TIMEOUT_S, the scanning is started.

Scanning module configuration

The Bluetooth LE scanning module relies on Bluetooth LE scanning to perform Bluetooth scanning. The Bluetooth LE scanning module selects CONFIG_BT_SCAN and CONFIG_BT_SCAN_FILTER_ENABLE. Apart from that the following default values are applied:

Scanning not started

The scanning will not start if one of the following conditions occurs:

The number of Bluetooth connections is defined as the CONFIG_BT_MAX_CONN Kconfig option.

Scanning interrupted

The scanning is interrupted if one of the following conditions occurs:

  • A connected peripheral is in use. Scanning in this situation will have a negative impact on user experience.

  • The maximum scan duration specified by CONFIG_DESKTOP_BLE_SCAN_DURATION_S times out.

The scanning is never interrupted if there is no connected Bluetooth peer. If CONFIG_DESKTOP_BLE_SCAN_PM_EVENTS is enabled, the power down event will also interrupt scanning.

Forced scan

The module supports a dedicated forced scan state that prevents interrupting scanning when a connected peripheral is in use. The forced scan speeds up establishing new connections with peripherals, but it also negatively impacts the performance of already connected peripherals. If the CONFIG_DESKTOP_BLE_FORCED_SCAN_DURATION_S Kconfig option is set to a value greater than zero, the module enters the forced scan state after one of the following conditions is met:

  • Boot or wakeup

  • Successful peripheral discovery

  • Peripheral disconnection

  • Connection failure

  • Bond erase

  • Scan request

After the duration that is specified in the CONFIG_DESKTOP_BLE_FORCED_SCAN_DURATION_S Kconfig option, the module switches to regular scanning. The regular scanning can be interrupted by using connected peripherals and times out after the scan duration specified by CONFIG_DESKTOP_BLE_SCAN_DURATION_S if there are peripherals connected over Bluetooth.

Note

The conditions described under Scanning not started prevent the starting of the forced scan.

Implementation details

The Bluetooth LE scanning module stores the following information for every bonded peer:

  • Peripheral Bluetooth address.

  • Peripheral type (mouse or keyboard).

  • Information about Low Latency Packet Mode (LLPM) support.

The module uses Zephyr’s Settings subsystem to store the information in the non-volatile memory. This information is required to filter out unbonded devices, because the nRF Desktop central connects and bonds only with a defined number of mice and keyboards.

Bluetooth connection interval

After the scan filter match, the following happens:

  1. The scanning is stopped and the nRF Connect SDK’s Bluetooth LE scanning automatically establishes the Bluetooth connection with the peripheral. The initial Bluetooth connection interval is set by default to 7.5 ms, that is to the shortest connection interval allowed by the Bluetooth specification.

  2. The peer discovery is started.

  3. After the Bluetooth LE discovery module completes the peer discovery, the Bluetooth LE connection parameters module receives the ble_discovery_complete_event and updates the Bluetooth connection interval. At this point, the scanning can be restarted.

Important

If the dongle supports Low Latency Packet Mode (CONFIG_CAF_BLE_USE_LLPM) and more than one Bluetooth connection (CONFIG_BT_MAX_CONN), a 10-ms connection interval is used instead of 7.5 ms. This is done to avoid Bluetooth scheduling issues that may lead to HID input report rate drops and disconnections.