Connection Management¶

The Zephyr Bluetooth stack uses an abstraction called bt_conn to represent connections to other devices. The internals of this struct are not exposed to the application, but a limited amount of information (such as the remote address) can be acquired using the bt_conn_get_info() API. Connection objects are reference counted, and the application is expected to use the bt_conn_ref() API whenever storing a connection pointer for a longer period of time, since this ensures that the object remains valid (even if the connection would get disconnected). Similarly the bt_conn_unref() API is to be used when releasing a reference to a connection.

An application may track connections by registering a bt_conn_cb struct using the bt_conn_cb_register() API. This struct lets the application define callbacks for connection & disconnection events, as well as other events related to a connection such as a change in the security level or the connection parameters. When acting as a central the application will also get hold of the connection object through the return value of the bt_conn_create_le() API.

API Reference¶

group bt_conn

Connection management.

Defines

BT_LE_CONN_PARAM_INIT(int_min, int_max, lat, to)¶

Initialize connection parameters.

Parameters

int_min: Minimum Connection Interval (N * 1.25 ms)
int_max: Maximum Connection Interval (N * 1.25 ms)
lat: Connection Latency
to: Supervision Timeout (N * 10 ms)

BT_LE_CONN_PARAM(int_min, int_max, lat, to)¶

Helper to declare connection parameters inline

Parameters

int_min: Minimum Connection Interval (N * 1.25 ms)
int_max: Maximum Connection Interval (N * 1.25 ms)
lat: Connection Latency
to: Supervision Timeout (N * 10 ms)

BT_LE_CONN_PARAM_DEFAULT¶: Default LE connection parameters: Connection Interval: 30-50 ms Latency: 0 Timeout: 4 s

BT_CONN_LE_PHY_PARAM_INIT(_pref_tx_phy, _pref_rx_phy)¶

Initialize PHY parameters

Parameters

_pref_tx_phy: Bitmask of preferred transmit PHYs.
_pref_rx_phy: Bitmask of preferred receive PHYs.

BT_CONN_LE_PHY_PARAM(_pref_tx_phy, _pref_rx_phy)¶

Helper to declare PHY parameters inline

Parameters

_pref_tx_phy: Bitmask of preferred transmit PHYs.
_pref_rx_phy: Bitmask of preferred receive PHYs.

BT_CONN_LE_PHY_PARAM_1M¶: Only LE 1M PHY

BT_CONN_LE_PHY_PARAM_2M¶: Only LE 2M PHY

BT_CONN_LE_PHY_PARAM_CODED¶: Only LE Coded PHY.

BT_CONN_LE_PHY_PARAM_ALL¶: All LE PHYs.

BT_CONN_LE_DATA_LEN_PARAM_INIT(_tx_max_len, _tx_max_time)¶

Initialize transmit data length parameters

Parameters

_tx_max_len: Maximum Link Layer transmission payload size in bytes.
_tx_max_time: Maximum Link Layer transmission payload time in us.

BT_CONN_LE_DATA_LEN_PARAM(_tx_max_len, _tx_max_time)¶

Helper to declare transmit data length parameters inline

Parameters

_tx_max_len: Maximum Link Layer transmission payload size in bytes.
_tx_max_time: Maximum Link Layer transmission payload time in us.

BT_LE_DATA_LEN_PARAM_DEFAULT¶: Default LE data length parameters.

BT_LE_DATA_LEN_PARAM_MAX¶: Maximum LE data length parameters.

BT_CONN_LE_CREATE_PARAM_INIT(_options, _interval, _window)¶

Initialize create connection parameters.

Parameters

_options: Create connection options.
_interval: Create connection scan interval (N * 0.625 ms).
_window: Create connection scan window (N * 0.625 ms).

BT_CONN_LE_CREATE_PARAM(_options, _interval, _window)¶

Helper to declare create connection parameters inline

Parameters

_options: Create connection options.
_interval: Create connection scan interval (N * 0.625 ms).
_window: Create connection scan window (N * 0.625 ms).

BT_CONN_LE_CREATE_CONN¶: Default LE create connection parameters. Scan continuously by setting scan interval equal to scan window.

BT_CONN_LE_CREATE_CONN_AUTO¶: Default LE create connection using whitelist parameters. Scan window: 30 ms. Scan interval: 60 ms.

BT_PASSKEY_INVALID¶: Special passkey value that can be used to disable a previously set fixed passkey.

BT_BR_CONN_PARAM_INIT(role_switch)¶

Initialize BR/EDR connection parameters.

Parameters

role_switch: True if role switch is allowed

BT_BR_CONN_PARAM(role_switch)¶

Helper to declare BR/EDR connection parameters inline

Parameters

