The latest development version of this page may be more current than this released 1.14.1 version.

Generic Access Profile (GAP)¶

API Reference¶

group bt_gap

Generic Access Profile.

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

Parameters

_type: Type of advertising data field
_bytes: Variable number of single-byte parameters

BT_LE_ADV_PARAM(_options, _int_min, _int_max)¶

Helper to declare advertising parameters inline

Parameters

_options: Advertising Options
_int_min: Minimum advertising interval
_int_max: Maximum advertising interval

BT_LE_ADV_CONN¶

BT_LE_ADV_CONN_NAME¶

BT_LE_ADV_CONN_DIR_LOW_DUTY¶

BT_LE_ADV_CONN_DIR¶

BT_LE_ADV_NCONN¶

BT_LE_ADV_NCONN_NAME¶

BT_LE_SCAN_PARAM(_type, _filter, _interval, _window)¶

Helper to declare scan parameters inline

Parameters

_type: Scan Type (BT_HCI_LE_SCAN_ACTIVE/BT_HCI_LE_SCAN_PASSIVE)
_filter: Filter Duplicates
_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_ADDR_STR_LEN¶

Recommended length of user string buffer for Bluetooth address.

The recommended length guarantee the output of address conversion will not lose valuable information about address being processed.

BT_ADDR_LE_STR_LEN¶

Recommended length of user string buffer for Bluetooth LE address.

The recommended length guarantee the output of address conversion will not lose valuable information about address being processed.

Typedefs

typedef bt_ready_cb_t¶

Callback for notifying that Bluetooth has been enabled.

Parameters

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

typedef bt_le_scan_cb_t¶

Callback type for reporting LE scan results.

A function of this type is given to the bt_le_scan_start() function and will be called for any discovered LE device.

Parameters

addr: Advertiser LE address and type.
rssi: Strength of advertiser signal.
adv_type: Type of advertising response from advertiser.
buf: Buffer containing advertiser data.

typedef bt_br_discovery_cb_t¶

Callback type for reporting BR/EDR discovery (inquiry) results.

A callback of this type is given to the bt_br_discovery_start() function and will be called at the end of the discovery with information about found devices populated in the results array.

Parameters

results: Storage used for discovery results
count: Number of valid discovery results.

Enums

enum [anonymous]¶

Advertising options

Values:

BT_LE_ADV_OPT_NONE = 0¶: Convenience value when no options are specified.

BT_LE_ADV_OPT_CONNECTABLE = BIT(0)¶: Advertise as connectable. Type of advertising is determined by providing SCAN_RSP data and/or enabling local privacy support.

BT_LE_ADV_OPT_ONE_TIME = BIT(1)¶: Don’t try to resume connectable advertising after a connection. This option is only meaningful when used together with BT_LE_ADV_OPT_CONNECTABLE. If set the advertising will be stopped when bt_le_adv_stop() is called or when an incoming (slave) connection happens. If this option is not set the stack will take care of keeping advertising enabled even as connections occur.

BT_LE_ADV_OPT_USE_IDENTITY = BIT(2)¶

Advertise using the identity address as the own address.

Warning: This will compromise the privacy of the device, so care must be taken when using this option.

BT_LE_ADV_OPT_USE_NAME = BIT(3)¶

BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY = BIT(4)¶: Use low duty directed advertising mode, otherwise high duty mode will be used. This option is only effective when used with bt_conn_create_slave_le().

BT_LE_ADV_OPT_DIR_ADDR_RPA = BIT(5)¶: Enable use of Resolvable Private Address (RPA) as the target address in directed advertisements when CONFIG_BT_PRIVACY is not enabled. This is required if the remote device is privacy-enabled and supports address resolution of the target address in directed advertisement. It is the responsibility of the application to check that the remote device supports address resolution of directed advertisements by reading its Central Address Resolution characteristic.

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.

Return

Zero on success or (negative) error code otherwise.

Parameters

cb: Callback to notify completion or NULL to perform the enabling synchronously.

int bt_set_name(const char *name)¶

Set Bluetooth Device Name.

Set Bluetooth GAP Device Name.

Return

