Line data Source code
1 1 : /** @file
2 : * @brief Bluetooth connection handling
3 : */
4 :
5 : /*
6 : * Copyright (c) 2015-2016 Intel Corporation
7 : *
8 : * SPDX-License-Identifier: Apache-2.0
9 : */
10 : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_CONN_H_
11 : #define ZEPHYR_INCLUDE_BLUETOOTH_CONN_H_
12 :
13 : /**
14 : * @brief Connection management
15 : * @defgroup bt_conn Connection management
16 : * @ingroup bluetooth
17 : * @{
18 : */
19 :
20 : #include <stdbool.h>
21 : #include <stdint.h>
22 :
23 : #include <zephyr/bluetooth/bluetooth.h>
24 : #include <zephyr/bluetooth/hci_types.h>
25 : #include <zephyr/bluetooth/addr.h>
26 : #include <zephyr/bluetooth/gap.h>
27 : #include <zephyr/bluetooth/direction.h>
28 : #include <zephyr/sys/iterable_sections.h>
29 :
30 : #ifdef __cplusplus
31 : extern "C" {
32 : #endif
33 :
34 : /** Opaque type representing a connection to a remote device */
35 : struct bt_conn;
36 :
37 : /** Connection parameters for LE connections */
38 1 : struct bt_le_conn_param {
39 0 : uint16_t interval_min;
40 0 : uint16_t interval_max;
41 0 : uint16_t latency;
42 0 : uint16_t timeout;
43 : };
44 :
45 : /** @brief Initialize connection parameters
46 : *
47 : * @param int_min Minimum Connection Interval (N * 1.25 ms)
48 : * @param int_max Maximum Connection Interval (N * 1.25 ms)
49 : * @param lat Connection Latency
50 : * @param to Supervision Timeout (N * 10 ms)
51 : */
52 1 : #define BT_LE_CONN_PARAM_INIT(int_min, int_max, lat, to) \
53 : { \
54 : .interval_min = (int_min), \
55 : .interval_max = (int_max), \
56 : .latency = (lat), \
57 : .timeout = (to), \
58 : }
59 :
60 : /** Helper to declare connection parameters inline
61 : *
62 : * @param int_min Minimum Connection Interval (N * 1.25 ms)
63 : * @param int_max Maximum Connection Interval (N * 1.25 ms)
64 : * @param lat Connection Latency
65 : * @param to Supervision Timeout (N * 10 ms)
66 : */
67 1 : #define BT_LE_CONN_PARAM(int_min, int_max, lat, to) \
68 : ((struct bt_le_conn_param[]) { \
69 : BT_LE_CONN_PARAM_INIT(int_min, int_max, lat, to) \
70 : })
71 :
72 : /** Default LE connection parameters:
73 : * Connection Interval: 30-50 ms
74 : * Latency: 0
75 : * Timeout: 4 s
76 : */
77 1 : #define BT_LE_CONN_PARAM_DEFAULT \
78 : BT_LE_CONN_PARAM(BT_GAP_INIT_CONN_INT_MIN, BT_GAP_INIT_CONN_INT_MAX, 0, \
79 : BT_GAP_MS_TO_CONN_TIMEOUT(4000))
80 :
81 : /** Connection PHY information for LE connections */
82 1 : struct bt_conn_le_phy_info {
83 0 : uint8_t tx_phy; /** Connection transmit PHY */
84 1 : uint8_t rx_phy; /** Connection receive PHY */
85 : };
86 :
87 : /** Connection PHY options */
88 1 : enum {
89 : /** Convenience value when no options are specified. */
90 : BT_CONN_LE_PHY_OPT_NONE = 0,
91 :
92 : /** LE Coded using S=2 coding preferred when transmitting. */
93 : BT_CONN_LE_PHY_OPT_CODED_S2 = BIT(0),
94 :
95 : /** LE Coded using S=8 coding preferred when transmitting. */
96 : BT_CONN_LE_PHY_OPT_CODED_S8 = BIT(1),
97 : };
98 :
99 : /** Preferred PHY parameters for LE connections */
100 1 : struct bt_conn_le_phy_param {
101 1 : uint16_t options; /**< Connection PHY options. */
102 1 : uint8_t pref_tx_phy; /**< Bitmask of preferred transmit PHYs */
103 1 : uint8_t pref_rx_phy; /**< Bitmask of preferred receive PHYs */
104 : };
105 :
106 : /** Initialize PHY parameters
107 : *
108 : * @param _pref_tx_phy Bitmask of preferred transmit PHYs.
109 : * @param _pref_rx_phy Bitmask of preferred receive PHYs.
110 : */
111 1 : #define BT_CONN_LE_PHY_PARAM_INIT(_pref_tx_phy, _pref_rx_phy) \
112 : { \
113 : .options = BT_CONN_LE_PHY_OPT_NONE, \
114 : .pref_tx_phy = (_pref_tx_phy), \
115 : .pref_rx_phy = (_pref_rx_phy), \
116 : }
117 :
118 : /** Helper to declare PHY parameters inline
119 : *
120 : * @param _pref_tx_phy Bitmask of preferred transmit PHYs.
121 : * @param _pref_rx_phy Bitmask of preferred receive PHYs.
122 : */
123 1 : #define BT_CONN_LE_PHY_PARAM(_pref_tx_phy, _pref_rx_phy) \
124 : ((struct bt_conn_le_phy_param []) { \
125 : BT_CONN_LE_PHY_PARAM_INIT(_pref_tx_phy, _pref_rx_phy) \
126 : })
127 :
128 : /** Only LE 1M PHY */
129 1 : #define BT_CONN_LE_PHY_PARAM_1M BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_1M, \
130 : BT_GAP_LE_PHY_1M)
131 :
132 : /** Only LE 2M PHY */
133 1 : #define BT_CONN_LE_PHY_PARAM_2M BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_2M, \
134 : BT_GAP_LE_PHY_2M)
135 :
136 : /** Only LE Coded PHY. */
137 1 : #define BT_CONN_LE_PHY_PARAM_CODED BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_CODED, \
138 : BT_GAP_LE_PHY_CODED)
139 :
140 : /** All LE PHYs. */
141 1 : #define BT_CONN_LE_PHY_PARAM_ALL BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_1M | \
142 : BT_GAP_LE_PHY_2M | \
143 : BT_GAP_LE_PHY_CODED, \
144 : BT_GAP_LE_PHY_1M | \
145 : BT_GAP_LE_PHY_2M | \
146 : BT_GAP_LE_PHY_CODED)
147 :
148 : /** Connection data length information for LE connections */
149 1 : struct bt_conn_le_data_len_info {
150 : /** Maximum Link Layer transmission payload size in bytes. */
151 1 : uint16_t tx_max_len;
152 : /** Maximum Link Layer transmission payload time in us. */
153 1 : uint16_t tx_max_time;
154 : /** Maximum Link Layer reception payload size in bytes. */
155 1 : uint16_t rx_max_len;
156 : /** Maximum Link Layer reception payload time in us. */
157 1 : uint16_t rx_max_time;
158 : };
159 :
160 : /** Connection data length parameters for LE connections */
161 1 : struct bt_conn_le_data_len_param {
162 : /** Maximum Link Layer transmission payload size in bytes. */
163 1 : uint16_t tx_max_len;
164 : /** Maximum Link Layer transmission payload time in us. */
165 1 : uint16_t tx_max_time;
166 : };
167 :
168 : /** Initialize transmit data length parameters
169 : *
170 : * @param _tx_max_len Maximum Link Layer transmission payload size in bytes.
171 : * @param _tx_max_time Maximum Link Layer transmission payload time in us.
172 : */
173 1 : #define BT_CONN_LE_DATA_LEN_PARAM_INIT(_tx_max_len, _tx_max_time) \
174 : { \
175 : .tx_max_len = (_tx_max_len), \
176 : .tx_max_time = (_tx_max_time), \
177 : }
178 :
179 : /** Helper to declare transmit data length parameters inline
180 : *
181 : * @param _tx_max_len Maximum Link Layer transmission payload size in bytes.
182 : * @param _tx_max_time Maximum Link Layer transmission payload time in us.
183 : */
184 1 : #define BT_CONN_LE_DATA_LEN_PARAM(_tx_max_len, _tx_max_time) \
185 : ((struct bt_conn_le_data_len_param[]) { \
186 : BT_CONN_LE_DATA_LEN_PARAM_INIT(_tx_max_len, _tx_max_time) \
187 : })
188 :
189 : /** Default LE data length parameters. */
190 1 : #define BT_LE_DATA_LEN_PARAM_DEFAULT \
191 : BT_CONN_LE_DATA_LEN_PARAM(BT_GAP_DATA_LEN_DEFAULT, \
192 : BT_GAP_DATA_TIME_DEFAULT)
193 :
194 : /** Maximum LE data length parameters. */
195 1 : #define BT_LE_DATA_LEN_PARAM_MAX \
196 : BT_CONN_LE_DATA_LEN_PARAM(BT_GAP_DATA_LEN_MAX, \
197 : BT_GAP_DATA_TIME_MAX)
198 :
199 : /** Connection subrating parameters for LE connections */
200 1 : struct bt_conn_le_subrate_param {
201 : /** Minimum subrate factor. */
202 1 : uint16_t subrate_min;
203 : /** Maximum subrate factor. */
204 1 : uint16_t subrate_max;
205 : /** Maximum Peripheral latency in units of subrated connection intervals. */
206 1 : uint16_t max_latency;
207 : /** Minimum number of underlying connection events to remain active
208 : * after a packet containing a Link Layer PDU with a non-zero Length
209 : * field is sent or received.
210 : */
211 1 : uint16_t continuation_number;
212 : /** Connection Supervision timeout (N * 10 ms).
213 : * If using @ref bt_conn_le_subrate_set_defaults, this is the
214 : * maximum supervision timeout allowed in requests by a peripheral.
215 : */
216 1 : uint16_t supervision_timeout;
217 : };
218 :
219 : /** Subrating information for LE connections */
220 1 : struct bt_conn_le_subrating_info {
221 : /** Connection subrate factor. */
222 1 : uint16_t factor;
223 : /** Number of underlying connection events to remain active after
224 : * a packet containing a Link Layer PDU with a non-zero Length
225 : * field is sent or received.
226 : */
227 1 : uint16_t continuation_number;
228 : };
229 :
230 : /** Updated subrating connection parameters for LE connections */
231 1 : struct bt_conn_le_subrate_changed {
232 : /** HCI Status from LE Subrate Changed event.
233 : * The remaining parameters will be unchanged if status is not
234 : * BT_HCI_ERR_SUCCESS.
235 : */
236 1 : uint8_t status;
237 : /** Connection subrate factor. */
238 1 : uint16_t factor;
239 : /** Number of underlying connection events to remain active after
240 : * a packet containing a Link Layer PDU with a non-zero Length
241 : * field is sent or received.
242 : */
243 1 : uint16_t continuation_number;
244 : /** Peripheral latency in units of subrated connection intervals. */
245 1 : uint16_t peripheral_latency;
246 : /** Connection Supervision timeout (N * 10 ms). */
247 1 : uint16_t supervision_timeout;
248 : };
249 :
250 : /** Connection Type */
251 1 : enum __packed bt_conn_type {
252 : /** LE Connection Type */
253 : BT_CONN_TYPE_LE = BIT(0),
254 : /** BR/EDR Connection Type */
255 : BT_CONN_TYPE_BR = BIT(1),
256 : /** SCO Connection Type */
257 : BT_CONN_TYPE_SCO = BIT(2),
258 : /** ISO Connection Type */
259 : BT_CONN_TYPE_ISO = BIT(3),
260 : /** All Connection Type */
261 : BT_CONN_TYPE_ALL = BT_CONN_TYPE_LE | BT_CONN_TYPE_BR |
262 : BT_CONN_TYPE_SCO | BT_CONN_TYPE_ISO,
263 : };
264 :
265 : /** Supported AA-Only RTT precision. */
266 1 : enum bt_conn_le_cs_capability_rtt_aa_only {
267 : /** AA-Only RTT variant is not supported. */
268 : BT_CONN_LE_CS_RTT_AA_ONLY_NOT_SUPP = 0,
269 : /** 10ns time-of-flight accuracy. */
270 : BT_CONN_LE_CS_RTT_AA_ONLY_10NS,
271 : /** 150ns time-of-flight accuracy. */
272 : BT_CONN_LE_CS_RTT_AA_ONLY_150NS,
273 : };
274 :
275 : /** Supported Sounding Sequence RTT precision. */
276 1 : enum bt_conn_le_cs_capability_rtt_sounding {
277 : /** Sounding Sequence RTT variant is not supported. */
278 : BT_CONN_LE_CS_RTT_SOUNDING_NOT_SUPP = 0,
279 : /** 10ns time-of-flight accuracy. */
280 : BT_CONN_LE_CS_RTT_SOUNDING_10NS,
281 : /** 150ns time-of-flight accuracy. */
282 : BT_CONN_LE_CS_RTT_SOUNDING_150NS,
283 : };
284 :
285 : /** Supported Random Payload RTT precision. */
286 1 : enum bt_conn_le_cs_capability_rtt_random_payload {
287 : /** Random Payload RTT variant is not supported. */
288 : BT_CONN_LE_CS_RTT_RANDOM_PAYLOAD_NOT_SUPP = 0,
289 : /** 10ns time-of-flight accuracy. */
290 : BT_CONN_LE_CS_RTT_RANDOM_PAYLOAD_10NS,
291 : /** 150ns time-of-flight accuracy. */
292 : BT_CONN_LE_CS_RTT_RANDOM_PAYLOAD_150NS,
293 : };
294 :
295 : /** Remote channel sounding capabilities for LE connections supporting CS */
296 1 : struct bt_conn_le_cs_capabilities {
297 : /** Number of CS configurations */
298 1 : uint8_t num_config_supported;
299 : /** Maximum number of consecutive CS procedures.
300 : *
301 : * When set to zero, indicates support for both fixed and indefinite
302 : * numbers of CS procedures before termination.
303 : */
304 1 : uint16_t max_consecutive_procedures_supported;
305 : /** Number of antennas. */
306 1 : uint8_t num_antennas_supported;
307 : /** Maximum number of antenna paths. */
308 1 : uint8_t max_antenna_paths_supported;
309 : /** Initiator role. */
310 1 : bool initiator_supported;
311 : /** Reflector role. */
312 1 : bool reflector_supported;
313 : /** Mode-3 */
314 1 : bool mode_3_supported;
315 : /** RTT AA-Only */
316 1 : enum bt_conn_le_cs_capability_rtt_aa_only rtt_aa_only_precision;
317 : /** RTT Sounding */
318 1 : enum bt_conn_le_cs_capability_rtt_sounding rtt_sounding_precision;
319 : /** RTT Random Payload */
320 1 : enum bt_conn_le_cs_capability_rtt_random_payload rtt_random_payload_precision;
321 : /** Number of CS steps needed to achieve the
322 : * accuracy requirements for RTT AA Only.
323 : *
324 : * Set to 0 if RTT AA Only isn't supported.
325 : */
326 1 : uint8_t rtt_aa_only_n;
327 : /** Number of CS steps needed to achieve the
328 : * accuracy requirements for RTT Sounding.
329 : *
330 : * Set to 0 if RTT Sounding isn't supported
331 : */
332 1 : uint8_t rtt_sounding_n;
333 : /** Number of CS steps needed to achieve the
334 : * accuracy requirements for RTT Random Payload.
335 : *
336 : * Set to 0 if RTT Random Payload isn't supported.
337 : */
338 1 : uint8_t rtt_random_payload_n;
339 : /** Phase-based normalized attack detector metric
340 : * when a CS_SYNC with sounding sequence is received.
341 : */
342 1 : bool phase_based_nadm_sounding_supported;
343 : /** Phase-based normalized attack detector metric
344 : * when a CS_SYNC with random sequence is received.
345 : */
346 1 : bool phase_based_nadm_random_supported;
347 : /** CS_SYNC LE 2M PHY. */
348 1 : bool cs_sync_2m_phy_supported;
349 : /** CS_SYNC LE 2M 2BT PHY. */
350 1 : bool cs_sync_2m_2bt_phy_supported;
351 : /** Subfeature: CS with no Frequency Actuation Error. */
352 1 : bool cs_without_fae_supported;
353 : /** Subfeature: Channel Selection Algorithm #3c */
354 1 : bool chsel_alg_3c_supported;
355 : /** Subfeature: Phase-based Ranging from RTT sounding sequence. */
356 1 : bool pbr_from_rtt_sounding_seq_supported;
357 : /** Optional T_IP1 time durations during CS steps.
358 : *
359 : * - Bit 0: 10 us
360 : * - Bit 1: 20 us
361 : * - Bit 2: 30 us
362 : * - Bit 3: 40 us
363 : * - Bit 4: 50 us
364 : * - Bit 5: 60 us
365 : * - Bit 6: 80 us
366 : */
367 1 : uint16_t t_ip1_times_supported;
368 : /** Optional T_IP2 time durations during CS steps.
369 : *
370 : * - Bit 0: 10 us
371 : * - Bit 1: 20 us
372 : * - Bit 2: 30 us
373 : * - Bit 3: 40 us
374 : * - Bit 4: 50 us
375 : * - Bit 5: 60 us
376 : * - Bit 6: 80 us
377 : */
378 1 : uint16_t t_ip2_times_supported;
379 : /** Optional T_FCS time durations during CS steps.
380 : *
381 : * - Bit 0: 15 us
382 : * - Bit 1: 20 us
383 : * - Bit 2: 30 us
384 : * - Bit 3: 40 us
385 : * - Bit 4: 50 us
386 : * - Bit 5: 60 us
387 : * - Bit 6: 80 us
388 : * - Bit 7: 100 us
389 : * - Bit 8: 120 us
390 : */
391 1 : uint16_t t_fcs_times_supported;
392 : /** Optional T_PM time durations during CS steps.
393 : *
394 : * - Bit 0: 10 us
395 : * - Bit 1: 20 us
396 : */
397 1 : uint16_t t_pm_times_supported;
398 : /** Time in microseconds for the antenna switch period of the CS tones. */
399 1 : uint8_t t_sw_time;
400 : /** Supported SNR levels used in RTT packets.
401 : *
402 : * - Bit 0: 18dB
403 : * - Bit 1: 21dB
404 : * - Bit 2: 24dB
405 : * - Bit 3: 27dB
406 : * - Bit 4: 30dB
407 : */
408 1 : uint8_t tx_snr_capability;
409 : };
410 :
411 : /** Remote FAE Table for LE connections supporting CS */
412 1 : struct bt_conn_le_cs_fae_table {
413 0 : int8_t *remote_fae_table;
414 : };
415 :
416 : /** Channel sounding main mode */
417 1 : enum bt_conn_le_cs_main_mode {
418 : /** Mode-1 (RTT) */
419 : BT_CONN_LE_CS_MAIN_MODE_1 = BT_HCI_OP_LE_CS_MAIN_MODE_1,
420 : /** Mode-2 (PBR) */
421 : BT_CONN_LE_CS_MAIN_MODE_2 = BT_HCI_OP_LE_CS_MAIN_MODE_2,
422 : /** Mode-3 (RTT and PBR) */
423 : BT_CONN_LE_CS_MAIN_MODE_3 = BT_HCI_OP_LE_CS_MAIN_MODE_3,
424 : };
425 :
426 : /** Channel sounding sub mode */
427 1 : enum bt_conn_le_cs_sub_mode {
428 : /** Unused */
429 : BT_CONN_LE_CS_SUB_MODE_UNUSED = BT_HCI_OP_LE_CS_SUB_MODE_UNUSED,
430 : /** Mode-1 (RTT) */
431 : BT_CONN_LE_CS_SUB_MODE_1 = BT_HCI_OP_LE_CS_SUB_MODE_1,
432 : /** Mode-2 (PBR) */
433 : BT_CONN_LE_CS_SUB_MODE_2 = BT_HCI_OP_LE_CS_SUB_MODE_2,
434 : /** Mode-3 (RTT and PBR) */
435 : BT_CONN_LE_CS_SUB_MODE_3 = BT_HCI_OP_LE_CS_SUB_MODE_3,
436 : };
437 :
438 : /** Channel sounding role */
439 1 : enum bt_conn_le_cs_role {
440 : /** CS initiator role */
441 : BT_CONN_LE_CS_ROLE_INITIATOR,
442 : /** CS reflector role */
443 : BT_CONN_LE_CS_ROLE_REFLECTOR,
444 : };
445 :
446 : /** Channel sounding RTT type */
447 1 : enum bt_conn_le_cs_rtt_type {
448 : /** RTT AA only */
449 : BT_CONN_LE_CS_RTT_TYPE_AA_ONLY = BT_HCI_OP_LE_CS_RTT_TYPE_AA_ONLY,
450 : /** RTT with 32-bit sounding sequence */
451 : BT_CONN_LE_CS_RTT_TYPE_32_BIT_SOUNDING = BT_HCI_OP_LE_CS_RTT_TYPE_32BIT_SOUND,
452 : /** RTT with 96-bit sounding sequence */
453 : BT_CONN_LE_CS_RTT_TYPE_96_BIT_SOUNDING = BT_HCI_OP_LE_CS_RTT_TYPE_96BIT_SOUND,
454 : /** RTT with 32-bit random sequence */
455 : BT_CONN_LE_CS_RTT_TYPE_32_BIT_RANDOM = BT_HCI_OP_LE_CS_RTT_TYPE_32BIT_RAND,
456 : /** RTT with 64-bit random sequence */
457 : BT_CONN_LE_CS_RTT_TYPE_64_BIT_RANDOM = BT_HCI_OP_LE_CS_RTT_TYPE_64BIT_RAND,
458 : /** RTT with 96-bit random sequence */
459 : BT_CONN_LE_CS_RTT_TYPE_96_BIT_RANDOM = BT_HCI_OP_LE_CS_RTT_TYPE_96BIT_RAND,
460 : /** RTT with 128-bit random sequence */
461 : BT_CONN_LE_CS_RTT_TYPE_128_BIT_RANDOM = BT_HCI_OP_LE_CS_RTT_TYPE_128BIT_RAND,
462 : };
463 :
464 : /** Channel sounding PHY used for CS sync */
465 1 : enum bt_conn_le_cs_sync_phy {
466 : /** LE 1M PHY */
467 : BT_CONN_LE_CS_SYNC_1M_PHY = BT_HCI_OP_LE_CS_CS_SYNC_1M,
468 : /** LE 2M PHY */
469 : BT_CONN_LE_CS_SYNC_2M_PHY = BT_HCI_OP_LE_CS_CS_SYNC_2M,
470 : /** LE 2M 2BT PHY */
471 : BT_CONN_LE_CS_SYNC_2M_2BT_PHY = BT_HCI_OP_LE_CS_CS_SYNC_2M_2BT,
472 : };
473 :
474 : /** Channel sounding channel selection type */
475 1 : enum bt_conn_le_cs_chsel_type {
476 : /** Use Channel Selection Algorithm #3b for non-mode-0 CS steps */
477 : BT_CONN_LE_CS_CHSEL_TYPE_3B = BT_HCI_OP_LE_CS_TEST_CHSEL_TYPE_3B,
478 : /** Use Channel Selection Algorithm #3c for non-mode-0 CS steps */
479 : BT_CONN_LE_CS_CHSEL_TYPE_3C = BT_HCI_OP_LE_CS_TEST_CHSEL_TYPE_3C,
480 : };
481 :
482 : /** Channel sounding channel sequence shape */
483 1 : enum bt_conn_le_cs_ch3c_shape {
484 : /** Use Hat shape for user-specified channel sequence */
485 : BT_CONN_LE_CS_CH3C_SHAPE_HAT = BT_HCI_OP_LE_CS_TEST_CH3C_SHAPE_HAT,
486 : /** Use X shape for user-specified channel sequence */
487 : BT_CONN_LE_CS_CH3C_SHAPE_X = BT_HCI_OP_LE_CS_TEST_CH3C_SHAPE_X,
488 : };
489 :
490 : /** Channel sounding configuration */
491 1 : struct bt_conn_le_cs_config {
492 : /** CS configuration ID */
493 1 : uint8_t id;
494 : /** Main CS mode type */
495 1 : enum bt_conn_le_cs_main_mode main_mode_type;
496 : /** Sub CS mode type */
497 1 : enum bt_conn_le_cs_sub_mode sub_mode_type;
498 : /** Minimum number of CS main mode steps to be executed before a submode step is executed */
499 1 : uint8_t min_main_mode_steps;
500 : /** Maximum number of CS main mode steps to be executed before a submode step is executed */
501 1 : uint8_t max_main_mode_steps;
502 : /** Number of main mode steps taken from the end of the last CS subevent to be repeated
503 : * at the beginning of the current CS subevent directly after the last mode-0 step of that
504 : * event
505 : */
506 1 : uint8_t main_mode_repetition;
507 : /** Number of CS mode-0 steps to be included at the beginning of each CS subevent */
508 1 : uint8_t mode_0_steps;
509 : /** CS role */
510 1 : enum bt_conn_le_cs_role role;
511 : /** RTT type */
512 1 : enum bt_conn_le_cs_rtt_type rtt_type;
513 : /** CS Sync PHY */
514 1 : enum bt_conn_le_cs_sync_phy cs_sync_phy;
515 : /** The number of times the Channel_Map field will be cycled through for non-mode-0 steps
516 : * within a CS procedure
517 : */
518 1 : uint8_t channel_map_repetition;
519 : /** Channel selection type */
520 1 : enum bt_conn_le_cs_chsel_type channel_selection_type;
521 : /** User-specified channel sequence shape */
522 1 : enum bt_conn_le_cs_ch3c_shape ch3c_shape;
523 : /** Number of channels skipped in each rising and falling sequence */
524 1 : uint8_t ch3c_jump;
525 : /** Interlude time in microseconds between the RTT packets */
526 1 : uint8_t t_ip1_time_us;
527 : /** Interlude time in microseconds between the CS tones */
528 1 : uint8_t t_ip2_time_us;
529 : /** Time in microseconds for frequency changes */
530 1 : uint8_t t_fcs_time_us;
531 : /** Time in microseconds for the phase measurement period of the CS tones */
532 1 : uint8_t t_pm_time_us;
533 : /** Channel map used for CS procedure
534 : * Channels n = 0, 1, 23, 24, 25, 77, and 78 are not allowed and shall be set to zero.
535 : * Channel 79 is reserved for future use and shall be set to zero.
536 : * At least 15 channels shall be enabled.
537 : */
538 1 : uint8_t channel_map[10];
539 : };
540 :
541 : /** Procedure done status */
542 0 : enum bt_conn_le_cs_procedure_done_status {
543 : BT_CONN_LE_CS_PROCEDURE_COMPLETE = BT_HCI_LE_CS_PROCEDURE_DONE_STATUS_COMPLETE,
544 : BT_CONN_LE_CS_PROCEDURE_INCOMPLETE = BT_HCI_LE_CS_PROCEDURE_DONE_STATUS_PARTIAL,
545 : BT_CONN_LE_CS_PROCEDURE_ABORTED = BT_HCI_LE_CS_PROCEDURE_DONE_STATUS_ABORTED,
546 : };
547 :
548 : /** Subevent done status */
549 0 : enum bt_conn_le_cs_subevent_done_status {
550 : BT_CONN_LE_CS_SUBEVENT_COMPLETE = BT_HCI_LE_CS_SUBEVENT_DONE_STATUS_COMPLETE,
551 : BT_CONN_LE_CS_SUBEVENT_ABORTED = BT_HCI_LE_CS_SUBEVENT_DONE_STATUS_ABORTED,
552 : };
553 :
554 : /** Procedure abort reason */
555 0 : enum bt_conn_le_cs_procedure_abort_reason {
556 : BT_CONN_LE_CS_PROCEDURE_NOT_ABORTED = BT_HCI_LE_CS_PROCEDURE_ABORT_REASON_NO_ABORT,
557 : BT_CONN_LE_CS_PROCEDURE_ABORT_REQUESTED =
558 : BT_HCI_LE_CS_PROCEDURE_ABORT_REASON_LOCAL_HOST_OR_REMOTE_REQUEST,
559 : BT_CONN_LE_CS_PROCEDURE_ABORT_TOO_FEW_CHANNELS =
560 : BT_HCI_LE_CS_PROCEDURE_ABORT_REASON_TOO_FEW_CHANNELS,
561 : BT_CONN_LE_CS_PROCEDURE_ABORT_CHMAP_INSTANT_PASSED =
562 : BT_HCI_LE_CS_PROCEDURE_ABORT_REASON_CHMAP_INSTANT_PASSED,
563 : BT_CONN_LE_CS_PROCEDURE_ABORT_UNSPECIFIED = BT_HCI_LE_CS_PROCEDURE_ABORT_REASON_UNSPECIFIED,
564 : };
565 :
566 : /** Subevent abort reason */
567 0 : enum bt_conn_le_cs_subevent_abort_reason {
568 : BT_CONN_LE_CS_SUBEVENT_NOT_ABORTED = BT_HCI_LE_CS_SUBEVENT_ABORT_REASON_NO_ABORT,
569 : BT_CONN_LE_CS_SUBEVENT_ABORT_REQUESTED =
570 : BT_HCI_LE_CS_SUBEVENT_ABORT_REASON_LOCAL_HOST_OR_REMOTE_REQUEST,
571 : BT_CONN_LE_CS_SUBEVENT_ABORT_NO_CS_SYNC =
572 : BT_HCI_LE_CS_SUBEVENT_ABORT_REASON_NO_CS_SYNC_RECEIVED,
573 : BT_CONN_LE_CS_SUBEVENT_ABORT_SCHED_CONFLICT =
574 : BT_HCI_LE_CS_SUBEVENT_ABORT_REASON_SCHED_CONFLICT,
575 : BT_CONN_LE_CS_SUBEVENT_ABORT_UNSPECIFIED = BT_HCI_LE_CS_SUBEVENT_ABORT_REASON_UNSPECIFIED,
576 : };
577 :
578 : /** Subevent data for LE connections supporting CS */
579 1 : struct bt_conn_le_cs_subevent_result {
580 : struct {
581 : /** CS configuration identifier.
582 : *
583 : * Range: 0 to 3
584 : *
585 : * If these results were generated by a CS Test,
586 : * this value will be set to 0 and has no meaning.
587 : */
588 1 : uint8_t config_id;
589 : /** Starting ACL connection event counter.
590 : *
591 : * If these results were generated by a CS Test,
592 : * this value will be set to 0 and has no meaning.
593 : */
594 1 : uint16_t start_acl_conn_event;
595 : /** CS procedure count associated with these results.
596 : *
597 : * This is the CS procedure count since the completion of
598 : * the Channel Sounding Security Start procedure.
599 : */
600 1 : uint16_t procedure_counter;
601 : /** Frequency compensation value in units of 0.01 ppm.
602 : *
603 : * This is a 15-bit signed integer in the range [-100, 100] ppm.
604 : *
605 : * A value of @ref BT_HCI_LE_CS_SUBEVENT_RESULT_FREQ_COMPENSATION_NOT_AVAILABLE
606 : * indicates that the role is not the initiator, or that the
607 : * frequency compensation value is unavailable.
608 : */
609 1 : uint16_t frequency_compensation;
610 : /** Reference power level in dBm.
611 : *
612 : * Range: -127 to 20
613 : *
614 : * A value of @ref BT_HCI_LE_CS_REF_POWER_LEVEL_UNAVAILABLE indicates
615 : * that the reference power level was not available during a subevent.
616 : */
617 1 : int8_t reference_power_level;
618 : /** Procedure status. */
619 1 : enum bt_conn_le_cs_procedure_done_status procedure_done_status;
620 : /** Subevent status
621 : *
622 : * For aborted subevents, this will be set to @ref BT_CONN_LE_CS_SUBEVENT_ABORTED
623 : * and abort_step will contain the step number on which the subevent was aborted.
624 : * Consider the following example:
625 : *
626 : * subevent_done_status = @ref BT_CONN_LE_CS_SUBEVENT_ABORTED
627 : * num_steps_reported = 160
628 : * abort_step = 100
629 : *
630 : * this would mean that steps from 0 to 99 are complete and steps from 100 to 159
631 : * are aborted.
632 : */
633 1 : enum bt_conn_le_cs_subevent_done_status subevent_done_status;
634 : /** Abort reason.
635 : *
636 : * If the procedure status is
637 : * @ref BT_CONN_LE_CS_PROCEDURE_ABORTED, this field will
638 : * specify the reason for the abortion.
639 : */
640 1 : enum bt_conn_le_cs_procedure_abort_reason procedure_abort_reason;
641 : /** Abort reason.
642 : *
643 : * If the subevent status is
644 : * @ref BT_CONN_LE_CS_SUBEVENT_ABORTED, this field will
645 : * specify the reason for the abortion.
646 : */
647 1 : enum bt_conn_le_cs_subevent_abort_reason subevent_abort_reason;
648 : /** Number of antenna paths used during the phase measurement stage.
649 : */
650 1 : uint8_t num_antenna_paths;
651 : /** Number of CS steps in the subevent.
652 : */
653 1 : uint8_t num_steps_reported;
654 : /** Step number, on which the subevent was aborted
655 : * if subevent_done_status is @ref BT_CONN_LE_CS_SUBEVENT_COMPLETE
656 : * then abort_step will be unused and set to 255
657 : */
658 1 : uint8_t abort_step;
659 0 : } header;
660 : /** Pointer to buffer containing step data.
661 : * NULL if num_steps_reported is 0.
662 : */
663 1 : struct net_buf_simple *step_data_buf;
664 : };
665 :
666 : /** @brief Increment a connection's reference count.
667 : *
668 : * Increment the reference count of a connection object.
669 : *
670 : * @note Will return NULL if the reference count is zero.
671 : *
672 : * @param conn Connection object.
673 : *
674 : * @return Connection object with incremented reference count, or NULL if the
675 : * reference count is zero.
676 : */
677 1 : struct bt_conn *bt_conn_ref(struct bt_conn *conn);
678 :
679 : /** @brief Decrement a connection's reference count.
680 : *
681 : * Decrement the reference count of a connection object.
682 : *
683 : * @param conn Connection object.
684 : */
685 1 : void bt_conn_unref(struct bt_conn *conn);
686 :
687 : /** @brief Iterate through all bt_conn objects.
688 : *
689 : * Iterates through all bt_conn objects that are alive in the Host allocator.
690 : *
691 : * To find established connections, combine this with @ref bt_conn_get_info.
692 : * Check that @ref bt_conn_info.state is @ref BT_CONN_STATE_CONNECTED.
693 : *
694 : * Thread safety: This API is thread safe, but it does not guarantee a
695 : * sequentially-consistent view for objects allocated during the current
696 : * invocation of this API. E.g. If preempted while allocations A then B then C
697 : * happen then results may include A and C but miss B.
698 : *
699 : * @param type Connection Type
700 : * @param func Function to call for each connection.
701 : * @param data Data to pass to the callback function.
702 : */
703 1 : void bt_conn_foreach(enum bt_conn_type type,
704 : void (*func)(struct bt_conn *conn, void *data),
705 : void *data);
706 :
707 : /** @brief Look up an existing connection by address.
708 : *
709 : * Look up an existing connection based on the remote address.
710 : *
711 : * The caller gets a new reference to the connection object which must be
712 : * released with bt_conn_unref() once done using the object.
713 : *
714 : * @param id Local identity (in most cases BT_ID_DEFAULT).
715 : * @param peer Remote address.
716 : *
717 : * @return Connection object or NULL if not found.
718 : */
719 1 : struct bt_conn *bt_conn_lookup_addr_le(uint8_t id, const bt_addr_le_t *peer);
720 :
721 : /** @brief Get destination (peer) address of a connection.
722 : *
723 : * @param conn Connection object.
724 : *
725 : * @return Destination address.
726 : */
727 1 : const bt_addr_le_t *bt_conn_get_dst(const struct bt_conn *conn);
728 :
729 : /** @brief Get array index of a connection
730 : *
731 : * This function is used to map bt_conn to index of an array of
732 : * connections. The array has CONFIG_BT_MAX_CONN elements.
733 : *
734 : * @param conn Connection object.
735 : *
736 : * @return Index of the connection object.
737 : * The range of the returned value is 0..CONFIG_BT_MAX_CONN-1
738 : */
739 1 : uint8_t bt_conn_index(const struct bt_conn *conn);
740 :
741 : /** LE Connection Info Structure */
742 1 : struct bt_conn_le_info {
743 : /** Source (Local) Identity Address */
744 1 : const bt_addr_le_t *src;
745 : /** Destination (Remote) Identity Address or remote Resolvable Private
746 : * Address (RPA) before identity has been resolved.
747 : */
748 1 : const bt_addr_le_t *dst;
749 : /** Local device address used during connection setup. */
750 1 : const bt_addr_le_t *local;
751 : /** Remote device address used during connection setup. */
752 1 : const bt_addr_le_t *remote;
753 1 : uint16_t interval; /**< Connection interval */
754 1 : uint16_t latency; /**< Connection peripheral latency */
755 1 : uint16_t timeout; /**< Connection supervision timeout */
756 :
757 : #if defined(CONFIG_BT_USER_PHY_UPDATE)
758 0 : const struct bt_conn_le_phy_info *phy;
759 : #endif /* defined(CONFIG_BT_USER_PHY_UPDATE) */
760 :
761 : #if defined(CONFIG_BT_USER_DATA_LEN_UPDATE)
762 : /* Connection maximum single fragment parameters */
763 0 : const struct bt_conn_le_data_len_info *data_len;
764 : #endif /* defined(CONFIG_BT_USER_DATA_LEN_UPDATE) */
765 :
766 : #if defined(CONFIG_BT_SUBRATING)
767 : /* Connection subrating parameters */
768 : const struct bt_conn_le_subrating_info *subrate;
769 : #endif /* defined(CONFIG_BT_SUBRATING) */
770 : };
771 :
772 : /** @brief Convert connection interval to milliseconds
773 : *
774 : * Multiply by 1.25 to get milliseconds.
775 : *
776 : * Note that this may be inaccurate, as something like 7.5 ms cannot be
777 : * accurately presented with integers.
778 : */
779 1 : #define BT_CONN_INTERVAL_TO_MS(interval) ((interval) * 5U / 4U)
780 :
781 : /** @brief Convert connection interval to microseconds
782 : *
783 : * Multiply by 1250 to get microseconds.
784 : */
785 1 : #define BT_CONN_INTERVAL_TO_US(interval) ((interval) * 1250U)
786 :
787 : /** BR/EDR Connection Info Structure */
788 1 : struct bt_conn_br_info {
789 1 : const bt_addr_t *dst; /**< Destination (Remote) BR/EDR address */
790 : };
791 :
792 0 : enum {
793 : BT_CONN_ROLE_CENTRAL = 0,
794 : BT_CONN_ROLE_PERIPHERAL = 1,
795 : };
796 :
797 0 : enum bt_conn_state {
798 : /** Channel disconnected */
799 : BT_CONN_STATE_DISCONNECTED,
800 : /** Channel in connecting state */
801 : BT_CONN_STATE_CONNECTING,
802 : /** Channel connected and ready for upper layer traffic on it */
803 : BT_CONN_STATE_CONNECTED,
804 : /** Channel in disconnecting state */
805 : BT_CONN_STATE_DISCONNECTING,
806 : };
807 :
808 : /** Security level. */
809 1 : typedef enum __packed {
810 : /** Level 0: Only for BR/EDR special cases, like SDP */
811 : BT_SECURITY_L0,
812 : /** Level 1: No encryption and no authentication. */
813 : BT_SECURITY_L1,
814 : /** Level 2: Encryption and no authentication (no MITM). */
815 : BT_SECURITY_L2,
816 : /** Level 3: Encryption and authentication (MITM). */
817 : BT_SECURITY_L3,
818 : /** Level 4: Authenticated Secure Connections and 128-bit key. */
819 : BT_SECURITY_L4,
820 : /** Bit to force new pairing procedure, bit-wise OR with requested
821 : * security level.
822 : */
823 : BT_SECURITY_FORCE_PAIR = BIT(7),
824 : } bt_security_t;
825 :
826 : /** Security Info Flags. */
827 1 : enum bt_security_flag {
828 : /** Paired with Secure Connections. */
829 : BT_SECURITY_FLAG_SC = BIT(0),
830 : /** Paired with Out of Band method. */
831 : BT_SECURITY_FLAG_OOB = BIT(1),
832 : };
833 :
834 : /** Security Info Structure. */
835 1 : struct bt_security_info {
836 : /** Security Level. */
837 1 : bt_security_t level;
838 : /** Encryption Key Size. */
839 1 : uint8_t enc_key_size;
840 : /** Flags. */
841 1 : enum bt_security_flag flags;
842 : };
843 :
844 : /** Connection Info Structure */
845 1 : struct bt_conn_info {
846 : /** Connection Type. */
847 1 : enum bt_conn_type type;
848 : /** Connection Role. */
849 1 : uint8_t role;
850 : /** Which local identity the connection was created with */
851 1 : uint8_t id;
852 : /** Connection Type specific Info.*/
853 : union {
854 : /** LE Connection specific Info. */
855 1 : struct bt_conn_le_info le;
856 : /** BR/EDR Connection specific Info. */
857 1 : struct bt_conn_br_info br;
858 1 : };
859 : /** Connection state. */
860 1 : enum bt_conn_state state;
861 : /** Security specific info. */
862 1 : struct bt_security_info security;
863 : };
864 :
865 : /** LE Connection Remote Info Structure */
866 1 : struct bt_conn_le_remote_info {
867 :
868 : /** Remote LE feature set (bitmask). */
869 1 : const uint8_t *features;
870 : };
871 :
872 : /** BR/EDR Connection Remote Info structure */
873 1 : struct bt_conn_br_remote_info {
874 :
875 : /** Remote feature set (pages of bitmasks). */
876 1 : const uint8_t *features;
877 :
878 : /** Number of pages in the remote feature set. */
879 1 : uint8_t num_pages;
880 : };
881 :
882 : /** @brief Connection Remote Info Structure
883 : *
884 : * @note The version, manufacturer and subversion fields will only contain
885 : * valid data if @kconfig{CONFIG_BT_REMOTE_VERSION} is enabled.
886 : */
887 1 : struct bt_conn_remote_info {
888 : /** Connection Type */
889 1 : uint8_t type;
890 :
891 : /** Remote Link Layer version */
892 1 : uint8_t version;
893 :
894 : /** Remote manufacturer identifier */
895 1 : uint16_t manufacturer;
896 :
897 : /** Per-manufacturer unique revision */
898 1 : uint16_t subversion;
899 :
900 : union {
901 : /** LE connection remote info */
902 1 : struct bt_conn_le_remote_info le;
903 :
904 : /** BR/EDR connection remote info */
905 1 : struct bt_conn_br_remote_info br;
906 0 : };
907 : };
908 :
909 0 : enum bt_conn_le_tx_power_phy {
910 : /** Convenience macro for when no PHY is set. */
911 : BT_CONN_LE_TX_POWER_PHY_NONE,
912 : /** LE 1M PHY */
913 : BT_CONN_LE_TX_POWER_PHY_1M,
914 : /** LE 2M PHY */
915 : BT_CONN_LE_TX_POWER_PHY_2M,
916 : /** LE Coded PHY using S=8 coding. */
917 : BT_CONN_LE_TX_POWER_PHY_CODED_S8,
918 : /** LE Coded PHY using S=2 coding. */
919 : BT_CONN_LE_TX_POWER_PHY_CODED_S2,
920 : };
921 :
922 : /** LE Transmit Power Level Structure */
923 1 : struct bt_conn_le_tx_power {
924 :
925 : /** Input: 1M, 2M, Coded S2 or Coded S8 */
926 1 : uint8_t phy;
927 :
928 : /** Output: current transmit power level */
929 1 : int8_t current_level;
930 :
931 : /** Output: maximum transmit power level */
932 1 : int8_t max_level;
933 : };
934 :
935 :
936 : /** LE Transmit Power Reporting Structure */
937 1 : struct bt_conn_le_tx_power_report {
938 :
939 : /** Reason for Transmit power reporting,
940 : * as documented in Core Spec. Version 5.4 Vol. 4, Part E, 7.7.65.33.
941 : */
942 1 : uint8_t reason;
943 :
944 : /** Phy of Transmit power reporting. */
945 1 : enum bt_conn_le_tx_power_phy phy;
946 :
947 : /** Transmit power level
948 : * - 0xXX - Transmit power level
949 : * + Range: -127 to 20
950 : * + Units: dBm
951 : *
952 : * - 0x7E - Remote device is not managing power levels on this PHY.
953 : * - 0x7F - Transmit power level is not available
954 : */
955 1 : int8_t tx_power_level;
956 :
957 : /** Bit 0: Transmit power level is at minimum level.
958 : * Bit 1: Transmit power level is at maximum level.
959 : */
960 1 : uint8_t tx_power_level_flag;
961 :
962 : /** Change in transmit power level
963 : * - 0xXX - Change in transmit power level (positive indicates increased
964 : * power, negative indicates decreased power, zero indicates unchanged)
965 : * Units: dB
966 : * - 0x7F - Change is not available or is out of range.
967 : */
968 1 : int8_t delta;
969 : };
970 :
971 : /** @brief Path Loss zone that has been entered.
972 : *
973 : * The path loss zone that has been entered in the most recent LE Path Loss Monitoring
974 : * Threshold Change event as documented in Core Spec. Version 5.4 Vol.4, Part E, 7.7.65.32.
975 : *
976 : * @note BT_CONN_LE_PATH_LOSS_ZONE_UNAVAILABLE has been added to notify when path loss becomes
977 : * unavailable.
978 : */
979 1 : enum bt_conn_le_path_loss_zone {
980 : /** Low path loss zone entered. */
981 : BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_LOW,
982 : /** Middle path loss zone entered. */
983 : BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_MIDDLE,
984 : /** High path loss zone entered. */
985 : BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_HIGH,
986 : /** Path loss has become unavailable. */
987 : BT_CONN_LE_PATH_LOSS_ZONE_UNAVAILABLE,
988 : };
989 :
990 : BUILD_ASSERT(BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_LOW == BT_HCI_LE_ZONE_ENTERED_LOW);
991 : BUILD_ASSERT(BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_MIDDLE == BT_HCI_LE_ZONE_ENTERED_MIDDLE);
992 : BUILD_ASSERT(BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_HIGH == BT_HCI_LE_ZONE_ENTERED_HIGH);
993 :
994 : /** @brief LE Path Loss Monitoring Threshold Change Report Structure. */
995 1 : struct bt_conn_le_path_loss_threshold_report {
996 :
997 : /** Path Loss zone as documented in Core Spec. Version 5.4 Vol.4, Part E, 7.7.65.32. */
998 1 : enum bt_conn_le_path_loss_zone zone;
999 :
1000 : /** Current path loss (dB). */
1001 1 : uint8_t path_loss;
1002 : };
1003 :
1004 : /** @brief LE Path Loss Monitoring Parameters Structure as defined in Core Spec. Version 5.4
1005 : * Vol.4, Part E, 7.8.119 LE Set Path Loss Reporting Parameters command.
1006 : */
1007 1 : struct bt_conn_le_path_loss_reporting_param {
1008 : /** High threshold for the path loss (dB). */
1009 1 : uint8_t high_threshold;
1010 : /** Hysteresis value for the high threshold (dB). */
1011 1 : uint8_t high_hysteresis;
1012 : /** Low threshold for the path loss (dB). */
1013 1 : uint8_t low_threshold;
1014 : /** Hysteresis value for the low threshold (dB). */
1015 1 : uint8_t low_hysteresis;
1016 : /** Minimum time in number of connection events to be observed once the
1017 : * path loss crosses the threshold before an event is generated.
1018 : */
1019 1 : uint16_t min_time_spent;
1020 : };
1021 :
1022 : /** @brief Passkey Keypress Notification type
1023 : *
1024 : * The numeric values are the same as in the Core specification for Pairing
1025 : * Keypress Notification PDU.
1026 : */
1027 0 : enum bt_conn_auth_keypress {
1028 : BT_CONN_AUTH_KEYPRESS_ENTRY_STARTED = 0x00,
1029 : BT_CONN_AUTH_KEYPRESS_DIGIT_ENTERED = 0x01,
1030 : BT_CONN_AUTH_KEYPRESS_DIGIT_ERASED = 0x02,
1031 : BT_CONN_AUTH_KEYPRESS_CLEARED = 0x03,
1032 : BT_CONN_AUTH_KEYPRESS_ENTRY_COMPLETED = 0x04,
1033 : };
1034 :
1035 : /** @brief Get connection info
1036 : *
1037 : * @param conn Connection object.
1038 : * @param info Connection info object.
1039 : *
1040 : * @return Zero on success or (negative) error code on failure.
1041 : */
1042 1 : int bt_conn_get_info(const struct bt_conn *conn, struct bt_conn_info *info);
1043 :
1044 : /** @brief Get connection info for the remote device.
1045 : *
1046 : * @param conn Connection object.
1047 : * @param remote_info Connection remote info object.
1048 : *
1049 : * @note In order to retrieve the remote version (version, manufacturer
1050 : * and subversion) @kconfig{CONFIG_BT_REMOTE_VERSION} must be enabled
1051 : *
1052 : * @note The remote information is exchanged directly after the connection has
1053 : * been established. The application can be notified about when the remote
1054 : * information is available through the remote_info_available callback.
1055 : *
1056 : * @return Zero on success or (negative) error code on failure.
1057 : * @return -EBUSY The remote information is not yet available.
1058 : */
1059 1 : int bt_conn_get_remote_info(struct bt_conn *conn,
1060 : struct bt_conn_remote_info *remote_info);
1061 :
1062 : /** @brief Get connection transmit power level.
1063 : *
1064 : * @param conn Connection object.
1065 : * @param tx_power_level Transmit power level descriptor.
1066 : *
1067 : * @return Zero on success or (negative) error code on failure.
1068 : * @return -ENOBUFS HCI command buffer is not available.
1069 : */
1070 1 : int bt_conn_le_get_tx_power_level(struct bt_conn *conn,
1071 : struct bt_conn_le_tx_power *tx_power_level);
1072 :
1073 : /** @brief Get local enhanced connection transmit power level.
1074 : *
1075 : * @param conn Connection object.
1076 : * @param tx_power Transmit power level descriptor.
1077 : *
1078 : * @return Zero on success or (negative) error code on failure.
1079 : * @retval -ENOBUFS HCI command buffer is not available.
1080 : */
1081 1 : int bt_conn_le_enhanced_get_tx_power_level(struct bt_conn *conn,
1082 : struct bt_conn_le_tx_power *tx_power);
1083 :
1084 : /** @brief Get remote (peer) transmit power level.
1085 : *
1086 : * @param conn Connection object.
1087 : * @param phy PHY information.
1088 : *
1089 : * @return Zero on success or (negative) error code on failure.
1090 : * @retval -ENOBUFS HCI command buffer is not available.
1091 : */
1092 1 : int bt_conn_le_get_remote_tx_power_level(struct bt_conn *conn,
1093 : enum bt_conn_le_tx_power_phy phy);
1094 :
1095 : /** @brief Enable transmit power reporting.
1096 : *
1097 : * @param conn Connection object.
1098 : * @param local_enable Enable/disable reporting for local.
1099 : * @param remote_enable Enable/disable reporting for remote.
1100 : *
1101 : * @return Zero on success or (negative) error code on failure.
1102 : * @retval -ENOBUFS HCI command buffer is not available.
1103 : */
1104 1 : int bt_conn_le_set_tx_power_report_enable(struct bt_conn *conn,
1105 : bool local_enable,
1106 : bool remote_enable);
1107 :
1108 : /** @brief Set Path Loss Monitoring Parameters.
1109 : *
1110 : * Change the configuration for path loss threshold change events for a given conn handle.
1111 : *
1112 : * @note To use this API @kconfig{CONFIG_BT_PATH_LOSS_MONITORING} must be set.
1113 : *
1114 : * @param conn Connection object.
1115 : * @param param Path Loss Monitoring parameters
1116 : *
1117 : * @return Zero on success or (negative) error code on failure.
1118 : */
1119 1 : int bt_conn_le_set_path_loss_mon_param(struct bt_conn *conn,
1120 : const struct bt_conn_le_path_loss_reporting_param *param);
1121 :
1122 : /** @brief Enable or Disable Path Loss Monitoring.
1123 : *
1124 : * Enable or disable Path Loss Monitoring, which will decide whether Path Loss Threshold events
1125 : * are sent from the controller to the host.
1126 : *
1127 : * @note To use this API @kconfig{CONFIG_BT_PATH_LOSS_MONITORING} must be set.
1128 : *
1129 : * @param conn Connection Object.
1130 : * @param enable Enable/disable path loss reporting.
1131 : *
1132 : * @return Zero on success or (negative) error code on failure.
1133 : */
1134 1 : int bt_conn_le_set_path_loss_mon_enable(struct bt_conn *conn, bool enable);
1135 :
1136 : /** @brief Set Default Connection Subrating Parameters.
1137 : *
1138 : * Change the default subrating parameters for all future
1139 : * ACL connections where the local device is the central.
1140 : * This command does not affect any existing connection.
1141 : * Parameters set for specific connection will always have precedence.
1142 : *
1143 : * @note To use this API @kconfig{CONFIG_BT_SUBRATING} and
1144 : * @kconfig{CONFIG_BT_CENTRAL} must be set.
1145 : *
1146 : * @param params Subrating parameters.
1147 : *
1148 : * @return Zero on success or (negative) error code on failure.
1149 : */
1150 1 : int bt_conn_le_subrate_set_defaults(const struct bt_conn_le_subrate_param *params);
1151 :
1152 : /** @brief Request New Subrating Parameters.
1153 : *
1154 : * Request a change to the subrating parameters of a connection.
1155 : *
1156 : * @note To use this API @kconfig{CONFIG_BT_SUBRATING} must be set.
1157 : *
1158 : * @param conn Connection object.
1159 : * @param params Subrating parameters.
1160 : *
1161 : * @return Zero on success or (negative) error code on failure.
1162 : */
1163 1 : int bt_conn_le_subrate_request(struct bt_conn *conn,
1164 : const struct bt_conn_le_subrate_param *params);
1165 :
1166 : /** @brief Update the connection parameters.
1167 : *
1168 : * If the local device is in the peripheral role then updating the connection
1169 : * parameters will be delayed. This delay can be configured by through the
1170 : * @kconfig{CONFIG_BT_CONN_PARAM_UPDATE_TIMEOUT} option.
1171 : *
1172 : * @param conn Connection object.
1173 : * @param param Updated connection parameters.
1174 : *
1175 : * @return Zero on success or (negative) error code on failure.
1176 : */
1177 1 : int bt_conn_le_param_update(struct bt_conn *conn,
1178 : const struct bt_le_conn_param *param);
1179 :
1180 : /** @brief Update the connection transmit data length parameters.
1181 : *
1182 : * @param conn Connection object.
1183 : * @param param Updated data length parameters.
1184 : *
1185 : * @return Zero on success or (negative) error code on failure.
1186 : */
1187 1 : int bt_conn_le_data_len_update(struct bt_conn *conn,
1188 : const struct bt_conn_le_data_len_param *param);
1189 :
1190 : /** @brief Update the connection PHY parameters.
1191 : *
1192 : * Update the preferred transmit and receive PHYs of the connection.
1193 : * Use @ref BT_GAP_LE_PHY_NONE to indicate no preference.
1194 : *
1195 : * @param conn Connection object.
1196 : * @param param Updated connection parameters.
1197 : *
1198 : * @return Zero on success or (negative) error code on failure.
1199 : */
1200 1 : int bt_conn_le_phy_update(struct bt_conn *conn,
1201 : const struct bt_conn_le_phy_param *param);
1202 :
1203 : /** @brief Disconnect from a remote device or cancel pending connection.
1204 : *
1205 : * Disconnect an active connection with the specified reason code or cancel
1206 : * pending outgoing connection.
1207 : *
1208 : * The disconnect reason for a normal disconnect should be:
1209 : * @ref BT_HCI_ERR_REMOTE_USER_TERM_CONN.
1210 : *
1211 : * The following disconnect reasons are accepted:
1212 : * - @ref BT_HCI_ERR_AUTH_FAIL
1213 : * - @ref BT_HCI_ERR_REMOTE_USER_TERM_CONN
1214 : * - @ref BT_HCI_ERR_REMOTE_LOW_RESOURCES
1215 : * - @ref BT_HCI_ERR_REMOTE_POWER_OFF
1216 : * - @ref BT_HCI_ERR_UNSUPP_REMOTE_FEATURE
1217 : * - @ref BT_HCI_ERR_PAIRING_NOT_SUPPORTED
1218 : * - @ref BT_HCI_ERR_UNACCEPT_CONN_PARAM
1219 : *
1220 : * @param conn Connection to disconnect.
1221 : * @param reason Reason code for the disconnection.
1222 : *
1223 : * @return Zero on success or (negative) error code on failure.
1224 : */
1225 1 : int bt_conn_disconnect(struct bt_conn *conn, uint8_t reason);
1226 :
1227 0 : enum {
1228 : /** Convenience value when no options are specified. */
1229 : BT_CONN_LE_OPT_NONE = 0,
1230 :
1231 : /** @brief Enable LE Coded PHY.
1232 : *
1233 : * Enable scanning on the LE Coded PHY.
1234 : */
1235 : BT_CONN_LE_OPT_CODED = BIT(0),
1236 :
1237 : /** @brief Disable LE 1M PHY.
1238 : *
1239 : * Disable scanning on the LE 1M PHY.
1240 : *
1241 : * @note Requires @ref BT_CONN_LE_OPT_CODED.
1242 : */
1243 : BT_CONN_LE_OPT_NO_1M = BIT(1),
1244 : };
1245 :
1246 0 : struct bt_conn_le_create_param {
1247 :
1248 : /** Bit-field of create connection options. */
1249 1 : uint32_t options;
1250 :
1251 : /** Scan interval (N * 0.625 ms)
1252 : *
1253 : * @note When @kconfig{CONFIG_BT_SCAN_AND_INITIATE_IN_PARALLEL} is enabled
1254 : * and the application wants to scan and connect in parallel,
1255 : * the Bluetooth Controller may require the scan interval used
1256 : * for scanning and connection establishment to be equal to
1257 : * obtain the best performance.
1258 : */
1259 1 : uint16_t interval;
1260 :
1261 : /** Scan window (N * 0.625 ms)
1262 : *
1263 : * @note When @kconfig{CONFIG_BT_SCAN_AND_INITIATE_IN_PARALLEL} is enabled
1264 : * and the application wants to scan and connect in parallel,
1265 : * the Bluetooth Controller may require the scan window used
1266 : * for scanning and connection establishment to be equal to
1267 : * obtain the best performance.
1268 : */
1269 1 : uint16_t window;
1270 :
1271 : /** @brief Scan interval LE Coded PHY (N * 0.625 MS)
1272 : *
1273 : * Set zero to use same as LE 1M PHY scan interval
1274 : */
1275 1 : uint16_t interval_coded;
1276 :
1277 : /** @brief Scan window LE Coded PHY (N * 0.625 MS)
1278 : *
1279 : * Set zero to use same as LE 1M PHY scan window.
1280 : */
1281 1 : uint16_t window_coded;
1282 :
1283 : /** @brief Connection initiation timeout (N * 10 MS)
1284 : *
1285 : * Set zero to use the default @kconfig{CONFIG_BT_CREATE_CONN_TIMEOUT}
1286 : * timeout.
1287 : *
1288 : * @note Unused in @ref bt_conn_le_create_auto
1289 : */
1290 1 : uint16_t timeout;
1291 : };
1292 :
1293 : /** @brief Initialize create connection parameters
1294 : *
1295 : * @param _options Create connection options.
1296 : * @param _interval Create connection scan interval (N * 0.625 ms).
1297 : * @param _window Create connection scan window (N * 0.625 ms).
1298 : */
1299 1 : #define BT_CONN_LE_CREATE_PARAM_INIT(_options, _interval, _window) \
1300 : { \
1301 : .options = (_options), \
1302 : .interval = (_interval), \
1303 : .window = (_window), \
1304 : .interval_coded = 0, \
1305 : .window_coded = 0, \
1306 : .timeout = 0, \
1307 : }
1308 :
1309 : /** Helper to declare create connection parameters inline
1310 : *
1311 : * @param _options Create connection options.
1312 : * @param _interval Create connection scan interval (N * 0.625 ms).
1313 : * @param _window Create connection scan window (N * 0.625 ms).
1314 : */
1315 1 : #define BT_CONN_LE_CREATE_PARAM(_options, _interval, _window) \
1316 : ((struct bt_conn_le_create_param[]) { \
1317 : BT_CONN_LE_CREATE_PARAM_INIT(_options, _interval, _window) \
1318 : })
1319 :
1320 : /** Default LE create connection parameters.
1321 : * Scan continuously by setting scan interval equal to scan window.
1322 : */
1323 1 : #define BT_CONN_LE_CREATE_CONN \
1324 : BT_CONN_LE_CREATE_PARAM(BT_CONN_LE_OPT_NONE, \
1325 : BT_GAP_SCAN_FAST_INTERVAL, \
1326 : BT_GAP_SCAN_FAST_INTERVAL)
1327 :
1328 : /** Default LE create connection using filter accept list parameters.
1329 : * Scan window: 30 ms.
1330 : * Scan interval: 60 ms.
1331 : */
1332 1 : #define BT_CONN_LE_CREATE_CONN_AUTO \
1333 : BT_CONN_LE_CREATE_PARAM(BT_CONN_LE_OPT_NONE, \
1334 : BT_GAP_SCAN_FAST_INTERVAL, \
1335 : BT_GAP_SCAN_FAST_WINDOW)
1336 :
1337 : /** @brief Initiate an LE connection to a remote device.
1338 : *
1339 : * Allows initiate new LE link to remote peer using its address.
1340 : *
1341 : * The caller gets a new reference to the connection object which must be
1342 : * released with bt_conn_unref() once done using the object. If
1343 : * @kconfig{CONFIG_BT_CONN_CHECK_NULL_BEFORE_CREATE} is enabled, this function
1344 : * will return -EINVAL if dereferenced @p conn is not NULL.
1345 : *
1346 : * This uses the General Connection Establishment procedure.
1347 : *
1348 : * The application must disable explicit scanning before initiating
1349 : * a new LE connection if @kconfig{CONFIG_BT_SCAN_AND_INITIATE_IN_PARALLEL}
1350 : * is not enabled.
1351 : *
1352 : * @param[in] peer Remote address.
1353 : * @param[in] create_param Create connection parameters.
1354 : * @param[in] conn_param Initial connection parameters.
1355 : * @param[out] conn Valid connection object on success.
1356 : *
1357 : * @return Zero on success or (negative) error code on failure.
1358 : */
1359 1 : int bt_conn_le_create(const bt_addr_le_t *peer,
1360 : const struct bt_conn_le_create_param *create_param,
1361 : const struct bt_le_conn_param *conn_param,
1362 : struct bt_conn **conn);
1363 :
1364 0 : struct bt_conn_le_create_synced_param {
1365 :
1366 : /** @brief Remote address
1367 : *
1368 : * The peer must be synchronized to the PAwR train.
1369 : *
1370 : */
1371 1 : const bt_addr_le_t *peer;
1372 :
1373 : /** The subevent where the connection will be initiated. */
1374 1 : uint8_t subevent;
1375 : };
1376 :
1377 : /** @brief Create a connection to a synced device
1378 : *
1379 : * Initiate a connection to a synced device from a Periodic Advertising
1380 : * with Responses (PAwR) train.
1381 : *
1382 : * The caller gets a new reference to the connection object which must be
1383 : * released with bt_conn_unref() once done using the object. If
1384 : * @kconfig{CONFIG_BT_CONN_CHECK_NULL_BEFORE_CREATE} is enabled, this function
1385 : * will return -EINVAL if dereferenced @p conn is not NULL.
1386 : *
1387 : * This uses the Periodic Advertising Connection Procedure.
1388 : *
1389 : * @param[in] adv The adverting set the PAwR advertiser belongs to.
1390 : * @param[in] synced_param Create connection parameters.
1391 : * @param[in] conn_param Initial connection parameters.
1392 : * @param[out] conn Valid connection object on success.
1393 : *
1394 : * @return Zero on success or (negative) error code on failure.
1395 : */
1396 1 : int bt_conn_le_create_synced(const struct bt_le_ext_adv *adv,
1397 : const struct bt_conn_le_create_synced_param *synced_param,
1398 : const struct bt_le_conn_param *conn_param, struct bt_conn **conn);
1399 :
1400 : /** @brief Automatically connect to remote devices in the filter accept list.
1401 : *
1402 : * This uses the Auto Connection Establishment procedure.
1403 : * The procedure will continue until a single connection is established or the
1404 : * procedure is stopped through @ref bt_conn_create_auto_stop.
1405 : * To establish connections to all devices in the filter accept list the
1406 : * procedure should be started again in the connected callback after a
1407 : * new connection has been established.
1408 : *
1409 : * @param create_param Create connection parameters
1410 : * @param conn_param Initial connection parameters.
1411 : *
1412 : * @return Zero on success or (negative) error code on failure.
1413 : * @return -ENOMEM No free connection object available.
1414 : */
1415 1 : int bt_conn_le_create_auto(const struct bt_conn_le_create_param *create_param,
1416 : const struct bt_le_conn_param *conn_param);
1417 :
1418 : /** @brief Stop automatic connect creation.
1419 : *
1420 : * @return Zero on success or (negative) error code on failure.
1421 : */
1422 1 : int bt_conn_create_auto_stop(void);
1423 :
1424 : /** @brief Automatically connect to remote device if it's in range.
1425 : *
1426 : * This function enables/disables automatic connection initiation.
1427 : * Every time the device loses the connection with peer, this connection
1428 : * will be re-established if connectable advertisement from peer is received.
1429 : *
1430 : * @note Auto connect is disabled during explicit scanning.
1431 : *
1432 : * @param addr Remote Bluetooth address.
1433 : * @param param If non-NULL, auto connect is enabled with the given
1434 : * parameters. If NULL, auto connect is disabled.
1435 : *
1436 : * @return Zero on success or error code otherwise.
1437 : */
1438 1 : __deprecated int bt_le_set_auto_conn(const bt_addr_le_t *addr,
1439 : const struct bt_le_conn_param *param);
1440 :
1441 : /** @brief Set security level for a connection.
1442 : *
1443 : * This function enable security (encryption) for a connection. If the device
1444 : * has bond information for the peer with sufficiently strong key encryption
1445 : * will be enabled. If the connection is already encrypted with sufficiently
1446 : * strong key this function does nothing.
1447 : *
1448 : * If the device has no bond information for the peer and is not already paired
1449 : * then the pairing procedure will be initiated. Note that @p sec has no effect
1450 : * on the security level selected for the pairing process. The selection is
1451 : * instead controlled by the values of the registered @ref bt_conn_auth_cb. If
1452 : * the device has bond information or is already paired and the keys are too
1453 : * weak then the pairing procedure will be initiated.
1454 : *
1455 : * This function may return an error if the required level of security defined using
1456 : * @p sec is not possible to achieve due to local or remote device limitation
1457 : * (e.g., input output capabilities), or if the maximum number of paired devices
1458 : * has been reached.
1459 : *
1460 : * This function may return an error if the pairing procedure has already been
1461 : * initiated by the local device or the peer device.
1462 : *
1463 : * @note When @kconfig{CONFIG_BT_SMP_SC_ONLY} is enabled then the security
1464 : * level will always be level 4.
1465 : *
1466 : * @note When @kconfig{CONFIG_BT_SMP_OOB_LEGACY_PAIR_ONLY} is enabled then the
1467 : * security level will always be level 3.
1468 : *
1469 : * @note When @ref BT_SECURITY_FORCE_PAIR within @p sec is enabled then the pairing
1470 : * procedure will always be initiated.
1471 : *
1472 : * @param conn Connection object.
1473 : * @param sec Requested minimum security level.
1474 : *
1475 : * @return 0 on success or negative error
1476 : */
1477 1 : int bt_conn_set_security(struct bt_conn *conn, bt_security_t sec);
1478 :
1479 : /** @brief Get security level for a connection.
1480 : *
1481 : * @return Connection security level
1482 : */
1483 1 : bt_security_t bt_conn_get_security(const struct bt_conn *conn);
1484 :
1485 : /** @brief Get encryption key size.
1486 : *
1487 : * This function gets encryption key size.
1488 : * If there is no security (encryption) enabled 0 will be returned.
1489 : *
1490 : * @param conn Existing connection object.
1491 : *
1492 : * @return Encryption key size.
1493 : */
1494 1 : uint8_t bt_conn_enc_key_size(const struct bt_conn *conn);
1495 :
1496 0 : enum bt_security_err {
1497 : /** Security procedure successful. */
1498 : BT_SECURITY_ERR_SUCCESS,
1499 :
1500 : /** Authentication failed. */
1501 : BT_SECURITY_ERR_AUTH_FAIL,
1502 :
1503 : /** PIN or encryption key is missing. */
1504 : BT_SECURITY_ERR_PIN_OR_KEY_MISSING,
1505 :
1506 : /** OOB data is not available. */
1507 : BT_SECURITY_ERR_OOB_NOT_AVAILABLE,
1508 :
1509 : /** The requested security level could not be reached. */
1510 : BT_SECURITY_ERR_AUTH_REQUIREMENT,
1511 :
1512 : /** Pairing is not supported */
1513 : BT_SECURITY_ERR_PAIR_NOT_SUPPORTED,
1514 :
1515 : /** Pairing is not allowed. */
1516 : BT_SECURITY_ERR_PAIR_NOT_ALLOWED,
1517 :
1518 : /** Invalid parameters. */
1519 : BT_SECURITY_ERR_INVALID_PARAM,
1520 :
1521 : /** Distributed Key Rejected */
1522 : BT_SECURITY_ERR_KEY_REJECTED,
1523 :
1524 : /** Pairing failed but the exact reason could not be specified. */
1525 : BT_SECURITY_ERR_UNSPECIFIED,
1526 : };
1527 :
1528 0 : enum bt_conn_le_cs_procedure_enable_state {
1529 : BT_CONN_LE_CS_PROCEDURES_DISABLED = BT_HCI_OP_LE_CS_PROCEDURES_DISABLED,
1530 : BT_CONN_LE_CS_PROCEDURES_ENABLED = BT_HCI_OP_LE_CS_PROCEDURES_ENABLED,
1531 : };
1532 :
1533 : /** CS Test Tone Antennna Config Selection.
1534 : *
1535 : * These enum values are indices in the following table, where N_AP is the maximum
1536 : * number of antenna paths (in the range [1, 4]).
1537 : *
1538 : * +--------------+-------------+-------------------+-------------------+--------+
1539 : * | Config Index | Total Paths | Dev A: # Antennas | Dev B: # Antennas | Config |
1540 : * +--------------+-------------+-------------------+-------------------+--------+
1541 : * | 0 | 1 | 1 | 1 | 1:1 |
1542 : * | 1 | 2 | 2 | 1 | N_AP:1 |
1543 : * | 2 | 3 | 3 | 1 | N_AP:1 |
1544 : * | 3 | 4 | 4 | 1 | N_AP:1 |
1545 : * | 4 | 2 | 1 | 2 | 1:N_AP |
1546 : * | 5 | 3 | 1 | 3 | 1:N_AP |
1547 : * | 6 | 4 | 1 | 4 | 1:N_AP |
1548 : * | 7 | 4 | 2 | 2 | 2:2 |
1549 : * +--------------+-------------+-------------------+-------------------+--------+
1550 : *
1551 : * There are therefore four groups of possible antenna configurations:
1552 : *
1553 : * - 1:1 configuration, where both A and B support 1 antenna each
1554 : * - 1:N_AP configuration, where A supports 1 antenna, B supports N_AP antennas, and
1555 : * N_AP is a value in the range [2, 4]
1556 : * - N_AP:1 configuration, where A supports N_AP antennas, B supports 1 antenna, and
1557 : * N_AP is a value in the range [2, 4]
1558 : * - 2:2 configuration, where both A and B support 2 antennas and N_AP = 4
1559 : */
1560 0 : enum bt_conn_le_cs_tone_antenna_config_selection {
1561 : BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_ONE = BT_HCI_OP_LE_CS_ACI_0,
1562 : BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_TWO = BT_HCI_OP_LE_CS_ACI_1,
1563 : BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_THREE = BT_HCI_OP_LE_CS_ACI_2,
1564 : BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_FOUR = BT_HCI_OP_LE_CS_ACI_3,
1565 : BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_FIVE = BT_HCI_OP_LE_CS_ACI_4,
1566 : BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_SIX = BT_HCI_OP_LE_CS_ACI_5,
1567 : BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_SEVEN = BT_HCI_OP_LE_CS_ACI_6,
1568 : BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_EIGHT = BT_HCI_OP_LE_CS_ACI_7,
1569 : };
1570 :
1571 0 : struct bt_conn_le_cs_procedure_enable_complete {
1572 : /* The ID associated with the desired configuration (0 to 3) */
1573 0 : uint8_t config_id;
1574 :
1575 : /* State of the CS procedure */
1576 0 : enum bt_conn_le_cs_procedure_enable_state state;
1577 :
1578 : /* Antenna configuration index */
1579 0 : enum bt_conn_le_cs_tone_antenna_config_selection tone_antenna_config_selection;
1580 :
1581 : /* Transmit power level used for CS procedures (-127 to 20 dB; 0x7F if unavailable) */
1582 0 : int8_t selected_tx_power;
1583 :
1584 : /* Duration of each CS subevent in microseconds (1250 us to 4 s) */
1585 0 : uint32_t subevent_len;
1586 :
1587 : /* Number of CS subevents anchored off the same ACL connection event (0x01 to 0x20) */
1588 0 : uint8_t subevents_per_event;
1589 :
1590 : /* Time between consecutive CS subevents anchored off the same ACL connection event in
1591 : * units of 0.625 ms
1592 : */
1593 0 : uint16_t subevent_interval;
1594 :
1595 : /* Number of ACL connection events between consecutive CS event anchor points */
1596 0 : uint16_t event_interval;
1597 :
1598 : /* Number of ACL connection events between consecutive CS procedure anchor points */
1599 0 : uint16_t procedure_interval;
1600 :
1601 : /* Number of CS procedures to be scheduled (0 if procedures to continue until disabled) */
1602 0 : uint16_t procedure_count;
1603 :
1604 : /* Maximum duration for each procedure in units of 0.625 ms (0x0001 to 0xFFFF) */
1605 0 : uint16_t max_procedure_len;
1606 : };
1607 :
1608 : /** @brief Connection callback structure.
1609 : *
1610 : * This structure is used for tracking the state of a connection.
1611 : * It is registered with the help of the bt_conn_cb_register() API.
1612 : * It's permissible to register multiple instances of this @ref bt_conn_cb
1613 : * type, in case different modules of an application are interested in
1614 : * tracking the connection state. If a callback is not of interest for
1615 : * an instance, it may be set to NULL and will as a consequence not be
1616 : * used for that instance.
1617 : */
1618 1 : struct bt_conn_cb {
1619 : /** @brief A new connection has been established.
1620 : *
1621 : * This callback notifies the application of a new connection.
1622 : * In case the err parameter is non-zero it means that the
1623 : * connection establishment failed.
1624 : *
1625 : * @note If the connection was established from an advertising set then
1626 : * the advertising set cannot be restarted directly from this
1627 : * callback. Instead use the connected callback of the
1628 : * advertising set.
1629 : *
1630 : * @param conn New connection object.
1631 : * @param err HCI error. Zero for success, non-zero otherwise.
1632 : *
1633 : * @p err can mean either of the following:
1634 : * - @ref BT_HCI_ERR_UNKNOWN_CONN_ID Creating the connection started by
1635 : * @ref bt_conn_le_create was canceled either by the user through
1636 : * @ref bt_conn_disconnect or by the timeout in the host through
1637 : * @ref bt_conn_le_create_param timeout parameter, which defaults to
1638 : * @kconfig{CONFIG_BT_CREATE_CONN_TIMEOUT} seconds.
1639 : * - @p BT_HCI_ERR_ADV_TIMEOUT High duty cycle directed connectable
1640 : * advertiser started by @ref bt_le_adv_start failed to be connected
1641 : * within the timeout.
1642 : */
1643 1 : void (*connected)(struct bt_conn *conn, uint8_t err);
1644 :
1645 : /** @brief A connection has been disconnected.
1646 : *
1647 : * This callback notifies the application that a connection
1648 : * has been disconnected.
1649 : *
1650 : * When this callback is called the stack still has one reference to
1651 : * the connection object. If the application in this callback tries to
1652 : * start either a connectable advertiser or create a new connection
1653 : * this might fail because there are no free connection objects
1654 : * available.
1655 : * To avoid this issue it is recommended to either start connectable
1656 : * advertise or create a new connection using @ref k_work_submit or
1657 : * increase @kconfig{CONFIG_BT_MAX_CONN}.
1658 : *
1659 : * @param conn Connection object.
1660 : * @param reason BT_HCI_ERR_* reason for the disconnection.
1661 : */
1662 1 : void (*disconnected)(struct bt_conn *conn, uint8_t reason);
1663 :
1664 : /** @brief A connection object has been returned to the pool.
1665 : *
1666 : * This callback notifies the application that it might be able to
1667 : * allocate a connection object. No guarantee, first come, first serve.
1668 : *
1669 : * Use this to e.g. re-start connectable advertising or scanning.
1670 : *
1671 : * Treat this callback as an ISR, as it originates from
1672 : * @ref bt_conn_unref which is used by the BT stack. Making
1673 : * Bluetooth API calls in this context is error-prone and strongly
1674 : * discouraged.
1675 : */
1676 1 : void (*recycled)(void);
1677 :
1678 : /** @brief LE connection parameter update request.
1679 : *
1680 : * This callback notifies the application that a remote device
1681 : * is requesting to update the connection parameters. The
1682 : * application accepts the parameters by returning true, or
1683 : * rejects them by returning false. Before accepting, the
1684 : * application may also adjust the parameters to better suit
1685 : * its needs.
1686 : *
1687 : * It is recommended for an application to have just one of these
1688 : * callbacks for simplicity. However, if an application registers
1689 : * multiple it needs to manage the potentially different
1690 : * requirements for each callback. Each callback gets the
1691 : * parameters as returned by previous callbacks, i.e. they are not
1692 : * necessarily the same ones as the remote originally sent.
1693 : *
1694 : * If the application does not have this callback then the default
1695 : * is to accept the parameters.
1696 : *
1697 : * @param conn Connection object.
1698 : * @param param Proposed connection parameters.
1699 : *
1700 : * @return true to accept the parameters, or false to reject them.
1701 : */
1702 1 : bool (*le_param_req)(struct bt_conn *conn,
1703 : struct bt_le_conn_param *param);
1704 :
1705 : /** @brief The parameters for an LE connection have been updated.
1706 : *
1707 : * This callback notifies the application that the connection
1708 : * parameters for an LE connection have been updated.
1709 : *
1710 : * @param conn Connection object.
1711 : * @param interval Connection interval.
1712 : * @param latency Connection latency.
1713 : * @param timeout Connection supervision timeout.
1714 : */
1715 1 : void (*le_param_updated)(struct bt_conn *conn, uint16_t interval,
1716 : uint16_t latency, uint16_t timeout);
1717 : #if defined(CONFIG_BT_SMP)
1718 : /** @brief Remote Identity Address has been resolved.
1719 : *
1720 : * This callback notifies the application that a remote
1721 : * Identity Address has been resolved
1722 : *
1723 : * @param conn Connection object.
1724 : * @param rpa Resolvable Private Address.
1725 : * @param identity Identity Address.
1726 : */
1727 1 : void (*identity_resolved)(struct bt_conn *conn,
1728 : const bt_addr_le_t *rpa,
1729 : const bt_addr_le_t *identity);
1730 : #endif /* CONFIG_BT_SMP */
1731 : #if defined(CONFIG_BT_SMP) || defined(CONFIG_BT_CLASSIC)
1732 : /** @brief The security level of a connection has changed.
1733 : *
1734 : * This callback notifies the application that the security of a
1735 : * connection has changed.
1736 : *
1737 : * The security level of the connection can either have been increased
1738 : * or remain unchanged. An increased security level means that the
1739 : * pairing procedure has been performed or the bond information from
1740 : * a previous connection has been applied. If the security level
1741 : * remains unchanged this means that the encryption key has been
1742 : * refreshed for the connection.
1743 : *
1744 : * @param conn Connection object.
1745 : * @param level New security level of the connection.
1746 : * @param err Security error. Zero for success, non-zero otherwise.
1747 : */
1748 1 : void (*security_changed)(struct bt_conn *conn, bt_security_t level,
1749 : enum bt_security_err err);
1750 : #endif /* defined(CONFIG_BT_SMP) || defined(CONFIG_BT_CLASSIC) */
1751 :
1752 : #if defined(CONFIG_BT_REMOTE_INFO)
1753 : /** @brief Remote information procedures has completed.
1754 : *
1755 : * This callback notifies the application that the remote information
1756 : * has been retrieved from the remote peer.
1757 : *
1758 : * @param conn Connection object.
1759 : * @param remote_info Connection information of remote device.
1760 : */
1761 1 : void (*remote_info_available)(struct bt_conn *conn,
1762 : struct bt_conn_remote_info *remote_info);
1763 : #endif /* defined(CONFIG_BT_REMOTE_INFO) */
1764 :
1765 : #if defined(CONFIG_BT_USER_PHY_UPDATE)
1766 : /** @brief The PHY of the connection has changed.
1767 : *
1768 : * This callback notifies the application that the PHY of the
1769 : * connection has changed.
1770 : *
1771 : * @param conn Connection object.
1772 : * @param info Connection LE PHY information.
1773 : */
1774 1 : void (*le_phy_updated)(struct bt_conn *conn,
1775 : struct bt_conn_le_phy_info *param);
1776 : #endif /* defined(CONFIG_BT_USER_PHY_UPDATE) */
1777 :
1778 : #if defined(CONFIG_BT_USER_DATA_LEN_UPDATE)
1779 : /** @brief The data length parameters of the connection has changed.
1780 : *
1781 : * This callback notifies the application that the maximum Link Layer
1782 : * payload length or transmission time has changed.
1783 : *
1784 : * @param conn Connection object.
1785 : * @param info Connection data length information.
1786 : */
1787 1 : void (*le_data_len_updated)(struct bt_conn *conn,
1788 : struct bt_conn_le_data_len_info *info);
1789 : #endif /* defined(CONFIG_BT_USER_DATA_LEN_UPDATE) */
1790 :
1791 : #if defined(CONFIG_BT_DF_CONNECTION_CTE_RX)
1792 : /** @brief Callback for IQ samples report collected when sampling
1793 : * CTE received by data channel PDU.
1794 : *
1795 : * @param conn The connection object.
1796 : * @param iq_report Report data for collected IQ samples.
1797 : */
1798 : void (*cte_report_cb)(struct bt_conn *conn,
1799 : const struct bt_df_conn_iq_samples_report *iq_report);
1800 : #endif /* CONFIG_BT_DF_CONNECTION_CTE_RX */
1801 :
1802 : #if defined(CONFIG_BT_TRANSMIT_POWER_CONTROL)
1803 : /** @brief LE Read Remote Transmit Power Level procedure has completed or LE
1804 : * Transmit Power Reporting event.
1805 : *
1806 : * This callback notifies the application that either the remote transmit power level
1807 : * has been read from the peer or transmit power level has changed for the local or
1808 : * remote controller when transmit power reporting is enabled for the respective side
1809 : * using @ref bt_conn_le_set_tx_power_report_enable.
1810 : *
1811 : * @param conn Connection object.
1812 : * @param report Transmit power report.
1813 : */
1814 : void (*tx_power_report)(struct bt_conn *conn,
1815 : const struct bt_conn_le_tx_power_report *report);
1816 : #endif /* CONFIG_BT_TRANSMIT_POWER_CONTROL */
1817 :
1818 : #if defined(CONFIG_BT_PATH_LOSS_MONITORING)
1819 : /** @brief LE Path Loss Threshold event.
1820 : *
1821 : * This callback notifies the application that there has been a path loss threshold
1822 : * crossing or reporting the initial path loss threshold zone after using
1823 : * @ref bt_conn_le_set_path_loss_mon_enable.
1824 : *
1825 : * @param conn Connection object.
1826 : * @param report Path loss threshold report.
1827 : */
1828 : void (*path_loss_threshold_report)(struct bt_conn *conn,
1829 : const struct bt_conn_le_path_loss_threshold_report *report);
1830 : #endif /* CONFIG_BT_PATH_LOSS_MONITORING */
1831 :
1832 : #if defined(CONFIG_BT_SUBRATING)
1833 : /** @brief LE Subrate Changed event.
1834 : *
1835 : * This callback notifies the application that the subrating parameters
1836 : * of the connection may have changed.
1837 : * The connection subrating parameters will be unchanged
1838 : * if status is not BT_HCI_ERR_SUCCESS.
1839 : *
1840 : * @param conn Connection object.
1841 : * @param params New subrating parameters.
1842 : */
1843 : void (*subrate_changed)(struct bt_conn *conn,
1844 : const struct bt_conn_le_subrate_changed *params);
1845 : #endif /* CONFIG_BT_SUBRATING */
1846 :
1847 : #if defined(CONFIG_BT_CHANNEL_SOUNDING)
1848 : /** @brief LE CS Read Remote Supported Capabilities Complete event.
1849 : *
1850 : * This callback notifies the application that the remote channel
1851 : * sounding capabilities have been received from the peer.
1852 : *
1853 : * @param conn Connection object.
1854 : * @param remote_cs_capabilities Remote Channel Sounding Capabilities.
1855 : */
1856 : void (*le_cs_remote_capabilities_available)(struct bt_conn *conn,
1857 : struct bt_conn_le_cs_capabilities *params);
1858 :
1859 : /** @brief LE CS Read Remote FAE Table Complete event.
1860 : *
1861 : * This callback notifies the application that the remote mode-0
1862 : * FAE Table has been received from the peer.
1863 : *
1864 : * @param conn Connection object.
1865 : * @param params FAE Table.
1866 : */
1867 : void (*le_cs_remote_fae_table_available)(struct bt_conn *conn,
1868 : struct bt_conn_le_cs_fae_table *params);
1869 :
1870 : /** @brief LE CS Config created.
1871 : *
1872 : * This callback notifies the application that a Channel Sounding
1873 : * Configuration procedure has completed and a new CS config is created
1874 : *
1875 : * @param conn Connection object.
1876 : * @param config CS configuration.
1877 : */
1878 : void (*le_cs_config_created)(struct bt_conn *conn, struct bt_conn_le_cs_config *config);
1879 :
1880 : /** @brief LE CS Config removed.
1881 : *
1882 : * This callback notifies the application that a Channel Sounding
1883 : * Configuration procedure has completed and a CS config is removed
1884 : *
1885 : * @param conn Connection object.
1886 : * @param config_id ID of the CS configuration that was removed.
1887 : */
1888 : void (*le_cs_config_removed)(struct bt_conn *conn, uint8_t config_id);
1889 :
1890 : /** @brief Subevent Results from a CS procedure are available.
1891 : *
1892 : * This callback notifies the user that CS subevent results are
1893 : * available for the given connection object.
1894 : *
1895 : * @param conn Connection objects.
1896 : * @param result Subevent results
1897 : */
1898 : void (*le_cs_subevent_data_available)(struct bt_conn *conn,
1899 : struct bt_conn_le_cs_subevent_result *result);
1900 :
1901 : /** @brief LE CS Security Enabled.
1902 : *
1903 : * This callback notifies the application that a Channel Sounding
1904 : * Security Enable procedure has completed
1905 : *
1906 : * @param conn Connection object.
1907 : */
1908 : void (*le_cs_security_enabled)(struct bt_conn *conn);
1909 :
1910 : /** @brief LE CS Procedure Enabled.
1911 : *
1912 : * This callback notifies the application that a Channel Sounding
1913 : * Procedure Enable procedure has completed
1914 : *
1915 : * @param conn Connection object.
1916 : * @param params CS Procedure Enable parameters
1917 : */
1918 : void (*le_cs_procedure_enabled)(
1919 : struct bt_conn *conn, struct bt_conn_le_cs_procedure_enable_complete *params);
1920 :
1921 : #endif
1922 :
1923 : /** @internal Internally used field for list handling */
1924 : sys_snode_t _node;
1925 : };
1926 :
1927 : /** @brief Register connection callbacks.
1928 : *
1929 : * Register callbacks to monitor the state of connections.
1930 : *
1931 : * @param cb Callback struct. Must point to memory that remains valid.
1932 : *
1933 : * @retval 0 Success.
1934 : * @retval -EEXIST if @p cb was already registered.
1935 : */
1936 1 : int bt_conn_cb_register(struct bt_conn_cb *cb);
1937 :
1938 : /**
1939 : * @brief Unregister connection callbacks.
1940 : *
1941 : * Unregister the state of connections callbacks.
1942 : *
1943 : * @param cb Callback struct point to memory that remains valid.
1944 : *
1945 : * @retval 0 Success
1946 : * @retval -EINVAL If @p cb is NULL
1947 : * @retval -ENOENT if @p cb was not registered
1948 : */
1949 1 : int bt_conn_cb_unregister(struct bt_conn_cb *cb);
1950 :
1951 : /**
1952 : * @brief Register a callback structure for connection events.
1953 : *
1954 : * @param _name Name of callback structure.
1955 : */
1956 1 : #define BT_CONN_CB_DEFINE(_name) \
1957 : static const STRUCT_SECTION_ITERABLE(bt_conn_cb, \
1958 : _CONCAT(bt_conn_cb_, \
1959 : _name))
1960 :
1961 : /** Converts a security error to string.
1962 : *
1963 : * @return The string representation of the security error code.
1964 : * If @kconfig{CONFIG_BT_SECURITY_ERR_TO_STR} is not enabled,
1965 : * this just returns the empty string
1966 : */
1967 : #if defined(CONFIG_BT_SECURITY_ERR_TO_STR)
1968 : const char *bt_security_err_to_str(enum bt_security_err err);
1969 : #else
1970 1 : static inline const char *bt_security_err_to_str(enum bt_security_err err)
1971 : {
1972 : ARG_UNUSED(err);
1973 :
1974 : return "";
1975 : }
1976 : #endif
1977 :
1978 : /** @brief Enable/disable bonding.
1979 : *
1980 : * Set/clear the Bonding flag in the Authentication Requirements of
1981 : * SMP Pairing Request/Response data.
1982 : * The initial value of this flag depends on BT_BONDABLE Kconfig setting.
1983 : * For the vast majority of applications calling this function shouldn't be
1984 : * needed.
1985 : *
1986 : * @param enable Value allowing/disallowing to be bondable.
1987 : */
1988 1 : void bt_set_bondable(bool enable);
1989 :
1990 : /** @brief Get bonding flag.
1991 : *
1992 : * Get current bonding flag.
1993 : * The initial value of this flag depends on @kconfig{CONFIG_BT_BONDABLE} Kconfig
1994 : * setting.
1995 : * The Bonding flag can be updated using bt_set_bondable().
1996 : *
1997 : * @return Current bonding flag.
1998 : */
1999 1 : bool bt_get_bondable(void);
2000 :
2001 : /** @brief Set/clear the bonding flag for a given connection.
2002 : *
2003 : * Set/clear the Bonding flag in the Authentication Requirements of
2004 : * SMP Pairing Request/Response data for a given connection.
2005 : *
2006 : * The bonding flag for a given connection cannot be set/cleared if
2007 : * security procedures in the SMP module have already started.
2008 : * This function can be called only once per connection.
2009 : *
2010 : * If the bonding flag is not set/cleared for a given connection,
2011 : * the value will depend on global configuration which is set using
2012 : * bt_set_bondable.
2013 : * The default value of the global configuration is defined using
2014 : * CONFIG_BT_BONDABLE Kconfig option.
2015 : *
2016 : * @param conn Connection object.
2017 : * @param enable Value allowing/disallowing to be bondable.
2018 : */
2019 1 : int bt_conn_set_bondable(struct bt_conn *conn, bool enable);
2020 :
2021 : /** @brief Allow/disallow remote LE SC OOB data to be used for pairing.
2022 : *
2023 : * Set/clear the OOB data flag for LE SC SMP Pairing Request/Response data.
2024 : *
2025 : * @param enable Value allowing/disallowing remote LE SC OOB data.
2026 : */
2027 1 : void bt_le_oob_set_sc_flag(bool enable);
2028 :
2029 : /** @brief Allow/disallow remote legacy OOB data to be used for pairing.
2030 : *
2031 : * Set/clear the OOB data flag for legacy SMP Pairing Request/Response data.
2032 : *
2033 : * @param enable Value allowing/disallowing remote legacy OOB data.
2034 : */
2035 1 : void bt_le_oob_set_legacy_flag(bool enable);
2036 :
2037 : /** @brief Set OOB Temporary Key to be used for pairing
2038 : *
2039 : * This function allows to set OOB data for the LE legacy pairing procedure.
2040 : * The function should only be called in response to the oob_data_request()
2041 : * callback provided that the legacy method is user pairing.
2042 : *
2043 : * @param conn Connection object
2044 : * @param tk Pointer to 16 byte long TK array
2045 : *
2046 : * @return Zero on success or -EINVAL if NULL
2047 : */
2048 1 : int bt_le_oob_set_legacy_tk(struct bt_conn *conn, const uint8_t *tk);
2049 :
2050 : /** @brief Set OOB data during LE Secure Connections (SC) pairing procedure
2051 : *
2052 : * This function allows to set OOB data during the LE SC pairing procedure.
2053 : * The function should only be called in response to the oob_data_request()
2054 : * callback provided that LE SC method is used for pairing.
2055 : *
2056 : * The user should submit OOB data according to the information received in the
2057 : * callback. This may yield three different configurations: with only local OOB
2058 : * data present, with only remote OOB data present or with both local and
2059 : * remote OOB data present.
2060 : *
2061 : * @param conn Connection object
2062 : * @param oobd_local Local OOB data or NULL if not present
2063 : * @param oobd_remote Remote OOB data or NULL if not present
2064 : *
2065 : * @return Zero on success or error code otherwise, positive in case of
2066 : * protocol error or negative (POSIX) in case of stack internal error.
2067 : */
2068 1 : int bt_le_oob_set_sc_data(struct bt_conn *conn,
2069 : const struct bt_le_oob_sc_data *oobd_local,
2070 : const struct bt_le_oob_sc_data *oobd_remote);
2071 :
2072 : /** @brief Get OOB data used for LE Secure Connections (SC) pairing procedure
2073 : *
2074 : * This function allows to get OOB data during the LE SC pairing procedure that
2075 : * were set by the bt_le_oob_set_sc_data() API.
2076 : *
2077 : * @note The OOB data will only be available as long as the connection object
2078 : * associated with it is valid.
2079 : *
2080 : * @param conn Connection object
2081 : * @param oobd_local Local OOB data or NULL if not set
2082 : * @param oobd_remote Remote OOB data or NULL if not set
2083 : *
2084 : * @return Zero on success or error code otherwise, positive in case of
2085 : * protocol error or negative (POSIX) in case of stack internal error.
2086 : */
2087 1 : int bt_le_oob_get_sc_data(struct bt_conn *conn,
2088 : const struct bt_le_oob_sc_data **oobd_local,
2089 : const struct bt_le_oob_sc_data **oobd_remote);
2090 :
2091 : /**
2092 : * Special passkey value that can be used to disable a previously
2093 : * set fixed passkey.
2094 : */
2095 1 : #define BT_PASSKEY_INVALID 0xffffffff
2096 :
2097 : /** @brief Set a fixed passkey to be used for pairing.
2098 : *
2099 : * This API is only available when the CONFIG_BT_FIXED_PASSKEY
2100 : * configuration option has been enabled.
2101 : *
2102 : * Sets a fixed passkey to be used for pairing. If set, the
2103 : * pairing_confirm() callback will be called for all incoming pairings.
2104 : *
2105 : * @param passkey A valid passkey (0 - 999999) or BT_PASSKEY_INVALID
2106 : * to disable a previously set fixed passkey.
2107 : *
2108 : * @return 0 on success or a negative error code on failure.
2109 : */
2110 1 : int bt_passkey_set(unsigned int passkey);
2111 :
2112 : /** Info Structure for OOB pairing */
2113 1 : struct bt_conn_oob_info {
2114 : /** Type of OOB pairing method */
2115 1 : enum {
2116 : /** LE legacy pairing */
2117 : BT_CONN_OOB_LE_LEGACY,
2118 :
2119 : /** LE SC pairing */
2120 : BT_CONN_OOB_LE_SC,
2121 1 : } type;
2122 :
2123 : union {
2124 : /** LE Secure Connections OOB pairing parameters */
2125 : struct {
2126 : /** OOB data configuration */
2127 : enum {
2128 : /** Local OOB data requested */
2129 : BT_CONN_OOB_LOCAL_ONLY,
2130 :
2131 : /** Remote OOB data requested */
2132 : BT_CONN_OOB_REMOTE_ONLY,
2133 :
2134 : /** Both local and remote OOB data requested */
2135 : BT_CONN_OOB_BOTH_PEERS,
2136 :
2137 : /** No OOB data requested */
2138 : BT_CONN_OOB_NO_DATA,
2139 1 : } oob_config;
2140 1 : } lesc;
2141 0 : };
2142 : };
2143 :
2144 : #if defined(CONFIG_BT_SMP_APP_PAIRING_ACCEPT)
2145 : /** @brief Pairing request and pairing response info structure.
2146 : *
2147 : * This structure is the same for both smp_pairing_req and smp_pairing_rsp
2148 : * and a subset of the packet data, except for the initial Code octet.
2149 : * It is documented in Core Spec. Vol. 3, Part H, 3.5.1 and 3.5.2.
2150 : */
2151 1 : struct bt_conn_pairing_feat {
2152 : /** IO Capability, Core Spec. Vol 3, Part H, 3.5.1, Table 3.4 */
2153 1 : uint8_t io_capability;
2154 :
2155 : /** OOB data flag, Core Spec. Vol 3, Part H, 3.5.1, Table 3.5 */
2156 1 : uint8_t oob_data_flag;
2157 :
2158 : /** AuthReq, Core Spec. Vol 3, Part H, 3.5.1, Fig. 3.3 */
2159 1 : uint8_t auth_req;
2160 :
2161 : /** Maximum Encryption Key Size, Core Spec. Vol 3, Part H, 3.5.1 */
2162 1 : uint8_t max_enc_key_size;
2163 :
2164 : /** Initiator Key Distribution/Generation, Core Spec. Vol 3, Part H,
2165 : * 3.6.1, Fig. 3.11
2166 : */
2167 1 : uint8_t init_key_dist;
2168 :
2169 : /** Responder Key Distribution/Generation, Core Spec. Vol 3, Part H
2170 : * 3.6.1, Fig. 3.11
2171 : */
2172 1 : uint8_t resp_key_dist;
2173 : };
2174 : #endif /* CONFIG_BT_SMP_APP_PAIRING_ACCEPT */
2175 :
2176 : /** Authenticated pairing callback structure */
2177 1 : struct bt_conn_auth_cb {
2178 : #if defined(CONFIG_BT_SMP_APP_PAIRING_ACCEPT)
2179 : /** @brief Query to proceed incoming pairing or not.
2180 : *
2181 : * On any incoming pairing req/rsp this callback will be called for
2182 : * the application to decide whether to allow for the pairing to
2183 : * continue.
2184 : *
2185 : * The pairing info received from the peer is passed to assist
2186 : * making the decision.
2187 : *
2188 : * As this callback is synchronous the application should return
2189 : * a response value immediately. Otherwise it may affect the
2190 : * timing during pairing. Hence, this information should not be
2191 : * conveyed to the user to take action.
2192 : *
2193 : * The remaining callbacks are not affected by this, but do notice
2194 : * that other callbacks can be called during the pairing. Eg. if
2195 : * pairing_confirm is registered both will be called for Just-Works
2196 : * pairings.
2197 : *
2198 : * This callback may be unregistered in which case pairing continues
2199 : * as if the Kconfig flag was not set.
2200 : *
2201 : * For BR/EDR Secure Simple Pairing (SSP), this callback is called
2202 : * when receiving the BT_HCI_EVT_IO_CAPA_REQ hci event.
2203 : *
2204 : * @param conn Connection where pairing is initiated.
2205 : * @param feat Pairing req/resp info.
2206 : */
2207 : enum bt_security_err (*pairing_accept)(struct bt_conn *conn,
2208 : const struct bt_conn_pairing_feat *const feat);
2209 : #endif /* CONFIG_BT_SMP_APP_PAIRING_ACCEPT */
2210 :
2211 : /** @brief Display a passkey to the user.
2212 : *
2213 : * When called the application is expected to display the given
2214 : * passkey to the user, with the expectation that the passkey will
2215 : * then be entered on the peer device. The passkey will be in the
2216 : * range of 0 - 999999, and is expected to be padded with zeroes so
2217 : * that six digits are always shown. E.g. the value 37 should be
2218 : * shown as 000037.
2219 : *
2220 : * This callback may be set to NULL, which means that the local
2221 : * device lacks the ability do display a passkey. If set
2222 : * to non-NULL the cancel callback must also be provided, since
2223 : * this is the only way the application can find out that it should
2224 : * stop displaying the passkey.
2225 : *
2226 : * @param conn Connection where pairing is currently active.
2227 : * @param passkey Passkey to show to the user.
2228 : */
2229 1 : void (*passkey_display)(struct bt_conn *conn, unsigned int passkey);
2230 :
2231 : #if defined(CONFIG_BT_PASSKEY_KEYPRESS)
2232 : /** @brief Receive Passkey Keypress Notification during pairing
2233 : *
2234 : * This allows the remote device to use the local device to give users
2235 : * feedback on the progress of entering the passkey over there. This is
2236 : * useful when the remote device itself has no display suitable for
2237 : * showing the progress.
2238 : *
2239 : * The handler of this callback is expected to keep track of the number
2240 : * of digits entered and show a password-field-like feedback to the
2241 : * user.
2242 : *
2243 : * This callback is only relevant while the local side does Passkey
2244 : * Display.
2245 : *
2246 : * The event type is verified to be in range of the enum. No other
2247 : * sanitization has been done. The remote could send a large number of
2248 : * events of any type in any order.
2249 : *
2250 : * @param conn The related connection.
2251 : * @param type Type of event. Verified in range of the enum.
2252 : */
2253 : void (*passkey_display_keypress)(struct bt_conn *conn,
2254 : enum bt_conn_auth_keypress type);
2255 : #endif
2256 :
2257 : /** @brief Request the user to enter a passkey.
2258 : *
2259 : * When called the user is expected to enter a passkey. The passkey
2260 : * must be in the range of 0 - 999999, and should be expected to
2261 : * be zero-padded, as that's how the peer device will typically be
2262 : * showing it (e.g. 37 would be shown as 000037).
2263 : *
2264 : * Once the user has entered the passkey its value should be given
2265 : * to the stack using the bt_conn_auth_passkey_entry() API.
2266 : *
2267 : * This callback may be set to NULL, which means that the local
2268 : * device lacks the ability to enter a passkey. If set to non-NULL
2269 : * the cancel callback must also be provided, since this is the
2270 : * only way the application can find out that it should stop
2271 : * requesting the user to enter a passkey.
2272 : *
2273 : * @param conn Connection where pairing is currently active.
2274 : */
2275 1 : void (*passkey_entry)(struct bt_conn *conn);
2276 :
2277 : /** @brief Request the user to confirm a passkey.
2278 : *
2279 : * When called the user is expected to confirm that the given
2280 : * passkey is also shown on the peer device.. The passkey will
2281 : * be in the range of 0 - 999999, and should be zero-padded to
2282 : * always be six digits (e.g. 37 would be shown as 000037).
2283 : *
2284 : * Once the user has confirmed the passkey to match, the
2285 : * bt_conn_auth_passkey_confirm() API should be called. If the
2286 : * user concluded that the passkey doesn't match the
2287 : * bt_conn_auth_cancel() API should be called.
2288 : *
2289 : * This callback may be set to NULL, which means that the local
2290 : * device lacks the ability to confirm a passkey. If set to non-NULL
2291 : * the cancel callback must also be provided, since this is the
2292 : * only way the application can find out that it should stop
2293 : * requesting the user to confirm a passkey.
2294 : *
2295 : * @param conn Connection where pairing is currently active.
2296 : * @param passkey Passkey to be confirmed.
2297 : */
2298 1 : void (*passkey_confirm)(struct bt_conn *conn, unsigned int passkey);
2299 :
2300 : /** @brief Request the user to provide Out of Band (OOB) data.
2301 : *
2302 : * When called the user is expected to provide OOB data. The required
2303 : * data are indicated by the information structure.
2304 : *
2305 : * For LE Secure Connections OOB pairing, the user should provide
2306 : * local OOB data, remote OOB data or both depending on their
2307 : * availability. Their value should be given to the stack using the
2308 : * bt_le_oob_set_sc_data() API.
2309 : *
2310 : * This callback must be set to non-NULL in order to support OOB
2311 : * pairing.
2312 : *
2313 : * @param conn Connection where pairing is currently active.
2314 : * @param info OOB pairing information.
2315 : */
2316 1 : void (*oob_data_request)(struct bt_conn *conn,
2317 : struct bt_conn_oob_info *info);
2318 :
2319 : /** @brief Cancel the ongoing user request.
2320 : *
2321 : * This callback will be called to notify the application that it
2322 : * should cancel any previous user request (passkey display, entry
2323 : * or confirmation).
2324 : *
2325 : * This may be set to NULL, but must always be provided whenever the
2326 : * passkey_display, passkey_entry passkey_confirm or pairing_confirm
2327 : * callback has been provided.
2328 : *
2329 : * @param conn Connection where pairing is currently active.
2330 : */
2331 1 : void (*cancel)(struct bt_conn *conn);
2332 :
2333 : /** @brief Request confirmation for an incoming pairing.
2334 : *
2335 : * This callback will be called to confirm an incoming pairing
2336 : * request where none of the other user callbacks is applicable.
2337 : *
2338 : * If the user decides to accept the pairing the
2339 : * bt_conn_auth_pairing_confirm() API should be called. If the
2340 : * user decides to reject the pairing the bt_conn_auth_cancel() API
2341 : * should be called.
2342 : *
2343 : * This callback may be set to NULL, which means that the local
2344 : * device lacks the ability to confirm a pairing request. If set
2345 : * to non-NULL the cancel callback must also be provided, since
2346 : * this is the only way the application can find out that it should
2347 : * stop requesting the user to confirm a pairing request.
2348 : *
2349 : * @param conn Connection where pairing is currently active.
2350 : */
2351 1 : void (*pairing_confirm)(struct bt_conn *conn);
2352 :
2353 : #if defined(CONFIG_BT_CLASSIC)
2354 : /** @brief Request the user to enter a passkey.
2355 : *
2356 : * This callback will be called for a BR/EDR (Bluetooth Classic)
2357 : * connection where pairing is being performed. Once called the
2358 : * user is expected to enter a PIN code with a length between
2359 : * 1 and 16 digits. If the @a highsec parameter is set to true
2360 : * the PIN code must be 16 digits long.
2361 : *
2362 : * Once entered, the PIN code should be given to the stack using
2363 : * the bt_conn_auth_pincode_entry() API.
2364 : *
2365 : * This callback may be set to NULL, however in that case pairing
2366 : * over BR/EDR will not be possible. If provided, the cancel
2367 : * callback must be provided as well.
2368 : *
2369 : * @param conn Connection where pairing is currently active.
2370 : * @param highsec true if 16 digit PIN is required.
2371 : */
2372 1 : void (*pincode_entry)(struct bt_conn *conn, bool highsec);
2373 : #endif
2374 : };
2375 :
2376 : /** Authenticated pairing information callback structure */
2377 1 : struct bt_conn_auth_info_cb {
2378 : /** @brief notify that pairing procedure was complete.
2379 : *
2380 : * This callback notifies the application that the pairing procedure
2381 : * has been completed.
2382 : *
2383 : * @param conn Connection object.
2384 : * @param bonded Bond information has been distributed during the
2385 : * pairing procedure.
2386 : */
2387 1 : void (*pairing_complete)(struct bt_conn *conn, bool bonded);
2388 :
2389 : /** @brief notify that pairing process has failed.
2390 : *
2391 : * @param conn Connection object.
2392 : * @param reason Pairing failed reason
2393 : */
2394 1 : void (*pairing_failed)(struct bt_conn *conn,
2395 : enum bt_security_err reason);
2396 :
2397 : /** @brief Notify that bond has been deleted.
2398 : *
2399 : * This callback notifies the application that the bond information
2400 : * for the remote peer has been deleted
2401 : *
2402 : * @param id Which local identity had the bond.
2403 : * @param peer Remote address.
2404 : */
2405 1 : void (*bond_deleted)(uint8_t id, const bt_addr_le_t *peer);
2406 :
2407 : /** Internally used field for list handling */
2408 1 : sys_snode_t node;
2409 : };
2410 :
2411 : /** @brief Register authentication callbacks.
2412 : *
2413 : * Register callbacks to handle authenticated pairing. Passing NULL
2414 : * unregisters a previous callbacks structure.
2415 : *
2416 : * @param cb Callback struct.
2417 : *
2418 : * @return Zero on success or negative error code otherwise
2419 : */
2420 1 : int bt_conn_auth_cb_register(const struct bt_conn_auth_cb *cb);
2421 :
2422 : /** @brief Overlay authentication callbacks used for a given connection.
2423 : *
2424 : * This function can be used only for Bluetooth LE connections.
2425 : * The @kconfig{CONFIG_BT_SMP} must be enabled for this function.
2426 : *
2427 : * The authentication callbacks for a given connection cannot be overlaid if
2428 : * security procedures in the SMP module have already started. This function
2429 : * can be called only once per connection.
2430 : *
2431 : * @param conn Connection object.
2432 : * @param cb Callback struct.
2433 : *
2434 : * @return Zero on success or negative error code otherwise
2435 : */
2436 1 : int bt_conn_auth_cb_overlay(struct bt_conn *conn, const struct bt_conn_auth_cb *cb);
2437 :
2438 : /** @brief Register authentication information callbacks.
2439 : *
2440 : * Register callbacks to get authenticated pairing information. Multiple
2441 : * registrations can be done.
2442 : *
2443 : * @param cb Callback struct.
2444 : *
2445 : * @return Zero on success or negative error code otherwise
2446 : */
2447 1 : int bt_conn_auth_info_cb_register(struct bt_conn_auth_info_cb *cb);
2448 :
2449 : /** @brief Unregister authentication information callbacks.
2450 : *
2451 : * Unregister callbacks to stop getting authenticated pairing information.
2452 : *
2453 : * @param cb Callback struct.
2454 : *
2455 : * @return Zero on success or negative error code otherwise
2456 : */
2457 1 : int bt_conn_auth_info_cb_unregister(struct bt_conn_auth_info_cb *cb);
2458 :
2459 : /** @brief Reply with entered passkey.
2460 : *
2461 : * This function should be called only after passkey_entry callback from
2462 : * bt_conn_auth_cb structure was called.
2463 : *
2464 : * @param conn Connection object.
2465 : * @param passkey Entered passkey.
2466 : *
2467 : * @return Zero on success or negative error code otherwise
2468 : */
2469 1 : int bt_conn_auth_passkey_entry(struct bt_conn *conn, unsigned int passkey);
2470 :
2471 : /** @brief Send Passkey Keypress Notification during pairing
2472 : *
2473 : * This function may be called only after passkey_entry callback from
2474 : * bt_conn_auth_cb structure was called.
2475 : *
2476 : * Requires @kconfig{CONFIG_BT_PASSKEY_KEYPRESS}.
2477 : *
2478 : * @param conn Destination for the notification.
2479 : * @param type What keypress event type to send. @see bt_conn_auth_keypress.
2480 : *
2481 : * @retval 0 Success
2482 : * @retval -EINVAL Improper use of the API.
2483 : * @retval -ENOMEM Failed to allocate.
2484 : * @retval -ENOBUFS Failed to allocate.
2485 : */
2486 1 : int bt_conn_auth_keypress_notify(struct bt_conn *conn, enum bt_conn_auth_keypress type);
2487 :
2488 : /** @brief Cancel ongoing authenticated pairing.
2489 : *
2490 : * This function allows to cancel ongoing authenticated pairing.
2491 : *
2492 : * @param conn Connection object.
2493 : *
2494 : * @return Zero on success or negative error code otherwise
2495 : */
2496 1 : int bt_conn_auth_cancel(struct bt_conn *conn);
2497 :
2498 : /** @brief Reply if passkey was confirmed to match by user.
2499 : *
2500 : * This function should be called only after passkey_confirm callback from
2501 : * bt_conn_auth_cb structure was called.
2502 : *
2503 : * @param conn Connection object.
2504 : *
2505 : * @return Zero on success or negative error code otherwise
2506 : */
2507 1 : int bt_conn_auth_passkey_confirm(struct bt_conn *conn);
2508 :
2509 : /** @brief Reply if incoming pairing was confirmed by user.
2510 : *
2511 : * This function should be called only after pairing_confirm callback from
2512 : * bt_conn_auth_cb structure was called if user confirmed incoming pairing.
2513 : *
2514 : * @param conn Connection object.
2515 : *
2516 : * @return Zero on success or negative error code otherwise
2517 : */
2518 1 : int bt_conn_auth_pairing_confirm(struct bt_conn *conn);
2519 :
2520 : /** @brief Reply with entered PIN code.
2521 : *
2522 : * This function should be called only after PIN code callback from
2523 : * bt_conn_auth_cb structure was called. It's for legacy 2.0 devices.
2524 : *
2525 : * @param conn Connection object.
2526 : * @param pin Entered PIN code.
2527 : *
2528 : * @return Zero on success or negative error code otherwise
2529 : */
2530 1 : int bt_conn_auth_pincode_entry(struct bt_conn *conn, const char *pin);
2531 :
2532 : /** Connection parameters for BR/EDR connections */
2533 1 : struct bt_br_conn_param {
2534 0 : bool allow_role_switch;
2535 : };
2536 :
2537 : /** @brief Initialize BR/EDR connection parameters
2538 : *
2539 : * @param role_switch True if role switch is allowed
2540 : */
2541 1 : #define BT_BR_CONN_PARAM_INIT(role_switch) \
2542 : { \
2543 : .allow_role_switch = (role_switch), \
2544 : }
2545 :
2546 : /** Helper to declare BR/EDR connection parameters inline
2547 : *
2548 : * @param role_switch True if role switch is allowed
2549 : */
2550 1 : #define BT_BR_CONN_PARAM(role_switch) \
2551 : ((struct bt_br_conn_param[]) { \
2552 : BT_BR_CONN_PARAM_INIT(role_switch) \
2553 : })
2554 :
2555 : /** Default BR/EDR connection parameters:
2556 : * Role switch allowed
2557 : */
2558 1 : #define BT_BR_CONN_PARAM_DEFAULT BT_BR_CONN_PARAM(true)
2559 :
2560 :
2561 : /** @brief Initiate an BR/EDR connection to a remote device.
2562 : *
2563 : * Allows initiate new BR/EDR link to remote peer using its address.
2564 : *
2565 : * The caller gets a new reference to the connection object which must be
2566 : * released with bt_conn_unref() once done using the object.
2567 : *
2568 : * @param peer Remote address.
2569 : * @param param Initial connection parameters.
2570 : *
2571 : * @return Valid connection object on success or NULL otherwise.
2572 : */
2573 1 : struct bt_conn *bt_conn_create_br(const bt_addr_t *peer,
2574 : const struct bt_br_conn_param *param);
2575 :
2576 : #ifdef __cplusplus
2577 : }
2578 : #endif
2579 :
2580 : /**
2581 : * @}
2582 : */
2583 :
2584 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_CONN_H_ */
|