role_switch: True if role switch is allowed

BT_BR_CONN_PARAM_DEFAULT¶: Default BR/EDR connection parameters: Role switch allowed

Enums

enum [anonymous]¶

Connection PHY options

Values:

enumerator BT_CONN_LE_PHY_OPT_NONE¶: Convenience value when no options are specified.

enumerator BT_CONN_LE_PHY_OPT_CODED_S2¶: LE Coded using S=2 coding preferred when transmitting.

enumerator BT_CONN_LE_PHY_OPT_CODED_S8¶: LE Coded using S=8 coding preferred when transmitting.

enum [anonymous]¶

Connection Type

Values:

enumerator BT_CONN_TYPE_LE¶: LE Connection Type

enumerator BT_CONN_TYPE_BR¶: BR/EDR Connection Type

enumerator BT_CONN_TYPE_SCO¶: SCO Connection Type

enumerator BT_CONN_TYPE_ISO¶: ISO Connection Type

enumerator BT_CONN_TYPE_ALL¶: All Connection Type

enum [anonymous]¶

Connection role (master or slave)

Values:

enumerator BT_CONN_ROLE_MASTER¶

enumerator BT_CONN_ROLE_SLAVE¶

enum [anonymous]¶

Values:

enumerator BT_CONN_LE_OPT_NONE¶: Convenience value when no options are specified.

enumerator BT_CONN_LE_OPT_CODED¶

Enable LE Coded PHY.

    Enable scanning on the LE Coded PHY.

enumerator BT_CONN_LE_OPT_NO_1M¶

Disable LE 1M PHY.

    Disable scanning on the LE 1M PHY.

    @note Requires @ref BT_CONN_LE_OPT_CODED.

enum bt_security_t¶

Security level.

Values:

enumerator BT_SECURITY_L0¶: Level 0: Only for BR/EDR special cases, like SDP

enumerator BT_SECURITY_L1¶: Level 1: No encryption and no authentication.

enumerator BT_SECURITY_L2¶: Level 2: Encryption and no authentication (no MITM).

enumerator BT_SECURITY_L3¶: Level 3: Encryption and authentication (MITM).

enumerator BT_SECURITY_L4¶: Level 4: Authenticated Secure Connections and 128-bit key.

enumerator BT_SECURITY_NONE¶

enumerator BT_SECURITY_LOW¶

enumerator BT_SECURITY_MEDIUM¶

enumerator BT_SECURITY_HIGH¶

enumerator BT_SECURITY_FIPS¶

enumerator BT_SECURITY_FORCE_PAIR¶: Bit to force new pairing procedure, bit-wise OR with requested security level.

enum bt_security_err¶

Values:

enumerator BT_SECURITY_ERR_SUCCESS¶: Security procedure successful.

enumerator BT_SECURITY_ERR_AUTH_FAIL¶: Authentication failed.

enumerator BT_SECURITY_ERR_PIN_OR_KEY_MISSING¶: PIN or encryption key is missing.

enumerator BT_SECURITY_ERR_OOB_NOT_AVAILABLE¶: OOB data is not available.

enumerator BT_SECURITY_ERR_AUTH_REQUIREMENT¶: The requested security level could not be reached.

enumerator BT_SECURITY_ERR_PAIR_NOT_SUPPORTED¶: Pairing is not supported

enumerator BT_SECURITY_ERR_PAIR_NOT_ALLOWED¶: Pairing is not allowed.

enumerator BT_SECURITY_ERR_INVALID_PARAM¶: Invalid parameters.

enumerator BT_SECURITY_ERR_UNSPECIFIED¶: Pairing failed but the exact reason could not be specified.

Functions

struct bt_conn *bt_conn_ref(struct bt_conn *conn)¶

Increment a connection’s reference count.

Increment the reference count of a connection object.

Return

Connection object with incremented reference count.

Parameters

conn: Connection object.

void bt_conn_unref(struct bt_conn *conn)¶

Decrement a connection’s reference count.

Decrement the reference count of a connection object.

Parameters

conn: Connection object.

void bt_conn_foreach(int type, void (*func)(struct bt_conn *conn, void *data), void *data, )¶

Iterate through all existing connections.

Parameters

type: Connection Type
func: Function to call for each connection.
data: Data to pass to the callback function.

struct bt_conn *bt_conn_lookup_addr_le(uint8_t id, const bt_addr_le_t *peer)¶

Look up an existing connection by address.

Look up an existing connection based on the remote address.

The caller gets a new reference to the connection object which must be released with bt_conn_unref() once done using the object.

Return

Connection object or NULL if not found.

Parameters

id: Local identity (in most cases BT_ID_DEFAULT).
peer: Remote address.

