Zephyr API Documentation  2.7.0-rc2
A Scalable Open Source RTOS
Connection management

Connection management. More...

Data Structures

struct  bt_le_conn_param
 
struct  bt_conn_le_phy_info
 
struct  bt_conn_le_phy_param
 
struct  bt_conn_le_data_len_info
 
struct  bt_conn_le_data_len_param
 
struct  bt_conn_le_info
 
struct  bt_conn_br_info
 
struct  bt_conn_info
 
struct  bt_conn_le_remote_info
 
struct  bt_conn_br_remote_info
 
struct  bt_conn_remote_info
 Connection Remote Info Structure. More...
 
struct  bt_conn_le_tx_power
 
struct  bt_conn_le_create_param
 
struct  bt_conn_cb
 Connection callback structure. More...
 
struct  bt_conn_oob_info
 
struct  bt_conn_pairing_feat
 Pairing request and pairing response info structure. More...
 
struct  bt_conn_auth_cb
 
struct  bt_br_conn_param
 

Macros

#define BT_LE_CONN_PARAM_INIT(int_min, int_max, lat, to)
 Initialize connection parameters. More...
 
#define BT_LE_CONN_PARAM(int_min, int_max, lat, to)
 
#define BT_LE_CONN_PARAM_DEFAULT
 
#define BT_CONN_LE_PHY_PARAM_INIT(_pref_tx_phy, _pref_rx_phy)
 
#define BT_CONN_LE_PHY_PARAM(_pref_tx_phy, _pref_rx_phy)
 
#define BT_CONN_LE_PHY_PARAM_1M
 
#define BT_CONN_LE_PHY_PARAM_2M
 
#define BT_CONN_LE_PHY_PARAM_CODED
 
#define BT_CONN_LE_PHY_PARAM_ALL
 
#define BT_CONN_LE_DATA_LEN_PARAM_INIT(_tx_max_len, _tx_max_time)
 
#define BT_CONN_LE_DATA_LEN_PARAM(_tx_max_len, _tx_max_time)
 
#define BT_LE_DATA_LEN_PARAM_DEFAULT
 
#define BT_LE_DATA_LEN_PARAM_MAX
 
#define BT_CONN_ROLE_MASTER   __DEPRECATED_MACRO BT_CONN_ROLE_CENTRAL
 
#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. More...
 
#define BT_CONN_LE_CREATE_PARAM(_options, _interval, _window)
 
#define BT_CONN_LE_CREATE_CONN
 
#define BT_CONN_LE_CREATE_CONN_AUTO
 
#define BT_CONN_CB_DEFINE(_name)
 Register a callback structure for connection events. More...
 
#define BT_PASSKEY_INVALID   0xffffffff
 
#define BT_BR_CONN_PARAM_INIT(role_switch)
 Initialize BR/EDR connection parameters. More...
 
#define BT_BR_CONN_PARAM(role_switch)
 
#define BT_BR_CONN_PARAM_DEFAULT   BT_BR_CONN_PARAM(true)
 

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) }
 
enum  {
  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
}
 
enum  { BT_CONN_ROLE_CENTRAL = 0 , BT_CONN_ROLE_PERIPHERAL = 1 }
 
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_OPT_NONE = 0 , BT_CONN_LE_OPT_CODED = BIT(0) , BT_CONN_LE_OPT_NO_1M = BIT(1) }
 
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)
}
 
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_UNSPECIFIED
}
 

Functions

struct bt_conn * bt_conn_ref (struct bt_conn *conn)
 Increment a connection's reference count. More...
 
void bt_conn_unref (struct bt_conn *conn)
 Decrement a connection's reference count. More...
 
void bt_conn_foreach (int type, void(*func)(struct bt_conn *conn, void *data), void *data)
 Iterate through all existing connections. More...
 
struct bt_conn * bt_conn_lookup_addr_le (uint8_t id, const bt_addr_le_t *peer)
 Look up an existing connection by address. More...
 
const bt_addr_le_tbt_conn_get_dst (const struct bt_conn *conn)
 Get destination (peer) address of a connection. More...
 
uint8_t bt_conn_index (struct bt_conn *conn)
 Get array index of a connection. More...
 
int bt_conn_get_info (const struct bt_conn *conn, struct bt_conn_info *info)
 Get connection info. More...
 
int bt_conn_get_remote_info (struct bt_conn *conn, struct bt_conn_remote_info *remote_info)
 Get connection info for the remote device. More...
 
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. More...
 
int bt_conn_le_param_update (struct bt_conn *conn, const struct bt_le_conn_param *param)
 Update the connection parameters. More...
 
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. More...
 
int bt_conn_le_phy_update (struct bt_conn *conn, const struct bt_conn_le_phy_param *param)
 Update the connection PHY parameters. More...
 
int bt_conn_disconnect (struct bt_conn *conn, uint8_t reason)
 Disconnect from a remote device or cancel pending connection. More...
 
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. More...
 
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.. More...
 
int bt_conn_create_auto_stop (void)
 Stop automatic connect creation. More...
 
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. More...
 
