2015-07-01 22:47:13 +02:00
|
|
|
/** @file
|
2015-06-16 16:38:26 +02:00
|
|
|
* @brief Bluetooth subsystem core APIs.
|
|
|
|
*/
|
2015-04-14 13:38:13 +02:00
|
|
|
|
|
|
|
/*
|
2017-03-15 11:19:27 +01:00
|
|
|
* Copyright (c) 2017 Nordic Semiconductor ASA
|
2016-06-10 11:10:18 +02:00
|
|
|
* Copyright (c) 2015-2016 Intel Corporation
|
2015-04-14 13:38:13 +02:00
|
|
|
*
|
2017-01-19 02:01:01 +01:00
|
|
|
* SPDX-License-Identifier: Apache-2.0
|
2015-04-14 13:38:13 +02:00
|
|
|
*/
|
2018-09-14 19:43:44 +02:00
|
|
|
#ifndef ZEPHYR_INCLUDE_BLUETOOTH_BLUETOOTH_H_
|
|
|
|
#define ZEPHYR_INCLUDE_BLUETOOTH_BLUETOOTH_H_
|
2015-04-14 13:38:13 +02:00
|
|
|
|
2016-05-16 18:54:24 +02:00
|
|
|
/**
|
|
|
|
* @brief Bluetooth APIs
|
|
|
|
* @defgroup bluetooth Bluetooth APIs
|
|
|
|
* @{
|
|
|
|
*/
|
|
|
|
|
2015-07-23 11:35:59 +02:00
|
|
|
#include <stdbool.h>
|
2015-06-17 15:46:38 +02:00
|
|
|
#include <string.h>
|
2019-06-26 16:33:49 +02:00
|
|
|
#include <sys/printk.h>
|
2019-06-26 16:33:55 +02:00
|
|
|
#include <sys/util.h>
|
2016-07-19 12:58:02 +02:00
|
|
|
#include <net/buf.h>
|
2019-10-16 12:00:16 +02:00
|
|
|
#include <bluetooth/gap.h>
|
2019-10-16 12:09:26 +02:00
|
|
|
#include <bluetooth/addr.h>
|
2017-03-16 09:50:04 +01:00
|
|
|
#include <bluetooth/crypto.h>
|
2015-04-14 14:04:46 +02:00
|
|
|
|
2016-01-22 18:38:49 +01:00
|
|
|
#ifdef __cplusplus
|
|
|
|
extern "C" {
|
|
|
|
#endif
|
|
|
|
|
2019-01-27 19:05:13 +01:00
|
|
|
/**
|
|
|
|
* @brief Generic Access Profile
|
|
|
|
* @defgroup bt_gap Generic Access Profile
|
|
|
|
* @ingroup bluetooth
|
|
|
|
* @{
|
|
|
|
*/
|
|
|
|
|
2018-07-04 11:58:10 +02:00
|
|
|
/** @def BT_ID_DEFAULT
|
|
|
|
*
|
|
|
|
* Convenience macro for specifying the default identity. This helps
|
|
|
|
* make the code more readable, especially when only one identity is
|
|
|
|
* supported.
|
|
|
|
*/
|
|
|
|
#define BT_ID_DEFAULT 0
|
|
|
|
|
2020-02-01 18:27:39 +01:00
|
|
|
/** Opaque type representing an advertiser. */
|
|
|
|
struct bt_le_ext_adv;
|
|
|
|
|
|
|
|
/* Don't require everyone to include conn.h */
|
|
|
|
struct bt_conn;
|
|
|
|
|
|
|
|
struct bt_le_ext_adv_sent_info {
|
|
|
|
/** The number of advertising events completed. */
|
2020-05-27 18:26:57 +02:00
|
|
|
uint8_t num_sent;
|
2020-02-01 18:27:39 +01:00
|
|
|
};
|
|
|
|
|
|
|
|
struct bt_le_ext_adv_connected_info {
|
|
|
|
/** Connection object of the new connection */
|
|
|
|
struct bt_conn *conn;
|
|
|
|
};
|
|
|
|
|
|
|
|
struct bt_le_ext_adv_scanned_info {
|
|
|
|
/** Active scanner LE address and type */
|
|
|
|
bt_addr_le_t *addr;
|
|
|
|
};
|
|
|
|
|
|
|
|
struct bt_le_ext_adv_cb {
|
|
|
|
/** @brief The advertising set has finished sending adv data.
|
|
|
|
*
|
|
|
|
* This callback notifies the application that the advertising set has
|
|
|
|
* finished sending advertising data.
|
|
|
|
* The advertising set can either have been stopped by a timeout or
|
|
|
|
* because the specified number of advertising events has been reached.
|
|
|
|
*
|
|
|
|
* @param adv The advertising set object.
|
|
|
|
* @param info Information about the sent event.
|
|
|
|
*/
|
|
|
|
void (*sent)(struct bt_le_ext_adv *adv,
|
|
|
|
struct bt_le_ext_adv_sent_info *info);
|
|
|
|
|
|
|
|
/** @brief The advertising set has accepted a new connection.
|
|
|
|
*
|
|
|
|
* This callback notifies the application that the advertising set has
|
|
|
|
* accepted a new connection.
|
|
|
|
*
|
|
|
|
* @param adv The advertising set object.
|
|
|
|
* @param info Information about the connected event.
|
|
|
|
*/
|
|
|
|
void (*connected)(struct bt_le_ext_adv *adv,
|
|
|
|
struct bt_le_ext_adv_connected_info *info);
|
|
|
|
|
|
|
|
/** @brief The advertising set has sent scan response data.
|
|
|
|
*
|
|
|
|
* This callback notifies the application that the advertising set has
|
|
|
|
* has received a Scan Request packet, and has sent a Scan Response
|
|
|
|
* packet.
|
|
|
|
*
|
|
|
|
* @param adv The advertising set object.
|
|
|
|
* @param addr Information about the scanned event.
|
|
|
|
*/
|
|
|
|
void (*scanned)(struct bt_le_ext_adv *adv,
|
|
|
|
struct bt_le_ext_adv_scanned_info *info);
|
|
|
|
};
|
|
|
|
|
2020-03-17 10:32:20 +01:00
|
|
|
/** @typedef bt_ready_cb_t
|
|
|
|
* @brief Callback for notifying that Bluetooth has been enabled.
|
2015-06-12 13:25:28 +02:00
|
|
|
*
|
2015-07-28 17:23:19 +02:00
|
|
|
* @param err zero on success or (negative) error code otherwise.
|
|
|
|
*/
|
|
|
|
typedef void (*bt_ready_cb_t)(int err);
|
|
|
|
|
|
|
|
/** @brief Enable Bluetooth
|
|
|
|
*
|
|
|
|
* Enable Bluetooth. Must be the called before any calls that
|
|
|
|
* require communication with the local Bluetooth hardware.
|
|
|
|
*
|
|
|
|
* @param cb Callback to notify completion or NULL to perform the
|
|
|
|
* enabling synchronously.
|
2015-06-12 13:25:28 +02:00
|
|
|
*
|
2015-06-18 09:43:23 +02:00
|
|
|
* @return Zero on success or (negative) error code otherwise.
|
2015-06-12 13:25:28 +02:00
|
|
|
*/
|
2015-07-28 17:23:19 +02:00
|
|
|
int bt_enable(bt_ready_cb_t cb);
|
2015-04-14 13:38:13 +02:00
|
|
|
|
2018-07-09 14:12:04 +02:00
|
|
|
/** @brief Set Bluetooth Device Name
|
|
|
|
*
|
|
|
|
* Set Bluetooth GAP Device Name.
|
|
|
|
*
|
|
|
|
* @param name New name
|
|
|
|
*
|
|
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
|
|
*/
|
|
|
|
int bt_set_name(const char *name);
|
|
|
|
|
|
|
|
/** @brief Get Bluetooth Device Name
|
|
|
|
*
|
|
|
|
* Get Bluetooth GAP Device Name.
|
|
|
|
*
|
|
|
|
* @return Bluetooth Device Name
|
|
|
|
*/
|
|
|
|
const char *bt_get_name(void);
|
|
|
|
|
2018-05-10 16:25:25 +02:00
|
|
|
/** @brief Set the local Identity Address
|
|
|
|
*
|
|
|
|
* Allows setting the local Identity Address from the application.
|
|
|
|
* This API must be called before calling bt_enable(). Calling it at any
|
|
|
|
* other time will cause it to fail. In most cases the application doesn't
|
|
|
|
* need to use this API, however there are a few valid cases where
|
|
|
|
* it can be useful (such as for testing).
|
|
|
|
*
|
|
|
|
* At the moment, the given address must be a static random address. In the
|
|
|
|
* future support for public addresses may be added.
|
|
|
|
*
|
|
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
|
|
*/
|
|
|
|
int bt_set_id_addr(const bt_addr_le_t *addr);
|
|
|
|
|
2018-07-13 11:04:39 +02:00
|
|
|
/** @brief Get the currently configured identities.
|
|
|
|
*
|
|
|
|
* Returns an array of the currently configured identity addresses. To
|
|
|
|
* make sure all available identities can be retrieved, the number of
|
|
|
|
* elements in the @a addrs array should be CONFIG_BT_ID_MAX. The identity
|
|
|
|
* identifier that some APIs expect (such as advertising parameters) is
|
|
|
|
* simply the index of the identity in the @a addrs array.
|
|
|
|
*
|
2020-03-17 10:32:20 +01:00
|
|
|
* @note Deleted identities may show up as BT_LE_ADDR_ANY in the returned
|
2018-08-02 10:25:57 +02:00
|
|
|
* array.
|
|
|
|
*
|
2018-07-13 11:04:39 +02:00
|
|
|
* @param addrs Array where to store the configured identities.
|
|
|
|
* @param count Should be initialized to the array size. Once the function
|
2018-08-28 18:50:56 +02:00
|
|
|
* returns it will contain the number of returned identities.
|
2018-07-13 11:04:39 +02:00
|
|
|
*/
|
|
|
|
void bt_id_get(bt_addr_le_t *addrs, size_t *count);
|
|
|
|
|
|
|
|
/** @brief Create a new identity.
|
|
|
|
*
|
|
|
|
* Create a new identity using the given address and IRK. This function
|
|
|
|
* can be called before calling bt_enable(), in which case it can be used
|
|
|
|
* to override the controller's public address (in case it has one). However,
|
|
|
|
* the new identity will only be stored persistently in flash when this API
|
|
|
|
* is used after bt_enable(). The reason is that the persistent settings
|
|
|
|
* are loaded after bt_enable() and would therefore cause potential conflicts
|
|
|
|
* with the stack blindly overwriting what's stored in flash. The identity
|
|
|
|
* will also not be written to flash in case a pre-defined address is
|
|
|
|
* provided, since in such a situation the app clearly has some place it got
|
|
|
|
* the address from and will be able to repeat the procedure on every power
|
|
|
|
* cycle, i.e. it would be redundant to also store the information in flash.
|
|
|
|
*
|
|
|
|
* If the application wants to have the stack randomly generate identities
|
|
|
|
* and store them in flash for later recovery, the way to do it would be
|
|
|
|
* to first initialize the stack (using bt_enable), then call settings_load(),
|
|
|
|
* and after that check with bt_id_get() how many identities were recovered.
|
|
|
|
* If an insufficient amount of identities were recovered the app may then
|
|
|
|
* call bt_id_create() to create new ones.
|
|
|
|
*
|
2018-07-16 13:39:06 +02:00
|
|
|
* @param addr Address to use for the new identity. If NULL or initialized
|
|
|
|
* to BT_ADDR_LE_ANY the stack will generate a new static
|
2018-07-13 11:04:39 +02:00
|
|
|
* random address for the identity and copy it to the given
|
2018-07-16 13:39:06 +02:00
|
|
|
* parameter upon return from this function (in case the
|
|
|
|
* parameter was non-NULL).
|
2018-07-13 11:04:39 +02:00
|
|
|
* @param irk Identity Resolving Key (16 bytes) to be used with this
|
|
|
|
* identity. If set to all zeroes or NULL, the stack will
|
|
|
|
* generate a random IRK for the identity and copy it back
|
|
|
|
* to the parameter upon return from this function (in case
|
2020-03-10 14:15:36 +01:00
|
|
|
* the parameter was non-NULL). If privacy
|
|
|
|
* :option:`CONFIG_BT_PRIVACY` is not enabled this parameter must
|
2018-07-13 11:04:39 +02:00
|
|
|
* be NULL.
|
|
|
|
*
|
|
|
|
* @return Identity identifier (>= 0) in case of success, or a negative
|
|
|
|
* error code on failure.
|
|
|
|
*/
|
2020-05-27 18:26:57 +02:00
|
|
|
int bt_id_create(bt_addr_le_t *addr, uint8_t *irk);
|
2018-07-13 11:04:39 +02:00
|
|
|
|
2018-07-18 12:47:04 +02:00
|
|
|
/** @brief Reset/reclaim an identity for reuse.
|
|
|
|
*
|
|
|
|
* The semantics of the @a addr and @a irk parameters of this function
|
|
|
|
* are the same as with bt_id_create(). The difference is the first
|
|
|
|
* @a id parameter that needs to be an existing identity (if it doesn't
|
|
|
|
* exist this function will return an error). When given an existing
|
|
|
|
* identity this function will disconnect any connections created using it,
|
|
|
|
* remove any pairing keys or other data associated with it, and then create
|
|
|
|
* a new identity in the same slot, based on the @a addr and @a irk
|
|
|
|
* parameters.
|
|
|
|
*
|
2020-03-17 10:32:20 +01:00
|
|
|
* @note the default identity (BT_ID_DEFAULT) cannot be reset, i.e. this
|
2018-07-18 12:47:04 +02:00
|
|
|
* API will return an error if asked to do that.
|
|
|
|
*
|
|
|
|
* @param id Existing identity identifier.
|
|
|
|
* @param addr Address to use for the new identity. If NULL or initialized
|
|
|
|
* to BT_ADDR_LE_ANY the stack will generate a new static
|
|
|
|
* random address for the identity and copy it to the given
|
|
|
|
* parameter upon return from this function (in case the
|
|
|
|
* parameter was non-NULL).
|
|
|
|
* @param irk Identity Resolving Key (16 bytes) to be used with this
|
|
|
|
* identity. If set to all zeroes or NULL, the stack will
|
|
|
|
* generate a random IRK for the identity and copy it back
|
|
|
|
* to the parameter upon return from this function (in case
|
2020-03-10 14:15:36 +01:00
|
|
|
* the parameter was non-NULL). If privacy
|
|
|
|
* :option:`CONFIG_BT_PRIVACY` is not enabled this parameter must
|
2018-07-18 12:47:04 +02:00
|
|
|
* be NULL.
|
|
|
|
*
|
|
|
|
* @return Identity identifier (>= 0) in case of success, or a negative
|
|
|
|
* error code on failure.
|
|
|
|
*/
|
2020-05-27 18:26:57 +02:00
|
|
|
int bt_id_reset(uint8_t id, bt_addr_le_t *addr, uint8_t *irk);
|
2018-07-18 12:47:04 +02:00
|
|
|
|
2018-08-02 10:25:57 +02:00
|
|
|
/** @brief Delete an identity.
|
|
|
|
*
|
|
|
|
* When given a valid identity this function will disconnect any connections
|
|
|
|
* created using it, remove any pairing keys or other data associated with
|
|
|
|
* it, and then flag is as deleted, so that it can not be used for any
|
|
|
|
* operations. To take back into use the slot the identity was occupying the
|
|
|
|
* bt_id_reset() API needs to be used.
|
|
|
|
*
|
2020-03-17 10:32:20 +01:00
|
|
|
* @note the default identity (BT_ID_DEFAULT) cannot be deleted, i.e. this
|
2018-08-02 10:25:57 +02:00
|
|
|
* API will return an error if asked to do that.
|
|
|
|
*
|
|
|
|
* @param id Existing identity identifier.
|
|
|
|
*
|
|
|
|
* @return 0 in case of success, or a negative error code on failure.
|
|
|
|
*/
|
2020-05-27 18:26:57 +02:00
|
|
|
int bt_id_delete(uint8_t id);
|
2018-08-02 10:25:57 +02:00
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Bluetooth data.
|
|
|
|
*
|
|
|
|
* Description of different data types that can be encoded into
|
2020-03-17 10:32:20 +01:00
|
|
|
* advertising data. Used to form arrays that are passed to the
|
|
|
|
* bt_le_adv_start() function.
|
|
|
|
*/
|
2016-01-13 11:53:54 +01:00
|
|
|
struct bt_data {
|
2020-05-27 18:26:57 +02:00
|
|
|
uint8_t type;
|
|
|
|
uint8_t data_len;
|
|
|
|
const uint8_t *data;
|
2016-01-13 11:53:54 +01:00
|
|
|
};
|
|
|
|
|
2016-01-30 12:51:22 +01:00
|
|
|
/** @brief Helper to declare elements of bt_data arrays
|
|
|
|
*
|
|
|
|
* This macro is mainly for creating an array of struct bt_data
|
2020-04-30 10:49:54 +02:00
|
|
|
* elements which is then passed to e.g. @ref bt_le_adv_start().
|
2016-01-30 12:51:22 +01:00
|
|
|
*
|
|
|
|
* @param _type Type of advertising data field
|
|
|
|
* @param _data Pointer to the data field payload
|
|
|
|
* @param _data_len Number of bytes behind the _data pointer
|
|
|
|
*/
|
2016-01-13 11:53:54 +01:00
|
|
|
#define BT_DATA(_type, _data, _data_len) \
|
2016-01-30 12:51:22 +01:00
|
|
|
{ \
|
|
|
|
.type = (_type), \
|
|
|
|
.data_len = (_data_len), \
|
2020-05-27 18:26:57 +02:00
|
|
|
.data = (const uint8_t *)(_data), \
|
2016-01-30 12:51:22 +01:00
|
|
|
}
|
2015-04-30 15:07:09 +02:00
|
|
|
|
2016-01-30 12:51:22 +01:00
|
|
|
/** @brief Helper to declare elements of bt_data arrays
|
|
|
|
*
|
|
|
|
* This macro is mainly for creating an array of struct bt_data
|
2020-04-30 10:49:54 +02:00
|
|
|
* elements which is then passed to e.g. @ref bt_le_adv_start().
|
2016-01-30 12:51:22 +01:00
|
|
|
*
|
|
|
|
* @param _type Type of advertising data field
|
|
|
|
* @param _bytes Variable number of single-byte parameters
|
|
|
|
*/
|
2016-01-30 12:26:23 +01:00
|
|
|
#define BT_DATA_BYTES(_type, _bytes...) \
|
2020-05-27 18:26:57 +02:00
|
|
|
BT_DATA(_type, ((uint8_t []) { _bytes }), \
|
|
|
|
sizeof((uint8_t []) { _bytes }))
|
2016-01-30 12:26:23 +01:00
|
|
|
|
2016-05-02 15:18:28 +02:00
|
|
|
/** Advertising options */
|
2015-12-07 07:11:41 +01:00
|
|
|
enum {
|
2016-06-27 09:31:51 +02:00
|
|
|
/** Convenience value when no options are specified. */
|
|
|
|
BT_LE_ADV_OPT_NONE = 0,
|
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Advertise as connectable.
|
|
|
|
*
|
|
|
|
* Advertise as connectable. If not connectable then the type of
|
2020-03-10 14:15:36 +01:00
|
|
|
* advertising is determined by providing scan response data.
|
|
|
|
* The advertiser address is determined by the type of advertising
|
|
|
|
* and/or enabling privacy :option:`CONFIG_BT_PRIVACY`.
|
2016-04-04 11:55:11 +02:00
|
|
|
*/
|
2016-05-02 15:18:28 +02:00
|
|
|
BT_LE_ADV_OPT_CONNECTABLE = BIT(0),
|
2017-06-29 13:13:39 +02:00
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Advertise one time.
|
|
|
|
*
|
|
|
|
* Don't try to resume connectable advertising after a connection.
|
2017-06-29 13:13:39 +02:00
|
|
|
* This option is only meaningful when used together with
|
|
|
|
* BT_LE_ADV_OPT_CONNECTABLE. If set the advertising will be stopped
|
|
|
|
* when bt_le_adv_stop() is called or when an incoming (slave)
|
|
|
|
* connection happens. If this option is not set the stack will
|
|
|
|
* take care of keeping advertising enabled even as connections
|
|
|
|
* occur.
|
2020-05-04 15:17:55 +02:00
|
|
|
* If Advertising directed or the advertiser was started with
|
|
|
|
* @ref bt_le_ext_adv_start then this behavior is the default behavior
|
|
|
|
* and this flag has no effect.
|
2017-06-29 13:13:39 +02:00
|
|
|
*/
|
|
|
|
BT_LE_ADV_OPT_ONE_TIME = BIT(1),
|
2018-03-20 15:57:00 +01:00
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Advertise using identity address.
|
|
|
|
*
|
|
|
|
* Advertise using the identity address as the advertiser address.
|
2018-03-20 15:57:00 +01:00
|
|
|
* @warning This will compromise the privacy of the device, so care
|
|
|
|
* must be taken when using this option.
|
2020-03-10 14:15:36 +01:00
|
|
|
* @note The address used for advertising will not be the same as
|
|
|
|
* returned by @ref bt_le_oob_get_local, instead @ref bt_id_get
|
|
|
|
* should be used to get the LE address.
|
2018-03-20 15:57:00 +01:00
|
|
|
*/
|
|
|
|
BT_LE_ADV_OPT_USE_IDENTITY = BIT(2),
|
2018-07-10 09:14:23 +02:00
|
|
|
|
2019-08-15 08:39:09 +02:00
|
|
|
/** Advertise using GAP device name */
|
2018-07-10 09:14:23 +02:00
|
|
|
BT_LE_ADV_OPT_USE_NAME = BIT(3),
|
2018-08-20 14:44:42 +02:00
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Low duty cycle directed advertising.
|
|
|
|
*
|
|
|
|
* Use low duty directed advertising mode, otherwise high duty mode
|
2020-04-09 20:06:02 +02:00
|
|
|
* will be used.
|
2018-08-20 14:44:42 +02:00
|
|
|
*/
|
|
|
|
BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY = BIT(4),
|
2019-03-28 15:18:23 +01:00
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Directed advertising to privacy-enabled peer.
|
|
|
|
*
|
|
|
|
* Enable use of Resolvable Private Address (RPA) as the target address
|
2020-03-10 14:15:36 +01:00
|
|
|
* in directed advertisements when :option:`CONFIG_BT_PRIVACY` is not
|
|
|
|
* enabled.
|
2019-03-28 15:18:23 +01:00
|
|
|
* This is required if the remote device is privacy-enabled and
|
|
|
|
* supports address resolution of the target address in directed
|
|
|
|
* advertisement.
|
|
|
|
* It is the responsibility of the application to check that the remote
|
|
|
|
* device supports address resolution of directed advertisements by
|
|
|
|
* reading its Central Address Resolution characteristic.
|
|
|
|
*/
|
|
|
|
BT_LE_ADV_OPT_DIR_ADDR_RPA = BIT(5),
|
2019-07-22 13:13:38 +02:00
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** Use whitelist to filter devices that can request scan response data.
|
2019-07-22 13:13:38 +02:00
|
|
|
*/
|
|
|
|
BT_LE_ADV_OPT_FILTER_SCAN_REQ = BIT(6),
|
|
|
|
|
2019-08-15 08:39:09 +02:00
|
|
|
/** Use whitelist to filter devices that can connect. */
|
2019-07-22 13:13:38 +02:00
|
|
|
BT_LE_ADV_OPT_FILTER_CONN = BIT(7),
|
2020-02-01 18:27:39 +01:00
|
|
|
|
|
|
|
/** Notify the application when a scan response data has been sent to an
|
|
|
|
* active scanner.
|
|
|
|
*/
|
|
|
|
BT_LE_ADV_OPT_NOTIFY_SCAN_REQ = BIT(8),
|
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Support scan response data.
|
2020-02-01 18:27:39 +01:00
|
|
|
*
|
|
|
|
* When used together with @ref BT_LE_ADV_OPT_EXT_ADV then this option
|
|
|
|
* cannot be used together with the @ref BT_LE_ADV_OPT_CONNECTABLE
|
|
|
|
* option.
|
|
|
|
* When used together with @ref BT_LE_ADV_OPT_EXT_ADV then scan
|
|
|
|
* response data must be set.
|
|
|
|
*/
|
|
|
|
BT_LE_ADV_OPT_SCANNABLE = BIT(9),
|
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Advertise with extended advertising.
|
2020-02-01 18:27:39 +01:00
|
|
|
*
|
|
|
|
* This options enables extended advertising in the advertising set.
|
|
|
|
* In extended advertising the advertising set will send a small header
|
|
|
|
* packet on the three primary advertising channels. This small header
|
|
|
|
* points to the advertising data packet that will be sent on one of
|
|
|
|
* the 37 secondary advertising channels.
|
|
|
|
* The advertiser will send primary advertising on LE 1M PHY, and
|
|
|
|
* secondary advertising on LE 2M PHY.
|
2020-04-23 11:29:58 +02:00
|
|
|
* Connections will be established on LE 2M PHY.
|
2020-02-01 18:27:39 +01:00
|
|
|
*
|
|
|
|
* Without this option the advertiser will send advertising data on the
|
|
|
|
* three primary advertising channels.
|
|
|
|
*
|
|
|
|
* @note Enabling this option requires extended advertising support in
|
|
|
|
* the peer devices scanning for advertisement packets.
|
|
|
|
*/
|
|
|
|
BT_LE_ADV_OPT_EXT_ADV = BIT(10),
|
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Disable use of LE 2M PHY on the secondary advertising
|
|
|
|
* channel.
|
2020-02-01 18:27:39 +01:00
|
|
|
*
|
|
|
|
* Disabling the use of LE 2M PHY could be necessary if scanners don't
|
|
|
|
* support the LE 2M PHY.
|
|
|
|
* The advertiser will send primary advertising on LE 1M PHY, and
|
|
|
|
* secondary advertising on LE 1M PHY.
|
2020-04-23 11:29:58 +02:00
|
|
|
* Connections will be established on LE 1M PHY.
|
2020-02-01 18:27:39 +01:00
|
|
|
*
|
|
|
|
* @note Cannot be set if BT_LE_ADV_OPT_CODED is set.
|
|
|
|
*
|
|
|
|
* @note Requires @ref BT_LE_ADV_OPT_EXT_ADV.
|
|
|
|
*/
|
|
|
|
BT_LE_ADV_OPT_NO_2M = BIT(11),
|
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Advertise on the LE Coded PHY (Long Range).
|
2020-02-01 18:27:39 +01:00
|
|
|
*
|
|
|
|
* The advertiser will send both primary and secondary advertising
|
|
|
|
* on the LE Coded PHY. This gives the advertiser increased range with
|
|
|
|
* the trade-off of lower data rate and higher power consumption.
|
2020-04-23 11:29:58 +02:00
|
|
|
* Connections will be established on LE Coded PHY.
|
2020-02-01 18:27:39 +01:00
|
|
|
*
|
|
|
|
* @note Requires @ref BT_LE_ADV_OPT_EXT_ADV
|
|
|
|
*/
|
|
|
|
BT_LE_ADV_OPT_CODED = BIT(12),
|
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Advertise without a device address (identity or RPA).
|
2020-02-01 18:27:39 +01:00
|
|
|
*
|
|
|
|
* @note Requires @ref BT_LE_ADV_OPT_EXT_ADV
|
|
|
|
*/
|
|
|
|
BT_LE_ADV_OPT_ANONYMOUS = BIT(13),
|
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Advertise with transmit power.
|
2020-02-01 18:27:39 +01:00
|
|
|
*
|
|
|
|
* @note Requires @ref BT_LE_ADV_OPT_EXT_ADV
|
|
|
|
*/
|
|
|
|
BT_LE_ADV_OPT_USE_TX_POWER = BIT(14),
|
2015-12-07 07:11:41 +01:00
|
|
|
};
|
|
|
|
|
2015-12-05 20:50:43 +01:00
|
|
|
/** LE Advertising Parameters. */
|
2015-12-03 14:27:19 +01:00
|
|
|
struct bt_le_adv_param {
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Local identity.
|
2020-04-18 18:30:12 +02:00
|
|
|
*
|
|
|
|
* @note When extended advertising :option:`CONFIG_BT_EXT_ADV` is not
|
|
|
|
* enabled or not supported by the controller it is not possible
|
|
|
|
* to scan and advertise simultaneously using two different
|
|
|
|
* random addresses.
|
|
|
|
*
|
|
|
|
* @note It is not possible to have multiple connectable advertising
|
|
|
|
* sets advertising simultaneously using different identities.
|
|
|
|
*/
|
2020-05-27 18:26:57 +02:00
|
|
|
uint8_t id;
|
2018-07-04 11:58:10 +02:00
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Advertising Set Identifier, valid range 0x00 - 0x0f.
|
2020-02-01 18:27:39 +01:00
|
|
|
*
|
|
|
|
* @note Requires @ref BT_LE_ADV_OPT_EXT_ADV
|
|
|
|
**/
|
2020-05-27 18:26:57 +02:00
|
|
|
uint8_t sid;
|
2020-02-01 18:27:39 +01:00
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Secondary channel maximum skip count.
|
|
|
|
*
|
|
|
|
* Maximum advertising events the advertiser can skip before it must
|
2020-02-01 18:27:39 +01:00
|
|
|
* send advertising data on the secondary advertising channel.
|
|
|
|
*
|
|
|
|
* @note Requires @ref BT_LE_ADV_OPT_EXT_ADV
|
|
|
|
*/
|
2020-05-27 18:26:57 +02:00
|
|
|
uint8_t secondary_max_skip;
|
2020-02-01 18:27:39 +01:00
|
|
|
|
2016-05-02 15:18:28 +02:00
|
|
|
/** Bit-field of advertising options */
|
2020-05-27 18:26:57 +02:00
|
|
|
uint32_t options;
|
2015-12-07 07:11:41 +01:00
|
|
|
|
2015-12-05 20:50:43 +01:00
|
|
|
/** Minimum Advertising Interval (N * 0.625) */
|
2020-05-27 18:26:57 +02:00
|
|
|
uint32_t interval_min;
|
2015-12-05 20:50:43 +01:00
|
|
|
|
|
|
|
/** Maximum Advertising Interval (N * 0.625) */
|
2020-05-27 18:26:57 +02:00
|
|
|
uint32_t interval_max;
|
2020-04-09 20:06:02 +02:00
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Directed advertising to peer
|
2020-04-09 20:06:02 +02:00
|
|
|
*
|
|
|
|
* When this parameter is set the advertiser will send directed
|
|
|
|
* advertising to the remote device.
|
|
|
|
*
|
|
|
|
* The advertising type will either be high duty cycle, or low duty
|
|
|
|
* cycle if the BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY option is enabled.
|
|
|
|
*
|
|
|
|
* In case of connectable high duty cycle if the connection could not
|
|
|
|
* be established within the timeout the connected() callback will be
|
|
|
|
* called with the status set to @ref BT_HCI_ERR_ADV_TIMEOUT.
|
|
|
|
*/
|
|
|
|
const bt_addr_le_t *peer;
|
2015-12-03 14:27:19 +01:00
|
|
|
};
|
|
|
|
|
2020-04-30 10:49:54 +02:00
|
|
|
/** @brief Initialize advertising parameters
|
|
|
|
*
|
|
|
|
* @param _options Advertising Options
|
|
|
|
* @param _int_min Minimum advertising interval
|
|
|
|
* @param _int_max Maximum advertising interval
|
|
|
|
* @param _peer Peer address, set to NULL for undirected advertising or
|
|
|
|
* address of peer for directed advertising.
|
|
|
|
*/
|
|
|
|
#define BT_LE_ADV_PARAM_INIT(_options, _int_min, _int_max, _peer) \
|
|
|
|
{ \
|
|
|
|
.id = BT_ID_DEFAULT, \
|
|
|
|
.sid = 0, \
|
|
|
|
.secondary_max_skip = 0, \
|
|
|
|
.options = (_options), \
|
|
|
|
.interval_min = (_int_min), \
|
|
|
|
.interval_max = (_int_max), \
|
|
|
|
.peer = (_peer), \
|
|
|
|
}
|
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Helper to declare advertising parameters inline
|
2020-03-17 10:32:20 +01:00
|
|
|
*
|
|
|
|
* @param _options Advertising Options
|
|
|
|
* @param _int_min Minimum advertising interval
|
|
|
|
* @param _int_max Maximum advertising interval
|
2020-04-09 20:06:02 +02:00
|
|
|
* @param _peer Peer address, set to NULL for undirected advertising or
|
|
|
|
* address of peer for directed advertising.
|
2020-03-17 10:32:20 +01:00
|
|
|
*/
|
2020-04-09 20:06:02 +02:00
|
|
|
#define BT_LE_ADV_PARAM(_options, _int_min, _int_max, _peer) \
|
2020-04-30 10:49:54 +02:00
|
|
|
((struct bt_le_adv_param[]) { \
|
|
|
|
BT_LE_ADV_PARAM_INIT(_options, _int_min, _int_max, _peer) \
|
|
|
|
})
|
2015-12-05 20:50:43 +01:00
|
|
|
|
2020-04-09 20:06:02 +02:00
|
|
|
#define BT_LE_ADV_CONN_DIR(_peer) BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONNECTABLE | \
|
|
|
|
BT_LE_ADV_OPT_ONE_TIME, 0, 0,\
|
|
|
|
_peer)
|
|
|
|
|
|
|
|
|
2016-05-02 15:18:28 +02:00
|
|
|
#define BT_LE_ADV_CONN BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONNECTABLE, \
|
|
|
|
BT_GAP_ADV_FAST_INT_MIN_2, \
|
2020-04-09 20:06:02 +02:00
|
|
|
BT_GAP_ADV_FAST_INT_MAX_2, NULL)
|
2016-05-02 15:18:28 +02:00
|
|
|
|
2018-07-10 10:26:19 +02:00
|
|
|
#define BT_LE_ADV_CONN_NAME BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONNECTABLE | \
|
|
|
|
BT_LE_ADV_OPT_USE_NAME, \
|
|
|
|
BT_GAP_ADV_FAST_INT_MIN_2, \
|
2020-04-09 20:06:02 +02:00
|
|
|
BT_GAP_ADV_FAST_INT_MAX_2, NULL)
|
2018-07-10 10:26:19 +02:00
|
|
|
|
2020-04-09 20:06:02 +02:00
|
|
|
#define BT_LE_ADV_CONN_DIR_LOW_DUTY(_peer) \
|
2018-08-20 14:44:42 +02:00
|
|
|
BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONNECTABLE | BT_LE_ADV_OPT_ONE_TIME | \
|
|
|
|
BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY, \
|
2020-04-09 20:06:02 +02:00
|
|
|
BT_GAP_ADV_FAST_INT_MIN_2, BT_GAP_ADV_FAST_INT_MAX_2, \
|
|
|
|
_peer)
|
2018-08-20 14:44:42 +02:00
|
|
|
|
2016-05-02 15:18:28 +02:00
|
|
|
#define BT_LE_ADV_NCONN BT_LE_ADV_PARAM(0, BT_GAP_ADV_FAST_INT_MIN_2, \
|
2020-04-09 20:06:02 +02:00
|
|
|
BT_GAP_ADV_FAST_INT_MAX_2, NULL)
|
2015-12-03 14:27:19 +01:00
|
|
|
|
2018-07-10 10:26:19 +02:00
|
|
|
#define BT_LE_ADV_NCONN_NAME BT_LE_ADV_PARAM(BT_LE_ADV_OPT_USE_NAME, \
|
|
|
|
BT_GAP_ADV_FAST_INT_MIN_2, \
|
2020-04-09 20:06:02 +02:00
|
|
|
BT_GAP_ADV_FAST_INT_MAX_2, NULL)
|
2018-07-10 10:26:19 +02:00
|
|
|
|
2015-07-01 22:47:13 +02:00
|
|
|
/** @brief Start advertising
|
2015-06-12 13:25:28 +02:00
|
|
|
*
|
2015-06-18 09:43:23 +02:00
|
|
|
* Set advertisement data, scan response data, advertisement parameters
|
2015-06-12 13:25:28 +02:00
|
|
|
* and start advertising.
|
|
|
|
*
|
2020-04-09 20:06:02 +02:00
|
|
|
* When the advertisement parameter peer address has been set the advertising
|
|
|
|
* will be directed to the peer. In this case advertisement data and scan
|
|
|
|
* response data parameters are ignored. If the mode is high duty cycle
|
|
|
|
* the timeout will be @ref BT_GAP_ADV_HIGH_DUTY_CYCLE_MAX_TIMEOUT.
|
|
|
|
*
|
2015-12-03 14:27:19 +01:00
|
|
|
* @param param Advertising parameters.
|
2015-06-18 09:43:23 +02:00
|
|
|
* @param ad Data to be used in advertisement packets.
|
2016-01-13 11:53:54 +01:00
|
|
|
* @param ad_len Number of elements in ad
|
2015-06-18 09:43:23 +02:00
|
|
|
* @param sd Data to be used in scan response packets.
|
2016-01-13 11:53:54 +01:00
|
|
|
* @param sd_len Number of elements in sd
|
2015-06-12 13:25:28 +02:00
|
|
|
*
|
2015-06-18 09:43:23 +02:00
|
|
|
* @return Zero on success or (negative) error code otherwise.
|
2020-01-13 14:39:30 +01:00
|
|
|
* @return -ENOMEM No free connection objects available for connectable
|
|
|
|
* advertiser.
|
2019-01-25 13:57:26 +01:00
|
|
|
* @return -ECONNREFUSED When connectable advertising is requested and there
|
2020-01-13 14:39:30 +01:00
|
|
|
* is already maximum number of connections established
|
|
|
|
* in the controller.
|
|
|
|
* This error code is only guaranteed when using Zephyr
|
|
|
|
* controller, for other controllers code returned in
|
|
|
|
* this case may be -EIO.
|
2015-06-12 13:25:28 +02:00
|
|
|
*/
|
2015-12-03 14:27:19 +01:00
|
|
|
int bt_le_adv_start(const struct bt_le_adv_param *param,
|
2016-01-13 11:53:54 +01:00
|
|
|
const struct bt_data *ad, size_t ad_len,
|
|
|
|
const struct bt_data *sd, size_t sd_len);
|
2015-06-02 17:28:00 +02:00
|
|
|
|
2018-10-25 15:20:09 +02:00
|
|
|
/** @brief Update advertising
|
|
|
|
*
|
|
|
|
* Update advertisement and scan response data.
|
|
|
|
*
|
|
|
|
* @param ad Data to be used in advertisement packets.
|
|
|
|
* @param ad_len Number of elements in ad
|
|
|
|
* @param sd Data to be used in scan response packets.
|
|
|
|
* @param sd_len Number of elements in sd
|
|
|
|
*
|
|
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
|
|
*/
|
|
|
|
int bt_le_adv_update_data(const struct bt_data *ad, size_t ad_len,
|
|
|
|
const struct bt_data *sd, size_t sd_len);
|
|
|
|
|
2015-07-08 12:17:01 +02:00
|
|
|
/** @brief Stop advertising
|
|
|
|
*
|
|
|
|
* Stops ongoing advertising.
|
|
|
|
*
|
|
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
|
|
*/
|
2015-12-03 09:19:38 +01:00
|
|
|
int bt_le_adv_stop(void);
|
2015-07-08 12:17:01 +02:00
|
|
|
|
2020-02-01 18:27:39 +01:00
|
|
|
/** @brief Create advertising set.
|
|
|
|
*
|
|
|
|
* Create a new advertising set and set advertising parameters.
|
|
|
|
* Advertising parameters can be updated with @ref bt_le_ext_adv_update_param.
|
|
|
|
*
|
|
|
|
* @param[in] param Advertising parameters.
|
|
|
|
* @param[in] cb Callback struct to notify about advertiser activity. Can be
|
|
|
|
* NULL. Must point to valid memory during the lifetime of the
|
|
|
|
* advertising set.
|
|
|
|
* @param[out] adv Valid advertising set object on success.
|
|
|
|
*
|
|
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
|
|
*/
|
|
|
|
int bt_le_ext_adv_create(const struct bt_le_adv_param *param,
|
|
|
|
const struct bt_le_ext_adv_cb *cb,
|
|
|
|
struct bt_le_ext_adv **adv);
|
|
|
|
|
|
|
|
struct bt_le_ext_adv_start_param {
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Advertiser timeout (N * 10 ms).
|
2020-02-01 18:27:39 +01:00
|
|
|
*
|
|
|
|
* Application will be notified by the advertiser sent callback.
|
|
|
|
* Set to zero for no timeout.
|
|
|
|
*
|
2020-04-09 20:06:02 +02:00
|
|
|
* When using high duty cycle directed connectable advertising then
|
|
|
|
* this parameters must be set to a non-zero value less than or equal
|
|
|
|
* to the maximum of @ref BT_GAP_ADV_HIGH_DUTY_CYCLE_MAX_TIMEOUT.
|
|
|
|
*
|
2020-02-01 18:27:39 +01:00
|
|
|
* If privacy :option:`CONFIG_BT_PRIVACY` is enabled then the timeout
|
|
|
|
* must be less than :option:`CONFIG_BT_RPA_TIMEOUT`.
|
|
|
|
*/
|
2020-05-27 18:26:57 +02:00
|
|
|
uint16_t timeout;
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Number of advertising events.
|
2020-02-01 18:27:39 +01:00
|
|
|
*
|
|
|
|
* Application will be notified by the advertiser sent callback.
|
|
|
|
* Set to zero for no limit.
|
|
|
|
*/
|
2020-05-27 18:26:57 +02:00
|
|
|
uint8_t num_events;
|
2020-02-01 18:27:39 +01:00
|
|
|
};
|
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Start advertising with the given advertising set
|
2020-02-01 18:27:39 +01:00
|
|
|
*
|
|
|
|
* If the advertiser is limited by either the timeout or number of advertising
|
|
|
|
* events the application will be notified by the advertiser sent callback once
|
|
|
|
* the limit is reached.
|
|
|
|
* If the advertiser is limited by both the timeout and the number of
|
|
|
|
* advertising events then the limit that is reached first will stop the
|
|
|
|
* advertiser.
|
|
|
|
*
|
|
|
|
* @param adv Advertising set object.
|
|
|
|
* @param param Advertise start parameters.
|
|
|
|
*/
|
|
|
|
int bt_le_ext_adv_start(struct bt_le_ext_adv *adv,
|
|
|
|
struct bt_le_ext_adv_start_param *param);
|
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Stop advertising with the given advertising set
|
2020-02-01 18:27:39 +01:00
|
|
|
*
|
|
|
|
* Stop advertising with a specific advertising set. When using this function
|
|
|
|
* the advertising sent callback will not be called.
|
|
|
|
*
|
|
|
|
* @param adv Advertising set object.
|
|
|
|
*
|
|
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
|
|
*/
|
|
|
|
int bt_le_ext_adv_stop(struct bt_le_ext_adv *adv);
|
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Set an advertising set's advertising or scan response data.
|
2020-02-01 18:27:39 +01:00
|
|
|
*
|
|
|
|
* Set advertisement data or scan response data. If the advertising set is
|
|
|
|
* currently advertising then the advertising data will be updated in
|
|
|
|
* subsequent advertising events.
|
|
|
|
*
|
|
|
|
* If the advertising set has been configured to send advertising data on the
|
|
|
|
* primary advertising channels then the maximum data length is
|
|
|
|
* @ref BT_GAP_ADV_MAX_ADV_DATA_LEN bytes.
|
|
|
|
* If the advertising set has been configured for extended advertising,
|
|
|
|
* then the maximum data length is defined by the controller with the maximum
|
|
|
|
* possible of @ref BT_GAP_ADV_MAX_EXT_ADV_DATA_LEN bytes.
|
|
|
|
*
|
|
|
|
* @note Not all scanners support extended data length advertising data.
|
|
|
|
*
|
|
|
|
* @note When updating the advertising data while advertising the advertising
|
|
|
|
* data and scan response data length must be smaller or equal to what
|
|
|
|
* can be fit in a single advertising packet. Otherwise the
|
|
|
|
* advertiser must be stopped.
|
|
|
|
*
|
|
|
|
* @param adv Advertising set object.
|
|
|
|
* @param ad Data to be used in advertisement packets.
|
|
|
|
* @param ad_len Number of elements in ad
|
|
|
|
* @param sd Data to be used in scan response packets.
|
|
|
|
* @param sd_len Number of elements in sd
|
|
|
|
*
|
|
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
|
|
*/
|
|
|
|
int bt_le_ext_adv_set_data(struct bt_le_ext_adv *adv,
|
|
|
|
const struct bt_data *ad, size_t ad_len,
|
|
|
|
const struct bt_data *sd, size_t sd_len);
|
|
|
|
|
|
|
|
/** @brief Update advertising parameters.
|
|
|
|
*
|
|
|
|
* Update the advertising parameters. The function will return an error if the
|
|
|
|
* advertiser set is currently advertising. Stop the advertising set before
|
|
|
|
* calling this function.
|
|
|
|
*
|
|
|
|
* @param adv Advertising set object.
|
|
|
|
* @param param Advertising parameters.
|
|
|
|
*
|
|
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
|
|
*/
|
|
|
|
int bt_le_ext_adv_update_param(struct bt_le_ext_adv *adv,
|
|
|
|
const struct bt_le_adv_param *param);
|
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Delete advertising set.
|
2020-02-01 18:27:39 +01:00
|
|
|
*
|
|
|
|
* Delete advertising set. This will free up the advertising set and make it
|
|
|
|
* possible to create a new advertising set.
|
|
|
|
*
|
|
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
|
|
*/
|
|
|
|
int bt_le_ext_adv_delete(struct bt_le_ext_adv *adv);
|
|
|
|
|
|
|
|
/** @brief Get array index of an advertising set.
|
|
|
|
*
|
|
|
|
* This function is used to map bt_adv to index of an array of
|
|
|
|
* advertising sets. The array has CONFIG_BT_EXT_ADV_MAX_ADV_SET elements.
|
|
|
|
*
|
|
|
|
* @param adv Advertising set.
|
|
|
|
*
|
|
|
|
* @return Index of the advertising set object.
|
|
|
|
* The range of the returned value is 0..CONFIG_BT_EXT_ADV_MAX_ADV_SET-1
|
|
|
|
*/
|
2020-05-27 18:26:57 +02:00
|
|
|
uint8_t bt_le_ext_adv_get_index(struct bt_le_ext_adv *adv);
|
2020-02-01 18:27:39 +01:00
|
|
|
|
|
|
|
/** @brief Advertising set info structure. */
|
|
|
|
struct bt_le_ext_adv_info {
|
|
|
|
/* Local identity */
|
2020-05-27 18:26:57 +02:00
|
|
|
uint8_t id;
|
2020-02-01 18:27:39 +01:00
|
|
|
|
|
|
|
/** Currently selected Transmit Power (dBM). */
|
2020-05-27 18:26:57 +02:00
|
|
|
int8_t tx_power;
|
2020-02-01 18:27:39 +01:00
|
|
|
};
|
|
|
|
|
|
|
|
/** @brief Get advertising set info
|
|
|
|
*
|
|
|
|
* @param adv Advertising set object
|
|
|
|
* @param info Advertising set info object
|
|
|
|
*
|
|
|
|
* @return Zero on success or (negative) error code on failure.
|
|
|
|
*/
|
|
|
|
int bt_le_ext_adv_get_info(const struct bt_le_ext_adv *adv,
|
|
|
|
struct bt_le_ext_adv_info *info);
|
|
|
|
|
2016-06-16 19:24:28 +02:00
|
|
|
/** @typedef bt_le_scan_cb_t
|
|
|
|
* @brief Callback type for reporting LE scan results.
|
2015-12-03 13:52:42 +01:00
|
|
|
*
|
2016-06-16 08:56:54 +02:00
|
|
|
* A function of this type is given to the bt_le_scan_start() function
|
|
|
|
* and will be called for any discovered LE device.
|
2015-12-03 13:52:42 +01:00
|
|
|
*
|
|
|
|
* @param addr Advertiser LE address and type.
|
|
|
|
* @param rssi Strength of advertiser signal.
|
|
|
|
* @param adv_type Type of advertising response from advertiser.
|
2019-01-27 19:05:54 +01:00
|
|
|
* @param buf Buffer containing advertiser data.
|
2015-12-03 13:52:42 +01:00
|
|
|
*/
|
2020-05-27 18:26:57 +02:00
|
|
|
typedef void bt_le_scan_cb_t(const bt_addr_le_t *addr, int8_t rssi,
|
|
|
|
uint8_t adv_type, struct net_buf_simple *buf);
|
2015-12-03 13:52:42 +01:00
|
|
|
|
2019-07-22 13:13:38 +02:00
|
|
|
enum {
|
2020-02-01 20:06:35 +01:00
|
|
|
/** Convenience value when no options are specified. */
|
|
|
|
BT_LE_SCAN_OPT_NONE = 0,
|
|
|
|
|
2020-03-17 10:32:20 +01:00
|
|
|
/** Filter duplicates. */
|
2020-02-01 20:06:35 +01:00
|
|
|
BT_LE_SCAN_OPT_FILTER_DUPLICATE = BIT(0),
|
2019-07-22 13:13:38 +02:00
|
|
|
|
2020-03-17 10:32:20 +01:00
|
|
|
/** Filter using whitelist. */
|
2020-02-01 20:06:35 +01:00
|
|
|
BT_LE_SCAN_OPT_FILTER_WHITELIST = BIT(1),
|
2019-07-22 13:13:38 +02:00
|
|
|
|
2020-02-01 20:57:05 +01:00
|
|
|
/** Enable scan on coded PHY (Long Range).*/
|
|
|
|
BT_LE_SCAN_OPT_CODED = BIT(2),
|
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Disable scan on 1M phy.
|
2020-02-01 20:57:05 +01:00
|
|
|
*
|
|
|
|
* @note Requires @ref BT_LE_SCAN_OPT_CODED.
|
|
|
|
*/
|
|
|
|
BT_LE_SCAN_OPT_NO_1M = BIT(3),
|
|
|
|
|
2020-02-01 20:06:35 +01:00
|
|
|
BT_LE_SCAN_FILTER_DUPLICATE __deprecated =
|
|
|
|
BT_LE_SCAN_OPT_FILTER_DUPLICATE,
|
|
|
|
BT_LE_SCAN_FILTER_WHITELIST __deprecated =
|
|
|
|
BT_LE_SCAN_OPT_FILTER_WHITELIST,
|
2019-07-22 13:13:38 +02:00
|
|
|
};
|
|
|
|
|
2019-10-16 10:20:50 +02:00
|
|
|
enum {
|
2020-03-17 10:32:20 +01:00
|
|
|
/** Scan without requesting additional information from advertisers. */
|
2019-10-16 10:20:50 +02:00
|
|
|
BT_LE_SCAN_TYPE_PASSIVE = 0x00,
|
|
|
|
|
2020-03-17 10:32:20 +01:00
|
|
|
/** Scan and request additional information from advertisers. */
|
2019-10-16 10:20:50 +02:00
|
|
|
BT_LE_SCAN_TYPE_ACTIVE = 0x01,
|
|
|
|
};
|
|
|
|
|
2015-12-03 21:39:11 +01:00
|
|
|
/** LE scan parameters */
|
2015-12-03 14:17:10 +01:00
|
|
|
struct bt_le_scan_param {
|
2019-10-16 10:20:50 +02:00
|
|
|
/** Scan type (BT_LE_SCAN_TYPE_ACTIVE or BT_LE_SCAN_TYPE_PASSIVE) */
|
2020-05-27 18:26:57 +02:00
|
|
|
uint8_t type;
|
2015-12-03 21:39:11 +01:00
|
|
|
|
2020-02-01 20:06:35 +01:00
|
|
|
union {
|
|
|
|
/** Bit-field of scanning filter options. */
|
2020-05-27 18:26:57 +02:00
|
|
|
uint32_t filter_dup __deprecated;
|
2020-02-01 20:06:35 +01:00
|
|
|
|
|
|
|
/** Bit-field of scanning options. */
|
2020-05-27 18:26:57 +02:00
|
|
|
uint32_t options;
|
2020-02-01 20:06:35 +01:00
|
|
|
};
|
2015-12-03 21:39:11 +01:00
|
|
|
|
2015-12-05 20:39:44 +01:00
|
|
|
/** Scan interval (N * 0.625 ms) */
|
2020-05-27 18:26:57 +02:00
|
|
|
uint16_t interval;
|
2015-12-03 21:39:11 +01:00
|
|
|
|
2015-12-05 20:39:44 +01:00
|
|
|
/** Scan window (N * 0.625 ms) */
|
2020-05-27 18:26:57 +02:00
|
|
|
uint16_t window;
|
2020-02-01 20:57:05 +01:00
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Scan timeout (N * 10 ms)
|
2020-02-01 20:57:05 +01:00
|
|
|
*
|
|
|
|
* Application will be notified by the scan timeout callback.
|
|
|
|
* Set zero to disable timeout.
|
|
|
|
*/
|
2020-05-27 18:26:57 +02:00
|
|
|
uint16_t timeout;
|
2020-02-01 20:57:05 +01:00
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Scan interval LE Coded PHY (N * 0.625 MS)
|
2020-02-01 20:57:05 +01:00
|
|
|
*
|
|
|
|
* Set zero to use same as LE 1M PHY scan interval.
|
|
|
|
*/
|
2020-05-27 18:26:57 +02:00
|
|
|
uint16_t interval_coded;
|
2020-02-01 20:57:05 +01:00
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Scan window LE Coded PHY (N * 0.625 MS)
|
2020-02-01 20:57:05 +01:00
|
|
|
*
|
|
|
|
* Set zero to use same as LE 1M PHY scan window.
|
|
|
|
*/
|
2020-05-27 18:26:57 +02:00
|
|
|
uint16_t window_coded;
|
2015-12-03 14:17:10 +01:00
|
|
|
};
|
2015-07-23 11:35:59 +02:00
|
|
|
|
2019-12-20 14:13:11 +01:00
|
|
|
/** LE advertisement packet information */
|
2020-02-11 16:59:35 +01:00
|
|
|
struct bt_le_scan_recv_info {
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Advertiser LE address and type.
|
2020-02-01 20:57:05 +01:00
|
|
|
*
|
|
|
|
* If advertiser is anonymous then this address will be
|
|
|
|
* @ref BT_ADDR_LE_ANY.
|
|
|
|
*/
|
2019-12-20 14:13:11 +01:00
|
|
|
const bt_addr_le_t *addr;
|
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** Advertising Set Identifier. */
|
2020-05-27 18:26:57 +02:00
|
|
|
uint8_t sid;
|
2020-02-01 20:57:05 +01:00
|
|
|
|
|
|
|
/** Strength of advertiser signal. */
|
2020-05-27 18:26:57 +02:00
|
|
|
int8_t rssi;
|
2019-12-20 14:13:11 +01:00
|
|
|
|
2020-02-01 20:57:05 +01:00
|
|
|
/** Transmit power of the advertiser. */
|
2020-05-27 18:26:57 +02:00
|
|
|
int8_t tx_power;
|
2020-02-01 20:57:05 +01:00
|
|
|
|
|
|
|
/** Advertising packet type. */
|
2020-05-27 18:26:57 +02:00
|
|
|
uint8_t adv_type;
|
2020-02-01 20:57:05 +01:00
|
|
|
|
|
|
|
/** Advertising packet properties. */
|
2020-05-27 18:26:57 +02:00
|
|
|
uint16_t adv_props;
|
2020-02-01 20:57:05 +01:00
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** Primary advertising channel PHY. */
|
2020-05-27 18:26:57 +02:00
|
|
|
uint8_t primary_phy;
|
2020-02-01 20:57:05 +01:00
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** Secondary advertising channel PHY. */
|
2020-05-27 18:26:57 +02:00
|
|
|
uint8_t secondary_phy;
|
2019-12-20 14:13:11 +01:00
|
|
|
};
|
|
|
|
|
|
|
|
/** Listener context for (LE) scanning. */
|
|
|
|
struct bt_le_scan_cb {
|
|
|
|
|
|
|
|
/** @brief Advertisement packet received callback.
|
|
|
|
*
|
|
|
|
* @param info Advertiser packet information.
|
|
|
|
* @param buf Buffer containing advertiser data.
|
|
|
|
*/
|
2020-02-11 16:59:35 +01:00
|
|
|
void (*recv)(const struct bt_le_scan_recv_info *info,
|
2019-12-20 14:13:11 +01:00
|
|
|
struct net_buf_simple *buf);
|
|
|
|
|
2020-02-01 20:57:05 +01:00
|
|
|
/** @brief The scanner has stopped scanning after scan timeout. */
|
|
|
|
void (*timeout)(void);
|
|
|
|
|
2019-12-20 14:13:11 +01:00
|
|
|
sys_snode_t node;
|
|
|
|
};
|
|
|
|
|
2020-04-30 10:49:54 +02:00
|
|
|
/** @brief Initialize scan parameters
|
|
|
|
*
|
|
|
|
* @param _type Scan Type, BT_LE_SCAN_TYPE_ACTIVE or
|
|
|
|
* BT_LE_SCAN_TYPE_PASSIVE.
|
|
|
|
* @param _options Scan options
|
|
|
|
* @param _interval Scan Interval (N * 0.625 ms)
|
|
|
|
* @param _window Scan Window (N * 0.625 ms)
|
|
|
|
*/
|
|
|
|
#define BT_LE_SCAN_PARAM_INIT(_type, _options, _interval, _window) \
|
|
|
|
{ \
|
|
|
|
.type = (_type), \
|
|
|
|
.options = (_options), \
|
|
|
|
.interval = (_interval), \
|
|
|
|
.window = (_window), \
|
|
|
|
.timeout = 0, \
|
|
|
|
.interval_coded = 0, \
|
|
|
|
.window_coded = 0, \
|
|
|
|
}
|
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Helper to declare scan parameters inline
|
2020-03-17 10:32:20 +01:00
|
|
|
*
|
|
|
|
* @param _type Scan Type, BT_LE_SCAN_TYPE_ACTIVE or
|
|
|
|
* BT_LE_SCAN_TYPE_PASSIVE.
|
2020-02-01 20:06:35 +01:00
|
|
|
* @param _options Scan options
|
2020-03-17 10:32:20 +01:00
|
|
|
* @param _interval Scan Interval (N * 0.625 ms)
|
|
|
|
* @param _window Scan Window (N * 0.625 ms)
|
|
|
|
*/
|
2020-02-01 20:06:35 +01:00
|
|
|
#define BT_LE_SCAN_PARAM(_type, _options, _interval, _window) \
|
2020-04-30 10:49:54 +02:00
|
|
|
((struct bt_le_scan_param[]) { \
|
|
|
|
BT_LE_SCAN_PARAM_INIT(_type, _options, _interval, _window) \
|
|
|
|
})
|
2015-12-05 20:39:44 +01:00
|
|
|
|
2015-12-07 11:18:30 +01:00
|
|
|
/** Helper macro to enable active scanning to discover new devices. */
|
2019-10-16 10:20:50 +02:00
|
|
|
#define BT_LE_SCAN_ACTIVE BT_LE_SCAN_PARAM(BT_LE_SCAN_TYPE_ACTIVE, \
|
2020-02-01 20:06:35 +01:00
|
|
|
BT_LE_SCAN_OPT_FILTER_DUPLICATE, \
|
2015-12-05 20:39:44 +01:00
|
|
|
BT_GAP_SCAN_FAST_INTERVAL, \
|
2015-12-07 11:18:30 +01:00
|
|
|
BT_GAP_SCAN_FAST_WINDOW)
|
2015-12-05 20:39:44 +01:00
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Helper macro to enable passive scanning to discover new devices.
|
2015-12-18 11:59:01 +01:00
|
|
|
*
|
2020-03-17 10:32:20 +01:00
|
|
|
* This macro should be used if information required for device identification
|
|
|
|
* (e.g., UUID) are known to be placed in Advertising Data.
|
2015-12-18 11:59:01 +01:00
|
|
|
*/
|
2019-10-16 10:20:50 +02:00
|
|
|
#define BT_LE_SCAN_PASSIVE BT_LE_SCAN_PARAM(BT_LE_SCAN_TYPE_PASSIVE, \
|
2020-02-01 20:06:35 +01:00
|
|
|
BT_LE_SCAN_OPT_FILTER_DUPLICATE, \
|
2015-12-18 11:59:01 +01:00
|
|
|
BT_GAP_SCAN_FAST_INTERVAL, \
|
|
|
|
BT_GAP_SCAN_FAST_WINDOW)
|
|
|
|
|
2015-07-01 22:47:13 +02:00
|
|
|
/** @brief Start (LE) scanning
|
2015-06-18 09:43:23 +02:00
|
|
|
*
|
2016-06-16 08:56:54 +02:00
|
|
|
* Start LE scanning with given parameters and provide results through
|
|
|
|
* the specified callback.
|
2015-06-18 09:43:23 +02:00
|
|
|
*
|
2020-03-17 10:32:20 +01:00
|
|
|
* @note The LE scanner by default does not use the Identity Address of the
|
2020-01-30 18:44:46 +01:00
|
|
|
* local device when :option:`CONFIG_BT_PRIVACY` is disabled. This is to
|
|
|
|
* prevent the active scanner from disclosing the identity information
|
|
|
|
* when requesting additional information from advertisers.
|
|
|
|
* In order to enable directed advertiser reports then
|
|
|
|
* :option:`CONFIG_BT_SCAN_WITH_IDENTITY` must be enabled.
|
|
|
|
*
|
2015-12-03 14:17:10 +01:00
|
|
|
* @param param Scan parameters.
|
2019-12-20 14:13:11 +01:00
|
|
|
* @param cb Callback to notify scan results. May be NULL if callback
|
|
|
|
* registration through @ref bt_le_scan_cb_register is preferred.
|
2015-06-18 09:43:23 +02:00
|
|
|
*
|
2020-03-17 10:32:20 +01:00
|
|
|
* @return Zero on success or error code otherwise, positive in case of
|
|
|
|
* protocol error or negative (POSIX) in case of stack internal error.
|
2015-06-18 09:43:23 +02:00
|
|
|
*/
|
2015-12-03 14:17:10 +01:00
|
|
|
int bt_le_scan_start(const struct bt_le_scan_param *param, bt_le_scan_cb_t cb);
|
2015-06-18 09:43:23 +02:00
|
|
|
|
2015-07-01 22:47:13 +02:00
|
|
|
/** @brief Stop (LE) scanning.
|
2015-06-18 09:43:23 +02:00
|
|
|
*
|
|
|
|
* Stops ongoing LE scanning.
|
|
|
|
*
|
2020-03-17 10:32:20 +01:00
|
|
|
* @return Zero on success or error code otherwise, positive in case of
|
|
|
|
* protocol error or negative (POSIX) in case of stack internal error.
|
2015-06-18 09:43:23 +02:00
|
|
|
*/
|
2015-12-03 09:19:38 +01:00
|
|
|
int bt_le_scan_stop(void);
|
2015-04-17 12:59:34 +02:00
|
|
|
|
2019-12-20 14:13:11 +01:00
|
|
|
/** @brief Register scanner packet callbacks.
|
|
|
|
*
|
|
|
|
* Adds the callback structure to the list of callback structures that monitors
|
|
|
|
* scanner activity.
|
|
|
|
*
|
|
|
|
* This callback will be called for all scanner activity, regardless of what
|
|
|
|
* API was used to start the scanner.
|
|
|
|
*
|
|
|
|
* @param cb Callback struct. Must point to static memory.
|
|
|
|
*/
|
|
|
|
void bt_le_scan_cb_register(struct bt_le_scan_cb *cb);
|
|
|
|
|
2019-07-22 13:13:38 +02:00
|
|
|
/** @brief Add device (LE) to whitelist.
|
|
|
|
*
|
|
|
|
* Add peer device LE address to the whitelist.
|
|
|
|
*
|
|
|
|
* @note The whitelist cannot be modified when an LE role is using
|
|
|
|
* the whitelist, i.e advertiser or scanner using a whitelist or automatic
|
|
|
|
* connecting to devices using whitelist.
|
|
|
|
*
|
|
|
|
* @param addr Bluetooth LE identity address.
|
|
|
|
*
|
2020-03-17 10:32:20 +01:00
|
|
|
* @return Zero on success or error code otherwise, positive in case of
|
|
|
|
* protocol error or negative (POSIX) in case of stack internal error.
|
2019-07-22 13:13:38 +02:00
|
|
|
*/
|
|
|
|
int bt_le_whitelist_add(const bt_addr_le_t *addr);
|
|
|
|
|
|
|
|
/** @brief Remove device (LE) from whitelist.
|
|
|
|
*
|
|
|
|
* Remove peer device LE address from the whitelist.
|
|
|
|
*
|
|
|
|
* @note The whitelist cannot be modified when an LE role is using
|
|
|
|
* the whitelist, i.e advertiser or scanner using a whitelist or automatic
|
|
|
|
* connecting to devices using whitelist.
|
|
|
|
*
|
|
|
|
* @param addr Bluetooth LE identity address.
|
|
|
|
*
|
2020-03-17 10:32:20 +01:00
|
|
|
* @return Zero on success or error code otherwise, positive in case of
|
|
|
|
* protocol error or negative (POSIX) in case of stack internal error.
|
2019-07-22 13:13:38 +02:00
|
|
|
*/
|
|
|
|
int bt_le_whitelist_rem(const bt_addr_le_t *addr);
|
|
|
|
|
|
|
|
/** @brief Clear whitelist.
|
|
|
|
*
|
|
|
|
* Clear all devices from the whitelist.
|
|
|
|
*
|
|
|
|
* @note The whitelist cannot be modified when an LE role is using
|
|
|
|
* the whitelist, i.e advertiser or scanner using a whitelist or automatic
|
|
|
|
* connecting to devices using whitelist.
|
|
|
|
*
|
2020-03-17 10:32:20 +01:00
|
|
|
* @return Zero on success or error code otherwise, positive in case of
|
|
|
|
* protocol error or negative (POSIX) in case of stack internal error.
|
2019-07-22 13:13:38 +02:00
|
|
|
*/
|
|
|
|
int bt_le_whitelist_clear(void);
|
2018-09-13 13:28:21 +02:00
|
|
|
|
|
|
|
/** @brief Set (LE) channel map.
|
|
|
|
*
|
|
|
|
* @param chan_map Channel map.
|
|
|
|
*
|
2020-03-17 10:32:20 +01:00
|
|
|
* @return Zero on success or error code otherwise, positive in case of
|
|
|
|
* protocol error or negative (POSIX) in case of stack internal error.
|
2018-09-13 13:28:21 +02:00
|
|
|
*/
|
2020-05-27 18:26:57 +02:00
|
|
|
int bt_le_set_chan_map(uint8_t chan_map[5]);
|
2018-09-13 13:28:21 +02:00
|
|
|
|
2018-06-26 12:48:56 +02:00
|
|
|
/** @brief Helper for parsing advertising (or EIR or OOB) data.
|
|
|
|
*
|
|
|
|
* A helper for parsing the basic data types used for Extended Inquiry
|
|
|
|
* Response (EIR), Advertising Data (AD), and OOB data blocks. The most
|
2018-08-07 23:16:26 +02:00
|
|
|
* common scenario is to call this helper on the advertising data
|
2018-06-26 12:48:56 +02:00
|
|
|
* received in the callback that was given to bt_le_scan_start().
|
|
|
|
*
|
|
|
|
* @param ad Advertising data as given to the bt_le_scan_cb_t callback.
|
|
|
|
* @param func Callback function which will be called for each element
|
|
|
|
* that's found in the data. The callback should return
|
|
|
|
* true to continue parsing, or false to stop parsing.
|
|
|
|
* @param user_data User data to be passed to the callback.
|
|
|
|
*/
|
|
|
|
void bt_data_parse(struct net_buf_simple *ad,
|
|
|
|
bool (*func)(struct bt_data *data, void *user_data),
|
|
|
|
void *user_data);
|
|
|
|
|
2020-03-10 14:15:36 +01:00
|
|
|
/** LE Secure Connections pairing Out of Band data. */
|
2019-03-12 10:57:42 +01:00
|
|
|
struct bt_le_oob_sc_data {
|
|
|
|
/** Random Number. */
|
2020-05-27 18:26:57 +02:00
|
|
|
uint8_t r[16];
|
2019-03-12 10:57:42 +01:00
|
|
|
|
|
|
|
/** Confirm Value. */
|
2020-05-27 18:26:57 +02:00
|
|
|
uint8_t c[16];
|
2019-03-12 10:57:42 +01:00
|
|
|
};
|
|
|
|
|
2020-03-10 14:15:36 +01:00
|
|
|
/** LE Out of Band information. */
|
2016-07-20 12:07:46 +02:00
|
|
|
struct bt_le_oob {
|
2020-03-10 14:15:36 +01:00
|
|
|
/** LE address. If privacy is enabled this is a Resolvable Private
|
2016-07-22 12:26:01 +02:00
|
|
|
* Address.
|
2016-07-20 12:07:46 +02:00
|
|
|
*/
|
2016-07-22 12:26:01 +02:00
|
|
|
bt_addr_le_t addr;
|
2019-03-12 10:57:42 +01:00
|
|
|
|
2020-03-10 14:15:36 +01:00
|
|
|
/** LE Secure Connections pairing Out of Band data. */
|
2019-03-12 10:57:42 +01:00
|
|
|
struct bt_le_oob_sc_data le_sc_data;
|
2016-07-20 12:07:46 +02:00
|
|
|
};
|
|
|
|
|
2020-03-10 14:15:36 +01:00
|
|
|
/** @brief Get local LE Out of Band (OOB) information.
|
2016-07-20 12:07:46 +02:00
|
|
|
*
|
2020-03-10 14:15:36 +01:00
|
|
|
* This function allows to get local information that are useful for
|
|
|
|
* Out of Band pairing or connection creation.
|
2016-07-20 12:07:46 +02:00
|
|
|
*
|
2020-03-10 14:15:36 +01:00
|
|
|
* If privacy :option:`CONFIG_BT_PRIVACY` is enabled this will result in
|
|
|
|
* generating new Resolvable Private Address (RPA) that is valid for
|
|
|
|
* :option:`CONFIG_BT_RPA_TIMEOUT` seconds. This address will be used for
|
2020-02-01 18:27:39 +01:00
|
|
|
* advertising started by @ref bt_le_adv_start, active scanning and
|
|
|
|
* connection creation.
|
2016-07-20 12:07:46 +02:00
|
|
|
*
|
2020-03-10 14:16:43 +01:00
|
|
|
* @note If privacy is enabled the RPA cannot be refreshed in the following
|
|
|
|
* cases:
|
|
|
|
* - Creating a connection in progress, wait for the connected callback.
|
2020-02-01 18:27:39 +01:00
|
|
|
* In addition when extended advertising :option:`CONFIG_BT_EXT_ADV` is
|
2020-04-18 18:30:12 +02:00
|
|
|
* not enabled or not supported by the controller:
|
2020-03-10 14:16:43 +01:00
|
|
|
* - Advertiser is enabled using a Random Static Identity Address for a
|
|
|
|
* different local identity.
|
|
|
|
* - The local identity conflicts with the local identity used by other
|
|
|
|
* roles.
|
|
|
|
*
|
2020-03-10 14:15:36 +01:00
|
|
|
* @param[in] id Local identity, in most cases BT_ID_DEFAULT.
|
|
|
|
* @param[out] oob LE OOB information
|
2019-03-12 10:57:42 +01:00
|
|
|
*
|
2020-03-17 10:32:20 +01:00
|
|
|
* @return Zero on success or error code otherwise, positive in case of
|
|
|
|
* protocol error or negative (POSIX) in case of stack internal error.
|
2016-07-20 12:07:46 +02:00
|
|
|
*/
|
2020-05-27 18:26:57 +02:00
|
|
|
int bt_le_oob_get_local(uint8_t id, struct bt_le_oob *oob);
|
2016-07-20 12:07:46 +02:00
|
|
|
|
2020-02-01 18:27:39 +01:00
|
|
|
/** @brief Get local LE Out of Band (OOB) information.
|
|
|
|
*
|
|
|
|
* This function allows to get local information that are useful for
|
|
|
|
* Out of Band pairing or connection creation.
|
|
|
|
*
|
|
|
|
* If privacy :option:`CONFIG_BT_PRIVACY` is enabled this will result in
|
|
|
|
* generating new Resolvable Private Address (RPA) that is valid for
|
|
|
|
* :option:`CONFIG_BT_RPA_TIMEOUT` seconds. This address will be used by the
|
|
|
|
* advertising set.
|
|
|
|
*
|
|
|
|
* @note When generating OOB information for multiple advertising set all
|
|
|
|
* OOB information needs to be generated at the same time.
|
|
|
|
*
|
|
|
|
* @note If privacy is enabled the RPA cannot be refreshed in the following
|
|
|
|
* cases:
|
|
|
|
* - Creating a connection in progress, wait for the connected callback.
|
|
|
|
*
|
|
|
|
* @param[in] adv The advertising set object
|
|
|
|
* @param[out] oob LE OOB information
|
|
|
|
*
|
|
|
|
* @return Zero on success or error code otherwise, positive in case
|
|
|
|
* of protocol error or negative (POSIX) in case of stack internal error.
|
|
|
|
*/
|
|
|
|
int bt_le_ext_adv_oob_get_local(struct bt_le_ext_adv *adv,
|
|
|
|
struct bt_le_oob *oob);
|
|
|
|
|
2016-03-10 11:58:56 +01:00
|
|
|
/** @brief BR/EDR discovery result structure */
|
|
|
|
struct bt_br_discovery_result {
|
2016-03-17 18:35:58 +01:00
|
|
|
/** private */
|
2020-05-27 18:26:57 +02:00
|
|
|
uint8_t _priv[4];
|
2016-03-17 18:35:58 +01:00
|
|
|
|
2016-03-10 11:58:56 +01:00
|
|
|
/** Remote device address */
|
|
|
|
bt_addr_t addr;
|
|
|
|
|
|
|
|
/** RSSI from inquiry */
|
2020-05-27 18:26:57 +02:00
|
|
|
int8_t rssi;
|
2016-03-10 11:58:56 +01:00
|
|
|
|
|
|
|
/** Class of Device */
|
2020-05-27 18:26:57 +02:00
|
|
|
uint8_t cod[3];
|
2016-03-10 11:58:56 +01:00
|
|
|
|
|
|
|
/** Extended Inquiry Response */
|
2020-05-27 18:26:57 +02:00
|
|
|
uint8_t eir[240];
|
2016-03-10 11:58:56 +01:00
|
|
|
};
|
|
|
|
|
2016-06-16 19:24:28 +02:00
|
|
|
/** @typedef bt_br_discovery_cb_t
|
|
|
|
* @brief Callback type for reporting BR/EDR discovery (inquiry)
|
2016-06-16 08:56:54 +02:00
|
|
|
* results.
|
2016-03-10 11:58:56 +01:00
|
|
|
*
|
2016-06-16 08:56:54 +02:00
|
|
|
* A callback of this type is given to the bt_br_discovery_start()
|
|
|
|
* function and will be called at the end of the discovery with
|
|
|
|
* information about found devices populated in the results array.
|
2016-03-10 11:58:56 +01:00
|
|
|
*
|
|
|
|
* @param results Storage used for discovery results
|
|
|
|
* @param count Number of valid discovery results.
|
|
|
|
*/
|
|
|
|
typedef void bt_br_discovery_cb_t(struct bt_br_discovery_result *results,
|
|
|
|
size_t count);
|
|
|
|
|
|
|
|
/** BR/EDR discovery parameters */
|
|
|
|
struct bt_br_discovery_param {
|
2016-06-16 09:21:15 +02:00
|
|
|
/** Maximum length of the discovery in units of 1.28 seconds.
|
|
|
|
* Valid range is 0x01 - 0x30.
|
|
|
|
*/
|
2020-05-27 18:26:57 +02:00
|
|
|
uint8_t length;
|
2016-06-16 09:21:15 +02:00
|
|
|
|
2016-03-10 11:58:56 +01:00
|
|
|
/** True if limited discovery procedure is to be used. */
|
2016-06-16 10:28:59 +02:00
|
|
|
bool limited;
|
2016-03-10 11:58:56 +01:00
|
|
|
};
|
|
|
|
|
|
|
|
/** @brief Start BR/EDR discovery
|
|
|
|
*
|
|
|
|
* Start BR/EDR discovery (inquiry) and provide results through the specified
|
|
|
|
* callback. When bt_br_discovery_cb_t is called it indicates that discovery
|
2016-12-19 18:02:41 +01:00
|
|
|
* has completed. If more inquiry results were received during session than
|
|
|
|
* fits in provided result storage, only ones with highest RSSI will be
|
|
|
|
* reported.
|
2016-03-10 11:58:56 +01:00
|
|
|
*
|
|
|
|
* @param param Discovery parameters.
|
|
|
|
* @param results Storage for discovery results.
|
2016-06-16 09:35:15 +02:00
|
|
|
* @param count Number of results in storage. Valid range: 1-255.
|
2016-03-10 11:58:56 +01:00
|
|
|
* @param cb Callback to notify discovery results.
|
|
|
|
*
|
|
|
|
* @return Zero on success or error code otherwise, positive in case
|
|
|
|
* of protocol error or negative (POSIX) in case of stack internal error
|
|
|
|
*/
|
|
|
|
int bt_br_discovery_start(const struct bt_br_discovery_param *param,
|
|
|
|
struct bt_br_discovery_result *results, size_t count,
|
|
|
|
bt_br_discovery_cb_t cb);
|
|
|
|
|
|
|
|
/** @brief Stop BR/EDR discovery.
|
|
|
|
*
|
|
|
|
* Stops ongoing BR/EDR discovery. If discovery was stopped by this call
|
|
|
|
* results won't be reported
|
|
|
|
*
|
2020-03-17 10:32:20 +01:00
|
|
|
* @return Zero on success or error code otherwise, positive in case of
|
|
|
|
* protocol error or negative (POSIX) in case of stack internal error.
|
2016-03-10 11:58:56 +01:00
|
|
|
*/
|
|
|
|
int bt_br_discovery_stop(void);
|
|
|
|
|
2016-07-20 12:07:46 +02:00
|
|
|
struct bt_br_oob {
|
|
|
|
/** BR/EDR address. */
|
|
|
|
bt_addr_t addr;
|
|
|
|
};
|
|
|
|
|
2020-03-17 10:32:20 +01:00
|
|
|
/** @brief Get BR/EDR local Out Of Band information
|
2016-07-20 12:07:46 +02:00
|
|
|
*
|
2020-03-17 10:32:20 +01:00
|
|
|
* This function allows to get local controller information that are useful
|
|
|
|
* for Out Of Band pairing or connection creation process.
|
2016-07-20 12:07:46 +02:00
|
|
|
*
|
2020-03-17 10:32:20 +01:00
|
|
|
* @param oob Out Of Band information
|
2016-07-20 12:07:46 +02:00
|
|
|
*/
|
|
|
|
int bt_br_oob_get_local(struct bt_br_oob *oob);
|
|
|
|
|
2015-07-01 22:47:13 +02:00
|
|
|
/** @def BT_ADDR_STR_LEN
|
2015-06-17 15:46:38 +02:00
|
|
|
*
|
2015-06-17 22:17:43 +02:00
|
|
|
* @brief Recommended length of user string buffer for Bluetooth address
|
2015-06-17 15:46:38 +02:00
|
|
|
*
|
2015-06-18 09:43:23 +02:00
|
|
|
* @details The recommended length guarantee the output of address
|
|
|
|
* conversion will not lose valuable information about address being
|
|
|
|
* processed.
|
2015-06-17 15:46:38 +02:00
|
|
|
*/
|
|
|
|
#define BT_ADDR_STR_LEN 18
|
|
|
|
|
2015-07-01 22:47:13 +02:00
|
|
|
/** @def BT_ADDR_LE_STR_LEN
|
2015-06-17 15:46:38 +02:00
|
|
|
*
|
2015-06-17 22:17:43 +02:00
|
|
|
* @brief Recommended length of user string buffer for Bluetooth LE address
|
2015-06-17 15:46:38 +02:00
|
|
|
*
|
2015-06-18 09:43:23 +02:00
|
|
|
* @details The recommended length guarantee the output of address
|
|
|
|
* conversion will not lose valuable information about address being
|
|
|
|
* processed.
|
2015-06-17 15:46:38 +02:00
|
|
|
*/
|
2019-08-05 10:26:07 +02:00
|
|
|
#define BT_ADDR_LE_STR_LEN 30
|
2015-06-17 15:46:38 +02:00
|
|
|
|
2015-07-01 22:47:13 +02:00
|
|
|
/** @brief Converts binary Bluetooth address to string.
|
2015-06-17 15:46:38 +02:00
|
|
|
*
|
2015-06-17 22:17:43 +02:00
|
|
|
* @param addr Address of buffer containing binary Bluetooth address.
|
2015-06-17 15:46:38 +02:00
|
|
|
* @param str Address of user buffer with enough room to store formatted
|
|
|
|
* string containing binary address.
|
|
|
|
* @param len Length of data to be copied to user string buffer. Refer to
|
|
|
|
* BT_ADDR_STR_LEN about recommended value.
|
|
|
|
*
|
|
|
|
* @return Number of successfully formatted bytes from binary address.
|
|
|
|
*/
|
|
|
|
static inline int bt_addr_to_str(const bt_addr_t *addr, char *str, size_t len)
|
|
|
|
{
|
2016-12-07 17:39:47 +01:00
|
|
|
return snprintk(str, len, "%02X:%02X:%02X:%02X:%02X:%02X",
|
2015-06-17 15:46:38 +02:00
|
|
|
addr->val[5], addr->val[4], addr->val[3],
|
|
|
|
addr->val[2], addr->val[1], addr->val[0]);
|
|
|
|
}
|
|
|
|
|
2015-07-01 22:47:13 +02:00
|
|
|
/** @brief Converts binary LE Bluetooth address to string.
|
2015-06-17 15:46:38 +02:00
|
|
|
*
|
2015-06-17 22:17:43 +02:00
|
|
|
* @param addr Address of buffer containing binary LE Bluetooth address.
|
2016-02-11 19:20:12 +01:00
|
|
|
* @param str Address of user buffer with enough room to store
|
2015-06-18 09:43:23 +02:00
|
|
|
* formatted string containing binary LE address.
|
2015-06-17 15:46:38 +02:00
|
|
|
* @param len Length of data to be copied to user string buffer. Refer to
|
|
|
|
* BT_ADDR_LE_STR_LEN about recommended value.
|
|
|
|
*
|
|
|
|
* @return Number of successfully formatted bytes from binary address.
|
|
|
|
*/
|
|
|
|
static inline int bt_addr_le_to_str(const bt_addr_le_t *addr, char *str,
|
|
|
|
size_t len)
|
|
|
|
{
|
2017-10-03 13:54:59 +02:00
|
|
|
char type[10];
|
2015-06-17 15:46:38 +02:00
|
|
|
|
|
|
|
switch (addr->type) {
|
|
|
|
case BT_ADDR_LE_PUBLIC:
|
|
|
|
strcpy(type, "public");
|
|
|
|
break;
|
|
|
|
case BT_ADDR_LE_RANDOM:
|
|
|
|
strcpy(type, "random");
|
|
|
|
break;
|
2017-10-03 13:54:59 +02:00
|
|
|
case BT_ADDR_LE_PUBLIC_ID:
|
2019-05-29 10:50:08 +02:00
|
|
|
strcpy(type, "public-id");
|
2017-10-03 13:54:59 +02:00
|
|
|
break;
|
|
|
|
case BT_ADDR_LE_RANDOM_ID:
|
2019-05-29 10:50:08 +02:00
|
|
|
strcpy(type, "random-id");
|
2017-10-03 13:54:59 +02:00
|
|
|
break;
|
2015-06-17 15:46:38 +02:00
|
|
|
default:
|
2016-12-06 20:46:10 +01:00
|
|
|
snprintk(type, sizeof(type), "0x%02x", addr->type);
|
2015-06-17 15:46:38 +02:00
|
|
|
break;
|
|
|
|
}
|
|
|
|
|
2016-12-07 17:39:47 +01:00
|
|
|
return snprintk(str, len, "%02X:%02X:%02X:%02X:%02X:%02X (%s)",
|
2016-04-04 12:06:55 +02:00
|
|
|
addr->a.val[5], addr->a.val[4], addr->a.val[3],
|
|
|
|
addr->a.val[2], addr->a.val[1], addr->a.val[0], type);
|
2015-06-17 15:46:38 +02:00
|
|
|
}
|
2015-11-26 14:47:11 +01:00
|
|
|
|
2020-03-17 10:32:20 +01:00
|
|
|
/** @brief Convert Bluetooth address from string to binary.
|
2019-05-29 10:50:08 +02:00
|
|
|
*
|
2020-03-17 10:32:20 +01:00
|
|
|
* @param[in] str The string representation of a Bluetooth address.
|
|
|
|
* @param[out] addr Address of buffer to store the Bluetooth address
|
2019-05-29 10:50:08 +02:00
|
|
|
*
|
|
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
|
|
*/
|
|
|
|
int bt_addr_from_str(const char *str, bt_addr_t *addr);
|
|
|
|
|
2020-03-17 10:32:20 +01:00
|
|
|
/** @brief Convert LE Bluetooth address from string to binary.
|
2019-05-29 10:50:08 +02:00
|
|
|
*
|
2020-03-17 10:32:20 +01:00
|
|
|
* @param[in] str The string representation of an LE Bluetooth address.
|
|
|
|
* @param[in] type The string representation of the LE Bluetooth address
|
|
|
|
* type.
|
|
|
|
* @param[out] addr Address of buffer to store the LE Bluetooth address
|
2019-05-29 10:50:08 +02:00
|
|
|
*
|
|
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
|
|
*/
|
|
|
|
int bt_addr_le_from_str(const char *str, const char *type, bt_addr_le_t *addr);
|
|
|
|
|
2015-11-26 14:47:11 +01:00
|
|
|
/** @brief Enable/disable set controller in discoverable state.
|
|
|
|
*
|
|
|
|
* Allows make local controller to listen on INQUIRY SCAN channel and responds
|
|
|
|
* to devices making general inquiry. To enable this state it's mandatory
|
|
|
|
* to first be in connectable state.
|
|
|
|
*
|
|
|
|
* @param enable Value allowing/disallowing controller to become discoverable.
|
|
|
|
*
|
|
|
|
* @return Negative if fail set to requested state or requested state has been
|
2020-03-17 10:32:20 +01:00
|
|
|
* already set. Zero if done successfully.
|
2015-11-26 14:47:11 +01:00
|
|
|
*/
|
2015-12-03 09:35:25 +01:00
|
|
|
int bt_br_set_discoverable(bool enable);
|
2015-11-26 14:47:11 +01:00
|
|
|
|
|
|
|
/** @brief Enable/disable set controller in connectable state.
|
|
|
|
*
|
|
|
|
* Allows make local controller to be connectable. It means the controller
|
|
|
|
* start listen to devices requests on PAGE SCAN channel. If disabled also
|
|
|
|
* resets discoverability if was set.
|
|
|
|
*
|
|
|
|
* @param enable Value allowing/disallowing controller to be connectable.
|
|
|
|
*
|
|
|
|
* @return Negative if fail set to requested state or requested state has been
|
2020-03-17 10:32:20 +01:00
|
|
|
* already set. Zero if done successfully.
|
2015-11-26 14:47:11 +01:00
|
|
|
*/
|
2015-12-03 09:35:25 +01:00
|
|
|
int bt_br_set_connectable(bool enable);
|
2016-01-22 18:38:49 +01:00
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Clear pairing information.
|
|
|
|
*
|
|
|
|
* @param id Local identity (mostly just BT_ID_DEFAULT).
|
|
|
|
* @param addr Remote address, NULL or BT_ADDR_LE_ANY to clear all remote
|
|
|
|
* devices.
|
|
|
|
*
|
|
|
|
* @return 0 on success or negative error value on failure.
|
|
|
|
*/
|
2020-05-27 18:26:57 +02:00
|
|
|
int bt_unpair(uint8_t id, const bt_addr_le_t *addr);
|
2018-04-27 09:31:13 +02:00
|
|
|
|
2018-09-20 14:19:40 +02:00
|
|
|
/** Information about a bond with a remote device. */
|
|
|
|
struct bt_bond_info {
|
|
|
|
/** Address of the remote device. */
|
|
|
|
bt_addr_le_t addr;
|
|
|
|
};
|
|
|
|
|
2020-04-28 19:47:46 +02:00
|
|
|
/** @brief Iterate through all existing bonds.
|
|
|
|
*
|
|
|
|
* @param id Local identity (mostly just BT_ID_DEFAULT).
|
|
|
|
* @param func Function to call for each bond.
|
|
|
|
* @param user_data Data to pass to the callback function.
|
|
|
|
*/
|
2020-05-27 18:26:57 +02:00
|
|
|
void bt_foreach_bond(uint8_t id, void (*func)(const struct bt_bond_info *info,
|
2018-09-20 14:19:40 +02:00
|
|
|
void *user_data),
|
|
|
|
void *user_data);
|
|
|
|
|
2016-06-15 10:03:11 +02:00
|
|
|
/**
|
|
|
|
* @}
|
|
|
|
*/
|
|
|
|
|
2016-01-22 18:38:49 +01:00
|
|
|
#ifdef __cplusplus
|
|
|
|
}
|
|
|
|
#endif
|
2016-05-16 18:54:24 +02:00
|
|
|
/**
|
|
|
|
* @}
|
|
|
|
*/
|
|
|
|
|
2018-09-14 19:43:44 +02:00
|
|
|
#endif /* ZEPHYR_INCLUDE_BLUETOOTH_BLUETOOTH_H_ */
|