conn.h

Go to the documentation of this file.

 
/*
 * Copyright (c) 2015-2016 Intel Corporation
 *
 * SPDX-License-Identifier: Apache-2.0
 */
#ifndef ZEPHYR_INCLUDE_BLUETOOTH_CONN_H_
#define ZEPHYR_INCLUDE_BLUETOOTH_CONN_H_
 
#include <stdbool.h>
#include <stdint.h>
 
#include <zephyr/bluetooth/bluetooth.h>
#include <zephyr/bluetooth/hci_types.h>
#include <zephyr/bluetooth/addr.h>
#include <zephyr/bluetooth/gap.h>
#include <zephyr/bluetooth/direction.h>
#include <zephyr/sys/iterable_sections.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct bt_conn;
 
struct bt_le_conn_param {
        uint16_t interval_min;
        uint16_t interval_max;
        uint16_t latency;
        uint16_t timeout;
};
 
#define BT_LE_CONN_PARAM_INIT(int_min, int_max, lat, to) \
{ \
        .interval_min = (int_min), \
        .interval_max = (int_max), \
        .latency = (lat), \
        .timeout = (to), \
}
 
#define BT_LE_CONN_PARAM(int_min, int_max, lat, to) \
        ((struct bt_le_conn_param[]) { \
                BT_LE_CONN_PARAM_INIT(int_min, int_max, lat, to) \
         })
 
#define BT_LE_CONN_PARAM_DEFAULT BT_LE_CONN_PARAM(BT_GAP_INIT_CONN_INT_MIN, \
                                                  BT_GAP_INIT_CONN_INT_MAX, \
                                                  0, 400)
 
struct bt_conn_le_phy_info {
        uint8_t tx_phy; 
        uint8_t rx_phy; 
};
 
enum {
        BT_CONN_LE_PHY_OPT_NONE = 0,
 
        BT_CONN_LE_PHY_OPT_CODED_S2  = BIT(0),
 
        BT_CONN_LE_PHY_OPT_CODED_S8  = BIT(1),
};
 
struct bt_conn_le_phy_param {
        uint16_t options; 
        uint8_t  pref_tx_phy; 
        uint8_t  pref_rx_phy; 
};
 
#define BT_CONN_LE_PHY_PARAM_INIT(_pref_tx_phy, _pref_rx_phy) \
{ \
        .options = BT_CONN_LE_PHY_OPT_NONE, \
        .pref_tx_phy = (_pref_tx_phy), \
        .pref_rx_phy = (_pref_rx_phy), \
}
 
#define BT_CONN_LE_PHY_PARAM(_pref_tx_phy, _pref_rx_phy) \
        ((struct bt_conn_le_phy_param []) { \
                BT_CONN_LE_PHY_PARAM_INIT(_pref_tx_phy, _pref_rx_phy) \
         })
 
#define BT_CONN_LE_PHY_PARAM_1M BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_1M, \
                                                     BT_GAP_LE_PHY_1M)
 
#define BT_CONN_LE_PHY_PARAM_2M BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_2M, \
                                                     BT_GAP_LE_PHY_2M)
 
#define BT_CONN_LE_PHY_PARAM_CODED BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_CODED, \
                                                        BT_GAP_LE_PHY_CODED)
 
#define BT_CONN_LE_PHY_PARAM_ALL BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_1M |   \
                                                      BT_GAP_LE_PHY_2M |   \
                                                      BT_GAP_LE_PHY_CODED, \
                                                      BT_GAP_LE_PHY_1M |   \
                                                      BT_GAP_LE_PHY_2M |   \
                                                      BT_GAP_LE_PHY_CODED)
 
struct bt_conn_le_data_len_info {
        uint16_t tx_max_len;
        uint16_t tx_max_time;
        uint16_t rx_max_len;
        uint16_t rx_max_time;
};
 
struct bt_conn_le_data_len_param {
        uint16_t tx_max_len;
        uint16_t tx_max_time;
};
 
