Zephyr Project
A Scalable Open Source RTOS for IoT Embedded Devices
Generic Access Profile

Generic Access Profile. More...

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_ext_adv_cb
 
struct  bt_data
 Bluetooth data. More...
 
struct  bt_le_adv_param
 
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_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
 
struct  bt_le_scan_recv_info
 
struct  bt_le_scan_cb
 
struct  bt_le_oob_sc_data
 
struct  bt_le_oob
 
struct  bt_br_discovery_result
 BR/EDR discovery result structure. More...
 
struct  bt_br_discovery_param
 
struct  bt_br_oob
 
struct  bt_bond_info
 

Macros

#define BT_ID_DEFAULT   0
 
#define BT_DATA(_type, _data, _data_len)
 Helper to declare elements of bt_data arrays. More...
 
#define BT_DATA_BYTES(_type, _bytes...)
 Helper to declare elements of bt_data arrays. More...
 
#define BT_LE_ADV_PARAM_INIT(_options, _int_min, _int_max, _peer)
 Initialize advertising parameters. More...
 
#define BT_LE_ADV_PARAM(_options, _int_min, _int_max, _peer)
 Helper to declare advertising parameters inline. More...
 
#define BT_LE_ADV_CONN_DIR(_peer)
 
#define BT_LE_ADV_CONN
 
#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
 
#define BT_LE_ADV_NCONN_NAME
 
#define BT_LE_ADV_NCONN_IDENTITY
 
#define BT_LE_EXT_ADV_CONN_NAME
 
#define BT_LE_EXT_ADV_NCONN
 
#define BT_LE_EXT_ADV_NCONN_NAME
 
#define BT_LE_EXT_ADV_NCONN_IDENTITY
 
#define BT_LE_EXT_ADV_CODED_NCONN
 
#define BT_LE_EXT_ADV_CODED_NCONN_NAME
 
#define BT_LE_EXT_ADV_CODED_NCONN_IDENTITY
 
#define BT_LE_EXT_ADV_START_PARAM_INIT(_timeout, _n_evts)
 
#define BT_LE_EXT_ADV_START_PARAM(_timeout, _n_evts)
 
#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)
 
#define BT_LE_PER_ADV_PARAM(_int_min, _int_max, _options)
 
#define BT_LE_PER_ADV_DEFAULT
 
#define BT_LE_SCAN_PARAM_INIT(_type, _options, _interval, _window)
 Initialize scan parameters. More...
 
#define BT_LE_SCAN_PARAM(_type, _options, _interval, _window)
 Helper to declare scan parameters inline. More...
 
#define BT_LE_SCAN_ACTIVE
 Helper macro to enable active scanning to discover new devices. More...
 
#define BT_LE_SCAN_PASSIVE
 Helper macro to enable passive scanning to discover new devices. More...
 
#define BT_LE_SCAN_CODED_ACTIVE
 Helper macro to enable active scanning to discover new devices. Include scanning on Coded PHY in addition to 1M PHY. More...
 
#define BT_LE_SCAN_CODED_PASSIVE
 Helper macro to enable passive scanning to discover new devices. Include scanning on Coded PHY in addition to 1M PHY. More...
 

Typedefs

typedef void(* bt_ready_cb_t) (int err)
 Callback for notifying that Bluetooth has been enabled. More...
 
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. More...
 
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. More...
 

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)
}
 
enum  { BT_LE_PER_ADV_OPT_NONE = 0, BT_LE_PER_ADV_OPT_USE_TX_POWER = BIT(1) }
 
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_DONT_SYNC_AOA = BIT(2),
  BT_LE_PER_ADV_SYNC_OPT_DONT_SYNC_AOD_1US = BIT(3), BT_LE_PER_ADV_SYNC_OPT_DONT_SYNC_AOD_2US = BIT(4), BT_LE_PER_ADV_SYNC_OPT_SYNC_ONLY_CONST_TONE_EXT = BIT(5)
}
 
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)
}
 
enum  {
  BT_LE_SCAN_OPT_NONE = 0, BT_LE_SCAN_OPT_FILTER_DUPLICATE = BIT(0), BT_LE_SCAN_OPT_FILTER_WHITELIST = 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. More...
 
int bt_set_name (const char *name)
 Set Bluetooth Device Name. More...
 
const char * bt_get_name (void)
 Get Bluetooth Device Name. More...
 
void bt_id_get (bt_addr_le_t *addrs, size_t *count)
 Get the currently configured identities. More...
 
int bt_id_create (bt_addr_le_t *addr, uint8_t *irk)
 Create a new identity. More...
 
int bt_id_reset (uint8_t id, bt_addr_le_t *addr, uint8_t *irk)
 Reset/reclaim an identity for reuse. More...
 
int bt_id_delete (uint8_t id)
 Delete an identity. More...
 
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. More...
 
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. More...
 
int bt_le_adv_stop (void)
 Stop advertising. More...
 
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. More...
 
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. More...
 
int bt_le_ext_adv_stop (struct bt_le_ext_adv *adv)
 Stop advertising with the given advertising set. More...
 
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. More...
 
int bt_le_ext_adv_update_param (struct bt_le_ext_adv *adv, const struct bt_le_adv_param *param)
 Update advertising parameters. More...
 
int bt_le_ext_adv_delete (struct bt_le_ext_adv *adv)
 Delete advertising set. More...
 
uint8_t bt_le_ext_adv_get_index (struct bt_le_ext_adv *adv)
 Get array index of an advertising set. More...
 
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. More...
 
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. More...
 
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. More...
 
int bt_le_per_adv_start (struct bt_le_ext_adv *adv)
 Starts periodic advertising. More...
 
int bt_le_per_adv_stop (struct bt_le_ext_adv *adv)
 Stops periodic advertising. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
int bt_le_per_adv_sync_delete (struct bt_le_per_adv_sync *per_adv_sync)
 Delete periodic advertising sync. More...
 
void bt_le_per_adv_sync_cb_register (struct bt_le_per_adv_sync_cb *cb)
 Register periodic advertising sync callbacks. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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). More...
 
