The latest development version of this page may be more current than this released 1.14.0 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¶: 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