#define BT_CONN_LE_DATA_LEN_PARAM_INIT(_tx_max_len, _tx_max_time) \
{ \
        .tx_max_len = (_tx_max_len), \
        .tx_max_time = (_tx_max_time), \
}
 
#define BT_CONN_LE_DATA_LEN_PARAM(_tx_max_len, _tx_max_time) \
        ((struct bt_conn_le_data_len_param[]) { \
                BT_CONN_LE_DATA_LEN_PARAM_INIT(_tx_max_len, _tx_max_time) \
         })
 
#define BT_LE_DATA_LEN_PARAM_DEFAULT \
        BT_CONN_LE_DATA_LEN_PARAM(BT_GAP_DATA_LEN_DEFAULT, \
                                  BT_GAP_DATA_TIME_DEFAULT)
 
#define BT_LE_DATA_LEN_PARAM_MAX \
        BT_CONN_LE_DATA_LEN_PARAM(BT_GAP_DATA_LEN_MAX, \
                                  BT_GAP_DATA_TIME_MAX)
 
enum __packed bt_conn_type {
        BT_CONN_TYPE_LE = BIT(0),
        BT_CONN_TYPE_BR = BIT(1),
        BT_CONN_TYPE_SCO = BIT(2),
        BT_CONN_TYPE_ISO = BIT(3),
        BT_CONN_TYPE_ALL = BT_CONN_TYPE_LE | BT_CONN_TYPE_BR |
                           BT_CONN_TYPE_SCO | BT_CONN_TYPE_ISO,
};
 
struct bt_conn *bt_conn_ref(struct bt_conn *conn);
 
void bt_conn_unref(struct bt_conn *conn);
 
void bt_conn_foreach(enum bt_conn_type type,
                     void (*func)(struct bt_conn *conn, void *data),
                     void *data);
 
struct bt_conn *bt_conn_lookup_addr_le(uint8_t id, const bt_addr_le_t *peer);
 
const bt_addr_le_t *bt_conn_get_dst(const struct bt_conn *conn);
 
uint8_t bt_conn_index(const struct bt_conn *conn);
 
struct bt_conn_le_info {
        const bt_addr_le_t *src;
        const bt_addr_le_t *dst;
        const bt_addr_le_t *local;
        const bt_addr_le_t *remote;
        uint16_t interval; 
        uint16_t latency; 
        uint16_t timeout; 
#if defined(CONFIG_BT_USER_PHY_UPDATE)
        const struct bt_conn_le_phy_info      *phy;
#endif /* defined(CONFIG_BT_USER_PHY_UPDATE) */
 
#if defined(CONFIG_BT_USER_DATA_LEN_UPDATE)
        /* Connection maximum single fragment parameters */
        const struct bt_conn_le_data_len_info *data_len;
#endif /* defined(CONFIG_BT_USER_DATA_LEN_UPDATE) */
};
 
#define BT_CONN_INTERVAL_TO_MS(interval) ((interval) * 5U / 4U)
 
#define BT_CONN_INTERVAL_TO_US(interval) ((interval) * 1250U)
 
struct bt_conn_br_info {
        const bt_addr_t *dst; 
};
 
enum {
        BT_CONN_ROLE_CENTRAL = 0,
        BT_CONN_ROLE_PERIPHERAL = 1,
};
 
enum bt_conn_state {
        BT_CONN_STATE_DISCONNECTED,
        BT_CONN_STATE_CONNECTING,
        BT_CONN_STATE_CONNECTED,
        BT_CONN_STATE_DISCONNECTING,
};
 
typedef enum __packed {
        BT_SECURITY_L0,
        BT_SECURITY_L1,
        BT_SECURITY_L2,
        BT_SECURITY_L3,
        BT_SECURITY_L4,
        BT_SECURITY_FORCE_PAIR = BIT(7),
} bt_security_t;
 
enum bt_security_flag {
        BT_SECURITY_FLAG_SC = BIT(0),
        BT_SECURITY_FLAG_OOB = BIT(1),
};
 