int bt_le_per_adv_sync_transfer_unsubscribe (const struct bt_conn *conn)
 Unsubscribe from periodic advertising sync transfers (PASTs). More...
 
int bt_le_per_adv_list_add (const bt_addr_le_t *addr, uint8_t sid)
 Add a device to the periodic advertising list. More...
 
int bt_le_per_adv_list_remove (const bt_addr_le_t *addr, uint8_t sid)
 Remove a device from the periodic advertising list. More...
 
int bt_le_per_adv_list_clear (void)
 Clear the periodic advertising list. More...
 
int bt_le_scan_start (const struct bt_le_scan_param *param, bt_le_scan_cb_t cb)
 Start (LE) scanning. More...
 
int bt_le_scan_stop (void)
 Stop (LE) scanning. More...
 
void bt_le_scan_cb_register (struct bt_le_scan_cb *cb)
 Register scanner packet callbacks. More...
 
void bt_le_scan_cb_unregister (struct bt_le_scan_cb *cb)
 Unregister scanner packet callbacks. More...
 
int bt_le_whitelist_add (const bt_addr_le_t *addr)
 Add device (LE) to whitelist. More...
 
int bt_le_whitelist_rem (const bt_addr_le_t *addr)
 Remove device (LE) from whitelist. More...
 
int bt_le_whitelist_clear (void)
 Clear whitelist. More...
 
int bt_le_set_chan_map (uint8_t chan_map[5])
 Set (LE) channel map. More...
 
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. More...
 
int bt_le_oob_get_local (uint8_t id, struct bt_le_oob *oob)
 Get local LE Out of Band (OOB) information. More...
 
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. More...
 
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. More...
 
int bt_br_discovery_stop (void)
 Stop BR/EDR discovery. More...
 
int bt_br_oob_get_local (struct bt_br_oob *oob)
 Get BR/EDR local Out Of Band information. More...
 
int bt_br_set_discoverable (bool enable)
 Enable/disable set controller in discoverable state. More...
 
int bt_br_set_connectable (bool enable)
 Enable/disable set controller in connectable state. More...
 
int bt_unpair (uint8_t id, const bt_addr_le_t *addr)
 Clear pairing information. More...
 
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. More...
 

Detailed Description

Generic Access Profile.

Macro Definition Documentation

◆ BT_DATA

#define BT_DATA (   _type,
  _data,
  _data_len 
)

#include <include/bluetooth/bluetooth.h>

Value:
{ \
.type = (_type), \
.data_len = (_data_len), \
.data = (const uint8_t *)(_data), \
}

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. bt_le_adv_start().

Parameters
_typeType of advertising data field
_dataPointer to the data field payload
_data_lenNumber of bytes behind the _data pointer

◆ BT_DATA_BYTES

#define BT_DATA_BYTES (   _type,
  _bytes... 
)

#include <include/bluetooth/bluetooth.h>

Value:
BT_DATA(_type, ((uint8_t []) { _bytes }), \
sizeof((uint8_t []) { _bytes }))

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. bt_le_adv_start().

Parameters
_typeType of advertising data field
_bytesVariable number of single-byte parameters

◆ BT_ID_DEFAULT

#define BT_ID_DEFAULT   0

#include <include/bluetooth/bluetooth.h>

Convenience macro for specifying the default identity. This helps make the code more readable, especially when only one identity is supported.

◆ BT_LE_ADV_CONN

◆ BT_LE_ADV_CONN_DIR

#define BT_LE_ADV_CONN_DIR (   _peer)

◆ BT_LE_ADV_CONN_DIR_LOW_DUTY

◆ BT_LE_ADV_CONN_NAME

◆ BT_LE_ADV_CONN_NAME_AD

◆ BT_LE_ADV_NCONN

#define BT_LE_ADV_NCONN

#include <include/bluetooth/bluetooth.h>

Value:

Non-connectable advertising with private address

◆ BT_LE_ADV_NCONN_IDENTITY

#define BT_LE_ADV_NCONN_IDENTITY

◆ BT_LE_ADV_NCONN_NAME

#define BT_LE_ADV_NCONN_NAME

◆ BT_LE_ADV_PARAM

#define BT_LE_ADV_PARAM (   _options,
  _int_min,
  _int_max,
  _peer 
)

#include <include/bluetooth/bluetooth.h>

Value:
((struct bt_le_adv_param[]) { \
BT_LE_ADV_PARAM_INIT(_options, _int_min, _int_max, _peer) \
})

Helper to declare advertising parameters inline.

Parameters
_optionsAdvertising Options
_int_minMinimum advertising interval
_int_maxMaximum advertising interval
_peerPeer address, set to NULL for undirected advertising or address of peer for directed advertising.

◆ BT_LE_ADV_PARAM_INIT

#define BT_LE_ADV_PARAM_INIT (   _options,
  _int_min,
  _int_max,
  _peer 
)

#include <include/bluetooth/bluetooth.h>

Value:
{ \
.id = BT_ID_DEFAULT, \
.sid = 0, \
.secondary_max_skip = 0, \
.options = (_options), \
.interval_min = (_int_min), \
.interval_max = (_int_max), \
.peer = (_peer), \
}

Initialize advertising parameters.

Parameters
_optionsAdvertising Options
_int_minMinimum advertising interval
_int_maxMaximum advertising interval
_peerPeer address, set to NULL for undirected advertising or address of peer for directed advertising.

◆ BT_LE_EXT_ADV_CODED_NCONN

#define BT_LE_EXT_ADV_CODED_NCONN

#include <include/bluetooth/bluetooth.h>

Value:

Non-connectable extended advertising on coded PHY with private address

◆ BT_LE_EXT_ADV_CODED_NCONN_IDENTITY

#define BT_LE_EXT_ADV_CODED_NCONN_IDENTITY

◆ BT_LE_EXT_ADV_CODED_NCONN_NAME

