Zephyr API Documentation  3.6.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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_subrate_param
 Connection subrating parameters for LE connections. More...
 
struct  bt_conn_le_subrating_info
 Subrating information for LE connections. More...
 
struct  bt_conn_le_subrate_changed
 Updated subrating connection 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_ROLE_MASTER   __DEPRECATED_MACRO BT_CONN_ROLE_CENTRAL
 Connection role (central or peripheral)
 
#define BT_CONN_ROLE_SLAVE   __DEPRECATED_MACRO BT_CONN_ROLE_PERIPHERAL
 
#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_tbt_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_subrate_set_defaults (const struct bt_conn_le_subrate_param *params)
 Set Default Connection Subrating Parameters.
 
int bt_conn_le_subrate_request (struct bt_conn *conn, const struct bt_conn_le_subrate_param *params)
 Request New Subrating Parameters.
 
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) \
})
Connection parameters for BR/EDR connections.
Definition: conn.h:1950

Helper to declare BR/EDR connection parameters inline.

Parameters
role_switchTrue 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_switchTrue if role switch is allowed

◆ BT_CONN_CB_DEFINE

#define BT_CONN_CB_DEFINE (   _name)

#include <zephyr/bluetooth/conn.h>

Value:
_CONCAT(bt_conn_cb_, \
_name))
#define STRUCT_SECTION_ITERABLE(struct_type, varname)
Defines a new element for an iterable section.
Definition: iterable_sections.h:216
Connection callback structure.
Definition: conn.h:1123

Register a callback structure for connection events.

Parameters
_nameName 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:
#define BT_CONN_LE_CREATE_PARAM(_options, _interval, _window)
Helper to declare create connection parameters inline.
Definition: conn.h:904
@ BT_CONN_LE_OPT_NONE
Convenience value when no options are specified.
Definition: conn.h:832
#define BT_GAP_SCAN_FAST_INTERVAL
Definition: gap.h:712

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:

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) \
})
Definition: conn.h:849

Helper to declare create connection parameters inline.

Parameters
_optionsCreate connection options.
_intervalCreate connection scan interval (N * 0.625 ms).
_windowCreate 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
_optionsCreate connection options.
_intervalCreate connection scan interval (N * 0.625 ms).
_windowCreate 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) \
})
Connection data length parameters for LE connections.
Definition: conn.h:161

Helper to declare transmit data length parameters inline.

Parameters
_tx_max_lenMaximum Link Layer transmission payload size in bytes.
_tx_max_timeMaximum 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_lenMaximum Link Layer transmission payload size in bytes.
_tx_max_timeMaximum 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) \
})
Preferred PHY parameters for LE connections.
Definition: conn.h:100

Helper to declare PHY parameters inline.

Parameters
_pref_tx_phyBitmask of preferred transmit PHYs.
_pref_rx_phyBitmask of preferred receive PHYs.

◆ BT_CONN_LE_PHY_PARAM_1M

#define BT_CONN_LE_PHY_PARAM_1M

#include <zephyr/bluetooth/conn.h>

Value:
#define BT_CONN_LE_PHY_PARAM(_pref_tx_phy, _pref_rx_phy)
Helper to declare PHY parameters inline.
Definition: conn.h:123
@ BT_GAP_LE_PHY_1M
LE 1M PHY.
Definition: gap.h:741

Only LE 1M PHY.

◆ BT_CONN_LE_PHY_PARAM_2M

#define BT_CONN_LE_PHY_PARAM_2M

#include <zephyr/bluetooth/conn.h>

Value:
@ BT_GAP_LE_PHY_2M
LE 2M PHY.
Definition: gap.h:743

Only LE 2M PHY.

◆ BT_CONN_LE_PHY_PARAM_ALL

#define BT_CONN_LE_PHY_PARAM_ALL

#include <zephyr/bluetooth/conn.h>

Value:

All LE PHYs.

◆ BT_CONN_LE_PHY_PARAM_CODED

#define BT_CONN_LE_PHY_PARAM_CODED

◆ 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:
{ \
.pref_tx_phy = (_pref_tx_phy), \
.pref_rx_phy = (_pref_rx_phy), \
}
@ BT_CONN_LE_PHY_OPT_NONE
Convenience value when no options are specified.
Definition: conn.h:90

Initialize PHY parameters.

Parameters
_pref_tx_phyBitmask of preferred transmit PHYs.
_pref_rx_phyBitmask of preferred receive PHYs.

◆ BT_CONN_ROLE_MASTER

#define BT_CONN_ROLE_MASTER   __DEPRECATED_MACRO BT_CONN_ROLE_CENTRAL

#include <zephyr/bluetooth/conn.h>

Connection role (central or peripheral)

◆ BT_CONN_ROLE_SLAVE

#define BT_CONN_ROLE_SLAVE   __DEPRECATED_MACRO BT_CONN_ROLE_PERIPHERAL

◆ 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) \
})
Connection parameters for LE connections.
Definition: conn.h:38

Helper to declare connection parameters inline.

Parameters
int_minMinimum Connection Interval (N * 1.25 ms)
int_maxMaximum Connection Interval (N * 1.25 ms)
latConnection Latency
toSupervision Timeout (N * 10 ms)

◆ BT_LE_CONN_PARAM_DEFAULT

#define BT_LE_CONN_PARAM_DEFAULT

#include <zephyr/bluetooth/conn.h>