struct bt_security_info {
        bt_security_t level;
        uint8_t enc_key_size;
        enum bt_security_flag flags;
};
 
struct bt_conn_info {
        enum bt_conn_type type;
        uint8_t role;
        uint8_t id;
        union {
                struct bt_conn_le_info le;
                struct bt_conn_br_info br;
        };
        enum bt_conn_state state;
        struct bt_security_info security;
};
 
struct bt_conn_le_remote_info {
 
        const uint8_t *features;
};
 
struct bt_conn_br_remote_info {
 
        const uint8_t *features;
 
        uint8_t num_pages;
};
 
struct bt_conn_remote_info {
        uint8_t  type;
 
        uint8_t  version;
 
        uint16_t manufacturer;
 
        uint16_t subversion;
 
        union {
                struct bt_conn_le_remote_info le;
 
                struct bt_conn_br_remote_info br;
        };
};
 
enum bt_conn_le_tx_power_phy {
        BT_CONN_LE_TX_POWER_PHY_NONE,
        BT_CONN_LE_TX_POWER_PHY_1M,
        BT_CONN_LE_TX_POWER_PHY_2M,
        BT_CONN_LE_TX_POWER_PHY_CODED_S8,
        BT_CONN_LE_TX_POWER_PHY_CODED_S2,
};
 
struct bt_conn_le_tx_power {
 
        uint8_t phy;
 
        int8_t current_level;
 
        int8_t max_level;
};
 
 
struct bt_conn_le_tx_power_report {
 
        uint8_t reason;
 
        enum bt_conn_le_tx_power_phy phy;
 
        int8_t tx_power_level;
 
        uint8_t tx_power_level_flag;
 
        int8_t delta;
};
 
enum bt_conn_le_path_loss_zone {
        BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_LOW,
        BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_MIDDLE,
        BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_HIGH,
        BT_CONN_LE_PATH_LOSS_ZONE_UNAVAILABLE,
};
 
BUILD_ASSERT(BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_LOW == BT_HCI_LE_ZONE_ENTERED_LOW);
BUILD_ASSERT(BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_MIDDLE == BT_HCI_LE_ZONE_ENTERED_MIDDLE);
BUILD_ASSERT(BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_HIGH == BT_HCI_LE_ZONE_ENTERED_HIGH);
 
struct bt_conn_le_path_loss_threshold_report {
 
        enum bt_conn_le_path_loss_zone zone;
 
        uint8_t path_loss;
};
 
struct bt_conn_le_path_loss_reporting_param {
        uint8_t high_threshold;
        uint8_t high_hysteresis;
        uint8_t low_threshold;
        uint8_t low_hysteresis;
        uint16_t min_time_spent;
};
 
enum bt_conn_auth_keypress {
        BT_CONN_AUTH_KEYPRESS_ENTRY_STARTED = 0x00,
        BT_CONN_AUTH_KEYPRESS_DIGIT_ENTERED = 0x01,
        BT_CONN_AUTH_KEYPRESS_DIGIT_ERASED = 0x02,
        BT_CONN_AUTH_KEYPRESS_CLEARED = 0x03,
        BT_CONN_AUTH_KEYPRESS_ENTRY_COMPLETED = 0x04,
};
 
int bt_conn_get_info(const struct bt_conn *conn, struct bt_conn_info *info);
 
int bt_conn_get_remote_info(struct bt_conn *conn,
                            struct bt_conn_remote_info *remote_info);
 
int bt_conn_le_get_tx_power_level(struct bt_conn *conn,
                                  struct bt_conn_le_tx_power *tx_power_level);
 
int bt_conn_le_enhanced_get_tx_power_level(struct bt_conn *conn,
                                           struct bt_conn_le_tx_power *tx_power);
 
int bt_conn_le_get_remote_tx_power_level(struct bt_conn *conn,
                                         enum bt_conn_le_tx_power_phy phy);
 
int bt_conn_le_set_tx_power_report_enable(struct bt_conn *conn,
                                          bool local_enable,
                                          bool remote_enable);
 
