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

LE Connection Type

BT_CONN_TYPE_BR

BR/EDR Connection Type

BT_CONN_TYPE_SCO

SCO 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_NONE

Only for BR/EDR special cases, like SDP

BT_SECURITY_LOW

No encryption and no authentication.

BT_SECURITY_MEDIUM

Encryption and no authentication (no MITM).

BT_SECURITY_HIGH

Encryption and authentication (MITM).

BT_SECURITY_FIPS

Authenticated Secure Connections

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.

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.

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

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

Return
0 on success or negative error
Parameters
  • conn: Connection object.
  • sec: Requested security level.

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.

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

Authenticated pairing callback structure

struct bt_br_conn_param
#include <conn.h>

Connection parameters for BR/EDR connections