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() or BT_CONN_CB_DEFINE APIs. 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_le_create() 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_INTERVAL_TO_MS(interval)

Convert connection interval to milliseconds.

Multiply by 1.25 to get milliseconds.

Note that this may be inaccurate, as something like 7.5 ms cannot be accurately presented with integers.

BT_CONN_INTERVAL_TO_US(interval)

Convert connection interval to microseconds.

Multiply by 1250 to get microseconds.

BT_CONN_ROLE_MASTER

Connection role (central or peripheral)

BT_CONN_ROLE_SLAVE
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 filter accept list parameters.

Scan window: 30 ms. Scan interval: 60 ms.

BT_CONN_CB_DEFINE(_name)

Register a callback structure for connection events.

Parameters:
  • _name – Name of callback structure.

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 = 0

Convenience value when no options are specified.

enumerator BT_CONN_LE_PHY_OPT_CODED_S2 = BIT(0)

LE Coded using S=2 coding preferred when transmitting.

enumerator BT_CONN_LE_PHY_OPT_CODED_S8 = BIT(1)

LE Coded using S=8 coding preferred when transmitting.

enum bt_conn_type

Connection Type.

Values:

enumerator BT_CONN_TYPE_LE = BIT(0)

LE Connection Type.

enumerator BT_CONN_TYPE_BR = BIT(1)

BR/EDR Connection Type.

enumerator BT_CONN_TYPE_SCO = BIT(2)

SCO Connection Type.

enumerator BT_CONN_TYPE_ISO = BIT(3)

ISO Connection Type.

enumerator BT_CONN_TYPE_ALL = BT_CONN_TYPE_LE | BT_CONN_TYPE_BR | BT_CONN_TYPE_SCO | BT_CONN_TYPE_ISO

All Connection Type.

enum [anonymous]

Values:

enumerator BT_CONN_ROLE_CENTRAL = 0
enumerator BT_CONN_ROLE_PERIPHERAL = 1
enum bt_conn_state

Values:

enumerator BT_CONN_STATE_DISCONNECTED

Channel disconnected.

enumerator BT_CONN_STATE_CONNECTING

Channel in connecting state.

enumerator BT_CONN_STATE_CONNECTED

Channel connected and ready for upper layer traffic on it.

enumerator BT_CONN_STATE_DISCONNECTING

Channel in disconnecting state.

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_FORCE_PAIR = BIT(7)

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

enum bt_security_flag

Security Info Flags.

Values:

enumerator BT_SECURITY_FLAG_SC = BIT(0)

Paired with Secure Connections.

enumerator BT_SECURITY_FLAG_OOB = BIT(1)

Paired with Out of Band method.

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 bt_conn_auth_keypress

Passkey Keypress Notification type.

The numeric values are the same as in the Core specification for Pairing Keypress Notification PDU.

Values:

enumerator BT_CONN_AUTH_KEYPRESS_ENTRY_STARTED = 0x00
enumerator BT_CONN_AUTH_KEYPRESS_DIGIT_ENTERED = 0x01
enumerator BT_CONN_AUTH_KEYPRESS_DIGIT_ERASED = 0x02
enumerator BT_CONN_AUTH_KEYPRESS_CLEARED = 0x03
enumerator BT_CONN_AUTH_KEYPRESS_ENTRY_COMPLETED = 0x04
enum [anonymous]

Values:

enumerator BT_CONN_LE_OPT_NONE = 0

Convenience value when no options are specified.

enumerator BT_CONN_LE_OPT_CODED = BIT(0)

Enable LE Coded PHY.

    Enable scanning on the LE Coded PHY.
enumerator BT_CONN_LE_OPT_NO_1M = BIT(1)

Disable LE 1M PHY.

    Disable scanning on the LE 1M PHY.

    @note Requires @ref BT_CONN_LE_OPT_CODED.
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_KEY_REJECTED

Distributed Key Rejected.

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.

Parameters:
  • conn – Connection object.

Returns:

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

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(enum bt_conn_type type, void (*func)(struct bt_conn *conn, void *data), void *data)

Iterate through all bt_conn objects.

Iterates trough all bt_conn objects that are alive in the Host allocator.

To find established connections, combine this with bt_conn_get_info. Check that bt_conn_info::state is BT_CONN_STATE_CONNECTED.

Thread safety: This API is thread safe, but it does not guarantee a sequentially-consistent view for objects allocated during the current invocation of this API. E.g. If preempted while allocations A then B then C happen then results may include A and C but miss B.

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.

Parameters:
  • id – Local identity (in most cases BT_ID_DEFAULT).

  • peer – Remote address.

Returns:

Connection object or NULL if not found.

const bt_addr_le_t *bt_conn_get_dst(const struct bt_conn *conn)