int bt_conn_le_set_path_loss_mon_param(struct bt_conn *conn,
                                       const struct bt_conn_le_path_loss_reporting_param *param);
 
int bt_conn_le_set_path_loss_mon_enable(struct bt_conn *conn, bool enable);
 
int bt_conn_le_param_update(struct bt_conn *conn,
                            const struct bt_le_conn_param *param);
 
int bt_conn_le_data_len_update(struct bt_conn *conn,
                               const struct bt_conn_le_data_len_param *param);
 
int bt_conn_le_phy_update(struct bt_conn *conn,
                          const struct bt_conn_le_phy_param *param);
 
int bt_conn_disconnect(struct bt_conn *conn, uint8_t reason);
 
enum {
        BT_CONN_LE_OPT_NONE = 0,
 
        BT_CONN_LE_OPT_CODED = BIT(0),
 
        BT_CONN_LE_OPT_NO_1M = BIT(1),
};
 
struct bt_conn_le_create_param {
 
        uint32_t options;
 
        uint16_t interval;
 
        uint16_t window;
 
        uint16_t interval_coded;
 
        uint16_t window_coded;
 
        uint16_t timeout;
};
 
#define BT_CONN_LE_CREATE_PARAM_INIT(_options, _interval, _window) \
{ \
        .options = (_options), \
        .interval = (_interval), \
        .window = (_window), \
        .interval_coded = 0, \
        .window_coded = 0, \
        .timeout = 0, \
}
 
#define BT_CONN_LE_CREATE_PARAM(_options, _interval, _window) \
        ((struct bt_conn_le_create_param[]) { \
                BT_CONN_LE_CREATE_PARAM_INIT(_options, _interval, _window) \
         })
 
#define BT_CONN_LE_CREATE_CONN \
        BT_CONN_LE_CREATE_PARAM(BT_CONN_LE_OPT_NONE, \
                                BT_GAP_SCAN_FAST_INTERVAL, \
                                BT_GAP_SCAN_FAST_INTERVAL)
 
#define BT_CONN_LE_CREATE_CONN_AUTO \
        BT_CONN_LE_CREATE_PARAM(BT_CONN_LE_OPT_NONE, \
                                BT_GAP_SCAN_FAST_INTERVAL, \
                                BT_GAP_SCAN_FAST_WINDOW)
 
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);
 
struct bt_conn_le_create_synced_param {
 
        const bt_addr_le_t *peer;
 
        uint8_t subevent;
};
 
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);
 
int bt_conn_le_create_auto(const struct bt_conn_le_create_param *create_param,
                           const struct bt_le_conn_param *conn_param);
 
int bt_conn_create_auto_stop(void);
 
int bt_le_set_auto_conn(const bt_addr_le_t *addr,
                        const struct bt_le_conn_param *param);
 
int bt_conn_set_security(struct bt_conn *conn, bt_security_t sec);
 
bt_security_t bt_conn_get_security(const struct bt_conn *conn);
 
uint8_t bt_conn_enc_key_size(const struct bt_conn *conn);
 
enum bt_security_err {
        BT_SECURITY_ERR_SUCCESS,
 
        BT_SECURITY_ERR_AUTH_FAIL,
 
        BT_SECURITY_ERR_PIN_OR_KEY_MISSING,
 
        BT_SECURITY_ERR_OOB_NOT_AVAILABLE,
 
        BT_SECURITY_ERR_AUTH_REQUIREMENT,
 
        BT_SECURITY_ERR_PAIR_NOT_SUPPORTED,
 
        BT_SECURITY_ERR_PAIR_NOT_ALLOWED,
 
        BT_SECURITY_ERR_INVALID_PARAM,
 
        BT_SECURITY_ERR_KEY_REJECTED,
 
        BT_SECURITY_ERR_UNSPECIFIED,
};
 
struct bt_conn_cb {
        void (*connected)(struct bt_conn *conn, uint8_t err);
 
        void (*disconnected)(struct bt_conn *conn, uint8_t reason);
 
