a6fa3fb3aa
These constants are based on (i.e. exactly as) the recommended values for regular (i.e. non-periodic) advertising. The GAP spec does not actually specifiy these numbers (or any numbers for periodic advertising), but they are sane numbers to use for periodic advertisement. The issue with using the non-periodic advertising whereas the peridic advertising unit is 1.25ms. Signed-off-by: Emil Gydesen <emil.gydesen@nordicsemi.no>
2164 lines
68 KiB
C
2164 lines
68 KiB
C
/** @file
|
|
* @brief Bluetooth subsystem core APIs.
|
|
*/
|
|
|
|
/*
|
|
* Copyright (c) 2017 Nordic Semiconductor ASA
|
|
* Copyright (c) 2015-2016 Intel Corporation
|
|
*
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*/
|
|
#ifndef ZEPHYR_INCLUDE_BLUETOOTH_BLUETOOTH_H_
|
|
#define ZEPHYR_INCLUDE_BLUETOOTH_BLUETOOTH_H_
|
|
|
|
/**
|
|
* @brief Bluetooth APIs
|
|
* @defgroup bluetooth Bluetooth APIs
|
|
* @{
|
|
*/
|
|
|
|
#include <stdbool.h>
|
|
#include <string.h>
|
|
#include <sys/util.h>
|
|
#include <net/buf.h>
|
|
#include <bluetooth/gap.h>
|
|
#include <bluetooth/addr.h>
|
|
#include <bluetooth/crypto.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* @brief Generic Access Profile
|
|
* @defgroup bt_gap Generic Access Profile
|
|
* @ingroup bluetooth
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* @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
|
|
|
|
/** Opaque type representing an advertiser. */
|
|
struct bt_le_ext_adv;
|
|
|
|
/** Opaque type representing an periodic advertising sync. */
|
|
struct bt_le_per_adv_sync;
|
|
|
|
/* Don't require everyone to include conn.h */
|
|
struct bt_conn;
|
|
|
|
/* Don't require everyone to include iso.h */
|
|
struct bt_iso_biginfo;
|
|
|
|
/* Don't require everyone to include direction.h */
|
|
struct bt_df_per_adv_sync_iq_samples_report;
|
|
|
|
struct bt_le_ext_adv_sent_info {
|
|
/** The number of advertising events completed. */
|
|
uint8_t num_sent;
|
|
};
|
|
|
|
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);
|
|
};
|
|
|
|
/**
|
|
* @typedef bt_ready_cb_t
|
|
* @brief Callback for notifying that Bluetooth has been enabled.
|
|
*
|
|
* @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.
|
|
*
|
|
* When @kconfig{CONFIG_BT_SETTINGS} has been enabled and the application is not
|
|
* managing identities of the stack itself then the application must call
|
|
* @ref settings_load() before the stack is fully enabled.
|
|
* See @ref bt_id_create() for more information.
|
|
*
|
|
* @param cb Callback to notify completion or NULL to perform the
|
|
* enabling synchronously.
|
|
*
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
*/
|
|
int bt_enable(bt_ready_cb_t cb);
|
|
|
|
/**
|
|
* @brief Set Bluetooth Device Name
|
|
*
|
|
* Set Bluetooth GAP Device Name.
|
|
*
|
|
* When advertising with device name in the advertising data the name should
|
|
* be updated by calling @ref bt_le_adv_update_data or
|
|
* @ref bt_le_ext_adv_set_data.
|
|
*
|
|
* @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);
|
|
|
|
/**
|
|
* @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.
|
|
*
|
|
* If @a addrs is passed as NULL, then returned @a count contains the
|
|
* count of all available identities that can be retrieved with a
|
|
* subsequent call to this function with non-NULL @a addrs parameter.
|
|
*
|
|
* @note Deleted identities may show up as BT_LE_ADDR_ANY in the returned
|
|
* array.
|
|
*
|
|
* @param addrs Array where to store the configured identities.
|
|
* @param count Should be initialized to the array size. Once the function
|
|
* returns it will contain the number of returned identities.
|
|
*/
|
|
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.
|
|
*
|
|
* Generating random static address or random IRK is not supported when calling
|
|
* this function before bt_enable().
|
|
*
|
|
* 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.
|
|
*
|
|
* @param addr Address to use for the new identity. If NULL or initialized
|
|
* to BT_ADDR_LE_ANY the stack will generate a new random
|
|
* static 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
|
|
* the parameter was non-NULL). If privacy
|
|
* @kconfig{CONFIG_BT_PRIVACY} is not enabled this parameter must
|
|
* be NULL.
|
|
*
|
|
* @return Identity identifier (>= 0) in case of success, or a negative
|
|
* error code on failure.
|
|
*/
|
|
int bt_id_create(bt_addr_le_t *addr, uint8_t *irk);
|
|
|
|
/**
|
|
* @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.
|
|
*
|
|
* @note the default identity (BT_ID_DEFAULT) cannot be reset, i.e. this
|
|
* 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
|
|
* the parameter was non-NULL). If privacy
|
|
* @kconfig{CONFIG_BT_PRIVACY} is not enabled this parameter must
|
|
* be NULL.
|
|
*
|
|
* @return Identity identifier (>= 0) in case of success, or a negative
|
|
* error code on failure.
|
|
*/
|
|
int bt_id_reset(uint8_t id, bt_addr_le_t *addr, uint8_t *irk);
|
|
|
|
/**
|
|
* @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.
|
|
*
|
|
* @note the default identity (BT_ID_DEFAULT) cannot be deleted, i.e. this
|
|
* 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.
|
|
*/
|
|
int bt_id_delete(uint8_t id);
|
|
|
|
/**
|
|
* @brief Bluetooth data.
|
|
*
|
|
* Description of different data types that can be encoded into
|
|
* advertising data. Used to form arrays that are passed to the
|
|
* bt_le_adv_start() function.
|
|
*/
|
|
struct bt_data {
|
|
uint8_t type;
|
|
uint8_t data_len;
|
|
const uint8_t *data;
|
|
};
|
|
|
|
/**
|
|
* @brief Helper to declare elements of bt_data arrays
|
|
*
|
|
* This macro is mainly for creating an array of struct bt_data
|
|
* elements which is then passed to e.g. @ref bt_le_adv_start().
|
|
*
|
|
* @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
|
|
*/
|
|
#define BT_DATA(_type, _data, _data_len) \
|
|
{ \
|
|
.type = (_type), \
|
|
.data_len = (_data_len), \
|
|
.data = (const uint8_t *)(_data), \
|
|
}
|
|
|
|
/**
|
|
* @brief Helper to declare elements of bt_data arrays
|
|
*
|
|
* This macro is mainly for creating an array of struct bt_data
|
|
* elements which is then passed to e.g. @ref bt_le_adv_start().
|
|
*
|
|
* @param _type Type of advertising data field
|
|
* @param _bytes Variable number of single-byte parameters
|
|
*/
|
|
#define BT_DATA_BYTES(_type, _bytes...) \
|
|
BT_DATA(_type, ((uint8_t []) { _bytes }), \
|
|
sizeof((uint8_t []) { _bytes }))
|
|
|
|
/** Advertising options */
|
|
enum {
|
|
/** Convenience value when no options are specified. */
|
|
BT_LE_ADV_OPT_NONE = 0,
|
|
|
|
/**
|
|
* @brief Advertise as connectable.
|
|
*
|
|
* Advertise as connectable. If not connectable then the type of
|
|
* advertising is determined by providing scan response data.
|
|
* The advertiser address is determined by the type of advertising
|
|
* and/or enabling privacy @kconfig{CONFIG_BT_PRIVACY}.
|
|
*/
|
|
BT_LE_ADV_OPT_CONNECTABLE = BIT(0),
|
|
|
|
/**
|
|
* @brief Advertise one time.
|
|
*
|
|
* Don't try to resume connectable advertising after a connection.
|
|
* 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.
|
|
* 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.
|
|
*/
|
|
BT_LE_ADV_OPT_ONE_TIME = BIT(1),
|
|
|
|
/**
|
|
* @brief Advertise using identity address.
|
|
*
|
|
* Advertise using the identity address as the advertiser address.
|
|
* @warning This will compromise the privacy of the device, so care
|
|
* must be taken when using this option.
|
|
* @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.
|
|
*/
|
|
BT_LE_ADV_OPT_USE_IDENTITY = BIT(2),
|
|
|
|
/** Advertise using GAP device name.
|
|
*
|
|
* Include the GAP device name automatically when advertising.
|
|
* By default the GAP device name is put at the end of the scan
|
|
* response data.
|
|
* When advertising using @ref BT_LE_ADV_OPT_EXT_ADV and not
|
|
* @ref BT_LE_ADV_OPT_SCANNABLE then it will be put at the end of the
|
|
* advertising data.
|
|
* If the GAP device name does not fit into advertising data it will be
|
|
* converted to a shortened name if possible.
|
|
* @ref BT_LE_ADV_OPT_FORCE_NAME_IN_AD can be used to force the device
|
|
* name to appear in the advertising data of an advert with scan
|
|
* response data.
|
|
*
|
|
* The application can set the device name itself by including the
|
|
* following in the advertising data.
|
|
* @code
|
|
* BT_DATA(BT_DATA_NAME_COMPLETE, name, strlen(name))
|
|
* @endcode
|
|
*/
|
|
BT_LE_ADV_OPT_USE_NAME = BIT(3),
|
|
|
|
/**
|
|
* @brief Low duty cycle directed advertising.
|
|
*
|
|
* Use low duty directed advertising mode, otherwise high duty mode
|
|
* will be used.
|
|
*/
|
|
BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY = BIT(4),
|
|
|
|
/**
|
|
* @brief Directed advertising to privacy-enabled peer.
|
|
*
|
|
* Enable use of Resolvable Private Address (RPA) as the target address
|
|
* in directed advertisements.
|
|
* 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),
|
|
|
|
/** Use whitelist to filter devices that can request scan response data.
|
|
*/
|
|
BT_LE_ADV_OPT_FILTER_SCAN_REQ = BIT(6),
|
|
|
|
/** Use whitelist to filter devices that can connect. */
|
|
BT_LE_ADV_OPT_FILTER_CONN = BIT(7),
|
|
|
|
/** Notify the application when a scan response data has been sent to an
|
|
* active scanner.
|
|
*/
|
|
BT_LE_ADV_OPT_NOTIFY_SCAN_REQ = BIT(8),
|
|
|
|
/**
|
|
* @brief Support scan response data.
|
|
*
|
|
* 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),
|
|
|
|
/**
|
|
* @brief Advertise with extended advertising.
|
|
*
|
|
* 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.
|
|
* Connections will be established on LE 2M PHY.
|
|
*
|
|
* 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),
|
|
|
|
/**
|
|
* @brief Disable use of LE 2M PHY on the secondary advertising
|
|
* channel.
|
|
*
|
|
* 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.
|
|
* Connections will be established on LE 1M PHY.
|
|
*
|
|
* @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),
|
|
|
|
/**
|
|
* @brief Advertise on the LE Coded PHY (Long Range).
|
|
*
|
|
* 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.
|
|
* Connections will be established on LE Coded PHY.
|
|
*
|
|
* @note Requires @ref BT_LE_ADV_OPT_EXT_ADV
|
|
*/
|
|
BT_LE_ADV_OPT_CODED = BIT(12),
|
|
|
|
/**
|
|
* @brief Advertise without a device address (identity or RPA).
|
|
*
|
|
* @note Requires @ref BT_LE_ADV_OPT_EXT_ADV
|
|
*/
|
|
BT_LE_ADV_OPT_ANONYMOUS = BIT(13),
|
|
|
|
/**
|
|
* @brief Advertise with transmit power.
|
|
*
|
|
* @note Requires @ref BT_LE_ADV_OPT_EXT_ADV
|
|
*/
|
|
BT_LE_ADV_OPT_USE_TX_POWER = BIT(14),
|
|
|
|
/** Disable advertising on channel index 37. */
|
|
BT_LE_ADV_OPT_DISABLE_CHAN_37 = BIT(15),
|
|
|
|
/** Disable advertising on channel index 38. */
|
|
BT_LE_ADV_OPT_DISABLE_CHAN_38 = BIT(16),
|
|
|
|
/** Disable advertising on channel index 39. */
|
|
BT_LE_ADV_OPT_DISABLE_CHAN_39 = BIT(17),
|
|
|
|
/**
|
|
* @brief Put GAP device name into advert data
|
|
*
|
|
* Will place the GAP device name into the advertising data rather
|
|
* than the scan response data.
|
|
*
|
|
* @note Requires @ref BT_LE_ADV_OPT_USE_NAME
|
|
*/
|
|
BT_LE_ADV_OPT_FORCE_NAME_IN_AD = BIT(18),
|
|
};
|
|
|
|
/** LE Advertising Parameters. */
|
|
struct bt_le_adv_param {
|
|
/**
|
|
* @brief Local identity.
|
|
*
|
|
* @note When extended advertising @kconfig{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.
|
|
*/
|
|
uint8_t id;
|
|
|
|
/**
|
|
* @brief Advertising Set Identifier, valid range 0x00 - 0x0f.
|
|
*
|
|
* @note Requires @ref BT_LE_ADV_OPT_EXT_ADV
|
|
**/
|
|
uint8_t sid;
|
|
|
|
/**
|
|
* @brief Secondary channel maximum skip count.
|
|
*
|
|
* Maximum advertising events the advertiser can skip before it must
|
|
* send advertising data on the secondary advertising channel.
|
|
*
|
|
* @note Requires @ref BT_LE_ADV_OPT_EXT_ADV
|
|
*/
|
|
uint8_t secondary_max_skip;
|
|
|
|
/** Bit-field of advertising options */
|
|
uint32_t options;
|
|
|
|
/** Minimum Advertising Interval (N * 0.625 milliseconds)
|
|
* Minimum Advertising Interval shall be less than or equal to the
|
|
* Maximum Advertising Interval. The Minimum Advertising Interval and
|
|
* Maximum Advertising Interval should not be the same value (as stated
|
|
* in Bluetooth Core Spec 5.2, section 7.8.5)
|
|
* Range: 0x0020 to 0x4000
|
|
*/
|
|
uint32_t interval_min;
|
|
|
|
/** Maximum Advertising Interval (N * 0.625 milliseconds)
|
|
* Minimum Advertising Interval shall be less than or equal to the
|
|
* Maximum Advertising Interval. The Minimum Advertising Interval and
|
|
* Maximum Advertising Interval should not be the same value (as stated
|
|
* in Bluetooth Core Spec 5.2, section 7.8.5)
|
|
* Range: 0x0020 to 0x4000
|
|
*/
|
|
uint32_t interval_max;
|
|
|
|
/**
|
|
* @brief Directed advertising to peer
|
|
*
|
|
* 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.
|
|
* When using @ref BT_LE_ADV_OPT_EXT_ADV then only low duty cycle is
|
|
* allowed.
|
|
*
|
|
* 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;
|
|
};
|
|
|
|
|
|
/** Periodic Advertising options */
|
|
enum {
|
|
/** Convenience value when no options are specified. */
|
|
BT_LE_PER_ADV_OPT_NONE = 0,
|
|
|
|
/**
|
|
* @brief Advertise with transmit power.
|
|
*
|
|
* @note Requires @ref BT_LE_ADV_OPT_EXT_ADV
|
|
*/
|
|
BT_LE_PER_ADV_OPT_USE_TX_POWER = BIT(1),
|
|
};
|
|
|
|
struct bt_le_per_adv_param {
|
|
/**
|
|
* @brief Minimum Periodic Advertising Interval (N * 1.25 ms)
|
|
*
|
|
* Shall be greater or equal to BT_GAP_PER_ADV_MIN_INTERVAL and
|
|
* less or equal to interval_max.
|
|
*/
|
|
uint16_t interval_min;
|
|
|
|
/**
|
|
* @brief Maximum Periodic Advertising Interval (N * 1.25 ms)
|
|
*
|
|
* Shall be less or equal to BT_GAP_PER_ADV_MAX_INTERVAL and
|
|
* greater or equal to interval_min.
|
|
*/
|
|
uint16_t interval_max;
|
|
|
|
/** Bit-field of periodic advertising options */
|
|
uint32_t options;
|
|
};
|
|
|
|
/**
|
|
* @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), \
|
|
}
|
|
|
|
/**
|
|
* @brief Helper to declare advertising parameters inline
|
|
*
|
|
* @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(_options, _int_min, _int_max, _peer) \
|
|
((struct bt_le_adv_param[]) { \
|
|
BT_LE_ADV_PARAM_INIT(_options, _int_min, _int_max, _peer) \
|
|
})
|
|
|
|
#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)
|
|
|
|
|
|
#define BT_LE_ADV_CONN BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONNECTABLE, \
|
|
BT_GAP_ADV_FAST_INT_MIN_2, \
|
|
BT_GAP_ADV_FAST_INT_MAX_2, NULL)
|
|
|
|
#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, \
|
|
BT_GAP_ADV_FAST_INT_MAX_2, NULL)
|
|
|
|
#define BT_LE_ADV_CONN_NAME_AD BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONNECTABLE | \
|
|
BT_LE_ADV_OPT_USE_NAME | \
|
|
BT_LE_ADV_OPT_FORCE_NAME_IN_AD, \
|
|
BT_GAP_ADV_FAST_INT_MIN_2, \
|
|
BT_GAP_ADV_FAST_INT_MAX_2, NULL)
|
|
|
|
#define BT_LE_ADV_CONN_DIR_LOW_DUTY(_peer) \
|
|
BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONNECTABLE | BT_LE_ADV_OPT_ONE_TIME | \
|
|
BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY, \
|
|
BT_GAP_ADV_FAST_INT_MIN_2, BT_GAP_ADV_FAST_INT_MAX_2, \
|
|
_peer)
|
|
|
|
/** Non-connectable advertising with private address */
|
|
#define BT_LE_ADV_NCONN BT_LE_ADV_PARAM(0, BT_GAP_ADV_FAST_INT_MIN_2, \
|
|
BT_GAP_ADV_FAST_INT_MAX_2, NULL)
|
|
|
|
/** Non-connectable advertising with @ref BT_LE_ADV_OPT_USE_NAME */
|
|
#define BT_LE_ADV_NCONN_NAME BT_LE_ADV_PARAM(BT_LE_ADV_OPT_USE_NAME, \
|
|
BT_GAP_ADV_FAST_INT_MIN_2, \
|
|
BT_GAP_ADV_FAST_INT_MAX_2, NULL)
|
|
|
|
/** Non-connectable advertising with @ref BT_LE_ADV_OPT_USE_IDENTITY */
|
|
#define BT_LE_ADV_NCONN_IDENTITY BT_LE_ADV_PARAM(BT_LE_ADV_OPT_USE_IDENTITY, \
|
|
BT_GAP_ADV_FAST_INT_MIN_2, \
|
|
BT_GAP_ADV_FAST_INT_MAX_2, \
|
|
NULL)
|
|
|
|
/** Connectable extended advertising with @ref BT_LE_ADV_OPT_USE_NAME */
|
|
#define BT_LE_EXT_ADV_CONN_NAME BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | \
|
|
BT_LE_ADV_OPT_CONNECTABLE | \
|
|
BT_LE_ADV_OPT_USE_NAME, \
|
|
BT_GAP_ADV_FAST_INT_MIN_2, \
|
|
BT_GAP_ADV_FAST_INT_MAX_2, \
|
|
NULL)
|
|
|
|
/** Scannable extended advertising with @ref BT_LE_ADV_OPT_USE_NAME */
|
|
#define BT_LE_EXT_ADV_SCAN_NAME BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | \
|
|
BT_LE_ADV_OPT_SCANNABLE | \
|
|
BT_LE_ADV_OPT_USE_NAME, \
|
|
BT_GAP_ADV_FAST_INT_MIN_2, \
|
|
BT_GAP_ADV_FAST_INT_MAX_2, \
|
|
NULL)
|
|
|
|
/** Non-connectable extended advertising with private address */
|
|
#define BT_LE_EXT_ADV_NCONN BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV, \
|
|
BT_GAP_ADV_FAST_INT_MIN_2, \
|
|
BT_GAP_ADV_FAST_INT_MAX_2, NULL)
|
|
|
|
/** Non-connectable extended advertising with @ref BT_LE_ADV_OPT_USE_NAME */
|
|
#define BT_LE_EXT_ADV_NCONN_NAME BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | \
|
|
BT_LE_ADV_OPT_USE_NAME, \
|
|
BT_GAP_ADV_FAST_INT_MIN_2, \
|
|
BT_GAP_ADV_FAST_INT_MAX_2, \
|
|
NULL)
|
|
|
|
/** Non-connectable extended advertising with @ref BT_LE_ADV_OPT_USE_IDENTITY */
|
|
#define BT_LE_EXT_ADV_NCONN_IDENTITY \
|
|
BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | \
|
|
BT_LE_ADV_OPT_USE_IDENTITY, \
|
|
BT_GAP_ADV_FAST_INT_MIN_2, \
|
|
BT_GAP_ADV_FAST_INT_MAX_2, NULL)
|
|
|
|
/** Non-connectable extended advertising on coded PHY with private address */
|
|
#define BT_LE_EXT_ADV_CODED_NCONN BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | \
|
|
BT_LE_ADV_OPT_CODED, \
|
|
BT_GAP_ADV_FAST_INT_MIN_2, \
|
|
BT_GAP_ADV_FAST_INT_MAX_2, \
|
|
NULL)
|
|
|
|
/** Non-connectable extended advertising on coded PHY with
|
|
* @ref BT_LE_ADV_OPT_USE_NAME
|
|
*/
|
|
#define BT_LE_EXT_ADV_CODED_NCONN_NAME \
|
|
BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | BT_LE_ADV_OPT_CODED | \
|
|
BT_LE_ADV_OPT_USE_NAME, \
|
|
BT_GAP_ADV_FAST_INT_MIN_2, \
|
|
BT_GAP_ADV_FAST_INT_MAX_2, NULL)
|
|
|
|
/** Non-connectable extended advertising on coded PHY with
|
|
* @ref BT_LE_ADV_OPT_USE_IDENTITY
|
|
*/
|
|
#define BT_LE_EXT_ADV_CODED_NCONN_IDENTITY \
|
|
BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | BT_LE_ADV_OPT_CODED | \
|
|
BT_LE_ADV_OPT_USE_IDENTITY, \
|
|
BT_GAP_ADV_FAST_INT_MIN_2, \
|
|
BT_GAP_ADV_FAST_INT_MAX_2, NULL)
|
|
|
|
/**
|
|
* Helper to initialize extended advertising start parameters inline
|
|
*
|
|
* @param _timeout Advertiser timeout
|
|
* @param _n_evts Number of advertising events
|
|
*/
|
|
#define BT_LE_EXT_ADV_START_PARAM_INIT(_timeout, _n_evts) \
|
|
{ \
|
|
.timeout = (_timeout), \
|
|
.num_events = (_n_evts), \
|
|
}
|
|
|
|
/**
|
|
* Helper to declare extended advertising start parameters inline
|
|
*
|
|
* @param _timeout Advertiser timeout
|
|
* @param _n_evts Number of advertising events
|
|
*/
|
|
#define BT_LE_EXT_ADV_START_PARAM(_timeout, _n_evts) \
|
|
((struct bt_le_ext_adv_start_param[]) { \
|
|
BT_LE_EXT_ADV_START_PARAM_INIT((_timeout), (_n_evts)) \
|
|
})
|
|
|
|
#define BT_LE_EXT_ADV_START_DEFAULT BT_LE_EXT_ADV_START_PARAM(0, 0)
|
|
|
|
/**
|
|
* Helper to declare periodic advertising parameters inline
|
|
*
|
|
* @param _int_min Minimum periodic advertising interval
|
|
* @param _int_max Maximum periodic advertising interval
|
|
* @param _options Periodic advertising properties bitfield.
|
|
*/
|
|
#define BT_LE_PER_ADV_PARAM_INIT(_int_min, _int_max, _options) \
|
|
{ \
|
|
.interval_min = (_int_min), \
|
|
.interval_max = (_int_max), \
|
|
.options = (_options), \
|
|
}
|
|
|
|
/**
|
|
* Helper to declare periodic advertising parameters inline
|
|
*
|
|
* @param _int_min Minimum periodic advertising interval
|
|
* @param _int_max Maximum periodic advertising interval
|
|
* @param _options Periodic advertising properties bitfield.
|
|
*/
|
|
#define BT_LE_PER_ADV_PARAM(_int_min, _int_max, _options) \
|
|
((struct bt_le_per_adv_param[]) { \
|
|
BT_LE_PER_ADV_PARAM_INIT(_int_min, _int_max, _options) \
|
|
})
|
|
|
|
#define BT_LE_PER_ADV_DEFAULT BT_LE_PER_ADV_PARAM(BT_GAP_PER_ADV_SLOW_INT_MIN, \
|
|
BT_GAP_PER_ADV_SLOW_INT_MAX, \
|
|
BT_LE_PER_ADV_OPT_NONE)
|
|
|
|
/**
|
|
* @brief Start advertising
|
|
*
|
|
* Set advertisement data, scan response data, advertisement parameters
|
|
* and start advertising.
|
|
*
|
|
* 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.
|
|
*
|
|
* @param param Advertising parameters.
|
|
* @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.
|
|
* @return -ENOMEM No free connection objects available for connectable
|
|
* advertiser.
|
|
* @return -ECONNREFUSED When connectable advertising is requested and there
|
|
* 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.
|
|
*/
|
|
int bt_le_adv_start(const struct bt_le_adv_param *param,
|
|
const struct bt_data *ad, size_t ad_len,
|
|
const struct bt_data *sd, size_t sd_len);
|
|
|
|
/**
|
|
* @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);
|
|
|
|
/**
|
|
* @brief Stop advertising
|
|
*
|
|
* Stops ongoing advertising.
|
|
*
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
*/
|
|
int bt_le_adv_stop(void);
|
|
|
|
/**
|
|
* @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 {
|
|
/**
|
|
* @brief Advertiser timeout (N * 10 ms).
|
|
*
|
|
* Application will be notified by the advertiser sent callback.
|
|
* Set to zero for no timeout.
|
|
*
|
|
* 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.
|
|
*
|
|
* If privacy @kconfig{CONFIG_BT_PRIVACY} is enabled then the timeout
|
|
* must be less than @kconfig{CONFIG_BT_RPA_TIMEOUT}.
|
|
*/
|
|
uint16_t timeout;
|
|
/**
|
|
* @brief Number of advertising events.
|
|
*
|
|
* Application will be notified by the advertiser sent callback.
|
|
* Set to zero for no limit.
|
|
*/
|
|
uint8_t num_events;
|
|
};
|
|
|
|
/**
|
|
* @brief Start advertising with the given advertising set
|
|
*
|
|
* 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);
|
|
|
|
/**
|
|
* @brief Stop advertising with the given advertising set
|
|
*
|
|
* 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);
|
|
|
|
/**
|
|
* @brief Set an advertising set's advertising or scan response data.
|
|
*
|
|
* 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.
|
|
*
|
|
* When both @ref BT_LE_ADV_OPT_EXT_ADV and @ref BT_LE_ADV_OPT_SCANNABLE are
|
|
* enabled then advertising data is ignored.
|
|
* When @ref BT_LE_ADV_OPT_SCANNABLE is not enabled then scan response data is
|
|
* ignored.
|
|
*
|
|
* 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.
|
|
*
|
|
* @note When changing the option @ref BT_LE_ADV_OPT_USE_NAME then
|
|
* @ref bt_le_ext_adv_set_data needs to be called in order to update the
|
|
* advertising data and scan response data.
|
|
*
|
|
* @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);
|
|
|
|
/**
|
|
* @brief Delete advertising set.
|
|
*
|
|
* 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
|
|
*/
|
|
uint8_t bt_le_ext_adv_get_index(struct bt_le_ext_adv *adv);
|
|
|
|
/** @brief Advertising set info structure. */
|
|
struct bt_le_ext_adv_info {
|
|
/* Local identity */
|
|
uint8_t id;
|
|
|
|
/** Currently selected Transmit Power (dBM). */
|
|
int8_t tx_power;
|
|
};
|
|
|
|
/**
|
|
* @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);
|
|
|
|
/**
|
|
* @typedef bt_le_scan_cb_t
|
|
* @brief Callback type for reporting LE scan results.
|
|
*
|
|
* A function of this type is given to the bt_le_scan_start() function
|
|
* and will be called for any discovered LE device.
|
|
*
|
|
* @param addr Advertiser LE address and type.
|
|
* @param rssi Strength of advertiser signal.
|
|
* @param adv_type Type of advertising response from advertiser.
|
|
* @param buf Buffer containing advertiser data.
|
|
*/
|
|
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);
|
|
|
|
/**
|
|
* @brief Set or update the periodic advertising parameters.
|
|
*
|
|
* The periodic advertising parameters can only be set or updated on an
|
|
* extended advertisement set which is neither scannable, connectable nor
|
|
* anonymous.
|
|
*
|
|
* @param adv Advertising set object.
|
|
* @param param Advertising parameters.
|
|
*
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
*/
|
|
int bt_le_per_adv_set_param(struct bt_le_ext_adv *adv,
|
|
const struct bt_le_per_adv_param *param);
|
|
|
|
/**
|
|
* @brief Set or update the periodic advertising data.
|
|
*
|
|
* The periodic advertisement data can only be set or updated on an
|
|
* extended advertisement set which is neither scannable, connectable nor
|
|
* anonymous.
|
|
*
|
|
* @param adv Advertising set object.
|
|
* @param ad Advertising data.
|
|
* @param ad_len Advertising data length.
|
|
*
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
*/
|
|
int bt_le_per_adv_set_data(const struct bt_le_ext_adv *adv,
|
|
const struct bt_data *ad, size_t ad_len);
|
|
|
|
/**
|
|
* @brief Starts periodic advertising.
|
|
*
|
|
* Enabling the periodic advertising can be done independently of extended
|
|
* advertising, but both periodic advertising and extended advertising
|
|
* shall be enabled before any periodic advertising data is sent. The
|
|
* periodic advertising and extended advertising can be enabled in any order.
|
|
*
|
|
* Once periodic advertising has been enabled, it will continue advertising
|
|
* until @ref bt_le_per_adv_stop() has been called, or if the advertising set
|
|
* is deleted by @ref bt_le_ext_adv_delete(). Calling @ref bt_le_ext_adv_stop()
|
|
* will not stop the periodic advertising.
|
|
*
|
|
* @param adv Advertising set object.
|
|
*
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
*/
|
|
int bt_le_per_adv_start(struct bt_le_ext_adv *adv);
|
|
|
|
/**
|
|
* @brief Stops periodic advertising.
|
|
*
|
|
* Disabling the periodic advertising can be done independently of extended
|
|
* advertising. Disabling periodic advertising will not disable extended
|
|
* advertising.
|
|
*
|
|
* @param adv Advertising set object.
|
|
*
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
*/
|
|
int bt_le_per_adv_stop(struct bt_le_ext_adv *adv);
|
|
|
|
struct bt_le_per_adv_sync_synced_info {
|
|
/** Advertiser LE address and type. */
|
|
const bt_addr_le_t *addr;
|
|
|
|
/** Advertiser SID */
|
|
uint8_t sid;
|
|
|
|
/** Periodic advertising interval (N * 1.25 ms) */
|
|
uint16_t interval;
|
|
|
|
/** Advertiser PHY */
|
|
uint8_t phy;
|
|
|
|
/** True if receiving periodic advertisements, false otherwise. */
|
|
bool recv_enabled;
|
|
|
|
/**
|
|
* @brief Service Data provided by the peer when sync is transferred
|
|
*
|
|
* Will always be 0 when the sync is locally created.
|
|
*/
|
|
uint16_t service_data;
|
|
|
|
/**
|
|
* @brief Peer that transferred the periodic advertising sync
|
|
*
|
|
* Will always be 0 when the sync is locally created.
|
|
*
|
|
*/
|
|
struct bt_conn *conn;
|
|
};
|
|
|
|
struct bt_le_per_adv_sync_term_info {
|
|
/** Advertiser LE address and type. */
|
|
const bt_addr_le_t *addr;
|
|
|
|
/** Advertiser SID */
|
|
uint8_t sid;
|
|
};
|
|
|
|
struct bt_le_per_adv_sync_recv_info {
|
|
/** Advertiser LE address and type. */
|
|
const bt_addr_le_t *addr;
|
|
|
|
/** Advertiser SID */
|
|
uint8_t sid;
|
|
|
|
/** The TX power of the advertisement. */
|
|
int8_t tx_power;
|
|
|
|
/** The RSSI of the advertisement excluding any CTE. */
|
|
int8_t rssi;
|
|
|
|
/** The Constant Tone Extension (CTE) of the advertisement (@ref bt_df_cte_type) */
|
|
uint8_t cte_type;
|
|
};
|
|
|
|
|
|
struct bt_le_per_adv_sync_state_info {
|
|
/** True if receiving periodic advertisements, false otherwise. */
|
|
bool recv_enabled;
|
|
};
|
|
|
|
struct bt_le_per_adv_sync_cb {
|
|
/**
|
|
* @brief The periodic advertising has been successfully synced.
|
|
*
|
|
* This callback notifies the application that the periodic advertising
|
|
* set has been successfully synced, and will now start to
|
|
* receive periodic advertising reports.
|
|
*
|
|
* @param sync The periodic advertising sync object.
|
|
* @param info Information about the sync event.
|
|
*/
|
|
void (*synced)(struct bt_le_per_adv_sync *sync,
|
|
struct bt_le_per_adv_sync_synced_info *info);
|
|
|
|
/**
|
|
* @brief The periodic advertising sync has been terminated.
|
|
*
|
|
* This callback notifies the application that the periodic advertising
|
|
* sync has been terminated, either by local request, remote request or
|
|
* because due to missing data, e.g. by being out of range or sync.
|
|
*
|
|
* @param sync The periodic advertising sync object.
|
|
*/
|
|
void (*term)(struct bt_le_per_adv_sync *sync,
|
|
const struct bt_le_per_adv_sync_term_info *info);
|
|
|
|
/**
|
|
* @brief Periodic advertising data received.
|
|
*
|
|
* This callback notifies the application of an periodic advertising
|
|
* report.
|
|
*
|
|
* @param sync The advertising set object.
|
|
* @param info Information about the periodic advertising event.
|
|
* @param buf Buffer containing the periodic advertising data.
|
|
*/
|
|
void (*recv)(struct bt_le_per_adv_sync *sync,
|
|
const struct bt_le_per_adv_sync_recv_info *info,
|
|
struct net_buf_simple *buf);
|
|
|
|
/**
|
|
* @brief The periodic advertising sync state has changed.
|
|
*
|
|
* This callback notifies the application about changes to the sync
|
|
* state. Initialize sync and termination is handled by their individual
|
|
* callbacks, and won't be notified here.
|
|
*
|
|
* @param sync The periodic advertising sync object.
|
|
* @param info Information about the state change.
|
|
*/
|
|
void (*state_changed)(struct bt_le_per_adv_sync *sync,
|
|
const struct bt_le_per_adv_sync_state_info *info);
|
|
|
|
/**
|
|
* @brief BIGInfo advertising report received.
|
|
*
|
|
* This callback notifies the application of a BIGInfo advertising report.
|
|
* This is received if the advertiser is broadcasting isochronous streams in a BIG.
|
|
* See iso.h for more information.
|
|
*
|
|
* @param sync The advertising set object.
|
|
* @param biginfo The BIGInfo report.
|
|
*/
|
|
void (*biginfo)(struct bt_le_per_adv_sync *sync, const struct bt_iso_biginfo *biginfo);
|
|
|
|
/**
|
|
* @brief Callback for IQ samples report collected when sampling
|
|
* CTE received with periodic advertising PDU.
|
|
*
|
|
* @param sync The periodic advertising sync object.
|
|
* @param info Information about the sync event.
|
|
*/
|
|
void (*cte_report_cb)(struct bt_le_per_adv_sync *sync,
|
|
struct bt_df_per_adv_sync_iq_samples_report const *info);
|
|
|
|
sys_snode_t node;
|
|
};
|
|
|
|
/** Periodic advertising sync options */
|
|
enum {
|
|
/** Convenience value when no options are specified. */
|
|
BT_LE_PER_ADV_SYNC_OPT_NONE = 0,
|
|
|
|
/**
|
|
* @brief Use the periodic advertising list to sync with advertiser
|
|
*
|
|
* When this option is set, the address and SID of the parameters
|
|
* are ignored.
|
|
*/
|
|
BT_LE_PER_ADV_SYNC_OPT_USE_PER_ADV_LIST = BIT(0),
|
|
|
|
/**
|
|
* @brief Disables periodic advertising reports
|
|
*
|
|
* No advertisement reports will be handled until enabled.
|
|
*/
|
|
BT_LE_PER_ADV_SYNC_OPT_REPORTING_INITIALLY_DISABLED = BIT(1),
|
|
|
|
/** Sync with Angle of Arrival (AoA) constant tone extension */
|
|
BT_LE_PER_ADV_SYNC_OPT_DONT_SYNC_AOA = BIT(2),
|
|
|
|
/** Sync with Angle of Departure (AoD) 1 us constant tone extension */
|
|
BT_LE_PER_ADV_SYNC_OPT_DONT_SYNC_AOD_1US = BIT(3),
|
|
|
|
/** Sync with Angle of Departure (AoD) 2 us constant tone extension */
|
|
BT_LE_PER_ADV_SYNC_OPT_DONT_SYNC_AOD_2US = BIT(4),
|
|
|
|
/** Do not sync to packets without a constant tone extension */
|
|
BT_LE_PER_ADV_SYNC_OPT_SYNC_ONLY_CONST_TONE_EXT = BIT(5),
|
|
};
|
|
|
|
struct bt_le_per_adv_sync_param {
|
|
/**
|
|
* @brief Periodic Advertiser Address
|
|
*
|
|
* Only valid if not using the periodic advertising list
|
|
*/
|
|
bt_addr_le_t addr;
|
|
|
|
/**
|
|
* @brief Advertiser SID
|
|
*
|
|
* Only valid if not using the periodic advertising list
|
|
*/
|
|
uint8_t sid;
|
|
|
|
/** Bit-field of periodic advertising sync options. */
|
|
uint32_t options;
|
|
|
|
/**
|
|
* @brief Maximum event skip
|
|
*
|
|
* Maximum number of periodic advertising events that can be
|
|
* skipped after a successful receive
|
|
*/
|
|
uint16_t skip;
|
|
|
|
/**
|
|
* @brief Synchronization timeout (N * 10 ms)
|
|
*
|
|
* Synchronization timeout for the periodic advertising sync.
|
|
* Range 0x000A to 0x4000 (100 ms to 163840 ms)
|
|
*/
|
|
uint16_t timeout;
|
|
};
|
|
|
|
/**
|
|
* @brief Get array index of an periodic advertising sync object.
|
|
*
|
|
* This function is get the index of an array of periodic advertising sync
|
|
* objects. The array has CONFIG_BT_PER_ADV_SYNC_MAX elements.
|
|
*
|
|
* @param per_adv_sync The periodic advertising sync object.
|
|
*
|
|
* @return Index of the periodic advertising sync object.
|
|
* The range of the returned value is 0..CONFIG_BT_PER_ADV_SYNC_MAX-1
|
|
*/
|
|
uint8_t bt_le_per_adv_sync_get_index(struct bt_le_per_adv_sync *per_adv_sync);
|
|
|
|
/** @brief Advertising set info structure. */
|
|
struct bt_le_per_adv_sync_info {
|
|
/** Periodic Advertiser Address */
|
|
bt_addr_le_t addr;
|
|
|
|
/** Advertiser SID */
|
|
uint8_t sid;
|
|
|
|
/** Periodic advertising interval (N * 1.25 ms) */
|
|
uint16_t interval;
|
|
|
|
/** Advertiser PHY */
|
|
uint8_t phy;
|
|
};
|
|
|
|
/**
|
|
* @brief Get periodic adv sync information.
|
|
*
|
|
* @param per_adv_sync Periodic advertising sync object.
|
|
* @param info Periodic advertising sync info object
|
|
*
|
|
* @return Zero on success or (negative) error code on failure.
|
|
*/
|
|
int bt_le_per_adv_sync_get_info(struct bt_le_per_adv_sync *per_adv_sync,
|
|
struct bt_le_per_adv_sync_info *info);
|
|
|
|
/**
|
|
* @brief Look up an existing periodic advertising sync object by advertiser address.
|
|
*
|
|
* @param adv_addr Advertiser address.
|
|
* @param sid The advertising set ID.
|
|
*
|
|
* @return Periodic advertising sync object or NULL if not found.
|
|
*/
|
|
struct bt_le_per_adv_sync *bt_le_per_adv_sync_lookup_addr(const bt_addr_le_t *adv_addr,
|
|
uint8_t sid);
|
|
|
|
/**
|
|
* @brief Create a periodic advertising sync object.
|
|
*
|
|
* Create a periodic advertising sync object that can try to synchronize
|
|
* to periodic advertising reports from an advertiser. Scan shall either be
|
|
* disabled or extended scan shall be enabled.
|
|
*
|
|
* @param[in] param Periodic advertising sync parameters.
|
|
* @param[out] out_sync Periodic advertising sync object on.
|
|
*
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
*/
|
|
int bt_le_per_adv_sync_create(const struct bt_le_per_adv_sync_param *param,
|
|
struct bt_le_per_adv_sync **out_sync);
|
|
|
|
/**
|
|
* @brief Delete periodic advertising sync.
|
|
*
|
|
* Delete the periodic advertising sync object. Can be called regardless of the
|
|
* state of the sync. If the syncing is currently syncing, the syncing is
|
|
* cancelled. If the sync has been established, it is terminated. The
|
|
* periodic advertising sync object will be invalidated afterwards.
|
|
*
|
|
* If the state of the sync object is syncing, then a new periodic advertising
|
|
* sync object may not be created until the controller has finished canceling
|
|
* this object.
|
|
*
|
|
* @param per_adv_sync The periodic advertising sync object.
|
|
*
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
*/
|
|
int bt_le_per_adv_sync_delete(struct bt_le_per_adv_sync *per_adv_sync);
|
|
|
|
/**
|
|
* @brief Register periodic advertising sync callbacks.
|
|
*
|
|
* Adds the callback structure to the list of callback structures for periodic
|
|
* adverising syncs.
|
|
*
|
|
* This callback will be called for all periodic advertising sync activity,
|
|
* such as synced, terminated and when data is received.
|
|
*
|
|
* @param cb Callback struct. Must point to memory that remains valid.
|
|
*/
|
|
void bt_le_per_adv_sync_cb_register(struct bt_le_per_adv_sync_cb *cb);
|
|
|
|
/**
|
|
* @brief Enables receiving periodic advertising reports for a sync.
|
|
*
|
|
* If the sync is already receiving the reports, -EALREADY is returned.
|
|
*
|
|
* @param per_adv_sync The periodic advertising sync object.
|
|
*
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
*/
|
|
int bt_le_per_adv_sync_recv_enable(struct bt_le_per_adv_sync *per_adv_sync);
|
|
|
|
/**
|
|
* @brief Disables receiving periodic advertising reports for a sync.
|
|
*
|
|
* If the sync report receiving is already disabled, -EALREADY is returned.
|
|
*
|
|
* @param per_adv_sync The periodic advertising sync object.
|
|
*
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
*/
|
|
int bt_le_per_adv_sync_recv_disable(struct bt_le_per_adv_sync *per_adv_sync);
|
|
|
|
/** Periodic Advertising Sync Transfer options */
|
|
enum {
|
|
/** Convenience value when no options are specified. */
|
|
BT_LE_PER_ADV_SYNC_TRANSFER_OPT_NONE = 0,
|
|
|
|
/**
|
|
* @brief No Angle of Arrival (AoA)
|
|
*
|
|
* Do not sync with Angle of Arrival (AoA) constant tone extension
|
|
**/
|
|
BT_LE_PER_ADV_SYNC_TRANSFER_OPT_SYNC_NO_AOA = BIT(0),
|
|
|
|
/**
|
|
* @brief No Angle of Departure (AoD) 1 us
|
|
*
|
|
* Do not sync with Angle of Departure (AoD) 1 us
|
|
* constant tone extension
|
|
*/
|
|
BT_LE_PER_ADV_SYNC_TRANSFER_OPT_SYNC_NO_AOD_1US = BIT(1),
|
|
|
|
/**
|
|
* @brief No Angle of Departure (AoD) 2
|
|
*
|
|
* Do not sync with Angle of Departure (AoD) 2 us
|
|
* constant tone extension
|
|
*/
|
|
BT_LE_PER_ADV_SYNC_TRANSFER_OPT_SYNC_NO_AOD_2US = BIT(2),
|
|
|
|
/** Only sync to packets with constant tone extension */
|
|
BT_LE_PER_ADV_SYNC_TRANSFER_OPT_SYNC_ONLY_CTE = BIT(3),
|
|
};
|
|
|
|
struct bt_le_per_adv_sync_transfer_param {
|
|
/**
|
|
* @brief Maximum event skip
|
|
*
|
|
* The number of periodic advertising packets that can be skipped
|
|
* after a successful receive.
|
|
*/
|
|
uint16_t skip;
|
|
|
|
/**
|
|
* @brief Synchronization timeout (N * 10 ms)
|
|
*
|
|
* Synchronization timeout for the periodic advertising sync.
|
|
* Range 0x000A to 0x4000 (100 ms to 163840 ms)
|
|
*/
|
|
uint16_t timeout;
|
|
|
|
/** Periodic Advertising Sync Transfer options */
|
|
uint32_t options;
|
|
};
|
|
|
|
/**
|
|
* @brief Transfer the periodic advertising sync information to a peer device.
|
|
*
|
|
* This will allow another device to quickly synchronize to the same periodic
|
|
* advertising train that this device is currently synced to.
|
|
*
|
|
* @param per_adv_sync The periodic advertising sync to transfer.
|
|
* @param conn The peer device that will receive the sync information.
|
|
* @param service_data Application service data provided to the remote host.
|
|
*
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
*/
|
|
int bt_le_per_adv_sync_transfer(const struct bt_le_per_adv_sync *per_adv_sync,
|
|
const struct bt_conn *conn,
|
|
uint16_t service_data);
|
|
|
|
|
|
/**
|
|
* @brief Transfer the information about a periodic advertising set.
|
|
*
|
|
* This will allow another device to quickly synchronize to periodic
|
|
* advertising set from this device.
|
|
*
|
|
* @param adv The periodic advertising set to transfer info of.
|
|
* @param conn The peer device that will receive the information.
|
|
* @param service_data Application service data provided to the remote host.
|
|
*
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
*/
|
|
int bt_le_per_adv_set_info_transfer(const struct bt_le_ext_adv *adv,
|
|
const struct bt_conn *conn,
|
|
uint16_t service_data);
|
|
|
|
/**
|
|
* @brief Subscribe to periodic advertising sync transfers (PASTs).
|
|
*
|
|
* Sets the parameters and allow other devices to transfer periodic advertising
|
|
* syncs.
|
|
*
|
|
* @param conn The connection to set the parameters for. If NULL default
|
|
* parameters for all connections will be set. Parameters set
|
|
* for specific connection will always have precedence.
|
|
* @param param The periodic advertising sync transfer parameters.
|
|
*
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
*/
|
|
int bt_le_per_adv_sync_transfer_subscribe(
|
|
const struct bt_conn *conn,
|
|
const struct bt_le_per_adv_sync_transfer_param *param);
|
|
|
|
/**
|
|
* @brief Unsubscribe from periodic advertising sync transfers (PASTs).
|
|
*
|
|
* Remove the parameters that allow other devices to transfer periodic
|
|
* advertising syncs.
|
|
*
|
|
* @param conn The connection to remove the parameters for. If NULL default
|
|
* parameters for all connections will be removed. Unsubscribing
|
|
* for a specific device, will still allow other devices to
|
|
* transfer periodic advertising syncs.
|
|
*
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
*/
|
|
int bt_le_per_adv_sync_transfer_unsubscribe(const struct bt_conn *conn);
|
|
|
|
/**
|
|
* @brief Add a device to the periodic advertising list.
|
|
*
|
|
* Add peer device LE address to the periodic advertising list. This will make
|
|
* it possibly to automatically create a periodic advertising sync to this
|
|
* device.
|
|
*
|
|
* @param addr Bluetooth LE identity address.
|
|
* @param sid The advertising set ID. This value is obtained from the
|
|
* @ref bt_le_scan_recv_info in the scan callback.
|
|
*
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
*/
|
|
int bt_le_per_adv_list_add(const bt_addr_le_t *addr, uint8_t sid);
|
|
|
|
/**
|
|
* @brief Remove a device from the periodic advertising list.
|
|
*
|
|
* Removes peer device LE address from the periodic advertising list.
|
|
*
|
|
* @param addr Bluetooth LE identity address.
|
|
* @param sid The advertising set ID. This value is obtained from the
|
|
* @ref bt_le_scan_recv_info in the scan callback.
|
|
*
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
*/
|
|
int bt_le_per_adv_list_remove(const bt_addr_le_t *addr, uint8_t sid);
|
|
|
|
/**
|
|
* @brief Clear the periodic advertising list.
|
|
*
|
|
* Clears the entire periodic advertising list.
|
|
*
|
|
* @return Zero on success or (negative) error code otherwise.
|
|
*/
|
|
int bt_le_per_adv_list_clear(void);
|
|
|
|
enum {
|
|
/** Convenience value when no options are specified. */
|
|
BT_LE_SCAN_OPT_NONE = 0,
|
|
|
|
/** Filter duplicates. */
|
|
BT_LE_SCAN_OPT_FILTER_DUPLICATE = BIT(0),
|
|
|
|
/** Filter using whitelist. */
|
|
BT_LE_SCAN_OPT_FILTER_WHITELIST = BIT(1),
|
|
|
|
/** Enable scan on coded PHY (Long Range).*/
|
|
BT_LE_SCAN_OPT_CODED = BIT(2),
|
|
|
|
/**
|
|
* @brief Disable scan on 1M phy.
|
|
*
|
|
* @note Requires @ref BT_LE_SCAN_OPT_CODED.
|
|
*/
|
|
BT_LE_SCAN_OPT_NO_1M = BIT(3),
|
|
};
|
|
|
|
enum {
|
|
/** Scan without requesting additional information from advertisers. */
|
|
BT_LE_SCAN_TYPE_PASSIVE = 0x00,
|
|
|
|
/** Scan and request additional information from advertisers. */
|
|
BT_LE_SCAN_TYPE_ACTIVE = 0x01,
|
|
};
|
|
|
|
/** LE scan parameters */
|
|
struct bt_le_scan_param {
|
|
/** Scan type (BT_LE_SCAN_TYPE_ACTIVE or BT_LE_SCAN_TYPE_PASSIVE) */
|
|
uint8_t type;
|
|
|
|
/** Bit-field of scanning options. */
|
|
uint32_t options;
|
|
|
|
/** Scan interval (N * 0.625 ms) */
|
|
uint16_t interval;
|
|
|
|
/** Scan window (N * 0.625 ms) */
|
|
uint16_t window;
|
|
|
|
/**
|
|
* @brief Scan timeout (N * 10 ms)
|
|
*
|
|
* Application will be notified by the scan timeout callback.
|
|
* Set zero to disable timeout.
|
|
*/
|
|
uint16_t timeout;
|
|
|
|
/**
|
|
* @brief Scan interval LE Coded PHY (N * 0.625 MS)
|
|
*
|
|
* Set zero to use same as LE 1M PHY scan interval.
|
|
*/
|
|
uint16_t interval_coded;
|
|
|
|
/**
|
|
* @brief Scan window LE Coded PHY (N * 0.625 MS)
|
|
*
|
|
* Set zero to use same as LE 1M PHY scan window.
|
|
*/
|
|
uint16_t window_coded;
|
|
};
|
|
|
|
/** LE advertisement packet information */
|
|
struct bt_le_scan_recv_info {
|
|
/**
|
|
* @brief Advertiser LE address and type.
|
|
*
|
|
* If advertiser is anonymous then this address will be
|
|
* @ref BT_ADDR_LE_ANY.
|
|
*/
|
|
const bt_addr_le_t *addr;
|
|
|
|
/** Advertising Set Identifier. */
|
|
uint8_t sid;
|
|
|
|
/** Strength of advertiser signal. */
|
|
int8_t rssi;
|
|
|
|
/** Transmit power of the advertiser. */
|
|
int8_t tx_power;
|
|
|
|
/** Advertising packet type. */
|
|
uint8_t adv_type;
|
|
|
|
/** Advertising packet properties. */
|
|
uint16_t adv_props;
|
|
|
|
/**
|
|
* @brief Periodic advertising interval.
|
|
*
|
|
* If 0 there is no periodic advertising.
|
|
*/
|
|
uint16_t interval;
|
|
|
|
/** Primary advertising channel PHY. */
|
|
uint8_t primary_phy;
|
|
|
|
/** Secondary advertising channel PHY. */
|
|
uint8_t secondary_phy;
|
|
};
|
|
|
|
/** 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.
|
|
*/
|
|
void (*recv)(const struct bt_le_scan_recv_info *info,
|
|
struct net_buf_simple *buf);
|
|
|
|
/** @brief The scanner has stopped scanning after scan timeout. */
|
|
void (*timeout)(void);
|
|
|
|
sys_snode_t node;
|
|
};
|
|
|
|
/**
|
|
* @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, \
|
|
}
|
|
|
|
/**
|
|
* @brief Helper to declare scan parameters inline
|
|
*
|
|
* @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(_type, _options, _interval, _window) \
|
|
((struct bt_le_scan_param[]) { \
|
|
BT_LE_SCAN_PARAM_INIT(_type, _options, _interval, _window) \
|
|
})
|
|
|
|
/**
|
|
* @brief Helper macro to enable active scanning to discover new devices.
|
|
*/
|
|
#define BT_LE_SCAN_ACTIVE BT_LE_SCAN_PARAM(BT_LE_SCAN_TYPE_ACTIVE, \
|
|
BT_LE_SCAN_OPT_FILTER_DUPLICATE, \
|
|
BT_GAP_SCAN_FAST_INTERVAL, \
|
|
BT_GAP_SCAN_FAST_WINDOW)
|
|
|
|
/**
|
|
* @brief Helper macro to enable passive scanning to discover new devices.
|
|
*
|
|
* This macro should be used if information required for device identification
|
|
* (e.g., UUID) are known to be placed in Advertising Data.
|
|
*/
|
|
#define BT_LE_SCAN_PASSIVE BT_LE_SCAN_PARAM(BT_LE_SCAN_TYPE_PASSIVE, \
|
|
BT_LE_SCAN_OPT_FILTER_DUPLICATE, \
|
|
BT_GAP_SCAN_FAST_INTERVAL, \
|
|
BT_GAP_SCAN_FAST_WINDOW)
|
|
|
|
/**
|
|
* @brief Helper macro to enable active scanning to discover new devices.
|
|
* Include scanning on Coded PHY in addition to 1M PHY.
|
|
*/
|
|
#define BT_LE_SCAN_CODED_ACTIVE \
|
|
BT_LE_SCAN_PARAM(BT_LE_SCAN_TYPE_ACTIVE, \
|
|
BT_LE_SCAN_OPT_CODED | \
|
|
BT_LE_SCAN_OPT_FILTER_DUPLICATE, \
|
|
BT_GAP_SCAN_FAST_INTERVAL, \
|
|
BT_GAP_SCAN_FAST_WINDOW)
|
|
|
|
/**
|
|
* @brief Helper macro to enable passive scanning to discover new devices.
|
|
* Include scanning on Coded PHY in addition to 1M PHY.
|
|
*
|
|
* This macro should be used if information required for device identification
|
|
* (e.g., UUID) are known to be placed in Advertising Data.
|
|
*/
|
|
#define BT_LE_SCAN_CODED_PASSIVE \
|
|
BT_LE_SCAN_PARAM(BT_LE_SCAN_TYPE_PASSIVE, \
|
|
BT_LE_SCAN_OPT_CODED | \
|
|
BT_LE_SCAN_OPT_FILTER_DUPLICATE, \
|
|
BT_GAP_SCAN_FAST_INTERVAL, \
|
|
BT_GAP_SCAN_FAST_WINDOW)
|
|
|
|
/**
|
|
* @brief Start (LE) scanning
|
|
*
|
|
* Start LE scanning with given parameters and provide results through
|
|
* the specified callback.
|
|
*
|
|
* @note The LE scanner by default does not use the Identity Address of the
|
|
* local device when @kconfig{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
|
|
* @kconfig{CONFIG_BT_SCAN_WITH_IDENTITY} must be enabled.
|
|
*
|
|
* @param param Scan parameters.
|
|
* @param cb Callback to notify scan results. May be NULL if callback
|
|
* registration through @ref bt_le_scan_cb_register is preferred.
|
|
*
|
|
* @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_scan_start(const struct bt_le_scan_param *param, bt_le_scan_cb_t cb);
|
|
|
|
/**
|
|
* @brief Stop (LE) scanning.
|
|
*
|
|
* Stops ongoing LE scanning.
|
|
*
|
|
* @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_scan_stop(void);
|
|
|
|
/**
|
|
* @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 memory that remains valid.
|
|
*/
|
|
void bt_le_scan_cb_register(struct bt_le_scan_cb *cb);
|
|
|
|
/**
|
|
* @brief Unregister scanner packet callbacks.
|
|
*
|
|
* Remove the callback structure from the list of scanner callbacks.
|
|
*
|
|
* @param cb Callback struct. Must point to memory that remains valid.
|
|
*/
|
|
void bt_le_scan_cb_unregister(struct bt_le_scan_cb *cb);
|
|
|
|
/**
|
|
* @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.
|
|
*
|
|
* @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_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.
|
|
*
|
|
* @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_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.
|
|
*
|
|
* @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_whitelist_clear(void);
|
|
|
|
/**
|
|
* @brief Set (LE) channel map.
|
|
*
|
|
* @param chan_map Channel map.
|
|
*
|
|
* @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_set_chan_map(uint8_t chan_map[5]);
|
|
|
|
/**
|
|
* @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
|
|
* common scenario is to call this helper on the advertising data
|
|
* 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);
|
|
|
|
/** LE Secure Connections pairing Out of Band data. */
|
|
struct bt_le_oob_sc_data {
|
|
/** Random Number. */
|
|
uint8_t r[16];
|
|
|
|
/** Confirm Value. */
|
|
uint8_t c[16];
|
|
};
|
|
|
|
/** LE Out of Band information. */
|
|
struct bt_le_oob {
|
|
/** LE address. If privacy is enabled this is a Resolvable Private
|
|
* Address.
|
|
*/
|
|
bt_addr_le_t addr;
|
|
|
|
/** LE Secure Connections pairing Out of Band data. */
|
|
struct bt_le_oob_sc_data le_sc_data;
|
|
};
|
|
|
|
/**
|
|
* @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 @kconfig{CONFIG_BT_PRIVACY} is enabled this will result in
|
|
* generating new Resolvable Private Address (RPA) that is valid for
|
|
* @kconfig{CONFIG_BT_RPA_TIMEOUT} seconds. This address will be used for
|
|
* advertising started by @ref bt_le_adv_start, active scanning and
|
|
* connection creation.
|
|
*
|
|
* @note If privacy is enabled the RPA cannot be refreshed in the following
|
|
* cases:
|
|
* - Creating a connection in progress, wait for the connected callback.
|
|
* In addition when extended advertising @kconfig{CONFIG_BT_EXT_ADV} is
|
|
* not enabled or not supported by the controller:
|
|
* - 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.
|
|
*
|
|
* @param[in] id Local identity, in most cases BT_ID_DEFAULT.
|
|
* @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_oob_get_local(uint8_t id, struct bt_le_oob *oob);
|
|
|
|
/**
|
|
* @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 @kconfig{CONFIG_BT_PRIVACY} is enabled this will result in
|
|
* generating new Resolvable Private Address (RPA) that is valid for
|
|
* @kconfig{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);
|
|
|
|
/** @brief BR/EDR discovery result structure */
|
|
struct bt_br_discovery_result {
|
|
/** private */
|
|
uint8_t _priv[4];
|
|
|
|
/** Remote device address */
|
|
bt_addr_t addr;
|
|
|
|
/** RSSI from inquiry */
|
|
int8_t rssi;
|
|
|
|
/** Class of Device */
|
|
uint8_t cod[3];
|
|
|
|
/** Extended Inquiry Response */
|
|
uint8_t eir[240];
|
|
};
|
|
|
|
/**
|
|
* @typedef bt_br_discovery_cb_t
|
|
* @brief Callback type for reporting BR/EDR discovery (inquiry)
|
|
* results.
|
|
*
|
|
* 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.
|
|
*
|
|
* @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 {
|
|
/** Maximum length of the discovery in units of 1.28 seconds.
|
|
* Valid range is 0x01 - 0x30.
|
|
*/
|
|
uint8_t length;
|
|
|
|
/** True if limited discovery procedure is to be used. */
|
|
bool limited;
|
|
};
|
|
|
|
/**
|
|
* @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
|
|
* has completed. If more inquiry results were received during session than
|
|
* fits in provided result storage, only ones with highest RSSI will be
|
|
* reported.
|
|
*
|
|
* @param param Discovery parameters.
|
|
* @param results Storage for discovery results.
|
|
* @param count Number of results in storage. Valid range: 1-255.
|
|
* @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
|
|
*
|
|
* @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_stop(void);
|
|
|
|
struct bt_br_oob {
|
|
/** BR/EDR address. */
|
|
bt_addr_t addr;
|
|
};
|
|
|
|
/**
|
|
* @brief Get BR/EDR local Out Of Band information
|
|
*
|
|
* This function allows to get local controller information that are useful
|
|
* for Out Of Band pairing or connection creation process.
|
|
*
|
|
* @param oob Out Of Band information
|
|
*/
|
|
int bt_br_oob_get_local(struct bt_br_oob *oob);
|
|
|
|
|
|
/**
|
|
* @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
|
|
* already set. Zero if done successfully.
|
|
*/
|
|
int bt_br_set_discoverable(bool enable);
|
|
|
|
/**
|
|
* @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
|
|
* already set. Zero if done successfully.
|
|
*/
|
|
int bt_br_set_connectable(bool enable);
|
|
|
|
/**
|
|
* @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.
|
|
*/
|
|
int bt_unpair(uint8_t id, const bt_addr_le_t *addr);
|
|
|
|
/** Information about a bond with a remote device. */
|
|
struct bt_bond_info {
|
|
/** Address of the remote device. */
|
|
bt_addr_le_t addr;
|
|
};
|
|
|
|
/**
|
|
* @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.
|
|
*/
|
|
void bt_foreach_bond(uint8_t id, void (*func)(const struct bt_bond_info *info,
|
|
void *user_data),
|
|
void *user_data);
|
|
|
|
/**
|
|
* @}
|
|
*/
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
/**
|
|
* @}
|
|
*/
|
|
|
|
#endif /* ZEPHYR_INCLUDE_BLUETOOTH_BLUETOOTH_H_ */
|