const bt_addr_le_t *bt_conn_get_dst(const struct bt_conn *conn)¶

Get destination (peer) address of a connection.

Return

Destination address.

Parameters

conn: Connection object.

uint8_t bt_conn_index(struct bt_conn *conn)¶

Get array index of a connection.

This function is used to map bt_conn to index of an array of connections. The array has CONFIG_BT_MAX_CONN elements.

Return

Index of the connection object. The range of the returned value is 0..CONFIG_BT_MAX_CONN-1

Parameters

conn: Connection object.

int bt_conn_get_info(const struct bt_conn *conn, struct bt_conn_info *info)¶

Get connection info.

Return

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

Parameters

conn: Connection object.
info: Connection info object.

int bt_conn_get_remote_info(struct bt_conn *conn, struct bt_conn_remote_info *remote_info)¶

Get connection info for the remote device.

Note

In order to retrieve the remote version (version, manufacturer and subversion) CONFIG_BT_REMOTE_VERSION must be enabled

Note

The remote information is exchanged directly after the connection has been established. The application can be notified about when the remote information is available through the remote_info_available callback.

Return

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

Return

-EBUSY The remote information is not yet available.

Parameters

conn: Connection object.
remote_info: Connection remote info object.

int bt_conn_le_param_update(struct bt_conn *conn, const struct bt_le_conn_param *param)¶

Update the connection parameters.

If the local device is in the peripheral role then updating the connection parameters will be delayed. This delay can be configured by through the CONFIG_BT_CONN_PARAM_UPDATE_TIMEOUT option.

Return

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

Parameters

conn: Connection object.
param: Updated connection parameters.

int bt_conn_le_data_len_update(struct bt_conn *conn, const struct bt_conn_le_data_len_param *param)¶

Update the connection transmit data length parameters.

Return

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

Parameters

conn: Connection object.
param: Updated data length parameters.

int bt_conn_le_phy_update(struct bt_conn *conn, const struct bt_conn_le_phy_param *param)¶

Update the connection PHY parameters.

Update the preferred transmit and receive PHYs of the connection. Use BT_GAP_LE_PHY_NONE to indicate no preference.

Return

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

Parameters

conn: Connection object.
param: Updated connection parameters.

int bt_conn_disconnect(struct bt_conn *conn, uint8_t reason)¶

Disconnect from a remote device or cancel pending connection.

Disconnect an active connection with the specified reason code or cancel pending outgoing connection.

Return

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

Parameters

conn: Connection to disconnect.
reason: Reason code for the disconnection.

int bt_conn_le_create(const bt_addr_le_t *peer, const struct bt_conn_le_create_param *create_param, const struct bt_le_conn_param *conn_param, struct bt_conn **conn)¶

Initiate an LE connection to a remote device.

Allows initiate new LE link to remote peer using its address.

The caller gets a new reference to the connection object which must be released with bt_conn_unref() once done using the object.

This uses the General Connection Establishment procedure.

Return

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

Parameters

[in] peer: Remote address.
[in] create_param: Create connection parameters.
[in] conn_param: Initial connection parameters.
[out] conn: Valid connection object on success.

struct bt_conn *bt_conn_create_le(const bt_addr_le_t *peer, const struct bt_le_conn_param *conn_param)¶

int bt_conn_le_create_auto(const struct bt_conn_le_create_param *create_param, const struct bt_le_conn_param *conn_param)¶

Automatically connect to remote devices in whitelist.

This uses the Auto Connection Establishment procedure. The procedure will continue until a single connection is established or the procedure is stopped through bt_conn_create_auto_stop. To establish connections to all devices in the whitelist the procedure should be started again in the connected callback after a new connection has been established.

Return

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

Return

-ENOMEM No free connection object available.

Parameters

create_param: Create connection parameters
conn_param: Initial connection parameters.

int bt_conn_create_auto_le(const struct bt_le_conn_param *conn_param)¶

int bt_conn_create_auto_stop(void)¶

Stop automatic connect creation.

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

int bt_le_set_auto_conn(const bt_addr_le_t *addr, const struct bt_le_conn_param *param)¶

Automatically connect to remote device if it’s in range.

This function enables/disables automatic connection initiation. Every time the device loses the connection with peer, this connection will be re-established if connectable advertisement from peer is received.

Note

Auto connect is disabled during explicit scanning.

Return

Zero on success or error code otherwise.

Parameters

addr: Remote Bluetooth address.
param: If non-NULL, auto connect is enabled with the given parameters. If NULL, auto connect is disabled.

struct bt_conn *bt_conn_create_slave_le(const bt_addr_le_t *peer, const struct bt_le_adv_param *param)¶

Initiate directed advertising to a remote device.