        void (*recycled)(void);
 
        bool (*le_param_req)(struct bt_conn *conn,
                             struct bt_le_conn_param *param);
 
        void (*le_param_updated)(struct bt_conn *conn, uint16_t interval,
                                 uint16_t latency, uint16_t timeout);
#if defined(CONFIG_BT_SMP)
        void (*identity_resolved)(struct bt_conn *conn,
                                  const bt_addr_le_t *rpa,
                                  const bt_addr_le_t *identity);
#endif /* CONFIG_BT_SMP */
#if defined(CONFIG_BT_SMP) || defined(CONFIG_BT_CLASSIC)
        void (*security_changed)(struct bt_conn *conn, bt_security_t level,
                                 enum bt_security_err err);
#endif /* defined(CONFIG_BT_SMP) || defined(CONFIG_BT_CLASSIC) */
 
#if defined(CONFIG_BT_REMOTE_INFO)
        void (*remote_info_available)(struct bt_conn *conn,
                                      struct bt_conn_remote_info *remote_info);
#endif /* defined(CONFIG_BT_REMOTE_INFO) */
 
#if defined(CONFIG_BT_USER_PHY_UPDATE)
        void (*le_phy_updated)(struct bt_conn *conn,
                               struct bt_conn_le_phy_info *param);
#endif /* defined(CONFIG_BT_USER_PHY_UPDATE) */
 
#if defined(CONFIG_BT_USER_DATA_LEN_UPDATE)
        void (*le_data_len_updated)(struct bt_conn *conn,
                                    struct bt_conn_le_data_len_info *info);
#endif /* defined(CONFIG_BT_USER_DATA_LEN_UPDATE) */
 
#if defined(CONFIG_BT_DF_CONNECTION_CTE_RX)
        void (*cte_report_cb)(struct bt_conn *conn,
                              const struct bt_df_conn_iq_samples_report *iq_report);
#endif /* CONFIG_BT_DF_CONNECTION_CTE_RX */
 
#if defined(CONFIG_BT_TRANSMIT_POWER_CONTROL)
        void (*tx_power_report)(struct bt_conn *conn,
                                const struct bt_conn_le_tx_power_report *report);
#endif /* CONFIG_BT_TRANSMIT_POWER_CONTROL */
 
#if defined(CONFIG_BT_PATH_LOSS_MONITORING)
        void (*path_loss_threshold_report)(struct bt_conn *conn,
                                const struct bt_conn_le_path_loss_threshold_report *report);
#endif /* CONFIG_BT_PATH_LOSS_MONITORING */
 
        sys_snode_t _node;
};
 
int bt_conn_cb_register(struct bt_conn_cb *cb);
 
int bt_conn_cb_unregister(struct bt_conn_cb *cb);
 
#define BT_CONN_CB_DEFINE(_name)                                        \
        static const STRUCT_SECTION_ITERABLE(bt_conn_cb,                \
                                                _CONCAT(bt_conn_cb_,    \
                                                        _name))
 
#if defined(CONFIG_BT_SECURITY_ERR_TO_STR)
const char *bt_security_err_to_str(enum bt_security_err err);
#else
static inline const char *bt_security_err_to_str(enum bt_security_err err)
{
        ARG_UNUSED(err);
 
        return "";
}
#endif
 
void bt_set_bondable(bool enable);
 
int bt_conn_set_bondable(struct bt_conn *conn, bool enable);
 
void bt_le_oob_set_sc_flag(bool enable);
 
void bt_le_oob_set_legacy_flag(bool enable);
 
int bt_le_oob_set_legacy_tk(struct bt_conn *conn, const uint8_t *tk);
 
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);
 
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);
 
#define BT_PASSKEY_INVALID 0xffffffff
 
int bt_passkey_set(unsigned int passkey);
 
struct bt_conn_oob_info {
        enum {
                BT_CONN_OOB_LE_LEGACY,
 
                BT_CONN_OOB_LE_SC,
        } type;
 
