Zephyr APIs - latest

Contents
Generic Access Profile (GAP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2
1. Generic Access Profile (GAP)
Topics | Data Structures | Macros | Typedefs | Enumerations | Functions

Generic Access Profile (GAP) More...

Topics

Defines and Assigned Numbers

Bluetooth Generic Access Profile defines and Assigned Numbers.

Data Structures

struct bt_le_ext_adv_sent_info

Info of the advertising sent event. More...

struct bt_le_ext_adv_connected_info

Info of the advertising connected event. More...

struct bt_le_ext_adv_scanned_info

Info of the advertising scanned event. More...

struct bt_le_per_adv_data_request

Info of the PAwR subevents. More...

struct bt_le_per_adv_response_info

Info about the PAwR responses received. More...

struct bt_le_ext_adv_cb

3
 Callback struct to notify about advertiser activity. More...

struct bt_data

Bluetooth data. More...

struct bt_le_local_features

Local Bluetooth LE controller features and capabilities. More...

struct bt_le_adv_param

LE Advertising Parameters. More...

struct bt_le_per_adv_param

Parameters for configuring periodic advertising. More...

struct bt_le_ext_adv_start_param

Parameters for starting an extended advertising session. More...

struct bt_le_ext_adv_info

Advertising set info structure. More...

struct bt_le_per_adv_subevent_data_params

Parameters for setting data for a specific periodic advertising with response subevent. More...

struct bt_le_per_adv_sync_synced_info

Information about the successful synchronization with periodic advertising. More...

struct bt_le_per_adv_sync_term_info

Information about the termination of a periodic advertising sync. More...

4
struct bt_le_per_adv_sync_recv_info

Information about a received periodic advertising report. More...

struct bt_le_per_adv_sync_state_info

Information about the state of periodic advertising sync. More...

struct bt_le_per_adv_sync_cb

Callback struct for periodic advertising sync events. More...

struct bt_le_per_adv_sync_param

Parameters for creating a periodic advertising sync object. More...

struct bt_le_per_adv_sync_info

Periodic advertising set info structure. More...

struct bt_le_per_adv_sync_transfer_param

Parameters for periodic advertising sync transfer. More...

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

5
struct bt_le_oob

LE Out of Band information. More...

struct bt_bond_info

Information about a bond with a remote device. More...

struct bt_le_per_adv_sync_subevent_params

Parameters for synchronizing with specific periodic advertising subevents. More...

struct bt_le_per_adv_response_params

Parameters for sending a periodic advertising response. 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_discovery_cb

struct bt_br_oob

struct bt_br_bond_info

Information about a bond with a remote device. More...

6
Macros

#define BT_ID_DEFAULT 0

Identity handle referring to the first identity address.

#define BT_LE_LOCAL_SUPPORTED_FEATURES_SIZE 8

Number of octets for local supported.

#define BT_DATA_SERIALIZED_SIZE(data_len)

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_FAST_1

GAP recommended connectable advertising parameters user-initiated.

7
#define BT_LE_ADV_CONN_FAST_2

GAP recommended connectable advertising parameters non-connectable advertising events.

#define BT_LE_ADV_CONN_ONE_TIME BT_LE_ADV_CONN_FAST_2 __DEPRECATED_MACRO

#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

8
#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)

9
 Helper to declare periodic advertising parameters inline.

#define BT_LE_PER_ADV_DEFAULT

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

#define BT_BR_EIR_SIZE_MAX 240

10
 Maximum size of Extended Inquiry Response.

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.

Enumerations

enum bt_le_adv_opt { BT_LE_ADV_OPT_NONE = 0 , BT_LE_ADV_OPT_CONNECTABLE = BIT(0) ,

BT LE ADV OPT CONNECTABLE = BIT(0) , BT_LE_ADV_OPT_ONE_TIME = BIT(1) , _BT_LE_ADV_OPT_ONE_TIME
_BT_LE_ADV_OPT_CONNECTABLE BT LE ADV OPT ONE TIME =
BIT(1) , BT_LE_ADV_OPT_CONN = BIT(0) | 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) , BT_LE_ADV_OPT_REQUIRE_S2_CODING = BIT(20) ,
BT_LE_ADV_OPT_REQUIRE_S8_CODING = BIT(21) }

Advertising options. More...

enum bt_le_per_adv_opt { 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 { 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) ,

11
 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 { 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 { 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 { 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)

12
 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 identity addresses.

int bt_id_create (bt_addr_le_t *addr, uint8_t *irk)

Create a new identity address.

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

Reset/reclaim an identity address for reuse.

int bt_id_delete (uint8_t id)

Delete an identity address.

size_t bt_data_get_len (const struct bt_data data[], size_t data_count)

Get the total size (in octets) 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 array).

13
int bt_le_get_local_features (struct bt_le_local_features *local_features)

Get local Bluetooth LE controller features.

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, const 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.

14
 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)

15
 *

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.

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

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

int bt_le_scan_cb_register (struct bt_le_scan_cb *cb)

Register scanner packet callbacks.

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

int bt_le_filter_accept_list_remove (const bt_addr_le_t *addr)

Remove device (LE) from filter accept list.

int bt_le_filter_accept_list_clear (void)

Clear filter accept list.

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_unpair (uint8_t id, const bt_addr_le_t *addr)

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

bool bt_le_bond_exists (uint8_t id, const bt_addr_le_t *addr)

Check if a device identified by a Bluetooth LE address is bonded.

int bt_br_discovery_start (const struct bt_br_discovery_param *param, struct bt_br_discovery_result *results,

size_t count)

Start BR/EDR discovery.

int bt_br_discovery_stop (void)

Stop BR/EDR discovery.

void bt_br_discovery_cb_register (struct bt_br_discovery_cb *cb)

Register discovery packet callbacks.

19
 void bt_br_discovery_cb_unregister (struct bt_br_discovery_cb *cb)

Unregister discovery packet callbacks.

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, bool limited)

Enable/disable set controller in discoverable state.

int bt_br_set_connectable (bool enable)

Enable/disable set controller in connectable state.

bool bt_br_bond_exists (const bt_addr_t *addr)

Check if a Bluetooth classic device address is bonded.

int bt_br_unpair (const bt_addr_t *addr)

Clear classic pairing information .

void bt_br_foreach_bond (void(*func)(const struct bt_br_bond_info *info, void *user_data), void *user_data)

Iterate through all existing bonds of Classic.

Detailed Description

Generic Access Profile (GAP)

Generic Access Profile (GAP) .

The Generic Access Profile (GAP) defines fundamental Bluetooth operations, including device discovery, pairing, and connection
management. Zephyr's GAP implementation supports both classic Bluetooth and Bluetooth Low Energy (LE) functionalities,
enabling roles such as Broadcaster, Observer, Peripheral, and Central. These roles define the device's behavior in advertising,
scanning, and establishing connections within Bluetooth networks.

20
Since
1.0

Version
1.0.0

Since
1.0

Version
1.0.0

Macro Definition Documentation

◆ BT_BR_EIR_SIZE_MAX

#define BT_BR_EIR_SIZE_MAX 240

#include <zephyr/bluetooth/classic/classic.h>

Maximum size of Extended Inquiry Response.

◆ BT_DATA

#define BT_DATA ( _type,

_data,

_data_len )

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

{ \

.type = (_type), \

.data_len = (_data_len), \

.data = (const uint8_t *)(_data), \

uint8_t
__UINT8_TYPE__ uint8_t
Definition stdint.h:88

21
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 function.

Parameters

_type Type of advertising data field

_data Pointer to the data field payload

_data_len Number of octets behind the _data pointer

◆ BT_DATA_BYTES

#define BT_DATA_BYTES ( _type,

_bytes... )

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

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

sizeof((uint8_t []) { _bytes }))

BT_DATA
#define BT_DATA(_type, _data, _data_len)
Helper to declare elements of bt_data arrays.
Definition bluetooth.h:550

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

Parameters

_type Type of advertising data field

_bytes Variable number of single-byte parameters

◆ BT_DATA_SERIALIZED_SIZE

#define BT_DATA_SERIALIZED_SIZE ( data_len )

22
#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

((data_len) + 2)

Bluetooth data serialized size.

Get the size of a serialized bt_data given its data length.

Size of 'AD Structure'->'Length' field, equal to 1. Size of 'AD Structure'->'Data'->'AD Type' field, equal to 1. Size of 'AD Structure'-
>'Data'->'AD Data' field, equal to data_len.

