Connection management

Connection management. More...

Data Structures
struct	bt_le_conn_param
	Connection parameters for LE connections. More...
struct	bt_conn_le_phy_info
	Connection PHY information for LE connections. More...
struct	bt_conn_le_phy_param
	Preferred PHY parameters for LE connections. More...
struct	bt_conn_le_data_len_info
	Connection data length information for LE connections. More...
struct	bt_conn_le_data_len_param
	Connection data length parameters for LE connections. More...
struct	bt_conn_le_info
	LE Connection Info Structure. More...
struct	bt_conn_br_info
	BR/EDR Connection Info Structure. More...
struct	bt_security_info
	Security Info Structure. More...
struct	bt_conn_info
	Connection Info Structure. More...
struct	bt_conn_le_remote_info
	LE Connection Remote Info Structure. More...
struct	bt_conn_br_remote_info
	BR/EDR Connection Remote Info structure. More...
struct	bt_conn_remote_info
	Connection Remote Info Structure. More...
struct	bt_conn_le_tx_power
	LE Transmit Power Level Structure. More...
struct	bt_conn_le_tx_power_report
	LE Transmit Power Reporting Structure. More...
struct	bt_conn_le_path_loss_threshold_report
	LE Path Loss Monitoring Threshold Change Report Structure. More...
struct	bt_conn_le_path_loss_reporting_param
	LE Path Loss Monitoring Parameters Structure as defined in Core Spec. More...
struct	bt_conn_le_create_param
struct	bt_conn_le_create_synced_param
struct	bt_conn_cb
	Connection callback structure. More...
struct	bt_conn_oob_info
	Info Structure for OOB pairing. More...
struct	bt_conn_pairing_feat
	Pairing request and pairing response info structure. More...
struct	bt_conn_auth_cb
	Authenticated pairing callback structure. More...
struct	bt_conn_auth_info_cb
	Authenticated pairing information callback structure. More...
struct	bt_br_conn_param
	Connection parameters for BR/EDR connections. More...

Macros
#define	BT_LE_CONN_PARAM_INIT(int_min, int_max, lat, to)
	Initialize connection parameters.
#define	BT_LE_CONN_PARAM(int_min, int_max, lat, to)
	Helper to declare connection parameters inline.
#define	BT_LE_CONN_PARAM_DEFAULT
	Default LE connection parameters: Connection Interval: 30-50 ms Latency: 0 Timeout: 4 s.
#define	BT_CONN_LE_PHY_PARAM_INIT(_pref_tx_phy, _pref_rx_phy)
	Initialize PHY parameters.
#define	BT_CONN_LE_PHY_PARAM(_pref_tx_phy, _pref_rx_phy)
	Helper to declare PHY parameters inline.
#define	BT_CONN_LE_PHY_PARAM_1M
	Only LE 1M PHY.
#define	BT_CONN_LE_PHY_PARAM_2M
	Only LE 2M PHY.
#define	BT_CONN_LE_PHY_PARAM_CODED
	Only LE Coded PHY.
#define	BT_CONN_LE_PHY_PARAM_ALL
	All LE PHYs.
#define	BT_CONN_LE_DATA_LEN_PARAM_INIT(_tx_max_len, _tx_max_time)
	Initialize transmit data length parameters.
#define	BT_CONN_LE_DATA_LEN_PARAM(_tx_max_len, _tx_max_time)
	Helper to declare transmit data length parameters inline.
#define	BT_LE_DATA_LEN_PARAM_DEFAULT
	Default LE data length parameters.
#define	BT_LE_DATA_LEN_PARAM_MAX
	Maximum LE data length parameters.
#define	BT_CONN_INTERVAL_TO_MS(interval)   ((interval) * 5U / 4U)
	Convert connection interval to milliseconds.
#define	BT_CONN_INTERVAL_TO_US(interval)   ((interval) * 1250U)
	Convert connection interval to microseconds.
#define	BT_CONN_LE_CREATE_PARAM_INIT(_options, _interval, _window)
	Initialize create connection parameters.
#define	BT_CONN_LE_CREATE_PARAM(_options, _interval, _window)
	Helper to declare create connection parameters inline.
#define	BT_CONN_LE_CREATE_CONN
	Default LE create connection parameters.
#define	BT_CONN_LE_CREATE_CONN_AUTO
	Default LE create connection using filter accept list parameters.
#define	BT_CONN_CB_DEFINE(_name)
	Register a callback structure for connection events.
#define	BT_PASSKEY_INVALID   0xffffffff
	Special passkey value that can be used to disable a previously set fixed passkey.
#define	BT_BR_CONN_PARAM_INIT(role_switch)
	Initialize BR/EDR connection parameters.