#define BT_LE_EXT_ADV_CODED_NCONN_NAME

◆ BT_LE_EXT_ADV_CONN_NAME

◆ BT_LE_EXT_ADV_NCONN

#define BT_LE_EXT_ADV_NCONN

#include <include/bluetooth/bluetooth.h>

Value:

Non-connectable extended advertising with private address

◆ BT_LE_EXT_ADV_NCONN_IDENTITY

#define BT_LE_EXT_ADV_NCONN_IDENTITY

◆ BT_LE_EXT_ADV_NCONN_NAME

#define BT_LE_EXT_ADV_NCONN_NAME

◆ BT_LE_EXT_ADV_START_DEFAULT

#define BT_LE_EXT_ADV_START_DEFAULT   BT_LE_EXT_ADV_START_PARAM(0, 0)

◆ BT_LE_EXT_ADV_START_PARAM

#define BT_LE_EXT_ADV_START_PARAM (   _timeout,
  _n_evts 
)

#include <include/bluetooth/bluetooth.h>

Value:
((struct bt_le_ext_adv_start_param[]) { \
BT_LE_EXT_ADV_START_PARAM_INIT((_timeout), (_n_evts)) \
})

Helper to declare extended advertising start parameters inline

Parameters
_timeoutAdvertiser timeout
_n_evtsNumber of advertising events

◆ BT_LE_EXT_ADV_START_PARAM_INIT

#define BT_LE_EXT_ADV_START_PARAM_INIT (   _timeout,
  _n_evts 
)

#include <include/bluetooth/bluetooth.h>

Value:
{ \
.timeout = (_timeout), \
.num_events = (_n_evts), \
}

Helper to initialize extended advertising start parameters inline

Parameters
_timeoutAdvertiser timeout
_n_evtsNumber of advertising events

◆ BT_LE_PER_ADV_DEFAULT

◆ BT_LE_PER_ADV_PARAM

#define BT_LE_PER_ADV_PARAM (   _int_min,
  _int_max,
  _options 
)

#include <include/bluetooth/bluetooth.h>

Value:
((struct bt_le_per_adv_param[]) { \
BT_LE_PER_ADV_PARAM_INIT(_int_min, _int_max, _options) \
})

Helper to declare periodic advertising parameters inline

Parameters
_int_minMinimum periodic advertising interval
_int_maxMaximum periodic advertising interval
_optionsPeriodic advertising properties bitfield.

◆ BT_LE_PER_ADV_PARAM_INIT

#define BT_LE_PER_ADV_PARAM_INIT (   _int_min,
  _int_max,
  _options 
)

#include <include/bluetooth/bluetooth.h>

Value:
{ \
.interval_min = (_int_min), \
.interval_max = (_int_max), \
.options = (_options), \
}

Helper to declare periodic advertising parameters inline

Parameters
_int_minMinimum periodic advertising interval
_int_maxMaximum periodic advertising interval
_optionsPeriodic advertising properties bitfield.

◆ BT_LE_SCAN_ACTIVE

#define BT_LE_SCAN_ACTIVE

#include <include/bluetooth/bluetooth.h>

Value:

Helper macro to enable active scanning to discover new devices.

◆ BT_LE_SCAN_CODED_ACTIVE

#define BT_LE_SCAN_CODED_ACTIVE

#include <include/bluetooth/bluetooth.h>

Value:

Helper macro to enable active scanning to discover new devices. Include scanning on Coded PHY in addition to 1M PHY.

◆ BT_LE_SCAN_CODED_PASSIVE

#define BT_LE_SCAN_CODED_PASSIVE

#include <include/bluetooth/bluetooth.h>

Value:

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.

◆ BT_LE_SCAN_PARAM

#define BT_LE_SCAN_PARAM (   _type,
  _options,
  _interval,
  _window 
)

#include <include/bluetooth/bluetooth.h>

Value:
((struct bt_le_scan_param[]) { \
BT_LE_SCAN_PARAM_INIT(_type, _options, _interval, _window) \
})

Helper to declare scan parameters inline.

Parameters
_typeScan Type, BT_LE_SCAN_TYPE_ACTIVE or BT_LE_SCAN_TYPE_PASSIVE.
_optionsScan options
_intervalScan Interval (N * 0.625 ms)
_windowScan Window (N * 0.625 ms)

◆ BT_LE_SCAN_PARAM_INIT

#define BT_LE_SCAN_PARAM_INIT (   _type,
  _options,
  _interval,
  _window 
)

#include <include/bluetooth/bluetooth.h>

Value:
{ \
.type = (_type), \
.options = (_options), \
.interval = (_interval), \
.window = (_window), \
.timeout = 0, \
.interval_coded = 0, \
.window_coded = 0, \
}

Initialize scan parameters.

Parameters
_typeScan Type, BT_LE_SCAN_TYPE_ACTIVE or BT_LE_SCAN_TYPE_PASSIVE.
_optionsScan options
_intervalScan Interval (N * 0.625 ms)
_windowScan Window (N * 0.625 ms)

◆ BT_LE_SCAN_PASSIVE

#define BT_LE_SCAN_PASSIVE

#include <include/bluetooth/bluetooth.h>

Value:

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.

Typedef Documentation

◆ bt_br_discovery_cb_t

bt_br_discovery_cb_t

#include <include/bluetooth/bluetooth.h>

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.

Parameters
resultsStorage used for discovery results
countNumber of valid discovery results.

◆ bt_le_scan_cb_t

bt_le_scan_cb_t

#include <include/bluetooth/bluetooth.h>

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.

Parameters
addrAdvertiser LE address and type.
rssiStrength of advertiser signal.
adv_typeType of advertising response from advertiser.
bufBuffer containing advertiser data.

◆ bt_ready_cb_t

bt_ready_cb_t

#include <include/bluetooth/bluetooth.h>

Callback for notifying that Bluetooth has been enabled.

Parameters
errzero on success or (negative) error code otherwise.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