See Core Specification Version 5.4 Vol. 3 Part C, 11, Figure 11.1.

◆ BT_ID_DEFAULT

#define BT_ID_DEFAULT 0

#include <zephyr/bluetooth/bluetooth.h>

Identity handle referring to the first identity address.

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

◆ BT_LE_ADV_CONN

#define BT_LE_ADV_CONN

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONNECTABLE, BT_GAP_ADV_FAST_INT_MIN_2,
\

BT_GAP_ADV_FAST_INT_MAX_2, NULL)
\

__DEPRECATED_MACRO

BT_GAP_ADV_FAST_INT_MIN_2
#define BT_GAP_ADV_FAST_INT_MIN_2
Definition gap.h:726

23
 BT_GAP_ADV_FAST_INT_MAX_2
#define BT_GAP_ADV_FAST_INT_MAX_2
Definition gap.h:727

BT_LE_ADV_PARAM
#define BT_LE_ADV_PARAM(_options, _int_min, _int_max, _peer)
Helper to declare advertising parameters inline.
Definition bluetooth.h:1191

BT_LE_ADV_OPT_CONNECTABLE
@ BT_LE_ADV_OPT_CONNECTABLE
Advertise as connectable.
Definition bluetooth.h:707

NULL
#define NULL
Definition iar_missing_defs.h:20

Deprecated
This is a convenience macro for BT_LE_ADV_OPT_CONNECTABLE, which is deprecated. Please use BT_LE_ADV_CONN_FAST_1 or
BT_LE_ADV_CONN_FAST_2 instead.

◆ BT_LE_ADV_CONN_DIR

#define BT_LE_ADV_CONN_DIR ( _peer )

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONN, 0, 0, _peer)

BT_LE_ADV_OPT_CONN
@ BT_LE_ADV_OPT_CONN
Connectable advertising.
Definition bluetooth.h:765

◆ BT_LE_ADV_CONN_DIR_LOW_DUTY

#define BT_LE_ADV_CONN_DIR_LOW_DUTY ( _peer )

#include <zephyr/bluetooth/bluetooth.h>

24
Value:
Value

BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONN | BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY,
\

BT_GAP_ADV_FAST_INT_MIN_2, BT_GAP_ADV_FAST_INT_MAX_2, _peer)

BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY
@ BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY
Low duty cycle directed advertising.
Definition bluetooth.h:811

◆ BT_LE_ADV_CONN_FAST_1

#define BT_LE_ADV_CONN_FAST_1

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONN, BT_GAP_ADV_FAST_INT_MIN_1, BT_GAP_ADV_FAST_IN

T_MAX_1, \

NULL)

BT_GAP_ADV_FAST_INT_MAX_1
#define BT_GAP_ADV_FAST_INT_MAX_1
Definition gap.h:725

BT_GAP_ADV_FAST_INT_MIN_1
#define BT_GAP_ADV_FAST_INT_MIN_1
Definition gap.h:724

GAP recommended connectable advertising parameters user-initiated.

This define sets the recommended default for when an application is likely waiting for the device to be connected or discovered.

GAP recommends advertisers use the advertising parameters set by BT_LE_ADV_CONN_FAST_1 for user-initiated advertisements.
This might mean any time a user interacts with a device, a press on a dedicated Bluetooth wakeup button, or anything in-between.
Interpretation is left to the application developer.

Following modes are considered in these parameter settings:

• Undirected Connectable Mode

• Limited Discoverable Mode and sending connectable undirected advertising events

25
• General Discoverable Mode and sending connectable undirected advertising events
• Directed Connectable Mode and sending low duty cycle directed advertising events

Note
These parameters are merely a recommendation. For example the application might use a longer interval to conserve
battery, which would be at the cost of responsiveness and it should be considered to enter a lower power state with longer
intervals only after a timeout.

This is the recommended setting for limited discoverable mode.

See Bluetooth Core Specification:

• 6.0 Vol 3, Part C, Appendix A "Timers and Constants", T_GAP(adv_fast_interval1)

• 6.0 Vol 3, Part C, Section 9.3.11 "Connection Establishment Timing parameters"

◆ BT_LE_ADV_CONN_FAST_2

#define BT_LE_ADV_CONN_FAST_2

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONN, BT_GAP_ADV_FAST_INT_MIN_2, BT_GAP_ADV_FAST_IN

T_MAX_2, \

NULL)

GAP recommended connectable advertising parameters non-connectable advertising events.

This define sets the recommended default for user-initiated advertisements or sending non-connectable advertising events.

Following modes are considered in these parameter settings:

• Non-Discoverable Mode
• Non-Connectable Mode
• Limited Discoverable Mode
• General Discoverable Mode

The advertising interval corresponds to what was offered as BT_LE_ADV_CONN in Zephyr 3.6 and earlier, but unlike
BT_LE_ADV_CONN, the host does not automatically resume the advertiser after it results in a connection.

See Bluetooth Core Specification:

• 6.0 Vol 3, Part C, Appendix A "Timers and Constants", T_GAP(adv_fast_interval2)

• 6.0 Vol 3, Part C, Section 9.3.11 "Connection Establishment Timing parameters"

26
◆ BT_LE_ADV_CONN_NAME

#define BT_LE_ADV_CONN_NAME

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

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) \

__DEPRECATED_MACRO

BT_LE_ADV_OPT_USE_NAME
@ BT_LE_ADV_OPT_USE_NAME
Advertise using GAP device name.
Definition bluetooth.h:803

Deprecated
This macro will be removed in the near future, see https://github.com/zephyrproject-rtos/zephyr/issues/71686

◆ BT_LE_ADV_CONN_NAME_AD

#define BT_LE_ADV_CONN_NAME_AD

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

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) \

__DEPRECATED_MACRO

27
 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:938

Deprecated
This macro will be removed in the near future, see https://github.com/zephyrproject-rtos/zephyr/issues/71686

◆ BT_LE_ADV_CONN_ONE_TIME

#define BT_LE_ADV_CONN_ONE_TIME BT_LE_ADV_CONN_FAST_2 __DEPRECATED_MACRO

#include <zephyr/bluetooth/bluetooth.h>

◆ BT_LE_ADV_NCONN

#define BT_LE_ADV_NCONN

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

BT_LE_ADV_PARAM(0, BT_GAP_ADV_FAST_INT_MIN_2, \

BT_GAP_ADV_FAST_INT_MAX_2, NULL)

Non-connectable advertising with private address.

◆ BT_LE_ADV_NCONN_IDENTITY

#define BT_LE_ADV_NCONN_IDENTITY

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

BT_LE_ADV_PARAM(BT_LE_ADV_OPT_USE_IDENTIT
Y, \

BT_GAP_ADV_FAST_INT_MIN_2, \

BT_GAP_ADV_FAST_INT_MAX_2, \

28
 NULL)

BT_LE_ADV_OPT_USE_IDENTITY
@ BT_LE_ADV_OPT_USE_IDENTITY
Advertise using identity address.
Definition bluetooth.h:777

Non-connectable advertising with BT_LE_ADV_OPT_USE_IDENTITY.

◆ BT_LE_ADV_NCONN_NAME

#define BT_LE_ADV_NCONN_NAME

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

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) \

__DEPRECATED_MACRO

Deprecated
This macro will be removed in the near future, see https://github.com/zephyrproject-rtos/zephyr/issues/71686

Non-connectable advertising with BT_LE_ADV_OPT_USE_NAME

◆ BT_LE_ADV_PARAM

#define BT_LE_ADV_PARAM ( _options,

_int_min,

_int_max,

_peer )

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

29
 ((const struct bt_le_adv_param[]) { \

BT_LE_ADV_PARAM_INIT(_options, _int_min, _int_max, _peer) \

})

bt_le_adv_param
LE Advertising Parameters.
Definition bluetooth.h:990

Helper to declare advertising parameters inline.

Parameters

_options Advertising Options

_int_min Minimum advertising interval

_int_max Maximum advertising interval

_peer Peer 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 <zephyr/bluetooth/bluetooth.h>

Value:
Value

{ \

.id = BT_ID_DEFAULT, \

.sid = 0, \

.secondary_max_skip = 0, \

.options = (_options), \

30
 .interval_min = (_int_min), \

.interval_max = (_int_max), \

.peer = (_peer), \

BT_ID_DEFAULT
#define BT_ID_DEFAULT
Identity handle referring to the first identity address.
Definition bluetooth.h:71

Initialize advertising parameters.

Parameters

_options Advertising Options

_int_min Minimum advertising interval

_int_max Maximum advertising interval

_peer Peer 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 <zephyr/bluetooth/bluetooth.h>

Value:
Value

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)

