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

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.

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.

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

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.

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

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

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

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

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_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_le_remote_info¶: #include <conn.h>
LE Connection Remote Info Structure

struct bt_conn_br_remote_info¶: #include <conn.h>
BR/EDR Connection Remote Info structure

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 :option:CONFIG_BT_REMOTE_VERSION is enabled.

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

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