Allows initiating a new LE connection to remote peer with the remote acting in central role and the local device in peripheral role.

The advertising type will either be BT_LE_ADV_DIRECT_IND, or BT_LE_ADV_DIRECT_IND_LOW_DUTY if the BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY option was used as part of the advertising parameters.

In case of high duty cycle this will result in a callback with connected() with a new connection or with an error.

The advertising may be canceled with bt_conn_disconnect().

The caller gets a new reference to the connection object which must be released with bt_conn_unref() once done using the object.

Return

Valid connection object on success or NULL otherwise.

Parameters

peer: Remote address.
param: Directed advertising parameters.

int bt_conn_set_security(struct bt_conn *conn, bt_security_t sec)¶

Set security level for a connection.

This function enable security (encryption) for a connection. If the device has bond information for the peer with sufficiently strong key encryption will be enabled. If the connection is already encrypted with sufficiently strong key this function does nothing.

If the device has no bond information for the peer and is not already paired then the pairing procedure will be initiated. If the device has bond information or is already paired and the keys are too weak then the pairing procedure will be initiated.

This function may return error if required level of security is not possible to achieve due to local or remote device limitation (e.g., input output capabilities), or if the maximum number of paired devices has been reached.

This function may return error if the pairing procedure has already been initiated by the local device or the peer device.

Note

When CONFIG_BT_SMP_SC_ONLY is enabled then the security level will always be level 4.

Note

When CONFIG_BT_SMP_OOB_LEGACY_PAIR_ONLY is enabled then the security level will always be level 3.

Return

0 on success or negative error

Parameters

conn: Connection object.
sec: Requested security level.

bt_security_t bt_conn_get_security(struct bt_conn *conn)¶

Get security level for a connection.

Return: Connection security level

int bt_conn_security(struct bt_conn *conn, bt_security_t sec)¶

uint8_t bt_conn_enc_key_size(struct bt_conn *conn)¶

Get encryption key size.

This function gets encryption key size. If there is no security (encryption) enabled 0 will be returned.

Return

Encryption key size.

Parameters

conn: Existing connection object.

void bt_conn_cb_register(struct bt_conn_cb *cb)¶

Register connection callbacks.

Register callbacks to monitor the state of connections.

Parameters

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

void bt_set_bondable(bool enable)¶

Enable/disable bonding.

Set/clear the Bonding flag in the Authentication Requirements of SMP Pairing Request/Response data. The initial value of this flag depends on BT_BONDABLE Kconfig setting. For the vast majority of applications calling this function shouldn’t be needed.

Parameters

enable: Value allowing/disallowing to be bondable.

void bt_set_oob_data_flag(bool enable)¶

Allow/disallow remote OOB data to be used for pairing.

Set/clear the OOB data flag for SMP Pairing Request/Response data. The initial value of this flag depends on BT_OOB_DATA_PRESENT Kconfig setting.

Parameters

enable: Value allowing/disallowing remote OOB data.

int bt_le_oob_set_legacy_tk(struct bt_conn *conn, const uint8_t *tk)¶

Set OOB Temporary Key to be used for pairing.

This function allows to set OOB data for the LE legacy pairing procedure. The function should only be called in response to the oob_data_request() callback provided that the legacy method is user pairing.

Return

Zero on success or -EINVAL if NULL

Parameters

conn: Connection object
tk: Pointer to 16 byte long TK array

int bt_le_oob_set_sc_data(struct bt_conn *conn, const struct bt_le_oob_sc_data *oobd_local, const struct bt_le_oob_sc_data *oobd_remote)¶

Set OOB data during LE Secure Connections (SC) pairing procedure.

This function allows to set OOB data during the LE SC pairing procedure. The function should only be called in response to the oob_data_request() callback provided that LE SC method is used for pairing.

The user should submit OOB data according to the information received in the callback. This may yield three different configurations: with only local OOB data present, with only remote OOB data present or with both local and remote OOB data present.

Return

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

Parameters

conn: Connection object
oobd_local: Local OOB data or NULL if not present
oobd_remote: Remote OOB data or NULL if not present

int bt_le_oob_get_sc_data(struct bt_conn *conn, const struct bt_le_oob_sc_data **oobd_local, const struct bt_le_oob_sc_data **oobd_remote)¶

Get OOB data used for LE Secure Connections (SC) pairing procedure.

This function allows to get OOB data during the LE SC pairing procedure that were set by the bt_le_oob_set_sc_data() API.

Note

The OOB data will only be available as long as the connection object associated with it is valid.

Return

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

Parameters

conn: Connection object
oobd_local: Local OOB data or NULL if not set
oobd_remote: Remote OOB data or NULL if not set