#define	BT_BR_CONN_PARAM(role_switch)
	Helper to declare BR/EDR connection parameters inline.
#define	BT_BR_CONN_PARAM_DEFAULT   BT_BR_CONN_PARAM(true)
	Default BR/EDR connection parameters: Role switch allowed.

Enumerations
enum	{ BT_CONN_LE_PHY_OPT_NONE = 0 , BT_CONN_LE_PHY_OPT_CODED_S2 = BIT(0) , BT_CONN_LE_PHY_OPT_CODED_S8 = BIT(1) }
	Connection PHY options. More...
enum	bt_conn_type {   BT_CONN_TYPE_LE = BIT(0) , BT_CONN_TYPE_BR = BIT(1) , BT_CONN_TYPE_SCO = BIT(2) , BT_CONN_TYPE_ISO = BIT(3) ,   BT_CONN_TYPE_ALL }
	Connection Type. More...
enum	{ BT_CONN_ROLE_CENTRAL = 0 , BT_CONN_ROLE_PERIPHERAL = 1 }
enum	bt_conn_state { BT_CONN_STATE_DISCONNECTED , BT_CONN_STATE_CONNECTING , BT_CONN_STATE_CONNECTED , BT_CONN_STATE_DISCONNECTING }
enum	bt_security_t {   BT_SECURITY_L0 , BT_SECURITY_L1 , BT_SECURITY_L2 , BT_SECURITY_L3 ,   BT_SECURITY_L4 , BT_SECURITY_FORCE_PAIR = BIT(7) }
	Security level. More...
enum	bt_security_flag { BT_SECURITY_FLAG_SC = BIT(0) , BT_SECURITY_FLAG_OOB = BIT(1) }
	Security Info Flags. More...
enum	bt_conn_le_tx_power_phy {   BT_CONN_LE_TX_POWER_PHY_NONE , BT_CONN_LE_TX_POWER_PHY_1M , BT_CONN_LE_TX_POWER_PHY_2M , BT_CONN_LE_TX_POWER_PHY_CODED_S8 ,   BT_CONN_LE_TX_POWER_PHY_CODED_S2 }
enum	bt_conn_le_path_loss_zone { BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_LOW , BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_MIDDLE , BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_HIGH , BT_CONN_LE_PATH_LOSS_ZONE_UNAVAILABLE }
	Path Loss zone that has been entered. More...
enum	bt_conn_auth_keypress {   BT_CONN_AUTH_KEYPRESS_ENTRY_STARTED = 0x00 , BT_CONN_AUTH_KEYPRESS_DIGIT_ENTERED = 0x01 , BT_CONN_AUTH_KEYPRESS_DIGIT_ERASED = 0x02 , BT_CONN_AUTH_KEYPRESS_CLEARED = 0x03 ,   BT_CONN_AUTH_KEYPRESS_ENTRY_COMPLETED = 0x04 }
	Passkey Keypress Notification type. More...
enum	{ BT_CONN_LE_OPT_NONE = 0 , BT_CONN_LE_OPT_CODED = BIT(0) , BT_CONN_LE_OPT_NO_1M = BIT(1) }
enum	bt_security_err {   BT_SECURITY_ERR_SUCCESS , BT_SECURITY_ERR_AUTH_FAIL , BT_SECURITY_ERR_PIN_OR_KEY_MISSING , BT_SECURITY_ERR_OOB_NOT_AVAILABLE ,   BT_SECURITY_ERR_AUTH_REQUIREMENT , BT_SECURITY_ERR_PAIR_NOT_SUPPORTED , BT_SECURITY_ERR_PAIR_NOT_ALLOWED , BT_SECURITY_ERR_INVALID_PARAM ,   BT_SECURITY_ERR_KEY_REJECTED , BT_SECURITY_ERR_UNSPECIFIED }

Functions
struct bt_conn *	bt_conn_ref (struct bt_conn *conn)
	Increment a connection's reference count.
void	bt_conn_unref (struct bt_conn *conn)
	Decrement a connection's reference count.
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.
struct bt_conn *	bt_conn_lookup_addr_le (uint8_t id, const bt_addr_le_t *peer)
	Look up an existing connection by address.
const bt_addr_le_t *	bt_conn_get_dst (const struct bt_conn *conn)
	Get destination (peer) address of a connection.
uint8_t	bt_conn_index (const struct bt_conn *conn)
	Get array index of a connection.
int	bt_conn_get_info (const struct bt_conn *conn, struct bt_conn_info *info)
	Get connection info.
int	bt_conn_get_remote_info (struct bt_conn *conn, struct bt_conn_remote_info *remote_info)
	Get connection info for the remote device.
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.
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.
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.
int	bt_conn_le_set_tx_power_report_enable (struct bt_conn *conn, bool local_enable, bool remote_enable)
	Enable transmit power reporting.
