.. _nrf_desktop_bluetooth_guide: nRF Desktop: Bluetooth ###################### .. contents:: :local: :depth: 2 The nRF Desktop devices use :ref:`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 :ref:`nrf:app_event_manager` events. The :option:`CONFIG_DESKTOP_BT` Kconfig option enables support for Bluetooth connectivity in the nRF Desktop. Specific Bluetooth configurations and application modules are selected or implied according to the HID device role. Apart from that, the defaults of Bluetooth-related Kconfig options are aligned with the nRF Desktop use case. The nRF Desktop devices come in the following roles: * HID peripheral (:option:`CONFIG_DESKTOP_ROLE_HID_PERIPHERAL`) that works as a Bluetooth Peripheral (:option:`CONFIG_DESKTOP_BT_PERIPHERAL`) * Support only the Bluetooth Peripheral role (:kconfig:option:`CONFIG_BT_PERIPHERAL`). * Handle only one Bluetooth LE connection at a time. * Use more than one Bluetooth local identity. * HID dongle (:option:`CONFIG_DESKTOP_ROLE_HID_DONGLE`) that works as a Bluetooth Central (:option:`CONFIG_DESKTOP_BT_CENTRAL`) * Support only the Bluetooth Central role (:kconfig:option:`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. The nRF Desktop peripheral configurations that enable `Fast Pair`_ support use a slightly different Bluetooth configuration. This is needed to improve the user experience. See :ref:`nrf_desktop_bluetooth_guide_fast_pair` for more details. .. note:: An nRF Desktop device cannot support both central and peripheral roles. Common configuration and application modules ******************************************** Some Bluetooth-related :ref:`configuration options ` (including :ref:`nrf_desktop_bluetooth_guide_configuration_ll` in a separate section) and :ref:`application modules ` are common for every nRF Desktop device. .. _nrf_desktop_bluetooth_guide_configuration: 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. * :kconfig:option:`CONFIG_BT_MAX_PAIRED` * nRF Desktop central: The maximum number of paired devices is greater than or equal to the maximum number of simultaneously connected peers. The :kconfig:option:`CONFIG_BT_MAX_PAIRED` is by default set to :option:`CONFIG_DESKTOP_HID_DONGLE_BOND_COUNT`. * 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. * :kconfig:option:`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. * :kconfig:option:`CONFIG_BT_MAX_CONN` * nRF Desktop central: This option is set to the maximum number of simultaneously connected devices. The :kconfig:option:`CONFIG_BT_MAX_CONN` is by default set to :option:`CONFIG_DESKTOP_HID_DONGLE_CONN_COUNT`. * nRF Desktop peripheral: The default value (one) is used. .. note:: After changing the number of Bluetooth peers for the nRF Desktop peripheral device, update the LED effects used to represent the Bluetooth connection state. For details, see :ref:`nrf_desktop_led_state`. .. _nrf_desktop_bluetooth_guide_configuration_ll: Link Layer configuration options ================================ The nRF Desktop devices use the SoftDevice Link Layer (:kconfig:option:`CONFIG_BT_LL_SOFTDEVICE`). This Link Layer supports: * Bluetooth Shorter Connection Intervals (SCI) required by HID Shorter Connection Intervals (HID SCI). This enables connection intervals as short as 750 µs. * Low Latency Packet Mode (LLPM) - A proprietary Bluetooth extension from Nordic Semiconductor enabling 1000 µs connection intervals. For the nRF Desktop central, make sure to also update the default max connection event length (:kconfig:option:`CONFIG_BT_CTLR_SDC_MAX_CONN_EVENT_LEN_DEFAULT`). The suggested values are: * ``750`` for configurations enabling HID SCI support (:option:`CONFIG_DESKTOP_HID_FORWARD_HID_SCI_ENABLE`). This is needed to achieve a connection interval of 750 µs. * ``3000`` for configurations enabling the LLPM (:kconfig:option:`CONFIG_BT_CTLR_SDC_LLPM`). For these configurations, the :kconfig:option:`CONFIG_CAF_BLE_USE_LLPM` is also enabled by default. The value of ``3000`` allows to avoid scheduling conflicts in the Bluetooth Link Layer. Such conflicts could lead to a drop in HID input report rate or a disconnection. If the nRF Desktop central supports LLPM and more than one simultaneous Bluetooth connection, it also uses 10 ms connection interval instead of 7.5 ms. Setting the value of :kconfig:option:`CONFIG_BT_CTLR_SDC_MAX_CONN_EVENT_LEN_DEFAULT` to ``3000`` also enables the nRF Desktop central to exchange data with up to three standard Bluetooth LE peripherals during every connection interval (every 10 ms). * ``2500`` for configurations without HID SCI nor LLPM support. The central will use only standard Bluetooth LE connection parameters with the lowest available connection interval of 7.5 ms. With this value, the nRF Desktop central can exchange the data with up to three Bluetooth LE peripherals during every 7.5-ms connection interval. Using the value of ``3000`` for more than two simultaneous Bluetooth LE connections will result in a lower HID input report rate. .. _nrf_desktop_bluetooth_guide_modules: Application modules =================== Every nRF Desktop device that enables Bluetooth must handle connections and manage bonds. These features are implemented by the following modules: * :ref:`nrf_desktop_ble_state` - Enables Bluetooth and LLPM (if supported), and handles Zephyr connection callbacks. * :ref:`nrf_desktop_ble_bond` - Manages Bluetooth bonds and local identities. 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 Desktop devices enable the :kconfig:option:`CONFIG_BT_SETTINGS` Kconfig option. When this option is enabled, the application is responsible for calling the :c:func:`settings_load` function - this is handled by the :ref:`nrf_desktop_settings_loader`. .. _nrf_desktop_bluetooth_guide_peripheral: 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: * HID Service - Handled in the :ref:`nrf_desktop_hids`. This also includes handling HID SCI as part of HID GATT Service if the :option:`CONFIG_DESKTOP_HIDS_SCI_ENABLE` Kconfig option is enabled. * Battery Service - Handled in the :ref:`nrf_desktop_bas`. * Device Information Service - Implemented in Zephyr and enabled with the :kconfig:option:`CONFIG_BT_DIS` Kconfig option. The device identifiers are configured according to the common :ref:`nrf_desktop_hid_device_identifiers` by default. You can configure it using Kconfig options with the ``CONFIG_BT_DIS`` prefix. The nRF Desktop peripherals must also define a dedicated GATT Service that is used to provide the following information: * Information on whether the device can use the LLPM Bluetooth connection parameters. * Hardware ID of the peripheral. The GATT Service is implemented by the :ref:`nrf_desktop_dev_descr`. Apart from the GATT Services, an nRF Desktop peripheral device must enable and configure the following application modules: * :ref:`nrf_desktop_ble_adv` - Controls the Bluetooth advertising. * :ref:`nrf_desktop_ble_latency` - Controls data exchange latencies and power consumption. It keeps the connection latency low when the :ref:`nrf_desktop_config_channel` is used or when either the :ref:`nrf_desktop_ble_smp` or :ref:`nrf_desktop_dfu_mcumgr` receives an update image. This is done to ensure quick data transfer. It also handles HID Shorter Connection Intervals (SCI) mode change requests when the :option:`CONFIG_DESKTOP_HIDS_SCI_ENABLE` Kconfig option is enabled. .. _nrf_desktop_bluetooth_guide_fast_pair: Fast Pair ========= The nRF Desktop peripheral can be built with Google `Fast Pair`_ support. The configurations that enable Fast Pair are specified in the files with filenames ending with the ``fast_pair`` and ``release_fast_pair`` suffixes. .. note:: Both the Fast Pair integration in the nRF Desktop and the Fast Pair support in the |NCS| for the HID use case are :ref:`experimental `. See :ref:`nrf:ug_bt_fast_pair` for details. These configurations support multiple bonds for each Bluetooth local identity (:kconfig:option:`CONFIG_CAF_BLE_STATE_MAX_LOCAL_ID_BONDS` is set to ``3``) and erase advertising (:option:`CONFIG_DESKTOP_BLE_PEER_ERASE`), but Bluetooth peer selection (:option:`CONFIG_DESKTOP_BLE_PEER_SELECT`) is disabled. You can now pair with your other hosts without switching the peripheral back in pairing mode (without triggering the erase advertising). The nRF Desktop peripheral that integrates Fast Pair behaves as follows: * The dongle peer does not use the Fast Pair advertising payload. * The bond erase operation is enabled for the dongle peer. This lets you change the bonded Bluetooth Central. * If the dongle peer (:option:`CONFIG_DESKTOP_BLE_DONGLE_PEER_ENABLE`) is enabled, the `Swift Pair`_ payload is, by default, included only for the mentioned peer. In the Fast Pair configurations, the dongle peer is intended to be used for all of the peers that are not Fast Pair Seekers. * If the used Bluetooth local identity has no bonds, the device advertises in pairing mode, and the Fast Pair discoverable advertising is used. This allows to pair with the nRF Desktop device using both Fast Pair and normal Bluetooth pairing flows. This advertising payload is also used during the erase advertising. * If the used Bluetooth local identity already has a bond, the device is no longer in the pairing mode and the Fast Pair not discoverable advertising is used. This allows to pair only with the Fast Pair Seekers linked to Google Accounts that are already associated with the nRF Desktop device. In this mode, the device rejects normal Bluetooth pairing by default (:option:`CONFIG_DESKTOP_FAST_PAIR_LIMIT_NORMAL_PAIRING` option is enabled). The Fast Pair UI indication is hidden after the Provider reaches :kconfig:option:`CONFIG_CAF_BLE_STATE_MAX_LOCAL_ID_BONDS` bonded peers on the used local identity. * The :ref:`nrf_desktop_factory_reset` is enabled by default if the :ref:`nrf_desktop_config_channel` is supported by the device. The factory reset operation removes both Fast Pair and Bluetooth non-volatile data. The factory reset operation is triggered using the configuration channel. After a successful erase advertising procedure, the peripheral removes all of the bonds of a given Bluetooth local identity. Apart from that, the following changes are applied in configurations that support Fast Pair: * The :kconfig:option:`SB_CONFIG_BT_FAST_PAIR_MODEL_ID` and :kconfig:option:`SB_CONFIG_BT_FAST_PAIR_ANTI_SPOOFING_PRIVATE_KEY` Kconfig options are set in the sysbuild configuration to generate the hex file with Fast Pair provisioning data. These Kconfig options are configured to represent the Nordic device models that are intended for demonstration purposes. * The :kconfig:option:`CONFIG_BT_FAST_PAIR` Kconfig option is enabled in the main (default) image configuration. For more details about enabling Fast Pair for your application, see the :ref:`nrf:ug_bt_fast_pair_prerequisite_ops_kconfig` section in the Fast Pair integration guide. * The :ref:`memory layout ` is modified to introduce a dedicated non-volatile memory partition used to store the Fast Pair provisioning data. * Bluetooth privacy feature (:kconfig:option:`CONFIG_BT_PRIVACY`) is enabled. * The fast and slow advertising intervals defined in the :ref:`nrf_desktop_ble_adv` are aligned with Fast Pair expectations. * The Bluetooth advertising filter accept list (:kconfig:option:`CONFIG_CAF_BLE_ADV_FILTER_ACCEPT_LIST`) is disabled to allow Fast Pair Seekers other than the bonded one to connect outside of the pairing mode. * The security failure timeout (:option:`CONFIG_DESKTOP_BLE_SECURITY_FAIL_TIMEOUT_S`) is longer to prevent disconnections during the Fast Pair procedure. * Passkey authentication is not used in the available nRF Desktop configurations. Currently, Fast Pair does not support devices that use a screen or keyboard for Bluetooth authentication. * TX power correction value (:kconfig:option:`CONFIG_BT_ADV_PROV_TX_POWER_CORRECTION_VAL`) is configured to align the TX power included in the advertising data with the Fast Pair expectations. See :ref:`nrf:ug_bt_fast_pair` for detailed information about Fast Pair support in the |NCS|. Bluetooth Central ***************** The nRF Desktop central must implement Bluetooth scanning and handle the GATT operations. The central must also control the Bluetooth connection parameters. For connections that do not use HID SCI, the central adjusts them directly. For HID SCI connections, the central requests the proper HID SCI mode from the connected peripherals. These features are implemented by the following application modules: * :ref:`nrf_desktop_ble_scan` - Controls the Bluetooth scanning. * :ref:`nrf_desktop_ble_conn_params` - Controls the Bluetooth connection parameters and reacts on latency update requests received from the connected peripherals. For HID SCI connections, the module negotiates connection parameters using HID SCI modes. * :ref:`nrf_desktop_ble_discovery` - Discovers and reads the GATT Characteristics from the connected peripheral. * :ref:`nrf_desktop_hid_forward` - Subscribes for HID reports from the Bluetooth Peripherals (HID over GATT) and forwards data using application events. When HID SCI is enabled, the module uses the HOGP client to send HID SCI mode change requests and report mode changes from peripherals. The connection parameter policy is handled by the :ref:`nrf_desktop_ble_conn_params`.