BT_LE_ADV_OPT_CODED

31
 @ BT_LE_ADV_OPT_CODED
Advertise on the LE Coded PHY (Long Range).
Definition bluetooth.h:900

BT_LE_ADV_OPT_EXT_ADV
@ BT_LE_ADV_OPT_EXT_ADV
Advertise with extended advertising.
Definition bluetooth.h:870

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

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

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)

Non-connectable extended advertising on coded PHY with BT_LE_ADV_OPT_USE_IDENTITY.

◆ BT_LE_EXT_ADV_CODED_NCONN_NAME

#define BT_LE_EXT_ADV_CODED_NCONN_NAME

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

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, \

32
 BT_GAP_ADV_FAST_INT_MAX_2, NULL) \

__DEPRECATED_MACRO

Deprecated
This macro will be removed in the near future, see https://github.com/zephyrproject-rtos/zephyr/issues/71686

Non-connectable extended advertising on coded PHY with BT_LE_ADV_OPT_USE_NAME

◆ BT_LE_EXT_ADV_CONN

#define BT_LE_EXT_ADV_CONN

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | BT_LE_ADV_OPT_CONN, BT_GAP_ADV_FAST_INT_MI

N_2, \

BT_GAP_ADV_FAST_INT_MAX_2, NULL)

Connectable extended advertising.

◆ BT_LE_EXT_ADV_CONN_NAME

#define BT_LE_EXT_ADV_CONN_NAME

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

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) \

33
 __DEPRECATED_MACRO

Deprecated
This macro will be removed in the near future, see https://github.com/zephyrproject-rtos/zephyr/issues/71686

Connectable extended advertising with BT_LE_ADV_OPT_USE_NAME

◆ BT_LE_EXT_ADV_NCONN

#define BT_LE_EXT_ADV_NCONN

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

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 private address.

◆ BT_LE_EXT_ADV_NCONN_IDENTITY

#define BT_LE_EXT_ADV_NCONN_IDENTITY

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

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 with BT_LE_ADV_OPT_USE_IDENTITY.

34
◆ BT_LE_EXT_ADV_NCONN_NAME

#define BT_LE_EXT_ADV_NCONN_NAME

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

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) \

__DEPRECATED_MACRO

Deprecated
This macro will be removed in the near future, see https://github.com/zephyrproject-rtos/zephyr/issues/71686

Non-connectable extended advertising with BT_LE_ADV_OPT_USE_NAME

◆ BT_LE_EXT_ADV_SCAN

#define BT_LE_EXT_ADV_SCAN

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | \

BT_LE_ADV_OPT_SCANNABLE, \

BT_GAP_ADV_FAST_INT_MIN_2, \

BT_GAP_ADV_FAST_INT_MAX_2, \

NULL)

BT_LE_ADV_OPT_SCANNABLE
@ BT_LE_ADV_OPT_SCANNABLE

35
 Support scan response data.
Definition bluetooth.h:848

Scannable extended advertising.

◆ BT_LE_EXT_ADV_SCAN_NAME

#define BT_LE_EXT_ADV_SCAN_NAME

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

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) \

__DEPRECATED_MACRO

Deprecated
This macro will be removed in the near future, see https://github.com/zephyrproject-rtos/zephyr/issues/71686

Scannable extended advertising with BT_LE_ADV_OPT_USE_NAME

◆ BT_LE_EXT_ADV_START_DEFAULT

#define BT_LE_EXT_ADV_START_DEFAULT BT_LE_EXT_ADV_START_PARAM(0, 0)

#include <zephyr/bluetooth/bluetooth.h>

◆ BT_LE_EXT_ADV_START_PARAM

#define BT_LE_EXT_ADV_START_PARAM ( _timeout,

_n_evts )

36
#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

((const struct bt_le_ext_adv_start_param[]) { \

BT_LE_EXT_ADV_START_PARAM_INIT((_timeout), (_n_evts)) \

})

bt_le_ext_adv_start_param
Parameters for starting an extended advertising session.
Definition bluetooth.h:1561

Helper to declare extended advertising start parameters inline.

Parameters

_timeout Advertiser timeout

_n_evts Number of advertising events

◆ BT_LE_EXT_ADV_START_PARAM_INIT

#define BT_LE_EXT_ADV_START_PARAM_INIT ( _timeout,

_n_evts )

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

{ \

.timeout = (_timeout), \

.num_events = (_n_evts), \

Helper to initialize extended advertising start parameters inline.

Parameters

_timeout Advertiser timeout

37
 _n_evts Number of advertising events

◆ BT_LE_LOCAL_SUPPORTED_FEATURES_SIZE

#define BT_LE_LOCAL_SUPPORTED_FEATURES_SIZE 8

#include <zephyr/bluetooth/bluetooth.h>

Number of octets for local supported.

The value of 8 correspond to page 0 in the LE Controller supported features

◆ BT_LE_PER_ADV_DEFAULT

#define BT_LE_PER_ADV_DEFAULT

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

BT_LE_PER_ADV_PARAM(BT_GAP_PER_ADV_SLO
W_INT_MIN, \

BT_GAP_PER_ADV_SLOW_INT_MAX, \

BT_LE_PER_ADV_OPT_NONE)

BT_GAP_PER_ADV_SLOW_INT_MAX
#define BT_GAP_PER_ADV_SLOW_INT_MAX
Definition gap.h:735

BT_GAP_PER_ADV_SLOW_INT_MIN
#define BT_GAP_PER_ADV_SLOW_INT_MIN
Definition gap.h:734

BT_LE_PER_ADV_PARAM
#define BT_LE_PER_ADV_PARAM(_int_min, _int_max, _options)
Helper to declare periodic advertising parameters inline.
Definition bluetooth.h:1456

BT_LE_PER_ADV_OPT_NONE
@ BT_LE_PER_ADV_OPT_NONE
Convenience value when no options are specified.
Definition bluetooth.h:1072

38
◆ BT_LE_PER_ADV_PARAM

#define BT_LE_PER_ADV_PARAM ( _int_min,

_int_max,

_options )

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

((struct bt_le_per_adv_param[]) { \

BT_LE_PER_ADV_PARAM_INIT(_int_min, _int_max, _options) \

})

bt_le_per_adv_param
Parameters for configuring periodic advertising.
Definition bluetooth.h:1104

Helper to declare periodic advertising parameters inline.

Parameters

_int_min Minimum periodic advertising interval, N * 0.625 milliseconds

_int_max Maximum periodic advertising interval, N * 0.625 milliseconds

_options Periodic advertising properties bitfield, see bt_le_adv_opt field.

◆ BT_LE_PER_ADV_PARAM_INIT

#define BT_LE_PER_ADV_PARAM_INIT ( _int_min,

_int_max,

_options )

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

{ \

.interval_min = (_int_min), \

39
 .interval_max = (_int_max), \

.options = (_options), \

Helper to declare periodic advertising parameters inline.

Parameters

_int_min Minimum periodic advertising interval, N * 0.625 milliseconds

_int_max Maximum periodic advertising interval, N * 0.625 milliseconds

_options Periodic advertising properties bitfield, see bt_le_adv_opt field.

◆ BT_LE_SCAN_ACTIVE

#define BT_LE_SCAN_ACTIVE

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

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)

BT_GAP_SCAN_FAST_WINDOW
#define BT_GAP_SCAN_FAST_WINDOW
Definition gap.h:719

BT_GAP_SCAN_FAST_INTERVAL
#define BT_GAP_SCAN_FAST_INTERVAL
Definition gap.h:718

BT_LE_SCAN_PARAM
#define BT_LE_SCAN_PARAM(_type, _options, _interval, _window)
Helper to declare scan parameters inline.

40
 Definition bluetooth.h:2683

BT_LE_SCAN_OPT_FILTER_DUPLICATE
@ BT_LE_SCAN_OPT_FILTER_DUPLICATE
Filter duplicates.
Definition bluetooth.h:2504

BT_LE_SCAN_TYPE_ACTIVE
@ BT_LE_SCAN_TYPE_ACTIVE
Scan and request additional information from advertisers.
Definition bluetooth.h:2531

Helper macro to enable active scanning to discover new devices.