#include <include/bluetooth/bluetooth.h>

Advertising options

Enumerator
BT_LE_ADV_OPT_NONE 

Convenience value when no options are specified.

BT_LE_ADV_OPT_CONNECTABLE 

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

embed:rst:inline :kconfig:`CONFIG_BT_PRIVACY` 

.

BT_LE_ADV_OPT_ONE_TIME 

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 bt_le_ext_adv_start then this behavior is the default behavior and this flag has no effect.

BT_LE_ADV_OPT_USE_IDENTITY 

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 bt_le_oob_get_local, instead bt_id_get should be used to get the LE address.
BT_LE_ADV_OPT_USE_NAME 

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_DIR_MODE_LOW_DUTY 

Low duty cycle directed advertising.

Use low duty directed advertising mode, otherwise high duty mode will be used.

BT_LE_ADV_OPT_DIR_ADDR_RPA 

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_FILTER_SCAN_REQ 

Use whitelist to filter devices that can request scan response data.

BT_LE_ADV_OPT_FILTER_CONN 

Use whitelist to filter devices that can connect.

BT_LE_ADV_OPT_NOTIFY_SCAN_REQ 

Notify the application when a scan response data has been sent to an active scanner.

BT_LE_ADV_OPT_SCANNABLE 

Support scan response data.

When used together with BT_LE_ADV_OPT_EXT_ADV then this option cannot be used together with the BT_LE_ADV_OPT_CONNECTABLE option. When used together with BT_LE_ADV_OPT_EXT_ADV then scan response data must be set.

BT_LE_ADV_OPT_EXT_ADV 

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_NO_2M 

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.
Requires BT_LE_ADV_OPT_EXT_ADV.
BT_LE_ADV_OPT_CODED 

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 BT_LE_ADV_OPT_EXT_ADV
BT_LE_ADV_OPT_ANONYMOUS 

Advertise without a device address (identity or RPA).

Note
Requires BT_LE_ADV_OPT_EXT_ADV
BT_LE_ADV_OPT_USE_TX_POWER 

Advertise with transmit power.

Note
Requires BT_LE_ADV_OPT_EXT_ADV
BT_LE_ADV_OPT_DISABLE_CHAN_37 

Disable advertising on channel index 37.

BT_LE_ADV_OPT_DISABLE_CHAN_38 

Disable advertising on channel index 38.

BT_LE_ADV_OPT_DISABLE_CHAN_39 

Disable advertising on channel index 39.

BT_LE_ADV_OPT_FORCE_NAME_IN_AD 

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 BT_LE_ADV_OPT_USE_NAME

◆ anonymous enum

anonymous enum

#include <include/bluetooth/bluetooth.h>

Periodic Advertising options

Enumerator
BT_LE_PER_ADV_OPT_NONE 

Convenience value when no options are specified.

BT_LE_PER_ADV_OPT_USE_TX_POWER 

Advertise with transmit power.

Note
Requires BT_LE_ADV_OPT_EXT_ADV

◆ anonymous enum

anonymous enum

#include <include/bluetooth/bluetooth.h>

Periodic advertising sync options

Enumerator
BT_LE_PER_ADV_SYNC_OPT_NONE 

Convenience value when no options are specified.

BT_LE_PER_ADV_SYNC_OPT_USE_PER_ADV_LIST 

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_REPORTING_INITIALLY_DISABLED 

Disables periodic advertising reports.

No advertisement reports will be handled until enabled.

BT_LE_PER_ADV_SYNC_OPT_DONT_SYNC_AOA 

Sync with Angle of Arrival (AoA) constant tone extension

BT_LE_PER_ADV_SYNC_OPT_DONT_SYNC_AOD_1US 

Sync with Angle of Departure (AoD) 1 us constant tone extension

BT_LE_PER_ADV_SYNC_OPT_DONT_SYNC_AOD_2US 

Sync with Angle of Departure (AoD) 2 us constant tone extension

BT_LE_PER_ADV_SYNC_OPT_SYNC_ONLY_CONST_TONE_EXT 

Do not sync to packets without a constant tone extension

◆ anonymous enum

anonymous enum

#include <include/bluetooth/bluetooth.h>

Periodic Advertising Sync Transfer options

Enumerator
BT_LE_PER_ADV_SYNC_TRANSFER_OPT_NONE 

Convenience value when no options are specified.

BT_LE_PER_ADV_SYNC_TRANSFER_OPT_SYNC_NO_AOA 

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_AOD_1US 

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_2US 

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_ONLY_CTE 

Only sync to packets with constant tone extension

◆ anonymous enum

anonymous enum

#include <include/bluetooth/bluetooth.h>

Enumerator
BT_LE_SCAN_OPT_NONE 

Convenience value when no options are specified.

BT_LE_SCAN_OPT_FILTER_DUPLICATE 

Filter duplicates.

BT_LE_SCAN_OPT_FILTER_WHITELIST 

Filter using whitelist.

BT_LE_SCAN_OPT_CODED 

Enable scan on coded PHY (Long Range).

BT_LE_SCAN_OPT_NO_1M 

Disable scan on 1M phy.

Note
Requires BT_LE_SCAN_OPT_CODED.

◆ anonymous enum

anonymous enum

#include <include/bluetooth/bluetooth.h>

Enumerator
BT_LE_SCAN_TYPE_PASSIVE 

Scan without requesting additional information from advertisers.

BT_LE_SCAN_TYPE_ACTIVE 

Scan and request additional information from advertisers.

Function Documentation

◆ bt_br_discovery_start()

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 
)

#include <include/bluetooth/bluetooth.h>

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.

Parameters
paramDiscovery parameters.
resultsStorage for discovery results.
countNumber of results in storage. Valid range: 1-255.
cbCallback to notify discovery results.
Returns
Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error

◆ bt_br_discovery_stop()

int bt_br_discovery_stop ( void  )

#include <include/bluetooth/bluetooth.h>

Stop BR/EDR discovery.

