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 Application 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.

Configuration

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

• CONFIG_BT

• CONFIG_BT_SMP - This option enables Security Manager Protocol support.

• 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). If the Bluetooth controller is enabled as part of the application, this option is enabled by default and depends on CONFIG_BT_CTLR_SDC_LLPM. Otherwise, this option is disabled and can be enabled manually. Before enabling the option manually, make sure that the used Bluetooth controller supports the LLPM.

• CONFIG_CAF_BLE_STATE_SECURITY_REQ - This option enables setting the security level 2 for a Bluetooth LE connection automatically, right after the connection is established. The security level 2 or higher enables connection encryption. The device disconnects if establishing the connection security level 2 fails.

• CONFIG_CAF_BLE_STATE_MAX_LOCAL_ID_BONDS - This option allows to specify the maximum number of allowed bonds per Bluetooth local identity for a Bluetooth Peripheral (CONFIG_BT_PERIPHERAL). If a local identity is already bonded with the maximum number of allowed bonds, new peers are disconnected right after Bluetooth connection is established.

• CONFIG_CAF_BLE_FRAME_SPACE_EVENTS - This option causes the module to emit the ble_peer_frame_space_updated_event. This event is used to inform other application modules about frame space changes and failed frame space update requests. It depends on CONFIG_BT_FRAME_SPACE_UPDATE. This option is enabled by default.

• CONFIG_CAF_BLE_PHY_UPDATED_EVENTS - This option causes the module to emit the ble_peer_phy_updated_event. This event is used to inform other application modules about PHY changes. It depends on CONFIG_BT_USER_PHY_UPDATE. This option is enabled by default.

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 Application 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.

Bluetooth connection state handling in CAF

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.

Connection parameter change

Connection parameter changes are handled differently depending on whether Shorter Connection Intervals (SCI) are used for a given Bluetooth LE connection. SCI support is controlled by the CONFIG_BT_SHORTER_CONNECTION_INTERVALS Kconfig option. The peer must also support SCI for it to be used on a connection.

Shorter Connection Intervals unused

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.

Shorter Connection Intervals used

If you are using SCI, update the connection parameters with the connection rate API (bt_conn_le_conn_rate_request()). The module submits a ble_peer_sci_conn_rate_event to inform other application modules about connection rate changes. The event is also emitted when a connection rate update request fails. In this case, it contains the status code of the failed request. No event is emitted when a connection rate update request is made, because the Bluetooth stack does not provide a callback for this when SCI is enabled.

A Bluetooth LE Central can use the bt_conn_le_conn_rate_set_defaults() API to limit the accepted connection rate range.

Note

When the CONFIG_BT_SHORTER_CONNECTION_INTERVALS Kconfig option is enabled, the non-SCI callbacks remain available. They are called if you use the non-SCI (connection parameter update) API to update the connection parameters. However, do not use the non-SCI API if both the device and peer support the SCI.

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().

Low Latency Packet Mode

If 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. The LLPM is a proprietary Bluetooth extension from Nordic Semiconductor that requires using Nordic Semiconductor’s SoftDevice Bluetooth LE Link Layer.