int bt_passkey_set(unsigned int passkey)¶

Set a fixed passkey to be used for pairing.

This API is only available when the CONFIG_BT_FIXED_PASSKEY configuration option has been enabled.

Sets a fixed passkey to be used for pairing. If set, the pairing_confim() callback will be called for all incoming pairings.

Return

0 on success or a negative error code on failure.

Parameters

passkey: A valid passkey (0 - 999999) or BT_PASSKEY_INVALID to disable a previously set fixed passkey.

int bt_conn_auth_cb_register(const struct bt_conn_auth_cb *cb)¶

Register authentication callbacks.

Register callbacks to handle authenticated pairing. Passing NULL unregisters a previous callbacks structure.

Return

Zero on success or negative error code otherwise

Parameters

cb: Callback struct.

int bt_conn_auth_passkey_entry(struct bt_conn *conn, unsigned int passkey)¶

Reply with entered passkey.

This function should be called only after passkey_entry callback from bt_conn_auth_cb structure was called.

Return

Zero on success or negative error code otherwise

Parameters

conn: Connection object.
passkey: Entered passkey.

int bt_conn_auth_cancel(struct bt_conn *conn)¶

Cancel ongoing authenticated pairing.

This function allows to cancel ongoing authenticated pairing.

Return

Zero on success or negative error code otherwise

Parameters

conn: Connection object.

int bt_conn_auth_passkey_confirm(struct bt_conn *conn)¶

Reply if passkey was confirmed to match by user.

This function should be called only after passkey_confirm callback from bt_conn_auth_cb structure was called.

Return

Zero on success or negative error code otherwise

Parameters

conn: Connection object.

int bt_conn_auth_pairing_confirm(struct bt_conn *conn)¶

Reply if incoming pairing was confirmed by user.

This function should be called only after pairing_confirm callback from bt_conn_auth_cb structure was called if user confirmed incoming pairing.

Return

Zero on success or negative error code otherwise

Parameters

conn: Connection object.

int bt_conn_auth_pincode_entry(struct bt_conn *conn, const char *pin)¶

Reply with entered PIN code.

This function should be called only after PIN code callback from bt_conn_auth_cb structure was called. It’s for legacy 2.0 devices.

Return

Zero on success or negative error code otherwise

Parameters

conn: Connection object.
pin: Entered PIN code.

struct bt_conn *bt_conn_create_br(const bt_addr_t *peer, const struct bt_br_conn_param *param)¶

Initiate an BR/EDR connection to a remote device.

Allows initiate new BR/EDR link to remote peer using its address.

The caller gets a new reference to the connection object which must be released with bt_conn_unref() once done using the object.

Return

Valid connection object on success or NULL otherwise.

Parameters

peer: Remote address.
param: Initial connection parameters.

struct bt_conn *bt_conn_create_sco(const bt_addr_t *peer)¶

Initiate an SCO connection to a remote device.

Allows initiate new SCO link to remote peer using its address.

The caller gets a new reference to the connection object which must be released with bt_conn_unref() once done using the object.

Return

Valid connection object on success or NULL otherwise.

Parameters

peer: Remote address.

struct bt_le_conn_param¶: #include <conn.h>
Connection parameters for LE connections

struct bt_conn_le_phy_info¶

#include <conn.h>

Connection PHY information for LE connections

Public Members

uint8_t rx_phy¶: Connection transmit PHY

struct bt_conn_le_phy_param¶

#include <conn.h>

Preferred PHY parameters for LE connections

Public Members

uint8_t pref_tx_phy¶: Connection PHY options.

uint8_t pref_rx_phy¶: Bitmask of preferred transmit PHYs

struct bt_conn_le_data_len_info¶

#include <conn.h>

Connection data length information for LE connections

Public Members

uint16_t tx_max_len¶: Maximum Link Layer transmission payload size in bytes.

uint16_t tx_max_time¶: Maximum Link Layer transmission payload time in us.

uint16_t rx_max_len¶: Maximum Link Layer reception payload size in bytes.

uint16_t rx_max_time¶: Maximum Link Layer reception payload time in us.

struct bt_conn_le_data_len_param¶

#include <conn.h>

Connection data length parameters for LE connections

Public Members

uint16_t tx_max_len¶: Maximum Link Layer transmission payload size in bytes.

uint16_t tx_max_time¶: Maximum Link Layer transmission payload time in us.

struct bt_conn_le_info¶

#include <conn.h>

LE Connection Info Structure

Public Members

const bt_addr_le_t *src¶: Source (Local) Identity Address

const bt_addr_le_t *dst¶: Destination (Remote) Identity Address or remote Resolvable Private Address (RPA) before identity has been resolved.