◆ BT_LE_SCAN_ACTIVE_CONTINUOUS

#define BT_LE_SCAN_ACTIVE_CONTINUOUS

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

BT_LE_SCAN_PARAM(BT_LE_SCAN_TYPE_ACT
IVE, \

BT_LE_SCAN_OPT_FILTER_DUPLICATE, \

BT_GAP_SCAN_FAST_INTERVAL_MIN, \

BT_GAP_SCAN_FAST_WINDOW)

BT_GAP_SCAN_FAST_INTERVAL_MIN
#define BT_GAP_SCAN_FAST_INTERVAL_MIN
Definition gap.h:717

Helper macro to enable active scanning to discover new devices with window == interval.

Continuous scanning should be used to maximize the chances of receiving advertising packets.

◆ BT_LE_SCAN_CODED_ACTIVE

#define BT_LE_SCAN_CODED_ACTIVE

41
#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

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)

BT_LE_SCAN_OPT_CODED
@ BT_LE_SCAN_OPT_CODED
Enable scan on coded PHY (Long Range).
Definition bluetooth.h:2510

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 <zephyr/bluetooth/bluetooth.h>

Value:
Value

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)

BT_LE_SCAN_TYPE_PASSIVE
@ BT_LE_SCAN_TYPE_PASSIVE
Scan without requesting additional information from advertisers.
Definition bluetooth.h:2522

42
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 <zephyr/bluetooth/bluetooth.h>

Value:
Value

((struct bt_le_scan_param[]) { \

BT_LE_SCAN_PARAM_INIT(_type, _options, _interval, _window) \

})

bt_le_scan_param
LE scan parameters.
Definition bluetooth.h:2535

Helper to declare scan parameters inline.

Parameters

_type Scan Type, BT_LE_SCAN_TYPE_ACTIVE or BT_LE_SCAN_TYPE_PASSIVE.

_options Scan options

_interval Scan Interval (N * 0.625 ms)

_window Scan Window (N * 0.625 ms)

◆ BT_LE_SCAN_PARAM_INIT

#define BT_LE_SCAN_PARAM_INIT ( _type,

43
 _options,

_interval,

_window )

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

{ \

.type = (_type), \

.options = (_options), \

.interval = (_interval), \

.window = (_window), \

.timeout = 0, \

.interval_coded = 0, \

.window_coded = 0, \

Initialize scan parameters.

Parameters

_type Scan Type, BT_LE_SCAN_TYPE_ACTIVE or BT_LE_SCAN_TYPE_PASSIVE.

_options Scan options

_interval Scan Interval (N * 0.625 ms)

_window Scan Window (N * 0.625 ms)

◆ BT_LE_SCAN_PASSIVE

#define BT_LE_SCAN_PASSIVE

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

44
 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)

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.

◆ BT_LE_SCAN_PASSIVE_CONTINUOUS

#define BT_LE_SCAN_PASSIVE_CONTINUOUS

#include <zephyr/bluetooth/bluetooth.h>

Value:
Value

BT_LE_SCAN_PARAM(BT_LE_SCAN_TYPE_PA
SSIVE, \

BT_LE_SCAN_OPT_FILTER_DUPLICATE, \

BT_GAP_SCAN_FAST_INTERVAL_MIN, \

BT_GAP_SCAN_FAST_WINDOW)

Helper macro to enable passive scanning to discover new devices with window==interval.

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_le_scan_cb_t

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)

#include <zephyr/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.

45
Parameters

addr Advertiser LE address and type.

rssi Strength of advertiser signal.

adv_type Type of advertising response from advertiser. Uses the bt_gap_adv_type values.

buf Buffer containing advertiser data.

◆ bt_ready_cb_t

typedef void(* bt_ready_cb_t) (int err)

#include <zephyr/bluetooth/bluetooth.h>

Callback for notifying that Bluetooth has been enabled.

Parameters

err zero on success or (negative) error code otherwise.

Enumeration Type Documentation

◆ bt_le_adv_opt

enum bt_le_adv_opt

#include <zephyr/bluetooth/bluetooth.h>

Advertising options.

Enumerator

BT_LE_ADV_OPT_NONE Convenience value when no options are specified.

Advertise as connectable.

Deprecated
Use BT_LE_ADV_OPT_CONN instead.
BT_LE_ADV_OPT_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

46
 CONFIG_BT_PRIVACY

Starting connectable advertising preallocates a connection object. If this fails, the

API returns -ENOMEM .

When an advertiser set results in a connection creation, the controller

automatically disables that advertising set.

If the advertising set was started with bt_le_adv_start without

BT_LE_ADV_OPT_ONE_TIME, the host will attempt to resume the advertiser under
some conditions.

Advertise one time.

Deprecated
Use BT_LE_ADV_OPT_CONN instead.

Don't try to resume connectable advertising after a connection. This option is only
BT_LE_ADV_OPT_ONE_TIME 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
(peripheral) 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.

Connectable advertising.

Starting connectable advertising preallocates a connection object. If this fails, the

API returns -ENOMEM .

The advertising set stops immediately after it creates a connection. This happens
automatically in the controller.

BT_LE_ADV_OPT_CONN
Note
To continue advertising after a connection is created, the application should
listen for the bt_conn_cb::connected event and start the advertising set
again. Note that the advertiser cannot be started when all connection
objects are in use. In that case, defer starting the advertiser until
bt_conn_cb::recycled. To continue after a disconnection, listen for
bt_conn_cb::recycled.

47
 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
BT_LE_ADV_OPT_USE_IDENTITY
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.

Advertise using GAP device name.

Deprecated
This option will be removed in the near future, see https://github.com/
zephyrproject-rtos/zephyr/issues/71686

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
BT_LE_ADV_OPT_EXT_ADV and not 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
BT_LE_ADV_OPT_USE_NAME
advertising data it will be converted to a shortened name if possible.
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.

BT_DATA(BT_DATA_NAME_COMPLETE, name, sizeof(name) - 1)

Low duty cycle directed advertising.

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

Directed advertising to privacy-enabled peer.

Enable use of Resolvable Private Address (RPA) as the target address in directed
BT_LE_ADV_OPT_DIR_ADDR_RPA
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

48
 address resolution of directed advertisements by reading its Central Address
Resolution characteristic.

BT_LE_ADV_OPT_FILTER_SCAN_REQ Use filter accept list to filter devices that can request scan response data.

BT_LE_ADV_OPT_FILTER_CONN Use filter accept list to filter devices that can connect.

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

Support scan response data.

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

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

This cannot be used with bt_le_adv_start.

Disable use of LE 2M PHY on the secondary advertising channel.

BT_LE_ADV_OPT_NO_2M 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

49
 PHY.

Note
Cannot be set if BT_LE_ADV_OPT_CODED is set.

Requires BT_LE_ADV_OPT_EXT_ADV bit (see bt_le_adv_opt field) to be set

as bt_le_adv_param::options.

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

Note
Requires BT_LE_ADV_OPT_EXT_ADV bit (see bt_le_adv_opt field) to be set
as bt_le_adv_param::options.

Advertise without a device address (identity address or RPA).

BT_LE_ADV_OPT_ANONYMOUS Note
Requires BT_LE_ADV_OPT_EXT_ADV bit (see bt_le_adv_opt field) to be set
as bt_le_adv_param::options.

Advertise with transmit power.

BT_LE_ADV_OPT_USE_TX_POWER Note
Requires BT_LE_ADV_OPT_EXT_ADV bit (see bt_le_adv_opt field) to be set
as bt_le_adv_param::options.

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.

50
 Put GAP device name into advert data.

Deprecated
This option will be removed in the near future, see https://github.com/
zephyrproject-rtos/zephyr/issues/71686

BT_LE_ADV_OPT_FORCE_NAME_IN_AD
Will place the GAP device name into the advertising data rather than the scan
response data.

Note
Requires BT_LE_ADV_OPT_USE_NAME

Advertise using a Non-Resolvable Private Address.

A new NRPA is set when updating the advertising parameters.

This is an advanced feature; most users will want to enable

CONFIG_BT_EXT_ADV

instead.
BT_LE_ADV_OPT_USE_NRPA

Note
Not implemented when

CONFIG_BT_PRIVACY

Mutually exclusive with BT_LE_ADV_OPT_USE_IDENTITY.

Configures the advertiser to use the S=2 coding scheme for LE Coded PHY.