        union {
                struct {
                        enum {
                                BT_CONN_OOB_LOCAL_ONLY,
 
                                BT_CONN_OOB_REMOTE_ONLY,
 
                                BT_CONN_OOB_BOTH_PEERS,
 
                                BT_CONN_OOB_NO_DATA,
                        } oob_config;
                } lesc;
        };
};
 
#if defined(CONFIG_BT_SMP_APP_PAIRING_ACCEPT)
struct bt_conn_pairing_feat {
        uint8_t io_capability;
 
        uint8_t oob_data_flag;
 
        uint8_t auth_req;
 
        uint8_t max_enc_key_size;
 
        uint8_t init_key_dist;
 
        uint8_t resp_key_dist;
};
#endif /* CONFIG_BT_SMP_APP_PAIRING_ACCEPT */
 
struct bt_conn_auth_cb {
#if defined(CONFIG_BT_SMP_APP_PAIRING_ACCEPT)
        enum bt_security_err (*pairing_accept)(struct bt_conn *conn,
                              const struct bt_conn_pairing_feat *const feat);
#endif /* CONFIG_BT_SMP_APP_PAIRING_ACCEPT */
 
        void (*passkey_display)(struct bt_conn *conn, unsigned int passkey);
 
#if defined(CONFIG_BT_PASSKEY_KEYPRESS)
        void (*passkey_display_keypress)(struct bt_conn *conn,
                                         enum bt_conn_auth_keypress type);
#endif
 
        void (*passkey_entry)(struct bt_conn *conn);
 
        void (*passkey_confirm)(struct bt_conn *conn, unsigned int passkey);
 
        void (*oob_data_request)(struct bt_conn *conn,
                                 struct bt_conn_oob_info *info);
 
        void (*cancel)(struct bt_conn *conn);
 
        void (*pairing_confirm)(struct bt_conn *conn);
 
#if defined(CONFIG_BT_CLASSIC)
        void (*pincode_entry)(struct bt_conn *conn, bool highsec);
#endif
};
 
struct bt_conn_auth_info_cb {
        void (*pairing_complete)(struct bt_conn *conn, bool bonded);
 
        void (*pairing_failed)(struct bt_conn *conn,
                               enum bt_security_err reason);
 
        void (*bond_deleted)(uint8_t id, const bt_addr_le_t *peer);
 
        sys_snode_t node;
};
 
int bt_conn_auth_cb_register(const struct bt_conn_auth_cb *cb);
 
int bt_conn_auth_cb_overlay(struct bt_conn *conn, const struct bt_conn_auth_cb *cb);
 
int bt_conn_auth_info_cb_register(struct bt_conn_auth_info_cb *cb);
 
int bt_conn_auth_info_cb_unregister(struct bt_conn_auth_info_cb *cb);
 
int bt_conn_auth_passkey_entry(struct bt_conn *conn, unsigned int passkey);
 
int bt_conn_auth_keypress_notify(struct bt_conn *conn, enum bt_conn_auth_keypress type);
 
int bt_conn_auth_cancel(struct bt_conn *conn);
 
int bt_conn_auth_passkey_confirm(struct bt_conn *conn);
 
int bt_conn_auth_pairing_confirm(struct bt_conn *conn);
 
int bt_conn_auth_pincode_entry(struct bt_conn *conn, const char *pin);
 
struct bt_br_conn_param {
        bool allow_role_switch;
};
 
#define BT_BR_CONN_PARAM_INIT(role_switch) \
{ \
        .allow_role_switch = (role_switch), \
}
 
#define BT_BR_CONN_PARAM(role_switch) \
        ((struct bt_br_conn_param[]) { \
                BT_BR_CONN_PARAM_INIT(role_switch) \
         })
 
#define BT_BR_CONN_PARAM_DEFAULT BT_BR_CONN_PARAM(true)
 
 
struct bt_conn *bt_conn_create_br(const bt_addr_t *peer,
                                  const struct bt_br_conn_param *param);
 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_BLUETOOTH_CONN_H_ */