const bt_addr_le_t *local¶: Local device address used during connection setup.

const bt_addr_le_t *remote¶: Remote device address used during connection setup.

uint16_t latency¶: Connection interval

uint16_t timeout¶: Connection slave latency

const struct bt_conn_le_phy_info *phy¶: Connection supervision timeout

struct bt_conn_br_info¶: #include <conn.h>
BR/EDR Connection Info Structure

struct bt_conn_info¶

#include <conn.h>

Connection Info Structure

Public Members

uint8_t type¶: Connection Type.

uint8_t role¶: Connection Role.

uint8_t id¶: Which local identity the connection was created with

union bt_conn_info.[anonymous] [anonymous]¶: Connection Type specific Info.

struct bt_conn_le_remote_info¶

#include <conn.h>

LE Connection Remote Info Structure

Public Members

const uint8_t *features¶: Remote LE feature set (bitmask).

struct bt_conn_br_remote_info¶

#include <conn.h>

BR/EDR Connection Remote Info structure

Public Members

const uint8_t *features¶: Remote feature set (pages of bitmasks).

uint8_t num_pages¶: Number of pages in the remote feature set.

struct bt_conn_remote_info¶

#include <conn.h>

Connection Remote Info Structure.

Note: The version, manufacturer and subversion fields will only contain valid data if CONFIG_BT_REMOTE_VERSION is enabled.

Public Members

uint8_t type¶: Connection Type

uint8_t version¶: Remote Link Layer version

uint16_t manufacturer¶: Remote manufacturer identifier

uint16_t subversion¶: Per-manufacturer unique revision

struct bt_conn_le_create_param¶

#include <conn.h>

Public Members

uint32_t options¶: Bit-field of create connection options.

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

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

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.

uint16_t timeout¶

Connection initiation timeout (N * 10 MS)

Set zero to use the default CONFIG_BT_CREATE_CONN_TIMEOUT timeout.

Note: Unused in bt_conn_create_auto_le

struct bt_conn_cb¶

#include <conn.h>

Connection callback structure.

This structure is used for tracking the state of a connection. It is registered with the help of the bt_conn_cb_register() API. It’s permissible to register multiple instances of this bt_conn_cb type, in case different modules of an application are interested in tracking the connection state. If a callback is not of interest for an instance, it may be set to NULL and will as a consequence not be used for that instance.

Public Members

void (*connected)(struct bt_conn *conn, uint8_t err)¶

A new connection has been established.

This callback notifies the application of a new connection. In case the err parameter is non-zero it means that the connection establishment failed.

err can mean either of the following:

BT_HCI_ERR_UNKNOWN_CONN_ID Creating the connection started by bt_conn_create_le was canceled either by the user through bt_conn_disconnect or by the timeout in the host through bt_conn_le_create_param timeout parameter, which defaults to CONFIG_BT_CREATE_CONN_TIMEOUT seconds.
BT_HCI_ERR_ADV_TIMEOUT High duty cycle directed connectable advertiser started by bt_le_adv_start failed to be connected within the timeout.

Parameters

conn: New connection object.
err: HCI error. Zero for success, non-zero otherwise.

void (*disconnected)(struct bt_conn *conn, uint8_t reason)¶

A connection has been disconnected.

This callback notifies the application that a connection has been disconnected.

When this callback is called the stack still has one reference to the connection object. If the application in this callback tries to start either a connectable advertiser or create a new connection this might fail because there are no free connection objects available. To avoid this issue it is recommended to either start connectable advertise or create a new connection using k_work_submit or increase CONFIG_BT_MAX_CONN .

Parameters

conn: Connection object.
reason: HCI reason for the disconnection.

bool (*le_param_req)(struct bt_conn *conn, struct bt_le_conn_param *param)¶

LE connection parameter update request.

This callback notifies the application that a remote device is requesting to update the connection parameters. The application accepts the parameters by returning true, or rejects them by returning false. Before accepting, the application may also adjust the parameters to better suit its needs.

It is recommended for an application to have just one of these callbacks for simplicity. However, if an application registers multiple it needs to manage the potentially different requirements for each callback. Each callback gets the parameters as returned by previous callbacks, i.e. they are not necessarily the same ones as the remote originally sent.

Return

true to accept the parameters, or false to reject them.

Parameters

conn: Connection object.
param: Proposed connection parameters.

void (*le_param_updated)(struct bt_conn *conn, uint16_t interval, uint16_t latency, uint16_t timeout)¶

The parameters for an LE connection have been updated.

This callback notifies the application that the connection parameters for an LE connection have been updated.

Parameters

conn: Connection object.
interval: Connection interval.
latency: Connection latency.
timeout: Connection supervision timeout.

