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 bt_conn_le_tx_power_phy

Values:

enumerator BT_CONN_LE_TX_POWER_PHY_NONE

Convenience macro for when no PHY is set.

enumerator BT_CONN_LE_TX_POWER_PHY_1M

LE 1M PHY

enumerator BT_CONN_LE_TX_POWER_PHY_2M

LE 2M PHY

enumerator BT_CONN_LE_TX_POWER_PHY_CODED_S8

LE Coded PHY using S=8 coding.

enumerator BT_CONN_LE_TX_POWER_PHY_CODED_S2

LE Coded PHY using S=2 coding.

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.

Note

Will return NULL if the reference count is zero.

Return

Connection object with incremented reference count, or NULL if the reference count is zero.

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_get_tx_power_level(struct bt_conn *conn, struct bt_conn_le_tx_power *tx_power_level)

Get connection transmit power level.

Return

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

Return

-ENOBUFS HCI command buffer is not available.

Parameters

  • conn: Connection object.

  • tx_power_level: Transmit power level descriptor.

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.

The disconnect reason for a normal disconnect should be: BT_HCI_ERR_REMOTE_USER_TERM_CONN.

The following disconnect reasons are accepted:

  • BT_HCI_ERR_AUTH_FAIL

  • BT_HCI_ERR_REMOTE_USER_TERM_CONN

  • BT_HCI_ERR_REMOTE_LOW_RESOURCES

  • BT_HCI_ERR_REMOTE_POWER_OFF

  • BT_HCI_ERR_UNSUPP_REMOTE_FEATURE

  • BT_HCI_ERR_PAIRING_NOT_SUPPORTED

  • BT_HCI_ERR_UNACCEPT_CONN_PARAM

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.

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

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

static inline 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

static inline 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_tx_power
#include <conn.h>

LE Transmit Power Level Structure

Public Members

uint8_t phy

Input: 1M, 2M, Coded S2 or Coded S8

int8_t current_level

Output: current transmit power level

int8_t max_level

Output: maximum transmit power level

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:

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