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(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_PASSKEY_INVALID

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

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 Type

Values:

BT_CONN_TYPE_LE = BIT(0)

LE Connection Type

BT_CONN_TYPE_BR = BIT(1)

BR/EDR Connection Type

BT_CONN_TYPE_SCO = BIT(2)

SCO Connection Type

BT_CONN_TYPE_ALL = BT_CONN_TYPE_LE | BT_CONN_TYPE_BR | BT_CONN_TYPE_SCO

All Connection Type

enum [anonymous]

Connection role (master or slave)

Values:

BT_CONN_ROLE_MASTER
BT_CONN_ROLE_SLAVE
enum bt_security_t

Security level.

Values:

BT_SECURITY_L0

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

BT_SECURITY_L1

Level 1: No encryption and no authentication.

BT_SECURITY_L2

Level 2: Encryption and no authentication (no MITM).

BT_SECURITY_L3

Level 3: Encryption and authentication (MITM).

BT_SECURITY_L4

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

BT_SECURITY_NONE = BT_SECURITY_L0
BT_SECURITY_LOW = BT_SECURITY_L1
BT_SECURITY_MEDIUM = BT_SECURITY_L2
BT_SECURITY_HIGH = BT_SECURITY_L3
BT_SECURITY_FIPS = BT_SECURITY_L4
BT_SECURITY_FORCE_PAIR = BIT(7)

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

enum bt_security_err

Values:

BT_SECURITY_ERR_SUCCESS

Security procedure successful.

BT_SECURITY_ERR_AUTH_FAIL

Authentication failed.

BT_SECURITY_ERR_PIN_OR_KEY_MISSING

PIN or encryption key is missing.

BT_SECURITY_ERR_OOB_NOT_AVAILABLE

OOB data is not available.

BT_SECURITY_ERR_AUTH_REQUIREMENT

The requested security level could not be reached.

BT_SECURITY_ERR_PAIR_NOT_SUPPORTED

Pairing is not supported

BT_SECURITY_ERR_PAIR_NOT_ALLOWED

Pairing is not allowed.

BT_SECURITY_ERR_INVALID_PARAM

Invalid parameters.

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

Return
Connection object or NULL if not found. The caller gets a new reference to the connection object which must be released with bt_conn_unref() once done using the object.
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.

u8_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_le_param_update(struct bt_conn *conn, const struct bt_le_conn_param *param)

Update the connection parameters.

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

struct bt_conn *bt_conn_create_le(const bt_addr_le_t *peer, const struct bt_le_conn_param *param)

Initiate an LE connection to a remote device.

Allows initiate new LE link to remote peer using its address. Returns a new reference that the the caller is responsible for managing.

This uses the General Connection Establishment procedure.

Return
Valid connection object on success or NULL otherwise.
Parameters
  • peer: Remote address.
  • param: Initial connection parameters.

int bt_conn_create_auto_le(const struct bt_le_conn_param *param)

Automatically connect to remote devices in whitelist.

This uses the Auto Connection Establishment procedure.

Return
Zero on success or (negative) error code on failure.
Parameters
  • param: Initial connection parameters.

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

Returns a new reference that the the caller is responsible for managing.

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 device is already paired with sufficiently strong key encryption will be enabled. If link is already encrypted with sufficiently strong key this function does nothing.

If device is not paired pairing will be initiated. If device is paired and keys are too weak but input output capabilities allow for strong enough keys pairing 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.

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 int bt_conn_security(struct bt_conn *conn, bt_security_t sec)
u8_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.

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_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 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 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. Returns a new reference that the the caller is responsible for managing.

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. Returns a new reference that the the caller is responsible for managing.

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_info
#include <conn.h>

LE Connection Info Structure

struct bt_conn_br_info
#include <conn.h>

BR/EDR Connection Info Structure

struct bt_conn_info
#include <conn.h>

Connection Info Structure.

Parameters
  • type: Connection Type
  • role: Connection Role
  • id: Which local identity the connection was created with
  • le: LE Connection specific Info
  • br: BR/EDR Connection specific Info

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.

struct bt_conn_oob_info
#include <conn.h>

Info Structure for OOB pairing

struct bt_conn_auth_cb
#include <conn.h>

Authenticated pairing callback structure

struct bt_br_conn_param
#include <conn.h>

Connection parameters for BR/EDR connections