void (*identity_resolved)(struct bt_conn *conn, const bt_addr_le_t *rpa, const bt_addr_le_t *identity)¶

Remote Identity Address has been resolved.

This callback notifies the application that a remote Identity Address has been resolved

Parameters

conn: Connection object.
rpa: Resolvable Private Address.
identity: Identity Address.

void (*security_changed)(struct bt_conn *conn, bt_security_t level, enum bt_security_err err)¶

The security level of a connection has changed.

This callback notifies the application that the security of a connection has changed.

The security level of the connection can either have been increased or remain unchanged. An increased security level means that the pairing procedure has been performed or the bond information from a previous connection has been applied. If the security level remains unchanged this means that the encryption key has been refreshed for the connection.

Parameters

conn: Connection object.
level: New security level of the connection.
err: Security error. Zero for success, non-zero otherwise.

void (*remote_info_available)(struct bt_conn *conn, struct bt_conn_remote_info *remote_info)¶

Remote information procedures has completed.

This callback notifies the application that the remote information has been retrieved from the remote peer.

Parameters

conn: Connection object.
remote_info: Connection information of remote device.

void (*le_phy_updated)(struct bt_conn *conn, struct bt_conn_le_phy_info *param)¶

The PHY of the connection has changed.

This callback notifies the application that the PHY of the connection has changed.

Parameters

conn: Connection object.
info: Connection LE PHY information.

void (*le_data_len_updated)(struct bt_conn *conn, struct bt_conn_le_data_len_info *info)¶

The data length parameters of the connection has changed.

This callback notifies the application that the maximum Link Layer payload length or transmission time has changed.

Parameters

conn: Connection object.
info: Connection data length information.

struct bt_conn_oob_info¶

#include <conn.h>

Info Structure for OOB pairing

Public Types

enum [anonymous]¶

Type of OOB pairing method

Values:

enumerator BT_CONN_OOB_LE_LEGACY¶: LE legacy pairing

enumerator BT_CONN_OOB_LE_SC¶: LE SC pairing

Public Members

enum bt_conn_oob_info.[anonymous] type¶: Type of OOB pairing method

struct bt_conn_pairing_feat¶

#include <conn.h>

Pairing request and pairing response info structure.

This structure is the same for both smp_pairing_req and smp_pairing_rsp and a subset of the packet data, except for the initial Code octet. It is documented in Core Spec. Vol. 3, Part H, 3.5.1 and 3.5.2.

Public Members

uint8_t io_capability¶: IO Capability, Core Spec. Vol 3, Part H, 3.5.1, Table 3.4

uint8_t oob_data_flag¶: OOB data flag, Core Spec. Vol 3, Part H, 3.5.1, Table 3.5

uint8_t auth_req¶: AuthReq, Core Spec. Vol 3, Part H, 3.5.1, Fig. 3.3

uint8_t max_enc_key_size¶: Maximum Encryption Key Size, Core Spec. Vol 3, Part H, 3.5.1

uint8_t init_key_dist¶: Initiator Key Distribution/Generation, Core Spec. Vol 3, Part H, 3.6.1, Fig. 3.11

uint8_t resp_key_dist¶: Responder Key Distribution/Generation, Core Spec. Vol 3, Part H 3.6.1, Fig. 3.11

struct bt_conn_auth_cb¶

#include <conn.h>

Authenticated pairing callback structure

Public Members

enum bt_security_err (*pairing_accept)(struct bt_conn *conn, const struct bt_conn_pairing_feat *const feat)¶

Query to proceed incoming pairing or not.

On any incoming pairing req/rsp this callback will be called for the application to decide whether to allow for the pairing to continue.

The pairing info received from the peer is passed to assist making the decision.

As this callback is synchronous the application should return a response value immediately. Otherwise it may affect the timing during pairing. Hence, this information should not be conveyed to the user to take action.

The remaining callbacks are not affected by this, but do notice that other callbacks can be called during the pairing. Eg. if pairing_confirm is registered both will be called for Just-Works pairings.

This callback may be unregistered in which case pairing continues as if the Kconfig flag was not set.

This callback is not called for BR/EDR Secure Simple Pairing (SSP).

Parameters

conn: Connection where pairing is initiated.
feat: Pairing req/resp info.

void (*passkey_display)(struct bt_conn *conn, unsigned int passkey)¶

Display a passkey to the user.

When called the application is expected to display the given passkey to the user, with the expectation that the passkey will then be entered on the peer device. The passkey will be in the range of 0 - 999999, and is expected to be padded with zeroes so that six digits are always shown. E.g. the value 37 should be shown as 000037.