Sets the advertiser's required coding scheme to S=2, which is one of the coding
options available for LE Coded PHY. The S=2 coding scheme offers higher data
rates compared to S=8, with a trade-off of reduced range. The coding scheme will
only be set if both the primary and secondary advertising channels indicate LE
BT_LE_ADV_OPT_REQUIRE_S2_CODING
Coded Phy. Additionally, the Controller must support the LE Feature Advertising
Coding Selection. If these conditions are not met, it will default to no required
coding scheme.

Attention
Available only when the following Kconfig option is enabled:

51
 BT_EXT_ADV_CODING_SELECTION

Configures the advertiser to use the S=8 coding scheme for LE Coded PHY.

Sets the advertiser's required coding scheme to S=8, which is one of the coding
options available for LE Coded PHY. The S=8 coding scheme offers increased
range compared to S=2, with a trade-off of lower data rates. The coding scheme
will only be set if both the primary and secondary advertising channels indicate LE
Coded Phy. Additionally, the Controller must support the LE Feature Advertising

BT_LE_ADV_OPT_REQUIRE_S8_CODING Coding Selection. If these conditions are not met, it will default to no required
coding scheme.

Attention
Available only when the following Kconfig option is enabled:

BT_EXT_ADV_CODING_SELECTION

◆ bt_le_per_adv_opt

enum bt_le_per_adv_opt

#include <zephyr/bluetooth/bluetooth.h>

Periodic Advertising options.

Enumerator

BT_LE_PER_ADV_OPT_NONE Convenience value when no options are specified.

Advertise with transmit power.

BT_LE_PER_ADV_OPT_USE_TX_POWER Note
Requires BT_LE_ADV_OPT_EXT_ADV bit (see bt_le_adv_opt field) to be set as
bt_le_adv_param::options.

BT_LE_PER_ADV_OPT_INCLUDE_ADI Advertise with included AdvDataInfo (ADI).

52
 Note
Requires BT_LE_ADV_OPT_EXT_ADV bit (see bt_le_adv_opt field) to be set as
bt_le_adv_param::options.

◆ bt_le_per_adv_sync_opt

enum bt_le_per_adv_sync_opt

#include <zephyr/bluetooth/bluetooth.h>

Periodic advertising sync options.

Enumerator

BT_LE_PER_ADV_SYNC_OPT_NONE Convenience value when no options are specified.

Use the periodic advertising list to sync with advertiser.

BT_LE_PER_ADV_SYNC_OPT_USE_PER_ADV_LIST
When this option is set, the address and SID of the
parameters are ignored.

Disables periodic advertising reports.

BT_LE_PER_ADV_SYNC_OPT_REPORTING_INITIALLY_DISABLED
No advertisement reports will be handled until enabled.

BT_LE_PER_ADV_SYNC_OPT_FILTER_DUPLICATE Filter duplicate Periodic Advertising reports.

BT_LE_PER_ADV_SYNC_OPT_DONT_SYNC_AOA Sync with Angle of Arrival (AoA) constant tone extension.

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

BT_LE_PER_ADV_SYNC_OPT_DONT_SYNC_AOD_1US
extension.

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

BT_LE_PER_ADV_SYNC_OPT_DONT_SYNC_AOD_2US
extension.

BT_LE_PER_ADV_SYNC_OPT_SYNC_ONLY_CONST_TONE_EXT Do not sync to packets without a constant tone extension.

53
◆ bt_le_per_adv_sync_transfer_opt

enum bt_le_per_adv_sync_transfer_opt

#include <zephyr/bluetooth/bluetooth.h>

Periodic Advertising Sync Transfer options.

Enumerator

BT_LE_PER_ADV_SYNC_TRANSFER_OPT_NONE Convenience value when no options are specified.

No Angle of Arrival (AoA)

BT_LE_PER_ADV_SYNC_TRANSFER_OPT_SYNC_NO_AOA
Do not sync with Angle of Arrival (AoA) constant tone extension

No Angle of Departure (AoD) 1 us.

BT_LE_PER_ADV_SYNC_TRANSFER_OPT_SYNC_NO_AOD_1US
Do not sync with Angle of Departure (AoD) 1 us constant tone ext

No Angle of Departure (AoD) 2.

BT_LE_PER_ADV_SYNC_TRANSFER_OPT_SYNC_NO_AOD_2US
Do not sync with Angle of Departure (AoD) 2 us constant tone ex

BT_LE_PER_ADV_SYNC_TRANSFER_OPT_SYNC_ONLY_CTE Only sync to packets with constant tone extension.

Sync to received PAST packets but don't generate sync reports.

BT_LE_PER_ADV_SYNC_TRANSFER_OPT_REPORTING_INITIALLY_DISABLED
This option must not be set at the same time as
BT_LE_PER_ADV_SYNC_TRANSFER_OPT_FILTER_DUPLICATES.

Sync to received PAST packets and generate sync reports with dup
filtering.
BT_LE_PER_ADV_SYNC_TRANSFER_OPT_FILTER_DUPLICATES
This option must not be set at the same time as
BT_LE_PER_ADV_SYNC_TRANSFER_OPT_REPORTING_INITIALLY_

◆ bt_le_scan_opt

enum bt_le_scan_opt

54
#include <zephyr/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_ACCEPT_LIST Filter using filter accept list.

BT_LE_SCAN_OPT_CODED Enable scan on coded PHY (Long Range).

Disable scan on 1M phy.

BT_LE_SCAN_OPT_NO_1M
Note
Requires BT_LE_SCAN_OPT_CODED.

◆ bt_le_scan_type

enum bt_le_scan_type

#include <zephyr/bluetooth/bluetooth.h>

Enumerator

BT_LE_SCAN_TYPE_PASSIVE Scan without requesting additional information from advertisers.

Scan and request additional information from advertisers.

BT_LE_SCAN_TYPE_ACTIVE
Using this scan type will automatically send scan requests to all devices. Scan responses are
received in the same manner and using the same callbacks as advertising reports.

Function Documentation

◆ bt_br_bond_exists()

bool bt_br_bond_exists ( const bt_addr_t * addr )

55
#include <zephyr/bluetooth/classic/classic.h>

Check if a Bluetooth classic device address is bonded.

Parameters

addr Bluetooth classic device address.

Returns
true if addr is bonded

◆ bt_br_discovery_cb_register()

void bt_br_discovery_cb_register ( struct bt_br_discovery_cb * cb )

#include <zephyr/bluetooth/classic/classic.h>

Register discovery packet callbacks.

Adds the callback structure to the list of callback structures that monitors inquiry activity.

This callback will be called for all inquiry activity, regardless of what API was used to start the discovery.

Parameters

cb Callback struct. Must point to memory that remains valid.

◆ bt_br_discovery_cb_unregister()

void bt_br_discovery_cb_unregister ( struct bt_br_discovery_cb * cb )

#include <zephyr/bluetooth/classic/classic.h>

Unregister discovery packet callbacks.

Remove the callback structure from the list of discovery callbacks.

Parameters

cb Callback struct. Must point to memory that remains valid.

◆ 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 )

56
#include <zephyr/bluetooth/classic/classic.h>

Start BR/EDR discovery.

Start BR/EDR discovery (inquiry) and provide results through the specified callback. The discovery results will be notified through
callbacks registered by bt_br_discovery_cb_register. If more inquiry results were received during session than fits in provided result
storage, only ones with highest RSSI will be reported.

Parameters

param Discovery parameters.

results Storage for discovery results.

count Number of results in storage. Valid range: 1-255.

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 <zephyr/bluetooth/classic/classic.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_foreach_bond()

void bt_br_foreach_bond ( void(* func )(const struct bt_br_bond_info *info, void *user_data),

void * user_data )

#include <zephyr/bluetooth/classic/classic.h>

Iterate through all existing bonds of Classic.

Parameters

func Function to call for each bond.

user_data Data to pass to the callback function.

57
◆ bt_br_oob_get_local()

int bt_br_oob_get_local ( struct bt_br_oob * oob )

#include <zephyr/bluetooth/classic/classic.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

oob Out Of Band information

◆ bt_br_set_connectable()

int bt_br_set_connectable ( bool enable )

#include <zephyr/bluetooth/classic/classic.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

enable Value 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,

bool limited )

#include <zephyr/bluetooth/classic/classic.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.

If the device enters limited discoverable mode, the controller will leave from discoverable mode after the duration of

58
 BT_LIMITED_DISCOVERABLE_DURATION

seconds in the limited discoverable mode.

Parameters

