CAF: Bluetooth LE state module

The Bluetooth® LE state module is a core Bluetooth module in Common Application Framework (CAF). When enabled for an application, the Bluetooth® LE state module is responsible for the following actions:

• Enabling Bluetooth (bt_enable())

• Handling Bluetooth connection callbacks (bt_conn_cb)

• Propagating information about the connection state and parameters with Event Manager events

The Bluetooth® LE state module does not handle Bluetooth advertising or scanning. If you want to use these functionalities to connect over Bluetooth LE, use CAF’s Bluetooth LE advertising module or Zephyr’s Bluetooth API directly.

Note

CAF assumes that Bluetooth Peripheral device supports only one simultaneous connection and can have up to one bond per Bluetooth local identity.

Configuration

To use the module, you must enable the following Kconfig options:

• CONFIG_BT

• CONFIG_BT_SMP - This option enables Security Manager Protocol support. The Bluetooth® LE state module on Bluetooth Peripheral requires at least the connection security level 2 (encryption).

• CONFIG_CAF_BLE_STATE - This option enables the Bluetooth® LE state module and selects the CONFIG_CAF_BLE_COMMON_EVENTS Kconfig option, which enables Bluetooth LE common events in CAF.

The following Kconfig options are also available for this module:

• CONFIG_CAF_BLE_STATE_EXCHANGE_MTU - This option can be used for GATT client (CONFIG_BT_GATT_CLIENT) to set the Maximum Transmission Unit (MTU) to the maximum possible size that the buffers can hold. This option is enabled by default.

• CONFIG_CAF_BLE_USE_LLPM - This option enables the Low Latency Packet Mode (LLPM). This option is enabled by default and depends on CONFIG_BT_CTLR_SDC_LLPM and CONFIG_BT_LL_SOFTDEVICE.

Implementation details

The Bluetooth® LE state module is used by both Bluetooth Peripheral and Bluetooth Central devices.

In line with other CAF modules, the Bluetooth® LE state module uses Event Manager events to broadcast changes in connection state and parameters. It also updates connection reference counts to ensure the connections remain valid as long as application modules use them.

Connection state change

The module propagates information about the connection state changes using ble_peer_event. In this event, ble_peer_event.id is a pointer to the connection object and ble_peer_event.state is the connection state.

Bluetooth connection state handling in CAF

The connection state can be set to one of the following values:

• PEER_STATE_CONNECTED - Bluetooth stack successfully connected to the remote peer.

• PEER_STATE_CONN_FAILED - Bluetooth stack failed to connect the remote peer.

• PEER_STATE_SECURED - Bluetooth stack set the connection security to at least level 2 (that is, encryption and no authentication).

• PEER_STATE_DISCONNECTED - Bluetooth stack disconnected from the remote peer.

Other application modules can call bt_conn_disconnect() to disconnect the remote peer. The application module can submit a ble_peer_event with ble_peer_event.state set to PEER_STATE_DISCONNECTING to let other application modules prepare for the disconnection.

On Bluetooth Peripheral, the Bluetooth® LE state module requires the connection security level 2. If the connection security level 2 is not established, the Peripheral disconnects.

Connection parameter change

The module submits a ble_peer_conn_params_event to inform other application modules about connection parameter update requests and connection parameter updates.

The Bluetooth® LE state module rejects the connection parameter update request in Zephyr’s callback. An application module can handle the ble_peer_conn_params_event and update the connection parameters.

Connection references

The Bluetooth® LE state module keeps references to bt_conn objects to ensure that they remain valid when other application modules access them. When a new connection is established, the module calls bt_conn_ref() to increase the object reference counter. After ble_peer_event about disconnection or connection failure is received by all other application modules, the Bluetooth® LE state module decrements the bt_conn object by using bt_conn_unref().

Behavior with SoftDevice Link Layer

If Nordic Semiconductor’s SoftDevice Bluetooth LE Link Layer is selected (CONFIG_BT_LL_SOFTDEVICE) and the CONFIG_CAF_BLE_USE_LLPM option is enabled, the Bluetooth® LE state module sends a Bluetooth HCI command to enable the LLPM when Bluetooth is ready.

If the SoftDevice Link Layer is selected, the Bluetooth® LE state module also sets the TX power for connections. The TX power is set according to Zephyr’s Kconfig options related to selecting the default TX power. This is necessary because the mentioned Kconfig options are not automatically applied by the Bluetooth stack if the SoftDevice Link Layer is selected.