Stops ongoing BR/EDR discovery. If discovery was stopped by this call results won't be reported

Returns
Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error.

◆ bt_br_oob_get_local()

int bt_br_oob_get_local ( struct bt_br_oob oob)

#include <include/bluetooth/bluetooth.h>

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.

Parameters
oobOut Of Band information

◆ bt_br_set_connectable()

int bt_br_set_connectable ( bool  enable)

#include <include/bluetooth/bluetooth.h>

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.

Parameters
enableValue allowing/disallowing controller to be connectable.
Returns
Negative if fail set to requested state or requested state has been already set. Zero if done successfully.

◆ bt_br_set_discoverable()

int bt_br_set_discoverable ( bool  enable)

#include <include/bluetooth/bluetooth.h>

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.

Parameters
enableValue allowing/disallowing controller to become discoverable.
Returns
Negative if fail set to requested state or requested state has been already set. Zero if done successfully.

◆ bt_data_parse()

void bt_data_parse ( struct net_buf_simple ad,
bool(*)(struct bt_data *data, void *user_data func,
void *  user_data 
)

#include <include/bluetooth/bluetooth.h>

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().

Parameters
adAdvertising data as given to the bt_le_scan_cb_t callback.
funcCallback 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.
user_dataUser data to be passed to the callback.

◆ bt_enable()

int bt_enable ( bt_ready_cb_t  cb)

#include <include/bluetooth/bluetooth.h>

Enable Bluetooth.

Enable Bluetooth. Must be the called before any calls that require communication with the local Bluetooth hardware.

When

embed:rst:inline :kconfig:`CONFIG_BT_SETTINGS` 

has been enabled and the application is not managing identities of the stack itself then the application must call settings_load() before the stack is fully enabled. See bt_id_create() for more information.

Parameters
cbCallback to notify completion or NULL to perform the enabling synchronously.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_foreach_bond()

void bt_foreach_bond ( uint8_t  id,
void(*)(const struct bt_bond_info *info, void *user_data func,
void *  user_data 
)

#include <include/bluetooth/bluetooth.h>

Iterate through all existing bonds.

Parameters
idLocal identity (mostly just BT_ID_DEFAULT).
funcFunction to call for each bond.
user_dataData to pass to the callback function.

◆ bt_get_name()

const char* bt_get_name ( void  )

#include <include/bluetooth/bluetooth.h>

Get Bluetooth Device Name.

Get Bluetooth GAP Device Name.

Returns
Bluetooth Device Name

◆ bt_id_create()

int bt_id_create ( bt_addr_le_t addr,
uint8_t irk 
)

#include <include/bluetooth/bluetooth.h>

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.

Parameters
addrAddress 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).
irkIdentity 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
embed:rst:inline :kconfig:`CONFIG_BT_PRIVACY` 
is not enabled this parameter must be NULL.
Returns
Identity identifier (>= 0) in case of success, or a negative error code on failure.

◆ bt_id_delete()

int bt_id_delete ( uint8_t  id)

#include <include/bluetooth/bluetooth.h>

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.
Parameters
idExisting identity identifier.
Returns
0 in case of success, or a negative error code on failure.

◆ bt_id_get()

void bt_id_get ( bt_addr_le_t addrs,
size_t *  count 
)

#include <include/bluetooth/bluetooth.h>

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 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 addrs array.

If addrs is passed as NULL, then returned count contains the count of all available identities that can be retrieved with a subsequent call to this function with non-NULL addrs parameter.

Note
Deleted identities may show up as BT_LE_ADDR_ANY in the returned array.
Parameters
addrsArray where to store the configured identities.
countShould be initialized to the array size. Once the function returns it will contain the number of returned identities.

◆ bt_id_reset()

int bt_id_reset ( uint8_t  id,
bt_addr_le_t addr,
uint8_t irk 
)

#include <include/bluetooth/bluetooth.h>

Reset/reclaim an identity for reuse.

The semantics of the addr and irk parameters of this function are the same as with bt_id_create(). The difference is the first 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 addr and 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.
Parameters
idExisting identity identifier.
addrAddress 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).
irkIdentity 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
embed:rst:inline :kconfig:`CONFIG_BT_PRIVACY` 
is not enabled this parameter must be NULL.
Returns
Identity identifier (>= 0) in case of success, or a negative error code on failure.

◆ bt_le_adv_start()

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 
)

#include <include/bluetooth/bluetooth.h>

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 BT_GAP_ADV_HIGH_DUTY_CYCLE_MAX_TIMEOUT.

Parameters
paramAdvertising parameters.
adData to be used in advertisement packets.
ad_lenNumber of elements in ad
sdData to be used in scan response packets.
sd_lenNumber of elements in sd
Returns
Zero on success or (negative) error code otherwise.
-ENOMEM No free connection objects available for connectable advertiser.
-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.

◆ bt_le_adv_stop()

int bt_le_adv_stop ( void  )

#include <include/bluetooth/bluetooth.h>

Stop advertising.

Stops ongoing advertising.

Returns
Zero on success or (negative) error code otherwise.

◆ bt_le_adv_update_data()

int bt_le_adv_update_data ( const struct bt_data ad,
size_t  ad_len,
const struct bt_data sd,
size_t  sd_len 
)

#include <include/bluetooth/bluetooth.h>

Update advertising.

Update advertisement and scan response data.

Parameters
adData to be used in advertisement packets.
ad_lenNumber of elements in ad
sdData to be used in scan response packets.
sd_lenNumber of elements in sd
Returns
Zero on success or (negative) error code otherwise.

◆ bt_le_ext_adv_create()

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 
)

#include <include/bluetooth/bluetooth.h>

Create advertising set.

Create a new advertising set and set advertising parameters. Advertising parameters can be updated with bt_le_ext_adv_update_param.

Parameters
[in]paramAdvertising parameters.
[in]cbCallback struct to notify about advertiser activity. Can be NULL. Must point to valid memory during the lifetime of the advertising set.
[out]advValid advertising set object on success.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_le_ext_adv_delete()

