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