bluetooth.h File Reference

Bluetooth subsystem core APIs. More...

#include <stdbool.h>
#include <string.h>
#include <zephyr/sys/util.h>
#include <zephyr/net/buf.h>
#include <zephyr/bluetooth/gap.h>
#include <zephyr/bluetooth/addr.h>
#include <zephyr/bluetooth/crypto.h>

Go to the source code of this file.

Data Structures
struct	bt_le_ext_adv_sent_info
struct	bt_le_ext_adv_connected_info
struct	bt_le_ext_adv_scanned_info
struct	bt_le_per_adv_data_request
struct	bt_le_per_adv_response_info
struct	bt_le_ext_adv_cb
struct	bt_data
	Bluetooth data. More...
struct	bt_le_adv_param
	LE Advertising Parameters. More...
struct	bt_le_per_adv_param
struct	bt_le_ext_adv_start_param
struct	bt_le_ext_adv_info
	Advertising set info structure. More...
struct	bt_le_per_adv_subevent_data_params
struct	bt_le_per_adv_sync_synced_info
struct	bt_le_per_adv_sync_term_info
struct	bt_le_per_adv_sync_recv_info
struct	bt_le_per_adv_sync_state_info
struct	bt_le_per_adv_sync_cb
struct	bt_le_per_adv_sync_param
struct	bt_le_per_adv_sync_info
	Advertising set info structure. More...
struct	bt_le_per_adv_sync_transfer_param
struct	bt_le_scan_param
	LE scan parameters. More...
struct	bt_le_scan_recv_info
	LE advertisement and scan response packet information. More...
struct	bt_le_scan_cb
	Listener context for (LE) scanning. More...
struct	bt_le_oob_sc_data
	LE Secure Connections pairing Out of Band data. More...
struct	bt_le_oob
	LE Out of Band information. More...
struct	bt_br_discovery_result
	BR/EDR discovery result structure. More...
struct	bt_br_discovery_param
	BR/EDR discovery parameters. More...
struct	bt_br_oob
struct	bt_bond_info
	Information about a bond with a remote device. More...
struct	bt_le_per_adv_sync_subevent_params
struct	bt_le_per_adv_response_params

Macros
#define	BT_ID_DEFAULT   0
	Convenience macro for specifying the default identity.
#define	BT_DATA_SERIALIZED_SIZE(data_len)   ((data_len) + 2)
	Bluetooth data serialized size.
#define	BT_DATA(_type, _data, _data_len)
	Helper to declare elements of bt_data arrays.
#define	BT_DATA_BYTES(_type, _bytes...)
	Helper to declare elements of bt_data arrays.
#define	BT_LE_ADV_PARAM_INIT(_options, _int_min, _int_max, _peer)
	Initialize advertising parameters.
#define	BT_LE_ADV_PARAM(_options, _int_min, _int_max, _peer)
	Helper to declare advertising parameters inline.
#define	BT_LE_ADV_CONN_DIR(_peer)
#define	BT_LE_ADV_CONN
#define	BT_LE_ADV_CONN_ONE_TIME
	This is the recommended default for connectable advertisers.
#define	BT_LE_ADV_CONN_NAME
#define	BT_LE_ADV_CONN_NAME_AD
#define	BT_LE_ADV_CONN_DIR_LOW_DUTY(_peer)
#define	BT_LE_ADV_NCONN
	Non-connectable advertising with private address.
#define	BT_LE_ADV_NCONN_NAME
#define	BT_LE_ADV_NCONN_IDENTITY
	Non-connectable advertising with BT_LE_ADV_OPT_USE_IDENTITY.
#define	BT_LE_EXT_ADV_CONN
	Connectable extended advertising.
#define	BT_LE_EXT_ADV_CONN_NAME
#define	BT_LE_EXT_ADV_SCAN
	Scannable extended advertising.
#define	BT_LE_EXT_ADV_SCAN_NAME
#define	BT_LE_EXT_ADV_NCONN
	Non-connectable extended advertising with private address.