Value:
0, 400)
#define BT_LE_CONN_PARAM(int_min, int_max, lat, to)
Helper to declare connection parameters inline.
Definition: conn.h:67
#define BT_GAP_INIT_CONN_INT_MAX
Definition: gap.h:731
#define BT_GAP_INIT_CONN_INT_MIN
Definition: gap.h:730

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_minMinimum Connection Interval (N * 1.25 ms)
int_maxMaximum Connection Interval (N * 1.25 ms)
latConnection Latency
toSupervision Timeout (N * 10 ms)

◆ BT_LE_DATA_LEN_PARAM_DEFAULT

#define BT_LE_DATA_LEN_PARAM_DEFAULT

#include <zephyr/bluetooth/conn.h>

Value:
#define BT_CONN_LE_DATA_LEN_PARAM(_tx_max_len, _tx_max_time)
Helper to declare transmit data length parameters inline.
Definition: conn.h:184
#define BT_GAP_DATA_TIME_DEFAULT
Default data time.
Definition: gap.h:803
#define BT_GAP_DATA_LEN_DEFAULT
Default data length.
Definition: gap.h:798

Default LE data length parameters.

◆ BT_LE_DATA_LEN_PARAM_MAX

#define BT_LE_DATA_LEN_PARAM_MAX

#include <zephyr/bluetooth/conn.h>

Value:
#define BT_GAP_DATA_TIME_MAX
Maximum data time.
Definition: gap.h:805
#define BT_GAP_DATA_LEN_MAX
Maximum data length.
Definition: gap.h:800

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

#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

#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

#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

#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

#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

#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

#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

#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
connConnection 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
connConnection object.
cbCallback 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
cbCallback 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
cbCallback 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
cbCallback 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
connDestination for the notification.
typeWhat keypress event type to send.
See also
bt_conn_auth_keypress.
Return values
0Success
-EINVALImproper use of the API.
-ENOMEMFailed to allocate.
-ENOBUFSFailed 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
connConnection 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
connConnection 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
connConnection object.
passkeyEntered 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
connConnection object.
pinEntered 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
cbCallback struct. Must point to memory that remains valid.
Return values
0Success.
-EEXISTif 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
cbCallback struct point to memory that remains valid.
Return values
0Success
-EINVALIf cb is NULL
-ENOENTif 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
peerRemote address.
paramInitial 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:

Parameters
connConnection to disconnect.
reasonReason 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
connExisting 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 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
typeConnection Type
funcFunction to call for each connection.
dataData 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
connConnection 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
connConnection object.
infoConnection 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
connConnection object.
remote_infoConnection 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
connConnection 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]peerRemote address.
[in]create_paramCreate connection parameters.
[in]conn_paramInitial connection parameters.
[out]connValid 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 the filter accept list the procedure should be started again in the connected callback after a new connection has been established.

Parameters
create_paramCreate connection parameters
conn_paramInitial 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]advThe adverting set the PAwR advertiser belongs to.
[in]synced_paramCreate connection parameters.
[in]conn_paramInitial connection parameters.
[out]connValid 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
connConnection object.
paramUpdated 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
connConnection object.
tx_powerTransmit power level descriptor.
Returns
Zero on success or (negative) error code on failure.
Return values
-ENOBUFSHCI 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
connConnection object.
phyPHY information.
Returns
Zero on success or (negative) error code on failure.
Return values
-ENOBUFSHCI 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
connConnection object.
tx_power_levelTransmit 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
connConnection object.
paramUpdated 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
connConnection object.
paramUpdated 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
connConnection Object.
enableEnable/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
connConnection object.
paramPath 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
connConnection object.
local_enableEnable/disable reporting for local.
remote_enableEnable/disable reporting for remote.
Returns
Zero on success or (negative) error code on failure.
Return values
-ENOBUFSHCI command buffer is not available.

◆ bt_conn_le_subrate_request()

int bt_conn_le_subrate_request ( struct bt_conn *  conn,
const struct bt_conn_le_subrate_param params 
)

#include <zephyr/bluetooth/conn.h>

Request New Subrating Parameters.

Request a change to the subrating parameters of a connection.

Note
To use this API CONFIG_BT_SUBRATING must be set.
Parameters
connConnection object.
paramsSubrating parameters.
Returns
Zero on success or (negative) error code on failure.

◆ bt_conn_le_subrate_set_defaults()

int bt_conn_le_subrate_set_defaults ( const struct bt_conn_le_subrate_param params)

#include <zephyr/bluetooth/conn.h>

Set Default Connection Subrating Parameters.

Change the default subrating parameters for all future ACL connections where the local device is the central. This command does not affect any existing connection. Parameters set for specific connection will always have precedence.

Note
To use this API CONFIG_BT_SUBRATING and CONFIG_BT_CENTRAL must be set.
Parameters
paramsSubrating parameters.
Returns
Zero on success or (negative) error code on failure.

◆ 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
idLocal identity (in most cases BT_ID_DEFAULT).
peerRemote 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
connConnection 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
connConnection object.
enableValue 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
connConnection object.
secRequested 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
connConnection 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
connConnection object
oobd_localLocal OOB data or NULL if not set
oobd_remoteRemote 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
enableValue 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
connConnection object
tkPointer 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
connConnection object
oobd_localLocal OOB data or NULL if not present
oobd_remoteRemote 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
enableValue 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
addrRemote Bluetooth address.
paramIf 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
passkeyA 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
enableValue allowing/disallowing to be bondable.