Get destination (peer) address of a connection.

Parameters:
  • conn – Connection object.

Returns:

Destination address.

uint8_t bt_conn_index(const 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.

Parameters:
  • conn – Connection object.

Returns:

Index of the connection object. The range of the returned value is 0..CONFIG_BT_MAX_CONN-1

int bt_conn_get_info(const struct bt_conn *conn, struct bt_conn_info *info)

Get connection info.

Parameters:
  • conn – Connection object.

  • info – Connection info object.

Returns:

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

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.

Parameters:
  • conn – Connection object.

  • remote_info – Connection remote info object.

Returns:

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

Returns:

-EBUSY The remote information is not yet available.

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.

Parameters:
  • conn – Connection object.

  • tx_power_level – Transmit power level descriptor.

Returns:

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

Returns:

-ENOBUFS HCI command buffer is not available.

int bt_conn_le_enhanced_get_tx_power_level(struct bt_conn *conn, struct bt_conn_le_tx_power *tx_power)

Get local enhanced connection transmit power level.

Parameters:
  • conn – Connection object.

  • tx_power – Transmit power level descriptor.

Return values:

-ENOBUFS – HCI command buffer is not available.

Returns:

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

int bt_conn_le_get_remote_tx_power_level(struct bt_conn *conn, enum bt_conn_le_tx_power_phy phy)

Get remote (peer) transmit power level.

Parameters:
  • conn – Connection object.

  • phy – PHY information.

Return values:

-ENOBUFS – HCI command buffer is not available.

Returns:

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

int bt_conn_le_set_tx_power_report_enable(struct bt_conn *conn, bool local_enable, bool remote_enable)

Enable transmit power reporting.

Parameters:
  • conn – Connection object.

  • local_enable – Enable/disable reporting for local.

  • remote_enable – Enable/disable reporting for remote.

Return values:

-ENOBUFS – HCI command buffer is not available.

Returns:

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

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.

Parameters:
  • conn – Connection object.

  • param – Updated connection parameters.

Returns:

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

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.

Parameters:
  • conn – Connection object.

  • param – Updated data length parameters.

Returns:

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

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.

Parameters:
  • conn – Connection object.

  • param – Updated connection parameters.

Returns:

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

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

Parameters:
  • conn – Connection to disconnect.

  • reason – Reason code for the disconnection.

Returns:

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

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.

The application must disable explicit scanning before initiating a new LE connection.

Parameters:
  • peer[in] Remote address.

  • create_param[in] Create connection parameters.

  • conn_param[in] Initial connection parameters.

  • conn[out] Valid connection object on success.

Returns:

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

int bt_conn_le_create_synced(const struct bt_le_ext_adv *adv, const struct bt_conn_le_create_synced_param *synced_param, const struct bt_le_conn_param *conn_param, struct bt_conn **conn)

Create a connection to a synced device.

Initiate a connection to a synced device from a Periodic Advertising with Responses (PAwR) train.

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 Periodic Advertising Connection Procedure.

Parameters:
  • adv[in] The adverting set the PAwR advertiser belongs to.

  • synced_param[in] Create connection parameters.

  • conn_param[in] Initial connection parameters.

  • conn[out] Valid connection object on success.

Returns:

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

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 the filter accept list.

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 the filter accept list the procedure should be started again in the connected callback after a new connection has been established.

Parameters:
  • create_param – Create connection parameters

  • conn_param – Initial connection parameters.

Returns:

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

Returns:

-ENOMEM No free connection object available.

int bt_conn_create_auto_stop(void)

Stop automatic connect creation.

Returns:

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.

Parameters:
  • addr – Remote Bluetooth address.

  • param – If non-NULL, auto connect is enabled with the given parameters. If NULL, auto connect is disabled.

Returns:

Zero on success or error code otherwise.

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. Note that sec has no effect on the security level selected for the pairing process. The selection is instead controlled by the values of the registered bt_conn_auth_cb. 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 an error if the required level of security defined using sec 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 an 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.

Note

When BT_SECURITY_FORCE_PAIR within sec is enabled then the pairing procedure will always be initiated.

Parameters:
  • conn – Connection object.

  • sec – Requested minimum security level.

Returns:

0 on success or negative error

bt_security_t bt_conn_get_security(const struct bt_conn *conn)

Get security level for a connection.

Returns:

Connection security level

uint8_t bt_conn_enc_key_size(const 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.

Parameters:
  • conn – Existing connection object.

Returns:

Encryption key size.

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.

int bt_conn_cb_unregister(struct bt_conn_cb *cb)

Unregister connection callbacks.

Unregister the state of connections callbacks.

Parameters:
  • cb – Callback struct point to memory that remains valid.

Return values:
  • 0 – Success

  • -EINVAL – If cb is NULL

  • -ENOENT – if cb was not registered

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_conn_set_bondable(struct bt_conn *conn, bool enable)

Set/clear the bonding flag for a given connection.

Set/clear the Bonding flag in the Authentication Requirements of SMP Pairing Request/Response data for a given connection.

The bonding flag for a given connection cannot be set/cleared if security procedures in the SMP module have already started. This function can be called only once per connection.

If the bonding flag is not set/cleared for a given connection, the value will depend on global configuration which is set using bt_set_bondable. The default value of the global configuration is defined using CONFIG_BT_BONDABLE Kconfig option.

Parameters:
  • conn – Connection object.

  • enable – Value allowing/disallowing to be bondable.

void bt_le_oob_set_sc_flag(bool enable)

Allow/disallow remote LE SC OOB data to be used for pairing.

Set/clear the OOB data flag for LE SC SMP Pairing Request/Response data.

Parameters:
  • enable – Value allowing/disallowing remote LE SC OOB data.

void bt_le_oob_set_legacy_flag(bool enable)

Allow/disallow remote legacy OOB data to be used for pairing.

Set/clear the OOB data flag for legacy SMP Pairing Request/Response data.

Parameters:
  • enable – Value allowing/disallowing remote legacy 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.

Parameters:
  • conn – Connection object

  • tk – Pointer to 16 byte long TK array

Returns:

Zero on success or -EINVAL if NULL

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.

Parameters:
  • conn – Connection object

  • oobd_local – Local OOB data or NULL if not present

  • oobd_remote – Remote OOB data or NULL if not present

Returns:

Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error.

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.

Parameters:
  • conn – Connection object

  • oobd_local – Local OOB data or NULL if not set

  • oobd_remote – Remote OOB data or NULL if not set

Returns:

Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error.

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_confirm() callback will be called for all incoming pairings.

Parameters:
  • passkey – A valid passkey (0 - 999999) or BT_PASSKEY_INVALID to disable a previously set fixed passkey.

Returns:

0 on success or a negative error code on failure.

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.

Parameters:
  • cb – Callback struct.

Returns:

Zero on success or negative error code otherwise

int bt_conn_auth_cb_overlay(struct bt_conn *conn, const struct bt_conn_auth_cb *cb)

Overlay authentication callbacks used for a given connection.

This function can be used only for Bluetooth LE connections. The CONFIG_BT_SMP must be enabled for this function.

The authentication callbacks for a given connection cannot be overlaid if security procedures in the SMP module have already started. This function can be called only once per connection.

Parameters:
  • conn – Connection object.

  • cb – Callback struct.

Returns:

Zero on success or negative error code otherwise

int bt_conn_auth_info_cb_register(struct bt_conn_auth_info_cb *cb)

Register authentication information callbacks.

Register callbacks to get authenticated pairing information. Multiple registrations can be done.

Parameters:
  • cb – Callback struct.

Returns:

Zero on success or negative error code otherwise

int bt_conn_auth_info_cb_unregister(struct bt_conn_auth_info_cb *cb)

Unregister authentication information callbacks.

Unregister callbacks to stop getting authenticated pairing information.

Parameters:
  • cb – Callback struct.

Returns:

Zero on success or negative error code otherwise

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.

Parameters:
  • conn – Connection object.

  • passkey – Entered passkey.

Returns:

Zero on success or negative error code otherwise

int bt_conn_auth_keypress_notify(struct bt_conn *conn, enum bt_conn_auth_keypress type)

Send Passkey Keypress Notification during pairing.

This function may be called only after passkey_entry callback from bt_conn_auth_cb structure was called.

Requires CONFIG_BT_PASSKEY_KEYPRESS .

Parameters:
  • conn – Destination for the notification.

  • type – What keypress event type to send.

Return values:
  • 0 – Success

  • -EINVAL – Improper use of the API.

  • -ENOMEM – Failed to allocate.

  • -ENOBUFS – Failed to allocate.

int bt_conn_auth_cancel(struct bt_conn *conn)

Cancel ongoing authenticated pairing.

This function allows to cancel ongoing authenticated pairing.

Parameters:
  • conn – Connection object.

Returns:

Zero on success or negative error code otherwise

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.

Parameters:
  • conn – Connection object.

Returns:

Zero on success or negative error code otherwise

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.

Parameters:
  • conn – Connection object.

Returns:

Zero on success or negative error code otherwise

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.

Parameters:
  • conn – Connection object.

  • pin – Entered PIN code.

Returns:

Zero on success or negative error code otherwise

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.

Parameters:
  • peer – Remote address.

  • param – Initial connection parameters.

Returns:

Valid connection object on success or NULL otherwise.

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

uint16_t options

Connection PHY options.

uint8_t pref_tx_phy

Bitmask of preferred transmit PHYs.

uint8_t pref_rx_phy

Bitmask of preferred receive 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 interval

Connection interval.

uint16_t latency

Connection peripheral latency.

uint16_t timeout

Connection supervision timeout.

struct bt_conn_br_info
#include <conn.h>

BR/EDR Connection Info Structure.

Public Members

const bt_addr_t *dst

Destination (Remote) BR/EDR address.

struct bt_security_info
#include <conn.h>

Security Info Structure.

Public Members

bt_security_t level

Security Level.

uint8_t enc_key_size

Encryption Key Size.

enum bt_security_flag flags

Flags.

struct bt_conn_info
#include <conn.h>

Connection Info Structure.

Public Members

enum bt_conn_type type

Connection Type.

uint8_t role

Connection Role.

uint8_t id

Which local identity the connection was created with.

struct bt_conn_le_info le

LE Connection specific Info.

struct bt_conn_br_info br

BR/EDR Connection specific Info.

union bt_conn_info.[anonymous] [anonymous]

Connection Type specific Info.

enum bt_conn_state state

Connection state.

struct bt_security_info security

Security 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_remote_info le

LE connection remote info.

struct bt_conn_br_remote_info br

BR/EDR connection remote info.

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

LE Transmit Power Reporting Structure.

Public Members

uint8_t reason

Reason for Transmit power reporting, as documented in Core Spec.

Version 5.4 Vol. 4, Part E, 7.7.65.33.

enum bt_conn_le_tx_power_phy phy

Phy of Transmit power reporting.

int8_t tx_power_level

Transmit power level.

  • 0xXX - Transmit power level

    • Range: -127 to 20

    • Units: dBm

  • 0x7E - Remote device is not managing power levels on this PHY.

  • 0x7F - Transmit power level is not available

uint8_t tx_power_level_flag

Bit 0: Transmit power level is at minimum level.

Bit 1: Transmit power level is at maximum level.

int8_t delta

Change in transmit power level.

  • 0xXX - Change in transmit power level (positive indicates increased power, negative indicates decreased power, zero indicates unchanged) Units: dB

  • 0x7F - Change is not available or is out of range.

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_le_create_auto

struct bt_conn_le_create_synced_param
#include <conn.h>

Public Members

const bt_addr_le_t *peer

Remote address.

The peer must be synchronized to the PAwR train.

uint8_t subevent

The subevent where the connection will be initiated.

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:

Note

If the connection was established from an advertising set then the advertising set cannot be restarted directly from this callback. Instead use the connected callback of the advertising set.

Param conn:

New connection object.

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

Param conn:

Connection object.

Param reason:

BT_HCI_ERR_* reason for the disconnection.

void (*recycled)(void)

A connection object has been returned to the pool.

This callback notifies the application that it might be able to allocate a connection object. No guarantee, first come, first serve.

Use this to e.g. re-start connectable advertising or scanning.

Treat this callback as an ISR, as it originates from bt_conn_unref which is used by the BT stack. Making Bluetooth API calls in this context is error-prone and strongly discouraged.

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.

If the application does not have this callback then the default is to accept the parameters.

Param conn:

Connection object.

Param param:

Proposed connection parameters.

Return:

true to accept the parameters, or false to reject them.

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.

Param conn:

Connection object.

Param interval:

Connection interval.

Param latency:

Connection latency.

Param 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

Param conn:

Connection object.

Param rpa:

Resolvable Private Address.

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

Param conn:

Connection object.

Param level:

New security level of the connection.

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

Param conn:

Connection object.

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

Param conn:

Connection object.

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

Param conn:

Connection object.

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

enum bt_conn_oob_info.[anonymous].[anonymous].[anonymous] oob_config

OOB data configuration.

struct bt_conn_oob_info.[anonymous].[anonymous] lesc

LE Secure Connections OOB pairing parameters.

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

Param conn:

Connection where pairing is initiated.

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

Param conn:

Connection where pairing is currently active.

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

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

Param conn:

Connection where pairing is currently active.

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

Param conn:

Connection where pairing is currently active.

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

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

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

Param conn:

Connection where pairing is currently active.

Param highsec:

true if 16 digit PIN is required.

struct bt_conn_auth_info_cb
#include <conn.h>

Authenticated pairing information callback structure.

Public Members

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.

Param conn:

Connection object.

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

Param conn:

Connection object.

Param 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

Param id:

Which local identity had the bond.

Param peer:

Remote address.

sys_snode_t node

Internally used field for list handling.

struct bt_br_conn_param
#include <conn.h>

Connection parameters for BR/EDR connections.