int	bt_conn_le_set_path_loss_mon_param (struct bt_conn *conn, const struct bt_conn_le_path_loss_reporting_param *param)
	Set Path Loss Monitoring Parameters.
int	bt_conn_le_set_path_loss_mon_enable (struct bt_conn *conn, bool enable)
	Enable or Disable Path Loss Monitoring.
int	bt_conn_le_param_update (struct bt_conn *conn, const struct bt_le_conn_param *param)
	Update the connection parameters.
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.
int	bt_conn_le_phy_update (struct bt_conn *conn, const struct bt_conn_le_phy_param *param)
	Update the connection PHY parameters.
int	bt_conn_disconnect (struct bt_conn *conn, uint8_t reason)
	Disconnect from a remote device or cancel pending connection.
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.
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.
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.
int	bt_conn_create_auto_stop (void)
	Stop automatic connect creation.
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.
int	bt_conn_set_security (struct bt_conn *conn, bt_security_t sec)
	Set security level for a connection.
bt_security_t	bt_conn_get_security (const struct bt_conn *conn)
	Get security level for a connection.
uint8_t	bt_conn_enc_key_size (const struct bt_conn *conn)
	Get encryption key size.
int	bt_conn_cb_register (struct bt_conn_cb *cb)
	Register connection callbacks.
int	bt_conn_cb_unregister (struct bt_conn_cb *cb)
	Unregister connection callbacks.
static const char *	bt_security_err_to_str (enum bt_security_err err)
	Converts a security error to string.
void	bt_set_bondable (bool enable)
	Enable/disable bonding.
int	bt_conn_set_bondable (struct bt_conn *conn, bool enable)
	Set/clear the bonding flag for a given connection.
void	bt_le_oob_set_sc_flag (bool enable)
	Allow/disallow remote LE SC OOB data to be used for pairing.
void	bt_le_oob_set_legacy_flag (bool enable)
	Allow/disallow remote legacy OOB data to be used for pairing.
int	bt_le_oob_set_legacy_tk (struct bt_conn *conn, const uint8_t *tk)
	Set OOB Temporary Key to be used for pairing.
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.
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.
int	bt_passkey_set (unsigned int passkey)
	Set a fixed passkey to be used for pairing.
int	bt_conn_auth_cb_register (const struct bt_conn_auth_cb *cb)
	Register authentication callbacks.
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.
int	bt_conn_auth_info_cb_register (struct bt_conn_auth_info_cb *cb)
	Register authentication information callbacks.
int	bt_conn_auth_info_cb_unregister (struct bt_conn_auth_info_cb *cb)
	Unregister authentication information callbacks.
int	bt_conn_auth_passkey_entry (struct bt_conn *conn, unsigned int passkey)
	Reply with entered passkey.
int	bt_conn_auth_keypress_notify (struct bt_conn *conn, enum bt_conn_auth_keypress type)
	Send Passkey Keypress Notification during pairing.
int	bt_conn_auth_cancel (struct bt_conn *conn)
	Cancel ongoing authenticated pairing.
int	bt_conn_auth_passkey_confirm (struct bt_conn *conn)
	Reply if passkey was confirmed to match by user.
int	bt_conn_auth_pairing_confirm (struct bt_conn *conn)
	Reply if incoming pairing was confirmed by user.
int	bt_conn_auth_pincode_entry (struct bt_conn *conn, const char *pin)
	Reply with 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.

Detailed Description

Connection management.

Macro Definition Documentation

BT_BR_CONN_PARAM

#define BT_BR_CONN_PARAM

(

role_switch

)

#include <zephyr/bluetooth/conn.h>

Value:

        ((struct bt_br_conn_param[]) { \
                BT_BR_CONN_PARAM_INIT(role_switch) \
         })

Helper to declare BR/EDR connection parameters inline.

Parameters

role_switch

True if role switch is allowed

BT_BR_CONN_PARAM_DEFAULT

#define BT_BR_CONN_PARAM_DEFAULT   BT_BR_CONN_PARAM(true)

#include <zephyr/bluetooth/conn.h>

Default BR/EDR connection parameters: Role switch allowed.

BT_BR_CONN_PARAM_INIT

#define BT_BR_CONN_PARAM_INIT

(

role_switch

)

#include <zephyr/bluetooth/conn.h>

Value:

{ \
        .allow_role_switch = (role_switch), \
}

Initialize BR/EDR connection parameters.

Parameters

role_switch

True if role switch is allowed

BT_CONN_CB_DEFINE

#define BT_CONN_CB_DEFINE

(

_name

)

#include <zephyr/bluetooth/conn.h>

