Connection Management¶
The Zephyr Bluetooth stack uses an abstraction called bt_conn
to represent connections to other devices. The internals of this struct
are not exposed to the application, but a limited amount of information
(such as the remote address) can be acquired using the
bt_conn_get_info()
API. Connection objects are reference
counted, and the application is expected to use the
bt_conn_ref()
API whenever storing a connection pointer for a
longer period of time, since this ensures that the object remains valid
(even if the connection would get disconnected). Similarly the
bt_conn_unref()
API is to be used when releasing a reference
to a connection.
An application may track connections by registering a
bt_conn_cb
struct using the bt_conn_cb_register()
API. This struct lets the application define callbacks for connection &
disconnection events, as well as other events related to a connection
such as a change in the security level or the connection parameters.
When acting as a central the application will also get hold of the
connection object through the return value of the
bt_conn_create_le()
API.
API Reference¶
-
group
bt_conn
Connection management.
Defines
-
BT_LE_CONN_PARAM_INIT
(int_min, int_max, lat, to)¶ Initialize connection parameters.
- Parameters
int_min
: Minimum Connection Interval (N * 1.25 ms)int_max
: Maximum Connection Interval (N * 1.25 ms)lat
: Connection Latencyto
: Supervision Timeout (N * 10 ms)
-
BT_LE_CONN_PARAM
(int_min, int_max, lat, to)¶ Helper to declare connection parameters inline
- Parameters
int_min
: Minimum Connection Interval (N * 1.25 ms)int_max
: Maximum Connection Interval (N * 1.25 ms)lat
: Connection Latencyto
: Supervision Timeout (N * 10 ms)
-
BT_LE_CONN_PARAM_DEFAULT
¶ Default LE connection parameters: Connection Interval: 30-50 ms Latency: 0 Timeout: 4 s
-
BT_CONN_LE_PHY_PARAM_INIT
(_pref_tx_phy, _pref_rx_phy)¶ Initialize PHY parameters
- Parameters
_pref_tx_phy
: Bitmask of preferred transmit PHYs._pref_rx_phy
: Bitmask of preferred receive PHYs.
-
BT_CONN_LE_PHY_PARAM
(_pref_tx_phy, _pref_rx_phy)¶ Helper to declare PHY parameters inline
- Parameters
_pref_tx_phy
: Bitmask of preferred transmit PHYs._pref_rx_phy
: Bitmask of preferred receive PHYs.
-
BT_CONN_LE_PHY_PARAM_1M
¶ Only LE 1M PHY
-
BT_CONN_LE_PHY_PARAM_2M
¶ Only LE 2M PHY
-
BT_CONN_LE_PHY_PARAM_CODED
¶ Only LE Coded PHY.
-
BT_CONN_LE_PHY_PARAM_ALL
¶ All LE PHYs.
-
BT_CONN_LE_DATA_LEN_PARAM_INIT
(_tx_max_len, _tx_max_time)¶ Initialize transmit data length parameters
- Parameters
_tx_max_len
: Maximum Link Layer transmission payload size in bytes._tx_max_time
: Maximum Link Layer transmission payload time in us.
-
BT_CONN_LE_DATA_LEN_PARAM
(_tx_max_len, _tx_max_time)¶ Helper to declare transmit data length parameters inline
- Parameters
_tx_max_len
: Maximum Link Layer transmission payload size in bytes._tx_max_time
: Maximum Link Layer transmission payload time in us.
-
BT_LE_DATA_LEN_PARAM_DEFAULT
¶ Default LE data length parameters.
-
BT_LE_DATA_LEN_PARAM_MAX
¶ Maximum LE data length parameters.
-
BT_CONN_LE_CREATE_PARAM_INIT
(_options, _interval, _window)¶ Initialize create connection parameters.
- Parameters
_options
: Create connection options._interval
: Create connection scan interval (N * 0.625 ms)._window
: Create connection scan window (N * 0.625 ms).
-
BT_CONN_LE_CREATE_PARAM
(_options, _interval, _window)¶ Helper to declare create connection parameters inline
- Parameters
_options
: Create connection options._interval
: Create connection scan interval (N * 0.625 ms)._window
: Create connection scan window (N * 0.625 ms).
-
BT_CONN_LE_CREATE_CONN
¶ Default LE create connection parameters. Scan continuously by setting scan interval equal to scan window.
-
BT_CONN_LE_CREATE_CONN_AUTO
¶ Default LE create connection using whitelist parameters. Scan window: 30 ms. Scan interval: 60 ms.
-
BT_PASSKEY_INVALID
¶ Special passkey value that can be used to disable a previously set fixed passkey.
-
BT_BR_CONN_PARAM_INIT
(role_switch)¶ Initialize BR/EDR connection parameters.
- Parameters
role_switch
: True if role switch is allowed
-
BT_BR_CONN_PARAM
(role_switch)¶ Helper to declare BR/EDR connection parameters inline
- Parameters
role_switch
: True if role switch is allowed
-
BT_BR_CONN_PARAM_DEFAULT
¶ Default BR/EDR connection parameters: Role switch allowed
Enums
-
enum [anonymous]¶
Connection PHY options
Values:
-
enumerator
BT_CONN_LE_PHY_OPT_NONE
¶ Convenience value when no options are specified.
-
enumerator
BT_CONN_LE_PHY_OPT_CODED_S2
¶ LE Coded using S=2 coding preferred when transmitting.
-
enumerator
BT_CONN_LE_PHY_OPT_CODED_S8
¶ LE Coded using S=8 coding preferred when transmitting.
-
enumerator
-
enum [anonymous]¶
Connection Type
Values:
-
enumerator
BT_CONN_TYPE_LE
¶ LE Connection Type
-
enumerator
BT_CONN_TYPE_BR
¶ BR/EDR Connection Type
-
enumerator
BT_CONN_TYPE_SCO
¶ SCO Connection Type
-
enumerator
BT_CONN_TYPE_ISO
¶ ISO Connection Type
-
enumerator
BT_CONN_TYPE_ALL
¶ All Connection Type
-
enumerator
-
enum [anonymous]¶
Connection role (master or slave)
Values:
-
enumerator
BT_CONN_ROLE_MASTER
¶
-
enumerator
BT_CONN_ROLE_SLAVE
¶
-
enumerator
-
enum
bt_conn_le_tx_power_phy
¶ Values:
-
enumerator
BT_CONN_LE_TX_POWER_PHY_NONE
¶ Convenience macro for when no PHY is set.
-
enumerator
BT_CONN_LE_TX_POWER_PHY_1M
¶ LE 1M PHY
-
enumerator
BT_CONN_LE_TX_POWER_PHY_2M
¶ LE 2M PHY
-
enumerator
BT_CONN_LE_TX_POWER_PHY_CODED_S8
¶ LE Coded PHY using S=8 coding.
-
enumerator
BT_CONN_LE_TX_POWER_PHY_CODED_S2
¶ LE Coded PHY using S=2 coding.
-
enumerator
-
enum [anonymous]¶
Values:
-
enumerator
BT_CONN_LE_OPT_NONE
¶ Convenience value when no options are specified.
-
enumerator
BT_CONN_LE_OPT_CODED
¶ Enable LE Coded PHY.
Enable scanning on the LE Coded PHY.
-
enumerator
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.
-
enumerator
-
enum
bt_security_t
¶ Security level.
Values:
-
enumerator
BT_SECURITY_L0
¶ Level 0: Only for BR/EDR special cases, like SDP
-
enumerator
BT_SECURITY_L1
¶ Level 1: No encryption and no authentication.
-
enumerator
BT_SECURITY_L2
¶ Level 2: Encryption and no authentication (no MITM).
-
enumerator
BT_SECURITY_L3
¶ Level 3: Encryption and authentication (MITM).
-
enumerator
BT_SECURITY_L4
¶ Level 4: Authenticated Secure Connections and 128-bit key.
-
enumerator
BT_SECURITY_NONE
¶
-
enumerator
BT_SECURITY_LOW
¶
-
enumerator
BT_SECURITY_MEDIUM
¶
-
enumerator
BT_SECURITY_HIGH
¶
-
enumerator
BT_SECURITY_FIPS
¶
-
enumerator
BT_SECURITY_FORCE_PAIR
¶ Bit to force new pairing procedure, bit-wise OR with requested security level.
-
enumerator
-
enum
bt_security_err
¶ Values:
-
enumerator
BT_SECURITY_ERR_SUCCESS
¶ Security procedure successful.
-
enumerator
BT_SECURITY_ERR_AUTH_FAIL
¶ Authentication failed.
-
enumerator
BT_SECURITY_ERR_PIN_OR_KEY_MISSING
¶ PIN or encryption key is missing.
-
enumerator
BT_SECURITY_ERR_OOB_NOT_AVAILABLE
¶ OOB data is not available.
-
enumerator
BT_SECURITY_ERR_AUTH_REQUIREMENT
¶ The requested security level could not be reached.
-
enumerator
BT_SECURITY_ERR_PAIR_NOT_SUPPORTED
¶ Pairing is not supported
-
enumerator
BT_SECURITY_ERR_PAIR_NOT_ALLOWED
¶ Pairing is not allowed.
-
enumerator
BT_SECURITY_ERR_INVALID_PARAM
¶ Invalid parameters.
-
enumerator
BT_SECURITY_ERR_UNSPECIFIED
¶ Pairing failed but the exact reason could not be specified.
-
enumerator
Functions
-
struct bt_conn *
bt_conn_ref
(struct bt_conn *conn)¶ Increment a connection’s reference count.
Increment the reference count of a connection object.
- Note
Will return NULL if the reference count is zero.
- Return
Connection object with incremented reference count, or NULL if the reference count is zero.
- Parameters
conn
: Connection object.
-
void
bt_conn_unref
(struct bt_conn *conn)¶ Decrement a connection’s reference count.
Decrement the reference count of a connection object.
- Parameters
conn
: Connection object.
-
void
bt_conn_foreach
(int type, void (*func)(struct bt_conn *conn, void *data), void *data, )¶ Iterate through all existing connections.
- Parameters
type
: Connection Typefunc
: Function to call for each connection.data
: Data to pass to the callback function.
-
struct bt_conn *
bt_conn_lookup_addr_le
(uint8_t id, const bt_addr_le_t *peer)¶ Look up an existing connection by address.
Look up an existing connection based on the remote address.
The caller gets a new reference to the connection object which must be released with bt_conn_unref() once done using the object.
- Return
Connection object or NULL if not found.
- Parameters
id
: Local identity (in most cases BT_ID_DEFAULT).peer
: Remote address.
-
const bt_addr_le_t *
bt_conn_get_dst
(const struct bt_conn *conn)¶ Get destination (peer) address of a connection.
- Return
Destination address.
- Parameters
conn
: Connection object.
-
uint8_t
bt_conn_index
(struct bt_conn *conn)¶ Get array index of a connection.
This function is used to map bt_conn to index of an array of connections. The array has CONFIG_BT_MAX_CONN elements.
- Return
Index of the connection object. The range of the returned value is 0..CONFIG_BT_MAX_CONN-1
- Parameters
conn
: Connection object.
-
int
bt_conn_get_info
(const struct bt_conn *conn, struct bt_conn_info *info)¶ Get connection info.
- Return
Zero on success or (negative) error code on failure.
- Parameters
conn
: Connection object.info
: Connection info object.
-
int
bt_conn_get_remote_info
(struct bt_conn *conn, struct bt_conn_remote_info *remote_info)¶ Get connection info for the remote device.
- Note
In order to retrieve the remote version (version, manufacturer and subversion)
CONFIG_BT_REMOTE_VERSION
must be enabled- Note
The remote information is exchanged directly after the connection has been established. The application can be notified about when the remote information is available through the remote_info_available callback.
- Return
Zero on success or (negative) error code on failure.
- Return
-EBUSY The remote information is not yet available.
- Parameters
conn
: Connection object.remote_info
: Connection remote info object.
-
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.
- Return
Zero on success or (negative) error code on failure.
- Return
-ENOBUFS HCI command buffer is not available.
- Parameters
conn
: Connection object.tx_power_level
: Transmit power level descriptor.
-
int
bt_conn_le_param_update
(struct bt_conn *conn, const struct bt_le_conn_param *param)¶ Update the connection parameters.
If the local device is in the peripheral role then updating the connection parameters will be delayed. This delay can be configured by through the
CONFIG_BT_CONN_PARAM_UPDATE_TIMEOUT
option.- Return
Zero on success or (negative) error code on failure.
- Parameters
conn
: Connection object.param
: Updated 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.
- Return
Zero on success or (negative) error code on failure.
- Parameters
conn
: Connection object.param
: Updated 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.
Update the preferred transmit and receive PHYs of the connection. Use BT_GAP_LE_PHY_NONE to indicate no preference.
- Return
Zero on success or (negative) error code on failure.
- Parameters
conn
: Connection object.param
: Updated connection parameters.
-
int
bt_conn_disconnect
(struct bt_conn *conn, uint8_t reason)¶ Disconnect from a remote device or cancel pending connection.
Disconnect an active connection with the specified reason code or cancel pending outgoing connection.
The disconnect reason for a normal disconnect should be: BT_HCI_ERR_REMOTE_USER_TERM_CONN.
The following disconnect reasons are accepted:
BT_HCI_ERR_AUTH_FAIL
BT_HCI_ERR_REMOTE_USER_TERM_CONN
BT_HCI_ERR_REMOTE_LOW_RESOURCES
BT_HCI_ERR_REMOTE_POWER_OFF
BT_HCI_ERR_UNSUPP_REMOTE_FEATURE
BT_HCI_ERR_PAIRING_NOT_SUPPORTED
BT_HCI_ERR_UNACCEPT_CONN_PARAM
- Return
Zero on success or (negative) error code on failure.
- Parameters
conn
: Connection to disconnect.reason
: Reason code for the disconnection.
-
int
bt_conn_le_create
(const bt_addr_le_t *peer, const struct bt_conn_le_create_param *create_param, const struct bt_le_conn_param *conn_param, struct bt_conn **conn)¶ Initiate an LE connection to a remote device.
Allows initiate new LE link to remote peer using its address.
The caller gets a new reference to the connection object which must be released with bt_conn_unref() once done using the object.
This uses the General Connection Establishment procedure.
- Return
Zero on success or (negative) error code on failure.
- Parameters
[in] peer
: Remote address.[in] create_param
: Create connection parameters.[in] conn_param
: Initial connection parameters.[out] conn
: Valid connection object on success.
-
static inline struct bt_conn *
bt_conn_create_le
(const bt_addr_le_t *peer, const struct bt_le_conn_param *conn_param)¶
-
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 whitelist.
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 whitelist the procedure should be started again in the connected callback after a new connection has been established.
- Return
Zero on success or (negative) error code on failure.
- Return
-ENOMEM No free connection object available.
- Parameters
create_param
: Create connection parametersconn_param
: Initial connection parameters.
-
static inline int
bt_conn_create_auto_le
(const struct bt_le_conn_param *conn_param)¶
-
int
bt_conn_create_auto_stop
(void)¶ Stop automatic connect creation.
- Return
Zero on success or (negative) error code on failure.
-
int
bt_le_set_auto_conn
(const bt_addr_le_t *addr, const struct bt_le_conn_param *param)¶ Automatically connect to remote device if it’s in range.
This function enables/disables automatic connection initiation. Every time the device loses the connection with peer, this connection will be re-established if connectable advertisement from peer is received.
- Note
Auto connect is disabled during explicit scanning.
- Return
Zero on success or error code otherwise.
- Parameters
addr
: Remote Bluetooth address.param
: If non-NULL, auto connect is enabled with the given parameters. If NULL, auto connect is disabled.
-
static inline struct bt_conn *
bt_conn_create_slave_le
(const bt_addr_le_t *peer, const struct bt_le_adv_param *param)¶ Initiate directed advertising to a remote device.
Allows initiating a new LE connection to remote peer with the remote acting in central role and the local device in peripheral role.
The advertising type will either be BT_LE_ADV_DIRECT_IND, or BT_LE_ADV_DIRECT_IND_LOW_DUTY if the BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY option was used as part of the advertising parameters.
In case of high duty cycle this will result in a callback with connected() with a new connection or with an error.
The advertising may be canceled with bt_conn_disconnect().
The caller gets a new reference to the connection object which must be released with bt_conn_unref() once done using the object.
- Return
Valid connection object on success or NULL otherwise.
- Parameters
peer
: Remote address.param
: Directed advertising parameters.
-
int
bt_conn_set_security
(struct bt_conn *conn, bt_security_t sec)¶ Set security level for a connection.
This function enable security (encryption) for a connection. If the device has bond information for the peer with sufficiently strong key encryption will be enabled. If the connection is already encrypted with sufficiently strong key this function does nothing.
If the device has no bond information for the peer and is not already paired then the pairing procedure will be initiated. 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
CONFIG_BT_SMP_SC_ONLY
is enabled then the security level will always be level 4.- Note
When
CONFIG_BT_SMP_OOB_LEGACY_PAIR_ONLY
is enabled then the security level will always be level 3.- Return
0 on success or negative error
- Parameters
conn
: Connection object.sec
: Requested security level.
-
bt_security_t
bt_conn_get_security
(struct bt_conn *conn)¶ Get security level for a connection.
- Return
Connection security level
-
static inline int
bt_conn_security
(struct bt_conn *conn, bt_security_t sec)¶
-
uint8_t
bt_conn_enc_key_size
(struct bt_conn *conn)¶ Get encryption key size.
This function gets encryption key size. If there is no security (encryption) enabled 0 will be returned.
- Return
Encryption key size.
- Parameters
conn
: Existing connection object.
-
void
bt_conn_cb_register
(struct bt_conn_cb *cb)¶ Register connection callbacks.
Register callbacks to monitor the state of connections.
- Parameters
cb
: Callback struct. Must point to memory that remains valid.
-
void
bt_set_bondable
(bool enable)¶ Enable/disable bonding.
Set/clear the Bonding flag in the Authentication Requirements of SMP Pairing Request/Response data. The initial value of this flag depends on BT_BONDABLE Kconfig setting. For the vast majority of applications calling this function shouldn’t be needed.
- Parameters
enable
: Value allowing/disallowing to be bondable.
-
void
bt_set_oob_data_flag
(bool enable)¶ 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
enable
: Value allowing/disallowing remote OOB data.
-
int
bt_le_oob_set_legacy_tk
(struct bt_conn *conn, const uint8_t *tk)¶ Set OOB Temporary Key to be used for pairing.
This function allows to set OOB data for the LE legacy pairing procedure. The function should only be called in response to the oob_data_request() callback provided that the legacy method is user pairing.
- Return
Zero on success or -EINVAL if NULL
- Parameters
conn
: Connection objecttk
: Pointer to 16 byte long TK array
-
int
bt_le_oob_set_sc_data
(struct bt_conn *conn, const struct bt_le_oob_sc_data *oobd_local, const struct bt_le_oob_sc_data *oobd_remote)¶ Set OOB data during LE Secure Connections (SC) pairing procedure.
This function allows to set OOB data during the LE SC pairing procedure. The function should only be called in response to the oob_data_request() callback provided that LE SC method is used for pairing.
The user should submit OOB data according to the information received in the callback. This may yield three different configurations: with only local OOB data present, with only remote OOB data present or with both local and remote OOB data present.
- Return
Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error.
- Parameters
conn
: Connection objectoobd_local
: Local OOB data or NULL if not presentoobd_remote
: Remote OOB data or NULL if not present
-
int
bt_le_oob_get_sc_data
(struct bt_conn *conn, const struct bt_le_oob_sc_data **oobd_local, const struct bt_le_oob_sc_data **oobd_remote)¶ Get OOB data used for LE Secure Connections (SC) pairing procedure.
This function allows to get OOB data during the LE SC pairing procedure that were set by the bt_le_oob_set_sc_data() API.
- Note
The OOB data will only be available as long as the connection object associated with it is valid.
- Return
Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error.
- Parameters
conn
: Connection objectoobd_local
: Local OOB data or NULL if not setoobd_remote
: Remote OOB data or NULL if not set
-
int
bt_passkey_set
(unsigned int passkey)¶ Set a fixed passkey to be used for pairing.
This API is only available when the CONFIG_BT_FIXED_PASSKEY configuration option has been enabled.
Sets a fixed passkey to be used for pairing. If set, the pairing_confim() callback will be called for all incoming pairings.
- Return
0 on success or a negative error code on failure.
- Parameters
passkey
: A valid passkey (0 - 999999) or BT_PASSKEY_INVALID to disable a previously set fixed passkey.
-
int
bt_conn_auth_cb_register
(const struct bt_conn_auth_cb *cb)¶ Register authentication callbacks.
Register callbacks to handle authenticated pairing. Passing NULL unregisters a previous callbacks structure.
- Return
Zero on success or negative error code otherwise
- Parameters
cb
: Callback struct.
-
int
bt_conn_auth_passkey_entry
(struct bt_conn *conn, unsigned int passkey)¶ Reply with entered passkey.
This function should be called only after passkey_entry callback from bt_conn_auth_cb structure was called.
- Return
Zero on success or negative error code otherwise
- Parameters
conn
: Connection object.passkey
: Entered passkey.
-
int
bt_conn_auth_cancel
(struct bt_conn *conn)¶ Cancel ongoing authenticated pairing.
This function allows to cancel ongoing authenticated pairing.
- Return
Zero on success or negative error code otherwise
- Parameters
conn
: Connection object.
-
int
bt_conn_auth_passkey_confirm
(struct bt_conn *conn)¶ Reply if passkey was confirmed to match by user.
This function should be called only after passkey_confirm callback from bt_conn_auth_cb structure was called.
- Return
Zero on success or negative error code otherwise
- Parameters
conn
: Connection object.
-
int
bt_conn_auth_pairing_confirm
(struct bt_conn *conn)¶ Reply if incoming pairing was confirmed by user.
This function should be called only after pairing_confirm callback from bt_conn_auth_cb structure was called if user confirmed incoming pairing.
- Return
Zero on success or negative error code otherwise
- Parameters
conn
: Connection object.
-
int
bt_conn_auth_pincode_entry
(struct bt_conn *conn, const char *pin)¶ Reply with entered PIN code.
This function should be called only after PIN code callback from bt_conn_auth_cb structure was called. It’s for legacy 2.0 devices.
- Return
Zero on success or negative error code otherwise
- Parameters
conn
: Connection object.pin
: Entered PIN code.
-
struct bt_conn *
bt_conn_create_br
(const bt_addr_t *peer, const struct bt_br_conn_param *param)¶ Initiate an BR/EDR connection to a remote device.
Allows initiate new BR/EDR link to remote peer using its address.
The caller gets a new reference to the connection object which must be released with bt_conn_unref() once done using the object.
- Return
Valid connection object on success or NULL otherwise.
- Parameters
peer
: Remote address.param
: Initial connection parameters.
-
struct bt_conn *
bt_conn_create_sco
(const bt_addr_t *peer)¶ Initiate an SCO connection to a remote device.
Allows initiate new SCO link to remote peer using its address.
The caller gets a new reference to the connection object which must be released with bt_conn_unref() once done using the object.
- Return
Valid connection object on success or NULL otherwise.
- Parameters
peer
: Remote address.
-
struct
bt_le_conn_param
¶ - #include <conn.h>
Connection parameters for LE connections
-
struct
bt_conn_le_phy_info
¶ - #include <conn.h>
Connection PHY information for LE connections
Public Members
-
uint8_t
rx_phy
¶ Connection transmit PHY
-
uint8_t
-
struct
bt_conn_le_phy_param
¶ - #include <conn.h>
Preferred PHY parameters for LE connections
-
struct
bt_conn_le_data_len_info
¶ - #include <conn.h>
Connection data length information for LE connections
Public Members
-
uint16_t
tx_max_len
¶ Maximum Link Layer transmission payload size in bytes.
-
uint16_t
tx_max_time
¶ Maximum Link Layer transmission payload time in us.
-
uint16_t
rx_max_len
¶ Maximum Link Layer reception payload size in bytes.
-
uint16_t
rx_max_time
¶ Maximum Link Layer reception payload time in us.
-
uint16_t
-
struct
bt_conn_le_data_len_param
¶ - #include <conn.h>
Connection data length parameters for LE connections
-
struct
bt_conn_le_info
¶ - #include <conn.h>
LE Connection Info Structure
Public Members
-
const bt_addr_le_t *
src
¶ Source (Local) Identity Address
-
const bt_addr_le_t *
dst
¶ Destination (Remote) Identity Address or remote Resolvable Private Address (RPA) before identity has been resolved.
-
const bt_addr_le_t *
local
¶ Local device address used during connection setup.
-
const bt_addr_le_t *
remote
¶ Remote device address used during connection setup.
-
uint16_t
latency
¶ Connection interval
-
uint16_t
timeout
¶ Connection slave latency
-
const struct bt_conn_le_phy_info *
phy
¶ Connection supervision timeout
-
const bt_addr_le_t *
-
struct
bt_conn_br_info
¶ - #include <conn.h>
BR/EDR Connection Info Structure
-
struct
bt_conn_info
¶ - #include <conn.h>
Connection Info Structure
Public Members
-
uint8_t
type
¶ Connection Type.
-
uint8_t
role
¶ Connection Role.
-
uint8_t
id
¶ Which local identity the connection was created with
-
union bt_conn_info.[anonymous] [anonymous]¶
Connection Type specific Info.
-
uint8_t
-
struct
bt_conn_le_remote_info
¶ - #include <conn.h>
LE Connection Remote Info Structure
Public Members
-
const uint8_t *
features
¶ Remote LE feature set (bitmask).
-
const uint8_t *
-
struct
bt_conn_br_remote_info
¶ - #include <conn.h>
BR/EDR Connection Remote Info structure
-
struct
bt_conn_remote_info
¶ - #include <conn.h>
Connection Remote Info Structure.
- Note
The version, manufacturer and subversion fields will only contain valid data if
CONFIG_BT_REMOTE_VERSION
is enabled.
-
struct
bt_conn_le_tx_power
¶ - #include <conn.h>
LE Transmit Power Level Structure
-
struct
bt_conn_le_create_param
¶ - #include <conn.h>
Public Members
-
uint32_t
options
¶ Bit-field of create connection options.
-
uint16_t
interval
¶ Scan interval (N * 0.625 ms)
-
uint16_t
window
¶ Scan window (N * 0.625 ms)
-
uint16_t
interval_coded
¶ Scan interval LE Coded PHY (N * 0.625 MS)
Set zero to use same as LE 1M PHY scan interval
-
uint16_t
window_coded
¶ Scan window LE Coded PHY (N * 0.625 MS)
Set zero to use same as LE 1M PHY scan window.
-
uint16_t
timeout
¶ Connection initiation timeout (N * 10 MS)
Set zero to use the default
CONFIG_BT_CREATE_CONN_TIMEOUT
timeout.- Note
Unused in bt_conn_create_auto_le
-
uint32_t
-
struct
bt_conn_cb
¶ - #include <conn.h>
Connection callback structure.
This structure is used for tracking the state of a connection. It is registered with the help of the bt_conn_cb_register() API. It’s permissible to register multiple instances of this bt_conn_cb type, in case different modules of an application are interested in tracking the connection state. If a callback is not of interest for an instance, it may be set to NULL and will as a consequence not be used for that instance.
Public Members
-
void (*
connected
)(struct bt_conn *conn, uint8_t err)¶ A new connection has been established.
This callback notifies the application of a new connection. In case the err parameter is non-zero it means that the connection establishment failed.
err
can mean either of the following:BT_HCI_ERR_UNKNOWN_CONN_ID Creating the connection started by bt_conn_create_le was canceled either by the user through bt_conn_disconnect or by the timeout in the host through bt_conn_le_create_param timeout parameter, which defaults to
CONFIG_BT_CREATE_CONN_TIMEOUT
seconds.BT_HCI_ERR_ADV_TIMEOUT
High duty cycle directed connectable advertiser started by bt_le_adv_start failed to be connected within the timeout.
- Parameters
conn
: New connection object.err
: HCI error. Zero for success, non-zero otherwise.
-
void (*
disconnected
)(struct bt_conn *conn, uint8_t reason)¶ A connection has been disconnected.
This callback notifies the application that a connection has been disconnected.
When this callback is called the stack still has one reference to the connection object. If the application in this callback tries to start either a connectable advertiser or create a new connection this might fail because there are no free connection objects available. To avoid this issue it is recommended to either start connectable advertise or create a new connection using k_work_submit or increase
CONFIG_BT_MAX_CONN
.- Parameters
conn
: Connection object.reason
: HCI reason for the disconnection.
-
bool (*
le_param_req
)(struct bt_conn *conn, struct bt_le_conn_param *param)¶ LE connection parameter update request.
This callback notifies the application that a remote device is requesting to update the connection parameters. The application accepts the parameters by returning true, or rejects them by returning false. Before accepting, the application may also adjust the parameters to better suit its needs.
It is recommended for an application to have just one of these callbacks for simplicity. However, if an application registers multiple it needs to manage the potentially different requirements for each callback. Each callback gets the parameters as returned by previous callbacks, i.e. they are not necessarily the same ones as the remote originally sent.
- Return
true to accept the parameters, or false to reject them.
- Parameters
conn
: Connection object.param
: Proposed connection parameters.
-
void (*
le_param_updated
)(struct bt_conn *conn, uint16_t interval, uint16_t latency, uint16_t timeout)¶ The parameters for an LE connection have been updated.
This callback notifies the application that the connection parameters for an LE connection have been updated.
- Parameters
conn
: Connection object.interval
: Connection interval.latency
: Connection latency.timeout
: Connection supervision timeout.
-
void (*
identity_resolved
)(struct bt_conn *conn, const bt_addr_le_t *rpa, const bt_addr_le_t *identity)¶ Remote Identity Address has been resolved.
This callback notifies the application that a remote Identity Address has been resolved
- Parameters
conn
: Connection object.rpa
: Resolvable Private Address.identity
: Identity Address.
-
void (*
security_changed
)(struct bt_conn *conn, bt_security_t level, enum bt_security_err err)¶ The security level of a connection has changed.
This callback notifies the application that the security of a connection has changed.
The security level of the connection can either have been increased or remain unchanged. An increased security level means that the pairing procedure has been performed or the bond information from a previous connection has been applied. If the security level remains unchanged this means that the encryption key has been refreshed for the connection.
- Parameters
conn
: Connection object.level
: New security level of the connection.err
: Security error. Zero for success, non-zero otherwise.
-
void (*
remote_info_available
)(struct bt_conn *conn, struct bt_conn_remote_info *remote_info)¶ Remote information procedures has completed.
This callback notifies the application that the remote information has been retrieved from the remote peer.
- Parameters
conn
: Connection object.remote_info
: Connection information of remote device.
-
void (*
le_phy_updated
)(struct bt_conn *conn, struct bt_conn_le_phy_info *param)¶ The PHY of the connection has changed.
This callback notifies the application that the PHY of the connection has changed.
- Parameters
conn
: Connection object.info
: Connection LE PHY information.
-
void (*
le_data_len_updated
)(struct bt_conn *conn, struct bt_conn_le_data_len_info *info)¶ The data length parameters of the connection has changed.
This callback notifies the application that the maximum Link Layer payload length or transmission time has changed.
- Parameters
conn
: Connection object.info
: Connection data length information.
-
void (*
-
struct
bt_conn_oob_info
¶ - #include <conn.h>
Info Structure for OOB pairing
Public Types
Public Members
-
enum bt_conn_oob_info.[anonymous]
type
¶ Type of OOB pairing method
-
enum bt_conn_oob_info.[anonymous]
-
struct
bt_conn_pairing_feat
¶ - #include <conn.h>
Pairing request and pairing response info structure.
This structure is the same for both smp_pairing_req and smp_pairing_rsp and a subset of the packet data, except for the initial Code octet. It is documented in Core Spec. Vol. 3, Part H, 3.5.1 and 3.5.2.
Public Members
-
uint8_t
io_capability
¶ IO Capability, Core Spec. Vol 3, Part H, 3.5.1, Table 3.4
-
uint8_t
oob_data_flag
¶ OOB data flag, Core Spec. Vol 3, Part H, 3.5.1, Table 3.5
-
uint8_t
auth_req
¶ AuthReq, Core Spec. Vol 3, Part H, 3.5.1, Fig. 3.3
-
uint8_t
max_enc_key_size
¶ Maximum Encryption Key Size, Core Spec. Vol 3, Part H, 3.5.1
-
uint8_t
init_key_dist
¶ Initiator Key Distribution/Generation, Core Spec. Vol 3, Part H, 3.6.1, Fig. 3.11
-
uint8_t
resp_key_dist
¶ Responder Key Distribution/Generation, Core Spec. Vol 3, Part H 3.6.1, Fig. 3.11
-
uint8_t
-
struct
bt_conn_auth_cb
¶ - #include <conn.h>
Authenticated pairing callback structure
Public Members
-
enum bt_security_err (*
pairing_accept
)(struct bt_conn *conn, const struct bt_conn_pairing_feat *const feat)¶ Query to proceed incoming pairing or not.
On any incoming pairing req/rsp this callback will be called for the application to decide whether to allow for the pairing to continue.
The pairing info received from the peer is passed to assist making the decision.
As this callback is synchronous the application should return a response value immediately. Otherwise it may affect the timing during pairing. Hence, this information should not be conveyed to the user to take action.
The remaining callbacks are not affected by this, but do notice that other callbacks can be called during the pairing. Eg. if pairing_confirm is registered both will be called for Just-Works pairings.
This callback may be unregistered in which case pairing continues as if the Kconfig flag was not set.
This callback is not called for BR/EDR Secure Simple Pairing (SSP).
- Parameters
conn
: Connection where pairing is initiated.feat
: Pairing req/resp info.
-
void (*
passkey_display
)(struct bt_conn *conn, unsigned int passkey)¶ Display a passkey to the user.
When called the application is expected to display the given passkey to the user, with the expectation that the passkey will then be entered on the peer device. The passkey will be in the range of 0 - 999999, and is expected to be padded with zeroes so that six digits are always shown. E.g. the value 37 should be shown as 000037.
This callback may be set to NULL, which means that the local device lacks the ability do display a passkey. If set to non-NULL the cancel callback must also be provided, since this is the only way the application can find out that it should stop displaying the passkey.
- Parameters
conn
: Connection where pairing is currently active.passkey
: Passkey to show to the user.
-
void (*
passkey_entry
)(struct bt_conn *conn)¶ Request the user to enter a passkey.
When called the user is expected to enter a passkey. The passkey must be in the range of 0 - 999999, and should be expected to be zero-padded, as that’s how the peer device will typically be showing it (e.g. 37 would be shown as 000037).
Once the user has entered the passkey its value should be given to the stack using the bt_conn_auth_passkey_entry() API.
This callback may be set to NULL, which means that the local device lacks the ability to enter a passkey. If set to non-NULL the cancel callback must also be provided, since this is the only way the application can find out that it should stop requesting the user to enter a passkey.
- Parameters
conn
: Connection where pairing is currently active.
-
void (*
passkey_confirm
)(struct bt_conn *conn, unsigned int passkey)¶ Request the user to confirm a passkey.
When called the user is expected to confirm that the given passkey is also shown on the peer device.. The passkey will be in the range of 0 - 999999, and should be zero-padded to always be six digits (e.g. 37 would be shown as 000037).
Once the user has confirmed the passkey to match, the bt_conn_auth_passkey_confirm() API should be called. If the user concluded that the passkey doesn’t match the bt_conn_auth_cancel() API should be called.
This callback may be set to NULL, which means that the local device lacks the ability to confirm a passkey. If set to non-NULL the cancel callback must also be provided, since this is the only way the application can find out that it should stop requesting the user to confirm a passkey.
- Parameters
conn
: Connection where pairing is currently active.passkey
: Passkey to be confirmed.
-
void (*
oob_data_request
)(struct bt_conn *conn, struct bt_conn_oob_info *info)¶ Request the user to provide Out of Band (OOB) data.
When called the user is expected to provide OOB data. The required data are indicated by the information structure.
For LE Secure Connections OOB pairing, the user should provide local OOB data, remote OOB data or both depending on their availability. Their value should be given to the stack using the bt_le_oob_set_sc_data() API.
This callback must be set to non-NULL in order to support OOB pairing.
- Parameters
conn
: Connection where pairing is currently active.info
: OOB pairing information.
-
void (*
cancel
)(struct bt_conn *conn)¶ Cancel the ongoing user request.
This callback will be called to notify the application that it should cancel any previous user request (passkey display, entry or confirmation).
This may be set to NULL, but must always be provided whenever the passkey_display, passkey_entry passkey_confirm or pairing_confirm callback has been provided.
- Parameters
conn
: Connection where pairing is currently active.
-
void (*
pairing_confirm
)(struct bt_conn *conn)¶ Request confirmation for an incoming pairing.
This callback will be called to confirm an incoming pairing request where none of the other user callbacks is applicable.
If the user decides to accept the pairing the bt_conn_auth_pairing_confirm() API should be called. If the user decides to reject the pairing the bt_conn_auth_cancel() API should be called.
This callback may be set to NULL, which means that the local device lacks the ability to confirm a pairing request. If set to non-NULL the cancel callback must also be provided, since this is the only way the application can find out that it should stop requesting the user to confirm a pairing request.
- Parameters
conn
: Connection where pairing is currently active.
-
void (*
pincode_entry
)(struct bt_conn *conn, bool highsec)¶ Request the user to enter a passkey.
This callback will be called for a BR/EDR (Bluetooth Classic) connection where pairing is being performed. Once called the user is expected to enter a PIN code with a length between 1 and 16 digits. If the highsec parameter is set to true the PIN code must be 16 digits long.
Once entered, the PIN code should be given to the stack using the bt_conn_auth_pincode_entry() API.
This callback may be set to NULL, however in that case pairing over BR/EDR will not be possible. If provided, the cancel callback must be provided as well.
- Parameters
conn
: Connection where pairing is currently active.highsec
: true if 16 digit PIN is required.
-
void (*
pairing_complete
)(struct bt_conn *conn, bool bonded)¶ notify that pairing procedure was complete.
This callback notifies the application that the pairing procedure has been completed.
- Parameters
conn
: Connection object.bonded
: Bond information has been distributed during the pairing procedure.
-
void (*
pairing_failed
)(struct bt_conn *conn, enum bt_security_err reason)¶ notify that pairing process has failed.
- Parameters
conn
: Connection object.reason
: Pairing failed reason
-
void (*
bond_deleted
)(uint8_t id, const bt_addr_le_t *peer)¶ Notify that bond has been deleted.
This callback notifies the application that the bond information for the remote peer has been deleted
- Parameters
id
: Which local identity had the bond.peer
: Remote address.
-
enum bt_security_err (*
-
struct
bt_br_conn_param
¶ - #include <conn.h>
Connection parameters for BR/EDR connections
-