#define	BT_LE_EXT_ADV_NCONN_NAME
#define	BT_LE_EXT_ADV_NCONN_IDENTITY
	Non-connectable extended advertising with BT_LE_ADV_OPT_USE_IDENTITY.
#define	BT_LE_EXT_ADV_CODED_NCONN
	Non-connectable extended advertising on coded PHY with private address.
#define	BT_LE_EXT_ADV_CODED_NCONN_NAME
#define	BT_LE_EXT_ADV_CODED_NCONN_IDENTITY
	Non-connectable extended advertising on coded PHY with BT_LE_ADV_OPT_USE_IDENTITY.
#define	BT_LE_EXT_ADV_START_PARAM_INIT(_timeout, _n_evts)
	Helper to initialize extended advertising start parameters inline.
#define	BT_LE_EXT_ADV_START_PARAM(_timeout, _n_evts)
	Helper to declare extended advertising start parameters inline.
#define	BT_LE_EXT_ADV_START_DEFAULT   BT_LE_EXT_ADV_START_PARAM(0, 0)
#define	BT_LE_PER_ADV_PARAM_INIT(_int_min, _int_max, _options)
	Helper to declare periodic advertising parameters inline.
#define	BT_LE_PER_ADV_PARAM(_int_min, _int_max, _options)
	Helper to declare periodic advertising parameters inline.
#define	BT_LE_PER_ADV_DEFAULT
#define	BT_LE_SCAN_OPT_FILTER_WHITELIST   __DEPRECATED_MACRO BT_LE_SCAN_OPT_FILTER_ACCEPT_LIST
#define	BT_LE_SCAN_PARAM_INIT(_type, _options, _interval, _window)
	Initialize scan parameters.
#define	BT_LE_SCAN_PARAM(_type, _options, _interval, _window)
	Helper to declare scan parameters inline.
#define	BT_LE_SCAN_ACTIVE
	Helper macro to enable active scanning to discover new devices.
#define	BT_LE_SCAN_ACTIVE_CONTINUOUS
	Helper macro to enable active scanning to discover new devices with window == interval.
#define	BT_LE_SCAN_PASSIVE
	Helper macro to enable passive scanning to discover new devices.
#define	BT_LE_SCAN_PASSIVE_CONTINUOUS
	Helper macro to enable passive scanning to discover new devices with window==interval.
#define	BT_LE_SCAN_CODED_ACTIVE
	Helper macro to enable active scanning to discover new devices.
#define	BT_LE_SCAN_CODED_PASSIVE
	Helper macro to enable passive scanning to discover new devices.

Typedefs
typedef void(*	bt_ready_cb_t) (int err)
	Callback for notifying that Bluetooth has been enabled.
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)
	Callback type for reporting LE scan results.
typedef void	bt_br_discovery_cb_t(struct bt_br_discovery_result *results, size_t count)
	Callback type for reporting BR/EDR discovery (inquiry) results.

Enumerations
enum	{   BT_LE_ADV_OPT_NONE = 0 , BT_LE_ADV_OPT_CONNECTABLE = BIT(0) , BT_LE_ADV_OPT_ONE_TIME = BIT(1) , BT_LE_ADV_OPT_USE_IDENTITY = BIT(2) ,   BT_LE_ADV_OPT_USE_NAME = BIT(3) , BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY = BIT(4) , BT_LE_ADV_OPT_DIR_ADDR_RPA = BIT(5) , BT_LE_ADV_OPT_FILTER_SCAN_REQ = BIT(6) ,   BT_LE_ADV_OPT_FILTER_CONN = BIT(7) , BT_LE_ADV_OPT_NOTIFY_SCAN_REQ = BIT(8) , BT_LE_ADV_OPT_SCANNABLE = BIT(9) , BT_LE_ADV_OPT_EXT_ADV = BIT(10) ,   BT_LE_ADV_OPT_NO_2M = BIT(11) , BT_LE_ADV_OPT_CODED = BIT(12) , BT_LE_ADV_OPT_ANONYMOUS = BIT(13) , BT_LE_ADV_OPT_USE_TX_POWER = BIT(14) ,   BT_LE_ADV_OPT_DISABLE_CHAN_37 = BIT(15) , BT_LE_ADV_OPT_DISABLE_CHAN_38 = BIT(16) , BT_LE_ADV_OPT_DISABLE_CHAN_39 = BIT(17) , BT_LE_ADV_OPT_FORCE_NAME_IN_AD = BIT(18) ,   BT_LE_ADV_OPT_USE_NRPA = BIT(19) }
	Advertising options. More...
