Bluetooth APIs
APIs for classic Bluetooth (BR/EDR) and Bluetooth low-energy (LE).
Note
Using Bluetooth requires the Coral Wireless Add-on board (or similar add-on).
You need to include only the
libs/nxp/rt1176-sdk/edgefast_bluetooth/edgefast_bluetooth.h
header.
This header defines just the InitEdgefastBluetooth()
function but also
includes all the other Bluetooth APIs shown here.
Functions
-
void
InitEdgefastBluetooth
(bt_ready_cb_t cb)¶ Initializes Bluetooth for the Dev Board Micro.
Requires the Coral Wireless Add-on (or similar add-on board). This is a wrapper for
bt_enable()
and performs other board-specific setup. Note: This function is non-blocking and bluetooth could be uninitialized after return. Please checkBluetoothReady()
to make sure it is in fact initialized before using other functions.- Parameters
cb – Callback to notify when Bluetooth is enabled or fails to enable.
-
bool
BluetoothReady
()¶ Check if bluetooth is ready.
- Returns
true if bluetooth is ready, false if it is not.
-
bool
BluetoothAdvertise
()¶ Start bluetooth advertising.
- Returns
true id advertised successfully, false if advertise failed.
-
std::optional<std::vector<std::string>>
BluetoothScan
(int max_results, unsigned int scan_period_ms)¶ Performs bluetooth scan.
- Parameters
max_results – Number of scan results.
scan_period_ms – Time in ms to scan for devices.
- Returns
An array of bluetooth ids.
Bluetooth subsystem core APIs.
-
struct
bt_le_ext_adv_sent_info
¶ - #include <bluetooth.h>
Public Members
-
uint8_t
num_sent
¶ The number of advertising events completed.
-
uint8_t
-
struct
bt_le_ext_adv_connected_info
¶ - #include <bluetooth.h>
Public Members
-
struct bt_conn *
conn
¶ Connection object of the new connection
-
struct bt_conn *
-
struct
bt_le_ext_adv_scanned_info
¶ - #include <bluetooth.h>
Public Members
-
bt_addr_le_t *
addr
¶ Active scanner LE address and type
-
bt_addr_le_t *
-
struct
bt_le_ext_adv_cb
¶ - #include <bluetooth.h>
Public Members
-
void (*
sent
)(struct bt_le_ext_adv *adv, struct bt_le_ext_adv_sent_info *info)¶ The advertising set has finished sending adv data.
This callback notifies the application that the advertising set has finished sending advertising data. The advertising set can either have been stopped by a timeout or because the specified number of advertising events has been reached.
- Parameters
adv – The advertising set object.
info – Information about the sent event.
-
void (*
connected
)(struct bt_le_ext_adv *adv, struct bt_le_ext_adv_connected_info *info)¶ The advertising set has accepted a new connection.
This callback notifies the application that the advertising set has accepted a new connection.
- Parameters
adv – The advertising set object.
info – Information about the connected event.
-
void (*
scanned
)(struct bt_le_ext_adv *adv, struct bt_le_ext_adv_scanned_info *info)¶ The advertising set has sent scan response data.
This callback notifies the application that the advertising set has has received a Scan Request packet, and has sent a Scan Response packet.
- Parameters
adv – The advertising set object.
addr – Information about the scanned event.
-
void (*
-
struct
bt_data
¶ - #include <bluetooth.h>
Bluetooth data.
Description of different data types that can be encoded into advertising data. Used to form arrays that are passed to the bt_le_adv_start() function.
-
struct
bt_le_adv_param
¶ - #include <bluetooth.h>
LE Advertising Parameters.
Public Members
-
uint8_t
id
¶ Local identity.
Note
When extended advertising @option{CONFIG_BT_EXT_ADV} is not enabled or not supported by the controller it is not possible to scan and advertise simultaneously using two different random addresses.
-
uint8_t
sid
¶ Advertising Set Identifier, valid range 0x00 - 0x0f.
Note
Requires BT_LE_ADV_OPT_EXT_ADV
-
uint8_t
secondary_max_skip
¶ Secondary channel maximum skip count.
Maximum advertising events the advertiser can skip before it must send advertising data on the secondary advertising channel.
Note
Requires BT_LE_ADV_OPT_EXT_ADV
-
uint32_t
options
¶ Bit-field of advertising options
-
uint32_t
interval_min
¶ Minimum Advertising Interval (N * 0.625 milliseconds) Minimum Advertising Interval shall be less than or equal to the Maximum Advertising Interval. The Minimum Advertising Interval and Maximum Advertising Interval should not be the same value (as stated in Bluetooth Core Spec 5.2, section 7.8.5) Range: 0x0020 to 0x4000
-
uint32_t
interval_max
¶ Maximum Advertising Interval (N * 0.625 milliseconds) Minimum Advertising Interval shall be less than or equal to the Maximum Advertising Interval. The Minimum Advertising Interval and Maximum Advertising Interval should not be the same value (as stated in Bluetooth Core Spec 5.2, section 7.8.5) Range: 0x0020 to 0x4000
-
const bt_addr_le_t *
peer
¶ Directed advertising to peer.
When this parameter is set the advertiser will send directed advertising to the remote device.
The advertising type will either be high duty cycle, or low duty cycle if the BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY option is enabled. When using BT_LE_ADV_OPT_EXT_ADV then only low duty cycle is allowed.
In case of connectable high duty cycle if the connection could not be established within the timeout the connected() callback will be called with the status set to BT_HCI_ERR_ADV_TIMEOUT.
-
uint8_t
-
struct
bt_le_per_adv_param
¶ - #include <bluetooth.h>
Public Members
-
uint16_t
interval_min
¶ Minimum Periodic Advertising Interval (N * 1.25 ms)
Shall be greater or equal to BT_GAP_PER_ADV_MIN_INTERVAL and less or equal to interval_max.
-
uint16_t
interval_max
¶ Maximum Periodic Advertising Interval (N * 1.25 ms)
Shall be less or equal to BT_GAP_PER_ADV_MAX_INTERVAL and greater or equal to interval_min.
-
uint32_t
options
¶ Bit-field of periodic advertising options
-
uint16_t
-
struct
bt_le_ext_adv_start_param
¶ - #include <bluetooth.h>
Public Members
-
uint16_t
timeout
¶ Advertiser timeout (N * 10 ms).
Application will be notified by the advertiser sent callback. Set to zero for no timeout.
When using high duty cycle directed connectable advertising then this parameters must be set to a non-zero value less than or equal to the maximum of BT_GAP_ADV_HIGH_DUTY_CYCLE_MAX_TIMEOUT.
If privacy @option{CONFIG_BT_PRIVACY} is enabled then the timeout must be less than @option{CONFIG_BT_RPA_TIMEOUT}.
-
uint8_t
num_events
¶ Number of advertising events.
Application will be notified by the advertiser sent callback. Set to zero for no limit.
-
uint16_t
-
struct
bt_le_ext_adv_info
¶ - #include <bluetooth.h>
Advertising set info structure.
-
struct
bt_le_per_adv_sync_synced_info
¶ - #include <bluetooth.h>
Public Members
-
const bt_addr_le_t *
addr
¶ Advertiser LE address and type.
-
uint8_t
sid
¶ Advertiser SID
-
uint16_t
interval
¶ Periodic advertising interval (N * 1.25 ms)
-
uint8_t
phy
¶ Advertiser PHY
-
bool
recv_enabled
¶ True if receiving periodic advertisements, false otherwise.
-
uint16_t
service_data
¶ Service Data provided by the peer when sync is transferred.
Will always be 0 when the sync is locally created.
-
struct bt_conn *
conn
¶ Peer that transferred the periodic advertising sync.
Will always be 0 when the sync is locally created.
-
const bt_addr_le_t *
-
struct
bt_le_per_adv_sync_term_info
¶ - #include <bluetooth.h>
-
struct
bt_le_per_adv_sync_recv_info
¶ - #include <bluetooth.h>
Public Members
-
const bt_addr_le_t *
addr
¶ Advertiser LE address and type.
-
uint8_t
sid
¶ Advertiser SID
-
int8_t
tx_power
¶ The TX power of the advertisement.
-
int8_t
rssi
¶ The RSSI of the advertisement excluding any CTE.
-
uint8_t
cte_type
¶ The Constant Tone Extension (CTE) of the advertisement (bt_df_cte_type)
-
const bt_addr_le_t *
-
struct
bt_le_per_adv_sync_state_info
¶ - #include <bluetooth.h>
Public Members
-
bool
recv_enabled
¶ True if receiving periodic advertisements, false otherwise.
-
bool
-
struct
bt_le_per_adv_sync_cb
¶ - #include <bluetooth.h>
Public Members
-
void (*
synced
)(struct bt_le_per_adv_sync *sync, struct bt_le_per_adv_sync_synced_info *info)¶ The periodic advertising has been successfully synced.
This callback notifies the application that the periodic advertising set has been successfully synced, and will now start to receive periodic advertising reports.
- Parameters
sync – The periodic advertising sync object.
info – Information about the sync event.
-
void (*
term
)(struct bt_le_per_adv_sync *sync, const struct bt_le_per_adv_sync_term_info *info)¶ The periodic advertising sync has been terminated.
This callback notifies the application that the periodic advertising sync has been terminated, either by local request, remote request or because due to missing data, e.g. by being out of range or sync.
- Parameters
sync – The periodic advertising sync object.
-
void (*
recv
)(struct bt_le_per_adv_sync *sync, const struct bt_le_per_adv_sync_recv_info *info, struct net_buf_simple *buf)¶ Periodic advertising data received.
This callback notifies the application of an periodic advertising report.
- Parameters
sync – The advertising set object.
info – Information about the periodic advertising event.
buf – Buffer containing the periodic advertising data.
-
void (*
state_changed
)(struct bt_le_per_adv_sync *sync, const struct bt_le_per_adv_sync_state_info *info)¶ The periodic advertising sync state has changed.
This callback notifies the application about changes to the sync state. Initialize sync and termination is handled by their individual callbacks, and won’t be notified here.
- Parameters
sync – The periodic advertising sync object.
info – Information about the state change.
-
void (*
biginfo
)(struct bt_le_per_adv_sync *sync, const struct bt_iso_biginfo *biginfo)¶ BIGInfo advertising report received.
This callback notifies the application of a BIGInfo advertising report. This is received if the advertiser is broadcasting isochronous streams in a BIG. See iso.h for more information.
- Parameters
sync – The advertising set object.
biginfo – The BIGInfo report.
-
void (*
cte_report_cb
)(struct bt_le_per_adv_sync *sync, struct bt_df_per_adv_sync_iq_samples_reportconst *info)¶ Callback for IQ samples report collected when sampling CTE received with periodic advertising PDU.
- Parameters
sync – The periodic advertising sync object.
info – Information about the sync event.
-
sys_snode_t
node
¶
-
void (*
-
struct
bt_le_per_adv_sync_param
¶ - #include <bluetooth.h>
Public Members
-
bt_addr_le_t
addr
¶ Periodic Advertiser Address.
Only valid if not using the periodic advertising list
-
uint8_t
sid
¶ Advertiser SID.
Only valid if not using the periodic advertising list
-
uint32_t
options
¶ Bit-field of periodic advertising sync options.
-
uint16_t
skip
¶ Maximum event skip.
Maximum number of periodic advertising events that can be skipped after a successful receive
-
uint16_t
timeout
¶ Synchronization timeout (N * 10 ms)
Synchronization timeout for the periodic advertising sync. Range 0x000A to 0x4000 (100 ms to 163840 ms)
-
bt_addr_le_t
-
struct
bt_le_per_adv_sync_info
¶ - #include <bluetooth.h>
Advertising set info structure.
-
struct
bt_le_per_adv_sync_transfer_param
¶ - #include <bluetooth.h>
Public Members
-
uint16_t
skip
¶ Maximum event skip.
The number of periodic advertising packets that can be skipped after a successful receive.
-
uint16_t
timeout
¶ Synchronization timeout (N * 10 ms)
Synchronization timeout for the periodic advertising sync. Range 0x000A to 0x4000 (100 ms to 163840 ms)
-
uint32_t
options
¶ Periodic Advertising Sync Transfer options
-
uint16_t
-
struct
bt_le_scan_param
¶ - #include <bluetooth.h>
LE scan parameters
Public Members
-
uint8_t
type
¶ Scan type (BT_LE_SCAN_TYPE_ACTIVE or BT_LE_SCAN_TYPE_PASSIVE)
-
uint32_t
options
¶ Bit-field of scanning options.
-
uint16_t
interval
¶ Scan interval (N * 0.625 ms)
-
uint16_t
window
¶ Scan window (N * 0.625 ms)
-
uint16_t
timeout
¶ Scan timeout (N * 10 ms)
Application will be notified by the scan timeout callback. Set zero to disable timeout.
-
uint16_t
interval_coded
¶ Scan interval LE Coded PHY (N * 0.625 MS)
Set zero to use same as LE 1M PHY scan interval.
-
uint16_t
window_coded
¶ Scan window LE Coded PHY (N * 0.625 MS)
Set zero to use same as LE 1M PHY scan window.
-
uint8_t
-
struct
bt_le_scan_recv_info
¶ - #include <bluetooth.h>
LE advertisement packet information
Public Members
-
const bt_addr_le_t *
addr
¶ Advertiser LE address and type.
If advertiser is anonymous then this address will be BT_ADDR_LE_ANY.
-
uint8_t
sid
¶ Advertising Set Identifier.
-
int8_t
rssi
¶ Strength of advertiser signal.
-
int8_t
tx_power
¶ Transmit power of the advertiser.
-
uint8_t
adv_type
¶ Advertising packet type.
-
uint16_t
adv_props
¶ Advertising packet properties.
-
uint16_t
interval
¶ Periodic advertising interval.
If 0 there is no periodic advertising.
-
uint8_t
primary_phy
¶ Primary advertising channel PHY.
-
uint8_t
secondary_phy
¶ Secondary advertising channel PHY.
-
const bt_addr_le_t *
-
struct
bt_le_scan_cb
¶ - #include <bluetooth.h>
Listener context for (LE) scanning.
Public Members
-
void (*
recv
)(const struct bt_le_scan_recv_info *info, struct net_buf_simple *buf)¶ Advertisement packet received callback.
- Parameters
info – Advertiser packet information.
buf – Buffer containing advertiser data.
-
void (*
timeout
)(void)¶ The scanner has stopped scanning after scan timeout.
-
sys_snode_t
node
¶
-
void (*
-
struct
bt_le_oob_sc_data
¶ - #include <bluetooth.h>
LE Secure Connections pairing Out of Band data.
-
struct
bt_le_oob
¶ - #include <bluetooth.h>
LE Out of Band information.
Public Members
-
bt_addr_le_t
addr
¶ LE address. If privacy is enabled this is a Resolvable Private Address.
-
struct bt_le_oob_sc_data
le_sc_data
¶ LE Secure Connections pairing Out of Band data.
-
bt_addr_le_t
-
struct
bt_br_discovery_result
¶ - #include <bluetooth.h>
BR/EDR discovery result structure.
-
struct
bt_br_discovery_param
¶ - #include <bluetooth.h>
BR/EDR discovery parameters
-
struct
bt_bond_info
¶ - #include <bluetooth.h>
Information about a bond with a remote device.
Public Members
-
bt_addr_le_t
addr
¶ Address of the remote device.
-
bt_addr_le_t
Defines
-
BT_ID_DEFAULT
¶ Convenience macro for specifying the default identity. This helps make the code more readable, especially when only one identity is supported.
-
BT_DATA
(_type, _data, _data_len)¶ Helper to declare elements of bt_data arrays.
This macro is mainly for creating an array of struct bt_data elements which is then passed to e.g. bt_le_adv_start().
- Parameters
_type – Type of advertising data field
_data – Pointer to the data field payload
_data_len – Number of bytes behind the _data pointer
-
BT_DATA_BYTES(_type, _bytes...)
Helper to declare elements of bt_data arrays.
This macro is mainly for creating an array of struct bt_data elements which is then passed to e.g. bt_le_adv_start().
- Parameters
_type – Type of advertising data field
_bytes – Variable number of single-byte parameters
-
BT_LE_ADV_PARAM_INIT
(_options, _int_min, _int_max, _peer)¶ 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_ADV_PARAM
(_options, _int_min, _int_max, _peer)¶ 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_CONN_DIR
(_peer)¶
-
BT_LE_ADV_CONN
¶
-
BT_LE_ADV_CONN_NAME
¶
-
BT_LE_ADV_CONN_NAME_AD
¶
-
BT_LE_ADV_CONN_DIR_LOW_DUTY
(_peer)¶
-
BT_LE_ADV_NCONN
¶ Non-connectable advertising with private address
-
BT_LE_ADV_NCONN_NAME
¶ Non-connectable advertising with BT_LE_ADV_OPT_USE_NAME
-
BT_LE_ADV_NCONN_IDENTITY
¶ Non-connectable advertising with BT_LE_ADV_OPT_USE_IDENTITY
-
BT_LE_EXT_ADV_CONN_NAME
¶ Connectable extended advertising with BT_LE_ADV_OPT_USE_NAME
-
BT_LE_EXT_ADV_NCONN
¶ Non-connectable extended advertising with private address
-
BT_LE_EXT_ADV_NCONN_NAME
¶ Non-connectable extended advertising with BT_LE_ADV_OPT_USE_NAME
-
BT_LE_EXT_ADV_NCONN_IDENTITY
¶ Non-connectable extended advertising with BT_LE_ADV_OPT_USE_IDENTITY
-
BT_LE_EXT_ADV_CODED_NCONN
¶ Non-connectable extended advertising on coded PHY with private address
-
BT_LE_EXT_ADV_CODED_NCONN_NAME
¶ Non-connectable extended advertising on coded PHY with BT_LE_ADV_OPT_USE_NAME
-
BT_LE_EXT_ADV_CODED_NCONN_IDENTITY
¶ Non-connectable extended advertising on coded PHY with BT_LE_ADV_OPT_USE_IDENTITY
-
BT_LE_EXT_ADV_START_PARAM_INIT
(_timeout, _n_evts)¶ Helper to initialize extended advertising start parameters inline
- Parameters
_timeout – Advertiser timeout
_n_evts – Number of advertising events
-
BT_LE_EXT_ADV_START_PARAM
(_timeout, _n_evts)¶ Helper to declare extended advertising start parameters inline
- Parameters
_timeout – Advertiser timeout
_n_evts – Number of advertising events
-
BT_LE_EXT_ADV_START_DEFAULT
¶
-
BT_LE_PER_ADV_PARAM_INIT
(_int_min, _int_max, _options)¶ Helper to declare periodic advertising parameters inline
- Parameters
_int_min – Minimum periodic advertising interval
_int_max – Maximum periodic advertising interval
_options – Periodic advertising properties bitfield.
-
BT_LE_PER_ADV_PARAM
(_int_min, _int_max, _options)¶ Helper to declare periodic advertising parameters inline
- Parameters
_int_min – Minimum periodic advertising interval
_int_max – Maximum periodic advertising interval
_options – Periodic advertising properties bitfield.
-
BT_LE_PER_ADV_DEFAULT
¶
-
BT_LE_SCAN_PARAM_INIT
(_type, _options, _interval, _window)¶ 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_PARAM
(_type, _options, _interval, _window)¶ 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_ACTIVE
¶ Helper macro to enable active scanning to discover new devices.
-
BT_LE_SCAN_PASSIVE
¶ 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_CODED_ACTIVE
¶ 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
¶ 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.
Functions
-
int
bt_enable
(bt_ready_cb_t cb)¶ Enable Bluetooth.
Enable Bluetooth. Must be the called before any calls that require communication with the local Bluetooth hardware.
- Parameters
cb – Callback to notify completion or NULL to perform the enabling synchronously.
- Returns
Zero on success or (negative) error code otherwise.
-
int
bt_set_name
(const char *name)¶ Set Bluetooth Device Name.
Set Bluetooth GAP Device Name.
When advertising with device name in the advertising data the name should be updated by calling bt_le_adv_update_data or bt_le_ext_adv_set_data.
- Parameters
name – New name
- Returns
Zero on success or (negative) error code otherwise.
-
const char *
bt_get_name
(void)¶ Get Bluetooth Device Name.
Get Bluetooth GAP Device Name.
- Returns
Bluetooth Device Name
-
__deprecated int bt_set_id_addr (const bt_addr_le_t *addr)
Set the local Identity Address.
Allows setting the local Identity Address from the application. This API must be called before calling bt_enable(). Calling it at any other time will cause it to fail. In most cases the application doesn’t need to use this API, however there are a few valid cases where it can be useful (such as for testing).
At the moment, the given address must be a static random address. In the future support for public addresses may be added.
- Deprecated:
in 2.5 release, replace with bt_id_create before bt_enable.
- Returns
Zero on success or (negative) error code otherwise.
-
void
bt_id_get
(bt_addr_le_t *addrs, size_t *count)¶ Get the currently configured identities.
Returns an array of the currently configured identity addresses. To make sure all available identities can be retrieved, the number of elements in the addrs array should be CONFIG_BT_ID_MAX. The identity identifier that some APIs expect (such as advertising parameters) is simply the index of the identity in the addrs array.
If addrs is passed as NULL, then returned count contains the count of all available identities that can be retrieved with a subsequent call to this function with non-NULL addrs parameter.
- Parameters
addrs – Array where to store the configured identities.
count – Should be initialized to the array size. Once the function returns it will contain the number of returned identities.
Note
Deleted identities may show up as BT_LE_ADDR_ANY in the returned array.
-
int
bt_id_create
(bt_addr_le_t *addr, uint8_t *irk)¶ Create a new identity.
Create a new identity using the given address and IRK. This function can be called before calling bt_enable(), in which case it can be used to override the controller’s public address (in case it has one). However, the new identity will only be stored persistently in flash when this API is used after bt_enable(). The reason is that the persistent settings are loaded after bt_enable() and would therefore cause potential conflicts with the stack blindly overwriting what’s stored in flash. The identity will also not be written to flash in case a pre-defined address is provided, since in such a situation the app clearly has some place it got the address from and will be able to repeat the procedure on every power cycle, i.e. it would be redundant to also store the information in flash.
Generating random static address or random IRK is not supported when calling this function before bt_enable().
If the application wants to have the stack randomly generate identities and store them in flash for later recovery, the way to do it would be to first initialize the stack (using bt_enable), then call settings_load(), and after that check with bt_id_get() how many identities were recovered. If an insufficient amount of identities were recovered the app may then call bt_id_create() to create new ones.
- Parameters
addr – Address to use for the new identity. If NULL or initialized to BT_ADDR_LE_ANY the stack will generate a new random static address for the identity and copy it to the given parameter upon return from this function (in case the parameter was non-NULL).
irk – Identity Resolving Key (16 bytes) to be used with this identity. If set to all zeroes or NULL, the stack will generate a random IRK for the identity and copy it back to the parameter upon return from this function (in case the parameter was non-NULL). If privacy @option{CONFIG_BT_PRIVACY} is not enabled this parameter must be NULL.
- Returns
Identity identifier (>= 0) in case of success, or a negative error code on failure.
-
int
bt_id_reset
(uint8_t id, bt_addr_le_t *addr, uint8_t *irk)¶ Reset/reclaim an identity for reuse.
The semantics of the addr and irk parameters of this function are the same as with bt_id_create(). The difference is the first id parameter that needs to be an existing identity (if it doesn’t exist this function will return an error). When given an existing identity this function will disconnect any connections created using it, remove any pairing keys or other data associated with it, and then create a new identity in the same slot, based on the addr and irk parameters.
- Parameters
id – Existing identity identifier.
addr – Address to use for the new identity. If NULL or initialized to BT_ADDR_LE_ANY the stack will generate a new static random address for the identity and copy it to the given parameter upon return from this function (in case the parameter was non-NULL).
irk – Identity Resolving Key (16 bytes) to be used with this identity. If set to all zeroes or NULL, the stack will generate a random IRK for the identity and copy it back to the parameter upon return from this function (in case the parameter was non-NULL). If privacy @option{CONFIG_BT_PRIVACY} is not enabled this parameter must be NULL.
- Returns
Identity identifier (>= 0) in case of success, or a negative error code on failure.
Note
the default identity (BT_ID_DEFAULT) cannot be reset, i.e. this API will return an error if asked to do that.
-
int
bt_id_delete
(uint8_t id)¶ Delete an identity.
When given a valid identity this function will disconnect any connections created using it, remove any pairing keys or other data associated with it, and then flag is as deleted, so that it can not be used for any operations. To take back into use the slot the identity was occupying the bt_id_reset() API needs to be used.
- Parameters
id – Existing identity identifier.
- Returns
0 in case of success, or a negative error code on failure.
Note
the default identity (BT_ID_DEFAULT) cannot be deleted, i.e. this API will return an error if asked to do that.
-
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.
Set advertisement data, scan response data, advertisement parameters and start advertising.
When the advertisement parameter peer address has been set the advertising will be directed to the peer. In this case advertisement data and scan response data parameters are ignored. If the mode is high duty cycle the timeout will be BT_GAP_ADV_HIGH_DUTY_CYCLE_MAX_TIMEOUT.
- Parameters
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.
- Returns
-ENOMEM No free connection objects available for connectable advertiser.
- Returns
-ECONNREFUSED When connectable advertising is requested and there is already maximum number of connections established in the controller. This error code is only guaranteed when using Zephyr controller, for other controllers code returned in this case may be -EIO.
-
int
bt_le_adv_update_data
(const struct bt_data *ad, size_t ad_len, const struct bt_data *sd, size_t sd_len)¶ 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.
-
int
bt_le_adv_stop
(void)¶ Stop advertising.
Stops ongoing advertising.
- Returns
Zero on success or (negative) error code otherwise.
-
int
bt_le_ext_adv_create
(const struct bt_le_adv_param *param, const struct bt_le_ext_adv_cb *cb, struct bt_le_ext_adv **adv)¶ Create advertising set.
Create a new advertising set and set advertising parameters. Advertising parameters can be updated with bt_le_ext_adv_update_param.
- Parameters
param – [in] Advertising parameters.
cb – [in] Callback struct to notify about advertiser activity. Can be NULL. Must point to valid memory during the lifetime of the advertising set.
adv – [out] Valid advertising set object on success.
- Returns
Zero on success or (negative) error code otherwise.
-
int
bt_le_ext_adv_start
(struct bt_le_ext_adv *adv, struct bt_le_ext_adv_start_param *param)¶ Start advertising with the given advertising set.
If the advertiser is limited by either the timeout or number of advertising events the application will be notified by the advertiser sent callback once the limit is reached. If the advertiser is limited by both the timeout and the number of advertising events then the limit that is reached first will stop the advertiser.
- Parameters
adv – Advertising set object.
param – Advertise start parameters.
-
int
bt_le_ext_adv_stop
(struct bt_le_ext_adv *adv)¶ 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.
-
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.
Set advertisement data or scan response data. If the advertising set is currently advertising then the advertising data will be updated in subsequent advertising events.
When both BT_LE_ADV_OPT_EXT_ADV and BT_LE_ADV_OPT_SCANNABLE are enabled then advertising data is ignored. When BT_LE_ADV_OPT_SCANNABLE is not enabled then scan response data is ignored.
If the advertising set has been configured to send advertising data on the primary advertising channels then the maximum data length is BT_GAP_ADV_MAX_ADV_DATA_LEN bytes. If the advertising set has been configured for extended advertising, then the maximum data length is defined by the controller with the maximum possible of BT_GAP_ADV_MAX_EXT_ADV_DATA_LEN bytes.
- Parameters
adv – Advertising set object.
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.
Note
Not all scanners support extended data length advertising data.
Note
When updating the advertising data while advertising the advertising data and scan response data length must be smaller or equal to what can be fit in a single advertising packet. Otherwise the advertiser must be stopped.
-
int
bt_le_ext_adv_update_param
(struct bt_le_ext_adv *adv, const struct bt_le_adv_param *param)¶ Update advertising parameters.
Update the advertising parameters. The function will return an error if the advertiser set is currently advertising. Stop the advertising set before calling this function.
- Parameters
adv – Advertising set object.
param – Advertising parameters.
- Returns
Zero on success or (negative) error code otherwise.
-
int
bt_le_ext_adv_delete
(struct bt_le_ext_adv *adv)¶ Delete advertising set.
Delete advertising set. This will free up the advertising set and make it possible to create a new advertising set.
- Returns
Zero on success or (negative) error code otherwise.
-
uint8_t
bt_le_ext_adv_get_index
(struct bt_le_ext_adv *adv)¶ 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
-
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.
- Parameters
adv – Advertising set object
info – Advertising set info object
- Returns
Zero on success or (negative) error code on failure.
-
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.
The periodic advertising parameters can only be set or updated on an extended advertisement set which is neither scannable, connectable nor anonymous.
- Parameters
adv – Advertising set object.
param – Advertising parameters.
- Returns
Zero on success or (negative) error code otherwise.
-
int
bt_le_per_adv_set_data
(const struct bt_le_ext_adv *adv, const struct bt_data *ad, size_t ad_len)¶ Set or update the periodic advertising data.
The periodic advertisement data can only be set or updated on an extended advertisement set which is neither scannable, connectable nor anonymous.
- Parameters
adv – Advertising set object.
ad – Advertising data.
ad_len – Advertising data length.
- Returns
Zero on success or (negative) error code otherwise.
-
int
bt_le_per_adv_start
(struct bt_le_ext_adv *adv)¶ Starts periodic advertising.
Enabling the periodic advertising can be done independently of extended advertising, but both periodic advertising and extended advertising shall be enabled before any periodic advertising data is sent. The periodic advertising and extended advertising can be enabled in any order.
Once periodic advertising has been enabled, it will continue advertising until bt_le_per_adv_stop() has been called, or if the advertising set is deleted by bt_le_ext_adv_delete(). Calling bt_le_ext_adv_stop() will not stop the periodic advertising.
- Parameters
adv – Advertising set object.
- Returns
Zero on success or (negative) error code otherwise.
-
int
bt_le_per_adv_stop
(struct bt_le_ext_adv *adv)¶ 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.
-
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.
This function is get the index of an array of periodic advertising sync objects. The array has CONFIG_BT_PER_ADV_SYNC_MAX elements.
- Parameters
per_adv_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
-
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.
- Parameters
per_adv_sync – Periodic advertising sync object.
info – Periodic advertising sync info object
- Returns
Zero on success or (negative) error code on failure.
-
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.
- Parameters
adv_addr – Advertiser address.
sid – The advertising set ID.
- Returns
Periodic advertising sync object or NULL if not found.
-
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.
Create a periodic advertising sync object that can try to synchronize to periodic advertising reports from an advertiser. Scan shall either be disabled or extended scan shall be enabled.
- Parameters
param – [in] Periodic advertising sync parameters.
out_sync – [out] Periodic advertising sync object on.
- Returns
Zero on success or (negative) error code otherwise.
-
int
bt_le_per_adv_sync_delete
(struct bt_le_per_adv_sync *per_adv_sync)¶ Delete periodic advertising sync.
Delete the periodic advertising sync object. Can be called regardless of the state of the sync. If the syncing is currently syncing, the syncing is cancelled. If the sync has been established, it is terminated. The periodic advertising sync object will be invalidated afterwards.
If the state of the sync object is syncing, then a new periodic advertising sync object may not be created until the controller has finished canceling this object.
- Parameters
per_adv_sync – The periodic advertising sync object.
- Returns
Zero on success or (negative) error code otherwise.
-
void
bt_le_per_adv_sync_cb_register
(struct bt_le_per_adv_sync_cb *cb)¶ Register periodic advertising sync callbacks.
Adds the callback structure to the list of callback structures for periodic adverising syncs.
This callback will be called for all periodic advertising sync activity, such as synced, terminated and when data is received.
- Parameters
cb – Callback struct. Must point to memory that remains valid.
-
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.
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.
-
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.
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.
-
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.
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.
-
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.
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.
-
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).
Sets the parameters and allow other devices to transfer periodic advertising syncs.
- Parameters
conn – The connection to set the parameters for. If NULL default parameters for all connections will be set. Parameters set for specific connection will always have precedence.
param – The periodic advertising sync transfer parameters.
- Returns
Zero on success or (negative) error code otherwise.
-
int
bt_le_per_adv_sync_transfer_unsubscribe
(const struct bt_conn *conn)¶ Unsubscribe from periodic advertising sync transfers (PASTs).
Remove the parameters that allow other devices to transfer periodic advertising syncs.
- Parameters
conn – The connection to remove the parameters for. If NULL default parameters for all connections will be removed. Unsubscribing for a specific device, will still allow other devices to transfer periodic advertising syncs.
- Returns
Zero on success or (negative) error code otherwise.
-
int
bt_le_per_adv_list_add
(const bt_addr_le_t *addr, uint8_t sid)¶ 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.
-
int
bt_le_per_adv_list_remove
(const bt_addr_le_t *addr, uint8_t sid)¶ 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.
-
int
bt_le_per_adv_list_clear
(void)¶ Clear the periodic advertising list.
Clears the entire periodic advertising list.
- Returns
Zero on success or (negative) error code otherwise.
-
int
bt_le_scan_start
(const struct bt_le_scan_param *param, bt_le_scan_cb_t cb)¶ Start (LE) scanning.
Start LE scanning with given parameters and provide results through the specified callback.
- 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.
Note
The LE scanner by default does not use the Identity Address of the local device when @option{CONFIG_BT_PRIVACY} is disabled. This is to prevent the active scanner from disclosing the identity information when requesting additional information from advertisers. In order to enable directed advertiser reports then @option{CONFIG_BT_SCAN_WITH_IDENTITY} must be enabled.
-
int
bt_le_scan_stop
(void)¶ 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.
-
void
bt_le_scan_cb_register
(struct bt_le_scan_cb *cb)¶ Register scanner packet callbacks.
Adds the callback structure to the list of callback structures that monitors scanner activity.
This callback will be called for all scanner activity, regardless of what API was used to start the scanner.
- Parameters
cb – Callback struct. Must point to memory that remains valid.
-
void
bt_le_scan_cb_unregister
(struct bt_le_scan_cb *cb)¶ 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.
-
int
bt_le_whitelist_add
(const bt_addr_le_t *addr)¶ Add device (LE) to whitelist.
Add peer device LE address to the whitelist.
- 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.
Note
The whitelist cannot be modified when an LE role is using the whitelist, i.e advertiser or scanner using a whitelist or automatic connecting to devices using whitelist.
-
int
bt_le_whitelist_rem
(const bt_addr_le_t *addr)¶ Remove device (LE) from whitelist.
Remove peer device LE address from the whitelist.
- 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.
Note
The whitelist cannot be modified when an LE role is using the whitelist, i.e advertiser or scanner using a whitelist or automatic connecting to devices using whitelist.
-
int
bt_le_whitelist_clear
(void)¶ Clear whitelist.
Clear all devices from the whitelist.
- Returns
Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error.
Note
The whitelist cannot be modified when an LE role is using the whitelist, i.e advertiser or scanner using a whitelist or automatic connecting to devices using whitelist.
-
int
bt_le_set_chan_map
(uint8_t chan_map[5])¶ Set (LE) channel map.
- Parameters
chan_map – Channel map.
- Returns
Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error.
-
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.
A helper for parsing the basic data types used for Extended Inquiry Response (EIR), Advertising Data (AD), and OOB data blocks. The most common scenario is to call this helper on the advertising data received in the callback that was given to bt_le_scan_start().
- Parameters
ad – Advertising data as given to the bt_le_scan_cb_t callback.
func – Callback function which will be called for each element that’s found in the data. The callback should return true to continue parsing, or false to stop parsing.
user_data – User data to be passed to the callback.
-
int
bt_le_oob_get_local
(uint8_t id, struct bt_le_oob *oob)¶ Get local LE Out of Band (OOB) information.
This function allows to get local information that are useful for Out of Band pairing or connection creation.
If privacy @option{CONFIG_BT_PRIVACY} is enabled this will result in generating new Resolvable Private Address (RPA) that is valid for @option{CONFIG_BT_RPA_TIMEOUT} seconds. This address will be used for advertising started by bt_le_adv_start, active scanning and connection creation.
- Parameters
id – [in] Local identity, in most cases BT_ID_DEFAULT.
oob – [out] 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.
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 @option{CONFIG_BT_EXT_ADV} is not enabled or not supported by the controller:
Advertiser is enabled using a Random Static Identity Address for a different local identity.
The local identity conflicts with the local identity used by other roles.
-
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.
This function allows to get local information that are useful for Out of Band pairing or connection creation.
If privacy @option{CONFIG_BT_PRIVACY} is enabled this will result in generating new Resolvable Private Address (RPA) that is valid for @option{CONFIG_BT_RPA_TIMEOUT} seconds. This address will be used by the advertising set.
- Parameters
adv – [in] The advertising set object
oob – [out] 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.
Note
When generating OOB information for multiple advertising set all OOB information needs to be generated at the same time.
Note
If privacy is enabled the RPA cannot be refreshed in the following cases:
Creating a connection in progress, wait for the connected callback.
-
int
bt_br_discovery_start
(const struct bt_br_discovery_param *param, struct bt_br_discovery_result *results, size_t count, bt_br_discovery_cb_t cb)¶ Start BR/EDR discovery.
Start BR/EDR discovery (inquiry) and provide results through the specified callback. When bt_br_discovery_cb_t is called it indicates that discovery has completed. If more inquiry results were received during session than fits in provided result storage, only ones with highest RSSI will be reported.
- Parameters
param – Discovery parameters.
results – Storage for discovery results.
count – Number of results in storage. Valid range: 1-255.
cb – Callback to notify discovery results.
- Returns
Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error
-
int
bt_br_discovery_stop
(void)¶ 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.
-
int
bt_br_oob_get_local
(struct bt_br_oob *oob)¶ 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
-
int
bt_br_set_discoverable
(bool enable)¶ Enable/disable set controller in discoverable state.
Allows make local controller to listen on INQUIRY SCAN channel and responds to devices making general inquiry. To enable this state it’s mandatory to first be in connectable state.
- Parameters
enable – Value allowing/disallowing controller to become discoverable.
- Returns
Negative if fail set to requested state or requested state has been already set. Zero if done successfully.
-
int
bt_br_set_connectable
(bool enable)¶ 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.
-
int
bt_unpair
(uint8_t id, const bt_addr_le_t *addr)¶ Clear pairing information.
- Parameters
id – Local identity (mostly just BT_ID_DEFAULT).
addr – Remote address, NULL or BT_ADDR_LE_ANY to clear all remote devices.
- Returns
0 on success or negative error value on failure.
-
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.
- Parameters
id – Local identity (mostly just BT_ID_DEFAULT).
func – Function to call for each bond.
user_data – Data to pass to the callback function.
Is this content helpful?