int bt_le_ext_adv_delete ( struct bt_le_ext_adv *  adv)

#include <include/bluetooth/bluetooth.h>

Delete advertising set.

Delete advertising set. This will free up the advertising set and make it possible to create a new advertising set.

Returns
Zero on success or (negative) error code otherwise.

◆ bt_le_ext_adv_get_index()

uint8_t bt_le_ext_adv_get_index ( struct bt_le_ext_adv *  adv)

#include <include/bluetooth/bluetooth.h>

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.

Parameters
advAdvertising set.
Returns
Index of the advertising set object. The range of the returned value is 0..CONFIG_BT_EXT_ADV_MAX_ADV_SET-1

◆ bt_le_ext_adv_get_info()

int bt_le_ext_adv_get_info ( const struct bt_le_ext_adv *  adv,
struct bt_le_ext_adv_info info 
)

#include <include/bluetooth/bluetooth.h>

Get advertising set info.

Parameters
advAdvertising set object
infoAdvertising set info object
Returns
Zero on success or (negative) error code on failure.

◆ bt_le_ext_adv_oob_get_local()

int bt_le_ext_adv_oob_get_local ( struct bt_le_ext_adv *  adv,
struct bt_le_oob oob 
)

#include <include/bluetooth/bluetooth.h>

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

embed:rst:inline :kconfig:`CONFIG_BT_PRIVACY` 

is enabled this will result in generating new Resolvable Private Address (RPA) that is valid for

embed:rst:inline :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.
If privacy is enabled the RPA cannot be refreshed in the following cases:
  • Creating a connection in progress, wait for the connected callback.
Parameters
[in]advThe advertising set object
[out]oobLE OOB information
Returns
Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error.

◆ bt_le_ext_adv_set_data()

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 
)

#include <include/bluetooth/bluetooth.h>

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 BT_LE_ADV_OPT_EXT_ADV and BT_LE_ADV_OPT_SCANNABLE are enabled then advertising data is ignored. When 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 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 BT_GAP_ADV_MAX_EXT_ADV_DATA_LEN bytes.

Note
Not all scanners support extended data length advertising data.
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.
Parameters
advAdvertising set object.
adData to be used in advertisement packets.
ad_lenNumber of elements in ad
sdData to be used in scan response packets.
sd_lenNumber of elements in sd
Returns
Zero on success or (negative) error code otherwise.

◆ bt_le_ext_adv_start()

int bt_le_ext_adv_start ( struct bt_le_ext_adv *  adv,
struct bt_le_ext_adv_start_param param 
)

#include <include/bluetooth/bluetooth.h>

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.

Parameters
advAdvertising set object.
paramAdvertise start parameters.

◆ bt_le_ext_adv_stop()

int bt_le_ext_adv_stop ( struct bt_le_ext_adv *  adv)

#include <include/bluetooth/bluetooth.h>

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.

Parameters
advAdvertising set object.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_le_ext_adv_update_param()

int bt_le_ext_adv_update_param ( struct bt_le_ext_adv *  adv,
const struct bt_le_adv_param param 
)

#include <include/bluetooth/bluetooth.h>

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.

Parameters
advAdvertising set object.
paramAdvertising parameters.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_le_oob_get_local()

int bt_le_oob_get_local ( uint8_t  id,
struct bt_le_oob oob 
)

#include <include/bluetooth/bluetooth.h>

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

embed:rst:inline :kconfig:`CONFIG_BT_PRIVACY` 

is enabled this will result in generating new Resolvable Private Address (RPA) that is valid for

embed:rst:inline :kconfig:`CONFIG_BT_RPA_TIMEOUT` 

seconds. This address will be used for advertising started by 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
    embed:rst:inline :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.
Parameters
[in]idLocal identity, in most cases BT_ID_DEFAULT.
[out]oobLE OOB information
Returns
Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error.

◆ bt_le_per_adv_list_add()

int bt_le_per_adv_list_add ( const bt_addr_le_t addr,
uint8_t  sid 
)

#include <include/bluetooth/bluetooth.h>

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.

Parameters
addrBluetooth LE identity address.
sidThe advertising set ID. This value is obtained from the bt_le_scan_recv_info in the scan callback.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_le_per_adv_list_clear()

int bt_le_per_adv_list_clear ( void  )

#include <include/bluetooth/bluetooth.h>

Clear the periodic advertising list.

Clears the entire periodic advertising list.

Returns
Zero on success or (negative) error code otherwise.

◆ bt_le_per_adv_list_remove()

int bt_le_per_adv_list_remove ( const bt_addr_le_t addr,
uint8_t  sid 
)

#include <include/bluetooth/bluetooth.h>

Remove a device from the periodic advertising list.

Removes peer device LE address from the periodic advertising list.

Parameters
addrBluetooth LE identity address.
sidThe advertising set ID. This value is obtained from the bt_le_scan_recv_info in the scan callback.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_le_per_adv_set_data()

int bt_le_per_adv_set_data ( const struct bt_le_ext_adv *  adv,
const struct bt_data ad,
size_t  ad_len 
)

#include <include/bluetooth/bluetooth.h>

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.

Parameters
advAdvertising set object.
adAdvertising data.
ad_lenAdvertising data length.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_le_per_adv_set_info_transfer()

int bt_le_per_adv_set_info_transfer ( const struct bt_le_ext_adv *  adv,
const struct bt_conn *  conn,
uint16_t  service_data 
)

#include <include/bluetooth/bluetooth.h>

Transfer the information about a periodic advertising set.

This will allow another device to quickly synchronize to periodic advertising set from this device.

Parameters
advThe periodic advertising set to transfer info of.
connThe peer device that will receive the information.
service_dataApplication service data provided to the remote host.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_le_per_adv_set_param()

int bt_le_per_adv_set_param ( struct bt_le_ext_adv *  adv,
const struct bt_le_per_adv_param param 
)

#include <include/bluetooth/bluetooth.h>

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.

