The latest development version of this page may be more current than this released 2.3.0 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 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_DIR_LOW_DUTY(_peer)¶

BT_LE_ADV_NCONN¶

BT_LE_ADV_NCONN_NAME¶

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

    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 :option:`CONFIG_BT_PRIVACY`.

BT_LE_ADV_OPT_ONE_TIME = BIT(1)¶

Advertise one time.

    Don't try to resume connectable advertising after a connection.
    This option is only meaningful when used together with
    BT_LE_ADV_OPT_CONNECTABLE. If set the advertising will be stopped
    when bt_le_adv_stop() is called or when an incoming (slave)
    connection happens. If this option is not set the stack will
    take care of keeping advertising enabled even as connections
    occur.
    If Advertising directed or the advertiser was started with
    @ref bt_le_ext_adv_start then this behavior is the default behavior
    and this flag has no effect.

BT_LE_ADV_OPT_USE_IDENTITY = BIT(2)¶

Advertise using identity address.

    Advertise using the identity address as the advertiser address.
    @warning This will compromise the privacy of the device, so care
             must be taken when using this option.
    @note The address used for advertising will not be the same as
           returned by @ref bt_le_oob_get_local, instead @ref bt_id_get
           should be used to get the LE address.

BT_LE_ADV_OPT_USE_NAME = BIT(3)¶: Advertise using GAP device name

BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY = BIT(4)¶

Low duty cycle directed advertising.

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

BT_LE_ADV_OPT_DIR_ADDR_RPA = BIT(5)¶