enable Value allowing/disallowing controller to become discoverable.

limited Value allowing/disallowing controller to enter limited discoverable mode.

Returns
Negative if fail set to requested state or requested state has been already set. Zero if done successfully.

◆ bt_br_unpair()

int bt_br_unpair ( const bt_addr_t * addr )

#include <zephyr/bluetooth/classic/classic.h>

Clear classic pairing information .

Parameters

addr Remote address, NULL or BT_ADDR_ANY to clear all remote devices.

Returns
0 on success or negative error value on failure.

◆ bt_configure_data_path()

int bt_configure_data_path ( uint8_t dir,

uint8_t id,

uint8_t vs_config_len,

const uint8_t * vs_config )

#include <zephyr/bluetooth/bluetooth.h>

Configure vendor data path.

Request the Controller to configure the data transport path in a given direction between the Controller and the Host.

Parameters

Direction to be configured, BT_HCI_DATAPATH_DIR_HOST_TO_CTLR or

dir
BT_HCI_DATAPATH_DIR_CTLR_TO_HOST

59
 id Vendor specific logical transport channel ID, range [BT_HCI_DATAPATH_ID_VS..BT_HCI_DATAPATH_ID_VS_END]

vs_config_len Length of additional vendor specific configuration data

vs_config Pointer to additional vendor specific configuration data

Returns
0 in case of success or negative value in case of error.

◆ bt_data_get_len()

size_t bt_data_get_len ( const struct bt_data data[],

size_t data_count )

#include <zephyr/bluetooth/bluetooth.h>

Get the total size (in octets) of a given set of bt_data structures.

The total size includes the length (1 octet) and type (1 octet) fields for each element, plus their respective data lengths.

Parameters

[in] data Array of bt_data structures.

[in] data_count Number of bt_data structures in data .

Returns
Size of the concatenated data, built from the bt_data structure set.

◆ bt_data_parse()

void bt_data_parse ( struct net_buf_simple * ad,

bool(* func )(struct bt_data *data, void *user_data),

void * user_data )

#include <zephyr/bluetooth/bluetooth.h>

Helper for parsing advertising (or EIR or OOB) data.

A helper for parsing the basic AD 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.

Warning
This helper function will consume ad when parsing. The user should make a copy if the original data is to be used afterwards.
This can be done by using net_buf_simple_save to store the state prior to the function call, and then using net_buf_simple_restore
to restore the state afterwards.

60
Parameters

ad Advertising data as given to the bt_le_scan_cb_t callback.

Callback function which will be called for each element that's found in the data. The callback should return true to
func
continue parsing, or false to stop parsing.

user_data User data to be passed to the callback.

◆ bt_data_serialize()

size_t bt_data_serialize ( const struct bt_data * input,

uint8_t * output )

#include <zephyr/bluetooth/bluetooth.h>

Serialize a bt_data struct into an advertising structure (a flat array).

The data are formatted according to the Bluetooth Core Specification v. 5.4, vol. 3, part C, 11.

Parameters

[in] input Single bt_data structure to read from.

Buffer large enough to store the advertising structure in input . The size of it must be at least the size of the
[out] output
input->data_len + 2 (for the type and the length).

Returns
Number of octets written in output .

◆ bt_disable()

int bt_disable ( void )

#include <zephyr/bluetooth/bluetooth.h>

Disable Bluetooth.

Disable Bluetooth. Can't be called before bt_enable has completed.

This API will clear all configured identity addresses and keys that are not persistently stored with

CONFIG_BT_SETTINGS

. These can be restored with settings_load before reenabling the stack.

This API does not clear previously registered callbacks like bt_le_scan_cb_register, bt_conn_cb_register AND

61
bt_br_discovery_cb_register. That is, the application shall not re-register them when the Bluetooth subsystem is re-enabled later.

Close and release HCI resources. Result is architecture dependent.

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

◆ bt_enable()

int bt_enable ( bt_ready_cb_t cb )

#include <zephyr/bluetooth/bluetooth.h>

Enable Bluetooth.

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

When

CONFIG_BT_SETTINGS

is enabled, the application must load the Bluetooth settings after this API call successfully completes before Bluetooth APIs can be
used. Loading the settings before calling this function is insufficient. Bluetooth settings can be loaded with settings_load or
settings_load_subtree with argument "bt". The latter selectively loads only Bluetooth settings and is recommended if settings_load
has been called earlier.

Parameters

Callback to notify completion or NULL to perform the enabling synchronously. The callback is called from the system
cb
workqueue.

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

◆ bt_foreach_bond()

void bt_foreach_bond ( uint8_t id,

void(* func )(const struct bt_bond_info *info, void *user_data),

void * user_data )

#include <zephyr/bluetooth/bluetooth.h>

Iterate through all existing bonds.

62
Parameters

id Local identity handle (typically BT_ID_DEFAULT). Corresponds to the identity address used in iteration.

func Function to call for each bond.

user_data Data to pass to the callback function.

◆ bt_get_appearance()

uint16_t bt_get_appearance ( void )

#include <zephyr/bluetooth/bluetooth.h>

Get local Bluetooth appearance.

Bluetooth Appearance is a description of the external appearance of a device in terms of an Appearance Value.

See also
Section 2.6 of the Bluetooth SIG Assigned Numbers document.

Returns
Appearance Value of local Bluetooth host.

◆ bt_get_name()

const char * bt_get_name ( void )

#include <zephyr/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 <zephyr/bluetooth/bluetooth.h>

Create a new identity address.

Create a new identity address using the given address and IRK. This function can be called before calling bt_enable. However, the

63
new identity address 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 address 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 identity addresses 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 identity addresses were recovered. If an insufficient amount of identity addresses were recovered the app may then call this
function to create new ones.

Note
If

CONFIG_BT_HCI_SET_PUBLIC_ADDR

is enabled, the first call can set a public address as the controller's identity, but only before bt_enable and if no other
identities exist.

Parameters

Address to use for the new identity address. If NULL or initialized to BT_ADDR_LE_ANY the stack will generate a new
addr random static address for the identity address and copy it to the given parameter upon return from this function (in case
the parameter was non-NULL).

Identity Resolving Key (16 octets) to be used with this identity address. If set to all zeroes or NULL, the stack will generate
a random IRK for the identity address and copy it back to the parameter upon return from this function (in case the
parameter was non-NULL). If privacy
irk
CONFIG_BT_PRIVACY

is not enabled this parameter must be NULL.

Returns
Identity handle (>= 0) in case of success, or a negative error code on failure.

◆ bt_id_delete()

int bt_id_delete ( uint8_t id )

#include <zephyr/bluetooth/bluetooth.h>

Delete an identity address.

When given a valid identity handle this function will disconnect any connections (to the corresponding identity address) created

64
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 address was occupying, the bt_id_reset API needs to be used.

Note
The default identity address (corresponding to BT_ID_DEFAULT) cannot be deleted, and this API will return an error if asked
to do that.

Parameters

id Existing identity handle.

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 <zephyr/bluetooth/bluetooth.h>

Get the currently configured identity addresses.

Returns an array of the currently configured identity addresses. To make sure all available identity addresses can be retrieved, the
number of elements in the addrs array should be

CONFIG_BT_ID_MAX

. The identity handle that some APIs expect (such as bt_le_adv_param) is simply the index of the identity address in the addrs
array.

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

Note
Deleted identity addresses may show up as BT_ADDR_LE_ANY in the returned array.

Parameters

addrs Array where to store the configured identity addresses.

count Should be initialized to the array size. Once the function returns it will contain the number of returned identity addresses.

65
◆ bt_id_reset()

int bt_id_reset ( uint8_t id,

bt_addr_le_t * addr,

uint8_t * irk )

#include <zephyr/bluetooth/bluetooth.h>

Reset/reclaim an identity address for reuse.

When given an existing identity handle, this function will disconnect any connections (to the corresponding identity address)
created using it, remove any pairing keys or other data associated with it, and then create a new identity address in the same slot,
based on the addr and irk parameters.

Note
The default identity address (corresponding to BT_ID_DEFAULT) cannot be reset, and this API will return an error if asked to
do that.

Parameters

id Existing identity handle.

Address to use for the new identity address. If NULL or initialized to BT_ADDR_LE_ANY the stack will generate a new
addr
static random address for the identity address and copy it to the given parameter upon return from this function.

