Skip to content

Commit 9bafc4f

Browse files
anhmoltb-gent
authored and
eivindj-nordic
committed
doc: libraries: ble_conn_params: add documentation
Document the BLE connection parameter library. Co-authored-by: Bartosz Gentkowski <[email protected]> Signed-off-by: Andreas Moltumyr <[email protected]>
1 parent e122fc6 commit 9bafc4f

File tree

3 files changed

+159
-1
lines changed

3 files changed

+159
-1
lines changed

‎doc/nrf-bm/libraries/ble_conn_params.rst

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
.. _lib_ble_conn_params:
2+
3+
Bluetooth: Connection Parameters
4+
################################
5+
6+
.. contents::
7+
:local:
8+
:depth: 2
9+
10+
The Bluetooth Low Energy® connection parameter library handles parameter negotiation procedures while the device is in a connection and can be used to initiate connection parameter update procedures.
11+
12+
Overview
13+
********
14+
15+
The Bluetooth LE connection parameter library provides functionality for responding to and requesting for:
16+
17+
* Connection parameter update
18+
* ATT MTU exchange
19+
* Data length update (data length extension)
20+
* Radio PHY mode update
21+
22+
The library registers as a Bluetooth LE event observer using the :c:macro:`NRF_SDH_BLE_OBSERVER` macro and handles the relevant Bluetooth LE events from the SoftDevice.
23+
24+
Configuration
25+
*************
26+
27+
The library is enabled and configured entirely using the Kconfig system.
28+
Set the :kconfig:option:`CONFIG_BLE_CONN_PARAMS` Kconfig option to enable the library.
29+
30+
The automatic handling for each of the four procedures can be individually disabled and enabled using the following configuration options:
31+
32+
* :kconfig:option:`CONFIG_BLE_CONN_PARAMS_AUTO_GAP_CONN_PARAM_UPDATE` - Enables the connection parameter update functionality.
33+
* :kconfig:option:`CONFIG_BLE_CONN_PARAMS_AUTO_ATT_MTU` - Enables the ATT MTU exchange functionality.
34+
* :kconfig:option:`CONFIG_BLE_CONN_PARAMS_AUTO_DATA_LENGTH` - Enables the data length update functionality.
35+
* :kconfig:option:`CONFIG_BLE_CONN_PARAMS_AUTO_PHY_UPDATE` - Enables the radio PHY mode update functionality.
36+
37+
All of these functionalities are enabled by default and depend on the :kconfig:option:`CONFIG_BLE_CONN_PARAMS` Kconfig option being enabled.
38+
39+
.. note::
40+
If you wish to disable all or part of the automatic handling, you must handle the respective SoftDevice events and invoke the respective SoftDevice supervisor calls yourself.
41+
42+
Initialization
43+
==============
44+
45+
No initialization is needed, however a callback can be registered with the :c:func:`ble_conn_params_evt_handler_set` function to receive events when the parameters are updated.
46+
47+
Usage
48+
*****
49+
50+
The following section describes the usage of this library in the four scenarios mentioned in `Configuration`_.
51+
52+
Connection parameter update
53+
===========================
54+
55+
You can specify the connection parameters using Kconfig options:
56+
57+
* :kconfig:option:`CONFIG_BLE_CONN_PARAMS_MIN_CONN_INTERVAL` - Minimum connection interval in 1.25 ms units.
58+
* :kconfig:option:`CONFIG_BLE_CONN_PARAMS_MAX_CONN_INTERVAL` - Maximum connection interval in 1.25 ms units.
59+
* :kconfig:option:`CONFIG_BLE_CONN_PARAMS_PERIPHERAL_LATENCY` - Peripheral latency (number of connection events that the peripheral can skip).
60+
* :kconfig:option:`CONFIG_BLE_CONN_PARAMS_MAX_PERIPHERAL_LATENCY_DEVIATION` - Allowed deviation from the specified peripheral latency.
61+
* :kconfig:option:`CONFIG_BLE_CONN_PARAMS_SUP_TIMEOUT` - Supervision timeout in 10 ms units.
62+
* :kconfig:option:`CONFIG_BLE_CONN_PARAMS_MAX_SUP_TIMEOUT_DEVIATION` - Allowed deviation from the specified supervision timeout.
63+
64+
If the device has the peripheral role in a connection and the connection parameters are not within the specified range, then the library will request a renegotiation.
65+
The number of renegotiation attempts is configured by the :kconfig:option:`CONFIG_CONFIG_BLE_CONN_PARAMS_NEGOTIATION_RETRIES` Kconfig option.
66+
67+
If the peripheral and central device cannot agree on a set of connection parameters after the given number of negotiation attempts, and the :kconfig:option:`CONFIG_CONFIG_BLE_CONN_PARAMS_DISCONNECT_ON_FAILURE` Kconfig option is set, the device disconnects automatically.
68+
69+
A connection parameter update procedure can be started using the :c:func:`ble_conn_params_override` function.
70+
71+
When a connection parameter update procedure finishes, the Bluetooth LE connection parameter library event :c:enum:`BLE_CONN_PARAMS_EVT_UPDATED` is raised.
72+
If the update procedure fails, the :c:enum:`BLE_CONN_PARAMS_EVT_REJECTED` event is raised instead.
73+
74+
ATT MTU exchange
75+
================
76+
77+
If a higher ATT MTU size than the default ``23`` is required, the :kconfig:option:`CONFIG_NRF_SDH_BLE_GATT_MAX_MTU_SIZE` Kconfig option must be set to a higher value.
78+
This value is used in the SoftDevice configuration as part of the :c:func:`nrf_sdh_ble_enable` function and is the specified ATT MTU used by this library when doing an ATT MTU exchange.
79+
80+
.. note::
81+
82+
* The largest ATT MTU that can fit within the largest size PDU (data length of 251) is ``247``.
83+
* The largest ATT MTU that can fit within two PDUs with the largest data length is ``498``.
84+
* The largest practical ATT MTU when writing the value of a Bluetooth LE attribute is ``515``.
85+
The maximum size of an attribute value is 512 bytes, plus 3 bytes of ATT header.
86+
* An ATT MTU exchange can only be initiated once.
87+
88+
The :kconfig:option:`CONFIG_BLE_CONN_PARAMS_INITIATE_ATT_MTU_EXCHANGE` Kconfig option can be set to automatically initiate an ATT MTU exchange on connection.
89+
90+
An ATT MTU exchange can be started using the :c:func:`ble_conn_params_att_mtu_set` function.
91+
The current ATT MTU size can be found using the :c:func:`ble_conn_params_att_mtu_get` function.
92+
93+
When an ATT MTU exchange finishes, the Bluetooth LE connection parameter library event :c:enum:`BLE_CONN_PARAMS_EVT_ATT_MTU_UPDATED` is raised.
94+
95+
Data length update
96+
==================
97+
98+
If a PDU data length larger than the default ``27`` is required, the :kconfig:option:`CONFIG_BLE_CONN_PARAMS_DATA_LENGTH` Kconfig option must be set to a higher value in the range of ``27`` to ``251``.
99+
100+
The :kconfig:option:`CONFIG_BLE_CONN_PARAMS_DATA_LENGTH` Kconfig option sets an application-defined upper limit on the negotiated data length.
101+
102+
Note that the SoftDevice ATT MTU configuration (set by the :kconfig:option:`CONFIG_NRF_SDH_BLE_GATT_MAX_MTU_SIZE` Kconfig option) places limitations on the maximum negotiable data length.
103+
This is due to memory efficiency in the SoftDevice.
104+
For instance, to use the definitive max data length of ``251``, the ATT MTU needs to be configured to at least ``247``.
105+
106+
The :kconfig:option:`CONFIG_BLE_CONN_PARAMS_INITIATE_DATA_LENGTH_UPDATE` Kconfig option can be set to automatically initiate a data length update on connection.
107+
108+
A data length update procedure can be started using the :c:func:`ble_conn_params_data_length_set` function.
109+
The current data length (PDU payload) size can be retrieved using the :c:func:`ble_conn_params_data_length_get` function.
110+
111+
When a data length update procedure completes, the Bluetooth LE connection parameter library event :c:enum:`BLE_CONN_PARAMS_EVT_DATA_LENGTH_UPDATED` is raised.
112+
113+
Radio PHY mode
114+
==============
115+
116+
The radio PHY mode defaults to 1 MB per second at the start of a connection.
117+
This can be changed by initiating a GAP radio PHY mode update procedure.
118+
If a specific radio PHY mode is required in connections, one of the following choice options must be enabled:
119+
120+
* :kconfig:option:`CONFIG_BLE_CONN_PARAMS_PHY_AUTO` - The SoftDevice will automatically select the PHY mode.
121+
* :kconfig:option:`CONFIG_BLE_CONN_PARAMS_PHY_1MBPS` - Default speed of 1 MB per second.
122+
* :kconfig:option:`CONFIG_BLE_CONN_PARAMS_PHY_2MBPS` - Higher throughput of 2 MB per second.
123+
* :kconfig:option:`CONFIG_BLE_CONN_PARAMS_PHY_CODED` - Bluetooth LE Coded PHY mode (increased range and reliability of the transmission at the cost of reduced data throughput).
124+
125+
.. note::
126+
The S115 SoftDevice does not support the :kconfig:option:`CONFIG_BLE_CONN_PARAMS_PHY_CODED` Kconfig option.
127+
128+
The :kconfig:option:`CONFIG_BLE_CONN_PARAMS_INITIATE_PHY_UPDATE` Kconfig option can be set to automatically initiate a radio PHY update on connection.
129+
130+
A radio PHY mode update procedure can be started using the :c:func:`ble_conn_params_phy_radio_mode_set` function.
131+
The current radio PHY mode can be retrieved using the :c:func:`ble_conn_params_phy_radio_mode_get` function.
132+
133+
When a radio PHY mode update procedure completes, the Bluetooth LE connection parameter library event :c:enum:`BLE_CONN_PARAMS_EVT_RADIO_PHY_MODE_UPDATED` is raised.
134+
135+
Dependencies
136+
************
137+
138+
This library uses the following |BMshort| libraries:
139+
140+
* SoftDevice - :kconfig:option:`CONFIG_SOFTDEVICE`
141+
* SoftDevice handler - :kconfig:option:`CONFIG_NRF_SDH`
142+
143+
API documentation
144+
*****************
145+
146+
| Header file: :file:`include/ble_conn_params.h`
147+
| Source files: :file:`lib/ble_conn_params/`
148+
149+
.. doxygengroup:: ble_conn_params

‎doc/nrf-bm/libraries/index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,4 +12,4 @@ Here you can find documentation for these libraries, including API documentation
1212
:glob:
1313
:caption: Subpages:
1414

15-
.. Subpages to be added here
15+
*

‎include/ble_conn_params.h

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,13 @@
44
* SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
55
*/
66

7+
/**
8+
* @file
9+
* @defgroup ble_conn_params BLE Connection Parameter Library
10+
* @{
11+
* @brief API for the BLE Connection Parameter library in BareMetal option.
12+
*/
13+
714
#ifndef BLE_CONN_PARAMS_H__
815
#define BLE_CONN_PARAMS_H__
916

@@ -205,3 +212,5 @@ int ble_conn_params_phy_radio_mode_get(uint16_t conn_handle, ble_gap_phys_t *phy
205212
#endif
206213

207214
#endif /* BLE_CONN_PARAMS_H__ */
215+
216+
/** @} */

0 commit comments

Comments
 (0)