Connection Management
The Zephyr Bluetooth stack uses an abstraction called bt_conn
to represent connections to other devices. The internals of this struct
are not exposed to the application, but a limited amount of information
(such as the remote address) can be acquired using the
bt_conn_get_info()
API. Connection objects are reference
counted, and the application is expected to use the
bt_conn_ref()
API whenever storing a connection pointer for a
longer period of time, since this ensures that the object remains valid
(even if the connection would get disconnected). Similarly the
bt_conn_unref()
API is to be used when releasing a reference
to a connection.
An application may track connections by registering a
bt_conn_cb
struct using the bt_conn_cb_register()
or BT_CONN_CB_DEFINE
APIs. This struct lets the application
define callbacks for connection & disconnection events, as well as other
events related to a connection such as a change in the security level or
the connection parameters. When acting as a central the application will
also get hold of the connection object through the return value of the
bt_conn_le_create()
API.
API Reference
- group bt_conn
Connection management.
Defines
-
BT_LE_CONN_PARAM_INIT(int_min, int_max, lat, to)
Initialize connection parameters.
- Parameters:
int_min – Minimum Connection Interval (N * 1.25 ms)
int_max – Maximum Connection Interval (N * 1.25 ms)
lat – Connection Latency
to – Supervision Timeout (N * 10 ms)
-
BT_LE_CONN_PARAM(int_min, int_max, lat, to)
Helper to declare connection parameters inline.
- Parameters:
int_min – Minimum Connection Interval (N * 1.25 ms)
int_max – Maximum Connection Interval (N * 1.25 ms)
lat – Connection Latency
to – Supervision Timeout (N * 10 ms)
-
BT_LE_CONN_PARAM_DEFAULT
Default LE connection parameters: Connection Interval: 30-50 ms Latency: 0 Timeout: 4 s.
-
BT_CONN_LE_PHY_PARAM_INIT(_pref_tx_phy, _pref_rx_phy)
Initialize PHY parameters.
- Parameters:
_pref_tx_phy – Bitmask of preferred transmit PHYs.
_pref_rx_phy – Bitmask of preferred receive PHYs.
-
BT_CONN_LE_PHY_PARAM(_pref_tx_phy, _pref_rx_phy)
Helper to declare PHY parameters inline.
- Parameters:
_pref_tx_phy – Bitmask of preferred transmit PHYs.
_pref_rx_phy – Bitmask of preferred receive PHYs.
-
BT_CONN_LE_PHY_PARAM_1M
Only LE 1M PHY.
-
BT_CONN_LE_PHY_PARAM_2M
Only LE 2M PHY.
-
BT_CONN_LE_PHY_PARAM_CODED
Only LE Coded PHY.
-
BT_CONN_LE_PHY_PARAM_ALL
All LE PHYs.
-
BT_CONN_LE_DATA_LEN_PARAM_INIT(_tx_max_len, _tx_max_time)
Initialize transmit data length parameters.
- Parameters:
_tx_max_len – Maximum Link Layer transmission payload size in bytes.
_tx_max_time – Maximum Link Layer transmission payload time in us.
-
BT_CONN_LE_DATA_LEN_PARAM(_tx_max_len, _tx_max_time)
Helper to declare transmit data length parameters inline.
- Parameters:
_tx_max_len – Maximum Link Layer transmission payload size in bytes.
_tx_max_time – Maximum Link Layer transmission payload time in us.
-
BT_LE_DATA_LEN_PARAM_DEFAULT
Default LE data length parameters.
-
BT_LE_DATA_LEN_PARAM_MAX
Maximum LE data length parameters.
-
BT_CONN_INTERVAL_TO_MS(interval)
Convert connection interval to milliseconds.
Multiply by 1.25 to get milliseconds.
Note that this may be inaccurate, as something like 7.5 ms cannot be accurately presented with integers.
-
BT_CONN_INTERVAL_TO_US(interval)
Convert connection interval to microseconds.
Multiply by 1250 to get microseconds.
-
BT_CONN_ROLE_MASTER
Connection role (central or peripheral)
-
BT_CONN_ROLE_SLAVE
-
BT_CONN_LE_CREATE_PARAM_INIT(_options, _interval, _window)
Initialize create connection parameters.
- Parameters:
_options – Create connection options.
_interval – Create connection scan interval (N * 0.625 ms).
_window – Create connection scan window (N * 0.625 ms).
-
BT_CONN_LE_CREATE_PARAM(_options, _interval, _window)
Helper to declare create connection parameters inline.
- Parameters:
_options – Create connection options.
_interval – Create connection scan interval (N * 0.625 ms).
_window – Create connection scan window (N * 0.625 ms).
-
BT_CONN_LE_CREATE_CONN
Default LE create connection parameters.
Scan continuously by setting scan interval equal to scan window.
-
BT_CONN_LE_CREATE_CONN_AUTO
Default LE create connection using filter accept list parameters.
Scan window: 30 ms. Scan interval: 60 ms.
-
BT_CONN_CB_DEFINE(_name)
Register a callback structure for connection events.
- Parameters:
_name – Name of callback structure.
-
BT_PASSKEY_INVALID
Special passkey value that can be used to disable a previously set fixed passkey.
-
BT_BR_CONN_PARAM_INIT(role_switch)
Initialize BR/EDR connection parameters.
- Parameters:
role_switch – True if role switch is allowed
-
BT_BR_CONN_PARAM(role_switch)
Helper to declare BR/EDR connection parameters inline.
- Parameters:
role_switch – True if role switch is allowed
-
BT_BR_CONN_PARAM_DEFAULT
Default BR/EDR connection parameters: Role switch allowed.
Enums
-
enum [anonymous]
Connection PHY options.
Values:
-
enumerator BT_CONN_LE_PHY_OPT_NONE = 0
Convenience value when no options are specified.
-
enumerator BT_CONN_LE_PHY_OPT_NONE = 0
-
enum bt_conn_type
Connection Type.
Values:
-
enumerator BT_CONN_TYPE_ALL = BT_CONN_TYPE_LE | BT_CONN_TYPE_BR | BT_CONN_TYPE_SCO | BT_CONN_TYPE_ISO
All Connection Type.
-
enumerator BT_CONN_TYPE_ALL = BT_CONN_TYPE_LE | BT_CONN_TYPE_BR | BT_CONN_TYPE_SCO | BT_CONN_TYPE_ISO
-
enum [anonymous]
Values:
-
enumerator BT_CONN_ROLE_CENTRAL = 0
-
enumerator BT_CONN_ROLE_PERIPHERAL = 1
-
enumerator BT_CONN_ROLE_CENTRAL = 0
-
enum bt_conn_state
Values:
-
enumerator BT_CONN_STATE_DISCONNECTED
Channel disconnected.
-
enumerator BT_CONN_STATE_CONNECTING
Channel in connecting state.
-
enumerator BT_CONN_STATE_CONNECTED
Channel connected and ready for upper layer traffic on it.
-
enumerator BT_CONN_STATE_DISCONNECTING
Channel in disconnecting state.
-
enumerator BT_CONN_STATE_DISCONNECTED
-
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_L0
-
enum bt_security_flag
Security Info Flags.
Values:
-
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 BT_CONN_LE_TX_POWER_PHY_NONE
-
enum bt_conn_le_path_loss_zone
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.
Values:
-
enumerator BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_LOW
Low path loss zone entered.
-
enumerator BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_MIDDLE
Middle path loss zone entered.
-
enumerator BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_HIGH
High path loss zone entered.
-
enumerator BT_CONN_LE_PATH_LOSS_ZONE_UNAVAILABLE
Path loss has become unavailable.
-
enumerator BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_LOW
-
enum bt_conn_auth_keypress
Passkey Keypress Notification type.
The numeric values are the same as in the Core specification for Pairing Keypress Notification PDU.
Values:
-
enumerator BT_CONN_AUTH_KEYPRESS_ENTRY_STARTED = 0x00
-
enumerator BT_CONN_AUTH_KEYPRESS_DIGIT_ENTERED = 0x01
-
enumerator BT_CONN_AUTH_KEYPRESS_DIGIT_ERASED = 0x02
-
enumerator BT_CONN_AUTH_KEYPRESS_CLEARED = 0x03
-
enumerator BT_CONN_AUTH_KEYPRESS_ENTRY_COMPLETED = 0x04
-
enumerator BT_CONN_AUTH_KEYPRESS_ENTRY_STARTED = 0x00
-
enum [anonymous]
Values:
-
enumerator BT_CONN_LE_OPT_NONE = 0
Convenience value when no options are specified.
-
enumerator BT_CONN_LE_OPT_NONE = 0
-
enum bt_security_err
Values:
-
enumerator BT_SECURITY_ERR_SUCCESS
Security procedure successful.
-
enumerator BT_SECURITY_ERR_AUTH_FAIL
Authentication failed.
-
enumerator BT_SECURITY_ERR_PIN_OR_KEY_MISSING
PIN or encryption key is missing.
-
enumerator BT_SECURITY_ERR_OOB_NOT_AVAILABLE
OOB data is not available.
-
enumerator BT_SECURITY_ERR_AUTH_REQUIREMENT
The requested security level could not be reached.
-
enumerator BT_SECURITY_ERR_PAIR_NOT_SUPPORTED
Pairing is not supported.
-
enumerator BT_SECURITY_ERR_PAIR_NOT_ALLOWED
Pairing is not allowed.
-
enumerator BT_SECURITY_ERR_INVALID_PARAM
Invalid parameters.
-
enumerator BT_SECURITY_ERR_KEY_REJECTED
Distributed Key Rejected.
-
enumerator BT_SECURITY_ERR_UNSPECIFIED
Pairing failed but the exact reason could not be specified.
-
enumerator BT_SECURITY_ERR_SUCCESS
Functions
-
struct bt_conn *bt_conn_ref(struct bt_conn *conn)
Increment a connection’s reference count.
Increment the reference count of a connection object.
Note
Will return NULL if the reference count is zero.
- Parameters:
conn – Connection object.
- Returns:
Connection object with incremented reference count, or NULL if the reference count is zero.
-
void bt_conn_unref(struct bt_conn *conn)
Decrement a connection’s reference count.
Decrement the reference count of a connection object.
- Parameters:
conn – Connection object.
-
void bt_conn_foreach(enum bt_conn_type type, void (*func)(struct bt_conn *conn, void *data), void *data)
Iterate through all bt_conn objects.
Iterates trough all bt_conn objects that are alive in the Host allocator.
To find established connections, combine this with bt_conn_get_info. Check that bt_conn_info::state is BT_CONN_STATE_CONNECTED.
Thread safety: This API is thread safe, but it does not guarantee a sequentially-consistent view for objects allocated during the current invocation of this API. E.g. If preempted while allocations A then B then C happen then results may include A and C but miss B.
- Parameters:
type – Connection Type
func – Function to call for each connection.
data – Data to pass to the callback function.
-
struct bt_conn *bt_conn_lookup_addr_le(uint8_t id, const bt_addr_le_t *peer)
Look up an existing connection by address.
Look up an existing connection based on the remote address.
The caller gets a new reference to the connection object which must be released with bt_conn_unref() once done using the object.
- Parameters:
id – Local identity (in most cases BT_ID_DEFAULT).
peer – Remote address.
- Returns:
Connection object or NULL if not found.
-
const bt_addr_le_t *bt_conn_get_dst(const struct bt_conn *conn)
Get destination (peer) address of a connection.
- Parameters:
conn – Connection object.
- Returns:
Destination address.
-
uint8_t bt_conn_index(const struct bt_conn *conn)
Get array index of a connection.
This function is used to map bt_conn to index of an array of connections. The array has CONFIG_BT_MAX_CONN elements.
- Parameters:
conn – Connection object.
- Returns:
Index of the connection object. The range of the returned value is 0..CONFIG_BT_MAX_CONN-1
-
int bt_conn_get_info(const struct bt_conn *conn, struct bt_conn_info *info)
Get connection info.
- Parameters:
conn – Connection object.
info – Connection info object.
- Returns:
Zero on success or (negative) error code on failure.
-
int bt_conn_get_remote_info(struct bt_conn *conn, struct bt_conn_remote_info *remote_info)
Get connection info for the remote device.
Note
In order to retrieve the remote version (version, manufacturer and subversion)
CONFIG_BT_REMOTE_VERSION
must be enabledNote
The remote information is exchanged directly after the connection has been established. The application can be notified about when the remote information is available through the remote_info_available callback.
- Parameters:
conn – Connection object.
remote_info – Connection remote info object.
- Returns:
Zero on success or (negative) error code on failure.
- Returns:
-EBUSY The remote information is not yet available.
-
int bt_conn_le_get_tx_power_level(struct bt_conn *conn, struct bt_conn_le_tx_power *tx_power_level)
Get connection transmit power level.
- Parameters:
conn – Connection object.
tx_power_level – Transmit power level descriptor.
- Returns:
Zero on success or (negative) error code on failure.
- Returns:
-ENOBUFS HCI command buffer is not available.
-
int bt_conn_le_enhanced_get_tx_power_level(struct bt_conn *conn, struct bt_conn_le_tx_power *tx_power)
Get local enhanced connection transmit power level.
- Parameters:
conn – Connection object.
tx_power – Transmit power level descriptor.
- Return values:
-ENOBUFS – HCI command buffer is not available.
- Returns:
Zero on success or (negative) error code on failure.
-
int bt_conn_le_get_remote_tx_power_level(struct bt_conn *conn, enum bt_conn_le_tx_power_phy phy)
Get remote (peer) transmit power level.
- Parameters:
conn – Connection object.
phy – PHY information.
- Return values:
-ENOBUFS – HCI command buffer is not available.
- Returns:
Zero on success or (negative) error code on failure.
-
int bt_conn_le_set_tx_power_report_enable(struct bt_conn *conn, bool local_enable, bool remote_enable)
Enable transmit power reporting.
- Parameters:
conn – Connection object.
local_enable – Enable/disable reporting for local.
remote_enable – Enable/disable reporting for remote.
- Return values:
-ENOBUFS – HCI command buffer is not available.
- Returns:
Zero on success or (negative) error code on failure.
-
int bt_conn_le_set_path_loss_mon_param(struct bt_conn *conn, const struct bt_conn_le_path_loss_reporting_param *param)
Set Path Loss Monitoring Parameters.
Change the configuration for path loss threshold change events for a given conn handle.
Note
To use this API
CONFIG_BT_PATH_LOSS_MONITORING
must be set.- Parameters:
conn – Connection object.
param – Path Loss Monitoring parameters
- Returns:
Zero on success or (negative) error code on failure.
-
int bt_conn_le_set_path_loss_mon_enable(struct bt_conn *conn, bool enable)
Enable or Disable Path Loss Monitoring.
Enable or disable Path Loss Monitoring, which will decide whether Path Loss Threshold events are sent from the controller to the host.
Note
To use this API
CONFIG_BT_PATH_LOSS_MONITORING
must be set.- Parameters:
conn – Connection Object.
enable – Enable/disable path loss reporting.
- Returns:
Zero on success or (negative) error code on failure.
-
int bt_conn_le_subrate_set_defaults(const struct bt_conn_le_subrate_param *params)
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
andCONFIG_BT_CENTRAL
must be set.- Parameters:
params – Subrating parameters.
- Returns:
Zero on success or (negative) error code on failure.
-
int bt_conn_le_subrate_request(struct bt_conn *conn, const struct bt_conn_le_subrate_param *params)
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:
conn – Connection object.
params – Subrating parameters.
- Returns:
Zero on success or (negative) error code on failure.
-
int bt_conn_le_param_update(struct bt_conn *conn, const struct bt_le_conn_param *param)
Update the connection parameters.
If the local device is in the peripheral role then updating the connection parameters will be delayed. This delay can be configured by through the
CONFIG_BT_CONN_PARAM_UPDATE_TIMEOUT
option.- Parameters:
conn – Connection object.
param – Updated connection parameters.
- Returns:
Zero on success or (negative) error code on failure.
-
int bt_conn_le_data_len_update(struct bt_conn *conn, const struct bt_conn_le_data_len_param *param)
Update the connection transmit data length parameters.
- Parameters:
conn – Connection object.
param – Updated data length parameters.
- Returns:
Zero on success or (negative) error code on failure.
-
int bt_conn_le_phy_update(struct bt_conn *conn, const struct bt_conn_le_phy_param *param)
Update the connection PHY parameters.
Update the preferred transmit and receive PHYs of the connection. Use BT_GAP_LE_PHY_NONE to indicate no preference.
- Parameters:
conn – Connection object.
param – Updated connection parameters.
- Returns:
Zero on success or (negative) error code on failure.
-
int bt_conn_disconnect(struct bt_conn *conn, uint8_t reason)
Disconnect from a remote device or cancel pending connection.
Disconnect an active connection with the specified reason code or cancel pending outgoing connection.
The disconnect reason for a normal disconnect should be: BT_HCI_ERR_REMOTE_USER_TERM_CONN.
The following disconnect reasons are accepted:
BT_HCI_ERR_AUTH_FAIL
BT_HCI_ERR_REMOTE_USER_TERM_CONN
BT_HCI_ERR_REMOTE_LOW_RESOURCES
BT_HCI_ERR_REMOTE_POWER_OFF
BT_HCI_ERR_UNSUPP_REMOTE_FEATURE
BT_HCI_ERR_PAIRING_NOT_SUPPORTED
BT_HCI_ERR_UNACCEPT_CONN_PARAM
- Parameters:
conn – Connection to disconnect.
reason – Reason code for the disconnection.
- Returns:
Zero on success or (negative) error code on failure.
-
int bt_conn_le_create(const bt_addr_le_t *peer, const struct bt_conn_le_create_param *create_param, const struct bt_le_conn_param *conn_param, struct bt_conn **conn)
Initiate an LE connection to a remote device.
Allows initiate new LE link to remote peer using its address.
The caller gets a new reference to the connection object which must be released with bt_conn_unref() once done using the object.
This uses the General Connection Establishment procedure.
The application must disable explicit scanning before initiating a new LE connection if
CONFIG_BT_SCAN_AND_INITIATE_IN_PARALLEL
is not enabled.- Parameters:
peer – [in] Remote address.
create_param – [in] Create connection parameters.
conn_param – [in] Initial connection parameters.
conn – [out] Valid connection object on success.
- Returns:
Zero on success or (negative) error code on failure.
-
int bt_conn_le_create_synced(const struct bt_le_ext_adv *adv, const struct bt_conn_le_create_synced_param *synced_param, const struct bt_le_conn_param *conn_param, struct bt_conn **conn)
Create a connection to a synced device.
Initiate a connection to a synced device from a Periodic Advertising with Responses (PAwR) train.
The caller gets a new reference to the connection object which must be released with bt_conn_unref() once done using the object.
This uses the Periodic Advertising Connection Procedure.
- Parameters:
adv – [in] The adverting set the PAwR advertiser belongs to.
synced_param – [in] Create connection parameters.
conn_param – [in] Initial connection parameters.
conn – [out] Valid connection object on success.
- Returns:
Zero on success or (negative) error code on failure.
-
int bt_conn_le_create_auto(const struct bt_conn_le_create_param *create_param, const struct bt_le_conn_param *conn_param)
Automatically connect to remote devices in the filter accept list.
This uses the Auto Connection Establishment procedure. The procedure will continue until a single connection is established or the procedure is stopped through bt_conn_create_auto_stop. To establish connections to all devices in the the filter accept list the procedure should be started again in the connected callback after a new connection has been established.
- Parameters:
create_param – Create connection parameters
conn_param – Initial connection parameters.
- Returns:
Zero on success or (negative) error code on failure.
- Returns:
-ENOMEM No free connection object available.
-
int bt_conn_create_auto_stop(void)
Stop automatic connect creation.
- Returns:
Zero on success or (negative) error code on failure.
-
int bt_le_set_auto_conn(const bt_addr_le_t *addr, const struct bt_le_conn_param *param)
Automatically connect to remote device if it’s in range.
This function enables/disables automatic connection initiation. Every time the device loses the connection with peer, this connection will be re-established if connectable advertisement from peer is received.
Note
Auto connect is disabled during explicit scanning.
- Parameters:
addr – Remote Bluetooth address.
param – If non-NULL, auto connect is enabled with the given parameters. If NULL, auto connect is disabled.
- Returns:
Zero on success or error code otherwise.
-
int bt_conn_set_security(struct bt_conn *conn, bt_security_t sec)
Set security level for a connection.
This function enable security (encryption) for a connection. If the device has bond information for the peer with sufficiently strong key encryption will be enabled. If the connection is already encrypted with sufficiently strong key this function does nothing.
If the device has no bond information for the peer and is not already paired then the pairing procedure will be initiated. Note that
sec
has no effect on the security level selected for the pairing process. The selection is instead controlled by the values of the registered bt_conn_auth_cb. If the device has bond information or is already paired and the keys are too weak then the pairing procedure will be initiated.This function may return an error if the required level of security defined using
sec
is not possible to achieve due to local or remote device limitation (e.g., input output capabilities), or if the maximum number of paired devices has been reached.This function may return an error if the pairing procedure has already been initiated by the local device or the peer device.
Note
When
CONFIG_BT_SMP_SC_ONLY
is enabled then the security level will always be level 4.Note
When
CONFIG_BT_SMP_OOB_LEGACY_PAIR_ONLY
is enabled then the security level will always be level 3.Note
When BT_SECURITY_FORCE_PAIR within
sec
is enabled then the pairing procedure will always be initiated.- Parameters:
conn – Connection object.
sec – Requested minimum security level.
- Returns:
0 on success or negative error
-
bt_security_t bt_conn_get_security(const struct bt_conn *conn)
Get security level for a connection.
- Returns:
Connection security level
-
uint8_t bt_conn_enc_key_size(const struct bt_conn *conn)
Get encryption key size.
This function gets encryption key size. If there is no security (encryption) enabled 0 will be returned.
- Parameters:
conn – Existing connection object.
- Returns:
Encryption key size.
-
int 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.
- Return values:
0 – Success.
-EEXIST – if
cb
was already registered.
-
int bt_conn_cb_unregister(struct bt_conn_cb *cb)
Unregister connection callbacks.
Unregister the state of connections callbacks.
- Parameters:
cb – Callback struct point to memory that remains valid.
- Return values:
0 – Success
-EINVAL – If
cb
is NULL-ENOENT – if
cb
was not registered
-
static inline const char *bt_security_err_to_str(enum bt_security_err err)
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
-
void bt_set_bondable(bool enable)
Enable/disable bonding.
Set/clear the Bonding flag in the Authentication Requirements of SMP Pairing Request/Response data. The initial value of this flag depends on BT_BONDABLE Kconfig setting. For the vast majority of applications calling this function shouldn’t be needed.
- Parameters:
enable – Value allowing/disallowing to be bondable.
-
int bt_conn_set_bondable(struct bt_conn *conn, bool enable)
Set/clear the bonding flag for a given connection.
Set/clear the Bonding flag in the Authentication Requirements of SMP Pairing Request/Response data for a given connection.
The bonding flag for a given connection cannot be set/cleared if security procedures in the SMP module have already started. This function can be called only once per connection.
If the bonding flag is not set/cleared for a given connection, the value will depend on global configuration which is set using bt_set_bondable. The default value of the global configuration is defined using CONFIG_BT_BONDABLE Kconfig option.
- Parameters:
conn – Connection object.
enable – Value allowing/disallowing to be bondable.
-
void bt_le_oob_set_sc_flag(bool enable)
Allow/disallow remote LE SC OOB data to be used for pairing.
Set/clear the OOB data flag for LE SC SMP Pairing Request/Response data.
- Parameters:
enable – Value allowing/disallowing remote LE SC OOB data.
-
void bt_le_oob_set_legacy_flag(bool enable)
Allow/disallow remote legacy OOB data to be used for pairing.
Set/clear the OOB data flag for legacy SMP Pairing Request/Response data.
- Parameters:
enable – Value allowing/disallowing remote legacy OOB data.
-
int bt_le_oob_set_legacy_tk(struct bt_conn *conn, const uint8_t *tk)
Set OOB Temporary Key to be used for pairing.
This function allows to set OOB data for the LE legacy pairing procedure. The function should only be called in response to the oob_data_request() callback provided that the legacy method is user pairing.
- Parameters:
conn – Connection object
tk – Pointer to 16 byte long TK array
- Returns:
Zero on success or -EINVAL if NULL
-
int bt_le_oob_set_sc_data(struct bt_conn *conn, const struct bt_le_oob_sc_data *oobd_local, const struct bt_le_oob_sc_data *oobd_remote)
Set OOB data during LE Secure Connections (SC) pairing procedure.
This function allows to set OOB data during the LE SC pairing procedure. The function should only be called in response to the oob_data_request() callback provided that LE SC method is used for pairing.
The user should submit OOB data according to the information received in the callback. This may yield three different configurations: with only local OOB data present, with only remote OOB data present or with both local and remote OOB data present.
- Parameters:
conn – Connection object
oobd_local – Local OOB data or NULL if not present
oobd_remote – Remote OOB data or NULL if not present
- Returns:
Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error.
-
int bt_le_oob_get_sc_data(struct bt_conn *conn, const struct bt_le_oob_sc_data **oobd_local, const struct bt_le_oob_sc_data **oobd_remote)
Get OOB data used for LE Secure Connections (SC) pairing procedure.
This function allows to get OOB data during the LE SC pairing procedure that were set by the bt_le_oob_set_sc_data() API.
Note
The OOB data will only be available as long as the connection object associated with it is valid.
- Parameters:
conn – Connection object
oobd_local – Local OOB data or NULL if not set
oobd_remote – Remote OOB data or NULL if not set
- Returns:
Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error.
-
int bt_passkey_set(unsigned int passkey)
Set a fixed passkey to be used for pairing.
This API is only available when the CONFIG_BT_FIXED_PASSKEY configuration option has been enabled.
Sets a fixed passkey to be used for pairing. If set, the pairing_confirm() callback will be called for all incoming pairings.
- Parameters:
passkey – A valid passkey (0 - 999999) or BT_PASSKEY_INVALID to disable a previously set fixed passkey.
- Returns:
0 on success or a negative error code on failure.
-
int bt_conn_auth_cb_register(const struct bt_conn_auth_cb *cb)
Register authentication callbacks.
Register callbacks to handle authenticated pairing. Passing NULL unregisters a previous callbacks structure.
- Parameters:
cb – Callback struct.
- Returns:
Zero on success or negative error code otherwise
-
int bt_conn_auth_cb_overlay(struct bt_conn *conn, const struct bt_conn_auth_cb *cb)
Overlay authentication callbacks used for a given connection.
This function can be used only for Bluetooth LE connections. The
CONFIG_BT_SMP
must be enabled for this function.The authentication callbacks for a given connection cannot be overlaid if security procedures in the SMP module have already started. This function can be called only once per connection.
- Parameters:
conn – Connection object.
cb – Callback struct.
- Returns:
Zero on success or negative error code otherwise
-
int bt_conn_auth_info_cb_register(struct bt_conn_auth_info_cb *cb)
Register authentication information callbacks.
Register callbacks to get authenticated pairing information. Multiple registrations can be done.
- Parameters:
cb – Callback struct.
- Returns:
Zero on success or negative error code otherwise
-
int bt_conn_auth_info_cb_unregister(struct bt_conn_auth_info_cb *cb)
Unregister authentication information callbacks.
Unregister callbacks to stop getting authenticated pairing information.
- Parameters:
cb – Callback struct.
- Returns:
Zero on success or negative error code otherwise
-
int bt_conn_auth_passkey_entry(struct bt_conn *conn, unsigned int passkey)
Reply with entered passkey.
This function should be called only after passkey_entry callback from bt_conn_auth_cb structure was called.
- Parameters:
conn – Connection object.
passkey – Entered passkey.
- Returns:
Zero on success or negative error code otherwise
-
int bt_conn_auth_keypress_notify(struct bt_conn *conn, enum bt_conn_auth_keypress type)
Send Passkey Keypress Notification during pairing.
This function may be called only after passkey_entry callback from bt_conn_auth_cb structure was called.
Requires
CONFIG_BT_PASSKEY_KEYPRESS
.See also
- Parameters:
conn – Destination for the notification.
type – What keypress event type to send.
- Return values:
0 – Success
-EINVAL – Improper use of the API.
-ENOMEM – Failed to allocate.
-ENOBUFS – Failed to allocate.
-
int bt_conn_auth_cancel(struct bt_conn *conn)
Cancel ongoing authenticated pairing.
This function allows to cancel ongoing authenticated pairing.
- Parameters:
conn – Connection object.
- Returns:
Zero on success or negative error code otherwise
-
int bt_conn_auth_passkey_confirm(struct bt_conn *conn)
Reply if passkey was confirmed to match by user.
This function should be called only after passkey_confirm callback from bt_conn_auth_cb structure was called.
- Parameters:
conn – Connection object.
- Returns:
Zero on success or negative error code otherwise
-
int bt_conn_auth_pairing_confirm(struct bt_conn *conn)
Reply if incoming pairing was confirmed by user.
This function should be called only after pairing_confirm callback from bt_conn_auth_cb structure was called if user confirmed incoming pairing.
- Parameters:
conn – Connection object.
- Returns:
Zero on success or negative error code otherwise
-
int bt_conn_auth_pincode_entry(struct bt_conn *conn, const char *pin)
Reply with entered PIN code.
This function should be called only after PIN code callback from bt_conn_auth_cb structure was called. It’s for legacy 2.0 devices.
- Parameters:
conn – Connection object.
pin – Entered PIN code.
- Returns:
Zero on success or negative error code otherwise
-
struct bt_conn *bt_conn_create_br(const bt_addr_t *peer, const struct bt_br_conn_param *param)
Initiate an BR/EDR connection to a remote device.
Allows initiate new BR/EDR link to remote peer using its address.
The caller gets a new reference to the connection object which must be released with bt_conn_unref() once done using the object.
- Parameters:
peer – Remote address.
param – Initial connection parameters.
- Returns:
Valid connection object on success or NULL otherwise.
-
struct bt_le_conn_param
- #include <conn.h>
Connection parameters for LE connections.
-
struct bt_conn_le_phy_info
- #include <conn.h>
Connection PHY information for LE connections.
Public Members
-
uint8_t rx_phy
Connection transmit PHY.
-
uint8_t rx_phy
-
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 tx_max_len
-
struct bt_conn_le_data_len_param
- #include <conn.h>
Connection data length parameters for LE connections.
-
struct bt_conn_le_subrate_param
- #include <conn.h>
Connection subrating parameters for LE connections.
Public Members
-
uint16_t subrate_min
Minimum subrate factor.
-
uint16_t subrate_max
Maximum subrate factor.
-
uint16_t max_latency
Maximum Peripheral latency in units of subrated connection intervals.
-
uint16_t continuation_number
Minimum number of underlying connection events to remain active after a packet containing a Link Layer PDU with a non-zero Length field is sent or received.
-
uint16_t supervision_timeout
Connection Supervision timeout (N * 10 ms).
If using bt_conn_le_subrate_set_defaults, this is the maximum supervision timeout allowed in requests by a peripheral.
-
uint16_t subrate_min
-
struct bt_conn_le_subrating_info
- #include <conn.h>
Subrating information for LE connections.
-
struct bt_conn_le_subrate_changed
- #include <conn.h>
Updated subrating connection parameters for LE connections.
Public Members
-
uint8_t status
HCI Status from LE Subrate Changed event.
The remaining parameters will be unchanged if status is not BT_HCI_ERR_SUCCESS.
-
uint16_t factor
Connection subrate factor.
-
uint16_t continuation_number
Number of underlying connection events to remain active after a packet containing a Link Layer PDU with a non-zero Length field is sent or received.
-
uint16_t peripheral_latency
Peripheral latency in units of subrated connection intervals.
-
uint16_t supervision_timeout
Connection Supervision timeout (N * 10 ms).
-
uint8_t status
-
struct bt_conn_le_info
- #include <conn.h>
LE Connection Info Structure.
Public Members
-
const bt_addr_le_t *src
Source (Local) Identity Address.
-
const bt_addr_le_t *dst
Destination (Remote) Identity Address or remote Resolvable Private Address (RPA) before identity has been resolved.
-
const bt_addr_le_t *local
Local device address used during connection setup.
-
const bt_addr_le_t *remote
Remote device address used during connection setup.
-
uint16_t interval
Connection interval.
-
uint16_t latency
Connection peripheral latency.
-
uint16_t timeout
Connection supervision timeout.
-
const bt_addr_le_t *src
-
struct bt_conn_br_info
- #include <conn.h>
BR/EDR Connection Info Structure.
-
struct bt_security_info
- #include <conn.h>
Security Info Structure.
Public Members
-
bt_security_t level
Security Level.
-
uint8_t enc_key_size
Encryption Key Size.
-
enum bt_security_flag flags
Flags.
-
bt_security_t level
-
struct bt_conn_info
- #include <conn.h>
Connection Info Structure.
Public Members
-
enum bt_conn_type type
Connection Type.
-
uint8_t role
Connection Role.
-
uint8_t id
Which local identity the connection was created with.
-
struct bt_conn_le_info le
LE Connection specific Info.
-
struct bt_conn_br_info br
BR/EDR Connection specific Info.
-
union bt_conn_info.[anonymous] [anonymous]
Connection Type specific Info.
-
enum bt_conn_state state
Connection state.
-
struct bt_security_info security
Security specific info.
-
enum bt_conn_type type
-
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 *features
-
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.Public Members
-
uint8_t type
Connection Type.
-
uint8_t version
Remote Link Layer version.
-
uint16_t manufacturer
Remote manufacturer identifier.
-
uint16_t subversion
Per-manufacturer unique revision.
-
struct bt_conn_le_remote_info le
LE connection remote info.
-
struct bt_conn_br_remote_info br
BR/EDR connection remote info.
-
uint8_t type
-
struct bt_conn_le_tx_power
- #include <conn.h>
LE Transmit Power Level Structure.
-
struct bt_conn_le_tx_power_report
- #include <conn.h>
LE Transmit Power Reporting Structure.
Public Members
-
uint8_t reason
Reason for Transmit power reporting, as documented in Core Spec.
Version 5.4 Vol. 4, Part E, 7.7.65.33.
-
enum bt_conn_le_tx_power_phy phy
Phy of Transmit power reporting.
-
int8_t tx_power_level
Transmit power level.
0xXX - Transmit power level
Range: -127 to 20
Units: dBm
0x7E - Remote device is not managing power levels on this PHY.
0x7F - Transmit power level is not available
-
uint8_t tx_power_level_flag
Bit 0: Transmit power level is at minimum level.
Bit 1: Transmit power level is at maximum level.
-
int8_t delta
Change in transmit power level.
0xXX - Change in transmit power level (positive indicates increased power, negative indicates decreased power, zero indicates unchanged) Units: dB
0x7F - Change is not available or is out of range.
-
uint8_t reason
-
struct bt_conn_le_path_loss_threshold_report
- #include <conn.h>
LE Path Loss Monitoring Threshold Change Report Structure.
Public Members
-
enum bt_conn_le_path_loss_zone zone
Path Loss zone as documented in Core Spec.
Version 5.4 Vol.4, Part E, 7.7.65.32.
-
uint8_t path_loss
Current path loss (dB).
-
enum bt_conn_le_path_loss_zone zone
-
struct bt_conn_le_path_loss_reporting_param
- #include <conn.h>
LE Path Loss Monitoring Parameters Structure as defined in Core Spec.
Version 5.4 Vol.4, Part E, 7.8.119 LE Set Path Loss Reporting Parameters command.
Public Members
-
uint8_t high_threshold
High threshold for the path loss (dB).
-
uint8_t high_hysteresis
Hysteresis value for the high threshold (dB).
-
uint8_t low_threshold
Low threshold for the path loss (dB).
-
uint8_t low_hysteresis
Hysteresis value for the low threshold (dB).
-
uint16_t min_time_spent
Minimum time in number of connection events to be observed once the path loss crosses the threshold before an event is generated.
-
uint8_t high_threshold
-
struct bt_conn_le_create_param
- #include <conn.h>
Public Members
-
uint32_t options
Bit-field of create connection options.
-
uint16_t interval
Scan interval (N * 0.625 ms)
-
uint16_t window
Scan window (N * 0.625 ms)
-
uint16_t interval_coded
Scan interval LE Coded PHY (N * 0.625 MS)
Set zero to use same as LE 1M PHY scan interval
-
uint16_t window_coded
Scan window LE Coded PHY (N * 0.625 MS)
Set zero to use same as LE 1M PHY scan window.
-
uint16_t timeout
Connection initiation timeout (N * 10 MS)
Set zero to use the default
CONFIG_BT_CREATE_CONN_TIMEOUT
timeout.Note
Unused in bt_conn_le_create_auto
-
uint32_t options
-
struct bt_conn_le_create_synced_param
- #include <conn.h>
Public Members
-
const bt_addr_le_t *peer
Remote address.
The peer must be synchronized to the PAwR train.
-
uint8_t subevent
The subevent where the connection will be initiated.
-
const bt_addr_le_t *peer
-
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_le_create 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.
Note
If the connection was established from an advertising set then the advertising set cannot be restarted directly from this callback. Instead use the connected callback of the advertising set.
- Param conn:
New connection object.
- Param err:
HCI error. Zero for success, non-zero otherwise.
-
void (*disconnected)(struct bt_conn *conn, uint8_t reason)
A connection has been disconnected.
This callback notifies the application that a connection has been disconnected.
When this callback is called the stack still has one reference to the connection object. If the application in this callback tries to start either a connectable advertiser or create a new connection this might fail because there are no free connection objects available. To avoid this issue it is recommended to either start connectable advertise or create a new connection using k_work_submit or increase
CONFIG_BT_MAX_CONN
.- Param conn:
Connection object.
- Param reason:
BT_HCI_ERR_* reason for the disconnection.
-
void (*recycled)(void)
A connection object has been returned to the pool.
This callback notifies the application that it might be able to allocate a connection object. No guarantee, first come, first serve.
Use this to e.g. re-start connectable advertising or scanning.
Treat this callback as an ISR, as it originates from bt_conn_unref which is used by the BT stack. Making Bluetooth API calls in this context is error-prone and strongly discouraged.
-
bool (*le_param_req)(struct bt_conn *conn, struct bt_le_conn_param *param)
LE connection parameter update request.
This callback notifies the application that a remote device is requesting to update the connection parameters. The application accepts the parameters by returning true, or rejects them by returning false. Before accepting, the application may also adjust the parameters to better suit its needs.
It is recommended for an application to have just one of these callbacks for simplicity. However, if an application registers multiple it needs to manage the potentially different requirements for each callback. Each callback gets the parameters as returned by previous callbacks, i.e. they are not necessarily the same ones as the remote originally sent.
If the application does not have this callback then the default is to accept the parameters.
- Param conn:
Connection object.
- Param param:
Proposed connection parameters.
- Return:
true to accept the parameters, or false to reject them.
-
void (*le_param_updated)(struct bt_conn *conn, uint16_t interval, uint16_t latency, uint16_t timeout)
The parameters for an LE connection have been updated.
This callback notifies the application that the connection parameters for an LE connection have been updated.
- Param conn:
Connection object.
- Param interval:
Connection interval.
- Param latency:
Connection latency.
- Param timeout:
Connection supervision timeout.
-
void (*identity_resolved)(struct bt_conn *conn, const bt_addr_le_t *rpa, const bt_addr_le_t *identity)
Remote Identity Address has been resolved.
This callback notifies the application that a remote Identity Address has been resolved
- Param conn:
Connection object.
- Param rpa:
Resolvable Private Address.
- Param identity:
Identity Address.
-
void (*security_changed)(struct bt_conn *conn, bt_security_t level, enum bt_security_err err)
The security level of a connection has changed.
This callback notifies the application that the security of a connection has changed.
The security level of the connection can either have been increased or remain unchanged. An increased security level means that the pairing procedure has been performed or the bond information from a previous connection has been applied. If the security level remains unchanged this means that the encryption key has been refreshed for the connection.
- Param conn:
Connection object.
- Param level:
New security level of the connection.
- Param err:
Security error. Zero for success, non-zero otherwise.
-
void (*remote_info_available)(struct bt_conn *conn, struct bt_conn_remote_info *remote_info)
Remote information procedures has completed.
This callback notifies the application that the remote information has been retrieved from the remote peer.
- Param conn:
Connection object.
- Param remote_info:
Connection information of remote device.
-
void (*le_phy_updated)(struct bt_conn *conn, struct bt_conn_le_phy_info *param)
The PHY of the connection has changed.
This callback notifies the application that the PHY of the connection has changed.
- Param conn:
Connection object.
- Param info:
Connection LE PHY information.
-
void (*le_data_len_updated)(struct bt_conn *conn, struct bt_conn_le_data_len_info *info)
The data length parameters of the connection has changed.
This callback notifies the application that the maximum Link Layer payload length or transmission time has changed.
- Param conn:
Connection object.
- Param info:
Connection data length information.
-
void (*connected)(struct bt_conn *conn, uint8_t err)
-
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].[anonymous].[anonymous] oob_config
OOB data configuration.
-
struct bt_conn_oob_info.[anonymous].[anonymous] lesc
LE Secure Connections OOB pairing parameters.
-
enum bt_conn_oob_info.[anonymous] type
-
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 io_capability
-
struct bt_conn_auth_cb
- #include <conn.h>
Authenticated pairing callback structure.
Public Members
-
enum bt_security_err (*pairing_accept)(struct bt_conn *conn, const struct bt_conn_pairing_feat *const feat)
Query to proceed incoming pairing or not.
On any incoming pairing req/rsp this callback will be called for the application to decide whether to allow for the pairing to continue.
The pairing info received from the peer is passed to assist making the decision.
As this callback is synchronous the application should return a response value immediately. Otherwise it may affect the timing during pairing. Hence, this information should not be conveyed to the user to take action.
The remaining callbacks are not affected by this, but do notice that other callbacks can be called during the pairing. Eg. if pairing_confirm is registered both will be called for Just-Works pairings.
This callback may be unregistered in which case pairing continues as if the Kconfig flag was not set.
This callback is not called for BR/EDR Secure Simple Pairing (SSP).
- Param conn:
Connection where pairing is initiated.
- Param feat:
Pairing req/resp info.
-
void (*passkey_display)(struct bt_conn *conn, unsigned int passkey)
Display a passkey to the user.
When called the application is expected to display the given passkey to the user, with the expectation that the passkey will then be entered on the peer device. The passkey will be in the range of 0 - 999999, and is expected to be padded with zeroes so that six digits are always shown. E.g. the value 37 should be shown as 000037.
This callback may be set to NULL, which means that the local device lacks the ability do display a passkey. If set to non-NULL the cancel callback must also be provided, since this is the only way the application can find out that it should stop displaying the passkey.
- Param conn:
Connection where pairing is currently active.
- Param passkey:
Passkey to show to the user.
-
void (*passkey_entry)(struct bt_conn *conn)
Request the user to enter a passkey.
When called the user is expected to enter a passkey. The passkey must be in the range of 0 - 999999, and should be expected to be zero-padded, as that’s how the peer device will typically be showing it (e.g. 37 would be shown as 000037).
Once the user has entered the passkey its value should be given to the stack using the bt_conn_auth_passkey_entry() API.
This callback may be set to NULL, which means that the local device lacks the ability to enter a passkey. If set to non-NULL the cancel callback must also be provided, since this is the only way the application can find out that it should stop requesting the user to enter a passkey.
- Param conn:
Connection where pairing is currently active.
-
void (*passkey_confirm)(struct bt_conn *conn, unsigned int passkey)
Request the user to confirm a passkey.
When called the user is expected to confirm that the given passkey is also shown on the peer device.. The passkey will be in the range of 0 - 999999, and should be zero-padded to always be six digits (e.g. 37 would be shown as 000037).
Once the user has confirmed the passkey to match, the bt_conn_auth_passkey_confirm() API should be called. If the user concluded that the passkey doesn’t match the bt_conn_auth_cancel() API should be called.
This callback may be set to NULL, which means that the local device lacks the ability to confirm a passkey. If set to non-NULL the cancel callback must also be provided, since this is the only way the application can find out that it should stop requesting the user to confirm a passkey.
- Param conn:
Connection where pairing is currently active.
- Param passkey:
Passkey to be confirmed.
-
void (*oob_data_request)(struct bt_conn *conn, struct bt_conn_oob_info *info)
Request the user to provide Out of Band (OOB) data.
When called the user is expected to provide OOB data. The required data are indicated by the information structure.
For LE Secure Connections OOB pairing, the user should provide local OOB data, remote OOB data or both depending on their availability. Their value should be given to the stack using the bt_le_oob_set_sc_data() API.
This callback must be set to non-NULL in order to support OOB pairing.
- Param conn:
Connection where pairing is currently active.
- Param info:
OOB pairing information.
-
void (*cancel)(struct bt_conn *conn)
Cancel the ongoing user request.
This callback will be called to notify the application that it should cancel any previous user request (passkey display, entry or confirmation).
This may be set to NULL, but must always be provided whenever the passkey_display, passkey_entry passkey_confirm or pairing_confirm callback has been provided.
- Param conn:
Connection where pairing is currently active.
-
void (*pairing_confirm)(struct bt_conn *conn)
Request confirmation for an incoming pairing.
This callback will be called to confirm an incoming pairing request where none of the other user callbacks is applicable.
If the user decides to accept the pairing the bt_conn_auth_pairing_confirm() API should be called. If the user decides to reject the pairing the bt_conn_auth_cancel() API should be called.
This callback may be set to NULL, which means that the local device lacks the ability to confirm a pairing request. If set to non-NULL the cancel callback must also be provided, since this is the only way the application can find out that it should stop requesting the user to confirm a pairing request.
- Param conn:
Connection where pairing is currently active.
-
void (*pincode_entry)(struct bt_conn *conn, bool highsec)
Request the user to enter a passkey.
This callback will be called for a BR/EDR (Bluetooth Classic) connection where pairing is being performed. Once called the user is expected to enter a PIN code with a length between 1 and 16 digits. If the highsec parameter is set to true the PIN code must be 16 digits long.
Once entered, the PIN code should be given to the stack using the bt_conn_auth_pincode_entry() API.
This callback may be set to NULL, however in that case pairing over BR/EDR will not be possible. If provided, the cancel callback must be provided as well.
- Param conn:
Connection where pairing is currently active.
- Param highsec:
true if 16 digit PIN is required.
-
enum bt_security_err (*pairing_accept)(struct bt_conn *conn, const struct bt_conn_pairing_feat *const feat)
-
struct bt_conn_auth_info_cb
- #include <conn.h>
Authenticated pairing information callback structure.
Public Members
-
void (*pairing_complete)(struct bt_conn *conn, bool bonded)
notify that pairing procedure was complete.
This callback notifies the application that the pairing procedure has been completed.
- Param conn:
Connection object.
- Param bonded:
Bond information has been distributed during the pairing procedure.
-
void (*pairing_failed)(struct bt_conn *conn, enum bt_security_err reason)
notify that pairing process has failed.
- Param conn:
Connection object.
- Param reason:
Pairing failed reason
-
void (*bond_deleted)(uint8_t id, const bt_addr_le_t *peer)
Notify that bond has been deleted.
This callback notifies the application that the bond information for the remote peer has been deleted
- Param id:
Which local identity had the bond.
- Param peer:
Remote address.
-
sys_snode_t node
Internally used field for list handling.
-
void (*pairing_complete)(struct bt_conn *conn, bool bonded)
-
struct bt_br_conn_param
- #include <conn.h>
Connection parameters for BR/EDR connections.
-
BT_LE_CONN_PARAM_INIT(int_min, int_max, lat, to)