int bt_conn_set_security (struct bt_conn *conn, bt_security_t sec)
 Set security level for a connection. More...
 
bt_security_t bt_conn_get_security (struct bt_conn *conn)
 Get security level for a connection. More...
 
uint8_t bt_conn_enc_key_size (struct bt_conn *conn)
 Get encryption key size. More...
 
void bt_conn_cb_register (struct bt_conn_cb *cb)
 Register connection callbacks. More...
 
void bt_set_bondable (bool enable)
 Enable/disable bonding. More...
 
void bt_set_oob_data_flag (bool enable)
 Allow/disallow remote OOB data to be used for pairing. More...
 
int bt_le_oob_set_legacy_tk (struct bt_conn *conn, const uint8_t *tk)
 Set OOB Temporary Key to be used for pairing. More...
 
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. More...
 
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. More...
 
int bt_passkey_set (unsigned int passkey)
 Set a fixed passkey to be used for pairing. More...
 
int bt_conn_auth_cb_register (const struct bt_conn_auth_cb *cb)
 Register authentication callbacks. More...
 
int bt_conn_auth_passkey_entry (struct bt_conn *conn, unsigned int passkey)
 Reply with entered passkey. More...
 
int bt_conn_auth_cancel (struct bt_conn *conn)
 Cancel ongoing authenticated pairing. More...
 
int bt_conn_auth_passkey_confirm (struct bt_conn *conn)
 Reply if passkey was confirmed to match by user. More...
 
int bt_conn_auth_pairing_confirm (struct bt_conn *conn)
 Reply if incoming pairing was confirmed by user. More...
 
int bt_conn_auth_pincode_entry (struct bt_conn *conn, const char *pin)
 Reply with entered PIN code. More...
 
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. More...
 
struct bt_conn * bt_conn_create_sco (const bt_addr_t *peer)
 Initiate an SCO connection to a remote device. More...
 

Detailed Description

Connection management.

Macro Definition Documentation

◆ BT_BR_CONN_PARAM

#define BT_BR_CONN_PARAM (   role_switch)

#include <include/bluetooth/conn.h>

Value:
((struct bt_br_conn_param[]) { \
BT_BR_CONN_PARAM_INIT(role_switch) \
})
Definition: conn.h:1381

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 <include/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 <include/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 <include/bluetooth/conn.h>

Value:
_CONCAT(bt_conn_cb_, \
_name))
#define STRUCT_SECTION_ITERABLE(struct_type, name)
Defines a new iterable section.
Definition: common.h:199
Connection callback structure.
Definition: conn.h:768

Register a callback structure for connection events.

Parameters
_nameName of callback structure.

◆ BT_CONN_LE_CREATE_CONN

#define BT_CONN_LE_CREATE_CONN

#include <include/bluetooth/conn.h>

Value:
#define BT_CONN_LE_CREATE_PARAM(_options, _interval, _window)
Definition: conn.h:575
@ BT_CONN_LE_OPT_NONE
Definition: conn.h:503
#define BT_GAP_SCAN_FAST_INTERVAL
Definition: gap.h:67

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 <include/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 <include/bluetooth/conn.h>

Value:
((struct bt_conn_le_create_param[]) { \
BT_CONN_LE_CREATE_PARAM_INIT(_options, _interval, _window) \
})
Definition: conn.h:520

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 <include/bluetooth/conn.h>

Value:
{ \
.options = (_options), \
.interval = (_interval), \
.window = (_window), \
.interval_coded = 0, \
.window_coded = 0, \
.timeout = 0, \
}
ZTEST_BMEM int timeout
Definition: main.c:31

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 <include/bluetooth/conn.h>

Value:
((struct bt_conn_le_data_len_param[]) { \
BT_CONN_LE_DATA_LEN_PARAM_INIT(_tx_max_len, _tx_max_time) \
})
Definition: conn.h:158

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 <include/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 <include/bluetooth/conn.h>

Value:
((struct bt_conn_le_phy_param []) { \
BT_CONN_LE_PHY_PARAM_INIT(_pref_tx_phy, _pref_rx_phy) \
})
Definition: conn.h:97

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 <include/bluetooth/conn.h>

Value:
#define BT_CONN_LE_PHY_PARAM(_pref_tx_phy, _pref_rx_phy)
Definition: conn.h:120
@ BT_GAP_LE_PHY_1M
Definition: gap.h:93

Only LE 1M PHY

◆ BT_CONN_LE_PHY_PARAM_2M

#define BT_CONN_LE_PHY_PARAM_2M

#include <include/bluetooth/conn.h>

Value:
@ BT_GAP_LE_PHY_2M
Definition: gap.h:95

Only LE 2M PHY

◆ BT_CONN_LE_PHY_PARAM_ALL

#define BT_CONN_LE_PHY_PARAM_ALL

◆ 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 <include/bluetooth/conn.h>

Value:
{ \
.pref_tx_phy = (_pref_tx_phy), \
.pref_rx_phy = (_pref_rx_phy), \
}
@ BT_CONN_LE_PHY_OPT_NONE
Definition: conn.h:87

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 <include/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 <include/bluetooth/conn.h>