Parameters
advAdvertising set object.
paramAdvertising parameters.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_le_per_adv_start()

int bt_le_per_adv_start ( struct bt_le_ext_adv *  adv)

#include <include/bluetooth/bluetooth.h>

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 bt_le_per_adv_stop() has been called, or if the advertising set is deleted by bt_le_ext_adv_delete(). Calling bt_le_ext_adv_stop() will not stop the periodic advertising.

Parameters
advAdvertising set object.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_le_per_adv_stop()

int bt_le_per_adv_stop ( struct bt_le_ext_adv *  adv)

#include <include/bluetooth/bluetooth.h>

Stops periodic advertising.

Disabling the periodic advertising can be done independently of extended advertising. Disabling periodic advertising will not disable extended advertising.

Parameters
advAdvertising set object.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_le_per_adv_sync_cb_register()

void bt_le_per_adv_sync_cb_register ( struct bt_le_per_adv_sync_cb cb)

#include <include/bluetooth/bluetooth.h>

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.

Parameters
cbCallback struct. Must point to memory that remains valid.

◆ bt_le_per_adv_sync_create()

int bt_le_per_adv_sync_create ( const struct bt_le_per_adv_sync_param param,
struct bt_le_per_adv_sync **  out_sync 
)

#include <include/bluetooth/bluetooth.h>

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.

Parameters
[in]paramPeriodic advertising sync parameters.
[out]out_syncPeriodic advertising sync object on.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_le_per_adv_sync_delete()

int bt_le_per_adv_sync_delete ( struct bt_le_per_adv_sync *  per_adv_sync)

#include <include/bluetooth/bluetooth.h>

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.

Parameters
per_adv_syncThe periodic advertising sync object.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_le_per_adv_sync_get_index()

uint8_t bt_le_per_adv_sync_get_index ( struct bt_le_per_adv_sync *  per_adv_sync)

#include <include/bluetooth/bluetooth.h>

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.

Parameters
per_adv_syncThe periodic advertising sync object.
Returns
Index of the periodic advertising sync object. The range of the returned value is 0..CONFIG_BT_PER_ADV_SYNC_MAX-1

◆ bt_le_per_adv_sync_get_info()

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 
)

#include <include/bluetooth/bluetooth.h>

Get periodic adv sync information.

Parameters
per_adv_syncPeriodic advertising sync object.
infoPeriodic advertising sync info object
Returns
Zero on success or (negative) error code on failure.

◆ bt_le_per_adv_sync_lookup_addr()

struct bt_le_per_adv_sync* bt_le_per_adv_sync_lookup_addr ( const bt_addr_le_t adv_addr,
uint8_t  sid 
)

#include <include/bluetooth/bluetooth.h>

Look up an existing periodic advertising sync object by advertiser address.

Parameters
adv_addrAdvertiser address.
sidThe advertising set ID.
Returns
Periodic advertising sync object or NULL if not found.

◆ bt_le_per_adv_sync_recv_disable()

int bt_le_per_adv_sync_recv_disable ( struct bt_le_per_adv_sync *  per_adv_sync)

#include <include/bluetooth/bluetooth.h>

Disables receiving periodic advertising reports for a sync.

If the sync report receiving is already disabled, -EALREADY is returned.

Parameters
per_adv_syncThe periodic advertising sync object.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_le_per_adv_sync_recv_enable()

int bt_le_per_adv_sync_recv_enable ( struct bt_le_per_adv_sync *  per_adv_sync)

#include <include/bluetooth/bluetooth.h>

Enables receiving periodic advertising reports for a sync.

If the sync is already receiving the reports, -EALREADY is returned.

Parameters
per_adv_syncThe periodic advertising sync object.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_le_per_adv_sync_transfer()

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 
)

#include <include/bluetooth/bluetooth.h>

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.

Parameters
per_adv_syncThe periodic advertising sync to transfer.
connThe peer device that will receive the sync information.
service_dataApplication service data provided to the remote host.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_le_per_adv_sync_transfer_subscribe()

int bt_le_per_adv_sync_transfer_subscribe ( const struct bt_conn *  conn,
const struct bt_le_per_adv_sync_transfer_param param 
)

#include <include/bluetooth/bluetooth.h>

Subscribe to periodic advertising sync transfers (PASTs).

Sets the parameters and allow other devices to transfer periodic advertising syncs.

Parameters
connThe 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.
paramThe periodic advertising sync transfer parameters.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_le_per_adv_sync_transfer_unsubscribe()

int bt_le_per_adv_sync_transfer_unsubscribe ( const struct bt_conn *  conn)

#include <include/bluetooth/bluetooth.h>

Unsubscribe from periodic advertising sync transfers (PASTs).

Remove the parameters that allow other devices to transfer periodic advertising syncs.

Parameters
connThe 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.
Returns
Zero on success or (negative) error code otherwise.

◆ bt_le_scan_cb_register()

void bt_le_scan_cb_register ( struct bt_le_scan_cb cb)

#include <include/bluetooth/bluetooth.h>

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.

Parameters
cbCallback struct. Must point to memory that remains valid.

◆ bt_le_scan_cb_unregister()

void bt_le_scan_cb_unregister ( struct bt_le_scan_cb cb)

#include <include/bluetooth/bluetooth.h>

Unregister scanner packet callbacks.

Remove the callback structure from the list of scanner callbacks.

Parameters
cbCallback struct. Must point to memory that remains valid.

◆ bt_le_scan_start()

int bt_le_scan_start ( const struct bt_le_scan_param param,
bt_le_scan_cb_t  cb 
)

#include <include/bluetooth/bluetooth.h>

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
embed:rst:inline :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
embed:rst:inline :kconfig:`CONFIG_BT_SCAN_WITH_IDENTITY` 
must be enabled.
Parameters
paramScan parameters.
cbCallback to notify scan results. May be NULL if callback registration through bt_le_scan_cb_register is preferred.
Returns
Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error.

