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

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_CODED_S2 = BIT(0): LE Coded using S=2 coding preferred when transmitting.

enumerator BT_CONN_LE_PHY_OPT_CODED_S8 = BIT(1): LE Coded using S=8 coding preferred when transmitting.

enum bt_conn_type

Connection Type.

Values:

enumerator BT_CONN_TYPE_LE = BIT(0): LE Connection Type.

enumerator BT_CONN_TYPE_BR = BIT(1): BR/EDR Connection Type.

enumerator BT_CONN_TYPE_SCO = BIT(2): SCO Connection Type.

enumerator BT_CONN_TYPE_ISO = BIT(3): ISO Connection Type.

enumerator BT_CONN_TYPE_ALL = BT_CONN_TYPE_LE | BT_CONN_TYPE_BR | BT_CONN_TYPE_SCO | BT_CONN_TYPE_ISO : All Connection Type.

Values:

enumerator BT_CONN_ROLE_CENTRAL = 0

enumerator BT_CONN_ROLE_PERIPHERAL = 1

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.

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_FORCE_PAIR = BIT(7): Bit to force new pairing procedure, bit-wise OR with requested security level.

enum bt_security_flag

Security Info Flags.

Values:

enumerator BT_SECURITY_FLAG_SC = BIT(0): Paired with Secure Connections.

enumerator BT_SECURITY_FLAG_OOB = BIT(1): Paired with Out of Band method.

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.

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.

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

Values:

enumerator BT_CONN_LE_OPT_NONE = 0: Convenience value when no options are specified.

enumerator BT_CONN_LE_OPT_CODED = BIT(0)

Enable LE Coded PHY.

    Enable scanning on the LE Coded PHY.

enumerator BT_CONN_LE_OPT_NO_1M = BIT(1)

Disable LE 1M PHY.

    Disable scanning on the LE 1M PHY.

    @note Requires @ref BT_CONN_LE_OPT_CODED.

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.

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 through all bt_conn objects that are alive in the Host allocator.

To find established connections, combine this with bt_conn_get_info. Check that bt_conn_info::state is BT_CONN_STATE_CONNECTED.

Thread safety: This API is thread safe, but it does not guarantee a sequentially-consistent view for objects allocated during the current invocation of this API. E.g. If preempted while allocations A then B then C happen then results may include A and C but miss B.

Parameters:

type – Connection Type
func – Function to call for each connection.
data – Data to pass to the callback function.

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

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