Value:
((struct bt_le_conn_param[]) { \
BT_LE_CONN_PARAM_INIT(int_min, int_max, lat, to) \
})
Definition: conn.h:35

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 <include/bluetooth/conn.h>

Value:
0, 400)
#define BT_LE_CONN_PARAM(int_min, int_max, lat, to)
Definition: conn.h:64
#define BT_GAP_INIT_CONN_INT_MAX
Definition: gap.h:86
#define BT_GAP_INIT_CONN_INT_MIN
Definition: gap.h:85

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 <include/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 <include/bluetooth/conn.h>

Value:
#define BT_CONN_LE_DATA_LEN_PARAM(_tx_max_len, _tx_max_time)
Definition: conn.h:181
#define BT_GAP_DATA_TIME_DEFAULT
Definition: gap.h:152
#define BT_GAP_DATA_LEN_DEFAULT
Definition: gap.h:149

Default LE data length parameters.

◆ BT_LE_DATA_LEN_PARAM_MAX

#define BT_LE_DATA_LEN_PARAM_MAX

#include <include/bluetooth/conn.h>

Value:
#define BT_GAP_DATA_TIME_MAX
Definition: gap.h:153
#define BT_GAP_DATA_LEN_MAX
Definition: gap.h:150

Maximum LE data length parameters.

◆ BT_PASSKEY_INVALID

#define BT_PASSKEY_INVALID   0xffffffff

#include <include/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 <include/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 <include/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

◆ anonymous enum

anonymous enum

#include <include/bluetooth/conn.h>

Enumerator
BT_CONN_ROLE_CENTRAL 
BT_CONN_ROLE_PERIPHERAL 

◆ anonymous enum

anonymous enum

#include <include/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_le_tx_power_phy

#include <include/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_security_err

#include <include/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_UNSPECIFIED 

Pairing failed but the exact reason could not be specified.

◆ bt_security_t

#include <include/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 <include/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_register()

int bt_conn_auth_cb_register ( const struct bt_conn_auth_cb cb)

#include <include/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_pairing_confirm()

int bt_conn_auth_pairing_confirm ( struct bt_conn *  conn)

#include <include/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 <include/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 <include/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 <include/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()

void bt_conn_cb_register ( struct bt_conn_cb cb)

#include <include/bluetooth/conn.h>

Register connection callbacks.

Register callbacks to monitor the state of connections.

Parameters
cbCallback struct. Must point to memory that remains valid.

◆ bt_conn_create_auto_stop()

int bt_conn_create_auto_stop ( void  )

#include <include/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 <include/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_create_sco()

struct bt_conn * bt_conn_create_sco ( const bt_addr_t peer)

#include <include/bluetooth/conn.h>

Initiate an SCO connection to a remote device.

Allows initiate new SCO 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.
Returns
Valid connection object on success or NULL otherwise.

◆ bt_conn_disconnect()

int bt_conn_disconnect ( struct bt_conn *  conn,
uint8_t  reason 
)

#include <include/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 ( struct bt_conn *  conn)

#include <include/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 ( int  type,
void(*)(struct bt_conn *conn, void *data func,
void data 
)

#include <include/bluetooth/conn.h>

Iterate through all existing connections.

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 <include/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 <include/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 <include/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)
embed:rst:inline :kconfig:`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 ( struct bt_conn *  conn)

#include <include/bluetooth/conn.h>

Get security level for a connection.

Returns
Connection security level

◆ bt_conn_index()

uint8_t bt_conn_index ( struct bt_conn *  conn)

#include <include/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 <include/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.

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 <include/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_data_len_update()

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

#include <include/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_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 <include/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 <include/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

embed:rst:inline :kconfig:`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 <include/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_lookup_addr_le()

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

#include <include/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 <include/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_security()

int bt_conn_set_security ( struct bt_conn *  conn,
bt_security_t  sec 
)

#include <include/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. 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 error if required level of security 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 error if the pairing procedure has already been initiated by the local device or the peer device.

Note
When
embed:rst:inline :kconfig:`CONFIG_BT_SMP_SC_ONLY` 
is enabled then the security level will always be level 4.
When
embed:rst:inline :kconfig:`CONFIG_BT_SMP_OOB_LEGACY_PAIR_ONLY` 
is enabled then the security level will always be level 3.
Parameters
connConnection object.
secRequested security level.
Returns
0 on success or negative error

◆ bt_conn_unref()

void bt_conn_unref ( struct bt_conn *  conn)

#include <include/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 <include/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_tk()

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

#include <include/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 <include/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_set_auto_conn()

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

#include <include/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 <include/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_confim() 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_set_bondable()

void bt_set_bondable ( bool  enable)

#include <include/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.

◆ bt_set_oob_data_flag()

void bt_set_oob_data_flag ( bool  enable)

#include <include/bluetooth/conn.h>

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

Set/clear the OOB data flag for SMP Pairing Request/Response data. The initial value of this flag depends on BT_OOB_DATA_PRESENT Kconfig setting.

Parameters
enableValue allowing/disallowing remote OOB data.