Zero on success or (negative) error code otherwise.

Parameters

name: New name

const char *bt_get_name(void)¶

Get Bluetooth Device Name.

Get Bluetooth GAP Device Name.

Return: Bluetooth Device Name

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.

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

Note: Deleted identities may show up as BT_LE_ADDR_ANY in the returned array.

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.

int bt_id_create(bt_addr_le_t *addr, u8_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.

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.

Return

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

Parameters

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 support (CONFIG_BT_PRIVACY) is not enabled this parameter must be NULL.

int bt_id_reset(u8_t id, bt_addr_le_t *addr, u8_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.

Note: the default identity (BT_ID_DEFAULT) cannot be reset, i.e. this API will return an error if asked to do that.

Return

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

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 support (CONFIG_BT_PRIVACY) is not enabled this parameter must be NULL.

int bt_id_delete(u8_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.

Note: the default identity (BT_ID_DEFAULT) cannot be deleted, i.e. this API will return an error if asked to do that.

Return

0 in case of success, or a negative error code on failure.

Parameters

id: Existing identity identifier.

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.

Return

Zero on success or (negative) error code otherwise.

Return

-ECONNREFUSED When connectable advertising is requested and there is already maximum number of connections established. This error code is only guaranteed when using Zephyr controller, for other controllers code returned in this case may be -EIO.

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

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.

Return

Zero on success or (negative) error code otherwise.

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

int bt_le_adv_stop(void)¶

Stop advertising.

Stops ongoing advertising.

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

Return

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

Parameters

param: Scan parameters.
cb: Callback to notify scan results.

int bt_le_scan_stop(void)¶

Stop (LE) scanning.

Stops ongoing LE scanning.

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

int bt_le_set_chan_map(u8_t chan_map[5])¶

Set (LE) channel map.

Return

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

Parameters

chan_map: Channel map.

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(u8_t id, struct bt_le_oob *oob)¶

Get LE local Out Of Band information.

This function allows to get local information that are useful for Out Of Band pairing or connection creation process.

If privacy is enabled this will result in generating new Resolvable Private Address that is valid for CONFIG_BT_RPA_TIMEOUT seconds. This address will be used for advertising, active scanning and connection creation.

Parameters

id: Local identity, in most cases BT_ID_DEFAULT.
oob: LE related information

int bt_br_discovery_start(const struct bt_br_discovery_param *param, struct bt_br_discovery_result *results, size_t count, bt_br_discovery_cb_t cb)¶

Start BR/EDR discovery.

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.

Return

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

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.

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

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

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

static int bt_addr_to_str(const bt_addr_t *addr, char *str, size_t len)¶

Converts binary Bluetooth address to string.

Return

Number of successfully formatted bytes from binary address.

Parameters

addr: Address of buffer containing binary Bluetooth address.
str: Address of user buffer with enough room to store formatted string containing binary address.
len: Length of data to be copied to user string buffer. Refer to BT_ADDR_STR_LEN about recommended value.

static int bt_addr_le_to_str(const bt_addr_le_t *addr, char *str, size_t len)¶

Converts binary LE Bluetooth address to string.

Return

Number of successfully formatted bytes from binary address.

Parameters

addr: Address of buffer containing binary LE Bluetooth address.
str: Address of user buffer with enough room to store formatted string containing binary LE address.
len: Length of data to be copied to user string buffer. Refer to BT_ADDR_LE_STR_LEN about recommended value.

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.

Return

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

Parameters

enable: Value allowing/disallowing controller to become discoverable.

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.

Return

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

Parameters

enable: Value allowing/disallowing controller to be connectable.

int bt_unpair(u8_t id, const bt_addr_le_t *addr)¶

Clear pairing information.

Return

0 on success or negative error value on failure.

Parameters

id: Local identity (mostly just BT_ID_DEFAULT).
addr: Remote address, NULL or BT_ADDR_LE_ANY to clear all remote devices.

void bt_foreach_bond(u8_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.

struct bt_data¶: #include <bluetooth.h>
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.

struct bt_le_scan_param¶: #include <bluetooth.h>
LE scan parameters

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.