enum	{ BT_LE_PER_ADV_OPT_NONE = 0 , BT_LE_PER_ADV_OPT_USE_TX_POWER = BIT(1) , BT_LE_PER_ADV_OPT_INCLUDE_ADI = BIT(2) }
	Periodic Advertising options. More...
enum	{   BT_LE_PER_ADV_SYNC_OPT_NONE = 0 , BT_LE_PER_ADV_SYNC_OPT_USE_PER_ADV_LIST = BIT(0) , BT_LE_PER_ADV_SYNC_OPT_REPORTING_INITIALLY_DISABLED = BIT(1) , BT_LE_PER_ADV_SYNC_OPT_FILTER_DUPLICATE = BIT(2) ,   BT_LE_PER_ADV_SYNC_OPT_DONT_SYNC_AOA = BIT(3) , BT_LE_PER_ADV_SYNC_OPT_DONT_SYNC_AOD_1US = BIT(4) , BT_LE_PER_ADV_SYNC_OPT_DONT_SYNC_AOD_2US = BIT(5) , BT_LE_PER_ADV_SYNC_OPT_SYNC_ONLY_CONST_TONE_EXT = BIT(6) }
	Periodic advertising sync options. More...
enum	{   BT_LE_PER_ADV_SYNC_TRANSFER_OPT_NONE = 0 , BT_LE_PER_ADV_SYNC_TRANSFER_OPT_SYNC_NO_AOA = BIT(0) , BT_LE_PER_ADV_SYNC_TRANSFER_OPT_SYNC_NO_AOD_1US = BIT(1) , BT_LE_PER_ADV_SYNC_TRANSFER_OPT_SYNC_NO_AOD_2US = BIT(2) ,   BT_LE_PER_ADV_SYNC_TRANSFER_OPT_SYNC_ONLY_CTE = BIT(3) , BT_LE_PER_ADV_SYNC_TRANSFER_OPT_REPORTING_INITIALLY_DISABLED = BIT(4) , BT_LE_PER_ADV_SYNC_TRANSFER_OPT_FILTER_DUPLICATES = BIT(5) }
	Periodic Advertising Sync Transfer options. More...
enum	{   BT_LE_SCAN_OPT_NONE = 0 , BT_LE_SCAN_OPT_FILTER_DUPLICATE = BIT(0) , BT_LE_SCAN_OPT_FILTER_ACCEPT_LIST = BIT(1) , BT_LE_SCAN_OPT_CODED = BIT(2) ,   BT_LE_SCAN_OPT_NO_1M = BIT(3) }
enum	{ BT_LE_SCAN_TYPE_PASSIVE = 0x00 , BT_LE_SCAN_TYPE_ACTIVE = 0x01 }

Functions
int	bt_enable (bt_ready_cb_t cb)
	Enable Bluetooth.
int	bt_disable (void)
	Disable Bluetooth.
bool	bt_is_ready (void)
	Check if Bluetooth is ready.
int	bt_set_name (const char *name)
	Set Bluetooth Device Name.
const char *	bt_get_name (void)
	Get Bluetooth Device Name.
uint16_t	bt_get_appearance (void)
	Get local Bluetooth appearance.
int	bt_set_appearance (uint16_t new_appearance)
	Set local Bluetooth appearance.
void	bt_id_get (bt_addr_le_t *addrs, size_t *count)
	Get the currently configured identities.