Value:

        static const STRUCT_SECTION_ITERABLE(bt_conn_cb,                \
                                                _CONCAT(bt_conn_cb_,    \
                                                        _name))

Register a callback structure for connection events.

Parameters

_name

Name of callback structure.

BT_CONN_INTERVAL_TO_MS

#define BT_CONN_INTERVAL_TO_MS

(

interval

)

((interval) * 5U / 4U)

#include <zephyr/bluetooth/conn.h>

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

#define BT_CONN_INTERVAL_TO_US

(

interval

)

((interval) * 1250U)

#include <zephyr/bluetooth/conn.h>

Convert connection interval to microseconds.

Multiply by 1250 to get microseconds.

BT_CONN_LE_CREATE_CONN

#define BT_CONN_LE_CREATE_CONN

#include <zephyr/bluetooth/conn.h>

Value:

        BT_CONN_LE_CREATE_PARAM(BT_CONN_LE_OPT_NONE, \
                                BT_GAP_SCAN_FAST_INTERVAL, \
                                BT_GAP_SCAN_FAST_INTERVAL)

Default LE create connection parameters.

Scan continuously by setting scan interval equal to scan window.

BT_CONN_LE_CREATE_CONN_AUTO

#define BT_CONN_LE_CREATE_CONN_AUTO

#include <zephyr/bluetooth/conn.h>

Value:

        BT_CONN_LE_CREATE_PARAM(BT_CONN_LE_OPT_NONE, \
                                BT_GAP_SCAN_FAST_INTERVAL, \
                                BT_GAP_SCAN_FAST_WINDOW)

Default LE create connection using filter accept list parameters.

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

BT_CONN_LE_CREATE_PARAM

#define BT_CONN_LE_CREATE_PARAM	(		_options,
			_interval,
			_window
	)

#include <zephyr/bluetooth/conn.h>

