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 * @{
18 */
19
20 #include <stdbool.h>
21 #include <string.h>
22 #include <stdio.h>
23 #include <misc/util.h>
24 #include <net/buf.h>
25 #include <bluetooth/gap.h>
26 #include <bluetooth/addr.h>
27 #include <bluetooth/crypto.h>
28
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32
33 /**
34 * @brief Generic Access Profile
35 * @defgroup bt_gap Generic Access Profile
36 * @ingroup bluetooth
37 * @{
38 */
39
40 /** @def BT_ID_DEFAULT
41 *
42 * Convenience macro for specifying the default identity. This helps
43 * make the code more readable, especially when only one identity is
44 * supported.
45 */
46 #define BT_ID_DEFAULT 0
47
48 /** Opaque type representing an advertiser. */
49 struct bt_le_ext_adv;
50
51 /* Don't require everyone to include conn.h */
52 struct bt_conn;
53
54 struct bt_le_ext_adv_sent_info {
55 /** The number of advertising events completed. */
56 u8_t num_sent;
57 };
58
59 struct bt_le_ext_adv_connected_info {
60 /** Connection object of the new connection */
61 struct bt_conn *conn;
62 };
63
64 struct bt_le_ext_adv_scanned_info {
65 /** Active scanner LE address and type */
66 bt_addr_le_t *addr;
67 };
68
69 struct bt_le_ext_adv_cb {
70 /** @brief The advertising set has finished sending adv data.
71 *
72 * This callback notifies the application that the advertising set has
73 * finished sending advertising data.
74 * The advertising set can either have been stopped by a timeout or
75 * because the specified number of advertising events has been reached.
76 *
77 * @param adv The advertising set object.
78 * @param info Information about the sent event.
79 */
80 void (*sent)(struct bt_le_ext_adv *adv,
81 struct bt_le_ext_adv_sent_info *info);
82
83 /** @brief The advertising set has accepted a new connection.
84 *
85 * This callback notifies the application that the advertising set has
86 * accepted a new connection.
87 *
88 * @param adv The advertising set object.
89 * @param info Information about the connected event.
90 */
91 void (*connected)(struct bt_le_ext_adv *adv,
92 struct bt_le_ext_adv_connected_info *info);
93
94 /** @brief The advertising set has sent scan response data.
95 *
96 * This callback notifies the application that the advertising set has
97 * has received a Scan Request packet, and has sent a Scan Response
98 * packet.
99 *
100 * @param adv The advertising set object.
101 * @param addr Information about the scanned event.
102 */
103 void (*scanned)(struct bt_le_ext_adv *adv,
104 struct bt_le_ext_adv_scanned_info *info);
105 };
106
107 /** @typedef bt_ready_cb_t
108 * @brief Callback for notifying that Bluetooth has been enabled.
109 *
110 * @param err zero on success or (negative) error code otherwise.
111 */
112 typedef void (*bt_ready_cb_t)(int err);
113
114 /** @brief Enable Bluetooth
115 *
116 * Enable Bluetooth. Must be the called before any calls that
117 * require communication with the local Bluetooth hardware.
118 *
119 * @param cb Callback to notify completion or NULL to perform the
120 * enabling synchronously.
121 *
122 * @return Zero on success or (negative) error code otherwise.
123 */
124 int bt_enable(bt_ready_cb_t cb);
125
126 /** @brief Set Bluetooth Device Name
127 *
128 * Set Bluetooth GAP Device Name.
129 *
130 * @param name New name
131 *
132 * @return Zero on success or (negative) error code otherwise.
133 */
134 int bt_set_name(const char *name);
135
136 /** @brief Get Bluetooth Device Name
137 *
138 * Get Bluetooth GAP Device Name.
139 *
140 * @return Bluetooth Device Name
141 */
142 const char *bt_get_name(void);
143
144 /** @brief Set the local Identity Address
145 *
146 * Allows setting the local Identity Address from the application.
147 * This API must be called before calling bt_enable(). Calling it at any
148 * other time will cause it to fail. In most cases the application doesn't
149 * need to use this API, however there are a few valid cases where
150 * it can be useful (such as for testing).
151 *
152 * At the moment, the given address must be a static random address. In the
153 * future support for public addresses may be added.
154 *
155 * @return Zero on success or (negative) error code otherwise.
156 */
157 int bt_set_id_addr(const bt_addr_le_t *addr);
158
159 /** @brief Get the currently configured identities.
160 *
161 * Returns an array of the currently configured identity addresses. To
162 * make sure all available identities can be retrieved, the number of
163 * elements in the @a addrs array should be CONFIG_BT_ID_MAX. The identity
164 * identifier that some APIs expect (such as advertising parameters) is
165 * simply the index of the identity in the @a addrs array.
166 *
167 * @note Deleted identities may show up as BT_LE_ADDR_ANY in the returned
168 * array.
169 *
170 * @param addrs Array where to store the configured identities.
171 * @param count Should be initialized to the array size. Once the function
172 * returns it will contain the number of returned identities.
173 */
174 void bt_id_get(bt_addr_le_t *addrs, size_t *count);
175
176 /** @brief Create a new identity.
177 *
178 * Create a new identity using the given address and IRK. This function
179 * can be called before calling bt_enable(), in which case it can be used
180 * to override the controller's public address (in case it has one). However,
181 * the new identity will only be stored persistently in flash when this API
182 * is used after bt_enable(). The reason is that the persistent settings
183 * are loaded after bt_enable() and would therefore cause potential conflicts
184 * with the stack blindly overwriting what's stored in flash. The identity
185 * will also not be written to flash in case a pre-defined address is
186 * provided, since in such a situation the app clearly has some place it got
187 * the address from and will be able to repeat the procedure on every power
188 * cycle, i.e. it would be redundant to also store the information in flash.
189 *
190 * If the application wants to have the stack randomly generate identities
191 * and store them in flash for later recovery, the way to do it would be
192 * to first initialize the stack (using bt_enable), then call settings_load(),
193 * and after that check with bt_id_get() how many identities were recovered.
194 * If an insufficient amount of identities were recovered the app may then
195 * call bt_id_create() to create new ones.
196 *
197 * @param addr Address to use for the new identity. If NULL or initialized
198 * to BT_ADDR_LE_ANY the stack will generate a new static
199 * random address for the identity and copy it to the given
200 * parameter upon return from this function (in case the
201 * parameter was non-NULL).
202 * @param irk Identity Resolving Key (16 bytes) to be used with this
203 * identity. If set to all zeroes or NULL, the stack will
204 * generate a random IRK for the identity and copy it back
205 * to the parameter upon return from this function (in case
206 * the parameter was non-NULL). If privacy
207 * :option:`CONFIG_BT_PRIVACY` is not enabled this parameter must
208 * be NULL.
209 *
210 * @return Identity identifier (>= 0) in case of success, or a negative
211 * error code on failure.
212 */
213 int bt_id_create(bt_addr_le_t *addr, u8_t *irk);
214
215 /** @brief Reset/reclaim an identity for reuse.
216 *
217 * The semantics of the @a addr and @a irk parameters of this function
218 * are the same as with bt_id_create(). The difference is the first
219 * @a id parameter that needs to be an existing identity (if it doesn't
220 * exist this function will return an error). When given an existing
221 * identity this function will disconnect any connections created using it,
222 * remove any pairing keys or other data associated with it, and then create
223 * a new identity in the same slot, based on the @a addr and @a irk
224 * parameters.
225 *
226 * @note the default identity (BT_ID_DEFAULT) cannot be reset, i.e. this
227 * API will return an error if asked to do that.
228 *
229 * @param id Existing identity identifier.
230 * @param addr Address to use for the new identity. If NULL or initialized
231 * to BT_ADDR_LE_ANY the stack will generate a new static
232 * random address for the identity and copy it to the given
233 * parameter upon return from this function (in case the
234 * parameter was non-NULL).
235 * @param irk Identity Resolving Key (16 bytes) to be used with this
236 * identity. If set to all zeroes or NULL, the stack will
237 * generate a random IRK for the identity and copy it back
238 * to the parameter upon return from this function (in case
239 * the parameter was non-NULL). If privacy
240 * :option:`CONFIG_BT_PRIVACY` is not enabled this parameter must
241 * be NULL.
242 *
243 * @return Identity identifier (>= 0) in case of success, or a negative
244 * error code on failure.
245 */
246 int bt_id_reset(u8_t id, bt_addr_le_t *addr, u8_t *irk);
247
248 /** @brief Delete an identity.
249 *
250 * When given a valid identity this function will disconnect any connections
251 * created using it, remove any pairing keys or other data associated with
252 * it, and then flag is as deleted, so that it can not be used for any
253 * operations. To take back into use the slot the identity was occupying the
254 * bt_id_reset() API needs to be used.
255 *
256 * @note the default identity (BT_ID_DEFAULT) cannot be deleted, i.e. this
257 * API will return an error if asked to do that.
258 *
259 * @param id Existing identity identifier.
260 *
261 * @return 0 in case of success, or a negative error code on failure.
262 */
263 int bt_id_delete(u8_t id);
264
265 /** @brief Bluetooth data.
266 *
267 * Description of different data types that can be encoded into
268 * advertising data. Used to form arrays that are passed to the
269 * bt_le_adv_start() function.
270 */
271 struct bt_data {
272 u8_t type;
273 u8_t data_len;
274 const u8_t *data;
275 };
276
277 /** @brief Helper to declare elements of bt_data arrays
278 *
279 * This macro is mainly for creating an array of struct bt_data
280 * elements which is then passed to e.g. @ref bt_le_adv_start().
281 *
282 * @param _type Type of advertising data field
283 * @param _data Pointer to the data field payload
284 * @param _data_len Number of bytes behind the _data pointer
285 */
286 #define BT_DATA(_type, _data, _data_len) \
287 { \
288 .type = (_type), \
289 .data_len = (_data_len), \
290 .data = (const u8_t *)(_data), \
291 }
292
293 /** @brief Helper to declare elements of bt_data arrays
294 *
295 * This macro is mainly for creating an array of struct bt_data
296 * elements which is then passed to e.g. @ref bt_le_adv_start().
297 *
298 * @param _type Type of advertising data field
299 * @param _bytes Variable number of single-byte parameters
300 */
301 #define BT_DATA_BYTES(_type, _bytes...) \
302 BT_DATA(_type, ((u8_t []) { _bytes }), \
303 sizeof((u8_t []) { _bytes }))
304
305 /** Advertising options */
306 enum {
307 /** Convenience value when no options are specified. */
308 BT_LE_ADV_OPT_NONE = 0,
309
310 /** @brief Advertise as connectable.
311 *
312 * Advertise as connectable. If not connectable then the type of
313 * advertising is determined by providing scan response data.
314 * The advertiser address is determined by the type of advertising
315 * and/or enabling privacy :option:`CONFIG_BT_PRIVACY`.
316 */
317 BT_LE_ADV_OPT_CONNECTABLE = BIT(0),
318
319 /** @brief Advertise one time.
320 *
321 * Don't try to resume connectable advertising after a connection.
322 * This option is only meaningful when used together with
323 * BT_LE_ADV_OPT_CONNECTABLE. If set the advertising will be stopped
324 * when bt_le_adv_stop() is called or when an incoming (slave)
325 * connection happens. If this option is not set the stack will
326 * take care of keeping advertising enabled even as connections
327 * occur.
328 * If Advertising directed or the advertiser was started with
329 * @ref bt_le_ext_adv_start then this behavior is the default behavior
330 * and this flag has no effect.
331 */
332 BT_LE_ADV_OPT_ONE_TIME = BIT(1),
333
334 /** @brief Advertise using identity address.
335 *
336 * Advertise using the identity address as the advertiser address.
337 * @warning This will compromise the privacy of the device, so care
338 * must be taken when using this option.
339 * @note The address used for advertising will not be the same as
340 * returned by @ref bt_le_oob_get_local, instead @ref bt_id_get
341 * should be used to get the LE address.
342 */
343 BT_LE_ADV_OPT_USE_IDENTITY = BIT(2),
344
345 /** Advertise using GAP device name */
346 BT_LE_ADV_OPT_USE_NAME = BIT(3),
347
348 /** @brief Low duty cycle directed advertising.
349 *
350 * Use low duty directed advertising mode, otherwise high duty mode
351 * will be used.
352 */
353 BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY = BIT(4),
354
355 /** @brief Directed advertising to privacy-enabled peer.
356 *
357 * Enable use of Resolvable Private Address (RPA) as the target address
358 * in directed advertisements when :option:`CONFIG_BT_PRIVACY` is not
359 * enabled.
360 * This is required if the remote device is privacy-enabled and
361 * supports address resolution of the target address in directed
362 * advertisement.
363 * It is the responsibility of the application to check that the remote
364 * device supports address resolution of directed advertisements by
365 * reading its Central Address Resolution characteristic.
366 */
367 BT_LE_ADV_OPT_DIR_ADDR_RPA = BIT(5),
368
369 /** Use whitelist to filter devices that can request scan response data.
370 */
371 BT_LE_ADV_OPT_FILTER_SCAN_REQ = BIT(6),
372
373 /** Use whitelist to filter devices that can connect. */
374 BT_LE_ADV_OPT_FILTER_CONN = BIT(7),
375
376 /** Notify the application when a scan response data has been sent to an
377 * active scanner.
378 */
379 BT_LE_ADV_OPT_NOTIFY_SCAN_REQ = BIT(8),
380
381 /** @brief Support scan response data.
382 *
383 * When used together with @ref BT_LE_ADV_OPT_EXT_ADV then this option
384 * cannot be used together with the @ref BT_LE_ADV_OPT_CONNECTABLE
385 * option.
386 * When used together with @ref BT_LE_ADV_OPT_EXT_ADV then scan
387 * response data must be set.
388 */
389 BT_LE_ADV_OPT_SCANNABLE = BIT(9),
390
391 /** @brief Advertise with extended advertising.
392 *
393 * This options enables extended advertising in the advertising set.
394 * In extended advertising the advertising set will send a small header
395 * packet on the three primary advertising channels. This small header
396 * points to the advertising data packet that will be sent on one of
397 * the 37 secondary advertising channels.
398 * The advertiser will send primary advertising on LE 1M PHY, and
399 * secondary advertising on LE 2M PHY.
400 * Connections will be established on LE 2M PHY.
401 *
402 * Without this option the advertiser will send advertising data on the
403 * three primary advertising channels.
404 *
405 * @note Enabling this option requires extended advertising support in
406 * the peer devices scanning for advertisement packets.
407 */
408 BT_LE_ADV_OPT_EXT_ADV = BIT(10),
409
410 /** @brief Disable use of LE 2M PHY on the secondary advertising
411 * channel.
412 *
413 * Disabling the use of LE 2M PHY could be necessary if scanners don't
414 * support the LE 2M PHY.
415 * The advertiser will send primary advertising on LE 1M PHY, and
416 * secondary advertising on LE 1M PHY.
417 * Connections will be established on LE 1M PHY.
418 *
419 * @note Cannot be set if BT_LE_ADV_OPT_CODED is set.
420 *
421 * @note Requires @ref BT_LE_ADV_OPT_EXT_ADV.
422 */
423 BT_LE_ADV_OPT_NO_2M = BIT(11),
424
425 /** @brief Advertise on the LE Coded PHY (Long Range).
426 *
427 * The advertiser will send both primary and secondary advertising
428 * on the LE Coded PHY. This gives the advertiser increased range with
429 * the trade-off of lower data rate and higher power consumption.
430 * Connections will be established on LE Coded PHY.
431 *
432 * @note Requires @ref BT_LE_ADV_OPT_EXT_ADV
433 */
434 BT_LE_ADV_OPT_CODED = BIT(12),
435
436 /** @brief Advertise without a device address (identity or RPA).
437 *
438 * @note Requires @ref BT_LE_ADV_OPT_EXT_ADV
439 */
440 BT_LE_ADV_OPT_ANONYMOUS = BIT(13),
441
442 /** @brief Advertise with transmit power.
443 *
444 * @note Requires @ref BT_LE_ADV_OPT_EXT_ADV
445 */
446 BT_LE_ADV_OPT_USE_TX_POWER = BIT(14),
447 };
448
449 /** LE Advertising Parameters. */
450 struct bt_le_adv_param {
451 /** @brief Local identity.
452 *
453 * @note When extended advertising :option:`CONFIG_BT_EXT_ADV` is not
454 * enabled or not supported by the controller it is not possible
455 * to scan and advertise simultaneously using two different
456 * random addresses.
457 *
458 * @note It is not possible to have multiple connectable advertising
459 * sets advertising simultaneously using different identities.
460 */
461 u8_t id;
462
463 /** @brief Advertising Set Identifier, valid range 0x00 - 0x0f.
464 *
465 * @note Requires @ref BT_LE_ADV_OPT_EXT_ADV
466 **/
467 u8_t sid;
468
469 /** @brief Secondary channel maximum skip count.
470 *
471 * Maximum advertising events the advertiser can skip before it must
472 * send advertising data on the secondary advertising channel.
473 *
474 * @note Requires @ref BT_LE_ADV_OPT_EXT_ADV
475 */
476 u8_t secondary_max_skip;
477
478 /** Bit-field of advertising options */
479 bt_u32_t options;
480
481 /** Minimum Advertising Interval (N * 0.625) */
482 bt_u32_t interval_min;
483
484 /** Maximum Advertising Interval (N * 0.625) */
485 bt_u32_t interval_max;
486
487 u8_t channel_map;
488 /** @brief Directed advertising to peer
489 *
490 * When this parameter is set the advertiser will send directed
491 * advertising to the remote device.
492 *
493 * The advertising type will either be high duty cycle, or low duty
494 * cycle if the BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY option is enabled.
495 *
496 * In case of connectable high duty cycle if the connection could not
497 * be established within the timeout the connected() callback will be
498 * called with the status set to @ref BT_HCI_ERR_ADV_TIMEOUT.
499 */
500 const bt_addr_le_t *peer;
501 };
502
503 /** @brief Initialize advertising parameters
504 *
505 * @param _options Advertising Options
506 * @param _int_min Minimum advertising interval
507 * @param _int_max Maximum advertising interval
508 * @param _peer Peer address, set to NULL for undirected advertising or
509 * address of peer for directed advertising.
510 */
511 #define BT_LE_ADV_PARAM_INIT(_options, _int_min, _int_max, _peer) \
512 { \
513 .id = BT_ID_DEFAULT, \
514 .sid = 0, \
515 .secondary_max_skip = 0, \
516 .options = (_options), \
517 .interval_min = (_int_min), \
518 .interval_max = (_int_max), \
519 .peer = (_peer), \
520 }
521
522 /** @brief Helper to declare advertising parameters inline
523 *
524 * @param _options Advertising Options
525 * @param _int_min Minimum advertising interval
526 * @param _int_max Maximum advertising interval
527 * @param _peer Peer address, set to NULL for undirected advertising or
528 * address of peer for directed advertising.
529 */
530 #define BT_LE_ADV_PARAM(_options, _int_min, _int_max, _peer) \
531 ((struct bt_le_adv_param[]) { \
532 BT_LE_ADV_PARAM_INIT(_options, _int_min, _int_max, _peer) \
533 })
534
535 #define BT_LE_ADV_CONN_DIR(_peer) BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONNECTABLE | \
536 BT_LE_ADV_OPT_ONE_TIME, 0, 0,\
537 _peer)
538
539
540 #define BT_LE_ADV_CONN BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONNECTABLE, \
541 BT_GAP_ADV_FAST_INT_MIN_2, \
542 BT_GAP_ADV_FAST_INT_MAX_2, NULL)
543
544 #define BT_LE_ADV_CONN_NAME BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONNECTABLE | \
545 BT_LE_ADV_OPT_USE_NAME, \
546 BT_GAP_ADV_FAST_INT_MIN_2, \
547 BT_GAP_ADV_FAST_INT_MAX_2, NULL)
548
549 #define BT_LE_ADV_CONN_DIR_LOW_DUTY(_peer) \
550 BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONNECTABLE | BT_LE_ADV_OPT_ONE_TIME | \
551 BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY, \
552 BT_GAP_ADV_FAST_INT_MIN_2, BT_GAP_ADV_FAST_INT_MAX_2, \
553 _peer)
554
555 #define BT_LE_ADV_NCONN BT_LE_ADV_PARAM(0, BT_GAP_ADV_FAST_INT_MIN_2, \
556 BT_GAP_ADV_FAST_INT_MAX_2, NULL)
557
558 #define BT_LE_ADV_NCONN_NAME BT_LE_ADV_PARAM(BT_LE_ADV_OPT_USE_NAME, \
559 BT_GAP_ADV_FAST_INT_MIN_2, \
560 BT_GAP_ADV_FAST_INT_MAX_2, NULL)
561
562 /** @brief Start advertising
563 *
564 * Set advertisement data, scan response data, advertisement parameters
565 * and start advertising.
566 *
567 * When the advertisement parameter peer address has been set the advertising
568 * will be directed to the peer. In this case advertisement data and scan
569 * response data parameters are ignored. If the mode is high duty cycle
570 * the timeout will be @ref BT_GAP_ADV_HIGH_DUTY_CYCLE_MAX_TIMEOUT.
571 *
572 * @param param Advertising parameters.
573 * @param ad Data to be used in advertisement packets.
574 * @param ad_len Number of elements in ad
575 * @param sd Data to be used in scan response packets.
576 * @param sd_len Number of elements in sd
577 *
578 * @return Zero on success or (negative) error code otherwise.
579 * @return -ENOMEM No free connection objects available for connectable
580 * advertiser.
581 * @return -ECONNREFUSED When connectable advertising is requested and there
582 * is already maximum number of connections established
583 * in the controller.
584 * This error code is only guaranteed when using Zephyr
585 * controller, for other controllers code returned in
586 * this case may be -EIO.
587 */
588 int bt_le_adv_start(const struct bt_le_adv_param *param,
589 const struct bt_data *ad, size_t ad_len,
590 const struct bt_data *sd, size_t sd_len);
591
592 /** @brief Update advertising
593 *
594 * Update advertisement and scan response data.
595 *
596 * @param ad Data to be used in advertisement packets.
597 * @param ad_len Number of elements in ad
598 * @param sd Data to be used in scan response packets.
599 * @param sd_len Number of elements in sd
600 *
601 * @return Zero on success or (negative) error code otherwise.
602 */
603 int bt_le_adv_update_data(const struct bt_data *ad, size_t ad_len,
604 const struct bt_data *sd, size_t sd_len);
605
606 /** @brief Stop advertising
607 *
608 * Stops ongoing advertising.
609 *
610 * @return Zero on success or (negative) error code otherwise.
611 */
612 int bt_le_adv_stop(void);
613
614 /** @brief Create advertising set.
615 *
616 * Create a new advertising set and set advertising parameters.
617 * Advertising parameters can be updated with @ref bt_le_ext_adv_update_param.
618 *
619 * @param[in] param Advertising parameters.
620 * @param[in] cb Callback struct to notify about advertiser activity. Can be
621 * NULL. Must point to valid memory during the lifetime of the
622 * advertising set.
623 * @param[out] adv Valid advertising set object on success.
624 *
625 * @return Zero on success or (negative) error code otherwise.
626 */
627 int bt_le_ext_adv_create(const struct bt_le_adv_param *param,
628 const struct bt_le_ext_adv_cb *cb,
629 struct bt_le_ext_adv **adv);
630
631 struct bt_le_ext_adv_start_param {
632 /** @brief Advertiser timeout (N * 10 ms).
633 *
634 * Application will be notified by the advertiser sent callback.
635 * Set to zero for no timeout.
636 *
637 * When using high duty cycle directed connectable advertising then
638 * this parameters must be set to a non-zero value less than or equal
639 * to the maximum of @ref BT_GAP_ADV_HIGH_DUTY_CYCLE_MAX_TIMEOUT.
640 *
641 * If privacy :option:`CONFIG_BT_PRIVACY` is enabled then the timeout
642 * must be less than :option:`CONFIG_BT_RPA_TIMEOUT`.
643 */
644 u16_t timeout;
645 /** @brief Number of advertising events.
646 *
647 * Application will be notified by the advertiser sent callback.
648 * Set to zero for no limit.
649 */
650 u8_t num_events;
651 };
652
653 /** @brief Start advertising with the given advertising set
654 *
655 * If the advertiser is limited by either the timeout or number of advertising
656 * events the application will be notified by the advertiser sent callback once
657 * the limit is reached.
658 * If the advertiser is limited by both the timeout and the number of
659 * advertising events then the limit that is reached first will stop the
660 * advertiser.
661 *
662 * @param adv Advertising set object.
663 * @param param Advertise start parameters.
664 */
665 int bt_le_ext_adv_start(struct bt_le_ext_adv *adv,
666 struct bt_le_ext_adv_start_param *param);
667
668 /** @brief Stop advertising with the given advertising set
669 *
670 * Stop advertising with a specific advertising set. When using this function
671 * the advertising sent callback will not be called.
672 *
673 * @param adv Advertising set object.
674 *
675 * @return Zero on success or (negative) error code otherwise.
676 */
677 int bt_le_ext_adv_stop(struct bt_le_ext_adv *adv);
678
679 /** @brief Set an advertising set's advertising or scan response data.
680 *
681 * Set advertisement data or scan response data. If the advertising set is
682 * currently advertising then the advertising data will be updated in
683 * subsequent advertising events.
684 *
685 * If the advertising set has been configured to send advertising data on the
686 * primary advertising channels then the maximum data length is
687 * @ref BT_GAP_ADV_MAX_ADV_DATA_LEN bytes.
688 * If the advertising set has been configured for extended advertising,
689 * then the maximum data length is defined by the controller with the maximum
690 * possible of @ref BT_GAP_ADV_MAX_EXT_ADV_DATA_LEN bytes.
691 *
692 * @note Not all scanners support extended data length advertising data.
693 *
694 * @note When updating the advertising data while advertising the advertising
695 * data and scan response data length must be smaller or equal to what
696 * can be fit in a single advertising packet. Otherwise the
697 * advertiser must be stopped.
698 *
699 * @param adv Advertising set object.
700 * @param ad Data to be used in advertisement packets.
701 * @param ad_len Number of elements in ad
702 * @param sd Data to be used in scan response packets.
703 * @param sd_len Number of elements in sd
704 *
705 * @return Zero on success or (negative) error code otherwise.
706 */
707 int bt_le_ext_adv_set_data(struct bt_le_ext_adv *adv,
708 const struct bt_data *ad, size_t ad_len,
709 const struct bt_data *sd, size_t sd_len);
710
711 /** @brief Update advertising parameters.
712 *
713 * Update the advertising parameters. The function will return an error if the
714 * advertiser set is currently advertising. Stop the advertising set before
715 * calling this function.
716 *
717 * @param adv Advertising set object.
718 * @param param Advertising parameters.
719 *
720 * @return Zero on success or (negative) error code otherwise.
721 */
722 int bt_le_ext_adv_update_param(struct bt_le_ext_adv *adv,
723 const struct bt_le_adv_param *param);
724
725 /** @brief Delete advertising set.
726 *
727 * Delete advertising set. This will free up the advertising set and make it
728 * possible to create a new advertising set.
729 *
730 * @return Zero on success or (negative) error code otherwise.
731 */
732 int bt_le_ext_adv_delete(struct bt_le_ext_adv *adv);
733
734 /** @brief Get array index of an advertising set.
735 *
736 * This function is used to map bt_adv to index of an array of
737 * advertising sets. The array has CONFIG_BT_EXT_ADV_MAX_ADV_SET elements.
738 *
739 * @param adv Advertising set.
740 *
741 * @return Index of the advertising set object.
742 * The range of the returned value is 0..CONFIG_BT_EXT_ADV_MAX_ADV_SET-1
743 */
744 u8_t bt_le_ext_adv_get_index(struct bt_le_ext_adv *adv);
745
746 /** @brief Advertising set info structure. */
747 struct bt_le_ext_adv_info {
748 /* Local identity */
749 u8_t id;
750
751 /** Currently selected Transmit Power (dBM). */
752 s8_t tx_power;
753 };
754
755 /** @brief Get advertising set info
756 *
757 * @param adv Advertising set object
758 * @param info Advertising set info object
759 *
760 * @return Zero on success or (negative) error code on failure.
761 */
762 int bt_le_ext_adv_get_info(const struct bt_le_ext_adv *adv,
763 struct bt_le_ext_adv_info *info);
764
765 /** @typedef bt_le_scan_cb_t
766 * @brief Callback type for reporting LE scan results.
767 *
768 * A function of this type is given to the bt_le_scan_start() function
769 * and will be called for any discovered LE device.
770 *
771 * @param addr Advertiser LE address and type.
772 * @param rssi Strength of advertiser signal.
773 * @param adv_type Type of advertising response from advertiser.
774 * @param buf Buffer containing advertiser data.
775 */
776 typedef void bt_le_scan_cb_t(const bt_addr_le_t *addr, s8_t rssi,
777 u8_t adv_type, struct net_buf_simple *buf);
778
779 enum {
780 /** Convenience value when no options are specified. */
781 BT_LE_SCAN_OPT_NONE = 0,
782
783 /** Filter duplicates. */
784 BT_LE_SCAN_OPT_FILTER_DUPLICATE = BIT(0),
785
786 /** Filter using whitelist. */
787 BT_LE_SCAN_OPT_FILTER_WHITELIST = BIT(1),
788
789 /** Enable scan on coded PHY (Long Range).*/
790 BT_LE_SCAN_OPT_CODED = BIT(2),
791
792 /** @brief Disable scan on 1M phy.
793 *
794 * @note Requires @ref BT_LE_SCAN_OPT_CODED.
795 */
796 BT_LE_SCAN_OPT_NO_1M = BIT(3),
797
798 BT_LE_SCAN_FILTER_DUPLICATE =
799 BT_LE_SCAN_OPT_FILTER_DUPLICATE, // __deprecated
800 BT_LE_SCAN_FILTER_WHITELIST =
801 BT_LE_SCAN_OPT_FILTER_WHITELIST, // __deprecated
802 };
803
804 enum {
805 /** Scan without requesting additional information from advertisers. */
806 BT_LE_SCAN_TYPE_PASSIVE = 0x00,
807
808 /** Scan and request additional information from advertisers. */
809 BT_LE_SCAN_TYPE_ACTIVE = 0x01,
810 };
811
812 /** LE scan parameters */
813 struct bt_le_scan_param {
814 /** Scan type (BT_LE_SCAN_TYPE_ACTIVE or BT_LE_SCAN_TYPE_PASSIVE) */
815 u8_t type;
816
817 union {
818 /** Bit-field of scanning filter options. */
819 bt_u32_t filter_dup; // __deprecated
820
821 /** Bit-field of scanning options. */
822 bt_u32_t options;
823 };
824
825 /** Scan interval (N * 0.625 ms) */
826 u16_t interval;
827
828 /** Scan window (N * 0.625 ms) */
829 u16_t window;
830
831 /** @brief Scan timeout (N * 10 ms)
832 *
833 * Application will be notified by the scan timeout callback.
834 * Set zero to disable timeout.
835 */
836 u16_t timeout;
837
838 /** @brief Scan interval LE Coded PHY (N * 0.625 MS)
839 *
840 * Set zero to use same as LE 1M PHY scan interval.
841 */
842 u16_t interval_coded;
843
844 /** @brief Scan window LE Coded PHY (N * 0.625 MS)
845 *
846 * Set zero to use same as LE 1M PHY scan window.
847 */
848 u16_t window_coded;
849 };
850
851 /** LE advertisement packet information */
852 struct bt_le_scan_recv_info {
853 /** @brief Advertiser LE address and type.
854 *
855 * If advertiser is anonymous then this address will be
856 * @ref BT_ADDR_LE_ANY.
857 */
858 const bt_addr_le_t *addr;
859
860 /** Advertising Set Identifier. */
861 u8_t sid;
862
863 /** Strength of advertiser signal. */
864 s8_t rssi;
865
866 /** Transmit power of the advertiser. */
867 s8_t tx_power;
868
869 /** Advertising packet type. */
870 u8_t adv_type;
871
872 /** Advertising packet properties. */
873 u16_t adv_props;
874
875 /** Primary advertising channel PHY. */
876 u8_t primary_phy;
877
878 /** Secondary advertising channel PHY. */
879 u8_t secondary_phy;
880 };
881
882 /** Listener context for (LE) scanning. */
883 struct bt_le_scan_cb {
884
885 /** @brief Advertisement packet received callback.
886 *
887 * @param info Advertiser packet information.
888 * @param buf Buffer containing advertiser data.
889 */
890 void (*recv)(const struct bt_le_scan_recv_info *info,
891 struct net_buf_simple *buf);
892
893 /** @brief The scanner has stopped scanning after scan timeout. */
894 void (*timeout)(void);
895
896 sys_snode_t node;
897 };
898
899 /** @brief Initialize scan parameters
900 *
901 * @param _type Scan Type, BT_LE_SCAN_TYPE_ACTIVE or
902 * BT_LE_SCAN_TYPE_PASSIVE.
903 * @param _options Scan options
904 * @param _interval Scan Interval (N * 0.625 ms)
905 * @param _window Scan Window (N * 0.625 ms)
906 */
907 #define BT_LE_SCAN_PARAM_INIT(_type, _options, _interval, _window) \
908 { \
909 .type = (_type), \
910 .options = (_options), \
911 .interval = (_interval), \
912 .window = (_window), \
913 .timeout = 0, \
914 .interval_coded = 0, \
915 .window_coded = 0, \
916 }
917
918 /** @brief Helper to declare scan parameters inline
919 *
920 * @param _type Scan Type, BT_LE_SCAN_TYPE_ACTIVE or
921 * BT_LE_SCAN_TYPE_PASSIVE.
922 * @param _options Scan options
923 * @param _interval Scan Interval (N * 0.625 ms)
924 * @param _window Scan Window (N * 0.625 ms)
925 */
926 #define BT_LE_SCAN_PARAM(_type, _options, _interval, _window) \
927 ((struct bt_le_scan_param[]) { \
928 BT_LE_SCAN_PARAM_INIT(_type, _options, _interval, _window) \
929 })
930
931 /** Helper macro to enable active scanning to discover new devices. */
932 #define BT_LE_SCAN_ACTIVE BT_LE_SCAN_PARAM(BT_LE_SCAN_TYPE_ACTIVE, \
933 BT_LE_SCAN_OPT_FILTER_DUPLICATE, \
934 BT_GAP_SCAN_FAST_INTERVAL, \
935 BT_GAP_SCAN_FAST_WINDOW)
936
937 /** @brief Helper macro to enable passive scanning to discover new devices.
938 *
939 * This macro should be used if information required for device identification
940 * (e.g., UUID) are known to be placed in Advertising Data.
941 */
942 #define BT_LE_SCAN_PASSIVE BT_LE_SCAN_PARAM(BT_LE_SCAN_TYPE_PASSIVE, \
943 BT_LE_SCAN_OPT_FILTER_DUPLICATE, \
944 BT_GAP_SCAN_FAST_INTERVAL, \
945 BT_GAP_SCAN_FAST_WINDOW)
946
947 /** @brief Start (LE) scanning
948 *
949 * Start LE scanning with given parameters and provide results through
950 * the specified callback.
951 *
952 * @note The LE scanner by default does not use the Identity Address of the
953 * local device when :option:`CONFIG_BT_PRIVACY` is disabled. This is to
954 * prevent the active scanner from disclosing the identity information
955 * when requesting additional information from advertisers.
956 * In order to enable directed advertiser reports then
957 * :option:`CONFIG_BT_SCAN_WITH_IDENTITY` must be enabled.
958 *
959 * @param param Scan parameters.
960 * @param cb Callback to notify scan results. May be NULL if callback
961 * registration through @ref bt_le_scan_cb_register is preferred.
962 *
963 * @return Zero on success or error code otherwise, positive in case of
964 * protocol error or negative (POSIX) in case of stack internal error.
965 */
966 int bt_le_scan_start(const struct bt_le_scan_param *param, bt_le_scan_cb_t cb);
967
968 /** @brief Stop (LE) scanning.
969 *
970 * Stops ongoing LE scanning.
971 *
972 * @return Zero on success or error code otherwise, positive in case of
973 * protocol error or negative (POSIX) in case of stack internal error.
974 */
975 int bt_le_scan_stop(void);
976
977 /** @brief Register scanner packet callbacks.
978 *
979 * Adds the callback structure to the list of callback structures that monitors
980 * scanner activity.
981 *
982 * This callback will be called for all scanner activity, regardless of what
983 * API was used to start the scanner.
984 *
985 * @param cb Callback struct. Must point to static memory.
986 */
987 void bt_le_scan_cb_register(struct bt_le_scan_cb *cb);
988
989 /** @brief Add device (LE) to whitelist.
990 *
991 * Add peer device LE address to the whitelist.
992 *
993 * @note The whitelist cannot be modified when an LE role is using
994 * the whitelist, i.e advertiser or scanner using a whitelist or automatic
995 * connecting to devices using whitelist.
996 *
997 * @param addr Bluetooth LE identity address.
998 *
999 * @return Zero on success or error code otherwise, positive in case of
1000 * protocol error or negative (POSIX) in case of stack internal error.
1001 */
1002 int bt_le_whitelist_add(const bt_addr_le_t *addr);
1003
1004 /** @brief Remove device (LE) from whitelist.
1005 *
1006 * Remove peer device LE address from the whitelist.
1007 *
1008 * @note The whitelist cannot be modified when an LE role is using
1009 * the whitelist, i.e advertiser or scanner using a whitelist or automatic
1010 * connecting to devices using whitelist.
1011 *
1012 * @param addr Bluetooth LE identity address.
1013 *
1014 * @return Zero on success or error code otherwise, positive in case of
1015 * protocol error or negative (POSIX) in case of stack internal error.
1016 */
1017 int bt_le_whitelist_rem(const bt_addr_le_t *addr);
1018
1019 /** @brief Clear whitelist.
1020 *
1021 * Clear all devices from the whitelist.
1022 *
1023 * @note The whitelist cannot be modified when an LE role is using
1024 * the whitelist, i.e advertiser or scanner using a whitelist or automatic
1025 * connecting to devices using whitelist.
1026 *
1027 * @return Zero on success or error code otherwise, positive in case of
1028 * protocol error or negative (POSIX) in case of stack internal error.
1029 */
1030 int bt_le_whitelist_clear(void);
1031
1032 int bt_le_whitelist_size(u8_t *size);
1033
1034 /** @brief Set (LE) channel map.
1035 *
1036 * @param chan_map Channel map.
1037 *
1038 * @return Zero on success or error code otherwise, positive in case of
1039 * protocol error or negative (POSIX) in case of stack internal error.
1040 */
1041 int bt_le_set_chan_map(u8_t chan_map[5]);
1042
1043 /** @brief Helper for parsing advertising (or EIR or OOB) data.
1044 *
1045 * A helper for parsing the basic data types used for Extended Inquiry
1046 * Response (EIR), Advertising Data (AD), and OOB data blocks. The most
1047 * common scenario is to call this helper on the advertising data
1048 * received in the callback that was given to bt_le_scan_start().
1049 *
1050 * @param ad Advertising data as given to the bt_le_scan_cb_t callback.
1051 * @param func Callback function which will be called for each element
1052 * that's found in the data. The callback should return
1053 * true to continue parsing, or false to stop parsing.
1054 * @param user_data User data to be passed to the callback.
1055 */
1056 void bt_data_parse(struct net_buf_simple *ad,
1057 bool (*func)(struct bt_data *data, void *user_data),
1058 void *user_data);
1059
1060 /** LE Secure Connections pairing Out of Band data. */
1061 struct bt_le_oob_sc_data {
1062 /** Random Number. */
1063 u8_t r[16];
1064
1065 /** Confirm Value. */
1066 u8_t c[16];
1067 };
1068
1069 /** LE Out of Band information. */
1070 struct bt_le_oob {
1071 /** LE address. If privacy is enabled this is a Resolvable Private
1072 * Address.
1073 */
1074 bt_addr_le_t addr;
1075
1076 /** LE Secure Connections pairing Out of Band data. */
1077 struct bt_le_oob_sc_data le_sc_data;
1078 };
1079
1080 /** @brief Get local LE Out of Band (OOB) information.
1081 *
1082 * This function allows to get local information that are useful for
1083 * Out of Band pairing or connection creation.
1084 *
1085 * If privacy :option:`CONFIG_BT_PRIVACY` is enabled this will result in
1086 * generating new Resolvable Private Address (RPA) that is valid for
1087 * :option:`CONFIG_BT_RPA_TIMEOUT` seconds. This address will be used for
1088 * advertising started by @ref bt_le_adv_start, active scanning and
1089 * connection creation.
1090 *
1091 * @note If privacy is enabled the RPA cannot be refreshed in the following
1092 * cases:
1093 * - Creating a connection in progress, wait for the connected callback.
1094 * In addition when extended advertising :option:`CONFIG_BT_EXT_ADV` is
1095 * not enabled or not supported by the controller:
1096 * - Advertiser is enabled using a Random Static Identity Address for a
1097 * different local identity.
1098 * - The local identity conflicts with the local identity used by other
1099 * roles.
1100 *
1101 * @param[in] id Local identity, in most cases BT_ID_DEFAULT.
1102 * @param[out] oob LE OOB information
1103 *
1104 * @return Zero on success or error code otherwise, positive in case of
1105 * protocol error or negative (POSIX) in case of stack internal error.
1106 */
1107 int bt_le_oob_get_local(u8_t id, struct bt_le_oob *oob);
1108
1109 /** @brief Get local LE Out of Band (OOB) information.
1110 *
1111 * This function allows to get local information that are useful for
1112 * Out of Band pairing or connection creation.
1113 *
1114 * If privacy :option:`CONFIG_BT_PRIVACY` is enabled this will result in
1115 * generating new Resolvable Private Address (RPA) that is valid for
1116 * :option:`CONFIG_BT_RPA_TIMEOUT` seconds. This address will be used by the
1117 * advertising set.
1118 *
1119 * @note When generating OOB information for multiple advertising set all
1120 * OOB information needs to be generated at the same time.
1121 *
1122 * @note If privacy is enabled the RPA cannot be refreshed in the following
1123 * cases:
1124 * - Creating a connection in progress, wait for the connected callback.
1125 *
1126 * @param[in] adv The advertising set object
1127 * @param[out] oob LE OOB information
1128 *
1129 * @return Zero on success or error code otherwise, positive in case
1130 * of protocol error or negative (POSIX) in case of stack internal error.
1131 */
1132 int bt_le_ext_adv_oob_get_local(struct bt_le_ext_adv *adv,
1133 struct bt_le_oob *oob);
1134
1135 /** @brief BR/EDR discovery result structure */
1136 struct bt_br_discovery_result {
1137 /** private */
1138 u8_t _priv[4];
1139
1140 /** Remote device address */
1141 bt_addr_t addr;
1142
1143 /** RSSI from inquiry */
1144 s8_t rssi;
1145
1146 /** Class of Device */
1147 u8_t cod[3];
1148
1149 /** Extended Inquiry Response */
1150 u8_t eir[240];
1151 };
1152
1153 /** @typedef bt_br_discovery_cb_t
1154 * @brief Callback type for reporting BR/EDR discovery (inquiry)
1155 * results.
1156 *
1157 * A callback of this type is given to the bt_br_discovery_start()
1158 * function and will be called at the end of the discovery with
1159 * information about found devices populated in the results array.
1160 *
1161 * @param results Storage used for discovery results
1162 * @param count Number of valid discovery results.
1163 */
1164 typedef void bt_br_discovery_cb_t(struct bt_br_discovery_result *results,
1165 size_t count);
1166
1167 /** BR/EDR discovery parameters */
1168 struct bt_br_discovery_param {
1169 /** Maximum length of the discovery in units of 1.28 seconds.
1170 * Valid range is 0x01 - 0x30.
1171 */
1172 u8_t length;
1173
1174 /** True if limited discovery procedure is to be used. */
1175 bool limited;
1176 };
1177
1178 /** @brief Start BR/EDR discovery
1179 *
1180 * Start BR/EDR discovery (inquiry) and provide results through the specified
1181 * callback. When bt_br_discovery_cb_t is called it indicates that discovery
1182 * has completed. If more inquiry results were received during session than
1183 * fits in provided result storage, only ones with highest RSSI will be
1184 * reported.
1185 *
1186 * @param param Discovery parameters.
1187 * @param results Storage for discovery results.
1188 * @param count Number of results in storage. Valid range: 1-255.
1189 * @param cb Callback to notify discovery results.
1190 *
1191 * @return Zero on success or error code otherwise, positive in case
1192 * of protocol error or negative (POSIX) in case of stack internal error
1193 */
1194 int bt_br_discovery_start(const struct bt_br_discovery_param *param,
1195 struct bt_br_discovery_result *results, size_t count,
1196 bt_br_discovery_cb_t cb);
1197
1198 /** @brief Stop BR/EDR discovery.
1199 *
1200 * Stops ongoing BR/EDR discovery. If discovery was stopped by this call
1201 * results won't be reported
1202 *
1203 * @return Zero on success or error code otherwise, positive in case of
1204 * protocol error or negative (POSIX) in case of stack internal error.
1205 */
1206 int bt_br_discovery_stop(void);
1207
1208 struct bt_br_oob {
1209 /** BR/EDR address. */
1210 bt_addr_t addr;
1211 };
1212
1213 /** @brief Get BR/EDR local Out Of Band information
1214 *
1215 * This function allows to get local controller information that are useful
1216 * for Out Of Band pairing or connection creation process.
1217 *
1218 * @param oob Out Of Band information
1219 */
1220 int bt_br_oob_get_local(struct bt_br_oob *oob);
1221
1222 /** @def BT_ADDR_STR_LEN
1223 *
1224 * @brief Recommended length of user string buffer for Bluetooth address
1225 *
1226 * @details The recommended length guarantee the output of address
1227 * conversion will not lose valuable information about address being
1228 * processed.
1229 */
1230 #define BT_ADDR_STR_LEN 18
1231
1232 /** @def BT_ADDR_LE_STR_LEN
1233 *
1234 * @brief Recommended length of user string buffer for Bluetooth LE address
1235 *
1236 * @details The recommended length guarantee the output of address
1237 * conversion will not lose valuable information about address being
1238 * processed.
1239 */
1240 #define BT_ADDR_LE_STR_LEN 30
1241
1242 /** @brief Converts binary Bluetooth address to string.
1243 *
1244 * @param addr Address of buffer containing binary Bluetooth address.
1245 * @param str Address of user buffer with enough room to store formatted
1246 * string containing binary address.
1247 * @param len Length of data to be copied to user string buffer. Refer to
1248 * BT_ADDR_STR_LEN about recommended value.
1249 *
1250 * @return Number of successfully formatted bytes from binary address.
1251 */
bt_addr_to_str(const bt_addr_t * addr,char * str,size_t len)1252 static inline int bt_addr_to_str(const bt_addr_t *addr, char *str, size_t len)
1253 {
1254 return snprintf(str, len, "%02X:%02X:%02X:%02X:%02X:%02X",
1255 addr->val[5], addr->val[4], addr->val[3],
1256 addr->val[2], addr->val[1], addr->val[0]);
1257 }
1258
1259 /** @brief Converts binary LE Bluetooth address to string.
1260 *
1261 * @param addr Address of buffer containing binary LE Bluetooth address.
1262 * @param str Address of user buffer with enough room to store
1263 * formatted string containing binary LE address.
1264 * @param len Length of data to be copied to user string buffer. Refer to
1265 * BT_ADDR_LE_STR_LEN about recommended value.
1266 *
1267 * @return Number of successfully formatted bytes from binary address.
1268 */
bt_addr_le_to_str(const bt_addr_le_t * addr,char * str,size_t len)1269 static inline int bt_addr_le_to_str(const bt_addr_le_t *addr, char *str,
1270 size_t len)
1271 {
1272 char type[10];
1273
1274 switch (addr->type) {
1275 case BT_ADDR_LE_PUBLIC:
1276 strcpy(type, "public");
1277 break;
1278 case BT_ADDR_LE_RANDOM:
1279 strcpy(type, "random");
1280 break;
1281 case BT_ADDR_LE_PUBLIC_ID:
1282 strcpy(type, "public-id");
1283 break;
1284 case BT_ADDR_LE_RANDOM_ID:
1285 strcpy(type, "random-id");
1286 break;
1287 default:
1288 snprintf(type, sizeof(type), "0x%02x", addr->type);
1289 break;
1290 }
1291
1292 return snprintf(str, len, "%02X:%02X:%02X:%02X:%02X:%02X (%s)",
1293 addr->a.val[5], addr->a.val[4], addr->a.val[3],
1294 addr->a.val[2], addr->a.val[1], addr->a.val[0], type);
1295 }
1296
1297 /** @brief Convert Bluetooth address from string to binary.
1298 *
1299 * @param[in] str The string representation of a Bluetooth address.
1300 * @param[out] addr Address of buffer to store the Bluetooth address
1301 *
1302 * @return Zero on success or (negative) error code otherwise.
1303 */
1304 int bt_addr_from_str(const char *str, bt_addr_t *addr);
1305
1306 /** @brief Convert LE Bluetooth address from string to binary.
1307 *
1308 * @param[in] str The string representation of an LE Bluetooth address.
1309 * @param[in] type The string representation of the LE Bluetooth address
1310 * type.
1311 * @param[out] addr Address of buffer to store the LE Bluetooth address
1312 *
1313 * @return Zero on success or (negative) error code otherwise.
1314 */
1315 int bt_addr_le_from_str(const char *str, const char *type, bt_addr_le_t *addr);
1316
1317 /** @brief Enable/disable set controller in discoverable state.
1318 *
1319 * Allows make local controller to listen on INQUIRY SCAN channel and responds
1320 * to devices making general inquiry. To enable this state it's mandatory
1321 * to first be in connectable state.
1322 *
1323 * @param enable Value allowing/disallowing controller to become discoverable.
1324 *
1325 * @return Negative if fail set to requested state or requested state has been
1326 * already set. Zero if done successfully.
1327 */
1328 int bt_br_set_discoverable(bool enable);
1329
1330 /** @brief Enable/disable set controller in connectable state.
1331 *
1332 * Allows make local controller to be connectable. It means the controller
1333 * start listen to devices requests on PAGE SCAN channel. If disabled also
1334 * resets discoverability if was set.
1335 *
1336 * @param enable Value allowing/disallowing controller to be connectable.
1337 *
1338 * @return Negative if fail set to requested state or requested state has been
1339 * already set. Zero if done successfully.
1340 */
1341 int bt_br_set_connectable(bool enable);
1342
1343 /** @brief Clear pairing information.
1344 *
1345 * @param id Local identity (mostly just BT_ID_DEFAULT).
1346 * @param addr Remote address, NULL or BT_ADDR_LE_ANY to clear all remote
1347 * devices.
1348 *
1349 * @return 0 on success or negative error value on failure.
1350 */
1351 int bt_unpair(u8_t id, const bt_addr_le_t *addr);
1352
1353 /** Information about a bond with a remote device. */
1354 struct bt_bond_info {
1355 /** Address of the remote device. */
1356 bt_addr_le_t addr;
1357 };
1358
1359 /** @brief Iterate through all existing bonds.
1360 *
1361 * @param id Local identity (mostly just BT_ID_DEFAULT).
1362 * @param func Function to call for each bond.
1363 * @param user_data Data to pass to the callback function.
1364 */
1365 void bt_foreach_bond(u8_t id, void (*func)(const struct bt_bond_info *info,
1366 void *user_data),
1367 void *user_data);
1368
1369 /**
1370 * @}
1371 */
1372
1373 #ifdef __cplusplus
1374 }
1375 #endif
1376 /**
1377 * @}
1378 */
1379
1380 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_BLUETOOTH_H_ */
1381