This callback may be set to NULL, which means that the local device lacks the ability do display a passkey. If set to non-NULL the cancel callback must also be provided, since this is the only way the application can find out that it should stop displaying the passkey.

Parameters

conn: Connection where pairing is currently active.
passkey: Passkey to show to the user.

void (*passkey_entry)(struct bt_conn *conn)¶

Request the user to enter a passkey.

When called the user is expected to enter a passkey. The passkey must be in the range of 0 - 999999, and should be expected to be zero-padded, as that’s how the peer device will typically be showing it (e.g. 37 would be shown as 000037).

Once the user has entered the passkey its value should be given to the stack using the bt_conn_auth_passkey_entry() API.

This callback may be set to NULL, which means that the local device lacks the ability to enter a passkey. If set to non-NULL the cancel callback must also be provided, since this is the only way the application can find out that it should stop requesting the user to enter a passkey.

Parameters

conn: Connection where pairing is currently active.

void (*passkey_confirm)(struct bt_conn *conn, unsigned int passkey)¶

Request the user to confirm a passkey.

When called the user is expected to confirm that the given passkey is also shown on the peer device.. The passkey will be in the range of 0 - 999999, and should be zero-padded to always be six digits (e.g. 37 would be shown as 000037).

Once the user has confirmed the passkey to match, the bt_conn_auth_passkey_confirm() API should be called. If the user concluded that the passkey doesn’t match the bt_conn_auth_cancel() API should be called.

This callback may be set to NULL, which means that the local device lacks the ability to confirm a passkey. If set to non-NULL the cancel callback must also be provided, since this is the only way the application can find out that it should stop requesting the user to confirm a passkey.

Parameters

conn: Connection where pairing is currently active.
passkey: Passkey to be confirmed.

void (*oob_data_request)(struct bt_conn *conn, struct bt_conn_oob_info *info)¶

Request the user to provide Out of Band (OOB) data.

When called the user is expected to provide OOB data. The required data are indicated by the information structure.

For LE Secure Connections OOB pairing, the user should provide local OOB data, remote OOB data or both depending on their availability. Their value should be given to the stack using the bt_le_oob_set_sc_data() API.

This callback must be set to non-NULL in order to support OOB pairing.

Parameters

conn: Connection where pairing is currently active.
info: OOB pairing information.

void (*cancel)(struct bt_conn *conn)¶

Cancel the ongoing user request.

This callback will be called to notify the application that it should cancel any previous user request (passkey display, entry or confirmation).

This may be set to NULL, but must always be provided whenever the passkey_display, passkey_entry passkey_confirm or pairing_confirm callback has been provided.

Parameters

conn: Connection where pairing is currently active.

void (*pairing_confirm)(struct bt_conn *conn)¶

Request confirmation for an incoming pairing.

This callback will be called to confirm an incoming pairing request where none of the other user callbacks is applicable.

If the user decides to accept the pairing the bt_conn_auth_pairing_confirm() API should be called. If the user decides to reject the pairing the bt_conn_auth_cancel() API should be called.

This callback may be set to NULL, which means that the local device lacks the ability to confirm a pairing request. If set to non-NULL the cancel callback must also be provided, since this is the only way the application can find out that it should stop requesting the user to confirm a pairing request.

Parameters

conn: Connection where pairing is currently active.

void (*pincode_entry)(struct bt_conn *conn, bool highsec)¶

Request the user to enter a passkey.

This callback will be called for a BR/EDR (Bluetooth Classic) connection where pairing is being performed. Once called the user is expected to enter a PIN code with a length between 1 and 16 digits. If the highsec parameter is set to true the PIN code must be 16 digits long.

Once entered, the PIN code should be given to the stack using the bt_conn_auth_pincode_entry() API.

This callback may be set to NULL, however in that case pairing over BR/EDR will not be possible. If provided, the cancel callback must be provided as well.

Parameters

conn: Connection where pairing is currently active.
highsec: true if 16 digit PIN is required.

void (*pairing_complete)(struct bt_conn *conn, bool bonded)¶

notify that pairing procedure was complete.

This callback notifies the application that the pairing procedure has been completed.

Parameters

conn: Connection object.
bonded: Bond information has been distributed during the pairing procedure.

void (*pairing_failed)(struct bt_conn *conn, enum bt_security_err reason)¶

notify that pairing process has failed.

Parameters

conn: Connection object.
reason: Pairing failed reason

void (*bond_deleted)(uint8_t id, const bt_addr_le_t *peer)¶

Notify that bond has been deleted.

This callback notifies the application that the bond information for the remote peer has been deleted

Parameters

id: Which local identity had the bond.
peer: Remote address.

struct bt_br_conn_param¶: #include <conn.h>
Connection parameters for BR/EDR connections