Value:

        ((struct bt_conn_le_create_param[]) { \
                BT_CONN_LE_CREATE_PARAM_INIT(_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_PARAM_INIT

#define BT_CONN_LE_CREATE_PARAM_INIT	(		_options,
			_interval,
			_window
	)

#include <zephyr/bluetooth/conn.h>

Value:

{ \
        .options = (_options), \
        .interval = (_interval), \
        .window = (_window), \
        .interval_coded = 0, \
        .window_coded = 0, \
        .timeout = 0, \
}

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_DATA_LEN_PARAM

#define BT_CONN_LE_DATA_LEN_PARAM	(		_tx_max_len,
			_tx_max_time
	)

#include <zephyr/bluetooth/conn.h>

Value:

        ((struct bt_conn_le_data_len_param[]) { \
                BT_CONN_LE_DATA_LEN_PARAM_INIT(_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_CONN_LE_DATA_LEN_PARAM_INIT

#define BT_CONN_LE_DATA_LEN_PARAM_INIT	(		_tx_max_len,
			_tx_max_time
	)

#include <zephyr/bluetooth/conn.h>

Value:

{ \
        .tx_max_len = (_tx_max_len), \
        .tx_max_time = (_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_PHY_PARAM

#define BT_CONN_LE_PHY_PARAM	(		_pref_tx_phy,
			_pref_rx_phy
	)

#include <zephyr/bluetooth/conn.h>

Value:

        ((struct bt_conn_le_phy_param []) { \
                BT_CONN_LE_PHY_PARAM_INIT(_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

#define BT_CONN_LE_PHY_PARAM_1M

#include <zephyr/bluetooth/conn.h>

Value:

                                                     BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_1M, \
                                                     BT_GAP_LE_PHY_1M)

Only LE 1M PHY.

BT_CONN_LE_PHY_PARAM_2M

#define BT_CONN_LE_PHY_PARAM_2M

#include <zephyr/bluetooth/conn.h>

Value:

                                                     BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_2M, \
                                                     BT_GAP_LE_PHY_2M)

Only LE 2M PHY.

BT_CONN_LE_PHY_PARAM_ALL

#define BT_CONN_LE_PHY_PARAM_ALL

#include <zephyr/bluetooth/conn.h>

Value:

                                                      BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_1M |   \
                                                      BT_GAP_LE_PHY_2M |   \
                                                      BT_GAP_LE_PHY_CODED, \
                                                      BT_GAP_LE_PHY_1M |   \
                                                      BT_GAP_LE_PHY_2M |   \
                                                      BT_GAP_LE_PHY_CODED)

All LE PHYs.

BT_CONN_LE_PHY_PARAM_CODED

#define BT_CONN_LE_PHY_PARAM_CODED

#include <zephyr/bluetooth/conn.h>

Value:

                                                        BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_CODED, \
                                                        BT_GAP_LE_PHY_CODED)

Only LE Coded PHY.

BT_CONN_LE_PHY_PARAM_INIT

#define BT_CONN_LE_PHY_PARAM_INIT	(		_pref_tx_phy,
			_pref_rx_phy
	)

#include <zephyr/bluetooth/conn.h>

Value:

{ \
        .options = BT_CONN_LE_PHY_OPT_NONE, \
        .pref_tx_phy = (_pref_tx_phy), \
        .pref_rx_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_LE_CONN_PARAM

#define BT_LE_CONN_PARAM	(		int_min,
			int_max,
			lat,
			to
	)

#include <zephyr/bluetooth/conn.h>

Value:

        ((struct bt_le_conn_param[]) { \
                BT_LE_CONN_PARAM_INIT(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

#define BT_LE_CONN_PARAM_DEFAULT

#include <zephyr/bluetooth/conn.h>

Value:

                                                  BT_LE_CONN_PARAM(BT_GAP_INIT_CONN_INT_MIN, \
                                                  BT_GAP_INIT_CONN_INT_MAX, \
                                                  0, 400)

Default LE connection parameters: Connection Interval: 30-50 ms Latency: 0 Timeout: 4 s.

BT_LE_CONN_PARAM_INIT

#define BT_LE_CONN_PARAM_INIT	(		int_min,
			int_max,
			lat,
			to
	)

#include <zephyr/bluetooth/conn.h>

Value:

{ \
        .interval_min = (int_min), \
        .interval_max = (int_max), \
        .latency = (lat), \
        .timeout = (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_DATA_LEN_PARAM_DEFAULT

#define BT_LE_DATA_LEN_PARAM_DEFAULT

#include <zephyr/bluetooth/conn.h>

Value:

        BT_CONN_LE_DATA_LEN_PARAM(BT_GAP_DATA_LEN_DEFAULT, \
                                  BT_GAP_DATA_TIME_DEFAULT)

Default LE data length parameters.

BT_LE_DATA_LEN_PARAM_MAX

#define BT_LE_DATA_LEN_PARAM_MAX

#include <zephyr/bluetooth/conn.h>

Value:

        BT_CONN_LE_DATA_LEN_PARAM(BT_GAP_DATA_LEN_MAX, \
                                  BT_GAP_DATA_TIME_MAX)

Maximum LE data length parameters.

BT_PASSKEY_INVALID

#define BT_PASSKEY_INVALID   0xffffffff

#include <zephyr/bluetooth/conn.h>

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

Enumeration Type Documentation

anonymous enum

anonymous enum

#include <zephyr/bluetooth/conn.h>

Connection PHY options.

Enumerator
BT_CONN_LE_PHY_OPT_NONE	Convenience value when no options are specified.
BT_CONN_LE_PHY_OPT_CODED_S2	LE Coded using S=2 coding preferred when transmitting.
BT_CONN_LE_PHY_OPT_CODED_S8	LE Coded using S=8 coding preferred when transmitting.

anonymous enum

anonymous enum

#include <zephyr/bluetooth/conn.h>

Enumerator
BT_CONN_ROLE_CENTRAL
BT_CONN_ROLE_PERIPHERAL

anonymous enum

anonymous enum

#include <zephyr/bluetooth/conn.h>

Enumerator
BT_CONN_LE_OPT_NONE	Convenience value when no options are specified.
BT_CONN_LE_OPT_CODED	Enable LE Coded PHY. Enable scanning on the LE Coded PHY.
BT_CONN_LE_OPT_NO_1M	Disable LE 1M PHY. Disable scanning on the LE 1M PHY. @note Requires @ref BT_CONN_LE_OPT_CODED.

bt_conn_auth_keypress

enum bt_conn_auth_keypress

#include <zephyr/bluetooth/conn.h>

Passkey Keypress Notification type.

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

Enumerator
BT_CONN_AUTH_KEYPRESS_ENTRY_STARTED
BT_CONN_AUTH_KEYPRESS_DIGIT_ENTERED
BT_CONN_AUTH_KEYPRESS_DIGIT_ERASED
BT_CONN_AUTH_KEYPRESS_CLEARED
BT_CONN_AUTH_KEYPRESS_ENTRY_COMPLETED

bt_conn_le_path_loss_zone

enum bt_conn_le_path_loss_zone

#include <zephyr/bluetooth/conn.h>

Path Loss zone that has been entered.

The path loss zone that has been entered in the most recent LE Path Loss Monitoring Threshold Change event as documented in Core Spec. Version 5.4 Vol.4, Part E, 7.7.65.32.

Note

BT_CONN_LE_PATH_LOSS_ZONE_UNAVAILABLE has been added to notify when path loss becomes unavailable.

Enumerator
BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_LOW	Low path loss zone entered.
BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_MIDDLE	Middle path loss zone entered.
BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_HIGH	High path loss zone entered.
BT_CONN_LE_PATH_LOSS_ZONE_UNAVAILABLE	Path loss has become unavailable.

bt_conn_le_tx_power_phy

enum bt_conn_le_tx_power_phy

#include <zephyr/bluetooth/conn.h>

Enumerator
BT_CONN_LE_TX_POWER_PHY_NONE	Convenience macro for when no PHY is set.
BT_CONN_LE_TX_POWER_PHY_1M	LE 1M PHY.
BT_CONN_LE_TX_POWER_PHY_2M	LE 2M PHY.
BT_CONN_LE_TX_POWER_PHY_CODED_S8	LE Coded PHY using S=8 coding.
BT_CONN_LE_TX_POWER_PHY_CODED_S2	LE Coded PHY using S=2 coding.

bt_conn_state

enum bt_conn_state

#include <zephyr/bluetooth/conn.h>

Enumerator
BT_CONN_STATE_DISCONNECTED	Channel disconnected.
BT_CONN_STATE_CONNECTING	Channel in connecting state.
BT_CONN_STATE_CONNECTED	Channel connected and ready for upper layer traffic on it.
BT_CONN_STATE_DISCONNECTING	Channel in disconnecting state.

bt_conn_type

enum bt_conn_type

#include <zephyr/bluetooth/conn.h>

Connection Type.

Enumerator
BT_CONN_TYPE_LE	LE Connection Type.
BT_CONN_TYPE_BR	BR/EDR Connection Type.
BT_CONN_TYPE_SCO	SCO Connection Type.
BT_CONN_TYPE_ISO	ISO Connection Type.
BT_CONN_TYPE_ALL	All Connection Type.

bt_security_err

enum bt_security_err

#include <zephyr/bluetooth/conn.h>

Enumerator
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_KEY_REJECTED	Distributed Key Rejected.
BT_SECURITY_ERR_UNSPECIFIED	Pairing failed but the exact reason could not be specified.

bt_security_flag

enum bt_security_flag

#include <zephyr/bluetooth/conn.h>

Security Info Flags.

Enumerator
BT_SECURITY_FLAG_SC	Paired with Secure Connections.
BT_SECURITY_FLAG_OOB	Paired with Out of Band method.

bt_security_t

enum bt_security_t

#include <zephyr/bluetooth/conn.h>

Security level.

Enumerator
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_FORCE_PAIR	Bit to force new pairing procedure, bit-wise OR with requested security level.

Function Documentation

bt_conn_auth_cancel()

int bt_conn_auth_cancel

(

struct bt_conn *

conn

)

#include <zephyr/bluetooth/conn.h>

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

bt_conn_auth_cb_overlay()

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

#include <zephyr/bluetooth/conn.h>

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

bt_conn_auth_cb_register()

int bt_conn_auth_cb_register

(

const struct bt_conn_auth_cb *

cb

)

#include <zephyr/bluetooth/conn.h>

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

bt_conn_auth_info_cb_register()

int bt_conn_auth_info_cb_register

(

struct bt_conn_auth_info_cb *

cb

)

#include <zephyr/bluetooth/conn.h>

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

bt_conn_auth_info_cb_unregister()

int bt_conn_auth_info_cb_unregister

(

struct bt_conn_auth_info_cb *

cb

)

#include <zephyr/bluetooth/conn.h>

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

bt_conn_auth_keypress_notify()

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

#include <zephyr/bluetooth/conn.h>

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.

See also

bt_conn_auth_keypress.

Return values

0	Success
-EINVAL	Improper use of the API.
-ENOMEM	Failed to allocate.
-ENOBUFS	Failed to allocate.

bt_conn_auth_pairing_confirm()

int bt_conn_auth_pairing_confirm

(

struct bt_conn *

conn

)

#include <zephyr/bluetooth/conn.h>

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

bt_conn_auth_passkey_confirm()

int bt_conn_auth_passkey_confirm

(

struct bt_conn *

conn

)

#include <zephyr/bluetooth/conn.h>

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

bt_conn_auth_passkey_entry()

int bt_conn_auth_passkey_entry	(	struct bt_conn *	conn,
		unsigned int	passkey
	)

#include <zephyr/bluetooth/conn.h>

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

bt_conn_auth_pincode_entry()

int bt_conn_auth_pincode_entry	(	struct bt_conn *	conn,
		const char *	pin
	)

#include <zephyr/bluetooth/conn.h>

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

bt_conn_cb_register()

int bt_conn_cb_register

(

struct bt_conn_cb *

cb

)

#include <zephyr/bluetooth/conn.h>

Register connection callbacks.

Register callbacks to monitor the state of connections.

Parameters

cb	Callback struct. Must point to memory that remains valid.

Return values

0	Success.
-EEXIST	if cb was already registered.

bt_conn_cb_unregister()

int bt_conn_cb_unregister

(

struct bt_conn_cb *

cb

)

#include <zephyr/bluetooth/conn.h>

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

bt_conn_create_auto_stop()

int bt_conn_create_auto_stop

(

void

)

#include <zephyr/bluetooth/conn.h>

Stop automatic connect creation.

Returns

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

bt_conn_create_br()

struct bt_conn * bt_conn_create_br	(	const bt_addr_t *	peer,
		const struct bt_br_conn_param *	param
	)

#include <zephyr/bluetooth/conn.h>

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.

bt_conn_disconnect()

int bt_conn_disconnect	(	struct bt_conn *	conn,
		uint8_t	reason
	)

#include <zephyr/bluetooth/conn.h>

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.

bt_conn_enc_key_size()

uint8_t bt_conn_enc_key_size

(

const struct bt_conn *

conn

)

#include <zephyr/bluetooth/conn.h>

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.

bt_conn_foreach()

void bt_conn_foreach	(	enum bt_conn_type	type,
		void(*)(struct bt_conn *conn, void *data)	func,
		void *	data
	)

#include <zephyr/bluetooth/conn.h>

Iterate through all bt_conn objects.

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

bt_conn_get_dst()

const bt_addr_le_t * bt_conn_get_dst

(

const struct bt_conn *

conn

)

#include <zephyr/bluetooth/conn.h>

Get destination (peer) address of a connection.

Parameters

conn	Connection object.

Returns

Destination address.

bt_conn_get_info()

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

#include <zephyr/bluetooth/conn.h>

Get connection info.

Parameters

conn	Connection object.
info	Connection info object.

Returns

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

bt_conn_get_remote_info()

int bt_conn_get_remote_info	(	struct bt_conn *	conn,
		struct bt_conn_remote_info *	remote_info
	)

#include <zephyr/bluetooth/conn.h>

Get connection info for the remote device.

Parameters

conn	Connection object.
remote_info	Connection remote info object.

Note

In order to retrieve the remote version (version, manufacturer and subversion) CONFIG_BT_REMOTE_VERSION must be enabled

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.

Returns

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

-EBUSY The remote information is not yet available.

bt_conn_get_security()

bt_security_t bt_conn_get_security

(

const struct bt_conn *

conn

)

#include <zephyr/bluetooth/conn.h>

Get security level for a connection.

Returns

Connection security level

bt_conn_index()

uint8_t bt_conn_index

(

const struct bt_conn *

conn

)

#include <zephyr/bluetooth/conn.h>

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

bt_conn_le_create()

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
	)

#include <zephyr/bluetooth/conn.h>

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 if CONFIG_BT_SCAN_AND_INITIATE_IN_PARALLEL is not enabled.

Parameters

[in]	peer	Remote address.
[in]	create_param	Create connection parameters.
[in]	conn_param	Initial connection parameters.
[out]	conn	Valid connection object on success.

Returns

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

bt_conn_le_create_auto()

int bt_conn_le_create_auto	(	const struct bt_conn_le_create_param *	create_param,
		const struct bt_le_conn_param *	conn_param
	)

#include <zephyr/bluetooth/conn.h>

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

-ENOMEM No free connection object available.

bt_conn_le_create_synced()

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
	)

#include <zephyr/bluetooth/conn.h>

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

[in]	adv	The adverting set the PAwR advertiser belongs to.
[in]	synced_param	Create connection parameters.
[in]	conn_param	Initial connection parameters.
[out]	conn	Valid connection object on success.

Returns

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

bt_conn_le_data_len_update()

int bt_conn_le_data_len_update	(	struct bt_conn *	conn,
		const struct bt_conn_le_data_len_param *	param
	)

#include <zephyr/bluetooth/conn.h>

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.

bt_conn_le_enhanced_get_tx_power_level()

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

#include <zephyr/bluetooth/conn.h>

Get local enhanced connection transmit power level.

Parameters

conn	Connection object.
tx_power	Transmit power level descriptor.

Returns

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

Return values

-ENOBUFS

HCI command buffer is not available.

bt_conn_le_get_remote_tx_power_level()

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

#include <zephyr/bluetooth/conn.h>

Get remote (peer) transmit power level.

Parameters

conn	Connection object.
phy	PHY information.

Returns

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

Return values

-ENOBUFS

HCI command buffer is not available.

bt_conn_le_get_tx_power_level()

int bt_conn_le_get_tx_power_level	(	struct bt_conn *	conn,
		struct bt_conn_le_tx_power *	tx_power_level
	)

#include <zephyr/bluetooth/conn.h>

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.

-ENOBUFS HCI command buffer is not available.

bt_conn_le_param_update()

int bt_conn_le_param_update	(	struct bt_conn *	conn,
		const struct bt_le_conn_param *	param
	)

#include <zephyr/bluetooth/conn.h>

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.

bt_conn_le_phy_update()

int bt_conn_le_phy_update	(	struct bt_conn *	conn,
		const struct bt_conn_le_phy_param *	param
	)

#include <zephyr/bluetooth/conn.h>

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.

bt_conn_le_set_path_loss_mon_enable()

int bt_conn_le_set_path_loss_mon_enable	(	struct bt_conn *	conn,
		bool	enable
	)

#include <zephyr/bluetooth/conn.h>

Enable or Disable Path Loss Monitoring.

Enable or disable Path Loss Monitoring, which will decide whether Path Loss Threshold events are sent from the controller to the host.

Note

To use this API CONFIG_BT_PATH_LOSS_MONITORING must be set.

Parameters

conn	Connection Object.
enable	Enable/disable path loss reporting.

Returns

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

bt_conn_le_set_path_loss_mon_param()

int bt_conn_le_set_path_loss_mon_param	(	struct bt_conn *	conn,
		const struct bt_conn_le_path_loss_reporting_param *	param
	)

#include <zephyr/bluetooth/conn.h>

Set Path Loss Monitoring Parameters.

Change the configuration for path loss threshold change events for a given conn handle.

Note

To use this API CONFIG_BT_PATH_LOSS_MONITORING must be set.

Parameters

conn	Connection object.
param	Path Loss Monitoring parameters

Returns

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

bt_conn_le_set_tx_power_report_enable()

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

#include <zephyr/bluetooth/conn.h>

Enable transmit power reporting.

Parameters

conn	Connection object.
local_enable	Enable/disable reporting for local.
remote_enable	Enable/disable reporting for remote.

Returns

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

Return values

-ENOBUFS

HCI command buffer is not available.

bt_conn_lookup_addr_le()

struct bt_conn * bt_conn_lookup_addr_le	(	uint8_t	id,
		const bt_addr_le_t *	peer
	)

#include <zephyr/bluetooth/conn.h>

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.

bt_conn_ref()

struct bt_conn * bt_conn_ref

(

struct bt_conn *

conn

)

#include <zephyr/bluetooth/conn.h>

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.

bt_conn_set_bondable()

int bt_conn_set_bondable	(	struct bt_conn *	conn,
		bool	enable
	)

#include <zephyr/bluetooth/conn.h>

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.

bt_conn_set_security()

int bt_conn_set_security	(	struct bt_conn *	conn,
		bt_security_t	sec
	)

#include <zephyr/bluetooth/conn.h>

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.

When CONFIG_BT_SMP_OOB_LEGACY_PAIR_ONLY is enabled then the security level will always be level 3.

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

void bt_conn_unref

(

struct bt_conn *

conn

)

#include <zephyr/bluetooth/conn.h>

Decrement a connection's reference count.

Decrement the reference count of a connection object.

Parameters

conn	Connection object.

bt_le_oob_get_sc_data()

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
	)

#include <zephyr/bluetooth/conn.h>

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.

bt_le_oob_set_legacy_flag()

void bt_le_oob_set_legacy_flag

(

bool

enable

)

#include <zephyr/bluetooth/conn.h>

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.

bt_le_oob_set_legacy_tk()

int bt_le_oob_set_legacy_tk	(	struct bt_conn *	conn,
		const uint8_t *	tk
	)

#include <zephyr/bluetooth/conn.h>

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

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

#include <zephyr/bluetooth/conn.h>

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.

bt_le_oob_set_sc_flag()

void bt_le_oob_set_sc_flag

(

bool

enable

)

#include <zephyr/bluetooth/conn.h>

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.

bt_le_set_auto_conn()

int bt_le_set_auto_conn	(	const bt_addr_le_t *	addr,
		const struct bt_le_conn_param *	param
	)

#include <zephyr/bluetooth/conn.h>

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.

bt_passkey_set()

int bt_passkey_set

(

unsigned int

passkey

)

#include <zephyr/bluetooth/conn.h>

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.

bt_security_err_to_str()

static const char * bt_security_err_to_str ( enum bt_security_err  err )

inlinestatic

#include <zephyr/bluetooth/conn.h>

Converts a security error to string.

Returns

The string representation of the security error code. If CONFIG_BT_SECURITY_ERR_TO_STR is not enabled, this just returns the empty string

bt_set_bondable()

void bt_set_bondable

(

bool

enable

)

#include <zephyr/bluetooth/conn.h>

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.