Line data Source code
1 1 : /**
2 : * @file
3 : * @brief Bluetooth subsystem core APIs.
4 : */
5 :
6 : /*
7 : * Copyright (c) 2017 Nordic Semiconductor ASA
8 : * Copyright (c) 2015-2016 Intel Corporation
9 : *
10 : * SPDX-License-Identifier: Apache-2.0
11 : */
12 : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_BLUETOOTH_H_
13 : #define ZEPHYR_INCLUDE_BLUETOOTH_BLUETOOTH_H_
14 :
15 : /**
16 : * @brief Bluetooth APIs
17 : *
18 : * @details The Bluetooth Subsystem Core APIs provide essential functionalities
19 : * to use and manage Bluetooth based communication. These APIs include
20 : * APIs for Bluetooth stack initialization, device discovery,
21 : * connection management, data transmission, profiles and services.
22 : * These APIs support both classic Bluetooth and Bluetooth Low Energy
23 : * (LE) operations.
24 : *
25 : * @defgroup bluetooth Bluetooth APIs
26 : * @ingroup connectivity
27 : * @{
28 : */
29 :
30 : #include <stdbool.h>
31 : #include <stdint.h>
32 : #include <string.h>
33 :
34 : #include <zephyr/bluetooth/gap.h>
35 : #include <zephyr/bluetooth/addr.h>
36 : #include <zephyr/bluetooth/crypto.h>
37 : #include <zephyr/bluetooth/hci_types.h>
38 : #include <zephyr/bluetooth/classic/classic.h>
39 : #include <zephyr/net_buf.h>
40 : #include <zephyr/sys/slist.h>
41 : #include <zephyr/sys/util.h>
42 : #include <zephyr/sys/util_macro.h>
43 : #include <zephyr/toolchain.h>
44 :
45 : #ifdef __cplusplus
46 : extern "C" {
47 : #endif
48 :
49 : /**
50 : * @brief Generic Access Profile (GAP)
51 : *
52 : * @details The Generic Access Profile (GAP) defines fundamental Bluetooth
53 : * operations, including device discovery, pairing, and connection
54 : * management. Zephyr's GAP implementation supports both classic
55 : * Bluetooth and Bluetooth Low Energy (LE) functionalities, enabling
56 : * roles such as Broadcaster, Observer, Peripheral, and Central. These
57 : * roles define the device's behavior in advertising, scanning, and
58 : * establishing connections within Bluetooth networks.
59 : *
60 : * @defgroup bt_gap Generic Access Profile (GAP)
61 : * @since 1.0
62 : * @version 1.0.0
63 : * @ingroup bluetooth
64 : * @{
65 : */
66 :
67 : /**
68 : * Identity handle referring to the first identity address. This is a convenience macro for
69 : * specifying the default identity address. This helps make the code more readable, especially when
70 : * only one identity address is supported.
71 : */
72 1 : #define BT_ID_DEFAULT 0
73 :
74 : /**
75 : * @brief Number of octets for local supported features
76 : *
77 : * The value of 8 correspond to page 0 in the LE Controller supported features.
78 : * 24 bytes are required for all subsequent supported feature pages.
79 : */
80 1 : #define BT_LE_LOCAL_SUPPORTED_FEATURES_SIZE \
81 : (BT_HCI_LE_BYTES_PAGE_0_FEATURE_PAGE + \
82 : COND_CODE_1(CONFIG_BT_LE_MAX_LOCAL_SUPPORTED_FEATURE_PAGE, \
83 : (CONFIG_BT_LE_MAX_LOCAL_SUPPORTED_FEATURE_PAGE \
84 : * BT_HCI_LE_BYTES_PER_FEATURE_PAGE), \
85 : (0U)))
86 :
87 : /** Opaque type representing an advertiser. */
88 : struct bt_le_ext_adv;
89 :
90 : /** Opaque type representing an periodic advertising sync. */
91 : struct bt_le_per_adv_sync;
92 :
93 : /* Don't require everyone to include conn.h */
94 : struct bt_conn;
95 :
96 : /* Don't require everyone to include iso.h */
97 : struct bt_iso_biginfo;
98 :
99 : /* Don't require everyone to include direction.h */
100 : struct bt_df_per_adv_sync_iq_samples_report;
101 :
102 : /**
103 : * @brief Info of the advertising sent event.
104 : *
105 : * @note Used in @ref bt_le_ext_adv_cb.
106 : */
107 1 : struct bt_le_ext_adv_sent_info {
108 : /**
109 : * If the advertising set was started with a non-zero
110 : * @ref bt_le_ext_adv_start_param.num_events, this field
111 : * contains the number of times this advertising set has
112 : * been sent since it was enabled.
113 : */
114 1 : uint8_t num_sent;
115 : };
116 :
117 : /**
118 : * @brief Info of the advertising connected event.
119 : *
120 : * @note Used in @ref bt_le_ext_adv_cb.
121 : */
122 1 : struct bt_le_ext_adv_connected_info {
123 : /** Connection object of the new connection */
124 1 : struct bt_conn *conn;
125 : };
126 :
127 : /**
128 : * @brief Info of the advertising scanned event.
129 : *
130 : * @note Used in @ref bt_le_ext_adv_cb.
131 : */
132 1 : struct bt_le_ext_adv_scanned_info {
133 : /** Active scanner LE address and type */
134 1 : bt_addr_le_t *addr;
135 : };
136 :
137 : /**
138 : * @brief Info of the PAwR subevents.
139 : *
140 : * @details When the Controller indicates it is ready to transmit one or more PAwR subevents,
141 : * @ref bt_le_per_adv_data_request holds the information about the first subevent data and the
142 : * number of subevents data can be set for.
143 : *
144 : * @note Used in @ref bt_le_ext_adv_cb.
145 : */
146 1 : struct bt_le_per_adv_data_request {
147 : /** The first subevent data can be set for */
148 1 : uint8_t start;
149 :
150 : /** The number of subevents data can be set for */
151 1 : uint8_t count;
152 : };
153 :
154 : /**
155 : * @brief Info about the PAwR responses received.
156 : *
157 : * @details When the Controller indicates that one or more synced devices have responded to a
158 : * periodic advertising subevent indication, @ref bt_le_per_adv_response_info holds the information
159 : * about the subevent in question, its status, TX power, RSSI of the response, the Constant Tone
160 : * Extension of the advertisement, and the slot the response was received in.
161 : *
162 : * @note Used in @ref bt_le_ext_adv_cb.
163 : */
164 1 : struct bt_le_per_adv_response_info {
165 : /** The subevent the response was received in */
166 1 : uint8_t subevent;
167 :
168 : /** @brief Status of the subevent indication.
169 : *
170 : * 0 if subevent indication was transmitted.
171 : * 1 if subevent indication was not transmitted.
172 : * All other values RFU.
173 : */
174 1 : uint8_t tx_status;
175 :
176 : /** The TX power of the response in dBm */
177 1 : int8_t tx_power;
178 :
179 : /** The RSSI of the response in dBm */
180 1 : int8_t rssi;
181 :
182 : /** The Constant Tone Extension (CTE) of the advertisement (@ref bt_df_cte_type) */
183 1 : uint8_t cte_type;
184 :
185 : /** The slot the response was received in */
186 1 : uint8_t response_slot;
187 : };
188 :
189 : /**
190 : * @brief Callback struct to notify about advertiser activity.
191 : *
192 : * @details The @ref bt_le_ext_adv_cb struct contains callback functions that are invoked in
193 : * response to various events related to the advertising set. These events include:
194 : * - Completion of advertising data transmission
195 : * - Acceptance of a new connection
196 : * - Transmission of scan response data
197 : * - If privacy is enabled:
198 : * - Expiration of the advertising set's validity
199 : * - If PAwR (Periodic Advertising with Response) is enabled:
200 : * - Readiness to send one or more PAwR subevents, namely the LE Periodic Advertising
201 : * Subevent Data Request event
202 : * - Response of synced devices to a periodic advertising subevent indication has been
203 : * received, namely the LE Periodic Advertising Response Report event
204 : *
205 : * @note Must point to valid memory during the lifetime of the advertising set.
206 : *
207 : * @note Used in @ref bt_le_ext_adv_create.
208 : */
209 1 : struct bt_le_ext_adv_cb {
210 : /**
211 : * @brief The advertising set was disabled after reaching limit
212 : *
213 : * This callback is invoked when the limit set in
214 : * @ref bt_le_ext_adv_start_param.timeout or
215 : * @ref bt_le_ext_adv_start_param.num_events is reached.
216 : *
217 : * @param adv The advertising set object.
218 : * @param info Information about the sent event.
219 : */
220 1 : void (*sent)(struct bt_le_ext_adv *adv,
221 : struct bt_le_ext_adv_sent_info *info);
222 :
223 : /**
224 : * @brief The advertising set has accepted a new connection.
225 : *
226 : * This callback notifies the application that the advertising set has
227 : * accepted a new connection.
228 : *
229 : * @param adv The advertising set object.
230 : * @param info Information about the connected event.
231 : */
232 1 : void (*connected)(struct bt_le_ext_adv *adv,
233 : struct bt_le_ext_adv_connected_info *info);
234 :
235 : /**
236 : * @brief The advertising set has sent scan response data.
237 : *
238 : * This callback notifies the application that the advertising set has
239 : * has received a Scan Request packet, and has sent a Scan Response
240 : * packet.
241 : *
242 : * @param adv The advertising set object.
243 : * @param info Information about the scanned event, namely the address.
244 : */
245 1 : void (*scanned)(struct bt_le_ext_adv *adv,
246 : struct bt_le_ext_adv_scanned_info *info);
247 :
248 : #if defined(CONFIG_BT_PRIVACY)
249 : /**
250 : * @brief The RPA validity of the advertising set has expired.
251 : *
252 : * This callback notifies the application that the RPA validity of the advertising set has
253 : * expired. The user can use this callback to synchronize the advertising payload update
254 : * with the RPA rotation by for example invoking @ref bt_le_ext_adv_set_data upon callback.
255 : *
256 : * If RPA sharing is enabled (see @kconfig{CONFIG_BT_RPA_SHARING}) and this RPA expired
257 : * callback of any adv-sets belonging to same adv id returns false, then adv-sets will
258 : * continue with the old RPA throughout the RPA rotations.
259 : *
260 : * @param adv The advertising set object.
261 : *
262 : * @return true to rotate the current RPA, or false to use it for the
263 : * next rotation period.
264 : */
265 : bool (*rpa_expired)(struct bt_le_ext_adv *adv);
266 : #endif /* defined(CONFIG_BT_PRIVACY) */
267 :
268 : #if defined(CONFIG_BT_PER_ADV_RSP)
269 : /**
270 : * @brief The Controller indicates it is ready to transmit one or more PAwR subevents.
271 : *
272 : * This callback notifies the application that the controller has requested
273 : * data for upcoming subevents.
274 : *
275 : * @param adv The advertising set object.
276 : * @param request Information about the upcoming subevents.
277 : */
278 : void (*pawr_data_request)(struct bt_le_ext_adv *adv,
279 : const struct bt_le_per_adv_data_request *request);
280 : /**
281 : * @brief The Controller indicates that one or more synced devices have
282 : * responded to a periodic advertising subevent indication.
283 : *
284 : * @param adv The advertising set object.
285 : * @param info Information about the responses received.
286 : * @param buf The received data. NULL if the controller reported
287 : * that it did not receive any response.
288 : */
289 : void (*pawr_response)(struct bt_le_ext_adv *adv, struct bt_le_per_adv_response_info *info,
290 : struct net_buf_simple *buf);
291 :
292 : #endif /* defined(CONFIG_BT_PER_ADV_RSP) */
293 : };
294 :
295 : /**
296 : * @typedef bt_ready_cb_t
297 : * @brief Callback for notifying that Bluetooth has been enabled.
298 : *
299 : * @param err zero on success or (negative) error code otherwise.
300 : */
301 1 : typedef void (*bt_ready_cb_t)(int err);
302 :
303 : /**
304 : * @brief Enable Bluetooth
305 : *
306 : * Enable Bluetooth. Must be the called before any calls that
307 : * require communication with the local Bluetooth hardware.
308 : *
309 : * When @kconfig{CONFIG_BT_SETTINGS} is enabled, the application must load the
310 : * Bluetooth settings after this API call successfully completes before
311 : * Bluetooth APIs can be used. Loading the settings before calling this function
312 : * is insufficient. Bluetooth settings can be loaded with @ref settings_load or
313 : * @ref settings_load_subtree with argument "bt". The latter selectively loads only
314 : * Bluetooth settings and is recommended if @ref settings_load has been called
315 : * earlier.
316 : *
317 : * @param cb Callback to notify completion or NULL to perform the
318 : * enabling synchronously. The callback is called from the system workqueue.
319 : *
320 : * @return Zero on success or (negative) error code otherwise.
321 : */
322 1 : int bt_enable(bt_ready_cb_t cb);
323 :
324 : /**
325 : * @brief Disable Bluetooth
326 : *
327 : * Disable Bluetooth. Can't be called before bt_enable has completed.
328 : *
329 : * This API will clear all configured identity addresses and keys that are not persistently
330 : * stored with @kconfig{CONFIG_BT_SETTINGS}. These can be restored
331 : * with @ref settings_load before reenabling the stack.
332 : *
333 : * This API does _not_ clear previously registered callbacks
334 : * like @ref bt_le_scan_cb_register, @ref bt_conn_cb_register
335 : * AND @ref bt_br_discovery_cb_register.
336 : * That is, the application shall not re-register them when
337 : * the Bluetooth subsystem is re-enabled later.
338 : *
339 : * Close and release HCI resources. Result is architecture dependent.
340 : *
341 : * @return Zero on success or (negative) error code otherwise.
342 : */
343 1 : int bt_disable(void);
344 :
345 : /**
346 : * @brief Check if Bluetooth is ready
347 : *
348 : * @return true when Bluetooth is ready, false otherwise
349 : */
350 1 : bool bt_is_ready(void);
351 :
352 : /**
353 : * @brief Set Bluetooth Device Name
354 : *
355 : * Set Bluetooth GAP Device Name.
356 : *
357 : * @note The advertising data is not automatically updated. When advertising with device name in the
358 : * advertising data, the name should be updated by calling @ref bt_le_adv_update_data or
359 : * @ref bt_le_ext_adv_set_data after the call to this function.
360 : *
361 : * @kconfig_dep{CONFIG_BT_DEVICE_NAME_DYNAMIC}
362 : *
363 : * @sa @kconfig{CONFIG_BT_DEVICE_NAME_MAX}.
364 : *
365 : * @param name New name, must be null terminated
366 : *
367 : * @return Zero on success or (negative) error code otherwise.
368 : */
369 1 : int bt_set_name(const char *name);
370 :
371 : /**
372 : * @brief Get Bluetooth Device Name
373 : *
374 : * Get Bluetooth GAP Device Name.
375 : *
376 : * @return Bluetooth Device Name
377 : */
378 1 : const char *bt_get_name(void);
379 :
380 : /**
381 : * @brief Get local Bluetooth appearance
382 : *
383 : * Bluetooth Appearance is a description of the external appearance of a device
384 : * in terms of an Appearance Value.
385 : *
386 : * @see Section 2.6 of the Bluetooth SIG Assigned Numbers document.
387 : *
388 : * @returns Appearance Value of local Bluetooth host.
389 : */
390 1 : uint16_t bt_get_appearance(void);
391 :
392 : /**
393 : * @brief Set local Bluetooth appearance
394 : *
395 : * Automatically preserves the new appearance across reboots if
396 : * @kconfig{CONFIG_BT_SETTINGS} is enabled.
397 : *
398 : * @kconfig_dep{CONFIG_BT_DEVICE_APPEARANCE_DYNAMIC}
399 : *
400 : * @param new_appearance Appearance Value
401 : *
402 : * @retval 0 Success.
403 : * @retval other Persistent storage failed. Appearance was not updated.
404 : */
405 1 : int bt_set_appearance(uint16_t new_appearance);
406 :
407 : /**
408 : * @brief Get the currently configured identity addresses.
409 : *
410 : * Returns an array of the currently configured identity addresses. To
411 : * make sure all available identity addresses can be retrieved, the number of
412 : * elements in the @a addrs array should be @kconfig{CONFIG_BT_ID_MAX}. The identity
413 : * handle that some APIs expect (such as @ref bt_le_adv_param) is
414 : * simply the index of the identity address in the @a addrs array.
415 : *
416 : * If @a addrs is passed as NULL, then the returned @a count contains the
417 : * count of all available identity addresses that can be retrieved with a
418 : * subsequent call to this function with non-NULL @a addrs parameter.
419 : *
420 : * @note Deleted identity addresses may show up as @ref BT_ADDR_LE_ANY in the returned array.
421 : *
422 : * @param addrs Array where to store the configured identity addresses.
423 : * @param count Should be initialized to the array size. Once the function returns
424 : * it will contain the number of returned identity addresses.
425 : */
426 1 : void bt_id_get(bt_addr_le_t *addrs, size_t *count);
427 :
428 : /**
429 : * @brief Create a new identity address.
430 : *
431 : * Create a new identity address using the given address and IRK. This function can be
432 : * called before calling @ref bt_enable. However, the new identity address will only be
433 : * stored persistently in flash when this API is used after @ref bt_enable. The
434 : * reason is that the persistent settings are loaded after @ref bt_enable and would
435 : * therefore cause potential conflicts with the stack blindly overwriting what's
436 : * stored in flash. The identity address will also not be written to flash in case a
437 : * pre-defined address is provided, since in such a situation the app clearly
438 : * has some place it got the address from and will be able to repeat the
439 : * procedure on every power cycle, i.e. it would be redundant to also store the
440 : * information in flash.
441 : *
442 : * Generating random static address or random IRK is not supported when calling
443 : * this function before @ref bt_enable.
444 : *
445 : * If the application wants to have the stack randomly generate identity addresses
446 : * and store them in flash for later recovery, the way to do it would be
447 : * to first initialize the stack (using bt_enable), then call @ref settings_load,
448 : * and after that check with @ref bt_id_get how many identity addresses were recovered.
449 : * If an insufficient amount of identity addresses were recovered the app may then
450 : * call this function to create new ones.
451 : *
452 : * @note If @kconfig{CONFIG_BT_HCI_SET_PUBLIC_ADDR} is enabled, the first call can set a
453 : * public address as the controller's identity, but only before @ref bt_enable and if
454 : * no other identities exist.
455 : *
456 : * @param addr Address to use for the new identity address. If NULL or initialized
457 : * to BT_ADDR_LE_ANY the stack will generate a new random static address
458 : * for the identity address and copy it to the given parameter upon return
459 : * from this function (in case the parameter was non-NULL).
460 : * @param irk Identity Resolving Key (16 octets) to be used with this
461 : * identity address. If set to all zeroes or NULL, the stack will
462 : * generate a random IRK for the identity address and copy it back
463 : * to the parameter upon return from this function (in case
464 : * the parameter was non-NULL). If privacy
465 : * @kconfig{CONFIG_BT_PRIVACY} is not enabled this parameter must
466 : * be NULL.
467 : *
468 : * @return Identity handle (>= 0) in case of success, or a negative error code on failure.
469 : */
470 1 : int bt_id_create(bt_addr_le_t *addr, uint8_t *irk);
471 :
472 : /**
473 : * @brief Reset/reclaim an identity address for reuse.
474 : *
475 : * When given an existing identity handle, this function will disconnect any connections (to the
476 : * corresponding identity address) created using it, remove any pairing keys or other data
477 : * associated with it, and then create a new identity address in the same slot, based on the @a addr
478 : * and @a irk parameters.
479 : *
480 : * @note The default identity address (corresponding to @ref BT_ID_DEFAULT) cannot be reset, and
481 : * this API will return an error if asked to do that.
482 : *
483 : * @param id Existing identity handle.
484 : * @param addr Address to use for the new identity address. If NULL or initialized
485 : * to BT_ADDR_LE_ANY the stack will generate a new static random
486 : * address for the identity address and copy it to the given
487 : * parameter upon return from this function.
488 : * @param irk Identity Resolving Key (16 octets) to be used with this
489 : * identity address. If set to all zeroes or NULL, the stack will
490 : * generate a random IRK for the identity address and copy it back
491 : * to the parameter upon return from this function (in case
492 : * the parameter was non-NULL). If privacy
493 : * @kconfig{CONFIG_BT_PRIVACY} is not enabled this parameter must
494 : * be NULL.
495 : *
496 : * @return Identity handle (>= 0) in case of success, or a negative error code on failure.
497 : */
498 1 : int bt_id_reset(uint8_t id, bt_addr_le_t *addr, uint8_t *irk);
499 :
500 : /**
501 : * @brief Delete an identity address.
502 : *
503 : * When given a valid identity handle this function will disconnect any connections
504 : * (to the corresponding identity address) created using it, remove any pairing keys
505 : * or other data associated with it, and then flag is as deleted, so that it can not
506 : * be used for any operations. To take back into use the slot the identity address was
507 : * occupying, the @ref bt_id_reset API needs to be used.
508 : *
509 : * @note The default identity address (corresponding to @ref BT_ID_DEFAULT) cannot be deleted, and
510 : * this API will return an error if asked to do that.
511 : *
512 : * @param id Existing identity handle.
513 : *
514 : * @return 0 in case of success, or a negative error code on failure.
515 : */
516 1 : int bt_id_delete(uint8_t id);
517 :
518 : /**
519 : * @brief Bluetooth data serialized size.
520 : *
521 : * Get the size of a serialized @ref bt_data given its data length.
522 : *
523 : * Size of 'AD Structure'->'Length' field, equal to 1.
524 : * Size of 'AD Structure'->'Data'->'AD Type' field, equal to 1.
525 : * Size of 'AD Structure'->'Data'->'AD Data' field, equal to data_len.
526 : *
527 : * See Core Specification Version 5.4 Vol. 3 Part C, 11, Figure 11.1.
528 : */
529 1 : #define BT_DATA_SERIALIZED_SIZE(data_len) ((data_len) + 2)
530 :
531 : /**
532 : * @brief Bluetooth data.
533 : *
534 : * @details Description of different AD Types that can be encoded into advertising data. Used to
535 : * form arrays that are passed to the @ref bt_le_adv_start function. The @ref BT_DATA define can
536 : * be used as a helpter to declare the elements of an @ref bt_data array.
537 : */
538 1 : struct bt_data {
539 : /** Type of scan response data or advertisement data. */
540 1 : uint8_t type;
541 : /** Length of scan response data or advertisement data. */
542 1 : uint8_t data_len;
543 : /** Pointer to Scan response or advertisement data. */
544 1 : const uint8_t *data;
545 : };
546 :
547 : /**
548 : * @brief Helper to declare elements of bt_data arrays
549 : *
550 : * This macro is mainly for creating an array of struct bt_data
551 : * elements which is then passed to e.g. @ref bt_le_adv_start function.
552 : *
553 : * @param _type Type of advertising data field
554 : * @param _data Pointer to the data field payload
555 : * @param _data_len Number of octets behind the _data pointer
556 : */
557 1 : #define BT_DATA(_type, _data, _data_len) \
558 : { \
559 : .type = (_type), \
560 : .data_len = (_data_len), \
561 : .data = (const uint8_t *)(_data), \
562 : }
563 :
564 : /**
565 : * @brief Helper to declare elements of bt_data arrays
566 : *
567 : * This macro is mainly for creating an array of struct bt_data
568 : * elements which is then passed to e.g. @ref bt_le_adv_start function.
569 : *
570 : * @param _type Type of advertising data field
571 : * @param _bytes Variable number of single-byte parameters
572 : */
573 1 : #define BT_DATA_BYTES(_type, _bytes...) \
574 : BT_DATA(_type, ((uint8_t []) { _bytes }), \
575 : sizeof((uint8_t []) { _bytes }))
576 :
577 : /**
578 : * @brief Get the total size (in octets) of a given set of @ref bt_data
579 : * structures.
580 : *
581 : * The total size includes the length (1 octet) and type (1 octet) fields for each element, plus
582 : * their respective data lengths.
583 : *
584 : * @param[in] data Array of @ref bt_data structures.
585 : * @param[in] data_count Number of @ref bt_data structures in @p data.
586 : *
587 : * @return Size of the concatenated data, built from the @ref bt_data structure set.
588 : */
589 1 : size_t bt_data_get_len(const struct bt_data data[], size_t data_count);
590 :
591 : /**
592 : * @brief Serialize a @ref bt_data struct into an advertising structure (a flat array).
593 : *
594 : * The data are formatted according to the Bluetooth Core Specification v. 5.4,
595 : * vol. 3, part C, 11.
596 : *
597 : * @param[in] input Single @ref bt_data structure to read from.
598 : * @param[out] output Buffer large enough to store the advertising structure in
599 : * @p input. The size of it must be at least the size of the
600 : * `input->data_len + 2` (for the type and the length).
601 : *
602 : * @return Number of octets written in @p output.
603 : */
604 1 : size_t bt_data_serialize(const struct bt_data *input, uint8_t *output);
605 :
606 : /**
607 : * @brief Local Bluetooth LE controller features and capabilities.
608 : *
609 : * @details This struct provides details about the Bluetooth LE controller's supported features,
610 : * states, and various other capabilities. It includes information on ACL and ISO data packet
611 : * lengths, the controller's resolving list size, and the maximum advertising data length. This
612 : * information can be obtained after enabling the Bluetooth stack with @ref bt_enable function.
613 : *
614 : * Refer to the Bluetooth Core Specification, Volume 6, Part B and Volume 4, Part E for detailed
615 : * sections about each field's significance and values.
616 : */
617 1 : struct bt_le_local_features {
618 : /**
619 : * @brief Local LE controller supported features.
620 : *
621 : * Refer to BT_LE_FEAT_BIT_* for values.
622 : * Refer to the BT_FEAT_LE_* macros for value comparionson.
623 : * See Bluetooth Core Specification, Vol 6, Part B, Section 4.6.
624 : */
625 1 : uint8_t features[BT_LE_LOCAL_SUPPORTED_FEATURES_SIZE];
626 :
627 : /**
628 : * @brief Local LE controller supported states
629 : *
630 : * Refer to BT_LE_STATES_* for values.
631 : * See Bluetooth Core Specification 6.0, Vol 4, Part E, Section 7.8.27
632 : */
633 1 : uint64_t states;
634 :
635 : /**
636 : * @brief ACL data packet length
637 : *
638 : * This represents the maximum ACL HCI Data packet which can be sent from the Host to the
639 : * Controller.
640 : * The Host may support L2CAP and ATT MTUs larger than this value.
641 : * See Bluetooth Core Specification, Vol 6, Part E, Section 7.8.2.
642 : */
643 1 : uint16_t acl_mtu;
644 : /** Total number of ACL data packets */
645 1 : uint8_t acl_pkts;
646 :
647 : /**
648 : * @brief ISO data packet length
649 : *
650 : * This represents the maximum ISO HCI Data packet which can be sent from the Host to the
651 : * Controller.
652 : * ISO SDUs above this size can be fragmented assuming that the number of
653 : * @ref bt_le_local_features.iso_pkts support the maximum size.
654 : */
655 1 : uint16_t iso_mtu;
656 : /** Total number of ISO data packets */
657 1 : uint8_t iso_pkts;
658 :
659 : /**
660 : * @brief Maximum size of the controller resolving list.
661 : *
662 : * See Bluetooth Core Specification, Vol 6, Part E, Section 7.8.41.
663 : */
664 1 : uint8_t rl_size;
665 :
666 : /**
667 : * @brief Maximum advertising data length
668 : *
669 : * @note The maximum advertising data length also depends on advertising type.
670 : *
671 : * See Bluetooth Core Specification, Vol 6, Part E, Section 7.8.57.
672 : */
673 1 : uint16_t max_adv_data_len;
674 : };
675 :
676 : /**
677 : * @brief Get local Bluetooth LE controller features
678 : *
679 : * Can only be called after @ref bt_enable.
680 : *
681 : * @param local_features Local features struct to be populated with information.
682 : *
683 : * @retval 0 Success
684 : * @retval -EAGAIN The information is not yet available.
685 : * @retval -EINVAL @p local_features is NULL.
686 : */
687 1 : int bt_le_get_local_features(struct bt_le_local_features *local_features);
688 :
689 : /** Advertising options */
690 1 : enum bt_le_adv_opt {
691 : /** Convenience value when no options are specified. */
692 : BT_LE_ADV_OPT_NONE = 0,
693 :
694 : /**
695 : * @brief Connectable advertising
696 : *
697 : * Starting connectable advertising preallocates a connection
698 : * object. If this fails, the API returns @c -ENOMEM.
699 : * Stopping connectable advertising will free the connection object,
700 : * and will trigger a call to @ref bt_conn_cb.recycled.
701 : *
702 : * The advertising set stops immediately after it creates a
703 : * connection. This happens automatically in the controller.
704 : *
705 : * @note To continue advertising after a connection is created,
706 : * the application should listen for the @ref bt_conn_cb.connected
707 : * event and start the advertising set again. Note that the
708 : * advertiser cannot be started when all connection objects are
709 : * in use. In that case, defer starting the advertiser until
710 : * @ref bt_conn_cb.recycled. To continue after a disconnection,
711 : * listen for @ref bt_conn_cb.recycled.
712 :
713 : */
714 : BT_LE_ADV_OPT_CONN = BIT(0) | BIT(1),
715 :
716 : /**
717 : * @brief Advertise using identity address.
718 : *
719 : * Advertise using the identity address as the advertiser address.
720 : * @warning This will compromise the privacy of the device, so care
721 : * must be taken when using this option.
722 : * @note The address used for advertising will not be the same as
723 : * returned by @ref bt_le_oob_get_local, instead @ref bt_id_get
724 : * should be used to get the LE address.
725 : */
726 : BT_LE_ADV_OPT_USE_IDENTITY = BIT(2),
727 :
728 : /**
729 : * @brief Low duty cycle directed advertising.
730 : *
731 : * Use low duty directed advertising mode, otherwise high duty mode
732 : * will be used.
733 : */
734 : BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY = BIT(4),
735 :
736 : /**
737 : * @brief Directed advertising to privacy-enabled peer.
738 : *
739 : * Enable use of Resolvable Private Address (RPA) as the target address
740 : * in directed advertisements.
741 : * This is required if the remote device is privacy-enabled and
742 : * supports address resolution of the target address in directed
743 : * advertisement.
744 : * It is the responsibility of the application to check that the remote
745 : * device supports address resolution of directed advertisements by
746 : * reading its Central Address Resolution characteristic.
747 : */
748 : BT_LE_ADV_OPT_DIR_ADDR_RPA = BIT(5),
749 :
750 : /** Use filter accept list to filter devices that can request scan
751 : * response data.
752 : */
753 : BT_LE_ADV_OPT_FILTER_SCAN_REQ = BIT(6),
754 :
755 : /** Use filter accept list to filter devices that can connect. */
756 : BT_LE_ADV_OPT_FILTER_CONN = BIT(7),
757 :
758 : /** Notify the application when a scan response data has been sent to an
759 : * active scanner.
760 : */
761 : BT_LE_ADV_OPT_NOTIFY_SCAN_REQ = BIT(8),
762 :
763 : /**
764 : * @brief Support scan response data.
765 : *
766 : * When used together with @ref BT_LE_ADV_OPT_EXT_ADV then this option
767 : * cannot be used together with the @ref BT_LE_ADV_OPT_CONN option.
768 : * When used together with @ref BT_LE_ADV_OPT_EXT_ADV then scan
769 : * response data must be set.
770 : */
771 : BT_LE_ADV_OPT_SCANNABLE = BIT(9),
772 :
773 : /**
774 : * @brief Advertise with extended advertising.
775 : *
776 : * This options enables extended advertising in the advertising set.
777 : * In extended advertising the advertising set will send a small header
778 : * packet on the three primary advertising channels. This small header
779 : * points to the advertising data packet that will be sent on one of
780 : * the 37 secondary advertising channels.
781 : * The advertiser will send primary advertising on LE 1M PHY, and
782 : * secondary advertising on LE 2M PHY.
783 : * Connections will be established on LE 2M PHY.
784 : *
785 : * Without this option the advertiser will send advertising data on the
786 : * three primary advertising channels.
787 : *
788 : * @note Enabling this option requires extended advertising support in
789 : * the peer devices scanning for advertisement packets.
790 : *
791 : * @note This cannot be used with @ref bt_le_adv_start.
792 : */
793 : BT_LE_ADV_OPT_EXT_ADV = BIT(10),
794 :
795 : /**
796 : * @brief Disable use of LE 2M PHY on the secondary advertising
797 : * channel.
798 : *
799 : * Disabling the use of LE 2M PHY could be necessary if scanners don't
800 : * support the LE 2M PHY.
801 : * The advertiser will send primary advertising on LE 1M PHY, and
802 : * secondary advertising on LE 1M PHY.
803 : * Connections will be established on LE 1M PHY.
804 : *
805 : * @note Cannot be set if BT_LE_ADV_OPT_CODED is set.
806 : *
807 : * @note Requires @ref BT_LE_ADV_OPT_EXT_ADV bit (see @ref bt_le_adv_opt field) to be
808 : * set as @ref bt_le_adv_param.options.
809 : */
810 : BT_LE_ADV_OPT_NO_2M = BIT(11),
811 :
812 : /**
813 : * @brief Advertise on the LE Coded PHY (Long Range).
814 : *
815 : * The advertiser will send both primary and secondary advertising
816 : * on the LE Coded PHY. This gives the advertiser increased range with
817 : * the trade-off of lower data rate and higher power consumption.
818 : * Connections will be established on LE Coded PHY.
819 : *
820 : * @note Requires @ref BT_LE_ADV_OPT_EXT_ADV bit (see @ref bt_le_adv_opt field) to be
821 : * set as @ref bt_le_adv_param.options.
822 : */
823 : BT_LE_ADV_OPT_CODED = BIT(12),
824 :
825 : /**
826 : * @brief Advertise without a device address (identity address or RPA).
827 : *
828 : * @note Requires @ref BT_LE_ADV_OPT_EXT_ADV bit (see @ref bt_le_adv_opt field) to be
829 : * set as @ref bt_le_adv_param.options.
830 : */
831 : BT_LE_ADV_OPT_ANONYMOUS = BIT(13),
832 :
833 : /**
834 : * @brief Advertise with transmit power.
835 : *
836 : * @note Requires @ref BT_LE_ADV_OPT_EXT_ADV bit (see @ref bt_le_adv_opt field) to be
837 : * set as @ref bt_le_adv_param.options.
838 : */
839 : BT_LE_ADV_OPT_USE_TX_POWER = BIT(14),
840 :
841 : /** Disable advertising on channel index 37. */
842 : BT_LE_ADV_OPT_DISABLE_CHAN_37 = BIT(15),
843 :
844 : /** Disable advertising on channel index 38. */
845 : BT_LE_ADV_OPT_DISABLE_CHAN_38 = BIT(16),
846 :
847 : /** Disable advertising on channel index 39. */
848 : BT_LE_ADV_OPT_DISABLE_CHAN_39 = BIT(17),
849 :
850 : /**
851 : * @brief Advertise using a Non-Resolvable Private Address.
852 : *
853 : * A new NRPA is set when updating the advertising parameters.
854 : *
855 : * This is an advanced feature; most users will want to enable
856 : * @kconfig{CONFIG_BT_EXT_ADV} instead.
857 : *
858 : * @note Not implemented when @kconfig{CONFIG_BT_PRIVACY}.
859 : *
860 : * @note Mutually exclusive with BT_LE_ADV_OPT_USE_IDENTITY.
861 : */
862 : BT_LE_ADV_OPT_USE_NRPA = BIT(19),
863 :
864 : /**
865 : * @brief Configures the advertiser to use the S=2 coding scheme for
866 : * LE Coded PHY.
867 : *
868 : * Sets the advertiser's required coding scheme to S=2, which is one
869 : * of the coding options available for LE Coded PHY. The S=2 coding
870 : * scheme offers higher data rates compared to S=8, with a trade-off
871 : * of reduced range. The coding scheme will only be set if both the
872 : * primary and secondary advertising channels indicate LE Coded Phy.
873 : * Additionally, the Controller must support the LE Feature Advertising
874 : * Coding Selection. If these conditions are not met, it will default to
875 : * no required coding scheme.
876 : *
877 : * @kconfig_dep{BT_EXT_ADV_CODING_SELECTION}
878 : */
879 : BT_LE_ADV_OPT_REQUIRE_S2_CODING = BIT(20),
880 :
881 : /**
882 : * @brief Configures the advertiser to use the S=8 coding scheme for
883 : * LE Coded PHY.
884 : *
885 : * Sets the advertiser's required coding scheme to S=8, which is one
886 : * of the coding options available for LE Coded PHY. The S=8 coding
887 : * scheme offers increased range compared to S=2, with a trade-off
888 : * of lower data rates. The coding scheme will only be set if both the
889 : * primary and secondary advertising channels indicate LE Coded Phy.
890 : * Additionally, the Controller must support the LE Feature Advertising
891 : * Coding Selection. If these conditions are not met, it will default to
892 : * no required coding scheme.
893 : *
894 : * @kconfig_dep{BT_EXT_ADV_CODING_SELECTION}
895 : */
896 : BT_LE_ADV_OPT_REQUIRE_S8_CODING = BIT(21),
897 : };
898 :
899 : /** LE Advertising Parameters. */
900 1 : struct bt_le_adv_param {
901 : /**
902 : * @brief Local identity handle.
903 : *
904 : * The index of the identity address in the local Bluetooth controller.
905 : *
906 : * @note When extended advertising @kconfig{CONFIG_BT_EXT_ADV} is not
907 : * enabled or not supported by the controller it is not possible
908 : * to scan and advertise simultaneously using two different
909 : * random addresses.
910 : */
911 1 : uint8_t id;
912 :
913 : /**
914 : * @brief Advertising Set Identifier, valid range is @ref BT_GAP_SID_MIN to
915 : * @ref BT_GAP_SID_MAX.
916 : *
917 : * @note Requires @ref BT_LE_ADV_OPT_EXT_ADV bit (see @ref bt_le_adv_opt field) to be
918 : *set as @ref bt_le_adv_param.options.
919 : **/
920 1 : uint8_t sid;
921 :
922 : /**
923 : * @brief Secondary channel maximum skip count.
924 : *
925 : * Maximum advertising events the advertiser can skip before it must
926 : * send advertising data on the secondary advertising channel.
927 : *
928 : * @note Requires @ref BT_LE_ADV_OPT_EXT_ADV bit (see @ref bt_le_adv_opt field) to be
929 : * set as @ref bt_le_adv_param.options.
930 : */
931 1 : uint8_t secondary_max_skip;
932 :
933 : /** @brief Bit-field of advertising options, see the @ref bt_le_adv_opt field. */
934 1 : uint32_t options;
935 :
936 : /**
937 : * @brief Minimum Advertising Interval (N * 0.625 milliseconds)
938 : *
939 : * @details The Minimum Advertising Interval shall be less than or equal to the Maximum
940 : * Advertising Interval. The Minimum Advertising Interval and Maximum Advertising Interval
941 : * aren't recommended to be the same value to enable the Controller to determine the best
942 : * advertising interval given other activities.
943 : * (See Bluetooth Core Spec 6.0, Vol 4, Part E, section 7.8.5)
944 : * Range: 0x0020 to 0x4000
945 : */
946 1 : uint32_t interval_min;
947 :
948 : /**
949 : * @brief Maximum Advertising Interval (N * 0.625 milliseconds)
950 : *
951 : * @details The Maximum Advertising Interval shall be more than or equal to the Minimum
952 : * Advertising Interval. The Minimum Advertising Interval and Maximum Advertising Interval
953 : * aren't recommended to be the same value to enable the Controller to determine the best
954 : * advertising interval given other activities.
955 : * (See Bluetooth Core Spec 6.0, Vol 4, Part E, section 7.8.5)
956 : * Range: 0x0020 to 0x4000
957 : */
958 1 : uint32_t interval_max;
959 :
960 : /**
961 : * @brief Directed advertising to peer
962 : *
963 : * When this parameter is set the advertiser will send directed
964 : * advertising to the remote device.
965 : *
966 : * The advertising type will either be high duty cycle, or low duty
967 : * cycle if the @ref BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY option is enabled.
968 : * When using @ref BT_LE_ADV_OPT_EXT_ADV then only low duty cycle is
969 : * allowed.
970 : *
971 : * In case of connectable high duty cycle if the connection could not
972 : * be established within the timeout the connected callback will be
973 : * called with the status set to @ref BT_HCI_ERR_ADV_TIMEOUT.
974 : */
975 1 : const bt_addr_le_t *peer;
976 : };
977 :
978 :
979 : /** Periodic Advertising options */
980 1 : enum bt_le_per_adv_opt {
981 : /** Convenience value when no options are specified. */
982 : BT_LE_PER_ADV_OPT_NONE = 0,
983 :
984 : /**
985 : * @brief Advertise with transmit power.
986 : *
987 : * @note Requires @ref BT_LE_ADV_OPT_EXT_ADV bit (see @ref bt_le_adv_opt field) to be
988 : * set as @ref bt_le_adv_param.options.
989 : */
990 : BT_LE_PER_ADV_OPT_USE_TX_POWER = BIT(1),
991 :
992 : /**
993 : * @brief Advertise with included AdvDataInfo (ADI).
994 : *
995 : * @note Requires @ref BT_LE_ADV_OPT_EXT_ADV bit (see @ref bt_le_adv_opt field) to be
996 : * set as @ref bt_le_adv_param.options.
997 : */
998 : BT_LE_PER_ADV_OPT_INCLUDE_ADI = BIT(2),
999 : };
1000 :
1001 : /**
1002 : * @brief Parameters for configuring periodic advertising.
1003 : *
1004 : * @details This struct is used to configure the parameters for periodic advertising, including the
1005 : * minimum and maximum advertising intervals, options, and settings for subevents if periodic
1006 : * advertising responses are supported. The intervals are specified in units of 1.25 ms, and the
1007 : * options field can be used to modify other advertising behaviors. For extended advertisers, the
1008 : * periodic advertising parameters can be set or updated using this structure. Some parameters are
1009 : * conditional based on whether the device supports periodic advertising responses (configured via
1010 : * @kconfig{CONFIG_BT_PER_ADV_RSP}).
1011 : *
1012 : * @note Used in @ref bt_le_per_adv_set_param function.
1013 : */
1014 1 : struct bt_le_per_adv_param {
1015 : /**
1016 : * @brief Minimum Periodic Advertising Interval (N * 1.25 ms)
1017 : *
1018 : * Shall be greater or equal to BT_GAP_PER_ADV_MIN_INTERVAL and
1019 : * less or equal to interval_max.
1020 : */
1021 1 : uint16_t interval_min;
1022 :
1023 : /**
1024 : * @brief Maximum Periodic Advertising Interval (N * 1.25 ms)
1025 : *
1026 : * Shall be less or equal to BT_GAP_PER_ADV_MAX_INTERVAL and
1027 : * greater or equal to interval_min.
1028 : */
1029 1 : uint16_t interval_max;
1030 :
1031 : /** Bit-field of periodic advertising options, see the @ref bt_le_adv_opt field. */
1032 1 : uint32_t options;
1033 :
1034 : #if defined(CONFIG_BT_PER_ADV_RSP)
1035 : /**
1036 : * @brief Number of subevents
1037 : *
1038 : * If zero, the periodic advertiser will be a broadcaster, without responses.
1039 : */
1040 : uint8_t num_subevents;
1041 :
1042 : /**
1043 : * @brief Interval between subevents (N * 1.25 ms)
1044 : *
1045 : * Shall be between 7.5ms and 318.75 ms.
1046 : */
1047 : uint8_t subevent_interval;
1048 :
1049 : /**
1050 : * @brief Time between the advertising packet in a subevent and the
1051 : * first response slot (N * 1.25 ms)
1052 : *
1053 : */
1054 : uint8_t response_slot_delay;
1055 :
1056 : /**
1057 : * @brief Time between response slots (N * 0.125 ms)
1058 : *
1059 : * Shall be between 0.25 and 31.875 ms.
1060 : */
1061 : uint8_t response_slot_spacing;
1062 :
1063 : /**
1064 : * @brief Number of subevent response slots
1065 : *
1066 : * If zero, response_slot_delay and response_slot_spacing are ignored.
1067 : */
1068 : uint8_t num_response_slots;
1069 : #endif /* CONFIG_BT_PER_ADV_RSP */
1070 : };
1071 :
1072 : /**
1073 : * @brief Initialize advertising parameters
1074 : *
1075 : * @param _options Advertising Options
1076 : * @param _int_min Minimum advertising interval
1077 : * @param _int_max Maximum advertising interval
1078 : * @param _peer Peer address, set to NULL for undirected advertising or
1079 : * address of peer for directed advertising.
1080 : */
1081 1 : #define BT_LE_ADV_PARAM_INIT(_options, _int_min, _int_max, _peer) \
1082 : { \
1083 : .id = BT_ID_DEFAULT, \
1084 : .sid = 0, \
1085 : .secondary_max_skip = 0, \
1086 : .options = (_options), \
1087 : .interval_min = (_int_min), \
1088 : .interval_max = (_int_max), \
1089 : .peer = (_peer), \
1090 : }
1091 :
1092 : /**
1093 : * @brief Helper to declare advertising parameters inline
1094 : *
1095 : * @param _options Advertising Options
1096 : * @param _int_min Minimum advertising interval
1097 : * @param _int_max Maximum advertising interval
1098 : * @param _peer Peer address, set to NULL for undirected advertising or
1099 : * address of peer for directed advertising.
1100 : */
1101 1 : #define BT_LE_ADV_PARAM(_options, _int_min, _int_max, _peer) \
1102 : ((const struct bt_le_adv_param[]) { \
1103 : BT_LE_ADV_PARAM_INIT(_options, _int_min, _int_max, _peer) \
1104 : })
1105 :
1106 0 : #define BT_LE_ADV_CONN_DIR(_peer) BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONN, 0, 0, _peer)
1107 :
1108 : /**
1109 : * @brief GAP recommended connectable advertising parameters user-initiated
1110 : *
1111 : * @details This define sets the recommended default for when an application is likely waiting for
1112 : * the device to be connected or discovered.
1113 : *
1114 : * GAP recommends advertisers use the advertising parameters set by @ref BT_LE_ADV_CONN_FAST_1 for
1115 : * user-initiated advertisements. This might mean any time a user interacts with a device, a press
1116 : * on a dedicated Bluetooth wakeup button, or anything in-between. Interpretation is left to the
1117 : * application developer.
1118 : *
1119 : * Following modes are considered in these parameter settings:
1120 : * - Undirected Connectable Mode
1121 : * - Limited Discoverable Mode and sending connectable undirected advertising events
1122 : * - General Discoverable Mode and sending connectable undirected advertising events
1123 : * - Directed Connectable Mode and sending low duty cycle directed advertising events
1124 : *
1125 : * @note These parameters are merely a recommendation. For example the application might use a
1126 : * longer interval to conserve battery, which would be at the cost of responsiveness and it should
1127 : * be considered to enter a lower power state with longer intervals only after a timeout.
1128 : *
1129 : * @note This is the recommended setting for limited discoverable mode.
1130 : *
1131 : * See Bluetooth Core Specification:
1132 : * - 6.0 Vol 3, Part C, Appendix A "Timers and Constants", T_GAP(adv_fast_interval1)
1133 : * - 6.0 Vol 3, Part C, Section 9.3.11 "Connection Establishment Timing parameters"
1134 : */
1135 :
1136 1 : #define BT_LE_ADV_CONN_FAST_1 \
1137 : BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONN, BT_GAP_ADV_FAST_INT_MIN_1, BT_GAP_ADV_FAST_INT_MAX_1, \
1138 : NULL)
1139 :
1140 : /**
1141 : * @brief GAP recommended connectable advertising parameters non-connectable advertising events
1142 : *
1143 : * @details This define sets the recommended default for user-initiated advertisements or sending
1144 : * non-connectable advertising events.
1145 : *
1146 : * Following modes are considered in these parameter settings:
1147 : * - Non-Discoverable Mode
1148 : * - Non-Connectable Mode
1149 : * - Limited Discoverable Mode
1150 : * - General Discoverable Mode
1151 : *
1152 : * See Bluetooth Core Specification:
1153 : * - 6.0 Vol 3, Part C, Appendix A "Timers and Constants", T_GAP(adv_fast_interval2)
1154 : * - 6.0 Vol 3, Part C, Section 9.3.11 "Connection Establishment Timing parameters"
1155 : */
1156 1 : #define BT_LE_ADV_CONN_FAST_2 \
1157 : BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONN, BT_GAP_ADV_FAST_INT_MIN_2, BT_GAP_ADV_FAST_INT_MAX_2, \
1158 : NULL)
1159 :
1160 0 : #define BT_LE_ADV_CONN_DIR_LOW_DUTY(_peer) \
1161 : BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONN | BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY, \
1162 : BT_GAP_ADV_FAST_INT_MIN_2, BT_GAP_ADV_FAST_INT_MAX_2, _peer)
1163 :
1164 : /** Non-connectable advertising with private address */
1165 1 : #define BT_LE_ADV_NCONN BT_LE_ADV_PARAM(0, BT_GAP_ADV_FAST_INT_MIN_2, \
1166 : BT_GAP_ADV_FAST_INT_MAX_2, NULL)
1167 :
1168 : /** Non-connectable advertising with @ref BT_LE_ADV_OPT_USE_IDENTITY */
1169 1 : #define BT_LE_ADV_NCONN_IDENTITY BT_LE_ADV_PARAM(BT_LE_ADV_OPT_USE_IDENTITY, \
1170 : BT_GAP_ADV_FAST_INT_MIN_2, \
1171 : BT_GAP_ADV_FAST_INT_MAX_2, \
1172 : NULL)
1173 :
1174 : /** Connectable extended advertising */
1175 1 : #define BT_LE_EXT_ADV_CONN \
1176 : BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | BT_LE_ADV_OPT_CONN, BT_GAP_ADV_FAST_INT_MIN_2, \
1177 : BT_GAP_ADV_FAST_INT_MAX_2, NULL)
1178 :
1179 : /** Scannable extended advertising */
1180 1 : #define BT_LE_EXT_ADV_SCAN BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | \
1181 : BT_LE_ADV_OPT_SCANNABLE, \
1182 : BT_GAP_ADV_FAST_INT_MIN_2, \
1183 : BT_GAP_ADV_FAST_INT_MAX_2, \
1184 : NULL)
1185 :
1186 : /** Non-connectable extended advertising with private address */
1187 1 : #define BT_LE_EXT_ADV_NCONN BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV, \
1188 : BT_GAP_ADV_FAST_INT_MIN_2, \
1189 : BT_GAP_ADV_FAST_INT_MAX_2, NULL)
1190 :
1191 : /** Non-connectable extended advertising with @ref BT_LE_ADV_OPT_USE_IDENTITY */
1192 1 : #define BT_LE_EXT_ADV_NCONN_IDENTITY \
1193 : BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | \
1194 : BT_LE_ADV_OPT_USE_IDENTITY, \
1195 : BT_GAP_ADV_FAST_INT_MIN_2, \
1196 : BT_GAP_ADV_FAST_INT_MAX_2, NULL)
1197 :
1198 : /** Non-connectable extended advertising on coded PHY with private address */
1199 1 : #define BT_LE_EXT_ADV_CODED_NCONN BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | \
1200 : BT_LE_ADV_OPT_CODED, \
1201 : BT_GAP_ADV_FAST_INT_MIN_2, \
1202 : BT_GAP_ADV_FAST_INT_MAX_2, \
1203 : NULL)
1204 :
1205 : /** Non-connectable extended advertising on coded PHY with
1206 : * @ref BT_LE_ADV_OPT_USE_IDENTITY
1207 : */
1208 1 : #define BT_LE_EXT_ADV_CODED_NCONN_IDENTITY \
1209 : BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | BT_LE_ADV_OPT_CODED | \
1210 : BT_LE_ADV_OPT_USE_IDENTITY, \
1211 : BT_GAP_ADV_FAST_INT_MIN_2, \
1212 : BT_GAP_ADV_FAST_INT_MAX_2, NULL)
1213 :
1214 : /**
1215 : * Helper to initialize extended advertising start parameters inline
1216 : *
1217 : * @param _timeout Advertiser timeout
1218 : * @param _n_evts Number of advertising events
1219 : */
1220 1 : #define BT_LE_EXT_ADV_START_PARAM_INIT(_timeout, _n_evts) \
1221 : { \
1222 : .timeout = (_timeout), \
1223 : .num_events = (_n_evts), \
1224 : }
1225 :
1226 : /**
1227 : * Helper to declare extended advertising start parameters inline
1228 : *
1229 : * @param _timeout Advertiser timeout
1230 : * @param _n_evts Number of advertising events
1231 : */
1232 1 : #define BT_LE_EXT_ADV_START_PARAM(_timeout, _n_evts) \
1233 : ((const struct bt_le_ext_adv_start_param[]) { \
1234 : BT_LE_EXT_ADV_START_PARAM_INIT((_timeout), (_n_evts)) \
1235 : })
1236 :
1237 0 : #define BT_LE_EXT_ADV_START_DEFAULT BT_LE_EXT_ADV_START_PARAM(0, 0)
1238 :
1239 : /**
1240 : * Helper to declare periodic advertising parameters inline
1241 : *
1242 : * @param _int_min Minimum periodic advertising interval, N * 0.625 milliseconds
1243 : * @param _int_max Maximum periodic advertising interval, N * 0.625 milliseconds
1244 : * @param _options Periodic advertising properties bitfield, see @ref bt_le_adv_opt
1245 : * field.
1246 : */
1247 1 : #define BT_LE_PER_ADV_PARAM_INIT(_int_min, _int_max, _options) \
1248 : { \
1249 : .interval_min = (_int_min), \
1250 : .interval_max = (_int_max), \
1251 : .options = (_options), \
1252 : }
1253 :
1254 : /**
1255 : * Helper to declare periodic advertising parameters inline
1256 : *
1257 : * @param _int_min Minimum periodic advertising interval, N * 0.625 milliseconds
1258 : * @param _int_max Maximum periodic advertising interval, N * 0.625 milliseconds
1259 : * @param _options Periodic advertising properties bitfield, see @ref bt_le_adv_opt
1260 : * field.
1261 : */
1262 1 : #define BT_LE_PER_ADV_PARAM(_int_min, _int_max, _options) \
1263 : ((struct bt_le_per_adv_param[]) { \
1264 : BT_LE_PER_ADV_PARAM_INIT(_int_min, _int_max, _options) \
1265 : })
1266 :
1267 0 : #define BT_LE_PER_ADV_DEFAULT BT_LE_PER_ADV_PARAM(BT_GAP_PER_ADV_SLOW_INT_MIN, \
1268 : BT_GAP_PER_ADV_SLOW_INT_MAX, \
1269 : BT_LE_PER_ADV_OPT_NONE)
1270 :
1271 : /**
1272 : * @brief Start advertising
1273 : *
1274 : * Set advertisement data, scan response data, advertisement parameters
1275 : * and start advertising.
1276 : *
1277 : * When @p param.peer is set, the advertising will be directed to that peer device. In this case,
1278 : * the other function parameters are ignored.
1279 : *
1280 : * This function cannot be used with @ref BT_LE_ADV_OPT_EXT_ADV in the @p param.options.
1281 : * For extended advertising, the bt_le_ext_adv_* functions must be used.
1282 : *
1283 : * @param param Advertising parameters.
1284 : * @param ad Data to be used in advertisement packets.
1285 : * @param ad_len Number of elements in ad
1286 : * @param sd Data to be used in scan response packets.
1287 : * @param sd_len Number of elements in sd
1288 : *
1289 : * @return Zero on success or (negative) error code otherwise.
1290 : * @return -ENOMEM No free connection objects available for connectable
1291 : * advertiser.
1292 : * @return -ECONNREFUSED When connectable advertising is requested and there
1293 : * is already maximum number of connections established
1294 : * in the controller.
1295 : * This error code is only guaranteed when using Zephyr
1296 : * controller, for other controllers code returned in
1297 : * this case may be -EIO.
1298 : */
1299 1 : int bt_le_adv_start(const struct bt_le_adv_param *param,
1300 : const struct bt_data *ad, size_t ad_len,
1301 : const struct bt_data *sd, size_t sd_len);
1302 :
1303 : /**
1304 : * @brief Update advertising
1305 : *
1306 : * Update advertisement and scan response data.
1307 : *
1308 : * @param ad Data to be used in advertisement packets.
1309 : * @param ad_len Number of elements in ad
1310 : * @param sd Data to be used in scan response packets.
1311 : * @param sd_len Number of elements in sd
1312 : *
1313 : * @return Zero on success or (negative) error code otherwise.
1314 : */
1315 1 : int bt_le_adv_update_data(const struct bt_data *ad, size_t ad_len,
1316 : const struct bt_data *sd, size_t sd_len);
1317 :
1318 : /**
1319 : * @brief Stop advertising
1320 : *
1321 : * Stops ongoing advertising.
1322 : *
1323 : * @return Zero on success or (negative) error code otherwise.
1324 : */
1325 1 : int bt_le_adv_stop(void);
1326 :
1327 : /**
1328 : * @brief Create advertising set.
1329 : *
1330 : * Create an instance of an independent advertising set with its own parameters and data.
1331 : * The advertising set remains valid until deleted with @ref bt_le_ext_adv_delete.
1332 : * Advertising parameters can be updated with @ref bt_le_ext_adv_update_param, and advertising
1333 : * can be started with @ref bt_le_ext_adv_start.
1334 : *
1335 : * @note The number of supported extended advertising sets can be controlled by
1336 : * @kconfig{CONFIG_BT_EXT_ADV_MAX_ADV_SET}.
1337 : *
1338 : * @param[in] param Advertising parameters.
1339 : * @param[in] cb Callback struct to notify about advertiser activity. Can be
1340 : * NULL. Must point to valid memory during the lifetime of the
1341 : * advertising set.
1342 : * @param[out] adv Valid advertising set object on success.
1343 : *
1344 : * @return Zero on success or (negative) error code otherwise.
1345 : */
1346 1 : int bt_le_ext_adv_create(const struct bt_le_adv_param *param,
1347 : const struct bt_le_ext_adv_cb *cb,
1348 : struct bt_le_ext_adv **adv);
1349 :
1350 : /**
1351 : * @brief Parameters for starting an extended advertising session.
1352 : *
1353 : * @details This struct provides the parameters to control the behavior of an extended advertising
1354 : * session, including the timeout and the number of advertising events to send. The timeout is
1355 : * specified in units of 10 ms, and the number of events determines how many times the advertising
1356 : * will be sent before stopping. If either the timeout or number of events is reached, the
1357 : * advertising session will be stopped, and the application will be notified via the advertiser sent
1358 : * callback. If both parameters are provided, the advertising session will stop when either limit is
1359 : * reached.
1360 : *
1361 : * @note Used in @ref bt_le_ext_adv_start function.
1362 : */
1363 1 : struct bt_le_ext_adv_start_param {
1364 : /**
1365 : * @brief Maximum advertising set duration (N * 10 ms)
1366 : *
1367 : * The advertising set can be automatically disabled after a
1368 : * certain amount of time has passed since it first appeared on
1369 : * air.
1370 : *
1371 : * Set to zero for no limit. Set in units of 10 ms.
1372 : *
1373 : * When the advertising set is automatically disabled because of
1374 : * this limit, @ref bt_le_ext_adv_cb.sent will be called.
1375 : *
1376 : * When using high duty cycle directed connectable advertising
1377 : * then this parameters must be set to a non-zero value less
1378 : * than or equal to the maximum of
1379 : * @ref BT_GAP_ADV_HIGH_DUTY_CYCLE_MAX_TIMEOUT.
1380 : *
1381 : * If privacy @kconfig{CONFIG_BT_PRIVACY} is enabled then the
1382 : * timeout must be less than @kconfig{CONFIG_BT_RPA_TIMEOUT}.
1383 : *
1384 : * For background information, see parameter "Duration" in
1385 : * Bluetooth Core Specification Version 6.0 Vol. 4 Part E,
1386 : * Section 7.8.56.
1387 : */
1388 1 : uint16_t timeout;
1389 :
1390 : /**
1391 : * @brief Maximum number of extended advertising events to be
1392 : * sent
1393 : *
1394 : * The advertiser can be automatically disabled once the whole
1395 : * advertisement (i.e. extended advertising event) has been sent
1396 : * a certain number of times. The number of advertising PDUs
1397 : * sent may be higher and is not relevant.
1398 : *
1399 : * Set to zero for no limit.
1400 : *
1401 : * When the advertising set is automatically disabled because of
1402 : * this limit, @ref bt_le_ext_adv_cb.sent will be called.
1403 : *
1404 : * For background information, see parameter
1405 : * "Max_Extended_Advertising_Events" in Bluetooth Core
1406 : * Specification Version 6.0 Vol. 4 Part E, Section 7.8.56.
1407 : */
1408 1 : uint8_t num_events;
1409 : };
1410 :
1411 : /**
1412 : * @brief Start advertising with the given advertising set
1413 : *
1414 : * If the advertiser is limited by either the @p param.timeout or @p param.num_events,
1415 : * the application will be notified by the @ref bt_le_ext_adv_cb.sent callback once
1416 : * the limit is reached.
1417 : * If the advertiser is limited by both the timeout and the number of
1418 : * advertising events, then the limit that is reached first will stop the
1419 : * advertiser.
1420 : *
1421 : * @note The advertising set @p adv can be created with @ref bt_le_ext_adv_create.
1422 : *
1423 : * @param adv Advertising set object.
1424 : * @param param Advertise start parameters.
1425 : */
1426 1 : int bt_le_ext_adv_start(struct bt_le_ext_adv *adv,
1427 : const struct bt_le_ext_adv_start_param *param);
1428 :
1429 : /**
1430 : * @brief Stop advertising with the given advertising set
1431 : *
1432 : * Stop advertising with a specific advertising set. When using this function
1433 : * the advertising sent callback will not be called.
1434 : *
1435 : * @param adv Advertising set object.
1436 : *
1437 : * @return Zero on success or (negative) error code otherwise.
1438 : */
1439 1 : int bt_le_ext_adv_stop(struct bt_le_ext_adv *adv);
1440 :
1441 : /**
1442 : * @brief Set an advertising set's advertising or scan response data.
1443 : *
1444 : * Set advertisement data or scan response data. If the advertising set is
1445 : * currently advertising then the advertising data will be updated in
1446 : * subsequent advertising events.
1447 : *
1448 : * When both @ref BT_LE_ADV_OPT_EXT_ADV and @ref BT_LE_ADV_OPT_SCANNABLE are
1449 : * enabled then advertising data is ignored and only scan response data is used.
1450 : * When @ref BT_LE_ADV_OPT_SCANNABLE is not enabled then scan response data is
1451 : * ignored and only advertising data is used.
1452 : *
1453 : * If the advertising set has been configured to send advertising data on the
1454 : * primary advertising channels then the maximum data length is
1455 : * @ref BT_GAP_ADV_MAX_ADV_DATA_LEN octets.
1456 : * If the advertising set has been configured for extended advertising,
1457 : * then the maximum data length is defined by the controller with the maximum
1458 : * possible of @ref BT_GAP_ADV_MAX_EXT_ADV_DATA_LEN bytes.
1459 : *
1460 : * @note Extended advertising was introduced in Bluetooth 5.0, and legacy scanners will not support
1461 : * reception of any extended advertising packets.
1462 : *
1463 : * @note When updating the advertising data while advertising the advertising
1464 : * data and scan response data length must be smaller or equal to what
1465 : * can be fit in a single advertising packet. Otherwise the
1466 : * advertiser must be stopped.
1467 : *
1468 : * @param adv Advertising set object.
1469 : * @param ad Data to be used in advertisement packets.
1470 : * @param ad_len Number of elements in ad
1471 : * @param sd Data to be used in scan response packets.
1472 : * @param sd_len Number of elements in sd
1473 : *
1474 : * @return Zero on success or (negative) error code otherwise.
1475 : */
1476 1 : int bt_le_ext_adv_set_data(struct bt_le_ext_adv *adv,
1477 : const struct bt_data *ad, size_t ad_len,
1478 : const struct bt_data *sd, size_t sd_len);
1479 :
1480 : /**
1481 : * @brief Update advertising parameters.
1482 : *
1483 : * Update the advertising parameters. The function will return an error if the
1484 : * advertiser set is currently advertising. Stop the advertising set before
1485 : * calling this function.
1486 : *
1487 : * @param adv Advertising set object.
1488 : * @param param Advertising parameters.
1489 : *
1490 : * @return Zero on success or (negative) error code otherwise.
1491 : */
1492 1 : int bt_le_ext_adv_update_param(struct bt_le_ext_adv *adv,
1493 : const struct bt_le_adv_param *param);
1494 :
1495 : /**
1496 : * @brief Delete advertising set.
1497 : *
1498 : * Delete advertising set. This will free up the advertising set and make it
1499 : * possible to create a new advertising set if the limit @kconfig{CONFIG_BT_EXT_ADV_MAX_ADV_SET}
1500 : * was reached.
1501 : *
1502 : * @return Zero on success or (negative) error code otherwise.
1503 : */
1504 1 : int bt_le_ext_adv_delete(struct bt_le_ext_adv *adv);
1505 :
1506 : /**
1507 : * @brief Get array index of an advertising set.
1508 : *
1509 : * This function is used to map bt_adv to index of an array of
1510 : * advertising sets. The array has @kconfig{CONFIG_BT_EXT_ADV_MAX_ADV_SET} elements.
1511 : *
1512 : * @param adv Advertising set.
1513 : *
1514 : * @return Index of the advertising set object.
1515 : * The range of the returned value is 0..@kconfig{CONFIG_BT_EXT_ADV_MAX_ADV_SET}-1
1516 : */
1517 1 : uint8_t bt_le_ext_adv_get_index(struct bt_le_ext_adv *adv);
1518 :
1519 : /** Advertising states. */
1520 1 : enum bt_le_ext_adv_state {
1521 : /** The advertising set has been created but not enabled. */
1522 : BT_LE_EXT_ADV_STATE_DISABLED,
1523 :
1524 : /** The advertising set is enabled. */
1525 : BT_LE_EXT_ADV_STATE_ENABLED,
1526 : };
1527 :
1528 : /** Periodic Advertising states. */
1529 1 : enum bt_le_per_adv_state {
1530 : /** Not configured for periodic advertising. */
1531 : BT_LE_PER_ADV_STATE_NONE,
1532 :
1533 : /** The advertising set has been configured for periodic advertising, but is not enabled. */
1534 : BT_LE_PER_ADV_STATE_DISABLED,
1535 :
1536 : /** Periodic advertising is enabled. */
1537 : BT_LE_PER_ADV_STATE_ENABLED,
1538 : };
1539 :
1540 : /** @brief Advertising set info structure. */
1541 1 : struct bt_le_ext_adv_info {
1542 : /** Local identity handle. */
1543 1 : uint8_t id;
1544 :
1545 : /** Currently selected Transmit Power (dBM). */
1546 1 : int8_t tx_power;
1547 :
1548 : /** Advertising Set ID */
1549 1 : uint8_t sid;
1550 :
1551 : /** Current local advertising address used. */
1552 1 : const bt_addr_le_t *addr;
1553 :
1554 : /** Extended advertising state. */
1555 1 : enum bt_le_ext_adv_state ext_adv_state;
1556 :
1557 : /** Periodic advertising state. */
1558 1 : enum bt_le_per_adv_state per_adv_state;
1559 : };
1560 :
1561 : /**
1562 : * @brief Get advertising set info
1563 : *
1564 : * @param adv Advertising set object
1565 : * @param info Advertising set info object. The values in this object are only valid on success.
1566 : *
1567 : * @retval 0 Success.
1568 : * @retval -EINVAL @p adv is not valid advertising set or @p info is NULL.
1569 : */
1570 1 : int bt_le_ext_adv_get_info(const struct bt_le_ext_adv *adv,
1571 : struct bt_le_ext_adv_info *info);
1572 :
1573 : /**
1574 : * @typedef bt_le_scan_cb_t
1575 : * @brief Callback type for reporting LE scan results.
1576 : *
1577 : * A function of this type is given to the @ref bt_le_scan_start function
1578 : * and will be called for any discovered LE device.
1579 : *
1580 : * @param addr Advertiser LE address and type.
1581 : * @param rssi Strength of advertiser signal.
1582 : * @param adv_type Type of advertising response from advertiser.
1583 : * Uses the @ref bt_gap_adv_type values.
1584 : * @param buf Buffer containing advertiser data.
1585 : */
1586 1 : typedef void bt_le_scan_cb_t(const bt_addr_le_t *addr, int8_t rssi,
1587 : uint8_t adv_type, struct net_buf_simple *buf);
1588 :
1589 : /**
1590 : * @brief Set or update the periodic advertising parameters.
1591 : *
1592 : * The periodic advertising parameters can only be set or updated on an
1593 : * extended advertisement set which is neither scannable, connectable nor
1594 : * anonymous (meaning, the advertising options @ref BT_LE_ADV_OPT_SCANNABLE,
1595 : * @ref BT_LE_ADV_OPT_CONN and @ref BT_LE_ADV_OPT_ANONYMOUS cannot be set for @p adv).
1596 : *
1597 : * @param adv Advertising set object.
1598 : * @param param Advertising parameters.
1599 : *
1600 : * @return Zero on success or (negative) error code otherwise.
1601 : */
1602 1 : int bt_le_per_adv_set_param(struct bt_le_ext_adv *adv,
1603 : const struct bt_le_per_adv_param *param);
1604 :
1605 : /**
1606 : * @brief Set or update the periodic advertising data.
1607 : *
1608 : * The periodic advertisement data can only be set or updated on an
1609 : * extended advertisement set which is neither scannable, connectable nor
1610 : * anonymous (meaning, the advertising options @ref BT_LE_ADV_OPT_SCANNABLE,
1611 : * @ref BT_LE_ADV_OPT_CONN and @ref BT_LE_ADV_OPT_ANONYMOUS cannot be set for @p adv).
1612 : *
1613 : * @param adv Advertising set object.
1614 : * @param ad Advertising data.
1615 : * @param ad_len Advertising data length.
1616 : *
1617 : * @return Zero on success or (negative) error code otherwise.
1618 : */
1619 1 : int bt_le_per_adv_set_data(const struct bt_le_ext_adv *adv,
1620 : const struct bt_data *ad, size_t ad_len);
1621 :
1622 : /**
1623 : * @brief Parameters for setting data for a specific periodic advertising with response subevent.
1624 : *
1625 : * @details This struct provides the necessary information to set the data for a specific subevent
1626 : * in a Periodic Advertising with Response (PAwR) scenario. It specifies the subevent number, the
1627 : * range of response slots to listen to, and the actual data to send. This is used to respond to
1628 : * data request from an advertiser by sending back the data in the specified subevent.
1629 : *
1630 : * @note Used in @ref bt_le_per_adv_set_subevent_data function.
1631 : */
1632 1 : struct bt_le_per_adv_subevent_data_params {
1633 : /** The subevent to set data for */
1634 1 : uint8_t subevent;
1635 :
1636 : /** The first response slot to listen to */
1637 1 : uint8_t response_slot_start;
1638 :
1639 : /** The number of response slots to listen to */
1640 1 : uint8_t response_slot_count;
1641 :
1642 : /** The data to send */
1643 1 : const struct net_buf_simple *data;
1644 : };
1645 :
1646 : /**
1647 : * @brief Set the periodic advertising with response subevent data.
1648 : *
1649 : * Set the data for one or more subevents of a Periodic Advertising with
1650 : * Responses Advertiser in reply data request.
1651 : *
1652 : * @pre There are @p num_subevents elements in @p params.
1653 : * @pre The controller has requested data for the subevents in @p params.
1654 : *
1655 : * @param adv The extended advertiser the PAwR train belongs to.
1656 : * @param num_subevents The number of subevents to set data for.
1657 : * @param params Subevent parameters.
1658 : *
1659 : * @return Zero on success or (negative) error code otherwise.
1660 : */
1661 1 : int bt_le_per_adv_set_subevent_data(const struct bt_le_ext_adv *adv, uint8_t num_subevents,
1662 : const struct bt_le_per_adv_subevent_data_params *params);
1663 :
1664 : /**
1665 : * @brief Starts periodic advertising.
1666 : *
1667 : * Enabling the periodic advertising can be done independently of extended
1668 : * advertising, but both periodic advertising and extended advertising
1669 : * shall be enabled before any periodic advertising data is sent. The
1670 : * periodic advertising and extended advertising can be enabled in any order.
1671 : *
1672 : * Once periodic advertising has been enabled, it will continue advertising
1673 : * until @ref bt_le_per_adv_stop function has been called, or if the advertising set
1674 : * is deleted by @ref bt_le_ext_adv_delete function. Calling @ref bt_le_ext_adv_stop function
1675 : * will not stop the periodic advertising.
1676 : *
1677 : * @param adv Advertising set object.
1678 : *
1679 : * @return Zero on success or (negative) error code otherwise.
1680 : */
1681 1 : int bt_le_per_adv_start(struct bt_le_ext_adv *adv);
1682 :
1683 : /**
1684 : * @brief Stops periodic advertising.
1685 : *
1686 : * Disabling the periodic advertising can be done independently of extended
1687 : * advertising. Disabling periodic advertising will not disable extended
1688 : * advertising.
1689 : *
1690 : * @param adv Advertising set object.
1691 : *
1692 : * @return Zero on success or (negative) error code otherwise.
1693 : */
1694 1 : int bt_le_per_adv_stop(struct bt_le_ext_adv *adv);
1695 :
1696 : /**
1697 : * @brief Information about the successful synchronization with periodic advertising.
1698 : *
1699 : * @details This struct provides information about the periodic advertising sync once it has been
1700 : * successfully established. It includes the advertiser's address, SID, the advertising interval,
1701 : * PHY, and the synchronization state. It also contains details about the sync, such as service data
1702 : * and the peer device that transferred the sync.
1703 : * When using periodic advertising response (configured via @kconfig{CONFIG_BT_PER_ADV_SYNC_RSP}),
1704 : * additional details such as subevent information and response timings are provided.
1705 : *
1706 : * @note Used in @ref bt_le_per_adv_sync_cb structure.
1707 : */
1708 1 : struct bt_le_per_adv_sync_synced_info {
1709 : /** Advertiser LE address and type. */
1710 1 : const bt_addr_le_t *addr;
1711 :
1712 : /** Advertising Set Identifier, valid range @ref BT_GAP_SID_MIN to @ref BT_GAP_SID_MAX. */
1713 1 : uint8_t sid;
1714 :
1715 : /** Periodic advertising interval (N * 1.25 ms) */
1716 1 : uint16_t interval;
1717 :
1718 : /** Advertiser PHY (see @ref bt_gap_le_phy). */
1719 1 : uint8_t phy;
1720 :
1721 : /** True if receiving periodic advertisements, false otherwise. */
1722 1 : bool recv_enabled;
1723 :
1724 : /**
1725 : * @brief Service Data provided by the peer when sync is transferred
1726 : *
1727 : * Will always be 0 when the sync is locally created.
1728 : */
1729 1 : uint16_t service_data;
1730 :
1731 : /**
1732 : * @brief Peer that transferred the periodic advertising sync
1733 : *
1734 : * Will always be NULL when the sync is locally created.
1735 : *
1736 : */
1737 1 : struct bt_conn *conn;
1738 : #if defined(CONFIG_BT_PER_ADV_SYNC_RSP)
1739 : /** Number of subevents */
1740 : uint8_t num_subevents;
1741 :
1742 : /** Subevent interval (N * 1.25 ms) */
1743 : uint8_t subevent_interval;
1744 :
1745 : /** Response slot delay (N * 1.25 ms) */
1746 : uint8_t response_slot_delay;
1747 :
1748 : /** Response slot spacing (N * 1.25 ms) */
1749 : uint8_t response_slot_spacing;
1750 :
1751 : #endif /* CONFIG_BT_PER_ADV_SYNC_RSP */
1752 : };
1753 :
1754 : /**
1755 : * @brief Information about the termination of a periodic advertising sync.
1756 : *
1757 : * @details This struct provides information about the termination of a periodic advertising sync.
1758 : * It includes the advertiser’s address and SID, along with the reason for the sync termination.
1759 : * This information is provided in the callback when the sync is terminated, either due to a
1760 : * local or remote request, or due to missing data (e.g., out of range or lost sync).
1761 : *
1762 : * @note Used in @ref bt_le_per_adv_sync_cb structure.
1763 : */
1764 1 : struct bt_le_per_adv_sync_term_info {
1765 : /** Advertiser LE address and type. */
1766 1 : const bt_addr_le_t *addr;
1767 :
1768 : /** Advertising Set Identifier, valid range @ref BT_GAP_SID_MIN to @ref BT_GAP_SID_MAX. */
1769 1 : uint8_t sid;
1770 :
1771 : /** Cause of periodic advertising termination (see the BT_HCI_ERR_* values). */
1772 1 : uint8_t reason;
1773 : };
1774 :
1775 : /**
1776 : * @brief Information about a received periodic advertising report.
1777 : *
1778 : * @details This struct holds information about a periodic advertising event that has been received.
1779 : * It contains details such as the advertiser’s address, SID, transmit power, RSSI, CTE type, and
1780 : * additional information depending on the configuration (e.g., event counter and subevent in case
1781 : * of a subevent indication). This information is provided in the callback when periodic advertising
1782 : * data is received.
1783 : *
1784 : * @note Used in @ref bt_le_per_adv_sync_cb structure.
1785 : */
1786 1 : struct bt_le_per_adv_sync_recv_info {
1787 : /** Advertiser LE address and type. */
1788 1 : const bt_addr_le_t *addr;
1789 :
1790 : /** Advertising Set Identifier, valid range @ref BT_GAP_SID_MIN to @ref BT_GAP_SID_MAX. */
1791 1 : uint8_t sid;
1792 :
1793 : /** The TX power of the advertisement. */
1794 1 : int8_t tx_power;
1795 :
1796 : /** The RSSI of the advertisement excluding any CTE. */
1797 1 : int8_t rssi;
1798 :
1799 : /** The Constant Tone Extension (CTE) of the advertisement (@ref bt_df_cte_type) */
1800 1 : uint8_t cte_type;
1801 : #if defined(CONFIG_BT_PER_ADV_SYNC_RSP)
1802 : /** The value of the event counter where the subevent indication was received. */
1803 : uint16_t periodic_event_counter;
1804 :
1805 : /** The subevent where the subevent indication was received. */
1806 : uint8_t subevent;
1807 : #endif /* CONFIG_BT_PER_ADV_SYNC_RSP */
1808 : };
1809 :
1810 : /**
1811 : * @brief Information about the state of periodic advertising sync.
1812 : *
1813 : * @details This struct provides information about the current state of a periodic advertising sync.
1814 : * It indicates whether periodic advertising reception is enabled or not. It is typically used to
1815 : * report the state change via callbacks in the @ref bt_le_per_adv_sync_cb structure.
1816 : */
1817 1 : struct bt_le_per_adv_sync_state_info {
1818 : /** True if receiving periodic advertisements, false otherwise. */
1819 1 : bool recv_enabled;
1820 : };
1821 :
1822 : /**
1823 : * @brief Callback struct for periodic advertising sync events.
1824 : *
1825 : * @details This struct defines the callback functions that are invoked for various periodic
1826 : * advertising sync events. These include when the sync is successfully established, terminated,
1827 : * when data is received, state changes, BIG info reports, and IQ samples from the periodic
1828 : * advertising.
1829 : *
1830 : * @note Used in @ref bt_le_per_adv_sync_cb_register function.
1831 : */
1832 :
1833 1 : struct bt_le_per_adv_sync_cb {
1834 : /**
1835 : * @brief The periodic advertising has been successfully synced.
1836 : *
1837 : * This callback notifies the application that the periodic advertising
1838 : * set has been successfully synced, and will now start to
1839 : * receive periodic advertising reports.
1840 : *
1841 : * @param sync The periodic advertising sync object.
1842 : * @param info Information about the sync event.
1843 : */
1844 1 : void (*synced)(struct bt_le_per_adv_sync *sync,
1845 : struct bt_le_per_adv_sync_synced_info *info);
1846 :
1847 : /**
1848 : * @brief The periodic advertising sync has been terminated.
1849 : *
1850 : * This callback notifies the application that the periodic advertising
1851 : * sync has been terminated, either by local request, remote request or
1852 : * because due to missing data, e.g. by being out of range or sync.
1853 : *
1854 : * @param sync The periodic advertising sync object.
1855 : * @param info Information about the termination event.
1856 : */
1857 1 : void (*term)(struct bt_le_per_adv_sync *sync,
1858 : const struct bt_le_per_adv_sync_term_info *info);
1859 :
1860 : /**
1861 : * @brief Periodic advertising data received.
1862 : *
1863 : * This callback notifies the application of an periodic advertising
1864 : * report.
1865 : *
1866 : * @param sync The advertising set object.
1867 : * @param info Information about the periodic advertising event.
1868 : * @param buf Buffer containing the periodic advertising data.
1869 : * NULL if the controller failed to receive a subevent
1870 : * indication. Only happens if
1871 : * @kconfig{CONFIG_BT_PER_ADV_SYNC_RSP} is enabled.
1872 : */
1873 1 : void (*recv)(struct bt_le_per_adv_sync *sync,
1874 : const struct bt_le_per_adv_sync_recv_info *info,
1875 : struct net_buf_simple *buf);
1876 :
1877 : /**
1878 : * @brief The periodic advertising sync state has changed.
1879 : *
1880 : * This callback notifies the application about changes to the sync
1881 : * state. Initialize sync and termination is handled by their individual
1882 : * callbacks, and won't be notified here.
1883 : *
1884 : * @param sync The periodic advertising sync object.
1885 : * @param info Information about the state change.
1886 : */
1887 1 : void (*state_changed)(struct bt_le_per_adv_sync *sync,
1888 : const struct bt_le_per_adv_sync_state_info *info);
1889 :
1890 : /**
1891 : * @brief BIGInfo advertising report received.
1892 : *
1893 : * This callback notifies the application of a BIGInfo advertising report.
1894 : * This is received if the advertiser is broadcasting isochronous streams in a BIG.
1895 : * See iso.h for more information.
1896 : *
1897 : * @param sync The advertising set object.
1898 : * @param biginfo The BIGInfo report.
1899 : */
1900 1 : void (*biginfo)(struct bt_le_per_adv_sync *sync, const struct bt_iso_biginfo *biginfo);
1901 :
1902 : /**
1903 : * @brief Callback for IQ samples report collected when sampling
1904 : * CTE received with periodic advertising PDU.
1905 : *
1906 : * @param sync The periodic advertising sync object.
1907 : * @param info Information about the sync event.
1908 : */
1909 1 : void (*cte_report_cb)(struct bt_le_per_adv_sync *sync,
1910 : struct bt_df_per_adv_sync_iq_samples_report const *info);
1911 :
1912 0 : sys_snode_t node;
1913 : };
1914 :
1915 : /** Periodic advertising sync options */
1916 1 : enum bt_le_per_adv_sync_opt {
1917 : /** Convenience value when no options are specified. */
1918 : BT_LE_PER_ADV_SYNC_OPT_NONE = 0,
1919 :
1920 : /**
1921 : * @brief Use the periodic advertising list to sync with advertiser
1922 : *
1923 : * When this option is set, the address and SID of the parameters
1924 : * are ignored.
1925 : */
1926 : BT_LE_PER_ADV_SYNC_OPT_USE_PER_ADV_LIST = BIT(0),
1927 :
1928 : /**
1929 : * @brief Disables periodic advertising reports
1930 : *
1931 : * No advertisement reports will be handled until enabled.
1932 : */
1933 : BT_LE_PER_ADV_SYNC_OPT_REPORTING_INITIALLY_DISABLED = BIT(1),
1934 :
1935 : /** Filter duplicate Periodic Advertising reports */
1936 : BT_LE_PER_ADV_SYNC_OPT_FILTER_DUPLICATE = BIT(2),
1937 :
1938 : /** Sync with Angle of Arrival (AoA) constant tone extension */
1939 : BT_LE_PER_ADV_SYNC_OPT_DONT_SYNC_AOA = BIT(3),
1940 :
1941 : /** Sync with Angle of Departure (AoD) 1 us constant tone extension */
1942 : BT_LE_PER_ADV_SYNC_OPT_DONT_SYNC_AOD_1US = BIT(4),
1943 :
1944 : /** Sync with Angle of Departure (AoD) 2 us constant tone extension */
1945 : BT_LE_PER_ADV_SYNC_OPT_DONT_SYNC_AOD_2US = BIT(5),
1946 :
1947 : /** Do not sync to packets without a constant tone extension */
1948 : BT_LE_PER_ADV_SYNC_OPT_SYNC_ONLY_CONST_TONE_EXT = BIT(6),
1949 : };
1950 :
1951 : /**
1952 : * @brief Parameters for creating a periodic advertising sync object.
1953 : *
1954 : * @details This struct contains the parameters required to create a periodic advertising sync
1955 : * object, which allows the system to synchronize with periodic advertising reports from an
1956 : * advertiser. It includes the advertiser's address, SID, sync options, event skip, and
1957 : * synchronization timeout.
1958 : *
1959 : * @note bt_le_per_adv_sync_param is used as a parameter in the @ref bt_le_per_adv_sync_create
1960 : * function to configure synchronization behavior.
1961 : */
1962 1 : struct bt_le_per_adv_sync_param {
1963 : /**
1964 : * @brief Periodic Advertiser Address
1965 : *
1966 : * Only valid if not using the periodic advertising list
1967 : * (@ref BT_LE_PER_ADV_SYNC_OPT_USE_PER_ADV_LIST)
1968 : */
1969 1 : bt_addr_le_t addr;
1970 :
1971 : /**
1972 : * @brief Advertising Set Identifier. Valid range @ref BT_GAP_SID_MIN to
1973 : * @ref BT_GAP_SID_MAX.
1974 : *
1975 : * Only valid if not using the periodic advertising list
1976 : * (@ref BT_LE_PER_ADV_SYNC_OPT_USE_PER_ADV_LIST)
1977 : */
1978 1 : uint8_t sid;
1979 :
1980 : /** Bit-field of periodic advertising sync options, see the @ref bt_le_adv_opt field. */
1981 1 : uint32_t options;
1982 :
1983 : /**
1984 : * @brief Maximum event skip
1985 : *
1986 : * Maximum number of periodic advertising events that can be
1987 : * skipped after a successful receive.
1988 : * Range: 0x0000 to 0x01F3
1989 : */
1990 1 : uint16_t skip;
1991 :
1992 : /**
1993 : * @brief Synchronization timeout (N * 10 ms)
1994 : *
1995 : * Synchronization timeout for the periodic advertising sync.
1996 : * Range 0x000A to 0x4000 (100 ms to 163840 ms)
1997 : */
1998 1 : uint16_t timeout;
1999 : };
2000 :
2001 : /**
2002 : * @brief Get array index of an periodic advertising sync object.
2003 : *
2004 : * This function is to get the index of an array of periodic advertising sync
2005 : * objects. The array has @kconfig{CONFIG_BT_PER_ADV_SYNC_MAX} elements.
2006 : *
2007 : * @param per_adv_sync The periodic advertising sync object.
2008 : *
2009 : * @return Index of the periodic advertising sync object.
2010 : * The range of the returned value is 0..@kconfig{CONFIG_BT_PER_ADV_SYNC_MAX}-1
2011 : */
2012 1 : uint8_t bt_le_per_adv_sync_get_index(struct bt_le_per_adv_sync *per_adv_sync);
2013 :
2014 : /**
2015 : * @brief Get a periodic advertising sync object from the array index.
2016 : *
2017 : * This function is to get the periodic advertising sync object from
2018 : * the array index.
2019 : * The array has @kconfig{CONFIG_BT_PER_ADV_SYNC_MAX} elements.
2020 : *
2021 : * @param index The index of the periodic advertising sync object.
2022 : * The range of the index value is 0..@kconfig{CONFIG_BT_PER_ADV_SYNC_MAX}-1
2023 : *
2024 : * @return The periodic advertising sync object of the array index or NULL if invalid index.
2025 : */
2026 1 : struct bt_le_per_adv_sync *bt_le_per_adv_sync_lookup_index(uint8_t index);
2027 :
2028 : /** @brief Periodic advertising set info structure. */
2029 1 : struct bt_le_per_adv_sync_info {
2030 : /** Periodic Advertiser Address */
2031 1 : bt_addr_le_t addr;
2032 :
2033 : /** Advertising Set Identifier, valid range @ref BT_GAP_SID_MIN to @ref BT_GAP_SID_MAX. */
2034 1 : uint8_t sid;
2035 :
2036 : /** Periodic advertising interval (N * 1.25 ms) */
2037 1 : uint16_t interval;
2038 :
2039 : /** Advertiser PHY (see @ref bt_gap_le_phy). */
2040 1 : uint8_t phy;
2041 : };
2042 :
2043 : /**
2044 : * @brief Get periodic adv sync information.
2045 : *
2046 : * @param per_adv_sync Periodic advertising sync object.
2047 : * @param info Periodic advertising sync info object
2048 : *
2049 : * @return Zero on success or (negative) error code on failure.
2050 : */
2051 1 : int bt_le_per_adv_sync_get_info(struct bt_le_per_adv_sync *per_adv_sync,
2052 : struct bt_le_per_adv_sync_info *info);
2053 :
2054 : /**
2055 : * @brief Look up an existing periodic advertising sync object by advertiser address.
2056 : *
2057 : * @param adv_addr Advertiser address.
2058 : * @param sid The periodic advertising set ID.
2059 : *
2060 : * @return Periodic advertising sync object or NULL if not found.
2061 : */
2062 1 : struct bt_le_per_adv_sync *bt_le_per_adv_sync_lookup_addr(const bt_addr_le_t *adv_addr,
2063 : uint8_t sid);
2064 :
2065 : /**
2066 : * @brief Create a periodic advertising sync object.
2067 : *
2068 : * Create a periodic advertising sync object that can try to synchronize
2069 : * to periodic advertising reports from an advertiser. Scan shall either be
2070 : * disabled or extended scan shall be enabled.
2071 : *
2072 : * This function does not timeout, and will continue to look for an advertiser until it either
2073 : * finds it or @ref bt_le_per_adv_sync_delete is called. It is thus suggested to implement a timeout
2074 : * when using this, if it is expected to find the advertiser within a reasonable timeframe.
2075 : *
2076 : * @param[in] param Periodic advertising sync parameters.
2077 : * @param[out] out_sync Periodic advertising sync object on.
2078 : *
2079 : * @return Zero on success or (negative) error code otherwise.
2080 : */
2081 1 : int bt_le_per_adv_sync_create(const struct bt_le_per_adv_sync_param *param,
2082 : struct bt_le_per_adv_sync **out_sync);
2083 :
2084 : /**
2085 : * @brief Delete periodic advertising sync.
2086 : *
2087 : * Delete the periodic advertising sync object. Can be called regardless of the
2088 : * state of the sync. If the syncing is currently syncing, the syncing is
2089 : * cancelled. If the sync has been established, it is terminated. The
2090 : * periodic advertising sync object will be invalidated afterwards.
2091 : *
2092 : * If the state of the sync object is syncing, then a new periodic advertising
2093 : * sync object cannot be created until the controller has finished canceling
2094 : * this object.
2095 : *
2096 : * @param per_adv_sync The periodic advertising sync object.
2097 : *
2098 : * @return Zero on success or (negative) error code otherwise.
2099 : */
2100 1 : int bt_le_per_adv_sync_delete(struct bt_le_per_adv_sync *per_adv_sync);
2101 :
2102 : /**
2103 : * @brief Register periodic advertising sync callbacks.
2104 : *
2105 : * Adds the callback structure to the list of callback structures for periodic
2106 : * advertising syncs.
2107 : *
2108 : * This callback will be called for all periodic advertising sync activity,
2109 : * such as synced, terminated and when data is received.
2110 : *
2111 : * @param cb Callback struct. Must point to memory that remains valid.
2112 : *
2113 : * @retval 0 Success.
2114 : * @retval -EEXIST if @p cb was already registered.
2115 : */
2116 1 : int bt_le_per_adv_sync_cb_register(struct bt_le_per_adv_sync_cb *cb);
2117 :
2118 : /**
2119 : * @brief Enables receiving periodic advertising reports for a sync.
2120 : *
2121 : * If the sync is already receiving the reports, -EALREADY is returned.
2122 : *
2123 : * @param per_adv_sync The periodic advertising sync object.
2124 : *
2125 : * @return Zero on success or (negative) error code otherwise.
2126 : */
2127 1 : int bt_le_per_adv_sync_recv_enable(struct bt_le_per_adv_sync *per_adv_sync);
2128 :
2129 : /**
2130 : * @brief Disables receiving periodic advertising reports for a sync.
2131 : *
2132 : * If the sync report receiving is already disabled, -EALREADY is returned.
2133 : *
2134 : * @param per_adv_sync The periodic advertising sync object.
2135 : *
2136 : * @return Zero on success or (negative) error code otherwise.
2137 : */
2138 1 : int bt_le_per_adv_sync_recv_disable(struct bt_le_per_adv_sync *per_adv_sync);
2139 :
2140 : /** Periodic Advertising Sync Transfer options */
2141 1 : enum bt_le_per_adv_sync_transfer_opt {
2142 : /** Convenience value when no options are specified. */
2143 : BT_LE_PER_ADV_SYNC_TRANSFER_OPT_NONE = 0,
2144 :
2145 : /**
2146 : * @brief No Angle of Arrival (AoA)
2147 : *
2148 : * Do not sync with Angle of Arrival (AoA) constant tone extension
2149 : **/
2150 : BT_LE_PER_ADV_SYNC_TRANSFER_OPT_SYNC_NO_AOA = BIT(0),
2151 :
2152 : /**
2153 : * @brief No Angle of Departure (AoD) 1 us
2154 : *
2155 : * Do not sync with Angle of Departure (AoD) 1 us
2156 : * constant tone extension
2157 : */
2158 : BT_LE_PER_ADV_SYNC_TRANSFER_OPT_SYNC_NO_AOD_1US = BIT(1),
2159 :
2160 : /**
2161 : * @brief No Angle of Departure (AoD) 2
2162 : *
2163 : * Do not sync with Angle of Departure (AoD) 2 us
2164 : * constant tone extension
2165 : */
2166 : BT_LE_PER_ADV_SYNC_TRANSFER_OPT_SYNC_NO_AOD_2US = BIT(2),
2167 :
2168 : /** Only sync to packets with constant tone extension */
2169 : BT_LE_PER_ADV_SYNC_TRANSFER_OPT_SYNC_ONLY_CTE = BIT(3),
2170 :
2171 : /**
2172 : * @brief Sync to received PAST packets but don't generate sync reports
2173 : *
2174 : * This option must not be set at the same time as
2175 : * @ref BT_LE_PER_ADV_SYNC_TRANSFER_OPT_FILTER_DUPLICATES.
2176 : */
2177 : BT_LE_PER_ADV_SYNC_TRANSFER_OPT_REPORTING_INITIALLY_DISABLED = BIT(4),
2178 :
2179 : /**
2180 : * @brief Sync to received PAST packets and generate sync reports with duplicate filtering
2181 : *
2182 : * This option must not be set at the same time as
2183 : * @ref BT_LE_PER_ADV_SYNC_TRANSFER_OPT_REPORTING_INITIALLY_DISABLED.
2184 : */
2185 : BT_LE_PER_ADV_SYNC_TRANSFER_OPT_FILTER_DUPLICATES = BIT(5),
2186 : };
2187 :
2188 : /**
2189 : * @brief Parameters for periodic advertising sync transfer.
2190 : *
2191 : * @details This struct defines the parameters for configuring periodic advertising sync transfers
2192 : * (PASTs). It includes settings for the maximum event skip, synchronization timeout, and options
2193 : * for sync transfer.
2194 : *
2195 : * @note Used in the @ref bt_le_per_adv_sync_transfer_subscribe function to configure sync transfer
2196 : * settings.
2197 : */
2198 1 : struct bt_le_per_adv_sync_transfer_param {
2199 : /**
2200 : * @brief Maximum event skip
2201 : *
2202 : * The number of periodic advertising packets that can be skipped
2203 : * after a successful receive.
2204 : */
2205 1 : uint16_t skip;
2206 :
2207 : /**
2208 : * @brief Synchronization timeout (N * 10 ms)
2209 : *
2210 : * Synchronization timeout for the periodic advertising sync.
2211 : * Range 0x000A to 0x4000 (100 ms to 163840 ms)
2212 : */
2213 1 : uint16_t timeout;
2214 :
2215 : /** Periodic Advertising Sync Transfer options, see @ref bt_le_per_adv_sync_transfer_opt. */
2216 1 : uint32_t options;
2217 : };
2218 :
2219 : /**
2220 : * @brief Transfer the periodic advertising sync information to a peer device.
2221 : *
2222 : * This will allow another device to quickly synchronize to the same periodic
2223 : * advertising train that this device is currently synced to.
2224 : *
2225 : * @param per_adv_sync The periodic advertising sync to transfer.
2226 : * @param conn The peer device that will receive the sync information.
2227 : * @param service_data Application service data provided to the remote host.
2228 : *
2229 : * @return Zero on success or (negative) error code otherwise.
2230 : */
2231 1 : int bt_le_per_adv_sync_transfer(const struct bt_le_per_adv_sync *per_adv_sync,
2232 : const struct bt_conn *conn,
2233 : uint16_t service_data);
2234 :
2235 :
2236 : /**
2237 : * @brief Transfer the information about a periodic advertising set.
2238 : *
2239 : * This will allow another device to quickly synchronize to periodic
2240 : * advertising set from this device.
2241 : *
2242 : * @param adv The periodic advertising set to transfer info of.
2243 : * @param conn The peer device that will receive the information.
2244 : * @param service_data Application service data provided to the remote host.
2245 : *
2246 : * @return Zero on success or (negative) error code otherwise.
2247 : */
2248 1 : int bt_le_per_adv_set_info_transfer(const struct bt_le_ext_adv *adv,
2249 : const struct bt_conn *conn,
2250 : uint16_t service_data);
2251 :
2252 : /**
2253 : * @brief Subscribe to periodic advertising sync transfers (PASTs).
2254 : *
2255 : * Sets the parameters and allow other devices to transfer periodic advertising
2256 : * syncs.
2257 : *
2258 : * @param conn The connection to set the parameters for. If NULL default
2259 : * parameters for all connections will be set. Parameters set
2260 : * for specific connection will always have precedence.
2261 : * @param param The periodic advertising sync transfer parameters.
2262 : *
2263 : * @return Zero on success or (negative) error code otherwise.
2264 : */
2265 1 : int bt_le_per_adv_sync_transfer_subscribe(
2266 : const struct bt_conn *conn,
2267 : const struct bt_le_per_adv_sync_transfer_param *param);
2268 :
2269 : /**
2270 : * @brief Unsubscribe from periodic advertising sync transfers (PASTs).
2271 : *
2272 : * Remove the parameters that allow other devices to transfer periodic
2273 : * advertising syncs.
2274 : *
2275 : * @param conn The connection to remove the parameters for. If NULL default
2276 : * parameters for all connections will be removed. Unsubscribing
2277 : * for a specific device, will still allow other devices to
2278 : * transfer periodic advertising syncs.
2279 : *
2280 : * @return Zero on success or (negative) error code otherwise.
2281 : */
2282 1 : int bt_le_per_adv_sync_transfer_unsubscribe(const struct bt_conn *conn);
2283 :
2284 : /**
2285 : * @brief Add a device to the periodic advertising list.
2286 : *
2287 : * Add peer device LE address to the periodic advertising list. This will make
2288 : * it possibly to automatically create a periodic advertising sync to this
2289 : * device.
2290 : *
2291 : * @param addr Bluetooth LE identity address.
2292 : * @param sid The advertising set ID. This value is obtained from the
2293 : * @ref bt_le_scan_recv_info in the scan callback.
2294 : *
2295 : * @return Zero on success or (negative) error code otherwise.
2296 : */
2297 1 : int bt_le_per_adv_list_add(const bt_addr_le_t *addr, uint8_t sid);
2298 :
2299 : /**
2300 : * @brief Remove a device from the periodic advertising list.
2301 : *
2302 : * Removes peer device LE address from the periodic advertising list.
2303 : *
2304 : * @param addr Bluetooth LE identity address.
2305 : * @param sid The advertising set ID. This value is obtained from the
2306 : * @ref bt_le_scan_recv_info in the scan callback.
2307 : *
2308 : * @return Zero on success or (negative) error code otherwise.
2309 : */
2310 1 : int bt_le_per_adv_list_remove(const bt_addr_le_t *addr, uint8_t sid);
2311 :
2312 : /**
2313 : * @brief Clear the periodic advertising list.
2314 : *
2315 : * Clears the entire periodic advertising list.
2316 : *
2317 : * @return Zero on success or (negative) error code otherwise.
2318 : */
2319 1 : int bt_le_per_adv_list_clear(void);
2320 :
2321 :
2322 0 : enum bt_le_scan_opt {
2323 : /** Convenience value when no options are specified. */
2324 : BT_LE_SCAN_OPT_NONE = 0,
2325 :
2326 : /** Filter duplicates. */
2327 : BT_LE_SCAN_OPT_FILTER_DUPLICATE = BIT(0),
2328 :
2329 : /** Filter using filter accept list. */
2330 : BT_LE_SCAN_OPT_FILTER_ACCEPT_LIST = BIT(1),
2331 :
2332 : /** Enable scan on coded PHY (Long Range).*/
2333 : BT_LE_SCAN_OPT_CODED = BIT(2),
2334 :
2335 : /**
2336 : * @brief Disable scan on 1M phy.
2337 : *
2338 : * @note Requires @ref BT_LE_SCAN_OPT_CODED.
2339 : */
2340 : BT_LE_SCAN_OPT_NO_1M = BIT(3),
2341 : };
2342 :
2343 0 : enum bt_le_scan_type {
2344 : /** Scan without requesting additional information from advertisers. */
2345 : BT_LE_SCAN_TYPE_PASSIVE = 0x00,
2346 :
2347 : /**
2348 : * @brief Scan and request additional information from advertisers.
2349 : *
2350 : * Using this scan type will automatically send scan requests to all
2351 : * devices. Scan responses are received in the same manner and using the
2352 : * same callbacks as advertising reports.
2353 : */
2354 : BT_LE_SCAN_TYPE_ACTIVE = 0x01,
2355 : };
2356 :
2357 : /** LE scan parameters */
2358 1 : struct bt_le_scan_param {
2359 : /** Scan type. @ref BT_LE_SCAN_TYPE_ACTIVE or @ref BT_LE_SCAN_TYPE_PASSIVE. */
2360 1 : uint8_t type;
2361 :
2362 : /** Bit-field of scanning options. */
2363 1 : uint8_t options;
2364 :
2365 : /** Scan interval (N * 0.625 ms).
2366 : *
2367 : * @note When @kconfig{CONFIG_BT_SCAN_AND_INITIATE_IN_PARALLEL} is enabled
2368 : * and the application wants to scan and connect in parallel,
2369 : * the Bluetooth Controller may require the scan interval used
2370 : * for scanning and connection establishment to be equal to
2371 : * obtain the best performance.
2372 : */
2373 1 : uint16_t interval;
2374 :
2375 : /** Scan window (N * 0.625 ms)
2376 : *
2377 : * @note When @kconfig{CONFIG_BT_SCAN_AND_INITIATE_IN_PARALLEL} is enabled
2378 : * and the application wants to scan and connect in parallel,
2379 : * the Bluetooth Controller may require the scan window used
2380 : * for scanning and connection establishment to be equal to
2381 : * obtain the best performance.
2382 : */
2383 1 : uint16_t window;
2384 :
2385 : /**
2386 : * @brief Scan timeout (N * 10 ms)
2387 : *
2388 : * Application will be notified by the scan timeout callback.
2389 : * Set zero to disable timeout.
2390 : */
2391 1 : uint16_t timeout;
2392 :
2393 : /**
2394 : * @brief Scan interval LE Coded PHY (N * 0.625 MS)
2395 : *
2396 : * Set zero to use same as LE 1M PHY scan interval.
2397 : */
2398 1 : uint16_t interval_coded;
2399 :
2400 : /**
2401 : * @brief Scan window LE Coded PHY (N * 0.625 MS)
2402 : *
2403 : * Set zero to use same as LE 1M PHY scan window.
2404 : */
2405 1 : uint16_t window_coded;
2406 : };
2407 :
2408 : /** LE advertisement and scan response packet information */
2409 1 : struct bt_le_scan_recv_info {
2410 : /**
2411 : * @brief Advertiser LE address and type.
2412 : *
2413 : * If advertiser is anonymous then this address will be
2414 : * @ref BT_ADDR_LE_ANY.
2415 : */
2416 1 : const bt_addr_le_t *addr;
2417 :
2418 : /** Advertising Set Identifier, valid range @ref BT_GAP_SID_MIN to @ref BT_GAP_SID_MAX. */
2419 1 : uint8_t sid;
2420 :
2421 : /** Strength of advertiser signal. */
2422 1 : int8_t rssi;
2423 :
2424 : /** Transmit power of the advertiser. */
2425 1 : int8_t tx_power;
2426 :
2427 : /**
2428 : * @brief Advertising packet type.
2429 : *
2430 : * Uses the @ref bt_gap_adv_type value.
2431 : *
2432 : * May indicate that this is a scan response if the type is
2433 : * @ref BT_GAP_ADV_TYPE_SCAN_RSP.
2434 : */
2435 1 : uint8_t adv_type;
2436 :
2437 : /**
2438 : * @brief Advertising packet properties bitfield.
2439 : *
2440 : * Uses the @ref bt_gap_adv_prop values.
2441 : * May indicate that this is a scan response if the value contains the
2442 : * @ref BT_GAP_ADV_PROP_SCAN_RESPONSE bit.
2443 : *
2444 : */
2445 1 : uint16_t adv_props;
2446 :
2447 : /**
2448 : * @brief Periodic advertising interval (N * 1.25 ms).
2449 : *
2450 : * If 0 there is no periodic advertising.
2451 : */
2452 1 : uint16_t interval;
2453 :
2454 : /** Primary advertising channel PHY. */
2455 1 : uint8_t primary_phy;
2456 :
2457 : /** Secondary advertising channel PHY. */
2458 1 : uint8_t secondary_phy;
2459 : };
2460 :
2461 : /** Listener context for (LE) scanning. */
2462 1 : struct bt_le_scan_cb {
2463 :
2464 : /**
2465 : * @brief Advertisement packet and scan response received callback.
2466 : *
2467 : * @param info Advertiser packet and scan response information.
2468 : * @param buf Buffer containing advertiser data.
2469 : */
2470 1 : void (*recv)(const struct bt_le_scan_recv_info *info,
2471 : struct net_buf_simple *buf);
2472 :
2473 : /** @brief The scanner has stopped scanning after scan timeout. */
2474 1 : void (*timeout)(void);
2475 :
2476 0 : sys_snode_t node;
2477 : };
2478 :
2479 : /**
2480 : * @brief Initialize scan parameters
2481 : *
2482 : * @param _type Scan Type, @ref BT_LE_SCAN_TYPE_ACTIVE or @ref BT_LE_SCAN_TYPE_PASSIVE.
2483 : * @param _options Scan options
2484 : * @param _interval Scan Interval (N * 0.625 ms)
2485 : * @param _window Scan Window (N * 0.625 ms)
2486 : */
2487 1 : #define BT_LE_SCAN_PARAM_INIT(_type, _options, _interval, _window) \
2488 : { \
2489 : .type = (_type), \
2490 : .options = (_options), \
2491 : .interval = (_interval), \
2492 : .window = (_window), \
2493 : .timeout = 0, \
2494 : .interval_coded = 0, \
2495 : .window_coded = 0, \
2496 : }
2497 :
2498 : /**
2499 : * @brief Helper to declare scan parameters inline
2500 : *
2501 : * @param _type Scan Type, @ref BT_LE_SCAN_TYPE_ACTIVE or @ref BT_LE_SCAN_TYPE_PASSIVE.
2502 : * @param _options Scan options
2503 : * @param _interval Scan Interval (N * 0.625 ms)
2504 : * @param _window Scan Window (N * 0.625 ms)
2505 : */
2506 1 : #define BT_LE_SCAN_PARAM(_type, _options, _interval, _window) \
2507 : ((struct bt_le_scan_param[]) { \
2508 : BT_LE_SCAN_PARAM_INIT(_type, _options, _interval, _window) \
2509 : })
2510 :
2511 : /**
2512 : * @brief Helper macro to enable active scanning to discover new devices.
2513 : */
2514 1 : #define BT_LE_SCAN_ACTIVE BT_LE_SCAN_PARAM(BT_LE_SCAN_TYPE_ACTIVE, \
2515 : BT_LE_SCAN_OPT_FILTER_DUPLICATE, \
2516 : BT_GAP_SCAN_FAST_INTERVAL, \
2517 : BT_GAP_SCAN_FAST_WINDOW)
2518 :
2519 : /**
2520 : * @brief Helper macro to enable active scanning to discover new devices with window == interval.
2521 : *
2522 : * Continuous scanning should be used to maximize the chances of receiving advertising packets.
2523 : */
2524 1 : #define BT_LE_SCAN_ACTIVE_CONTINUOUS BT_LE_SCAN_PARAM(BT_LE_SCAN_TYPE_ACTIVE, \
2525 : BT_LE_SCAN_OPT_FILTER_DUPLICATE, \
2526 : BT_GAP_SCAN_FAST_INTERVAL_MIN, \
2527 : BT_GAP_SCAN_FAST_WINDOW)
2528 : BUILD_ASSERT(BT_GAP_SCAN_FAST_WINDOW == BT_GAP_SCAN_FAST_INTERVAL_MIN,
2529 : "Continuous scanning is requested by setting window and interval equal.");
2530 :
2531 : /**
2532 : * @brief Helper macro to enable passive scanning to discover new devices.
2533 : *
2534 : * This macro should be used if information required for device identification
2535 : * (e.g., UUID) are known to be placed in Advertising Data.
2536 : */
2537 1 : #define BT_LE_SCAN_PASSIVE BT_LE_SCAN_PARAM(BT_LE_SCAN_TYPE_PASSIVE, \
2538 : BT_LE_SCAN_OPT_FILTER_DUPLICATE, \
2539 : BT_GAP_SCAN_FAST_INTERVAL, \
2540 : BT_GAP_SCAN_FAST_WINDOW)
2541 :
2542 : /**
2543 : * @brief Helper macro to enable passive scanning to discover new devices with window==interval.
2544 : *
2545 : * This macro should be used if information required for device identification
2546 : * (e.g., UUID) are known to be placed in Advertising Data.
2547 : */
2548 1 : #define BT_LE_SCAN_PASSIVE_CONTINUOUS BT_LE_SCAN_PARAM(BT_LE_SCAN_TYPE_PASSIVE, \
2549 : BT_LE_SCAN_OPT_FILTER_DUPLICATE, \
2550 : BT_GAP_SCAN_FAST_INTERVAL_MIN, \
2551 : BT_GAP_SCAN_FAST_WINDOW)
2552 : BUILD_ASSERT(BT_GAP_SCAN_FAST_WINDOW == BT_GAP_SCAN_FAST_INTERVAL_MIN,
2553 : "Continuous scanning is requested by setting window and interval equal.");
2554 :
2555 : /**
2556 : * @brief Helper macro to enable active scanning to discover new devices.
2557 : * Include scanning on Coded PHY in addition to 1M PHY.
2558 : */
2559 1 : #define BT_LE_SCAN_CODED_ACTIVE \
2560 : BT_LE_SCAN_PARAM(BT_LE_SCAN_TYPE_ACTIVE, \
2561 : BT_LE_SCAN_OPT_CODED | \
2562 : BT_LE_SCAN_OPT_FILTER_DUPLICATE, \
2563 : BT_GAP_SCAN_FAST_INTERVAL, \
2564 : BT_GAP_SCAN_FAST_WINDOW)
2565 :
2566 : /**
2567 : * @brief Helper macro to enable passive scanning to discover new devices.
2568 : * Include scanning on Coded PHY in addition to 1M PHY.
2569 : *
2570 : * This macro should be used if information required for device identification
2571 : * (e.g., UUID) are known to be placed in Advertising Data.
2572 : */
2573 1 : #define BT_LE_SCAN_CODED_PASSIVE \
2574 : BT_LE_SCAN_PARAM(BT_LE_SCAN_TYPE_PASSIVE, \
2575 : BT_LE_SCAN_OPT_CODED | \
2576 : BT_LE_SCAN_OPT_FILTER_DUPLICATE, \
2577 : BT_GAP_SCAN_FAST_INTERVAL, \
2578 : BT_GAP_SCAN_FAST_WINDOW)
2579 :
2580 : /**
2581 : * @brief Start (LE) scanning
2582 : *
2583 : * Start LE scanning with given parameters and provide results through
2584 : * the specified callback.
2585 : *
2586 : * @note The LE scanner by default does not use the Identity Address of the
2587 : * local device when @kconfig{CONFIG_BT_PRIVACY} is disabled. This is to
2588 : * prevent the active scanner from disclosing the identity address information
2589 : * when requesting additional information from advertisers.
2590 : * In order to enable directed advertiser reports then
2591 : * @kconfig{CONFIG_BT_SCAN_WITH_IDENTITY} must be enabled.
2592 : *
2593 : * @note Setting the `param.timeout` parameter is not supported when
2594 : * @kconfig{CONFIG_BT_PRIVACY} is enabled, when the param.type is @ref
2595 : * BT_LE_SCAN_TYPE_ACTIVE. Supplying a non-zero timeout will result in an
2596 : * -EINVAL error code.
2597 : *
2598 : * @note The scanner will automatically scan for extended advertising packets if their support is
2599 : * enabled through @kconfig{CONFIG_BT_EXT_ADV}.
2600 : *
2601 : * @param param Scan parameters.
2602 : * @param cb Callback to notify scan results. May be NULL if callback
2603 : * registration through @ref bt_le_scan_cb_register is preferred.
2604 : *
2605 : * @return Zero on success or error code otherwise, positive in case of
2606 : * protocol error or negative (POSIX) in case of stack internal error.
2607 : * @retval -EBUSY if the scanner is already being started in a different thread.
2608 : */
2609 1 : int bt_le_scan_start(const struct bt_le_scan_param *param, bt_le_scan_cb_t cb);
2610 :
2611 : /**
2612 : * @brief Stop (LE) scanning.
2613 : *
2614 : * Stops ongoing LE scanning.
2615 : *
2616 : * @return Zero on success or error code otherwise, positive in case of
2617 : * protocol error or negative (POSIX) in case of stack internal error.
2618 : */
2619 1 : int bt_le_scan_stop(void);
2620 :
2621 : /**
2622 : * @brief Register scanner packet callbacks.
2623 : *
2624 : * Adds the callback structure to the list of callback structures that monitors
2625 : * scanner activity.
2626 : *
2627 : * This callback will be called for all scanner activity.
2628 : *
2629 : * @param cb Callback struct. Must point to memory that remains valid.
2630 : *
2631 : * @retval 0 Success.
2632 : * @retval -EEXIST if @p cb was already registered.
2633 : */
2634 1 : int bt_le_scan_cb_register(struct bt_le_scan_cb *cb);
2635 :
2636 : /**
2637 : * @brief Unregister scanner packet callbacks.
2638 : *
2639 : * Remove the callback structure from the list of scanner callbacks.
2640 : *
2641 : * @param cb Callback struct. Must point to memory that remains valid.
2642 : */
2643 1 : void bt_le_scan_cb_unregister(struct bt_le_scan_cb *cb);
2644 :
2645 : /**
2646 : * @brief Add device (LE) to filter accept list.
2647 : *
2648 : * Add peer device LE address to the filter accept list.
2649 : *
2650 : * @note The filter accept list cannot be modified when an LE role is using
2651 : * the filter accept list, i.e advertiser or scanner using a filter accept list
2652 : * or automatic connecting to devices using filter accept list.
2653 : *
2654 : * @param addr Bluetooth LE identity address.
2655 : *
2656 : * @return Zero on success or error code otherwise, positive in case of
2657 : * protocol error or negative (POSIX) in case of stack internal error.
2658 : */
2659 1 : int bt_le_filter_accept_list_add(const bt_addr_le_t *addr);
2660 :
2661 : /**
2662 : * @brief Remove device (LE) from filter accept list.
2663 : *
2664 : * Remove peer device LE address from the filter accept list.
2665 : *
2666 : * @note The filter accept list cannot be modified when an LE role is using
2667 : * the filter accept list, i.e advertiser or scanner using a filter accept list
2668 : * or automatic connecting to devices using filter accept list.
2669 : *
2670 : * @param addr Bluetooth LE identity address.
2671 : *
2672 : * @return Zero on success or error code otherwise, positive in case of
2673 : * protocol error or negative (POSIX) in case of stack internal error.
2674 : */
2675 1 : int bt_le_filter_accept_list_remove(const bt_addr_le_t *addr);
2676 :
2677 : /**
2678 : * @brief Clear filter accept list.
2679 : *
2680 : * Clear all devices from the filter accept list.
2681 : *
2682 : * @note The filter accept list cannot be modified when an LE role is using
2683 : * the filter accept list, i.e advertiser or scanner using a filter accept
2684 : * list or automatic connecting to devices using filter accept list.
2685 : *
2686 : * @return Zero on success or error code otherwise, positive in case of
2687 : * protocol error or negative (POSIX) in case of stack internal error.
2688 : */
2689 1 : int bt_le_filter_accept_list_clear(void);
2690 :
2691 : /**
2692 : * @brief Set (LE) channel map.
2693 : *
2694 : * Used to inform the Controller of known channel classifications. The Host can specify which
2695 : * channels are bad or unknown by setting the corresponding bit in the channel map to respectively
2696 : * 0 or 1.
2697 : *
2698 : * @note The interval between two succesive calls to this function must be at least one second.
2699 : *
2700 : * @param chan_map Channel map. 5 octets where each bit represents a channel. Only the lower 37 bits
2701 : * are valid.
2702 : *
2703 : * @return Zero on success or error code otherwise, positive in case of
2704 : * protocol error or negative (POSIX) in case of stack internal error.
2705 : */
2706 1 : int bt_le_set_chan_map(uint8_t chan_map[5]);
2707 :
2708 : /**
2709 : * @brief Set the Resolvable Private Address timeout in runtime
2710 : *
2711 : * The new RPA timeout value will be used for the next RPA rotation
2712 : * and all subsequent rotations until another override is scheduled
2713 : * with this API.
2714 : *
2715 : * Initially, @kconfig{CONFIG_BT_RPA_TIMEOUT} is used as the RPA timeout.
2716 : *
2717 : * @kconfig_dep{CONFIG_BT_RPA_TIMEOUT_DYNAMIC}.
2718 : *
2719 : * @param new_rpa_timeout Resolvable Private Address timeout in seconds.
2720 : *
2721 : * @retval 0 Success.
2722 : * @retval -EINVAL RPA timeout value is invalid. Valid range is 1s - 3600s.
2723 : */
2724 1 : int bt_le_set_rpa_timeout(uint16_t new_rpa_timeout);
2725 :
2726 : /**
2727 : * @brief Helper for parsing advertising (or EIR or OOB) data.
2728 : *
2729 : * A helper for parsing the basic AD Types used for Extended Inquiry
2730 : * Response (EIR), Advertising Data (AD), and OOB data blocks. The most
2731 : * common scenario is to call this helper on the advertising data
2732 : * received in the callback that was given to @ref bt_le_scan_start.
2733 : *
2734 : * @warning This helper function will consume @p ad when parsing. The user should make a copy if the
2735 : * original data is to be used afterwards. This can be done by using
2736 : * @ref net_buf_simple_save to store the state prior to the function call, and then using
2737 : * @ref net_buf_simple_restore to restore the state afterwards.
2738 : *
2739 : * @param ad Advertising data as given to the @ref bt_le_scan_cb_t callback.
2740 : * @param func Callback function which will be called for each element
2741 : * that's found in the data. The callback should return
2742 : * true to continue parsing, or false to stop parsing.
2743 : * @param user_data User data to be passed to the callback.
2744 : */
2745 1 : void bt_data_parse(struct net_buf_simple *ad,
2746 : bool (*func)(struct bt_data *data, void *user_data),
2747 : void *user_data);
2748 :
2749 : /** LE Secure Connections pairing Out of Band data. */
2750 1 : struct bt_le_oob_sc_data {
2751 : /** Random Number. */
2752 1 : uint8_t r[16];
2753 :
2754 : /** Confirm Value. */
2755 1 : uint8_t c[16];
2756 : };
2757 :
2758 : /** LE Out of Band information. */
2759 1 : struct bt_le_oob {
2760 : /** LE address. If privacy is enabled this is a Resolvable Private
2761 : * Address.
2762 : */
2763 1 : bt_addr_le_t addr;
2764 :
2765 : /** LE Secure Connections pairing Out of Band data. */
2766 1 : struct bt_le_oob_sc_data le_sc_data;
2767 : };
2768 :
2769 : /**
2770 : * @brief Get local LE Out of Band (OOB) information.
2771 : *
2772 : * This function allows to get local information that are useful for
2773 : * Out of Band pairing or connection creation.
2774 : *
2775 : * If privacy @kconfig{CONFIG_BT_PRIVACY} is enabled this will result in
2776 : * generating new Resolvable Private Address (RPA) that is valid for
2777 : * @kconfig{CONFIG_BT_RPA_TIMEOUT} seconds. This address will be used for
2778 : * advertising started by @ref bt_le_adv_start, active scanning and
2779 : * connection creation.
2780 : *
2781 : * @note If privacy is enabled the RPA cannot be refreshed in the following
2782 : * cases:
2783 : * - Creating a connection in progress, wait for the connected callback.
2784 : * In addition when extended advertising @kconfig{CONFIG_BT_EXT_ADV} is
2785 : * not enabled or not supported by the controller:
2786 : * - Advertiser is enabled using a Random Static Identity Address as a
2787 : * different local identity address.
2788 : * - The local identity address conflicts with the local identity address used by other
2789 : * roles.
2790 : *
2791 : * @param[in] id Local identity handle (typically @ref BT_ID_DEFAULT). Corresponds to the identity
2792 : * address this function will be called for.
2793 : * @param[out] oob LE OOB information
2794 : *
2795 : * @return Zero on success or error code otherwise, positive in case of
2796 : * protocol error or negative (POSIX) in case of stack internal error.
2797 : */
2798 1 : int bt_le_oob_get_local(uint8_t id, struct bt_le_oob *oob);
2799 :
2800 : /**
2801 : * @brief Get local LE Out of Band (OOB) information.
2802 : *
2803 : * This function allows to get local information that are useful for
2804 : * Out of Band pairing or connection creation.
2805 : *
2806 : * If privacy @kconfig{CONFIG_BT_PRIVACY} is enabled this will result in
2807 : * generating new Resolvable Private Address (RPA) that is valid for
2808 : * @kconfig{CONFIG_BT_RPA_TIMEOUT} seconds. This address will be used by the
2809 : * advertising set.
2810 : *
2811 : * @note When generating OOB information for multiple advertising set all
2812 : * OOB information needs to be generated at the same time.
2813 : *
2814 : * @note If privacy is enabled the RPA cannot be refreshed in the following
2815 : * cases:
2816 : * - Creating a connection in progress, wait for the connected callback.
2817 : *
2818 : * @param[in] adv The advertising set object
2819 : * @param[out] oob LE OOB information
2820 : *
2821 : * @return Zero on success or error code otherwise, positive in case
2822 : * of protocol error or negative (POSIX) in case of stack internal error.
2823 : */
2824 1 : int bt_le_ext_adv_oob_get_local(struct bt_le_ext_adv *adv,
2825 : struct bt_le_oob *oob);
2826 :
2827 : /**
2828 : * @brief Clear pairing information.
2829 : *
2830 : * @param id Local identity handle (typically @ref BT_ID_DEFAULT). Corresponds to the identity
2831 : * address this function will be called for.
2832 : * @param addr Remote address, NULL or BT_ADDR_LE_ANY to clear all remote
2833 : * devices.
2834 : *
2835 : * @return 0 on success or negative error value on failure.
2836 : */
2837 1 : int bt_unpair(uint8_t id, const bt_addr_le_t *addr);
2838 :
2839 : /** Information about a bond with a remote device. */
2840 1 : struct bt_bond_info {
2841 : /** Address of the remote device. */
2842 1 : bt_addr_le_t addr;
2843 : };
2844 :
2845 : /**
2846 : * @brief Iterate through all existing bonds.
2847 : *
2848 : * @param id Local identity handle (typically @ref BT_ID_DEFAULT). Corresponds to the
2849 : * identity address used in iteration.
2850 : * @param func Function to call for each bond.
2851 : * @param user_data Data to pass to the callback function.
2852 : */
2853 1 : void bt_foreach_bond(uint8_t id, void (*func)(const struct bt_bond_info *info,
2854 : void *user_data),
2855 : void *user_data);
2856 :
2857 : /**
2858 : * @brief Configure vendor data path
2859 : *
2860 : * @details Request the Controller to configure the data transport path in a given direction between
2861 : * the Controller and the Host.
2862 : *
2863 : * @param dir Direction to be configured, BT_HCI_DATAPATH_DIR_HOST_TO_CTLR or
2864 : * BT_HCI_DATAPATH_DIR_CTLR_TO_HOST
2865 : * @param id Vendor specific logical transport channel ID, range
2866 : * [BT_HCI_DATAPATH_ID_VS..BT_HCI_DATAPATH_ID_VS_END]
2867 : * @param vs_config_len Length of additional vendor specific configuration data
2868 : * @param vs_config Pointer to additional vendor specific configuration data
2869 : *
2870 : * @return 0 in case of success or negative value in case of error.
2871 : */
2872 1 : int bt_configure_data_path(uint8_t dir, uint8_t id, uint8_t vs_config_len,
2873 : const uint8_t *vs_config);
2874 :
2875 : /**
2876 : * @brief Parameters for synchronizing with specific periodic advertising subevents.
2877 : *
2878 : * @details This struct contains the parameters used to synchronize with a subset of subevents in
2879 : * periodic advertising. It includes the periodic advertising properties, the number of subevents
2880 : * to sync to, and the list of subevents that the controller should synchronize with.
2881 : *
2882 : * @note Used in @ref bt_le_per_adv_sync_subevent function to control synchronization.
2883 : */
2884 1 : struct bt_le_per_adv_sync_subevent_params {
2885 : /** @brief Periodic Advertising Properties.
2886 : *
2887 : * Bit 6 is include TxPower, all others RFU.
2888 : *
2889 : */
2890 1 : uint16_t properties;
2891 :
2892 : /** Number of subevents to sync to */
2893 1 : uint8_t num_subevents;
2894 :
2895 : /** @brief The subevent(s) to synchronize with
2896 : *
2897 : * The array must have @ref num_subevents elements.
2898 : *
2899 : */
2900 1 : uint8_t *subevents;
2901 : };
2902 :
2903 : /** @brief Synchronize with a subset of subevents
2904 : *
2905 : * Until this command is issued, the subevent(s) the controller is synchronized
2906 : * to is unspecified.
2907 : *
2908 : * @param per_adv_sync The periodic advertising sync object.
2909 : * @param params Subevent sync parameters.
2910 : *
2911 : * @return 0 in case of success or negative value in case of error.
2912 : */
2913 1 : int bt_le_per_adv_sync_subevent(struct bt_le_per_adv_sync *per_adv_sync,
2914 : struct bt_le_per_adv_sync_subevent_params *params);
2915 :
2916 : /**
2917 : * @brief Parameters for sending a periodic advertising response.
2918 : *
2919 : * @details This struct contains the parameters used when sending a response to a periodic
2920 : * advertising request (see @ref bt_le_per_adv_set_response_data function). The response is sent
2921 : * in the specified subevent and response slot, and includes event and subevent counters
2922 : * to track the request the response corresponds to.
2923 : */
2924 1 : struct bt_le_per_adv_response_params {
2925 : /**
2926 : * @brief The periodic event counter of the request the response is sent to.
2927 : *
2928 : * @ref bt_le_per_adv_sync_recv_info
2929 : *
2930 : * @note The response can be sent up to one periodic interval after
2931 : * the request was received.
2932 : *
2933 : */
2934 1 : uint16_t request_event;
2935 :
2936 : /**
2937 : * @brief The subevent counter of the request the response is sent to.
2938 : *
2939 : * @ref bt_le_per_adv_sync_recv_info
2940 : *
2941 : */
2942 1 : uint8_t request_subevent;
2943 :
2944 : /** The subevent the response shall be sent in */
2945 1 : uint8_t response_subevent;
2946 :
2947 : /** The response slot the response shall be sent in */
2948 1 : uint8_t response_slot;
2949 : };
2950 :
2951 : /**
2952 : * @brief Set the data for a response slot in a specific subevent of the PAwR.
2953 : *
2954 : * This function is called by the application to set the response data.
2955 : * The data for a response slot shall be transmitted only once.
2956 : *
2957 : * @param per_adv_sync The periodic advertising sync object.
2958 : * @param params Parameters.
2959 : * @param data The response data to send.
2960 : *
2961 : * @return Zero on success or (negative) error code otherwise.
2962 : */
2963 1 : int bt_le_per_adv_set_response_data(struct bt_le_per_adv_sync *per_adv_sync,
2964 : const struct bt_le_per_adv_response_params *params,
2965 : const struct net_buf_simple *data);
2966 :
2967 : /**
2968 : * @brief Check if a device identified by a Bluetooth LE address is bonded.
2969 : *
2970 : * @details Valid Bluetooth LE identity addresses are either public address or random static
2971 : * address.
2972 : *
2973 : * @param id Local identity handle (typically @ref BT_ID_DEFAULT). Corresponds to the identity
2974 : * address this function will be called for.
2975 : * @param addr Bluetooth LE device address.
2976 : *
2977 : * @return true if @p addr is bonded with local @p id
2978 : */
2979 1 : bool bt_le_bond_exists(uint8_t id, const bt_addr_le_t *addr);
2980 :
2981 : /**
2982 : * @}
2983 : */
2984 :
2985 : #ifdef __cplusplus
2986 : }
2987 : #endif
2988 : /**
2989 : * @}
2990 : */
2991 :
2992 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_BLUETOOTH_H_ */
|
