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 0 : enum bt_le_adv_opt {
691 : /** Convenience value when no options are specified. */
692 : BT_LE_ADV_OPT_NONE = 0,
693 :
694 : /**
695 : * @brief Advertise as connectable.
696 : *
697 : * @deprecated Use @ref BT_LE_ADV_OPT_CONN instead.
698 : *
699 : * Advertise as connectable. If not connectable then the type of
700 : * advertising is determined by providing scan response data.
701 : * The advertiser address is determined by the type of advertising
702 : * and/or enabling privacy @kconfig{CONFIG_BT_PRIVACY}.
703 : *
704 : * Starting connectable advertising preallocates a connection
705 : * object. If this fails, the API returns @c -ENOMEM.
706 : *
707 : * When an advertiser set results in a connection creation, the
708 : * controller automatically disables that advertising set.
709 : *
710 : * If the advertising set was started with @ref bt_le_adv_start
711 : * without @ref BT_LE_ADV_OPT_ONE_TIME, the host will attempt to
712 : * resume the advertiser under some conditions.
713 : */
714 : BT_LE_ADV_OPT_CONNECTABLE __deprecated = BIT(0),
715 :
716 : /**
717 : * @internal
718 : *
719 : * Internal access to the deprecated value to maintain the
720 : * implementation of the deprecated feature.
721 : *
722 : * At the end of the deprecation period, ABI will change so
723 : * `BT_LE_ADV_OPT_CONN` is just `BIT(0)`, removing the need for this
724 : * symbol.
725 : */
726 : _BT_LE_ADV_OPT_CONNECTABLE = BIT(0),
727 :
728 : /**
729 : * @brief Advertise one time.
730 : *
731 : * @deprecated Use @ref BT_LE_ADV_OPT_CONN instead.
732 : *
733 : * Don't try to resume connectable advertising after a connection.
734 : * This option is only meaningful when used together with
735 : * BT_LE_ADV_OPT_CONNECTABLE. If set the advertising will be stopped
736 : * when @ref bt_le_adv_stop is called or when an incoming (peripheral)
737 : * connection happens. If this option is not set the stack will
738 : * take care of keeping advertising enabled even as connections
739 : * occur.
740 : * If Advertising directed or the advertiser was started with
741 : * @ref bt_le_ext_adv_start then this behavior is the default behavior
742 : * and this flag has no effect.
743 : */
744 : BT_LE_ADV_OPT_ONE_TIME __deprecated = BIT(1),
745 :
746 : /**
747 : * @internal
748 : *
749 : * Internal access to the deprecated value to maintain
750 : * the implementation of the deprecated feature.
751 : */
752 : _BT_LE_ADV_OPT_ONE_TIME = BIT(1),
753 :
754 : /**
755 : * @brief Connectable advertising
756 : *
757 : * Starting connectable advertising preallocates a connection
758 : * object. If this fails, the API returns @c -ENOMEM.
759 : *
760 : * The advertising set stops immediately after it creates a
761 : * connection. This happens automatically in the controller.
762 : *
763 : * @note To continue advertising after a connection is created,
764 : * the application should listen for the @ref bt_conn_cb.connected
765 : * event and start the advertising set again. Note that the
766 : * advertiser cannot be started when all connection objects are
767 : * in use. In that case, defer starting the advertiser until
768 : * @ref bt_conn_cb.recycled. To continue after a disconnection,
769 : * listen for @ref bt_conn_cb.recycled.
770 :
771 : */
772 : BT_LE_ADV_OPT_CONN = BIT(0) | BIT(1),
773 :
774 : /**
775 : * @brief Advertise using identity address.
776 : *
777 : * Advertise using the identity address as the advertiser address.
778 : * @warning This will compromise the privacy of the device, so care
779 : * must be taken when using this option.
780 : * @note The address used for advertising will not be the same as
781 : * returned by @ref bt_le_oob_get_local, instead @ref bt_id_get
782 : * should be used to get the LE address.
783 : */
784 : BT_LE_ADV_OPT_USE_IDENTITY = BIT(2),
785 :
786 : /**
787 : * @brief Low duty cycle directed advertising.
788 : *
789 : * Use low duty directed advertising mode, otherwise high duty mode
790 : * will be used.
791 : */
792 : BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY = BIT(4),
793 :
794 : /**
795 : * @brief Directed advertising to privacy-enabled peer.
796 : *
797 : * Enable use of Resolvable Private Address (RPA) as the target address
798 : * in directed advertisements.
799 : * This is required if the remote device is privacy-enabled and
800 : * supports address resolution of the target address in directed
801 : * advertisement.
802 : * It is the responsibility of the application to check that the remote
803 : * device supports address resolution of directed advertisements by
804 : * reading its Central Address Resolution characteristic.
805 : */
806 : BT_LE_ADV_OPT_DIR_ADDR_RPA = BIT(5),
807 :
808 : /** Use filter accept list to filter devices that can request scan
809 : * response data.
810 : */
811 : BT_LE_ADV_OPT_FILTER_SCAN_REQ = BIT(6),
812 :
813 : /** Use filter accept list to filter devices that can connect. */
814 : BT_LE_ADV_OPT_FILTER_CONN = BIT(7),
815 :
816 : /** Notify the application when a scan response data has been sent to an
817 : * active scanner.
818 : */
819 : BT_LE_ADV_OPT_NOTIFY_SCAN_REQ = BIT(8),
820 :
821 : /**
822 : * @brief Support scan response data.
823 : *
824 : * When used together with @ref BT_LE_ADV_OPT_EXT_ADV then this option
825 : * cannot be used together with the @ref BT_LE_ADV_OPT_CONN option.
826 : * When used together with @ref BT_LE_ADV_OPT_EXT_ADV then scan
827 : * response data must be set.
828 : */
829 : BT_LE_ADV_OPT_SCANNABLE = BIT(9),
830 :
831 : /**
832 : * @brief Advertise with extended advertising.
833 : *
834 : * This options enables extended advertising in the advertising set.
835 : * In extended advertising the advertising set will send a small header
836 : * packet on the three primary advertising channels. This small header
837 : * points to the advertising data packet that will be sent on one of
838 : * the 37 secondary advertising channels.
839 : * The advertiser will send primary advertising on LE 1M PHY, and
840 : * secondary advertising on LE 2M PHY.
841 : * Connections will be established on LE 2M PHY.
842 : *
843 : * Without this option the advertiser will send advertising data on the
844 : * three primary advertising channels.
845 : *
846 : * @note Enabling this option requires extended advertising support in
847 : * the peer devices scanning for advertisement packets.
848 : *
849 : * @note This cannot be used with @ref bt_le_adv_start.
850 : */
851 : BT_LE_ADV_OPT_EXT_ADV = BIT(10),
852 :
853 : /**
854 : * @brief Disable use of LE 2M PHY on the secondary advertising
855 : * channel.
856 : *
857 : * Disabling the use of LE 2M PHY could be necessary if scanners don't
858 : * support the LE 2M PHY.
859 : * The advertiser will send primary advertising on LE 1M PHY, and
860 : * secondary advertising on LE 1M PHY.
861 : * Connections will be established on LE 1M PHY.
862 : *
863 : * @note Cannot be set if BT_LE_ADV_OPT_CODED is set.
864 : *
865 : * @note Requires @ref BT_LE_ADV_OPT_EXT_ADV bit (see @ref bt_le_adv_opt field) to be
866 : * set as @ref bt_le_adv_param.options.
867 : */
868 : BT_LE_ADV_OPT_NO_2M = BIT(11),
869 :
870 : /**
871 : * @brief Advertise on the LE Coded PHY (Long Range).
872 : *
873 : * The advertiser will send both primary and secondary advertising
874 : * on the LE Coded PHY. This gives the advertiser increased range with
875 : * the trade-off of lower data rate and higher power consumption.
876 : * Connections will be established on LE Coded PHY.
877 : *
878 : * @note Requires @ref BT_LE_ADV_OPT_EXT_ADV bit (see @ref bt_le_adv_opt field) to be
879 : * set as @ref bt_le_adv_param.options.
880 : */
881 : BT_LE_ADV_OPT_CODED = BIT(12),
882 :
883 : /**
884 : * @brief Advertise without a device address (identity address or RPA).
885 : *
886 : * @note Requires @ref BT_LE_ADV_OPT_EXT_ADV bit (see @ref bt_le_adv_opt field) to be
887 : * set as @ref bt_le_adv_param.options.
888 : */
889 : BT_LE_ADV_OPT_ANONYMOUS = BIT(13),
890 :
891 : /**
892 : * @brief Advertise with transmit power.
893 : *
894 : * @note Requires @ref BT_LE_ADV_OPT_EXT_ADV bit (see @ref bt_le_adv_opt field) to be
895 : * set as @ref bt_le_adv_param.options.
896 : */
897 : BT_LE_ADV_OPT_USE_TX_POWER = BIT(14),
898 :
899 : /** Disable advertising on channel index 37. */
900 : BT_LE_ADV_OPT_DISABLE_CHAN_37 = BIT(15),
901 :
902 : /** Disable advertising on channel index 38. */
903 : BT_LE_ADV_OPT_DISABLE_CHAN_38 = BIT(16),
904 :
905 : /** Disable advertising on channel index 39. */
906 : BT_LE_ADV_OPT_DISABLE_CHAN_39 = BIT(17),
907 :
908 : /**
909 : * @brief Advertise using a Non-Resolvable Private Address.
910 : *
911 : * A new NRPA is set when updating the advertising parameters.
912 : *
913 : * This is an advanced feature; most users will want to enable
914 : * @kconfig{CONFIG_BT_EXT_ADV} instead.
915 : *
916 : * @note Not implemented when @kconfig{CONFIG_BT_PRIVACY}.
917 : *
918 : * @note Mutually exclusive with BT_LE_ADV_OPT_USE_IDENTITY.
919 : */
920 : BT_LE_ADV_OPT_USE_NRPA = BIT(19),
921 :
922 : /**
923 : * @brief Configures the advertiser to use the S=2 coding scheme for
924 : * LE Coded PHY.
925 : *
926 : * Sets the advertiser's required coding scheme to S=2, which is one
927 : * of the coding options available for LE Coded PHY. The S=2 coding
928 : * scheme offers higher data rates compared to S=8, with a trade-off
929 : * of reduced range. The coding scheme will only be set if both the
930 : * primary and secondary advertising channels indicate LE Coded Phy.
931 : * Additionally, the Controller must support the LE Feature Advertising
932 : * Coding Selection. If these conditions are not met, it will default to
933 : * no required coding scheme.
934 : *
935 : * @kconfig_dep{BT_EXT_ADV_CODING_SELECTION}
936 : */
937 : BT_LE_ADV_OPT_REQUIRE_S2_CODING = BIT(20),
938 :
939 : /**
940 : * @brief Configures the advertiser to use the S=8 coding scheme for
941 : * LE Coded PHY.
942 : *
943 : * Sets the advertiser's required coding scheme to S=8, which is one
944 : * of the coding options available for LE Coded PHY. The S=8 coding
945 : * scheme offers increased range compared to S=2, with a trade-off
946 : * of lower data rates. The coding scheme will only be set if both the
947 : * primary and secondary advertising channels indicate LE Coded Phy.
948 : * Additionally, the Controller must support the LE Feature Advertising
949 : * Coding Selection. If these conditions are not met, it will default to
950 : * no required coding scheme.
951 : *
952 : * @kconfig_dep{BT_EXT_ADV_CODING_SELECTION}
953 : */
954 : BT_LE_ADV_OPT_REQUIRE_S8_CODING = BIT(21),
955 : };
956 :
957 : /** LE Advertising Parameters. */
958 1 : struct bt_le_adv_param {
959 : /**
960 : * @brief Local identity handle.
961 : *
962 : * The index of the identity address in the local Bluetooth controller.
963 : *
964 : * @note When extended advertising @kconfig{CONFIG_BT_EXT_ADV} is not
965 : * enabled or not supported by the controller it is not possible
966 : * to scan and advertise simultaneously using two different
967 : * random addresses.
968 : */
969 1 : uint8_t id;
970 :
971 : /**
972 : * @brief Advertising Set Identifier, valid range is @ref BT_GAP_SID_MIN to
973 : * @ref BT_GAP_SID_MAX.
974 : *
975 : * @note Requires @ref BT_LE_ADV_OPT_EXT_ADV bit (see @ref bt_le_adv_opt field) to be
976 : *set as @ref bt_le_adv_param.options.
977 : **/
978 1 : uint8_t sid;
979 :
980 : /**
981 : * @brief Secondary channel maximum skip count.
982 : *
983 : * Maximum advertising events the advertiser can skip before it must
984 : * send advertising data on the secondary advertising channel.
985 : *
986 : * @note Requires @ref BT_LE_ADV_OPT_EXT_ADV bit (see @ref bt_le_adv_opt field) to be
987 : * set as @ref bt_le_adv_param.options.
988 : */
989 1 : uint8_t secondary_max_skip;
990 :
991 : /** @brief Bit-field of advertising options, see the @ref bt_le_adv_opt field. */
992 1 : uint32_t options;
993 :
994 : /**
995 : * @brief Minimum Advertising Interval (N * 0.625 milliseconds)
996 : *
997 : * @details The Minimum Advertising Interval shall be less than or equal to the Maximum
998 : * Advertising Interval. The Minimum Advertising Interval and Maximum Advertising Interval
999 : * aren't recommended to be the same value to enable the Controller to determine the best
1000 : * advertising interval given other activities.
1001 : * (See Bluetooth Core Spec 6.0, Vol 4, Part E, section 7.8.5)
1002 : * Range: 0x0020 to 0x4000
1003 : */
1004 1 : uint32_t interval_min;
1005 :
1006 : /**
1007 : * @brief Maximum Advertising Interval (N * 0.625 milliseconds)
1008 : *
1009 : * @details The Maximum Advertising Interval shall be more than or equal to the Minimum
1010 : * Advertising Interval. The Minimum Advertising Interval and Maximum Advertising Interval
1011 : * aren't recommended to be the same value to enable the Controller to determine the best
1012 : * advertising interval given other activities.
1013 : * (See Bluetooth Core Spec 6.0, Vol 4, Part E, section 7.8.5)
1014 : * Range: 0x0020 to 0x4000
1015 : */
1016 1 : uint32_t interval_max;
1017 :
1018 : /**
1019 : * @brief Directed advertising to peer
1020 : *
1021 : * When this parameter is set the advertiser will send directed
1022 : * advertising to the remote device.
1023 : *
1024 : * The advertising type will either be high duty cycle, or low duty
1025 : * cycle if the @ref BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY option is enabled.
1026 : * When using @ref BT_LE_ADV_OPT_EXT_ADV then only low duty cycle is
1027 : * allowed.
1028 : *
1029 : * In case of connectable high duty cycle if the connection could not
1030 : * be established within the timeout the connected callback will be
1031 : * called with the status set to @ref BT_HCI_ERR_ADV_TIMEOUT.
1032 : */
1033 1 : const bt_addr_le_t *peer;
1034 : };
1035 :
1036 :
1037 : /** Periodic Advertising options */
1038 1 : enum bt_le_per_adv_opt {
1039 : /** Convenience value when no options are specified. */
1040 : BT_LE_PER_ADV_OPT_NONE = 0,
1041 :
1042 : /**
1043 : * @brief Advertise with transmit power.
1044 : *
1045 : * @note Requires @ref BT_LE_ADV_OPT_EXT_ADV bit (see @ref bt_le_adv_opt field) to be
1046 : * set as @ref bt_le_adv_param.options.
1047 : */
1048 : BT_LE_PER_ADV_OPT_USE_TX_POWER = BIT(1),
1049 :
1050 : /**
1051 : * @brief Advertise with included AdvDataInfo (ADI).
1052 : *
1053 : * @note Requires @ref BT_LE_ADV_OPT_EXT_ADV bit (see @ref bt_le_adv_opt field) to be
1054 : * set as @ref bt_le_adv_param.options.
1055 : */
1056 : BT_LE_PER_ADV_OPT_INCLUDE_ADI = BIT(2),
1057 : };
1058 :
1059 : /**
1060 : * @brief Parameters for configuring periodic advertising.
1061 : *
1062 : * @details This struct is used to configure the parameters for periodic advertising, including the
1063 : * minimum and maximum advertising intervals, options, and settings for subevents if periodic
1064 : * advertising responses are supported. The intervals are specified in units of 1.25 ms, and the
1065 : * options field can be used to modify other advertising behaviors. For extended advertisers, the
1066 : * periodic advertising parameters can be set or updated using this structure. Some parameters are
1067 : * conditional based on whether the device supports periodic advertising responses (configured via
1068 : * @kconfig{CONFIG_BT_PER_ADV_RSP}).
1069 : *
1070 : * @note Used in @ref bt_le_per_adv_set_param function.
1071 : */
1072 1 : struct bt_le_per_adv_param {
1073 : /**
1074 : * @brief Minimum Periodic Advertising Interval (N * 1.25 ms)
1075 : *
1076 : * Shall be greater or equal to BT_GAP_PER_ADV_MIN_INTERVAL and
1077 : * less or equal to interval_max.
1078 : */
1079 1 : uint16_t interval_min;
1080 :
1081 : /**
1082 : * @brief Maximum Periodic Advertising Interval (N * 1.25 ms)
1083 : *
1084 : * Shall be less or equal to BT_GAP_PER_ADV_MAX_INTERVAL and
1085 : * greater or equal to interval_min.
1086 : */
1087 1 : uint16_t interval_max;
1088 :
1089 : /** Bit-field of periodic advertising options, see the @ref bt_le_adv_opt field. */
1090 1 : uint32_t options;
1091 :
1092 : #if defined(CONFIG_BT_PER_ADV_RSP)
1093 : /**
1094 : * @brief Number of subevents
1095 : *
1096 : * If zero, the periodic advertiser will be a broadcaster, without responses.
1097 : */
1098 : uint8_t num_subevents;
1099 :
1100 : /**
1101 : * @brief Interval between subevents (N * 1.25 ms)
1102 : *
1103 : * Shall be between 7.5ms and 318.75 ms.
1104 : */
1105 : uint8_t subevent_interval;
1106 :
1107 : /**
1108 : * @brief Time between the advertising packet in a subevent and the
1109 : * first response slot (N * 1.25 ms)
1110 : *
1111 : */
1112 : uint8_t response_slot_delay;
1113 :
1114 : /**
1115 : * @brief Time between response slots (N * 0.125 ms)
1116 : *
1117 : * Shall be between 0.25 and 31.875 ms.
1118 : */
1119 : uint8_t response_slot_spacing;
1120 :
1121 : /**
1122 : * @brief Number of subevent response slots
1123 : *
1124 : * If zero, response_slot_delay and response_slot_spacing are ignored.
1125 : */
1126 : uint8_t num_response_slots;
1127 : #endif /* CONFIG_BT_PER_ADV_RSP */
1128 : };
1129 :
1130 : /**
1131 : * @brief Initialize advertising parameters
1132 : *
1133 : * @param _options Advertising Options
1134 : * @param _int_min Minimum advertising interval
1135 : * @param _int_max Maximum advertising interval
1136 : * @param _peer Peer address, set to NULL for undirected advertising or
1137 : * address of peer for directed advertising.
1138 : */
1139 1 : #define BT_LE_ADV_PARAM_INIT(_options, _int_min, _int_max, _peer) \
1140 : { \
1141 : .id = BT_ID_DEFAULT, \
1142 : .sid = 0, \
1143 : .secondary_max_skip = 0, \
1144 : .options = (_options), \
1145 : .interval_min = (_int_min), \
1146 : .interval_max = (_int_max), \
1147 : .peer = (_peer), \
1148 : }
1149 :
1150 : /**
1151 : * @brief Helper to declare advertising parameters inline
1152 : *
1153 : * @param _options Advertising Options
1154 : * @param _int_min Minimum advertising interval
1155 : * @param _int_max Maximum advertising interval
1156 : * @param _peer Peer address, set to NULL for undirected advertising or
1157 : * address of peer for directed advertising.
1158 : */
1159 1 : #define BT_LE_ADV_PARAM(_options, _int_min, _int_max, _peer) \
1160 : ((const struct bt_le_adv_param[]) { \
1161 : BT_LE_ADV_PARAM_INIT(_options, _int_min, _int_max, _peer) \
1162 : })
1163 :
1164 0 : #define BT_LE_ADV_CONN_DIR(_peer) BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONN, 0, 0, _peer)
1165 :
1166 : /**
1167 : * @deprecated This is a convenience macro for @ref
1168 : * BT_LE_ADV_OPT_CONNECTABLE, which is deprecated. Please use
1169 : * @ref BT_LE_ADV_CONN_FAST_1 or @ref BT_LE_ADV_CONN_FAST_2
1170 : * instead.
1171 : */
1172 1 : #define BT_LE_ADV_CONN \
1173 : BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONNECTABLE, BT_GAP_ADV_FAST_INT_MIN_2, \
1174 : BT_GAP_ADV_FAST_INT_MAX_2, NULL) \
1175 : __DEPRECATED_MACRO
1176 :
1177 : /**
1178 : * @brief GAP recommended connectable advertising parameters user-initiated
1179 : *
1180 : * @details This define sets the recommended default for when an application is likely waiting for
1181 : * the device to be connected or discovered.
1182 : *
1183 : * GAP recommends advertisers use the advertising parameters set by @ref BT_LE_ADV_CONN_FAST_1 for
1184 : * user-initiated advertisements. This might mean any time a user interacts with a device, a press
1185 : * on a dedicated Bluetooth wakeup button, or anything in-between. Interpretation is left to the
1186 : * application developer.
1187 : *
1188 : * Following modes are considered in these parameter settings:
1189 : * - Undirected Connectable Mode
1190 : * - Limited Discoverable Mode and sending connectable undirected advertising events
1191 : * - General Discoverable Mode and sending connectable undirected advertising events
1192 : * - Directed Connectable Mode and sending low duty cycle directed advertising events
1193 : *
1194 : * @note These parameters are merely a recommendation. For example the application might use a
1195 : * longer interval to conserve battery, which would be at the cost of responsiveness and it should
1196 : * be considered to enter a lower power state with longer intervals only after a timeout.
1197 : *
1198 : * @note This is the recommended setting for limited discoverable mode.
1199 : *
1200 : * See Bluetooth Core Specification:
1201 : * - 6.0 Vol 3, Part C, Appendix A "Timers and Constants", T_GAP(adv_fast_interval1)
1202 : * - 6.0 Vol 3, Part C, Section 9.3.11 "Connection Establishment Timing parameters"
1203 : */
1204 :
1205 1 : #define BT_LE_ADV_CONN_FAST_1 \
1206 : BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONN, BT_GAP_ADV_FAST_INT_MIN_1, BT_GAP_ADV_FAST_INT_MAX_1, \
1207 : NULL)
1208 :
1209 : /**
1210 : * @brief GAP recommended connectable advertising parameters non-connectable advertising events
1211 : *
1212 : * @details This define sets the recommended default for user-initiated advertisements or sending
1213 : * non-connectable advertising events.
1214 : *
1215 : * Following modes are considered in these parameter settings:
1216 : * - Non-Discoverable Mode
1217 : * - Non-Connectable Mode
1218 : * - Limited Discoverable Mode
1219 : * - General Discoverable Mode
1220 : *
1221 : * The advertising interval corresponds to what was offered as @ref BT_LE_ADV_CONN in Zephyr 3.6 and
1222 : * earlier, but unlike @ref BT_LE_ADV_CONN, the host does not automatically resume the advertiser
1223 : * after it results in a connection.
1224 : *
1225 : * See Bluetooth Core Specification:
1226 : * - 6.0 Vol 3, Part C, Appendix A "Timers and Constants", T_GAP(adv_fast_interval2)
1227 : * - 6.0 Vol 3, Part C, Section 9.3.11 "Connection Establishment Timing parameters"
1228 : */
1229 1 : #define BT_LE_ADV_CONN_FAST_2 \
1230 : BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONN, BT_GAP_ADV_FAST_INT_MIN_2, BT_GAP_ADV_FAST_INT_MAX_2, \
1231 : NULL)
1232 :
1233 0 : #define BT_LE_ADV_CONN_ONE_TIME BT_LE_ADV_CONN_FAST_2 __DEPRECATED_MACRO
1234 :
1235 0 : #define BT_LE_ADV_CONN_DIR_LOW_DUTY(_peer) \
1236 : BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONN | BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY, \
1237 : BT_GAP_ADV_FAST_INT_MIN_2, BT_GAP_ADV_FAST_INT_MAX_2, _peer)
1238 :
1239 : /** Non-connectable advertising with private address */
1240 1 : #define BT_LE_ADV_NCONN BT_LE_ADV_PARAM(0, BT_GAP_ADV_FAST_INT_MIN_2, \
1241 : BT_GAP_ADV_FAST_INT_MAX_2, NULL)
1242 :
1243 : /** Non-connectable advertising with @ref BT_LE_ADV_OPT_USE_IDENTITY */
1244 1 : #define BT_LE_ADV_NCONN_IDENTITY BT_LE_ADV_PARAM(BT_LE_ADV_OPT_USE_IDENTITY, \
1245 : BT_GAP_ADV_FAST_INT_MIN_2, \
1246 : BT_GAP_ADV_FAST_INT_MAX_2, \
1247 : NULL)
1248 :
1249 : /** Connectable extended advertising */
1250 1 : #define BT_LE_EXT_ADV_CONN \
1251 : BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | BT_LE_ADV_OPT_CONN, BT_GAP_ADV_FAST_INT_MIN_2, \
1252 : BT_GAP_ADV_FAST_INT_MAX_2, NULL)
1253 :
1254 : /** Scannable extended advertising */
1255 1 : #define BT_LE_EXT_ADV_SCAN BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | \
1256 : BT_LE_ADV_OPT_SCANNABLE, \
1257 : BT_GAP_ADV_FAST_INT_MIN_2, \
1258 : BT_GAP_ADV_FAST_INT_MAX_2, \
1259 : NULL)
1260 :
1261 : /** Non-connectable extended advertising with private address */
1262 1 : #define BT_LE_EXT_ADV_NCONN BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV, \
1263 : BT_GAP_ADV_FAST_INT_MIN_2, \
1264 : BT_GAP_ADV_FAST_INT_MAX_2, NULL)
1265 :
1266 : /** Non-connectable extended advertising with @ref BT_LE_ADV_OPT_USE_IDENTITY */
1267 1 : #define BT_LE_EXT_ADV_NCONN_IDENTITY \
1268 : BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | \
1269 : BT_LE_ADV_OPT_USE_IDENTITY, \
1270 : BT_GAP_ADV_FAST_INT_MIN_2, \
1271 : BT_GAP_ADV_FAST_INT_MAX_2, NULL)
1272 :
1273 : /** Non-connectable extended advertising on coded PHY with private address */
1274 1 : #define BT_LE_EXT_ADV_CODED_NCONN BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | \
1275 : BT_LE_ADV_OPT_CODED, \
1276 : BT_GAP_ADV_FAST_INT_MIN_2, \
1277 : BT_GAP_ADV_FAST_INT_MAX_2, \
1278 : NULL)
1279 :
1280 : /** Non-connectable extended advertising on coded PHY with
1281 : * @ref BT_LE_ADV_OPT_USE_IDENTITY
1282 : */
1283 1 : #define BT_LE_EXT_ADV_CODED_NCONN_IDENTITY \
1284 : BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | BT_LE_ADV_OPT_CODED | \
1285 : BT_LE_ADV_OPT_USE_IDENTITY, \
1286 : BT_GAP_ADV_FAST_INT_MIN_2, \
1287 : BT_GAP_ADV_FAST_INT_MAX_2, NULL)
1288 :
1289 : /**
1290 : * Helper to initialize extended advertising start parameters inline
1291 : *
1292 : * @param _timeout Advertiser timeout
1293 : * @param _n_evts Number of advertising events
1294 : */
1295 1 : #define BT_LE_EXT_ADV_START_PARAM_INIT(_timeout, _n_evts) \
1296 : { \
1297 : .timeout = (_timeout), \
1298 : .num_events = (_n_evts), \
1299 : }
1300 :
1301 : /**
1302 : * Helper to declare extended advertising start parameters inline
1303 : *
1304 : * @param _timeout Advertiser timeout
1305 : * @param _n_evts Number of advertising events
1306 : */
1307 1 : #define BT_LE_EXT_ADV_START_PARAM(_timeout, _n_evts) \
1308 : ((const struct bt_le_ext_adv_start_param[]) { \
1309 : BT_LE_EXT_ADV_START_PARAM_INIT((_timeout), (_n_evts)) \
1310 : })
1311 :
1312 0 : #define BT_LE_EXT_ADV_START_DEFAULT BT_LE_EXT_ADV_START_PARAM(0, 0)
1313 :
1314 : /**
1315 : * Helper to declare periodic advertising parameters inline
1316 : *
1317 : * @param _int_min Minimum periodic advertising interval, N * 0.625 milliseconds
1318 : * @param _int_max Maximum periodic advertising interval, N * 0.625 milliseconds
1319 : * @param _options Periodic advertising properties bitfield, see @ref bt_le_adv_opt
1320 : * field.
1321 : */
1322 1 : #define BT_LE_PER_ADV_PARAM_INIT(_int_min, _int_max, _options) \
1323 : { \
1324 : .interval_min = (_int_min), \
1325 : .interval_max = (_int_max), \
1326 : .options = (_options), \
1327 : }
1328 :
1329 : /**
1330 : * Helper to declare periodic advertising parameters inline
1331 : *
1332 : * @param _int_min Minimum periodic advertising interval, N * 0.625 milliseconds
1333 : * @param _int_max Maximum periodic advertising interval, N * 0.625 milliseconds
1334 : * @param _options Periodic advertising properties bitfield, see @ref bt_le_adv_opt
1335 : * field.
1336 : */
1337 1 : #define BT_LE_PER_ADV_PARAM(_int_min, _int_max, _options) \
1338 : ((struct bt_le_per_adv_param[]) { \
1339 : BT_LE_PER_ADV_PARAM_INIT(_int_min, _int_max, _options) \
1340 : })
1341 :
1342 0 : #define BT_LE_PER_ADV_DEFAULT BT_LE_PER_ADV_PARAM(BT_GAP_PER_ADV_SLOW_INT_MIN, \
1343 : BT_GAP_PER_ADV_SLOW_INT_MAX, \
1344 : BT_LE_PER_ADV_OPT_NONE)
1345 :
1346 : /**
1347 : * @brief Start advertising
1348 : *
1349 : * Set advertisement data, scan response data, advertisement parameters
1350 : * and start advertising.
1351 : *
1352 : * When @p param.peer is set, the advertising will be directed to that peer device. In this case,
1353 : * the other function parameters are ignored.
1354 : *
1355 : * This function cannot be used with @ref BT_LE_ADV_OPT_EXT_ADV in the @p param.options.
1356 : * For extended advertising, the bt_le_ext_adv_* functions must be used.
1357 : *
1358 : * @param param Advertising parameters.
1359 : * @param ad Data to be used in advertisement packets.
1360 : * @param ad_len Number of elements in ad
1361 : * @param sd Data to be used in scan response packets.
1362 : * @param sd_len Number of elements in sd
1363 : *
1364 : * @return Zero on success or (negative) error code otherwise.
1365 : * @return -ENOMEM No free connection objects available for connectable
1366 : * advertiser.
1367 : * @return -ECONNREFUSED When connectable advertising is requested and there
1368 : * is already maximum number of connections established
1369 : * in the controller.
1370 : * This error code is only guaranteed when using Zephyr
1371 : * controller, for other controllers code returned in
1372 : * this case may be -EIO.
1373 : */
1374 1 : int bt_le_adv_start(const struct bt_le_adv_param *param,
1375 : const struct bt_data *ad, size_t ad_len,
1376 : const struct bt_data *sd, size_t sd_len);
1377 :
1378 : /**
1379 : * @brief Update advertising
1380 : *
1381 : * Update advertisement and scan response data.
1382 : *
1383 : * @param ad Data to be used in advertisement packets.
1384 : * @param ad_len Number of elements in ad
1385 : * @param sd Data to be used in scan response packets.
1386 : * @param sd_len Number of elements in sd
1387 : *
1388 : * @return Zero on success or (negative) error code otherwise.
1389 : */
1390 1 : int bt_le_adv_update_data(const struct bt_data *ad, size_t ad_len,
1391 : const struct bt_data *sd, size_t sd_len);
1392 :
1393 : /**
1394 : * @brief Stop advertising
1395 : *
1396 : * Stops ongoing advertising.
1397 : *
1398 : * @return Zero on success or (negative) error code otherwise.
1399 : */
1400 1 : int bt_le_adv_stop(void);
1401 :
1402 : /**
1403 : * @brief Create advertising set.
1404 : *
1405 : * Create an instance of an independent advertising set with its own parameters and data.
1406 : * The advertising set remains valid until deleted with @ref bt_le_ext_adv_delete.
1407 : * Advertising parameters can be updated with @ref bt_le_ext_adv_update_param, and advertising
1408 : * can be started with @ref bt_le_ext_adv_start.
1409 : *
1410 : * @note The number of supported extended advertising sets can be controlled by
1411 : * @kconfig{CONFIG_BT_EXT_ADV_MAX_ADV_SET}.
1412 : *
1413 : * @param[in] param Advertising parameters.
1414 : * @param[in] cb Callback struct to notify about advertiser activity. Can be
1415 : * NULL. Must point to valid memory during the lifetime of the
1416 : * advertising set.
1417 : * @param[out] adv Valid advertising set object on success.
1418 : *
1419 : * @return Zero on success or (negative) error code otherwise.
1420 : */
1421 1 : int bt_le_ext_adv_create(const struct bt_le_adv_param *param,
1422 : const struct bt_le_ext_adv_cb *cb,
1423 : struct bt_le_ext_adv **adv);
1424 :
1425 : /**
1426 : * @brief Parameters for starting an extended advertising session.
1427 : *
1428 : * @details This struct provides the parameters to control the behavior of an extended advertising
1429 : * session, including the timeout and the number of advertising events to send. The timeout is
1430 : * specified in units of 10 ms, and the number of events determines how many times the advertising
1431 : * will be sent before stopping. If either the timeout or number of events is reached, the
1432 : * advertising session will be stopped, and the application will be notified via the advertiser sent
1433 : * callback. If both parameters are provided, the advertising session will stop when either limit is
1434 : * reached.
1435 : *
1436 : * @note Used in @ref bt_le_ext_adv_start function.
1437 : */
1438 1 : struct bt_le_ext_adv_start_param {
1439 : /**
1440 : * @brief Maximum advertising set duration (N * 10 ms)
1441 : *
1442 : * The advertising set can be automatically disabled after a
1443 : * certain amount of time has passed since it first appeared on
1444 : * air.
1445 : *
1446 : * Set to zero for no limit. Set in units of 10 ms.
1447 : *
1448 : * When the advertising set is automatically disabled because of
1449 : * this limit, @ref bt_le_ext_adv_cb.sent will be called.
1450 : *
1451 : * When using high duty cycle directed connectable advertising
1452 : * then this parameters must be set to a non-zero value less
1453 : * than or equal to the maximum of
1454 : * @ref BT_GAP_ADV_HIGH_DUTY_CYCLE_MAX_TIMEOUT.
1455 : *
1456 : * If privacy @kconfig{CONFIG_BT_PRIVACY} is enabled then the
1457 : * timeout must be less than @kconfig{CONFIG_BT_RPA_TIMEOUT}.
1458 : *
1459 : * For background information, see parameter "Duration" in
1460 : * Bluetooth Core Specification Version 6.0 Vol. 4 Part E,
1461 : * Section 7.8.56.
1462 : */
1463 1 : uint16_t timeout;
1464 :
1465 : /**
1466 : * @brief Maximum number of extended advertising events to be
1467 : * sent
1468 : *
1469 : * The advertiser can be automatically disabled once the whole
1470 : * advertisement (i.e. extended advertising event) has been sent
1471 : * a certain number of times. The number of advertising PDUs
1472 : * sent may be higher and is not relevant.
1473 : *
1474 : * Set to zero for no limit.
1475 : *
1476 : * When the advertising set is automatically disabled because of
1477 : * this limit, @ref bt_le_ext_adv_cb.sent will be called.
1478 : *
1479 : * For background information, see parameter
1480 : * "Max_Extended_Advertising_Events" in Bluetooth Core
1481 : * Specification Version 6.0 Vol. 4 Part E, Section 7.8.56.
1482 : */
1483 1 : uint8_t num_events;
1484 : };
1485 :
1486 : /**
1487 : * @brief Start advertising with the given advertising set
1488 : *
1489 : * If the advertiser is limited by either the @p param.timeout or @p param.num_events,
1490 : * the application will be notified by the @ref bt_le_ext_adv_cb.sent callback once
1491 : * the limit is reached.
1492 : * If the advertiser is limited by both the timeout and the number of
1493 : * advertising events, then the limit that is reached first will stop the
1494 : * advertiser.
1495 : *
1496 : * @note The advertising set @p adv can be created with @ref bt_le_ext_adv_create.
1497 : *
1498 : * @param adv Advertising set object.
1499 : * @param param Advertise start parameters.
1500 : */
1501 1 : int bt_le_ext_adv_start(struct bt_le_ext_adv *adv,
1502 : const struct bt_le_ext_adv_start_param *param);
1503 :
1504 : /**
1505 : * @brief Stop advertising with the given advertising set
1506 : *
1507 : * Stop advertising with a specific advertising set. When using this function
1508 : * the advertising sent callback will not be called.
1509 : *
1510 : * @param adv Advertising set object.
1511 : *
1512 : * @return Zero on success or (negative) error code otherwise.
1513 : */
1514 1 : int bt_le_ext_adv_stop(struct bt_le_ext_adv *adv);
1515 :
1516 : /**
1517 : * @brief Set an advertising set's advertising or scan response data.
1518 : *
1519 : * Set advertisement data or scan response data. If the advertising set is
1520 : * currently advertising then the advertising data will be updated in
1521 : * subsequent advertising events.
1522 : *
1523 : * When both @ref BT_LE_ADV_OPT_EXT_ADV and @ref BT_LE_ADV_OPT_SCANNABLE are
1524 : * enabled then advertising data is ignored and only scan response data is used.
1525 : * When @ref BT_LE_ADV_OPT_SCANNABLE is not enabled then scan response data is
1526 : * ignored and only advertising data is used.
1527 : *
1528 : * If the advertising set has been configured to send advertising data on the
1529 : * primary advertising channels then the maximum data length is
1530 : * @ref BT_GAP_ADV_MAX_ADV_DATA_LEN octets.
1531 : * If the advertising set has been configured for extended advertising,
1532 : * then the maximum data length is defined by the controller with the maximum
1533 : * possible of @ref BT_GAP_ADV_MAX_EXT_ADV_DATA_LEN bytes.
1534 : *
1535 : * @note Extended advertising was introduced in Bluetooth 5.0, and legacy scanners will not support
1536 : * reception of any extended advertising packets.
1537 : *
1538 : * @note When updating the advertising data while advertising the advertising
1539 : * data and scan response data length must be smaller or equal to what
1540 : * can be fit in a single advertising packet. Otherwise the
1541 : * advertiser must be stopped.
1542 : *
1543 : * @param adv Advertising set object.
1544 : * @param ad Data to be used in advertisement packets.
1545 : * @param ad_len Number of elements in ad
1546 : * @param sd Data to be used in scan response packets.
1547 : * @param sd_len Number of elements in sd
1548 : *
1549 : * @return Zero on success or (negative) error code otherwise.
1550 : */
1551 1 : int bt_le_ext_adv_set_data(struct bt_le_ext_adv *adv,
1552 : const struct bt_data *ad, size_t ad_len,
1553 : const struct bt_data *sd, size_t sd_len);
1554 :
1555 : /**
1556 : * @brief Update advertising parameters.
1557 : *
1558 : * Update the advertising parameters. The function will return an error if the
1559 : * advertiser set is currently advertising. Stop the advertising set before
1560 : * calling this function.
1561 : *
1562 : * @param adv Advertising set object.
1563 : * @param param Advertising parameters.
1564 : *
1565 : * @return Zero on success or (negative) error code otherwise.
1566 : */
1567 1 : int bt_le_ext_adv_update_param(struct bt_le_ext_adv *adv,
1568 : const struct bt_le_adv_param *param);
1569 :
1570 : /**
1571 : * @brief Delete advertising set.
1572 : *
1573 : * Delete advertising set. This will free up the advertising set and make it
1574 : * possible to create a new advertising set if the limit @kconfig{CONFIG_BT_EXT_ADV_MAX_ADV_SET}
1575 : * was reached.
1576 : *
1577 : * @return Zero on success or (negative) error code otherwise.
1578 : */
1579 1 : int bt_le_ext_adv_delete(struct bt_le_ext_adv *adv);
1580 :
1581 : /**
1582 : * @brief Get array index of an advertising set.
1583 : *
1584 : * This function is used to map bt_adv to index of an array of
1585 : * advertising sets. The array has @kconfig{CONFIG_BT_EXT_ADV_MAX_ADV_SET} elements.
1586 : *
1587 : * @param adv Advertising set.
1588 : *
1589 : * @return Index of the advertising set object.
1590 : * The range of the returned value is 0..@kconfig{CONFIG_BT_EXT_ADV_MAX_ADV_SET}-1
1591 : */
1592 1 : uint8_t bt_le_ext_adv_get_index(struct bt_le_ext_adv *adv);
1593 :
1594 : /** Advertising states. */
1595 1 : enum bt_le_ext_adv_state {
1596 : /** The advertising set has been created but not enabled. */
1597 : BT_LE_EXT_ADV_STATE_DISABLED,
1598 :
1599 : /** The advertising set is enabled. */
1600 : BT_LE_EXT_ADV_STATE_ENABLED,
1601 : };
1602 :
1603 : /** Periodic Advertising states. */
1604 1 : enum bt_le_per_adv_state {
1605 : /** Not configured for periodic advertising. */
1606 : BT_LE_PER_ADV_STATE_NONE,
1607 :
1608 : /** The advertising set has been configured for periodic advertising, but is not enabled. */
1609 : BT_LE_PER_ADV_STATE_DISABLED,
1610 :
1611 : /** Periodic advertising is enabled. */
1612 : BT_LE_PER_ADV_STATE_ENABLED,
1613 : };
1614 :
1615 : /** @brief Advertising set info structure. */
1616 1 : struct bt_le_ext_adv_info {
1617 : /** Local identity handle. */
1618 1 : uint8_t id;
1619 :
1620 : /** Currently selected Transmit Power (dBM). */
1621 1 : int8_t tx_power;
1622 :
1623 : /** Advertising Set ID */
1624 1 : uint8_t sid;
1625 :
1626 : /** Current local advertising address used. */
1627 1 : const bt_addr_le_t *addr;
1628 :
1629 : /** Extended advertising state. */
1630 1 : enum bt_le_ext_adv_state ext_adv_state;
1631 :
1632 : /** Periodic advertising state. */
1633 1 : enum bt_le_per_adv_state per_adv_state;
1634 : };
1635 :
1636 : /**
1637 : * @brief Get advertising set info
1638 : *
1639 : * @param adv Advertising set object
1640 : * @param info Advertising set info object. The values in this object are only valid on success.
1641 : *
1642 : * @retval 0 Success.
1643 : * @retval -EINVAL @p adv is not valid advertising set or @p info is NULL.
1644 : */
1645 1 : int bt_le_ext_adv_get_info(const struct bt_le_ext_adv *adv,
1646 : struct bt_le_ext_adv_info *info);
1647 :
1648 : /**
1649 : * @typedef bt_le_scan_cb_t
1650 : * @brief Callback type for reporting LE scan results.
1651 : *
1652 : * A function of this type is given to the @ref bt_le_scan_start function
1653 : * and will be called for any discovered LE device.
1654 : *
1655 : * @param addr Advertiser LE address and type.
1656 : * @param rssi Strength of advertiser signal.
1657 : * @param adv_type Type of advertising response from advertiser.
1658 : * Uses the @ref bt_gap_adv_type values.
1659 : * @param buf Buffer containing advertiser data.
1660 : */
1661 1 : typedef void bt_le_scan_cb_t(const bt_addr_le_t *addr, int8_t rssi,
1662 : uint8_t adv_type, struct net_buf_simple *buf);
1663 :
1664 : /**
1665 : * @brief Set or update the periodic advertising parameters.
1666 : *
1667 : * The periodic advertising parameters can only be set or updated on an
1668 : * extended advertisement set which is neither scannable, connectable nor
1669 : * anonymous (meaning, the advertising options @ref BT_LE_ADV_OPT_SCANNABLE,
1670 : * @ref BT_LE_ADV_OPT_CONNECTABLE and @ref BT_LE_ADV_OPT_ANONYMOUS cannot be set for @p adv).
1671 : *
1672 : * @param adv Advertising set object.
1673 : * @param param Advertising parameters.
1674 : *
1675 : * @return Zero on success or (negative) error code otherwise.
1676 : */
1677 1 : int bt_le_per_adv_set_param(struct bt_le_ext_adv *adv,
1678 : const struct bt_le_per_adv_param *param);
1679 :
1680 : /**
1681 : * @brief Set or update the periodic advertising data.
1682 : *
1683 : * The periodic advertisement data can only be set or updated on an
1684 : * extended advertisement set which is neither scannable, connectable nor
1685 : * anonymous (meaning, the advertising options @ref BT_LE_ADV_OPT_SCANNABLE,
1686 : * @ref BT_LE_ADV_OPT_CONNECTABLE and @ref BT_LE_ADV_OPT_ANONYMOUS cannot be set for @p adv).
1687 : *
1688 : * @param adv Advertising set object.
1689 : * @param ad Advertising data.
1690 : * @param ad_len Advertising data length.
1691 : *
1692 : * @return Zero on success or (negative) error code otherwise.
1693 : */
1694 1 : int bt_le_per_adv_set_data(const struct bt_le_ext_adv *adv,
1695 : const struct bt_data *ad, size_t ad_len);
1696 :
1697 : /**
1698 : * @brief Parameters for setting data for a specific periodic advertising with response subevent.
1699 : *
1700 : * @details This struct provides the necessary information to set the data for a specific subevent
1701 : * in a Periodic Advertising with Response (PAwR) scenario. It specifies the subevent number, the
1702 : * range of response slots to listen to, and the actual data to send. This is used to respond to
1703 : * data request from an advertiser by sending back the data in the specified subevent.
1704 : *
1705 : * @note Used in @ref bt_le_per_adv_set_subevent_data function.
1706 : */
1707 1 : struct bt_le_per_adv_subevent_data_params {
1708 : /** The subevent to set data for */
1709 1 : uint8_t subevent;
1710 :
1711 : /** The first response slot to listen to */
1712 1 : uint8_t response_slot_start;
1713 :
1714 : /** The number of response slots to listen to */
1715 1 : uint8_t response_slot_count;
1716 :
1717 : /** The data to send */
1718 1 : const struct net_buf_simple *data;
1719 : };
1720 :
1721 : /**
1722 : * @brief Set the periodic advertising with response subevent data.
1723 : *
1724 : * Set the data for one or more subevents of a Periodic Advertising with
1725 : * Responses Advertiser in reply data request.
1726 : *
1727 : * @pre There are @p num_subevents elements in @p params.
1728 : * @pre The controller has requested data for the subevents in @p params.
1729 : *
1730 : * @param adv The extended advertiser the PAwR train belongs to.
1731 : * @param num_subevents The number of subevents to set data for.
1732 : * @param params Subevent parameters.
1733 : *
1734 : * @return Zero on success or (negative) error code otherwise.
1735 : */
1736 1 : int bt_le_per_adv_set_subevent_data(const struct bt_le_ext_adv *adv, uint8_t num_subevents,
1737 : const struct bt_le_per_adv_subevent_data_params *params);
1738 :
1739 : /**
1740 : * @brief Starts periodic advertising.
1741 : *
1742 : * Enabling the periodic advertising can be done independently of extended
1743 : * advertising, but both periodic advertising and extended advertising
1744 : * shall be enabled before any periodic advertising data is sent. The
1745 : * periodic advertising and extended advertising can be enabled in any order.
1746 : *
1747 : * Once periodic advertising has been enabled, it will continue advertising
1748 : * until @ref bt_le_per_adv_stop function has been called, or if the advertising set
1749 : * is deleted by @ref bt_le_ext_adv_delete function. Calling @ref bt_le_ext_adv_stop function
1750 : * will not stop the periodic advertising.
1751 : *
1752 : * @param adv Advertising set object.
1753 : *
1754 : * @return Zero on success or (negative) error code otherwise.
1755 : */
1756 1 : int bt_le_per_adv_start(struct bt_le_ext_adv *adv);
1757 :
1758 : /**
1759 : * @brief Stops periodic advertising.
1760 : *
1761 : * Disabling the periodic advertising can be done independently of extended
1762 : * advertising. Disabling periodic advertising will not disable extended
1763 : * advertising.
1764 : *
1765 : * @param adv Advertising set object.
1766 : *
1767 : * @return Zero on success or (negative) error code otherwise.
1768 : */
1769 1 : int bt_le_per_adv_stop(struct bt_le_ext_adv *adv);
1770 :
1771 : /**
1772 : * @brief Information about the successful synchronization with periodic advertising.
1773 : *
1774 : * @details This struct provides information about the periodic advertising sync once it has been
1775 : * successfully established. It includes the advertiser's address, SID, the advertising interval,
1776 : * PHY, and the synchronization state. It also contains details about the sync, such as service data
1777 : * and the peer device that transferred the sync.
1778 : * When using periodic advertising response (configured via @kconfig{CONFIG_BT_PER_ADV_SYNC_RSP}),
1779 : * additional details such as subevent information and response timings are provided.
1780 : *
1781 : * @note Used in @ref bt_le_per_adv_sync_cb structure.
1782 : */
1783 1 : struct bt_le_per_adv_sync_synced_info {
1784 : /** Advertiser LE address and type. */
1785 1 : const bt_addr_le_t *addr;
1786 :
1787 : /** Advertising Set Identifier, valid range @ref BT_GAP_SID_MIN to @ref BT_GAP_SID_MAX. */
1788 1 : uint8_t sid;
1789 :
1790 : /** Periodic advertising interval (N * 1.25 ms) */
1791 1 : uint16_t interval;
1792 :
1793 : /** Advertiser PHY (see @ref bt_gap_le_phy). */
1794 1 : uint8_t phy;
1795 :
1796 : /** True if receiving periodic advertisements, false otherwise. */
1797 1 : bool recv_enabled;
1798 :
1799 : /**
1800 : * @brief Service Data provided by the peer when sync is transferred
1801 : *
1802 : * Will always be 0 when the sync is locally created.
1803 : */
1804 1 : uint16_t service_data;
1805 :
1806 : /**
1807 : * @brief Peer that transferred the periodic advertising sync
1808 : *
1809 : * Will always be NULL when the sync is locally created.
1810 : *
1811 : */
1812 1 : struct bt_conn *conn;
1813 : #if defined(CONFIG_BT_PER_ADV_SYNC_RSP)
1814 : /** Number of subevents */
1815 : uint8_t num_subevents;
1816 :
1817 : /** Subevent interval (N * 1.25 ms) */
1818 : uint8_t subevent_interval;
1819 :
1820 : /** Response slot delay (N * 1.25 ms) */
1821 : uint8_t response_slot_delay;
1822 :
1823 : /** Response slot spacing (N * 1.25 ms) */
1824 : uint8_t response_slot_spacing;
1825 :
1826 : #endif /* CONFIG_BT_PER_ADV_SYNC_RSP */
1827 : };
1828 :
1829 : /**
1830 : * @brief Information about the termination of a periodic advertising sync.
1831 : *
1832 : * @details This struct provides information about the termination of a periodic advertising sync.
1833 : * It includes the advertiser’s address and SID, along with the reason for the sync termination.
1834 : * This information is provided in the callback when the sync is terminated, either due to a
1835 : * local or remote request, or due to missing data (e.g., out of range or lost sync).
1836 : *
1837 : * @note Used in @ref bt_le_per_adv_sync_cb structure.
1838 : */
1839 1 : struct bt_le_per_adv_sync_term_info {
1840 : /** Advertiser LE address and type. */
1841 1 : const bt_addr_le_t *addr;
1842 :
1843 : /** Advertising Set Identifier, valid range @ref BT_GAP_SID_MIN to @ref BT_GAP_SID_MAX. */
1844 1 : uint8_t sid;
1845 :
1846 : /** Cause of periodic advertising termination (see the BT_HCI_ERR_* values). */
1847 1 : uint8_t reason;
1848 : };
1849 :
1850 : /**
1851 : * @brief Information about a received periodic advertising report.
1852 : *
1853 : * @details This struct holds information about a periodic advertising event that has been received.
1854 : * It contains details such as the advertiser’s address, SID, transmit power, RSSI, CTE type, and
1855 : * additional information depending on the configuration (e.g., event counter and subevent in case
1856 : * of a subevent indication). This information is provided in the callback when periodic advertising
1857 : * data is received.
1858 : *
1859 : * @note Used in @ref bt_le_per_adv_sync_cb structure.
1860 : */
1861 1 : struct bt_le_per_adv_sync_recv_info {
1862 : /** Advertiser LE address and type. */
1863 1 : const bt_addr_le_t *addr;
1864 :
1865 : /** Advertising Set Identifier, valid range @ref BT_GAP_SID_MIN to @ref BT_GAP_SID_MAX. */
1866 1 : uint8_t sid;
1867 :
1868 : /** The TX power of the advertisement. */
1869 1 : int8_t tx_power;
1870 :
1871 : /** The RSSI of the advertisement excluding any CTE. */
1872 1 : int8_t rssi;
1873 :
1874 : /** The Constant Tone Extension (CTE) of the advertisement (@ref bt_df_cte_type) */
1875 1 : uint8_t cte_type;
1876 : #if defined(CONFIG_BT_PER_ADV_SYNC_RSP)
1877 : /** The value of the event counter where the subevent indication was received. */
1878 : uint16_t periodic_event_counter;
1879 :
1880 : /** The subevent where the subevent indication was received. */
1881 : uint8_t subevent;
1882 : #endif /* CONFIG_BT_PER_ADV_SYNC_RSP */
1883 : };
1884 :
1885 : /**
1886 : * @brief Information about the state of periodic advertising sync.
1887 : *
1888 : * @details This struct provides information about the current state of a periodic advertising sync.
1889 : * It indicates whether periodic advertising reception is enabled or not. It is typically used to
1890 : * report the state change via callbacks in the @ref bt_le_per_adv_sync_cb structure.
1891 : */
1892 1 : struct bt_le_per_adv_sync_state_info {
1893 : /** True if receiving periodic advertisements, false otherwise. */
1894 1 : bool recv_enabled;
1895 : };
1896 :
1897 : /**
1898 : * @brief Callback struct for periodic advertising sync events.
1899 : *
1900 : * @details This struct defines the callback functions that are invoked for various periodic
1901 : * advertising sync events. These include when the sync is successfully established, terminated,
1902 : * when data is received, state changes, BIG info reports, and IQ samples from the periodic
1903 : * advertising.
1904 : *
1905 : * @note Used in @ref bt_le_per_adv_sync_cb_register function.
1906 : */
1907 :
1908 1 : struct bt_le_per_adv_sync_cb {
1909 : /**
1910 : * @brief The periodic advertising has been successfully synced.
1911 : *
1912 : * This callback notifies the application that the periodic advertising
1913 : * set has been successfully synced, and will now start to
1914 : * receive periodic advertising reports.
1915 : *
1916 : * @param sync The periodic advertising sync object.
1917 : * @param info Information about the sync event.
1918 : */
1919 1 : void (*synced)(struct bt_le_per_adv_sync *sync,
1920 : struct bt_le_per_adv_sync_synced_info *info);
1921 :
1922 : /**
1923 : * @brief The periodic advertising sync has been terminated.
1924 : *
1925 : * This callback notifies the application that the periodic advertising
1926 : * sync has been terminated, either by local request, remote request or
1927 : * because due to missing data, e.g. by being out of range or sync.
1928 : *
1929 : * @param sync The periodic advertising sync object.
1930 : * @param info Information about the termination event.
1931 : */
1932 1 : void (*term)(struct bt_le_per_adv_sync *sync,
1933 : const struct bt_le_per_adv_sync_term_info *info);
1934 :
1935 : /**
1936 : * @brief Periodic advertising data received.
1937 : *
1938 : * This callback notifies the application of an periodic advertising
1939 : * report.
1940 : *
1941 : * @param sync The advertising set object.
1942 : * @param info Information about the periodic advertising event.
1943 : * @param buf Buffer containing the periodic advertising data.
1944 : * NULL if the controller failed to receive a subevent
1945 : * indication. Only happens if
1946 : * @kconfig{CONFIG_BT_PER_ADV_SYNC_RSP} is enabled.
1947 : */
1948 1 : void (*recv)(struct bt_le_per_adv_sync *sync,
1949 : const struct bt_le_per_adv_sync_recv_info *info,
1950 : struct net_buf_simple *buf);
1951 :
1952 : /**
1953 : * @brief The periodic advertising sync state has changed.
1954 : *
1955 : * This callback notifies the application about changes to the sync
1956 : * state. Initialize sync and termination is handled by their individual
1957 : * callbacks, and won't be notified here.
1958 : *
1959 : * @param sync The periodic advertising sync object.
1960 : * @param info Information about the state change.
1961 : */
1962 1 : void (*state_changed)(struct bt_le_per_adv_sync *sync,
1963 : const struct bt_le_per_adv_sync_state_info *info);
1964 :
1965 : /**
1966 : * @brief BIGInfo advertising report received.
1967 : *
1968 : * This callback notifies the application of a BIGInfo advertising report.
1969 : * This is received if the advertiser is broadcasting isochronous streams in a BIG.
1970 : * See iso.h for more information.
1971 : *
1972 : * @param sync The advertising set object.
1973 : * @param biginfo The BIGInfo report.
1974 : */
1975 1 : void (*biginfo)(struct bt_le_per_adv_sync *sync, const struct bt_iso_biginfo *biginfo);
1976 :
1977 : /**
1978 : * @brief Callback for IQ samples report collected when sampling
1979 : * CTE received with periodic advertising PDU.
1980 : *
1981 : * @param sync The periodic advertising sync object.
1982 : * @param info Information about the sync event.
1983 : */
1984 1 : void (*cte_report_cb)(struct bt_le_per_adv_sync *sync,
1985 : struct bt_df_per_adv_sync_iq_samples_report const *info);
1986 :
1987 0 : sys_snode_t node;
1988 : };
1989 :
1990 : /** Periodic advertising sync options */
1991 1 : enum bt_le_per_adv_sync_opt {
1992 : /** Convenience value when no options are specified. */
1993 : BT_LE_PER_ADV_SYNC_OPT_NONE = 0,
1994 :
1995 : /**
1996 : * @brief Use the periodic advertising list to sync with advertiser
1997 : *
1998 : * When this option is set, the address and SID of the parameters
1999 : * are ignored.
2000 : */
2001 : BT_LE_PER_ADV_SYNC_OPT_USE_PER_ADV_LIST = BIT(0),
2002 :
2003 : /**
2004 : * @brief Disables periodic advertising reports
2005 : *
2006 : * No advertisement reports will be handled until enabled.
2007 : */
2008 : BT_LE_PER_ADV_SYNC_OPT_REPORTING_INITIALLY_DISABLED = BIT(1),
2009 :
2010 : /** Filter duplicate Periodic Advertising reports */
2011 : BT_LE_PER_ADV_SYNC_OPT_FILTER_DUPLICATE = BIT(2),
2012 :
2013 : /** Sync with Angle of Arrival (AoA) constant tone extension */
2014 : BT_LE_PER_ADV_SYNC_OPT_DONT_SYNC_AOA = BIT(3),
2015 :
2016 : /** Sync with Angle of Departure (AoD) 1 us constant tone extension */
2017 : BT_LE_PER_ADV_SYNC_OPT_DONT_SYNC_AOD_1US = BIT(4),
2018 :
2019 : /** Sync with Angle of Departure (AoD) 2 us constant tone extension */
2020 : BT_LE_PER_ADV_SYNC_OPT_DONT_SYNC_AOD_2US = BIT(5),
2021 :
2022 : /** Do not sync to packets without a constant tone extension */
2023 : BT_LE_PER_ADV_SYNC_OPT_SYNC_ONLY_CONST_TONE_EXT = BIT(6),
2024 : };
2025 :
2026 : /**
2027 : * @brief Parameters for creating a periodic advertising sync object.
2028 : *
2029 : * @details This struct contains the parameters required to create a periodic advertising sync
2030 : * object, which allows the system to synchronize with periodic advertising reports from an
2031 : * advertiser. It includes the advertiser's address, SID, sync options, event skip, and
2032 : * synchronization timeout.
2033 : *
2034 : * @note bt_le_per_adv_sync_param is used as a parameter in the @ref bt_le_per_adv_sync_create
2035 : * function to configure synchronization behavior.
2036 : */
2037 1 : struct bt_le_per_adv_sync_param {
2038 : /**
2039 : * @brief Periodic Advertiser Address
2040 : *
2041 : * Only valid if not using the periodic advertising list
2042 : * (@ref BT_LE_PER_ADV_SYNC_OPT_USE_PER_ADV_LIST)
2043 : */
2044 1 : bt_addr_le_t addr;
2045 :
2046 : /**
2047 : * @brief Advertising Set Identifier. Valid range @ref BT_GAP_SID_MIN to
2048 : * @ref BT_GAP_SID_MAX.
2049 : *
2050 : * Only valid if not using the periodic advertising list
2051 : * (@ref BT_LE_PER_ADV_SYNC_OPT_USE_PER_ADV_LIST)
2052 : */
2053 1 : uint8_t sid;
2054 :
2055 : /** Bit-field of periodic advertising sync options, see the @ref bt_le_adv_opt field. */
2056 1 : uint32_t options;
2057 :
2058 : /**
2059 : * @brief Maximum event skip
2060 : *
2061 : * Maximum number of periodic advertising events that can be
2062 : * skipped after a successful receive.
2063 : * Range: 0x0000 to 0x01F3
2064 : */
2065 1 : uint16_t skip;
2066 :
2067 : /**
2068 : * @brief Synchronization timeout (N * 10 ms)
2069 : *
2070 : * Synchronization timeout for the periodic advertising sync.
2071 : * Range 0x000A to 0x4000 (100 ms to 163840 ms)
2072 : */
2073 1 : uint16_t timeout;
2074 : };
2075 :
2076 : /**
2077 : * @brief Get array index of an periodic advertising sync object.
2078 : *
2079 : * This function is to get the index of an array of periodic advertising sync
2080 : * objects. The array has @kconfig{CONFIG_BT_PER_ADV_SYNC_MAX} elements.
2081 : *
2082 : * @param per_adv_sync The periodic advertising sync object.
2083 : *
2084 : * @return Index of the periodic advertising sync object.
2085 : * The range of the returned value is 0..@kconfig{CONFIG_BT_PER_ADV_SYNC_MAX}-1
2086 : */
2087 1 : uint8_t bt_le_per_adv_sync_get_index(struct bt_le_per_adv_sync *per_adv_sync);
2088 :
2089 : /**
2090 : * @brief Get a periodic advertising sync object from the array index.
2091 : *
2092 : * This function is to get the periodic advertising sync object from
2093 : * the array index.
2094 : * The array has @kconfig{CONFIG_BT_PER_ADV_SYNC_MAX} elements.
2095 : *
2096 : * @param index The index of the periodic advertising sync object.
2097 : * The range of the index value is 0..@kconfig{CONFIG_BT_PER_ADV_SYNC_MAX}-1
2098 : *
2099 : * @return The periodic advertising sync object of the array index or NULL if invalid index.
2100 : */
2101 1 : struct bt_le_per_adv_sync *bt_le_per_adv_sync_lookup_index(uint8_t index);
2102 :
2103 : /** @brief Periodic advertising set info structure. */
2104 1 : struct bt_le_per_adv_sync_info {
2105 : /** Periodic Advertiser Address */
2106 1 : bt_addr_le_t addr;
2107 :
2108 : /** Advertising Set Identifier, valid range @ref BT_GAP_SID_MIN to @ref BT_GAP_SID_MAX. */
2109 1 : uint8_t sid;
2110 :
2111 : /** Periodic advertising interval (N * 1.25 ms) */
2112 1 : uint16_t interval;
2113 :
2114 : /** Advertiser PHY (see @ref bt_gap_le_phy). */
2115 1 : uint8_t phy;
2116 : };
2117 :
2118 : /**
2119 : * @brief Get periodic adv sync information.
2120 : *
2121 : * @param per_adv_sync Periodic advertising sync object.
2122 : * @param info Periodic advertising sync info object
2123 : *
2124 : * @return Zero on success or (negative) error code on failure.
2125 : */
2126 1 : int bt_le_per_adv_sync_get_info(struct bt_le_per_adv_sync *per_adv_sync,
2127 : struct bt_le_per_adv_sync_info *info);
2128 :
2129 : /**
2130 : * @brief Look up an existing periodic advertising sync object by advertiser address.
2131 : *
2132 : * @param adv_addr Advertiser address.
2133 : * @param sid The periodic advertising set ID.
2134 : *
2135 : * @return Periodic advertising sync object or NULL if not found.
2136 : */
2137 1 : struct bt_le_per_adv_sync *bt_le_per_adv_sync_lookup_addr(const bt_addr_le_t *adv_addr,
2138 : uint8_t sid);
2139 :
2140 : /**
2141 : * @brief Create a periodic advertising sync object.
2142 : *
2143 : * Create a periodic advertising sync object that can try to synchronize
2144 : * to periodic advertising reports from an advertiser. Scan shall either be
2145 : * disabled or extended scan shall be enabled.
2146 : *
2147 : * This function does not timeout, and will continue to look for an advertiser until it either
2148 : * finds it or @ref bt_le_per_adv_sync_delete is called. It is thus suggested to implement a timeout
2149 : * when using this, if it is expected to find the advertiser within a reasonable timeframe.
2150 : *
2151 : * @param[in] param Periodic advertising sync parameters.
2152 : * @param[out] out_sync Periodic advertising sync object on.
2153 : *
2154 : * @return Zero on success or (negative) error code otherwise.
2155 : */
2156 1 : int bt_le_per_adv_sync_create(const struct bt_le_per_adv_sync_param *param,
2157 : struct bt_le_per_adv_sync **out_sync);
2158 :
2159 : /**
2160 : * @brief Delete periodic advertising sync.
2161 : *
2162 : * Delete the periodic advertising sync object. Can be called regardless of the
2163 : * state of the sync. If the syncing is currently syncing, the syncing is
2164 : * cancelled. If the sync has been established, it is terminated. The
2165 : * periodic advertising sync object will be invalidated afterwards.
2166 : *
2167 : * If the state of the sync object is syncing, then a new periodic advertising
2168 : * sync object cannot be created until the controller has finished canceling
2169 : * this object.
2170 : *
2171 : * @param per_adv_sync The periodic advertising sync object.
2172 : *
2173 : * @return Zero on success or (negative) error code otherwise.
2174 : */
2175 1 : int bt_le_per_adv_sync_delete(struct bt_le_per_adv_sync *per_adv_sync);
2176 :
2177 : /**
2178 : * @brief Register periodic advertising sync callbacks.
2179 : *
2180 : * Adds the callback structure to the list of callback structures for periodic
2181 : * advertising syncs.
2182 : *
2183 : * This callback will be called for all periodic advertising sync activity,
2184 : * such as synced, terminated and when data is received.
2185 : *
2186 : * @param cb Callback struct. Must point to memory that remains valid.
2187 : *
2188 : * @retval 0 Success.
2189 : * @retval -EEXIST if @p cb was already registered.
2190 : */
2191 1 : int bt_le_per_adv_sync_cb_register(struct bt_le_per_adv_sync_cb *cb);
2192 :
2193 : /**
2194 : * @brief Enables receiving periodic advertising reports for a sync.
2195 : *
2196 : * If the sync is already receiving the reports, -EALREADY is returned.
2197 : *
2198 : * @param per_adv_sync The periodic advertising sync object.
2199 : *
2200 : * @return Zero on success or (negative) error code otherwise.
2201 : */
2202 1 : int bt_le_per_adv_sync_recv_enable(struct bt_le_per_adv_sync *per_adv_sync);
2203 :
2204 : /**
2205 : * @brief Disables receiving periodic advertising reports for a sync.
2206 : *
2207 : * If the sync report receiving is already disabled, -EALREADY is returned.
2208 : *
2209 : * @param per_adv_sync The periodic advertising sync object.
2210 : *
2211 : * @return Zero on success or (negative) error code otherwise.
2212 : */
2213 1 : int bt_le_per_adv_sync_recv_disable(struct bt_le_per_adv_sync *per_adv_sync);
2214 :
2215 : /** Periodic Advertising Sync Transfer options */
2216 1 : enum bt_le_per_adv_sync_transfer_opt {
2217 : /** Convenience value when no options are specified. */
2218 : BT_LE_PER_ADV_SYNC_TRANSFER_OPT_NONE = 0,
2219 :
2220 : /**
2221 : * @brief No Angle of Arrival (AoA)
2222 : *
2223 : * Do not sync with Angle of Arrival (AoA) constant tone extension
2224 : **/
2225 : BT_LE_PER_ADV_SYNC_TRANSFER_OPT_SYNC_NO_AOA = BIT(0),
2226 :
2227 : /**
2228 : * @brief No Angle of Departure (AoD) 1 us
2229 : *
2230 : * Do not sync with Angle of Departure (AoD) 1 us
2231 : * constant tone extension
2232 : */
2233 : BT_LE_PER_ADV_SYNC_TRANSFER_OPT_SYNC_NO_AOD_1US = BIT(1),
2234 :
2235 : /**
2236 : * @brief No Angle of Departure (AoD) 2
2237 : *
2238 : * Do not sync with Angle of Departure (AoD) 2 us
2239 : * constant tone extension
2240 : */
2241 : BT_LE_PER_ADV_SYNC_TRANSFER_OPT_SYNC_NO_AOD_2US = BIT(2),
2242 :
2243 : /** Only sync to packets with constant tone extension */
2244 : BT_LE_PER_ADV_SYNC_TRANSFER_OPT_SYNC_ONLY_CTE = BIT(3),
2245 :
2246 : /**
2247 : * @brief Sync to received PAST packets but don't generate sync reports
2248 : *
2249 : * This option must not be set at the same time as
2250 : * @ref BT_LE_PER_ADV_SYNC_TRANSFER_OPT_FILTER_DUPLICATES.
2251 : */
2252 : BT_LE_PER_ADV_SYNC_TRANSFER_OPT_REPORTING_INITIALLY_DISABLED = BIT(4),
2253 :
2254 : /**
2255 : * @brief Sync to received PAST packets and generate sync reports with duplicate filtering
2256 : *
2257 : * This option must not be set at the same time as
2258 : * @ref BT_LE_PER_ADV_SYNC_TRANSFER_OPT_REPORTING_INITIALLY_DISABLED.
2259 : */
2260 : BT_LE_PER_ADV_SYNC_TRANSFER_OPT_FILTER_DUPLICATES = BIT(5),
2261 : };
2262 :
2263 : /**
2264 : * @brief Parameters for periodic advertising sync transfer.
2265 : *
2266 : * @details This struct defines the parameters for configuring periodic advertising sync transfers
2267 : * (PASTs). It includes settings for the maximum event skip, synchronization timeout, and options
2268 : * for sync transfer.
2269 : *
2270 : * @note Used in the @ref bt_le_per_adv_sync_transfer_subscribe function to configure sync transfer
2271 : * settings.
2272 : */
2273 1 : struct bt_le_per_adv_sync_transfer_param {
2274 : /**
2275 : * @brief Maximum event skip
2276 : *
2277 : * The number of periodic advertising packets that can be skipped
2278 : * after a successful receive.
2279 : */
2280 1 : uint16_t skip;
2281 :
2282 : /**
2283 : * @brief Synchronization timeout (N * 10 ms)
2284 : *
2285 : * Synchronization timeout for the periodic advertising sync.
2286 : * Range 0x000A to 0x4000 (100 ms to 163840 ms)
2287 : */
2288 1 : uint16_t timeout;
2289 :
2290 : /** Periodic Advertising Sync Transfer options, see @ref bt_le_per_adv_sync_transfer_opt. */
2291 1 : uint32_t options;
2292 : };
2293 :
2294 : /**
2295 : * @brief Transfer the periodic advertising sync information to a peer device.
2296 : *
2297 : * This will allow another device to quickly synchronize to the same periodic
2298 : * advertising train that this device is currently synced to.
2299 : *
2300 : * @param per_adv_sync The periodic advertising sync to transfer.
2301 : * @param conn The peer device that will receive the sync information.
2302 : * @param service_data Application service data provided to the remote host.
2303 : *
2304 : * @return Zero on success or (negative) error code otherwise.
2305 : */
2306 1 : int bt_le_per_adv_sync_transfer(const struct bt_le_per_adv_sync *per_adv_sync,
2307 : const struct bt_conn *conn,
2308 : uint16_t service_data);
2309 :
2310 :
2311 : /**
2312 : * @brief Transfer the information about a periodic advertising set.
2313 : *
2314 : * This will allow another device to quickly synchronize to periodic
2315 : * advertising set from this device.
2316 : *
2317 : * @param adv The periodic advertising set to transfer info of.
2318 : * @param conn The peer device that will receive the information.
2319 : * @param service_data Application service data provided to the remote host.
2320 : *
2321 : * @return Zero on success or (negative) error code otherwise.
2322 : */
2323 1 : int bt_le_per_adv_set_info_transfer(const struct bt_le_ext_adv *adv,
2324 : const struct bt_conn *conn,
2325 : uint16_t service_data);
2326 :
2327 : /**
2328 : * @brief Subscribe to periodic advertising sync transfers (PASTs).
2329 : *
2330 : * Sets the parameters and allow other devices to transfer periodic advertising
2331 : * syncs.
2332 : *
2333 : * @param conn The connection to set the parameters for. If NULL default
2334 : * parameters for all connections will be set. Parameters set
2335 : * for specific connection will always have precedence.
2336 : * @param param The periodic advertising sync transfer parameters.
2337 : *
2338 : * @return Zero on success or (negative) error code otherwise.
2339 : */
2340 1 : int bt_le_per_adv_sync_transfer_subscribe(
2341 : const struct bt_conn *conn,
2342 : const struct bt_le_per_adv_sync_transfer_param *param);
2343 :
2344 : /**
2345 : * @brief Unsubscribe from periodic advertising sync transfers (PASTs).
2346 : *
2347 : * Remove the parameters that allow other devices to transfer periodic
2348 : * advertising syncs.
2349 : *
2350 : * @param conn The connection to remove the parameters for. If NULL default
2351 : * parameters for all connections will be removed. Unsubscribing
2352 : * for a specific device, will still allow other devices to
2353 : * transfer periodic advertising syncs.
2354 : *
2355 : * @return Zero on success or (negative) error code otherwise.
2356 : */
2357 1 : int bt_le_per_adv_sync_transfer_unsubscribe(const struct bt_conn *conn);
2358 :
2359 : /**
2360 : * @brief Add a device to the periodic advertising list.
2361 : *
2362 : * Add peer device LE address to the periodic advertising list. This will make
2363 : * it possibly to automatically create a periodic advertising sync to this
2364 : * device.
2365 : *
2366 : * @param addr Bluetooth LE identity address.
2367 : * @param sid The advertising set ID. This value is obtained from the
2368 : * @ref bt_le_scan_recv_info in the scan callback.
2369 : *
2370 : * @return Zero on success or (negative) error code otherwise.
2371 : */
2372 1 : int bt_le_per_adv_list_add(const bt_addr_le_t *addr, uint8_t sid);
2373 :
2374 : /**
2375 : * @brief Remove a device from the periodic advertising list.
2376 : *
2377 : * Removes peer device LE address from the periodic advertising list.
2378 : *
2379 : * @param addr Bluetooth LE identity address.
2380 : * @param sid The advertising set ID. This value is obtained from the
2381 : * @ref bt_le_scan_recv_info in the scan callback.
2382 : *
2383 : * @return Zero on success or (negative) error code otherwise.
2384 : */
2385 1 : int bt_le_per_adv_list_remove(const bt_addr_le_t *addr, uint8_t sid);
2386 :
2387 : /**
2388 : * @brief Clear the periodic advertising list.
2389 : *
2390 : * Clears the entire periodic advertising list.
2391 : *
2392 : * @return Zero on success or (negative) error code otherwise.
2393 : */
2394 1 : int bt_le_per_adv_list_clear(void);
2395 :
2396 :
2397 0 : enum bt_le_scan_opt {
2398 : /** Convenience value when no options are specified. */
2399 : BT_LE_SCAN_OPT_NONE = 0,
2400 :
2401 : /** Filter duplicates. */
2402 : BT_LE_SCAN_OPT_FILTER_DUPLICATE = BIT(0),
2403 :
2404 : /** Filter using filter accept list. */
2405 : BT_LE_SCAN_OPT_FILTER_ACCEPT_LIST = BIT(1),
2406 :
2407 : /** Enable scan on coded PHY (Long Range).*/
2408 : BT_LE_SCAN_OPT_CODED = BIT(2),
2409 :
2410 : /**
2411 : * @brief Disable scan on 1M phy.
2412 : *
2413 : * @note Requires @ref BT_LE_SCAN_OPT_CODED.
2414 : */
2415 : BT_LE_SCAN_OPT_NO_1M = BIT(3),
2416 : };
2417 :
2418 0 : enum bt_le_scan_type {
2419 : /** Scan without requesting additional information from advertisers. */
2420 : BT_LE_SCAN_TYPE_PASSIVE = 0x00,
2421 :
2422 : /**
2423 : * @brief Scan and request additional information from advertisers.
2424 : *
2425 : * Using this scan type will automatically send scan requests to all
2426 : * devices. Scan responses are received in the same manner and using the
2427 : * same callbacks as advertising reports.
2428 : */
2429 : BT_LE_SCAN_TYPE_ACTIVE = 0x01,
2430 : };
2431 :
2432 : /** LE scan parameters */
2433 1 : struct bt_le_scan_param {
2434 : /** Scan type. @ref BT_LE_SCAN_TYPE_ACTIVE or @ref BT_LE_SCAN_TYPE_PASSIVE. */
2435 1 : uint8_t type;
2436 :
2437 : /** Bit-field of scanning options. */
2438 1 : uint8_t options;
2439 :
2440 : /** Scan interval (N * 0.625 ms).
2441 : *
2442 : * @note When @kconfig{CONFIG_BT_SCAN_AND_INITIATE_IN_PARALLEL} is enabled
2443 : * and the application wants to scan and connect in parallel,
2444 : * the Bluetooth Controller may require the scan interval used
2445 : * for scanning and connection establishment to be equal to
2446 : * obtain the best performance.
2447 : */
2448 1 : uint16_t interval;
2449 :
2450 : /** Scan window (N * 0.625 ms)
2451 : *
2452 : * @note When @kconfig{CONFIG_BT_SCAN_AND_INITIATE_IN_PARALLEL} is enabled
2453 : * and the application wants to scan and connect in parallel,
2454 : * the Bluetooth Controller may require the scan window used
2455 : * for scanning and connection establishment to be equal to
2456 : * obtain the best performance.
2457 : */
2458 1 : uint16_t window;
2459 :
2460 : /**
2461 : * @brief Scan timeout (N * 10 ms)
2462 : *
2463 : * Application will be notified by the scan timeout callback.
2464 : * Set zero to disable timeout.
2465 : */
2466 1 : uint16_t timeout;
2467 :
2468 : /**
2469 : * @brief Scan interval LE Coded PHY (N * 0.625 MS)
2470 : *
2471 : * Set zero to use same as LE 1M PHY scan interval.
2472 : */
2473 1 : uint16_t interval_coded;
2474 :
2475 : /**
2476 : * @brief Scan window LE Coded PHY (N * 0.625 MS)
2477 : *
2478 : * Set zero to use same as LE 1M PHY scan window.
2479 : */
2480 1 : uint16_t window_coded;
2481 : };
2482 :
2483 : /** LE advertisement and scan response packet information */
2484 1 : struct bt_le_scan_recv_info {
2485 : /**
2486 : * @brief Advertiser LE address and type.
2487 : *
2488 : * If advertiser is anonymous then this address will be
2489 : * @ref BT_ADDR_LE_ANY.
2490 : */
2491 1 : const bt_addr_le_t *addr;
2492 :
2493 : /** Advertising Set Identifier, valid range @ref BT_GAP_SID_MIN to @ref BT_GAP_SID_MAX. */
2494 1 : uint8_t sid;
2495 :
2496 : /** Strength of advertiser signal. */
2497 1 : int8_t rssi;
2498 :
2499 : /** Transmit power of the advertiser. */
2500 1 : int8_t tx_power;
2501 :
2502 : /**
2503 : * @brief Advertising packet type.
2504 : *
2505 : * Uses the @ref bt_gap_adv_type value.
2506 : *
2507 : * May indicate that this is a scan response if the type is
2508 : * @ref BT_GAP_ADV_TYPE_SCAN_RSP.
2509 : */
2510 1 : uint8_t adv_type;
2511 :
2512 : /**
2513 : * @brief Advertising packet properties bitfield.
2514 : *
2515 : * Uses the @ref bt_gap_adv_prop values.
2516 : * May indicate that this is a scan response if the value contains the
2517 : * @ref BT_GAP_ADV_PROP_SCAN_RESPONSE bit.
2518 : *
2519 : */
2520 1 : uint16_t adv_props;
2521 :
2522 : /**
2523 : * @brief Periodic advertising interval (N * 1.25 ms).
2524 : *
2525 : * If 0 there is no periodic advertising.
2526 : */
2527 1 : uint16_t interval;
2528 :
2529 : /** Primary advertising channel PHY. */
2530 1 : uint8_t primary_phy;
2531 :
2532 : /** Secondary advertising channel PHY. */
2533 1 : uint8_t secondary_phy;
2534 : };
2535 :
2536 : /** Listener context for (LE) scanning. */
2537 1 : struct bt_le_scan_cb {
2538 :
2539 : /**
2540 : * @brief Advertisement packet and scan response received callback.
2541 : *
2542 : * @param info Advertiser packet and scan response information.
2543 : * @param buf Buffer containing advertiser data.
2544 : */
2545 1 : void (*recv)(const struct bt_le_scan_recv_info *info,
2546 : struct net_buf_simple *buf);
2547 :
2548 : /** @brief The scanner has stopped scanning after scan timeout. */
2549 1 : void (*timeout)(void);
2550 :
2551 0 : sys_snode_t node;
2552 : };
2553 :
2554 : /**
2555 : * @brief Initialize scan parameters
2556 : *
2557 : * @param _type Scan Type, @ref BT_LE_SCAN_TYPE_ACTIVE or @ref BT_LE_SCAN_TYPE_PASSIVE.
2558 : * @param _options Scan options
2559 : * @param _interval Scan Interval (N * 0.625 ms)
2560 : * @param _window Scan Window (N * 0.625 ms)
2561 : */
2562 1 : #define BT_LE_SCAN_PARAM_INIT(_type, _options, _interval, _window) \
2563 : { \
2564 : .type = (_type), \
2565 : .options = (_options), \
2566 : .interval = (_interval), \
2567 : .window = (_window), \
2568 : .timeout = 0, \
2569 : .interval_coded = 0, \
2570 : .window_coded = 0, \
2571 : }
2572 :
2573 : /**
2574 : * @brief Helper to declare scan parameters inline
2575 : *
2576 : * @param _type Scan Type, @ref BT_LE_SCAN_TYPE_ACTIVE or @ref BT_LE_SCAN_TYPE_PASSIVE.
2577 : * @param _options Scan options
2578 : * @param _interval Scan Interval (N * 0.625 ms)
2579 : * @param _window Scan Window (N * 0.625 ms)
2580 : */
2581 1 : #define BT_LE_SCAN_PARAM(_type, _options, _interval, _window) \
2582 : ((struct bt_le_scan_param[]) { \
2583 : BT_LE_SCAN_PARAM_INIT(_type, _options, _interval, _window) \
2584 : })
2585 :
2586 : /**
2587 : * @brief Helper macro to enable active scanning to discover new devices.
2588 : */
2589 1 : #define BT_LE_SCAN_ACTIVE BT_LE_SCAN_PARAM(BT_LE_SCAN_TYPE_ACTIVE, \
2590 : BT_LE_SCAN_OPT_FILTER_DUPLICATE, \
2591 : BT_GAP_SCAN_FAST_INTERVAL, \
2592 : BT_GAP_SCAN_FAST_WINDOW)
2593 :
2594 : /**
2595 : * @brief Helper macro to enable active scanning to discover new devices with window == interval.
2596 : *
2597 : * Continuous scanning should be used to maximize the chances of receiving advertising packets.
2598 : */
2599 1 : #define BT_LE_SCAN_ACTIVE_CONTINUOUS BT_LE_SCAN_PARAM(BT_LE_SCAN_TYPE_ACTIVE, \
2600 : BT_LE_SCAN_OPT_FILTER_DUPLICATE, \
2601 : BT_GAP_SCAN_FAST_INTERVAL_MIN, \
2602 : BT_GAP_SCAN_FAST_WINDOW)
2603 : BUILD_ASSERT(BT_GAP_SCAN_FAST_WINDOW == BT_GAP_SCAN_FAST_INTERVAL_MIN,
2604 : "Continuous scanning is requested by setting window and interval equal.");
2605 :
2606 : /**
2607 : * @brief Helper macro to enable passive scanning to discover new devices.
2608 : *
2609 : * This macro should be used if information required for device identification
2610 : * (e.g., UUID) are known to be placed in Advertising Data.
2611 : */
2612 1 : #define BT_LE_SCAN_PASSIVE BT_LE_SCAN_PARAM(BT_LE_SCAN_TYPE_PASSIVE, \
2613 : BT_LE_SCAN_OPT_FILTER_DUPLICATE, \
2614 : BT_GAP_SCAN_FAST_INTERVAL, \
2615 : BT_GAP_SCAN_FAST_WINDOW)
2616 :
2617 : /**
2618 : * @brief Helper macro to enable passive scanning to discover new devices with window==interval.
2619 : *
2620 : * This macro should be used if information required for device identification
2621 : * (e.g., UUID) are known to be placed in Advertising Data.
2622 : */
2623 1 : #define BT_LE_SCAN_PASSIVE_CONTINUOUS BT_LE_SCAN_PARAM(BT_LE_SCAN_TYPE_PASSIVE, \
2624 : BT_LE_SCAN_OPT_FILTER_DUPLICATE, \
2625 : BT_GAP_SCAN_FAST_INTERVAL_MIN, \
2626 : BT_GAP_SCAN_FAST_WINDOW)
2627 : BUILD_ASSERT(BT_GAP_SCAN_FAST_WINDOW == BT_GAP_SCAN_FAST_INTERVAL_MIN,
2628 : "Continuous scanning is requested by setting window and interval equal.");
2629 :
2630 : /**
2631 : * @brief Helper macro to enable active scanning to discover new devices.
2632 : * Include scanning on Coded PHY in addition to 1M PHY.
2633 : */
2634 1 : #define BT_LE_SCAN_CODED_ACTIVE \
2635 : BT_LE_SCAN_PARAM(BT_LE_SCAN_TYPE_ACTIVE, \
2636 : BT_LE_SCAN_OPT_CODED | \
2637 : BT_LE_SCAN_OPT_FILTER_DUPLICATE, \
2638 : BT_GAP_SCAN_FAST_INTERVAL, \
2639 : BT_GAP_SCAN_FAST_WINDOW)
2640 :
2641 : /**
2642 : * @brief Helper macro to enable passive scanning to discover new devices.
2643 : * Include scanning on Coded PHY in addition to 1M PHY.
2644 : *
2645 : * This macro should be used if information required for device identification
2646 : * (e.g., UUID) are known to be placed in Advertising Data.
2647 : */
2648 1 : #define BT_LE_SCAN_CODED_PASSIVE \
2649 : BT_LE_SCAN_PARAM(BT_LE_SCAN_TYPE_PASSIVE, \
2650 : BT_LE_SCAN_OPT_CODED | \
2651 : BT_LE_SCAN_OPT_FILTER_DUPLICATE, \
2652 : BT_GAP_SCAN_FAST_INTERVAL, \
2653 : BT_GAP_SCAN_FAST_WINDOW)
2654 :
2655 : /**
2656 : * @brief Start (LE) scanning
2657 : *
2658 : * Start LE scanning with given parameters and provide results through
2659 : * the specified callback.
2660 : *
2661 : * @note The LE scanner by default does not use the Identity Address of the
2662 : * local device when @kconfig{CONFIG_BT_PRIVACY} is disabled. This is to
2663 : * prevent the active scanner from disclosing the identity address information
2664 : * when requesting additional information from advertisers.
2665 : * In order to enable directed advertiser reports then
2666 : * @kconfig{CONFIG_BT_SCAN_WITH_IDENTITY} must be enabled.
2667 : *
2668 : * @note Setting the `param.timeout` parameter is not supported when
2669 : * @kconfig{CONFIG_BT_PRIVACY} is enabled, when the param.type is @ref
2670 : * BT_LE_SCAN_TYPE_ACTIVE. Supplying a non-zero timeout will result in an
2671 : * -EINVAL error code.
2672 : *
2673 : * @note The scanner will automatically scan for extended advertising packets if their support is
2674 : * enabled through @kconfig{CONFIG_BT_EXT_ADV}.
2675 : *
2676 : * @param param Scan parameters.
2677 : * @param cb Callback to notify scan results. May be NULL if callback
2678 : * registration through @ref bt_le_scan_cb_register is preferred.
2679 : *
2680 : * @return Zero on success or error code otherwise, positive in case of
2681 : * protocol error or negative (POSIX) in case of stack internal error.
2682 : * @retval -EBUSY if the scanner is already being started in a different thread.
2683 : */
2684 1 : int bt_le_scan_start(const struct bt_le_scan_param *param, bt_le_scan_cb_t cb);
2685 :
2686 : /**
2687 : * @brief Stop (LE) scanning.
2688 : *
2689 : * Stops ongoing LE scanning.
2690 : *
2691 : * @return Zero on success or error code otherwise, positive in case of
2692 : * protocol error or negative (POSIX) in case of stack internal error.
2693 : */
2694 1 : int bt_le_scan_stop(void);
2695 :
2696 : /**
2697 : * @brief Register scanner packet callbacks.
2698 : *
2699 : * Adds the callback structure to the list of callback structures that monitors
2700 : * scanner activity.
2701 : *
2702 : * This callback will be called for all scanner activity.
2703 : *
2704 : * @param cb Callback struct. Must point to memory that remains valid.
2705 : *
2706 : * @retval 0 Success.
2707 : * @retval -EEXIST if @p cb was already registered.
2708 : */
2709 1 : int bt_le_scan_cb_register(struct bt_le_scan_cb *cb);
2710 :
2711 : /**
2712 : * @brief Unregister scanner packet callbacks.
2713 : *
2714 : * Remove the callback structure from the list of scanner callbacks.
2715 : *
2716 : * @param cb Callback struct. Must point to memory that remains valid.
2717 : */
2718 1 : void bt_le_scan_cb_unregister(struct bt_le_scan_cb *cb);
2719 :
2720 : /**
2721 : * @brief Add device (LE) to filter accept list.
2722 : *
2723 : * Add peer device LE address to the filter accept list.
2724 : *
2725 : * @note The filter accept list cannot be modified when an LE role is using
2726 : * the filter accept list, i.e advertiser or scanner using a filter accept list
2727 : * or automatic connecting to devices using filter accept list.
2728 : *
2729 : * @param addr Bluetooth LE identity address.
2730 : *
2731 : * @return Zero on success or error code otherwise, positive in case of
2732 : * protocol error or negative (POSIX) in case of stack internal error.
2733 : */
2734 1 : int bt_le_filter_accept_list_add(const bt_addr_le_t *addr);
2735 :
2736 : /**
2737 : * @brief Remove device (LE) from filter accept list.
2738 : *
2739 : * Remove peer device LE address from the filter accept list.
2740 : *
2741 : * @note The filter accept list cannot be modified when an LE role is using
2742 : * the filter accept list, i.e advertiser or scanner using a filter accept list
2743 : * or automatic connecting to devices using filter accept list.
2744 : *
2745 : * @param addr Bluetooth LE identity address.
2746 : *
2747 : * @return Zero on success or error code otherwise, positive in case of
2748 : * protocol error or negative (POSIX) in case of stack internal error.
2749 : */
2750 1 : int bt_le_filter_accept_list_remove(const bt_addr_le_t *addr);
2751 :
2752 : /**
2753 : * @brief Clear filter accept list.
2754 : *
2755 : * Clear all devices from the filter accept list.
2756 : *
2757 : * @note The filter accept list cannot be modified when an LE role is using
2758 : * the filter accept list, i.e advertiser or scanner using a filter accept
2759 : * list or automatic connecting to devices using filter accept list.
2760 : *
2761 : * @return Zero on success or error code otherwise, positive in case of
2762 : * protocol error or negative (POSIX) in case of stack internal error.
2763 : */
2764 1 : int bt_le_filter_accept_list_clear(void);
2765 :
2766 : /**
2767 : * @brief Set (LE) channel map.
2768 : *
2769 : * Used to inform the Controller of known channel classifications. The Host can specify which
2770 : * channels are bad or unknown by setting the corresponding bit in the channel map to respectively
2771 : * 0 or 1.
2772 : *
2773 : * @note The interval between two succesive calls to this function must be at least one second.
2774 : *
2775 : * @param chan_map Channel map. 5 octets where each bit represents a channel. Only the lower 37 bits
2776 : * are valid.
2777 : *
2778 : * @return Zero on success or error code otherwise, positive in case of
2779 : * protocol error or negative (POSIX) in case of stack internal error.
2780 : */
2781 1 : int bt_le_set_chan_map(uint8_t chan_map[5]);
2782 :
2783 : /**
2784 : * @brief Set the Resolvable Private Address timeout in runtime
2785 : *
2786 : * The new RPA timeout value will be used for the next RPA rotation
2787 : * and all subsequent rotations until another override is scheduled
2788 : * with this API.
2789 : *
2790 : * Initially, @kconfig{CONFIG_BT_RPA_TIMEOUT} is used as the RPA timeout.
2791 : *
2792 : * @kconfig_dep{CONFIG_BT_RPA_TIMEOUT_DYNAMIC}.
2793 : *
2794 : * @param new_rpa_timeout Resolvable Private Address timeout in seconds.
2795 : *
2796 : * @retval 0 Success.
2797 : * @retval -EINVAL RPA timeout value is invalid. Valid range is 1s - 3600s.
2798 : */
2799 1 : int bt_le_set_rpa_timeout(uint16_t new_rpa_timeout);
2800 :
2801 : /**
2802 : * @brief Helper for parsing advertising (or EIR or OOB) data.
2803 : *
2804 : * A helper for parsing the basic AD Types used for Extended Inquiry
2805 : * Response (EIR), Advertising Data (AD), and OOB data blocks. The most
2806 : * common scenario is to call this helper on the advertising data
2807 : * received in the callback that was given to @ref bt_le_scan_start.
2808 : *
2809 : * @warning This helper function will consume @p ad when parsing. The user should make a copy if the
2810 : * original data is to be used afterwards. This can be done by using
2811 : * @ref net_buf_simple_save to store the state prior to the function call, and then using
2812 : * @ref net_buf_simple_restore to restore the state afterwards.
2813 : *
2814 : * @param ad Advertising data as given to the @ref bt_le_scan_cb_t callback.
2815 : * @param func Callback function which will be called for each element
2816 : * that's found in the data. The callback should return
2817 : * true to continue parsing, or false to stop parsing.
2818 : * @param user_data User data to be passed to the callback.
2819 : */
2820 1 : void bt_data_parse(struct net_buf_simple *ad,
2821 : bool (*func)(struct bt_data *data, void *user_data),
2822 : void *user_data);
2823 :
2824 : /** LE Secure Connections pairing Out of Band data. */
2825 1 : struct bt_le_oob_sc_data {
2826 : /** Random Number. */
2827 1 : uint8_t r[16];
2828 :
2829 : /** Confirm Value. */
2830 1 : uint8_t c[16];
2831 : };
2832 :
2833 : /** LE Out of Band information. */
2834 1 : struct bt_le_oob {
2835 : /** LE address. If privacy is enabled this is a Resolvable Private
2836 : * Address.
2837 : */
2838 1 : bt_addr_le_t addr;
2839 :
2840 : /** LE Secure Connections pairing Out of Band data. */
2841 1 : struct bt_le_oob_sc_data le_sc_data;
2842 : };
2843 :
2844 : /**
2845 : * @brief Get local LE Out of Band (OOB) information.
2846 : *
2847 : * This function allows to get local information that are useful for
2848 : * Out of Band pairing or connection creation.
2849 : *
2850 : * If privacy @kconfig{CONFIG_BT_PRIVACY} is enabled this will result in
2851 : * generating new Resolvable Private Address (RPA) that is valid for
2852 : * @kconfig{CONFIG_BT_RPA_TIMEOUT} seconds. This address will be used for
2853 : * advertising started by @ref bt_le_adv_start, active scanning and
2854 : * connection creation.
2855 : *
2856 : * @note If privacy is enabled the RPA cannot be refreshed in the following
2857 : * cases:
2858 : * - Creating a connection in progress, wait for the connected callback.
2859 : * In addition when extended advertising @kconfig{CONFIG_BT_EXT_ADV} is
2860 : * not enabled or not supported by the controller:
2861 : * - Advertiser is enabled using a Random Static Identity Address as a
2862 : * different local identity address.
2863 : * - The local identity address conflicts with the local identity address used by other
2864 : * roles.
2865 : *
2866 : * @param[in] id Local identity handle (typically @ref BT_ID_DEFAULT). Corresponds to the identity
2867 : * address this function will be called for.
2868 : * @param[out] oob LE OOB information
2869 : *
2870 : * @return Zero on success or error code otherwise, positive in case of
2871 : * protocol error or negative (POSIX) in case of stack internal error.
2872 : */
2873 1 : int bt_le_oob_get_local(uint8_t id, struct bt_le_oob *oob);
2874 :
2875 : /**
2876 : * @brief Get local LE Out of Band (OOB) information.
2877 : *
2878 : * This function allows to get local information that are useful for
2879 : * Out of Band pairing or connection creation.
2880 : *
2881 : * If privacy @kconfig{CONFIG_BT_PRIVACY} is enabled this will result in
2882 : * generating new Resolvable Private Address (RPA) that is valid for
2883 : * @kconfig{CONFIG_BT_RPA_TIMEOUT} seconds. This address will be used by the
2884 : * advertising set.
2885 : *
2886 : * @note When generating OOB information for multiple advertising set all
2887 : * OOB information needs to be generated at the same time.
2888 : *
2889 : * @note If privacy is enabled the RPA cannot be refreshed in the following
2890 : * cases:
2891 : * - Creating a connection in progress, wait for the connected callback.
2892 : *
2893 : * @param[in] adv The advertising set object
2894 : * @param[out] oob LE OOB information
2895 : *
2896 : * @return Zero on success or error code otherwise, positive in case
2897 : * of protocol error or negative (POSIX) in case of stack internal error.
2898 : */
2899 1 : int bt_le_ext_adv_oob_get_local(struct bt_le_ext_adv *adv,
2900 : struct bt_le_oob *oob);
2901 :
2902 : /**
2903 : * @brief Clear pairing information.
2904 : *
2905 : * @param id Local identity handle (typically @ref BT_ID_DEFAULT). Corresponds to the identity
2906 : * address this function will be called for.
2907 : * @param addr Remote address, NULL or BT_ADDR_LE_ANY to clear all remote
2908 : * devices.
2909 : *
2910 : * @return 0 on success or negative error value on failure.
2911 : */
2912 1 : int bt_unpair(uint8_t id, const bt_addr_le_t *addr);
2913 :
2914 : /** Information about a bond with a remote device. */
2915 1 : struct bt_bond_info {
2916 : /** Address of the remote device. */
2917 1 : bt_addr_le_t addr;
2918 : };
2919 :
2920 : /**
2921 : * @brief Iterate through all existing bonds.
2922 : *
2923 : * @param id Local identity handle (typically @ref BT_ID_DEFAULT). Corresponds to the
2924 : * identity address used in iteration.
2925 : * @param func Function to call for each bond.
2926 : * @param user_data Data to pass to the callback function.
2927 : */
2928 1 : void bt_foreach_bond(uint8_t id, void (*func)(const struct bt_bond_info *info,
2929 : void *user_data),
2930 : void *user_data);
2931 :
2932 : /**
2933 : * @brief Configure vendor data path
2934 : *
2935 : * @details Request the Controller to configure the data transport path in a given direction between
2936 : * the Controller and the Host.
2937 : *
2938 : * @param dir Direction to be configured, BT_HCI_DATAPATH_DIR_HOST_TO_CTLR or
2939 : * BT_HCI_DATAPATH_DIR_CTLR_TO_HOST
2940 : * @param id Vendor specific logical transport channel ID, range
2941 : * [BT_HCI_DATAPATH_ID_VS..BT_HCI_DATAPATH_ID_VS_END]
2942 : * @param vs_config_len Length of additional vendor specific configuration data
2943 : * @param vs_config Pointer to additional vendor specific configuration data
2944 : *
2945 : * @return 0 in case of success or negative value in case of error.
2946 : */
2947 1 : int bt_configure_data_path(uint8_t dir, uint8_t id, uint8_t vs_config_len,
2948 : const uint8_t *vs_config);
2949 :
2950 : /**
2951 : * @brief Parameters for synchronizing with specific periodic advertising subevents.
2952 : *
2953 : * @details This struct contains the parameters used to synchronize with a subset of subevents in
2954 : * periodic advertising. It includes the periodic advertising properties, the number of subevents
2955 : * to sync to, and the list of subevents that the controller should synchronize with.
2956 : *
2957 : * @note Used in @ref bt_le_per_adv_sync_subevent function to control synchronization.
2958 : */
2959 1 : struct bt_le_per_adv_sync_subevent_params {
2960 : /** @brief Periodic Advertising Properties.
2961 : *
2962 : * Bit 6 is include TxPower, all others RFU.
2963 : *
2964 : */
2965 1 : uint16_t properties;
2966 :
2967 : /** Number of subevents to sync to */
2968 1 : uint8_t num_subevents;
2969 :
2970 : /** @brief The subevent(s) to synchronize with
2971 : *
2972 : * The array must have @ref num_subevents elements.
2973 : *
2974 : */
2975 1 : uint8_t *subevents;
2976 : };
2977 :
2978 : /** @brief Synchronize with a subset of subevents
2979 : *
2980 : * Until this command is issued, the subevent(s) the controller is synchronized
2981 : * to is unspecified.
2982 : *
2983 : * @param per_adv_sync The periodic advertising sync object.
2984 : * @param params Subevent sync parameters.
2985 : *
2986 : * @return 0 in case of success or negative value in case of error.
2987 : */
2988 1 : int bt_le_per_adv_sync_subevent(struct bt_le_per_adv_sync *per_adv_sync,
2989 : struct bt_le_per_adv_sync_subevent_params *params);
2990 :
2991 : /**
2992 : * @brief Parameters for sending a periodic advertising response.
2993 : *
2994 : * @details This struct contains the parameters used when sending a response to a periodic
2995 : * advertising request (see @ref bt_le_per_adv_set_response_data function). The response is sent
2996 : * in the specified subevent and response slot, and includes event and subevent counters
2997 : * to track the request the response corresponds to.
2998 : */
2999 1 : struct bt_le_per_adv_response_params {
3000 : /**
3001 : * @brief The periodic event counter of the request the response is sent to.
3002 : *
3003 : * @ref bt_le_per_adv_sync_recv_info
3004 : *
3005 : * @note The response can be sent up to one periodic interval after
3006 : * the request was received.
3007 : *
3008 : */
3009 1 : uint16_t request_event;
3010 :
3011 : /**
3012 : * @brief The subevent counter of the request the response is sent to.
3013 : *
3014 : * @ref bt_le_per_adv_sync_recv_info
3015 : *
3016 : */
3017 1 : uint8_t request_subevent;
3018 :
3019 : /** The subevent the response shall be sent in */
3020 1 : uint8_t response_subevent;
3021 :
3022 : /** The response slot the response shall be sent in */
3023 1 : uint8_t response_slot;
3024 : };
3025 :
3026 : /**
3027 : * @brief Set the data for a response slot in a specific subevent of the PAwR.
3028 : *
3029 : * This function is called by the application to set the response data.
3030 : * The data for a response slot shall be transmitted only once.
3031 : *
3032 : * @param per_adv_sync The periodic advertising sync object.
3033 : * @param params Parameters.
3034 : * @param data The response data to send.
3035 : *
3036 : * @return Zero on success or (negative) error code otherwise.
3037 : */
3038 1 : int bt_le_per_adv_set_response_data(struct bt_le_per_adv_sync *per_adv_sync,
3039 : const struct bt_le_per_adv_response_params *params,
3040 : const struct net_buf_simple *data);
3041 :
3042 : /**
3043 : * @brief Check if a device identified by a Bluetooth LE address is bonded.
3044 : *
3045 : * @details Valid Bluetooth LE identity addresses are either public address or random static
3046 : * address.
3047 : *
3048 : * @param id Local identity handle (typically @ref BT_ID_DEFAULT). Corresponds to the identity
3049 : * address this function will be called for.
3050 : * @param addr Bluetooth LE device address.
3051 : *
3052 : * @return true if @p addr is bonded with local @p id
3053 : */
3054 1 : bool bt_le_bond_exists(uint8_t id, const bt_addr_le_t *addr);
3055 :
3056 : /**
3057 : * @}
3058 : */
3059 :
3060 : #ifdef __cplusplus
3061 : }
3062 : #endif
3063 : /**
3064 : * @}
3065 : */
3066 :
3067 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_BLUETOOTH_H_ */
|