Identity Resolving Key (16 octets) to be used with this identity address. If set to all zeroes or NULL, the stack will generate
a random IRK for the identity address and copy it back to the parameter upon return from this function (in case the
parameter was non-NULL). If privacy
irk
CONFIG_BT_PRIVACY

is not enabled this parameter must be NULL.

Returns
Identity handle (>= 0) in case of success, or a negative error code on failure.

◆ bt_is_ready()

bool bt_is_ready ( void )

#include <zephyr/bluetooth/bluetooth.h>

Check if Bluetooth is ready.

Returns
true when Bluetooth is ready, false otherwise

66
◆ 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 <zephyr/bluetooth/bluetooth.h>

Start advertising.

Set advertisement data, scan response data, advertisement parameters and start advertising.

When param.peer is set, the advertising will be directed to that peer device. In this case, the other function parameters are
ignored.

This function cannot be used with BT_LE_ADV_OPT_EXT_ADV in the param.options . For extended advertising, the
bt_le_ext_adv_* functions must be used.

Parameters

param Advertising parameters.

ad Data to be used in advertisement packets.

ad_len Number of elements in ad

sd Data to be used in scan response packets.

sd_len Number 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.

-EPERM When

CONFIG_BT_PRIVACY

and

CONFIG_BT_ID_AUTO_SWAP_MATCHING_BONDS

67
are enabled and connectable advertising is requested, and the given local identity has a conflicting key with another local identity
for which advertising is already started.

◆ bt_le_adv_stop()

int bt_le_adv_stop ( void )

#include <zephyr/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 <zephyr/bluetooth/bluetooth.h>

Update advertising.

Update advertisement and scan response data.

Parameters

ad Data to be used in advertisement packets.

ad_len Number of elements in ad

sd Data to be used in scan response packets.

sd_len Number of elements in sd

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

◆ bt_le_bond_exists()

bool bt_le_bond_exists ( uint8_t id,

68
 const bt_addr_le_t * addr )

#include <zephyr/bluetooth/bluetooth.h>

Check if a device identified by a Bluetooth LE address is bonded.

Valid Bluetooth LE identity addresses are either public address or random static address.

Parameters

id Local identity handle (typically BT_ID_DEFAULT). Corresponds to the identity address this function will be called for.

addr Bluetooth LE device address.

Returns
true if addr is bonded with local id

◆ 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 <zephyr/bluetooth/bluetooth.h>

Create advertising set.

Create an instance of an independent advertising set with its own parameters and data. The advertising set remains valid until
deleted with bt_le_ext_adv_delete. Advertising parameters can be updated with bt_le_ext_adv_update_param, and advertising
can be started with bt_le_ext_adv_start.

Note
The number of supported extended advertising sets can be controlled by

CONFIG_BT_EXT_ADV_MAX_ADV_SET

Parameters

[in] param Advertising parameters.

Callback struct to notify about advertiser activity. Can be NULL. Must point to valid memory during the lifetime
[in] cb
of the advertising set.

[out] adv Valid advertising set object on success.

69
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 <zephyr/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 if the limit

CONFIG_BT_EXT_ADV_MAX_ADV_SET

was reached.

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 <zephyr/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

adv Advertising set.

Returns
Index of the advertising set object. The range of the returned value is 0..

CONFIG_BT_EXT_ADV_MAX_ADV_SET

-1

70
◆ 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 <zephyr/bluetooth/bluetooth.h>

Get advertising set info.

Parameters

adv Advertising set object

info Advertising 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 <zephyr/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

CONFIG_BT_PRIVACY

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

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.

71
Parameters

[in] adv The advertising set object

[out] oob LE 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 <zephyr/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 and
only scan response data is used. When BT_LE_ADV_OPT_SCANNABLE is not enabled then scan response data is ignored and
only advertising data is used.

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 octets. 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
Extended advertising was introduced in Bluetooth 5.0, and legacy scanners will not support reception of any extended
advertising packets.

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

adv Advertising set object.

ad Data to be used in advertisement packets.

ad_len Number of elements in ad

72
 sd Data to be used in scan response packets.

sd_len Number 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,

const struct bt_le_ext_adv_start_param * param )

#include <zephyr/bluetooth/bluetooth.h>

Start advertising with the given advertising set.

If the advertiser is limited by either the param.timeout or param.num_events , the application will be notified by the
bt_le_ext_adv_cb::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.

Note
The advertising set adv can be created with bt_le_ext_adv_create.

Parameters

adv Advertising set object.

param Advertise start parameters.

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

-EPERM When

CONFIG_BT_PRIVACY

and

CONFIG_BT_ID_AUTO_SWAP_MATCHING_BONDS

are enabled and connectable advertising is requested, and the given local identity has a conflicting key with another local identity
for which advertising is already started.

◆ bt_le_ext_adv_stop()

int bt_le_ext_adv_stop ( struct bt_le_ext_adv * adv )

73
#include <zephyr/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

adv Advertising 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 <zephyr/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.

Note
When changing the option BT_LE_ADV_OPT_USE_NAME then bt_le_ext_adv_set_data needs to be called in order to
update the advertising data and scan response data.

Parameters

adv Advertising set object.

param Advertising parameters.

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

◆ bt_le_filter_accept_list_add()

int bt_le_filter_accept_list_add ( const bt_addr_le_t * addr )

#include <zephyr/bluetooth/bluetooth.h>

Add device (LE) to filter accept list.

Add peer device LE address to the filter accept list.

74
 Note
The filter accept list cannot be modified when an LE role is using the filter accept list, i.e advertiser or scanner using a filter
accept list or automatic connecting to devices using filter accept list.

Parameters

addr Bluetooth 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_filter_accept_list_clear()

int bt_le_filter_accept_list_clear ( void )

#include <zephyr/bluetooth/bluetooth.h>

Clear filter accept list.

Clear all devices from the filter accept list.

Note
The filter accept list cannot be modified when an LE role is using the filter accept list, i.e advertiser or scanner using a filter
accept list or automatic connecting to devices using filter accept list.

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

int bt_le_filter_accept_list_remove ( const bt_addr_le_t * addr )

#include <zephyr/bluetooth/bluetooth.h>

Remove device (LE) from filter accept list.

Remove peer device LE address from the filter accept list.

Note
The filter accept list cannot be modified when an LE role is using the filter accept list, i.e advertiser or scanner using a filter
accept list or automatic connecting to devices using filter accept list.

Parameters

addr Bluetooth LE identity address.

75
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_get_local_features()

int bt_le_get_local_features ( struct bt_le_local_features * local_features )

#include <zephyr/bluetooth/bluetooth.h>

Get local Bluetooth LE controller features.

Can only be called after bt_enable.

Parameters

local_features Local features struct to be populated with information.

Return values

0 Success

-EAGAIN The information is not yet available.

-EINVAL local_features is NULL.

◆ bt_le_oob_get_local()

int bt_le_oob_get_local ( uint8_t id,

struct bt_le_oob * oob )

#include <zephyr/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

CONFIG_BT_PRIVACY

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

CONFIG_BT_RPA_TIMEOUT

seconds. This address will be used for advertising started by bt_le_adv_start, active scanning and connection creation.

76
 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

CONFIG_BT_EXT_ADV

is not enabled or not supported by the controller:

• Advertiser is enabled using a Random Static Identity Address as a different local identity address.
• The local identity address conflicts with the local identity address used by other roles.

Parameters

[in] id Local identity handle (typically BT_ID_DEFAULT). Corresponds to the identity address this function will be called for.

[out] oob LE 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 <zephyr/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

addr Bluetooth LE identity address.

sid The 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 <zephyr/bluetooth/bluetooth.h>

Clear the periodic advertising list.

77
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 <zephyr/bluetooth/bluetooth.h>

Remove a device from the periodic advertising list.

Removes peer device LE address from the periodic advertising list.

Parameters

addr Bluetooth LE identity address.

sid The 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 <zephyr/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 (meaning, the advertising options BT_LE_ADV_OPT_SCANNABLE, BT_LE_ADV_OPT_CONNECTABLE
and BT_LE_ADV_OPT_ANONYMOUS cannot be set for adv ).

Parameters

adv Advertising set object.

ad Advertising data.

ad_len Advertising data length.

78
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 <zephyr/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

adv The periodic advertising set to transfer info of.

conn The peer device that will receive the information.

service_data Application 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 <zephyr/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 (meaning, the advertising options BT_LE_ADV_OPT_SCANNABLE, BT_LE_ADV_OPT_CONNECTABLE
and BT_LE_ADV_OPT_ANONYMOUS cannot be set for adv ).

