Bluetooth LE bond module
Use the Bluetooth® LE bond module to manage the Bluetooth peers and bonds. The module controls the following operations:
Switching between peers (only for nRF Desktop peripheral).
Triggering scanning for new peers (only for nRF Desktop central).
Erasing the Bluetooth bonds.
The nRF Desktop uses the application-specific Bluetooth® LE bond module implementation. The application does not rely on the CAF: Bluetooth LE bond module implementation.
See the Overview: Firmware architecture for more information about the event-based communication in the nRF Desktop application and about how to read this table.
The nRF Desktop device uses the following types of local identities:
Application local identity - Used by the application modules. The currently selected application local identity and its state are presented to the user by the LED state module.
Bluetooth local identity - Used by Zephyr’s Bluetooth API. Every Bluetooth local identity uses its own Bluetooth address and Identity Resolving Key (IRK). From the remote device’s perspective, every Bluetooth local identity of a given peripheral is observed as a separate Bluetooth device.
Both application local identities and Bluetooth local identities are identified using IDs.
Both IDs related to the given Bluetooth peer operation are propagated in
The identity usage depends on the device type:
nRF Desktop central uses only one application local identity and only one Bluetooth local identity (the default ones).
nRF Desktop peripheral uses multiple local identities.
Every application local identity is associated with exactly one Bluetooth local identity.
The Bluetooth® LE bond module stores the mapping from the application local identities to the Bluetooth local identities in the
The mapping changes only after a successful erase advertising.
Only one Bluetooth peer can be bonded with a given local identity.
Also, only one of the application local identities is selected at a time. When the device changes the selected Bluetooth peer, it actually switches its own local identity. The old peer is disconnected by the application, Bluetooth advertising is started, and the new peer connects.
The Bluetooth® LE bond module is implemented as a state machine.
Every transition is triggered by an Application Event Manager event with a predefined value.
Some transitions can be also triggered by internal timeout.
For example, the transition from
STATE_IDLE can be triggered by
selector_event, or an internal timeout.
When the transition occurs:
ble_peer_operation_eventwith the defined
ble_peer_operation_event.opis submitted. For example, when the user confirms the erase advertising, the
ble_peer_operation_eventis submitted with
The currently selected application local identity is updated (if anything changed).
The following diagram shows states and transitions between these states after the module is initialized:
The diagram does not present the states related to module going into standby (
For more information about the standby states, see Standby states.
click_event with a click type that is not included in the schematic will result in cancelling the ongoing operation and returning to
This does not apply to
In this state, all the peer operations triggered by
click_event are disabled.
This is the default state of the module.
When in this state, the following transitions are possible:
Start peer erase with
PEER_OPERATION_ERASEby triggering a
Start erase advertising with
PEER_OPERATION_ERASE_ADVby triggering a
Select next peer with
PEER_OPERATION_SELECTby triggering a
It is also possible to trigger looking for a new peer with
PEER_OPERATION_SCAN_REQUEST with a
click_event of the
CLICK_SHORT click type.
Peer erasing is triggered with the reception of a
click_event of the
Depending on the device type:
The nRF Desktop central erases all bonded peers on the erase confirmation.
The nRF Desktop peripheral starts erase advertising on the erase confirmation.
The erase advertising is used to make sure that the user is able to switch back to the old peer if the new one fails to connect or bond. The peripheral uses an additional Bluetooth local identity that is not associated with any application local identity. The peripheral resets the identity and starts advertising using it.
If a new peer successfully connects, establishes security, and bonds, the current application local identity switches to using the Bluetooth local identity that was used during the erase advertising. The new peer is associated with the currently used application local identity.
After a timeout or on user request, the erase advertising is stopped. The application local identity still uses the Bluetooth local identity that was associated with it before the erase advertising.
The erase advertising timeout can be extended in case a new peer connects. This ensures that a new peer will have time to establish the Bluetooth security level.
The timeout is increased to a bigger value when the passkey authentication is enabled (CONFIG_DESKTOP_BLE_ENABLE_PASSKEY). This gives the end user enough time to enter the passkey.
In this state, the module waits for confirmation before the peer is switched. The connected peer remains unchanged until the selection is confirmed.
The module can go into one of the following dongle states:
STATE_DONGLE- This is the default state of the module when the hardware selector used to select the dongle peer is placed in the CONFIG_DESKTOP_BLE_DONGLE_PEER_SELECTOR_POS position. This state is used for connection with the nRF Desktop dongle.
STATE_DONGLE_STANDBY- The Bluetooth LE bond module is suspended when the dongle peer is selected. See Standby states.
STATE_DONGLE_ERASE_PEER- As Peer erasing (STATE_ERASE_PEER), but for erasing dongle peer.
STATE_DONGLE_ERASE_ADV- As Erase advertising (STATE_ERASE_ADV), but for erasing dongle peer. Similarly, the device waits with erasing the previous peer until it is connected and bonded with a new one.
The module can go into one of the following standby states to make sure that the peer operations are not triggered when the device is suspended by Power manager module:
STATE_DISABLED_STANDBY- The module is suspended before initialization.
STATE_DONGLE_STANDBY- The module is suspended when the dongle peer is selected.
STATE_STANDBY- The module is suspended when other Bluetooth peers are selected.
Going into the standby states and leaving these states happens in reaction to the following events:
power_down_event- On this event, the module goes into one of the standby states and the ongoing peer operation is cancelled.
wake_up_event- On this event, the module returns from the standby state.
You can control the connected peers using the following methods:
You can use both methods, but the hardware selector has precedence.
When configuring the module, you can also enable Default Bluetooth local identity on peripheral.
This feature can be used only by nRF Desktop peripheral devices.
Set the CONFIG_DESKTOP_BLE_DONGLE_PEER_ENABLE option to use the dedicated local identity to connect with the dongle. The last application local identity (the one with the highest ID) is used for this purpose.
The dongle is the nRF Desktop central. If the dongle peer is enabled, the nRF Desktop peripheral uses one of the local identities for the Bluetooth connection with the dongle. This local identity is meant to be paired with the dongle during the production process.
The dongle peer is selected using the Selector module. You must also define the following parameters of the selector used to switch between dongle peer and other Bluetooth LE peers:
CONFIG_DESKTOP_BLE_DONGLE_PEER_SELECTOR_ID - Selector ID.
CONFIG_DESKTOP_BLE_DONGLE_PEER_SELECTOR_POS - Selector position for the dongle peer (when selector is in other position, other Bluetooth peers are selected).
The Bluetooth local identity used for the dongle peer does not provide any special capabilities. All the application modules and the Zephyr Bluetooth stack use it in the same way as any other local identity. The Low Latency Packet Mode can be used with any other local identity.
The only difference is that selecting the dongle peer disables other peer operations.
By default, the default Bluetooth local identity is unused, because it cannot be reset.
You can set CONFIG_DESKTOP_BLE_USE_DEFAULT_ID to make the nRF Desktop peripheral initially use the default Bluetooth local identity for the application local identity with ID
After the successful erase advertising for application local identity with ID
0, the default Bluetooth local identity is switched out and it is no longer used.
The peer bonded with the default Bluetooth local identity is unpaired.
The default identity on given device uses the same Bluetooth address after every programming. This feature can be useful for automatic tests.
To enable erasing dongle peer you have to enable the following options:
CONFIG_DESKTOP_BLE_DONGLE_PEER_ERASE_BOND_BUTTON - If you want to enable erasing peers using buttons.
CONFIG_DESKTOP_BLE_DONGLE_PEER_ERASE_BOND_CONF_CHANNEL - If you want to enable erasing peers using Configuration channel options.
The module provides the following Configuration channel options:
peer_erase- Erase peer for the current local identity. The nRF Desktop central erases all the peers. The nRF Desktop peripheral starts erase advertising.
peer_search- Request scanning for new peripherals. The option is available only for the nRF Desktop central.
Perform a Configuration channel set operation on the selected option to trigger the operation.
The options can be used only if the module is in
Because of this, they cannot be used when the device is suspended by Power manager module.
The device must be woken up from suspended state before the operation is started.
The module is integrated with Zephyr’s Shell module. When the shell is turned on, an additional subcommand set (peers) is added.
This subcommand set contains the following commands:
show - Show bonded peers for every Bluetooth local identity.
remove - Remove bonded peers for the currently selected Bluetooth local identity. The command instantly removes the peers for both nRF Desktop central and nRF Desktop peripheral. It does not start erase advertising.
The module uses Zephyr’s Settings subsystem to store the following data in the non-volatile memory:
Currently selected peer (application local identity)
Mapping between the application local identities and the Bluetooth local identities