int	bt_id_create (bt_addr_le_t *addr, uint8_t *irk)
	Create a new identity.
int	bt_id_reset (uint8_t id, bt_addr_le_t *addr, uint8_t *irk)
	Reset/reclaim an identity for reuse.
int	bt_id_delete (uint8_t id)
	Delete an identity.
size_t	bt_data_get_len (const struct bt_data data[], size_t data_count)
	Get the total size (in bytes) of a given set of bt_data structures.
size_t	bt_data_serialize (const struct bt_data *input, uint8_t *output)
	Serialize a bt_data struct into an advertising structure (a flat byte array).
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)
	Start advertising.
int	bt_le_adv_update_data (const struct bt_data *ad, size_t ad_len, const struct bt_data *sd, size_t sd_len)
	Update advertising.
int	bt_le_adv_stop (void)
	Stop advertising.
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)
	Create advertising set.
int	bt_le_ext_adv_start (struct bt_le_ext_adv *adv, struct bt_le_ext_adv_start_param *param)
	Start advertising with the given advertising set.
int	bt_le_ext_adv_stop (struct bt_le_ext_adv *adv)
	Stop advertising with the given advertising set.
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)
	Set an advertising set's advertising or scan response data.
int	bt_le_ext_adv_update_param (struct bt_le_ext_adv *adv, const struct bt_le_adv_param *param)
	Update advertising parameters.
int	bt_le_ext_adv_delete (struct bt_le_ext_adv *adv)
	Delete advertising set.
uint8_t	bt_le_ext_adv_get_index (struct bt_le_ext_adv *adv)
	Get array index of an advertising set.
int	bt_le_ext_adv_get_info (const struct bt_le_ext_adv *adv, struct bt_le_ext_adv_info *info)
	Get advertising set info.
int	bt_le_per_adv_set_param (struct bt_le_ext_adv *adv, const struct bt_le_per_adv_param *param)
	Set or update the periodic advertising parameters.
int	bt_le_per_adv_set_data (const struct bt_le_ext_adv *adv, const struct bt_data *ad, size_t ad_len)
	Set or update the periodic advertising data.
int	bt_le_per_adv_set_subevent_data (const struct bt_le_ext_adv *adv, uint8_t num_subevents, const struct bt_le_per_adv_subevent_data_params *params)
	Set the periodic advertising with response subevent data.
int	bt_le_per_adv_start (struct bt_le_ext_adv *adv)
	Starts periodic advertising.
int	bt_le_per_adv_stop (struct bt_le_ext_adv *adv)
	Stops periodic advertising.
uint8_t	bt_le_per_adv_sync_get_index (struct bt_le_per_adv_sync *per_adv_sync)
	Get array index of an periodic advertising sync object.
struct bt_le_per_adv_sync *	bt_le_per_adv_sync_lookup_index (uint8_t index)
	Get a periodic advertising sync object from the array index.
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)
	Get periodic adv sync information.
struct bt_le_per_adv_sync *	bt_le_per_adv_sync_lookup_addr (const bt_addr_le_t *adv_addr, uint8_t sid)
	Look up an existing periodic advertising sync object by advertiser address.
int	bt_le_per_adv_sync_create (const struct bt_le_per_adv_sync_param *param, struct bt_le_per_adv_sync **out_sync)
	Create a periodic advertising sync object.
int	bt_le_per_adv_sync_delete (struct bt_le_per_adv_sync *per_adv_sync)
	Delete periodic advertising sync.
void	bt_le_per_adv_sync_cb_register (struct bt_le_per_adv_sync_cb *cb)
	Register periodic advertising sync callbacks.
int	bt_le_per_adv_sync_recv_enable (struct bt_le_per_adv_sync *per_adv_sync)
	Enables receiving periodic advertising reports for a sync.
int	bt_le_per_adv_sync_recv_disable (struct bt_le_per_adv_sync *per_adv_sync)
	Disables receiving periodic advertising reports for a sync.
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)
	Transfer the periodic advertising sync information to a peer device.