Directed advertising to privacy-enabled peer.

    Enable use of Resolvable Private Address (RPA) as the target address
    in directed advertisements when :option:`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.

BT_LE_ADV_OPT_FILTER_SCAN_REQ = BIT(6)¶: Use whitelist to filter devices that can request scan response data.

BT_LE_ADV_OPT_FILTER_CONN = BIT(7)¶: Use whitelist to filter devices that can connect.

BT_LE_ADV_OPT_NOTIFY_SCAN_REQ = BIT(8)¶: Notify the application when a scan response data has been sent to an active scanner.

BT_LE_ADV_OPT_SCANNABLE = BIT(9)¶

Support scan response data.

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

BT_LE_ADV_OPT_EXT_ADV = BIT(10)¶

Advertise with extended advertising.

    This options enables extended advertising in the advertising set.
    In extended advertising the advertising set will send a small header
    packet on the three primary advertising channels. This small header
    points to the advertising data packet that will be sent on one of
    the 37 secondary advertising channels.
    The advertiser will send primary advertising on LE 1M PHY, and
    secondary advertising on LE 2M PHY.
    Connections will be established on LE 2M PHY.

    Without this option the advertiser will send advertising data on the
    three primary advertising channels.

    @note Enabling this option requires extended advertising support in
          the peer devices scanning for advertisement packets.

BT_LE_ADV_OPT_NO_2M = BIT(11)¶

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

Disabling the use of LE 2M PHY could be necessary if scanners don’t support the LE 2M PHY. The advertiser will send primary advertising on LE 1M PHY, and secondary advertising on LE 1M PHY. Connections will be established on LE 1M PHY.

Note: Cannot be set if BT_LE_ADV_OPT_CODED is set.
Note: Requires BT_LE_ADV_OPT_EXT_ADV.

BT_LE_ADV_OPT_CODED = BIT(12)¶

Advertise on the LE Coded PHY (Long Range).

    The advertiser will send both primary and secondary advertising
    on the LE Coded PHY. This gives the advertiser increased range with
    the trade-off of lower data rate and higher power consumption.
    Connections will be established on LE Coded PHY.

    @note Requires @ref BT_LE_ADV_OPT_EXT_ADV

BT_LE_ADV_OPT_ANONYMOUS = BIT(13)¶

Advertise without a device address (identity or RPA).

    @note Requires @ref BT_LE_ADV_OPT_EXT_ADV

BT_LE_ADV_OPT_USE_TX_POWER = BIT(14)¶

Advertise with transmit power.

    @note Requires @ref BT_LE_ADV_OPT_EXT_ADV

enum [anonymous]¶

Values:

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

BT_LE_SCAN_OPT_FILTER_DUPLICATE = BIT(0)¶: Filter duplicates.

BT_LE_SCAN_OPT_FILTER_WHITELIST = BIT(1)¶: Filter using whitelist.

BT_LE_SCAN_OPT_CODED = BIT(2)¶: Enable scan on coded PHY (Long Range).

BT_LE_SCAN_OPT_NO_1M = BIT(3)¶

Disable scan on 1M phy.

    @note Requires @ref BT_LE_SCAN_OPT_CODED.

BT_LE_SCAN_FILTER_DUPLICATE = BT_LE_SCAN_OPT_FILTER_DUPLICATE ¶

BT_LE_SCAN_FILTER_WHITELIST = BT_LE_SCAN_OPT_FILTER_WHITELIST ¶

enum [anonymous]¶

Values:

BT_LE_SCAN_TYPE_PASSIVE = 0x00¶: Scan without requesting additional information from advertisers.

BT_LE_SCAN_TYPE_ACTIVE = 0x01¶: Scan and request additional information from advertisers.

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

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.

Return

Zero on success or (negative) error code otherwise.

Return

-ENOMEM No free connection objects available for connectable advertiser.

Return

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

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

Return

Zero on success or (negative) error code otherwise.

Parameters

[in] param: Advertising parameters.
[in] cb: Callback struct to notify about advertiser activity. Can be NULL. Must point to valid memory during the lifetime of the advertising set.
[out] adv: Valid advertising set object on success.

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.

Return

Zero on success or (negative) error code otherwise.

Parameters

adv: Advertising set object.

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.

If the advertising set has been configured to send advertising data on the primary advertising channels then the maximum data length is BT_GAP_ADV_MAX_ADV_DATA_LEN bytes. If the advertising set has been configured for extended advertising, then the maximum data length is defined by the controller with the maximum possible of BT_GAP_ADV_MAX_EXT_ADV_DATA_LEN bytes.

Note

Not all scanners support extended data length advertising data.

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.

Return

Zero on success or (negative) error code otherwise.

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

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.

Return

Zero on success or (negative) error code otherwise.

Parameters

adv: Advertising set object.
param: Advertising parameters.

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.

Return: Zero on success or (negative) error code otherwise.

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

Return

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

Parameters

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

Return

Zero on success or (negative) error code on failure.

Parameters

adv: Advertising set object
info: Advertising set info object

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.

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.

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. May be NULL if callback registration through bt_le_scan_cb_register is preferred.

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.

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

int bt_le_whitelist_add(const bt_addr_le_t *addr)¶

Add device (LE) to whitelist.

Add peer device LE address to the whitelist.

Note

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

Return

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

Parameters

addr: Bluetooth LE identity address.

int bt_le_whitelist_rem(const bt_addr_le_t *addr)¶

Remove device (LE) from whitelist.

Remove peer device LE address from the whitelist.

Note

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

Return

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

Parameters

addr: Bluetooth LE identity address.

int bt_le_whitelist_clear(void)¶

Clear whitelist.

Clear all devices from the whitelist.

Note: The whitelist cannot be modified when an LE role is using the whitelist, i.e advertiser or scanner using a whitelist or automatic connecting to devices using whitelist.
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 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.

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.

Return

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

Parameters

[in] id: Local identity, in most cases BT_ID_DEFAULT.
[out] oob: LE 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.

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.

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.

Return

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

Parameters

[in] adv: The advertising set object
[out] oob: LE OOB information

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

Start BR/EDR discovery.

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_addr_from_str(const char *str, bt_addr_t *addr)¶

Convert Bluetooth address from string to binary.

Return

Zero on success or (negative) error code otherwise.

Parameters

[in] str: The string representation of a Bluetooth address.
[out] addr: Address of buffer to store the Bluetooth address

int bt_addr_le_from_str(const char *str, const char *type, bt_addr_le_t *addr)¶

Convert LE Bluetooth address from string to binary.

Return

Zero on success or (negative) error code otherwise.

Parameters

[in] str: The string representation of an LE Bluetooth address.
[in] type: The string representation of the LE Bluetooth address type.
[out] addr: Address of buffer to store the LE Bluetooth address

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_le_ext_adv_sent_info¶

#include <bluetooth.h>

Public Members

u8_t num_sent¶: The number of advertising events completed.

struct bt_le_ext_adv_connected_info¶

#include <bluetooth.h>

Public Members

struct bt_conn *conn¶: Connection object of the new connection

struct bt_le_ext_adv_scanned_info¶

#include <bluetooth.h>

Public Members

bt_addr_le_t *addr¶: Active scanner LE address and type

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.

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

u8_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.
Note: It is not possible to have multiple connectable advertising sets advertising simultaneously using different identities.

u8_t sid¶

Advertising Set Identifier, valid range 0x00 - 0x0f.

Note: Requires BT_LE_ADV_OPT_EXT_ADV

u8_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

u32_t options¶: Bit-field of advertising options

u32_t interval_min¶: Minimum Advertising Interval (N * 0.625)

u32_t interval_max¶: Maximum Advertising Interval (N * 0.625)

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.

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.

struct bt_le_ext_adv_start_param¶

#include <bluetooth.h>

Public Members

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

u8_t num_events¶

Number of advertising events.

Application will be notified by the advertiser sent callback. Set to zero for no limit.

struct bt_le_ext_adv_info¶

#include <bluetooth.h>

Advertising set info structure.

Public Members

s8_t tx_power¶: Currently selected Transmit Power (dBM).

struct bt_le_scan_param¶

#include <bluetooth.h>

LE scan parameters

Public Members

u8_t type¶: Scan type (BT_LE_SCAN_TYPE_ACTIVE or BT_LE_SCAN_TYPE_PASSIVE)

u16_t interval¶: Scan interval (N * 0.625 ms)

u16_t window¶: Scan window (N * 0.625 ms)

u16_t timeout¶

Scan timeout (N * 10 ms)

Application will be notified by the scan timeout callback. Set zero to disable timeout.

u16_t interval_coded¶

Scan interval LE Coded PHY (N * 0.625 MS)

Set zero to use same as LE 1M PHY scan interval.

u16_t window_coded¶

Scan window LE Coded PHY (N * 0.625 MS)

Set zero to use same as LE 1M PHY scan window.

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.

u8_t sid¶: Advertising Set Identifier.

s8_t rssi¶: Strength of advertiser signal.

s8_t tx_power¶: Transmit power of the advertiser.

u8_t adv_type¶: Advertising packet type.

u16_t adv_props¶: Advertising packet properties.

u8_t primary_phy¶: Primary advertising channel PHY.

u8_t secondary_phy¶: Secondary advertising channel PHY.

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.

struct bt_le_oob_sc_data¶

#include <bluetooth.h>

LE Secure Connections pairing Out of Band data.

Public Members

u8_t r[16]¶: Random Number.

u8_t c[16]¶: Confirm Value.

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.

struct bt_br_discovery_result¶

#include <bluetooth.h>

BR/EDR discovery result structure.

Public Members

bt_addr_t addr¶: Remote device address

s8_t rssi¶: RSSI from inquiry

u8_t cod[3]¶: Class of Device

u8_t eir[240]¶: Extended Inquiry Response

struct bt_br_discovery_param¶

#include <bluetooth.h>

BR/EDR discovery parameters

Public Members

u8_t length¶: Maximum length of the discovery in units of 1.28 seconds. Valid range is 0x01 - 0x30.

bool limited¶: True if limited discovery procedure is to be used.

struct bt_br_oob¶

#include <bluetooth.h>

Public Members

bt_addr_t addr¶: BR/EDR address.

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.

group bt_addr

Bluetooth device address definitions and utilities.

Defines

BT_ADDR_LE_PUBLIC¶

BT_ADDR_LE_RANDOM¶

BT_ADDR_LE_PUBLIC_ID¶

BT_ADDR_LE_RANDOM_ID¶

BT_ADDR_ANY¶

BT_ADDR_NONE¶

BT_ADDR_LE_ANY¶

BT_ADDR_LE_NONE¶

BT_ADDR_IS_RPA(a)¶

BT_ADDR_IS_NRPA(a)¶

BT_ADDR_IS_STATIC(a)¶

BT_ADDR_SET_RPA(a)¶

BT_ADDR_SET_NRPA(a)¶

BT_ADDR_SET_STATIC(a)¶

Functions

static int bt_addr_cmp(const bt_addr_t *a, const bt_addr_t *b)¶

static int bt_addr_le_cmp(const bt_addr_le_t *a, const bt_addr_le_t *b)¶

static void bt_addr_copy(bt_addr_t *dst, const bt_addr_t *src)¶

static void bt_addr_le_copy(bt_addr_le_t *dst, const bt_addr_le_t *src)¶

int bt_addr_le_create_nrpa(bt_addr_le_t *addr)¶

int bt_addr_le_create_static(bt_addr_le_t *addr)¶

static bool bt_addr_le_is_rpa(const bt_addr_le_t *addr)¶

static bool bt_addr_le_is_identity(const bt_addr_le_t *addr)¶

struct bt_addr_t¶: #include <addr.h>
Bluetooth Device Address

struct bt_addr_le_t¶: #include <addr.h>
Bluetooth LE Device Address

group bt_gap_defines

Bluetooth Generic Access Profile defines and Assigned Numbers.

Defines

BT_COMP_ID_LF¶: Company Identifiers (see Bluetooth Assigned Numbers)

BT_DATA_FLAGS¶: EIR/AD data type definitions

BT_DATA_UUID16_SOME¶

BT_DATA_UUID16_ALL¶

BT_DATA_UUID32_SOME¶

BT_DATA_UUID32_ALL¶

BT_DATA_UUID128_SOME¶

BT_DATA_UUID128_ALL¶

BT_DATA_NAME_SHORTENED¶

BT_DATA_NAME_COMPLETE¶

BT_DATA_TX_POWER¶

BT_DATA_SM_TK_VALUE¶

BT_DATA_SM_OOB_FLAGS¶

BT_DATA_SOLICIT16¶

BT_DATA_SOLICIT128¶

BT_DATA_SVC_DATA16¶

BT_DATA_GAP_APPEARANCE¶

BT_DATA_LE_BT_DEVICE_ADDRESS¶

BT_DATA_LE_ROLE¶

BT_DATA_SOLICIT32¶

BT_DATA_SVC_DATA32¶

BT_DATA_SVC_DATA128¶

BT_DATA_LE_SC_CONFIRM_VALUE¶

BT_DATA_LE_SC_RANDOM_VALUE¶

BT_DATA_URI¶

BT_DATA_MESH_PROV¶

BT_DATA_MESH_MESSAGE¶

BT_DATA_MESH_BEACON¶

BT_DATA_MANUFACTURER_DATA¶

BT_LE_AD_LIMITED¶

BT_LE_AD_GENERAL¶

BT_LE_AD_NO_BREDR¶

BT_GAP_SCAN_FAST_INTERVAL¶

BT_GAP_SCAN_FAST_WINDOW¶

BT_GAP_SCAN_SLOW_INTERVAL_1¶

BT_GAP_SCAN_SLOW_WINDOW_1¶

BT_GAP_SCAN_SLOW_INTERVAL_2¶

BT_GAP_SCAN_SLOW_WINDOW_2¶

BT_GAP_ADV_FAST_INT_MIN_1¶

BT_GAP_ADV_FAST_INT_MAX_1¶

BT_GAP_ADV_FAST_INT_MIN_2¶

BT_GAP_ADV_FAST_INT_MAX_2¶

BT_GAP_ADV_SLOW_INT_MIN¶

BT_GAP_ADV_SLOW_INT_MAX¶

BT_GAP_INIT_CONN_INT_MIN¶

BT_GAP_INIT_CONN_INT_MAX¶

BT_GAP_ADV_MAX_ADV_DATA_LEN¶: Maximum advertising data length.

BT_GAP_ADV_MAX_EXT_ADV_DATA_LEN¶

Maximum extended advertising data length.

Note: The maximum advertising data length that can be sent by an extended advertiser is defined by the controller.

BT_GAP_TX_POWER_INVALID¶

BT_GAP_RSSI_INVALID¶

BT_GAP_SID_INVALID¶

BT_GAP_NO_TIMEOUT¶

BT_GAP_ADV_HIGH_DUTY_CYCLE_MAX_TIMEOUT¶

BT_GAP_DATA_LEN_DEFAULT¶

BT_GAP_DATA_LEN_MAX¶

BT_GAP_DATA_TIME_DEFAULT¶

BT_GAP_DATA_TIME_MAX¶

Enums

enum [anonymous]¶

LE PHY types

Values:

BT_GAP_LE_PHY_1M = BIT(0)¶: LE 1M PHY

BT_GAP_LE_PHY_2M = BIT(1)¶: LE 2M PHY

BT_GAP_LE_PHY_CODED = BIT(2)¶: LE Coded PHY

enum [anonymous]¶

Advertising PDU types

Values:

BT_GAP_ADV_TYPE_ADV_IND = 0x00¶: Scannable and connectable advertising.

BT_GAP_ADV_TYPE_ADV_DIRECT_IND = 0x01¶: Directed connectable advertising.

BT_GAP_ADV_TYPE_ADV_SCAN_IND = 0x02¶: Non-connectable and scannable advertising.

BT_GAP_ADV_TYPE_ADV_NONCONN_IND = 0x03¶: Non-connectable and non-scannable advertising.

BT_GAP_ADV_TYPE_SCAN_RSP = 0x04¶: Additional advertising data requested by an active scanner.

BT_GAP_ADV_TYPE_EXT_ADV = 0x05¶: Extended advertising, see advertising properties.

enum [anonymous]¶

Advertising PDU properties

Values:

BT_GAP_ADV_PROP_CONNECTABLE = BIT(0)¶: Connectable advertising.

BT_GAP_ADV_PROP_SCANNABLE = BIT(1)¶: Scannable advertising.

BT_GAP_ADV_PROP_DIRECTED = BIT(2)¶: Directed advertising.

BT_GAP_ADV_PROP_SCAN_RESPONSE = BIT(3)¶: Additional advertising data requested by an active scanner.

BT_GAP_ADV_PROP_EXT_ADV = BIT(4)¶: Extended advertising.