Parameters

adv Advertising set object.

param Advertising parameters.

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

79
◆ bt_le_per_adv_set_response_data()

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 )

#include <zephyr/bluetooth/bluetooth.h>

Set the data for a response slot in a specific subevent of the PAwR.

This function is called by the application to set the response data. The data for a response slot shall be transmitted only once.

Parameters

per_adv_sync The periodic advertising sync object.

params Parameters.

data The response data to send.

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

◆ bt_le_per_adv_set_subevent_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 )

#include <zephyr/bluetooth/bluetooth.h>

Set the periodic advertising with response subevent data.

Set the data for one or more subevents of a Periodic Advertising with Responses Advertiser in reply data request.

Precondition
There are num_subevents elements in params .

The controller has requested data for the subevents in params .

Parameters

adv The extended advertiser the PAwR train belongs to.

num_subevents The number of subevents to set data for.

params Subevent parameters.

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

Parameters

adv Advertising 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 <zephyr/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

adv Advertising set object.

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

◆ bt_le_per_adv_sync_cb_register()

int bt_le_per_adv_sync_cb_register ( struct bt_le_per_adv_sync_cb * cb )

81
#include <zephyr/bluetooth/bluetooth.h>

Register periodic advertising sync callbacks.

Adds the callback structure to the list of callback structures for periodic advertising syncs.

This callback will be called for all periodic advertising sync activity, such as synced, terminated and when data is received.

Parameters

cb Callback struct. Must point to memory that remains valid.

Return values

0 Success.

-EEXIST if cb was already registered.

◆ 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 <zephyr/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.

This function does not timeout, and will continue to look for an advertiser until it either finds it or bt_le_per_adv_sync_delete is
called. It is thus suggested to implement a timeout when using this, if it is expected to find the advertiser within a reasonable
timeframe.

Parameters

[in] param Periodic advertising sync parameters.

[out] out_sync Periodic 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 <zephyr/bluetooth/bluetooth.h>

82
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 cannot be created until the controller has
finished canceling this object.

Parameters

per_adv_sync The 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 <zephyr/bluetooth/bluetooth.h>

Get array index of an periodic advertising sync object.

This function is to get the index of an array of periodic advertising sync objects. The array has

CONFIG_BT_PER_ADV_SYNC_MAX

elements.

Parameters

per_adv_sync The 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 <zephyr/bluetooth/bluetooth.h>

83
Get periodic adv sync information.

Parameters

per_adv_sync Periodic advertising sync object.

info Periodic 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 <zephyr/bluetooth/bluetooth.h>

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

Parameters

adv_addr Advertiser address.

sid The periodic advertising set ID.

Returns
Periodic advertising sync object or NULL if not found.

◆ bt_le_per_adv_sync_lookup_index()

struct bt_le_per_adv_sync * bt_le_per_adv_sync_lookup_index ( uint8_t index )

#include <zephyr/bluetooth/bluetooth.h>

Get a periodic advertising sync object from the array index.

This function is to get the periodic advertising sync object from the array index. The array has

CONFIG_BT_PER_ADV_SYNC_MAX

elements.

Parameters

index The index of the periodic advertising sync object. The range of the index value is 0..

84
 CONFIG_BT_PER_ADV_SYNC_MAX

-1

Returns
The periodic advertising sync object of the array index or NULL if invalid index.

◆ 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 <zephyr/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_sync The 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 <zephyr/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_sync The periodic advertising sync object.

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

◆ bt_le_per_adv_sync_subevent()

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 )

85
#include <zephyr/bluetooth/bluetooth.h>

Synchronize with a subset of subevents.

Until this command is issued, the subevent(s) the controller is synchronized to is unspecified.

Parameters

per_adv_sync The periodic advertising sync object.

params Subevent sync parameters.

Returns
0 in case of success or negative value in case of error.

◆ 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 <zephyr/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_sync The periodic advertising sync to transfer.

conn The peer device that will receive the sync information.

service_data Application 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 <zephyr/bluetooth/bluetooth.h>

Subscribe to periodic advertising sync transfers (PASTs).

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

Parameters

The connection to set the parameters for. If NULL default parameters for all connections will be set. Parameters set for
conn
specific connection will always have precedence.

param The 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 <zephyr/bluetooth/bluetooth.h>

Unsubscribe from periodic advertising sync transfers (PASTs).

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

Parameters

The connection to remove the parameters for. If NULL default parameters for all connections will be removed.
conn
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()

int bt_le_scan_cb_register ( struct bt_le_scan_cb * cb )

#include <zephyr/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.

Parameters

cb Callback struct. Must point to memory that remains valid.

87
Return values

0 Success.

-EEXIST if cb was already registered.

◆ bt_le_scan_cb_unregister()

void bt_le_scan_cb_unregister ( struct bt_le_scan_cb * cb )

#include <zephyr/bluetooth/bluetooth.h>

Unregister scanner packet callbacks.

Remove the callback structure from the list of scanner callbacks.

Parameters

cb Callback 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 <zephyr/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

CONFIG_BT_PRIVACY

is disabled. This is to prevent the active scanner from disclosing the identity address information when requesting additional
information from advertisers. In order to enable directed advertiser reports then

CONFIG_BT_SCAN_WITH_IDENTITY

must be enabled.

Setting the param.timeout parameter is not supported when

CONFIG_BT_PRIVACY

88
 is enabled, when the param.type is BT_LE_SCAN_TYPE_ACTIVE. Supplying a non-zero timeout will result in an -EINVAL error
code.

The scanner will automatically scan for extended advertising packets if their support is enabled through

CONFIG_BT_EXT_ADV

Parameters

param Scan parameters.

cb Callback 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.

Return values

-EBUSY if the scanner is already being started in a different thread.

◆ bt_le_scan_stop()

int bt_le_scan_stop ( void )

#include <zephyr/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 <zephyr/bluetooth/bluetooth.h>

Set (LE) channel map.

Used to inform the Controller of known channel classifications. The Host can specify which channels are bad or unknown by
setting the corresponding bit in the channel map to respectively 0 or 1.

89
 Note
The interval between two succesive calls to this function must be at least one second.

Parameters

chan_map Channel map. 5 octets where each bit represents a channel. Only the lower 37 bits are valid.

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

int bt_le_set_rpa_timeout ( uint16_t new_rpa_timeout )

#include <zephyr/bluetooth/bluetooth.h>

Set the Resolvable Private Address timeout in runtime.

The new RPA timeout value will be used for the next RPA rotation and all subsequent rotations until another override is scheduled
with this API.

Initially,

CONFIG_BT_RPA_TIMEOUT

is used as the RPA timeout.

Attention
Available only when the following Kconfig option is enabled:

CONFIG_BT_RPA_TIMEOUT_DYNAMIC

..

Parameters

new_rpa_timeout Resolvable Private Address timeout in seconds.

Return values

0 Success.

-EINVAL RPA timeout value is invalid. Valid range is 1s - 3600s.

90
◆ bt_set_appearance()

int bt_set_appearance ( uint16_t new_appearance )

#include <zephyr/bluetooth/bluetooth.h>

Set local Bluetooth appearance.

Automatically preserves the new appearance across reboots if

CONFIG_BT_SETTINGS

is enabled.

Attention
Available only when the following Kconfig option is enabled:

CONFIG_BT_DEVICE_APPEARANCE_DYNAMIC

Parameters

new_appearance Appearance Value

Return values

0 Success.

other Persistent storage failed. Appearance was not updated.

◆ bt_set_name()

int bt_set_name ( const char * name )

#include <zephyr/bluetooth/bluetooth.h>

Set Bluetooth Device Name.

Set Bluetooth GAP Device Name.

Note
The advertising data is not automatically updated. 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 after the call to this function.

Attention
Available only when the following Kconfig option is enabled:

91
 CONFIG_BT_DEVICE_NAME_DYNAMIC

See also

CONFIG_BT_DEVICE_NAME_MAX

Parameters

name New name, must be null terminated

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

◆ bt_unpair()

int bt_unpair ( uint8_t id,

const bt_addr_le_t * addr )

#include <zephyr/bluetooth/bluetooth.h>

Clear pairing information.

Parameters

id Local identity handle (typically BT_ID_DEFAULT). Corresponds to the identity address this function will be called for.

addr Remote address, NULL or BT_ADDR_LE_ANY to clear all remote devices.

Returns
0 on success or negative error value on failure.

92