int	bt_le_per_adv_set_info_transfer (const struct bt_le_ext_adv *adv, const struct bt_conn *conn, uint16_t service_data)
	Transfer the information about a periodic advertising set.
int	bt_le_per_adv_sync_transfer_subscribe (const struct bt_conn *conn, const struct bt_le_per_adv_sync_transfer_param *param)
	Subscribe to periodic advertising sync transfers (PASTs).
int	bt_le_per_adv_sync_transfer_unsubscribe (const struct bt_conn *conn)
	Unsubscribe from periodic advertising sync transfers (PASTs).
int	bt_le_per_adv_list_add (const bt_addr_le_t *addr, uint8_t sid)
	Add a device to the periodic advertising list.
int	bt_le_per_adv_list_remove (const bt_addr_le_t *addr, uint8_t sid)
	Remove a device from the periodic advertising list.
int	bt_le_per_adv_list_clear (void)
	Clear the periodic advertising list.
int	bt_le_scan_start (const struct bt_le_scan_param *param, bt_le_scan_cb_t cb)
	Start (LE) scanning.
int	bt_le_scan_stop (void)
	Stop (LE) scanning.
void	bt_le_scan_cb_register (struct bt_le_scan_cb *cb)
	Register scanner packet callbacks.
void	bt_le_scan_cb_unregister (struct bt_le_scan_cb *cb)
	Unregister scanner packet callbacks.
int	bt_le_filter_accept_list_add (const bt_addr_le_t *addr)
	Add device (LE) to filter accept list.
static int	bt_le_whitelist_add (const bt_addr_le_t *addr)
int	bt_le_filter_accept_list_remove (const bt_addr_le_t *addr)
	Remove device (LE) from filter accept list.
static int	bt_le_whitelist_rem (const bt_addr_le_t *addr)
int	bt_le_filter_accept_list_clear (void)
	Clear filter accept list.
static int	bt_le_whitelist_clear (void)
int	bt_le_set_chan_map (uint8_t chan_map[5])
	Set (LE) channel map.
int	bt_le_set_rpa_timeout (uint16_t new_rpa_timeout)
	Set the Resolvable Private Address timeout in runtime.
void	bt_data_parse (struct net_buf_simple *ad, bool(*func)(struct bt_data *data, void *user_data), void *user_data)
	Helper for parsing advertising (or EIR or OOB) data.
int	bt_le_oob_get_local (uint8_t id, struct bt_le_oob *oob)
	Get local LE Out of Band (OOB) information.
int	bt_le_ext_adv_oob_get_local (struct bt_le_ext_adv *adv, struct bt_le_oob *oob)
	Get local LE Out of Band (OOB) information.
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)
	Start BR/EDR discovery.
int	bt_br_discovery_stop (void)
	Stop BR/EDR discovery.
int	bt_br_oob_get_local (struct bt_br_oob *oob)
	Get BR/EDR local Out Of Band information.
int	bt_br_set_discoverable (bool enable)
	Enable/disable set controller in discoverable state.
int	bt_br_set_connectable (bool enable)
	Enable/disable set controller in connectable state.
int	bt_unpair (uint8_t id, const bt_addr_le_t *addr)
	Clear pairing information.
void	bt_foreach_bond (uint8_t id, void(*func)(const struct bt_bond_info *info, void *user_data), void *user_data)
	Iterate through all existing bonds.
int	bt_configure_data_path (uint8_t dir, uint8_t id, uint8_t vs_config_len, const uint8_t *vs_config)
	Configure vendor data path.
int	bt_le_per_adv_sync_subevent (struct bt_le_per_adv_sync *per_adv_sync, struct bt_le_per_adv_sync_subevent_params *params)
	Synchronize with a subset of subevents.
int	bt_le_per_adv_set_response_data (struct bt_le_per_adv_sync *per_adv_sync, const struct bt_le_per_adv_response_params *params, const struct net_buf_simple *data)
	Set the data for a response slot in a specific subevent of the PAwR.

Detailed Description

Bluetooth subsystem core APIs.