◆ bt_le_scan_stop()

int bt_le_scan_stop ( void  )

#include <include/bluetooth/bluetooth.h>

Stop (LE) scanning.

Stops ongoing LE scanning.

Returns
Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error.

◆ bt_le_set_chan_map()

int bt_le_set_chan_map ( uint8_t  chan_map[5])

#include <include/bluetooth/bluetooth.h>

Set (LE) channel map.

Parameters
chan_mapChannel map.
Returns
Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error.

◆ bt_le_whitelist_add()

int bt_le_whitelist_add ( const bt_addr_le_t addr)

#include <include/bluetooth/bluetooth.h>

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.
Parameters
addrBluetooth LE identity address.
Returns
Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error.

◆ bt_le_whitelist_clear()

int bt_le_whitelist_clear ( void  )

#include <include/bluetooth/bluetooth.h>

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.
Returns
Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error.

◆ bt_le_whitelist_rem()

int bt_le_whitelist_rem ( const bt_addr_le_t addr)

#include <include/bluetooth/bluetooth.h>

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.
Parameters
addrBluetooth LE identity address.
Returns
Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error.

◆ bt_set_name()

int bt_set_name ( const char *  name)

#include <include/bluetooth/bluetooth.h>

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 bt_le_adv_update_data or bt_le_ext_adv_set_data.

Parameters
nameNew name
Returns
Zero on success or (negative) error code otherwise.

◆ bt_unpair()

int bt_unpair ( uint8_t  id,
const bt_addr_le_t addr 
)

#include <include/bluetooth/bluetooth.h>

Clear pairing information.

Parameters
idLocal identity (mostly just BT_ID_DEFAULT).
addrRemote address, NULL or BT_ADDR_LE_ANY to clear all remote devices.
Returns
0 on success or negative error value on failure.
bt_le_per_adv_param
Definition: bluetooth.h:603
BT_LE_ADV_OPT_EXT_ADV
@ BT_LE_ADV_OPT_EXT_ADV
Advertise with extended advertising.
Definition: bluetooth.h:457
BT_LE_SCAN_OPT_FILTER_DUPLICATE
@ BT_LE_SCAN_OPT_FILTER_DUPLICATE
Definition: bluetooth.h:1592
BT_LE_PER_ADV_OPT_NONE
@ BT_LE_PER_ADV_OPT_NONE
Definition: bluetooth.h:593
BT_GAP_SCAN_FAST_INTERVAL
#define BT_GAP_SCAN_FAST_INTERVAL
Definition: gap.h:66
BT_LE_ADV_OPT_USE_NAME
@ BT_LE_ADV_OPT_USE_NAME
Definition: bluetooth.h:392
BT_LE_SCAN_OPT_CODED
@ BT_LE_SCAN_OPT_CODED
Definition: bluetooth.h:1598
BT_LE_SCAN_TYPE_ACTIVE
@ BT_LE_SCAN_TYPE_ACTIVE
Definition: bluetooth.h:1613
uint8_t
__UINT8_TYPE__ uint8_t
Definition: stdint.h:58
bt_le_ext_adv_start_param
Definition: bluetooth.h:879
BT_ID_DEFAULT
#define BT_ID_DEFAULT
Definition: bluetooth.h:46
BT_LE_PER_ADV_PARAM
#define BT_LE_PER_ADV_PARAM(_int_min, _int_max, _options)
Definition: bluetooth.h:797
BT_LE_ADV_OPT_CONNECTABLE
@ BT_LE_ADV_OPT_CONNECTABLE
Advertise as connectable.
Definition: bluetooth.h:342
BT_GAP_ADV_FAST_INT_MAX_2
#define BT_GAP_ADV_FAST_INT_MAX_2
Definition: gap.h:75
BT_LE_ADV_OPT_CODED
@ BT_LE_ADV_OPT_CODED
Advertise on the LE Coded PHY (Long Range).
Definition: bluetooth.h:485
BT_GAP_ADV_SLOW_INT_MAX
#define BT_GAP_ADV_SLOW_INT_MAX
Definition: gap.h:77
BT_LE_ADV_OPT_USE_IDENTITY
@ BT_LE_ADV_OPT_USE_IDENTITY
Advertise using identity address.
Definition: bluetooth.h:370
BT_DATA
#define BT_DATA(_type, _data, _data_len)
Helper to declare elements of bt_data arrays.
Definition: bluetooth.h:309
BT_GAP_ADV_SLOW_INT_MIN
#define BT_GAP_ADV_SLOW_INT_MIN
Definition: gap.h:76
BT_LE_ADV_OPT_ONE_TIME
@ BT_LE_ADV_OPT_ONE_TIME
Advertise one time.
Definition: bluetooth.h:358
BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY
@ BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY
Low duty cycle directed advertising.
Definition: bluetooth.h:400
bt_le_adv_param
Definition: bluetooth.h:522
bt_le_scan_param
Definition: bluetooth.h:1617
BT_GAP_SCAN_FAST_WINDOW
#define BT_GAP_SCAN_FAST_WINDOW
Definition: gap.h:67
BT_LE_SCAN_TYPE_PASSIVE
@ BT_LE_SCAN_TYPE_PASSIVE
Definition: bluetooth.h:1610
BT_LE_ADV_OPT_FORCE_NAME_IN_AD
@ BT_LE_ADV_OPT_FORCE_NAME_IN_AD
Put GAP device name into advert data.
Definition: bluetooth.h:518
BT_GAP_ADV_FAST_INT_MIN_2
#define BT_GAP_ADV_FAST_INT_MIN_2
Definition: gap.h:74
BT_LE_SCAN_PARAM
#define BT_LE_SCAN_PARAM(_type, _options, _interval, _window)
Helper to declare scan parameters inline.
Definition: bluetooth.h:1739
BT_LE_ADV_PARAM
#define BT_LE_ADV_PARAM(_options, _int_min, _int_max, _peer)
Helper to declare advertising parameters inline.
Definition: bluetooth.h:653