1 /* 2 * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef __ESP_BT_H__ 8 #define __ESP_BT_H__ 9 10 #include <stdint.h> 11 #include <stdbool.h> 12 #include "esp_err.h" 13 #include "sdkconfig.h" 14 #include "esp_assert.h" 15 16 #ifdef __cplusplus 17 extern "C" { 18 #endif 19 20 /** 21 * @brief Internal use only 22 * 23 * @note Please do not modify this value 24 */ 25 #define ESP_BT_CTRL_CONFIG_MAGIC_VAL 0x5A5AA5A5 26 27 /** 28 * @brief Internal use only 29 * 30 * @note Please do not modify this value 31 */ 32 #define ESP_BT_CTRL_CONFIG_VERSION 0x02410230 33 34 /** 35 * @brief Internal use only 36 * 37 * @note Please do not modify this value 38 */ 39 #define ESP_BT_HCI_TL_MAGIC_VALUE 0xfadebead 40 41 /** 42 * @brief Internal use only 43 * 44 * @note Please do not modify this value 45 */ 46 #define ESP_BT_HCI_TL_VERSION 0x00010000 47 48 #if defined(CONFIG_BT_CTLR_TX_PWR_PLUS_21) 49 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_P21 50 #elif defined(CONFIG_BT_CTLR_TX_PWR_PLUS_18) 51 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_P18 52 #elif defined(CONFIG_BT_CTLR_TX_PWR_PLUS_15) 53 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_P15 54 #elif defined(CONFIG_BT_CTLR_TX_PWR_PLUS_12) 55 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_P12 56 #elif defined(CONFIG_BT_CTLR_TX_PWR_PLUS_9) 57 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_P9 58 #elif defined(CONFIG_BT_CTLR_TX_PWR_PLUS_6) 59 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_P6 60 #elif defined(CONFIG_BT_CTLR_TX_PWR_PLUS_3) 61 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_P3 62 #elif defined(CONFIG_BT_CTLR_TX_PWR_0) 63 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_N0 64 #elif defined(CONFIG_BT_CTLR_TX_PWR_MINUS_3) 65 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_N3 66 #elif defined(CONFIG_BT_CTLR_TX_PWR_MINUS_6) 67 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_N6 68 #elif defined(CONFIG_BT_CTLR_TX_PWR_MINUS_9) 69 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_N9 70 #elif defined(CONFIG_BT_CTLR_TX_PWR_MINUS_12) 71 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_N12 72 #elif defined(CONFIG_BT_CTLR_TX_PWR_MINUS_15) 73 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_N15 74 #elif defined(CONFIG_BT_CTLR_TX_PWR_MINUS_18) 75 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_N18 76 #elif defined(CONFIG_BT_CTLR_TX_PWR_MINUS_21) 77 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_N21 78 #elif defined(CONFIG_BT_CTLR_TX_PWR_MINUS_24) 79 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_N24 80 #else 81 /* use 0dB TX power as default */ 82 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_N0 83 #endif 84 85 /** 86 * @brief Bluetooth mode for controller enable/disable 87 */ 88 typedef enum { 89 ESP_BT_MODE_IDLE = 0x00, /*!< Bluetooth is not running */ 90 ESP_BT_MODE_BLE = 0x01, /*!< Run BLE mode */ 91 ESP_BT_MODE_CLASSIC_BT = 0x02, /*!< Run Classic BT mode */ 92 ESP_BT_MODE_BTDM = 0x03, /*!< Run dual mode */ 93 } esp_bt_mode_t; 94 95 /** 96 * @brief Type of controller HCI transport layer 97 */ 98 typedef enum { 99 ESP_BT_CTRL_HCI_TL_UART = 0, /*!< HCI UART h4 transport layer */ 100 ESP_BT_CTRL_HCI_TL_VHCI = 1, /*!< VHCI interface */ 101 } esp_bt_ctrl_hci_tl_t; 102 103 /** 104 * @brief type of BLE connection event length computation 105 */ 106 typedef enum { 107 ESP_BLE_CE_LEN_TYPE_ORIG = 0, /*!< original */ 108 ESP_BLE_CE_LEN_TYPE_CE = 1, /*!< use CE_LEN parameter from HCI commands */ 109 ESP_BLE_CE_LEN_TYPE_SD = 1, /*!< Espressif vendor defined */ 110 } esp_ble_ce_len_t; 111 112 /** 113 * @brief Bluetooth sleep mode 114 */ 115 typedef enum { 116 ESP_BT_SLEEP_MODE_NONE = 0, /*!< Bluetooth sleep mode disabled */ 117 ESP_BT_SLEEP_MODE_1 = 1, /*!< Bluetooth sleep mode 1 */ 118 } esp_bt_sleep_mode_t; 119 120 /** 121 * @brief Bluetooth sleep clock 122 */ 123 typedef enum { 124 ESP_BT_SLEEP_CLOCK_NONE = 0, /*!< Sleep clock not configured */ 125 ESP_BT_SLEEP_CLOCK_MAIN_XTAL = 1, /*!< SoC main crystal */ 126 ESP_BT_SLEEP_CLOCK_EXT_32K_XTAL = 2, /*!< External 32.768kHz crystal */ 127 ESP_BT_SLEEP_CLOCK_RTC_SLOW = 3, /*!< Internal 136kHz RC oscillator */ 128 ESP_BT_SLEEP_CLOCK_FPGA_32K = 4, /*!< Hardwired 32KHz clock temporarily used for FPGA */ 129 } esp_bt_sleep_clock_t; 130 131 /** 132 * @brief antenna index used for bluetooth 133 */ 134 enum { 135 ESP_BT_ANT_IDX_0 = 0, /*!< anntena NO 0 */ 136 ESP_BT_ANT_IDX_1 = 1, /*!< anntena NO 1 */ 137 }; 138 139 /** 140 * @brief Maximum Tx/Rx time limit on Coded-PHY connection 141 */ 142 enum { 143 ESP_BT_COEX_PHY_CODED_TX_RX_TIME_LIMIT_FORCE_DISABLE = 0, /*!< Disable the limit */ 144 ESP_BT_COEX_PHY_CODED_TX_RX_TIME_LIMIT_FORCE_ENABLE, /*!< Always Enable the limit */ 145 }; 146 147 /* vendor dependent signals to be posted to controller task */ 148 typedef enum { 149 BTDM_VND_OL_SIG_WAKEUP_TMR = 0, 150 BTDM_VND_OL_SIG_NUM, 151 } btdm_vnd_ol_sig_t; 152 153 #define ESP_BT_HCI_TL_STATUS_OK (0) /*!< HCI_TL Tx/Rx operation status OK */ 154 155 /** 156 * @brief callback function for HCI Transport Layer send/receive operations 157 */ 158 typedef void (* esp_bt_hci_tl_callback_t) (void *arg, uint8_t status); 159 160 /* prototype of function to handle vendor dependent signals */ 161 typedef void (* btdm_vnd_ol_task_func_t)(void *param); 162 163 #ifdef CONFIG_BT_ENABLED 164 165 #define BT_CTRL_BLE_MAX_ACT_LIMIT 10 //Maximum BLE activity limitation 166 #define SLAVE_CE_LEN_MIN_DEFAULT 5 167 168 #ifdef CONFIG_BT_CTRL_SCAN_DUPL_TYPE 169 #define SCAN_DUPLICATE_TYPE_VALUE CONFIG_BT_CTRL_SCAN_DUPL_TYPE 170 #else 171 #define SCAN_DUPLICATE_TYPE_VALUE 0 172 #endif 173 174 /* normal adv cache size */ 175 #ifdef CONFIG_BT_CTRL_SCAN_DUPL_CACHE_SIZE 176 #define NORMAL_SCAN_DUPLICATE_CACHE_SIZE CONFIG_BT_CTRL_SCAN_DUPL_CACHE_SIZE 177 #else 178 #define NORMAL_SCAN_DUPLICATE_CACHE_SIZE 20 179 #endif 180 181 #ifndef CONFIG_BT_CTRL_BLE_MESH_SCAN_DUPL_EN 182 #define CONFIG_BT_CTRL_BLE_MESH_SCAN_DUPL_EN FALSE 183 #endif 184 185 #define SCAN_DUPLICATE_MODE_NORMAL_ADV_ONLY 0 186 #define SCAN_DUPLICATE_MODE_NORMAL_ADV_MESH_ADV 1 187 188 #if CONFIG_BT_CTRL_BLE_MESH_SCAN_DUPL_EN 189 #define SCAN_DUPLICATE_MODE SCAN_DUPLICATE_MODE_NORMAL_ADV_MESH_ADV 190 #ifdef CONFIG_BT_CTRL_MESH_DUPL_SCAN_CACHE_SIZE 191 #define MESH_DUPLICATE_SCAN_CACHE_SIZE CONFIG_BT_CTRL_MESH_DUPL_SCAN_CACHE_SIZE 192 #else 193 #define MESH_DUPLICATE_SCAN_CACHE_SIZE 50 194 #endif 195 #else 196 #define SCAN_DUPLICATE_MODE SCAN_DUPLICATE_MODE_NORMAL_ADV_ONLY 197 #define MESH_DUPLICATE_SCAN_CACHE_SIZE 0 198 #endif 199 200 #ifndef CONFIG_BT_CTRL_DUPL_SCAN_CACHE_REFRESH_PERIOD 201 #define DUPL_SCAN_CACHE_REFRESH_PERIOD 0 202 #else 203 #define DUPL_SCAN_CACHE_REFRESH_PERIOD CONFIG_BT_CTRL_DUPL_SCAN_CACHE_REFRESH_PERIOD 204 #endif 205 206 #ifdef CONFIG_BT_CTRL_SCAN_BACKOFF_UPPERLIMITMAX 207 #define BT_CTRL_SCAN_BACKOFF_UPPERLIMITMAX CONFIG_BT_CTRL_SCAN_BACKOFF_UPPERLIMITMAX 208 #else 209 #define BT_CTRL_SCAN_BACKOFF_UPPERLIMITMAX 0 210 #endif 211 212 #ifdef CONFIG_BT_CTRL_AGC_RECORRECT_EN 213 #define BT_CTRL_AGC_RECORRECT_EN CONFIG_BT_CTRL_AGC_RECORRECT_EN 214 // ESP32-S3 215 #if CONFIG_IDF_TARGET_ESP32S3 216 #define BT_CTRL_AGC_RECORRECT_NEW 1 217 #else 218 //Check if chip target is ESP32-C3 101 219 #if CONFIG_ESP32C3_REV_MIN_101 220 #define BT_CTRL_AGC_RECORRECT_NEW 1 221 #else 222 #define BT_CTRL_AGC_RECORRECT_NEW 0 223 #endif // CONFIG_ESP32C3_REV_MIN_101 224 #endif // CONFIG_IDF_TARGET_ESP32S3 225 226 #else 227 #define BT_CTRL_AGC_RECORRECT_EN 0 228 #define BT_CTRL_AGC_RECORRECT_NEW 0 229 #endif 230 231 #ifdef CONFIG_BT_CTRL_CODED_AGC_RECORRECT_EN 232 #define BT_CTRL_CODED_AGC_RECORRECT CONFIG_BT_CTRL_CODED_AGC_RECORRECT_EN 233 #else 234 #define BT_CTRL_CODED_AGC_RECORRECT 0 235 #endif 236 237 #if defined (CONFIG_BT_BLE_50_FEATURES_SUPPORTED) || defined (CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT) 238 #ifdef CONFIG_BT_BLE_50_FEATURES_SUPPORTED 239 #define BT_CTRL_50_FEATURE_SUPPORT (CONFIG_BT_BLE_50_FEATURES_SUPPORTED) 240 #endif // CONFIG_BT_BLE_50_FEATURES_SUPPORTED 241 #ifdef CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT 242 #define BT_CTRL_50_FEATURE_SUPPORT (CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT) 243 #endif // CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT 244 #else 245 #if defined (CONFIG_BT_BLUEDROID_ENABLED) || defined (CONFIG_BT_NIMBLE_ENABLED) 246 #define BT_CTRL_50_FEATURE_SUPPORT (0) 247 #else 248 #define BT_CTRL_50_FEATURE_SUPPORT (1) 249 #endif // (CONFIG_BT_BLUEDROID_ENABLED) || (CONFIG_BT_NIMBLE_ENABLED) 250 #endif // (CONFIG_BT_BLE_50_FEATURES_SUPPORTED) || (CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT) 251 252 #if defined(CONFIG_BT_BLE_CCA_MODE) 253 #define BT_BLE_CCA_MODE (CONFIG_BT_BLE_CCA_MODE) 254 #else 255 #define BT_BLE_CCA_MODE (0) 256 #endif 257 258 #if defined(CONFIG_BT_BLE_ADV_DATA_LENGTH_ZERO_AUX) 259 #define BT_BLE_ADV_DATA_LENGTH_ZERO_AUX (CONFIG_BT_BLE_ADV_DATA_LENGTH_ZERO_AUX) 260 #else 261 #define BT_BLE_ADV_DATA_LENGTH_ZERO_AUX (0) 262 #endif 263 264 #if defined(CONFIG_BT_CTRL_CHAN_ASS_EN) 265 #define BT_CTRL_CHAN_ASS_EN (CONFIG_BT_CTRL_CHAN_ASS_EN) 266 #else 267 #define BT_CTRL_CHAN_ASS_EN (0) 268 #endif 269 270 #if defined(CONFIG_BT_CTRL_LE_PING_EN) 271 #define BT_CTRL_LE_PING_EN (CONFIG_BT_CTRL_LE_PING_EN) 272 #else 273 #define BT_CTRL_LE_PING_EN (0) 274 #endif 275 276 #define AGC_RECORRECT_EN ((BT_CTRL_AGC_RECORRECT_EN << 0) | (BT_CTRL_CODED_AGC_RECORRECT <<1) | (BT_CTRL_AGC_RECORRECT_NEW << 2)) 277 278 #define CFG_MASK_BIT_SCAN_DUPLICATE_OPTION (1<<0) 279 280 #define CFG_MASK CFG_MASK_BIT_SCAN_DUPLICATE_OPTION 281 #if CONFIG_IDF_TARGET_ESP32C3 282 #define BLE_HW_TARGET_CODE_CHIP_ECO0 (0x01010000) 283 #else // CONFIG_IDF_TARGET_ESP32S3 284 #define BLE_HW_TARGET_CODE_CHIP_ECO0 (0x02010000) 285 #endif 286 287 #define BT_TASK_EXTRA_STACK_SIZE 512 288 #define ESP_TASK_BT_CONTROLLER_STACK (3584 + BT_TASK_EXTRA_STACK_SIZE) 289 #define ESP_TASK_BT_CONTROLLER_PRIO 4 290 291 #define BT_CONTROLLER_INIT_CONFIG_DEFAULT() { \ 292 .magic = ESP_BT_CTRL_CONFIG_MAGIC_VAL, \ 293 .version = ESP_BT_CTRL_CONFIG_VERSION, \ 294 .controller_task_stack_size = CONFIG_ESP32_BT_CONTROLLER_STACK_SIZE, \ 295 .controller_task_prio = CONFIG_ESP32_BT_CONTROLLER_TASK_PRIO, \ 296 .controller_task_run_cpu = 0, \ 297 .bluetooth_mode = 1, \ 298 .ble_max_act = 6, \ 299 .sleep_mode = 0, \ 300 .sleep_clock = 0, \ 301 .ble_st_acl_tx_buf_nb = 0, \ 302 .ble_hw_cca_check = 0, \ 303 .ble_adv_dup_filt_max = 30, \ 304 .coex_param_en = false, \ 305 .ce_len_type = 0, \ 306 .coex_use_hooks = false, \ 307 .hci_tl_type = 1, \ 308 .hci_tl_funcs = NULL, \ 309 .txant_dft = 0, \ 310 .rxant_dft = 0, \ 311 .txpwr_dft = ESP32_RADIO_TXP_DEFAULT, \ 312 .cfg_mask = CFG_MASK, \ 313 .scan_duplicate_mode = SCAN_DUPLICATE_MODE, \ 314 .scan_duplicate_type = SCAN_DUPLICATE_TYPE_VALUE, \ 315 .normal_adv_size = NORMAL_SCAN_DUPLICATE_CACHE_SIZE, \ 316 .mesh_adv_size = MESH_DUPLICATE_SCAN_CACHE_SIZE, \ 317 .coex_phy_coded_tx_rx_time_limit = 0, \ 318 .hw_target_code = BLE_HW_TARGET_CODE_CHIP_ECO0, \ 319 .slave_ce_len_min = SLAVE_CE_LEN_MIN_DEFAULT, \ 320 .hw_recorrect_en = AGC_RECORRECT_EN, \ 321 .cca_thresh = 20, \ 322 .scan_backoff_upperlimitmax = BT_CTRL_SCAN_BACKOFF_UPPERLIMITMAX, \ 323 .dup_list_refresh_period = DUPL_SCAN_CACHE_REFRESH_PERIOD, \ 324 .ble_50_feat_supp = BT_CTRL_50_FEATURE_SUPPORT, \ 325 .ble_cca_mode = BT_BLE_CCA_MODE, \ 326 .ble_data_lenth_zero_aux = BT_BLE_ADV_DATA_LENGTH_ZERO_AUX, \ 327 .ble_chan_ass_en = BT_CTRL_CHAN_ASS_EN, \ 328 .ble_ping_en = BT_CTRL_LE_PING_EN, \ 329 .ble_llcp_disc_flag = 0, \ 330 .run_in_flash = 0, \ 331 .dtm_en = 1, \ 332 .enc_en = 1, \ 333 .qa_test = 0, \ 334 .master_en = 0, \ 335 .scan_en = 1, \ 336 .ble_aa_check = 0, \ 337 } 338 339 #else 340 #define BT_CONTROLLER_INIT_CONFIG_DEFAULT() {0}; ESP_STATIC_ASSERT(0, "please enable bluetooth in menuconfig to use esp_bt.h"); 341 #endif 342 343 /** 344 * @brief Controller HCI transport layer function structure 345 * This structure shall be registered when HCI transport layer is UART 346 */ 347 typedef struct { 348 uint32_t _magic; /*!< Magic number */ 349 uint32_t _version; /*!< Version number of the defined structure */ 350 uint32_t _reserved; /*!< Reserved for future use */ 351 int (* _open)(void); /*!< HCI transport layer open function */ 352 void (* _close)(void); /*!< HCI transport layer close function */ 353 void (* _finish_transfers)(void); /*!< HCI transport layer finish transfers function */ 354 void (* _recv)(uint8_t *buf, uint32_t len, esp_bt_hci_tl_callback_t callback, void* arg); /*!< HCI transport layer receive function */ 355 void (* _send)(uint8_t *buf, uint32_t len, esp_bt_hci_tl_callback_t callback, void* arg); /*!< HCI transport layer send function */ 356 bool (* _flow_off)(void); /*!< HCI transport layer flow off function */ 357 void (* _flow_on)(void); /*!< HCI transport layer flow on function */ 358 } esp_bt_hci_tl_t; 359 360 /** 361 * @brief Controller config options, depend on config mask. 362 * Config mask indicate which functions enabled, this means 363 * some options or parameters of some functions enabled by config mask. 364 */ 365 typedef struct { 366 uint32_t magic; /*!< Magic number */ 367 uint32_t version; /*!< version number of the defined structure */ 368 uint16_t controller_task_stack_size; /*!< Bluetooth Controller task stack size in bytes */ 369 uint8_t controller_task_prio; /*!< Bluetooth Controller task priority */ 370 uint8_t controller_task_run_cpu; /*!< CPU number that Bluetooth Controller task runs on. Configurable in menuconfig. 371 - 0 - CPU 0 (default) 372 - 1 - CPU 1 */ 373 uint8_t bluetooth_mode; /*!< BLE mode */ 374 uint8_t ble_max_act; /*!< The maximum number of BLE instance. Configurable in menuconfig. 375 - Range: 1 - 10 376 - Default: 6 */ 377 uint8_t sleep_mode; /*!< Modem sleep mode. Configurable in menuconfig. 378 - 0 - Disable (default) 379 - 1 - Enable */ 380 uint8_t sleep_clock; /*!< Modem sleep clock source. Configurable in menuconfig. */ 381 uint8_t ble_st_acl_tx_buf_nb; /*!< Static ACL TX buffer numbers. Configurable in menuconfig. 382 - Range: 0 - 12 383 - Default: 0 */ 384 uint8_t ble_hw_cca_check; /*!< Deprecated */ 385 uint16_t ble_adv_dup_filt_max; /*!< The maximum number of extended duplicate scan filter. Configurable in menuconfig. 386 - Range: 1 - 500 387 - Default: 30 */ 388 bool coex_param_en; /*!< Deprecated */ 389 uint8_t ce_len_type; /*!< Connection event length determination method. Configurable in menuconfig. 390 - 0 - Original (default) 391 - 1 - use `CE_LEN` parameter from HCI commands 392 - 2 - Espressif vendor defined method */ 393 bool coex_use_hooks; /*!< Deprecated */ 394 uint8_t hci_tl_type; /*!< HCI transport layer type. Configurable in menuconfig. 395 - 0 - URAT 396 - 1 - Virtual HCI (default) */ 397 esp_bt_hci_tl_t *hci_tl_funcs; /*!< HCI transport functions used. It must be set when `hci_tl_type` is UART. */ 398 uint8_t txant_dft; /*!< Default TX antenna. Configurable in menuconfig. 399 - 0 - Antenna 0 (default) 400 - 1 - Antenna 1 */ 401 uint8_t rxant_dft; /*!< Default RX antenna. Configurable in menuconfig. 402 - 0 - Antenna 0 (default) 403 - 1 - Antenna 1 */ 404 uint8_t txpwr_dft; /*!< Default TX power. Please refer to `esp_power_level_t` for supported power level. Configurable in menuconfig. 405 - Default : `ESP_PWR_LVL_P9` +9 dBm. */ 406 uint32_t cfg_mask; /*!< Configuration mask to set specific options */ 407 uint8_t scan_duplicate_mode; /*!< Scan duplicate filtering mode. Configurable in menuconfig. 408 - 0 - Normal scan duplicate filtering mode (default) 409 - 1 - Special scan duplicate filtering mode for BLE Mesh */ 410 uint8_t scan_duplicate_type; /*!< Scan duplicate filtering type. If `scan_duplicate_mode` is set to 1, this parameter will be ignored. Configurable in menuconfig. 411 - 0 - Filter scan duplicates by device address only (default) 412 - 1 - Filter scan duplicates by advertising data only, even if they originate from different devices. 413 - 2 - Filter scan duplicated by device address and advertising data. */ 414 uint16_t normal_adv_size; /*!< Maximum number of devices in scan duplicate filtering list. Configurable in menuconfig. 415 - Range: 10 - 1000 416 - Default: 100 */ 417 uint16_t mesh_adv_size; /*!< Maximum number of Mesh advertising packets in scan duplicate filtering list. Configurable in menuconfig. 418 - Range: 10 - 1000 419 - Default: 100 */ 420 uint8_t coex_phy_coded_tx_rx_time_limit; /*!< Enable / disable the maximum TX/RX time limit for Coded-PHY connections in coexistence with Wi-Fi scenarios. Configurable in menuconfig. 421 - 0 - Disable (default) 422 - 1 - Enable */ 423 uint32_t hw_target_code; /*!< Hardware target. Internal use only. Please do not modify this value. */ 424 uint8_t slave_ce_len_min; /*!< Slave minimum connection event length: 5 slots. Please do not modify this value. */ 425 uint8_t hw_recorrect_en; /*!< Enable / disable uncoded phy / coded phy hardware re-correction. Configurable in menuconfig. */ 426 uint8_t cca_thresh; /*!< Absolute value of hardware-triggered CCA threshold. The CCA threshold is always negative. 427 If the channel assessment result exceeds the CCA threshold (e.g. -75 dBm), indicating the channel is busy, 428 the hardware will not transmit packets on that channel. Configurable in menuconfig. 429 - Range: 20 dBm - 100 dBm 430 - Default: 75 dBm */ 431 uint16_t scan_backoff_upperlimitmax; /*!< Enable / disable active scan backoff. Configurable in menuconfig. 432 - 0 - Disable (default) 433 - 1 - Enable */ 434 uint16_t dup_list_refresh_period; /*!< Scan duplicate filtering list refresh period in seconds. Configurable in menuconfig 435 - Range: 0 - 100 seconds 436 - Default: 0 second */ 437 bool ble_50_feat_supp; /*!< True if BLE 5.0 features are enabled; false otherwise. This option depends on whether the Host enable the 5.0 features. */ 438 uint8_t ble_cca_mode; /*!< BLE CCA mode. Configurable in menuconfig 439 - 0 - Disable (default) 440 - 1 - Hardware-triggered CCA 441 - 2 - Software-based CCA */ 442 uint8_t ble_data_lenth_zero_aux; /*!< Enable / disable auxiliary packets when the extended ADV data length is zero. Configurable in menuconfig. 443 - 0 - Disable (default) 444 - 1 - Enable */ 445 uint8_t ble_chan_ass_en; /*!< Enable / disable BLE channel assessment. Configurable in menuconfig. 446 - 0 - Disable 447 - 1 - Enable (default) */ 448 uint8_t ble_ping_en; /*!< Enable / disable BLE ping procedure. Configurable in menuconfig. 449 - 0 - Disable 450 - 1 - Enable (default) */ 451 uint8_t ble_llcp_disc_flag; /*!< Flag indicating whether the Controller disconnects after Instant Passed (0x28) error occurs. Configurable in menuconfig. 452 - The Controller does not disconnect after Instant Passed (0x28) by default. */ 453 bool run_in_flash; /*!< True if the Controller code is in flash (flash model); false otherwise (default). Configurable in menuconfig. */ 454 bool dtm_en; /*!< In the flash mode, True if the DTM feature is enabled; false otherwise (default). Configurable in menuconfig. */ 455 bool enc_en; /*!< In the flash mode, True if the encryption feature is enabled (default); false otherwise. Configurable in menuconfig. */ 456 bool qa_test; /*!< In the flash mode, True if the QA test feature is enabled; false otherwise (default). Configurable in menuconfig.*/ 457 bool master_en; /*!< In the flash mode, True if the master feature is enabled (default); false otherwise. Configurable in menuconfig.*/ 458 bool scan_en; /*!< In the flash mode, True if the scan feature is enabled (default); false otherwise. Configurable in menuconfig.*/ 459 bool ble_aa_check; /*!< True if adds a verification step for the Access Address within the CONNECT_IND PDU; false otherwise. Configurable in menuconfig */ 460 } esp_bt_controller_config_t; 461 462 /** 463 * @brief Bluetooth controller enable/disable/initialised/de-initialised status 464 */ 465 typedef enum { 466 ESP_BT_CONTROLLER_STATUS_IDLE = 0, 467 ESP_BT_CONTROLLER_STATUS_INITED, 468 ESP_BT_CONTROLLER_STATUS_ENABLED, 469 ESP_BT_CONTROLLER_STATUS_NUM, 470 } esp_bt_controller_status_t; 471 472 /** 473 * @brief BLE tx power type 474 * ESP_BLE_PWR_TYPE_CONN_HDL0-8: for each connection, and only be set after connection completed. 475 * when disconnect, the correspond TX power is not effected. 476 * ESP_BLE_PWR_TYPE_ADV : for advertising/scan response. 477 * ESP_BLE_PWR_TYPE_SCAN : for scan. 478 * ESP_BLE_PWR_TYPE_DEFAULT : if each connection's TX power is not set, it will use this default value. 479 * if neither in scan mode nor in adv mode, it will use this default value. 480 * If none of power type is set, system will use ESP_PWR_LVL_P3 as default for ADV/SCAN/CONN0-9. 481 */ 482 typedef enum { 483 ESP_BLE_PWR_TYPE_CONN_HDL0 = 0, /*!< For connection handle 0 */ 484 ESP_BLE_PWR_TYPE_CONN_HDL1 = 1, /*!< For connection handle 1 */ 485 ESP_BLE_PWR_TYPE_CONN_HDL2 = 2, /*!< For connection handle 2 */ 486 ESP_BLE_PWR_TYPE_CONN_HDL3 = 3, /*!< For connection handle 3 */ 487 ESP_BLE_PWR_TYPE_CONN_HDL4 = 4, /*!< For connection handle 4 */ 488 ESP_BLE_PWR_TYPE_CONN_HDL5 = 5, /*!< For connection handle 5 */ 489 ESP_BLE_PWR_TYPE_CONN_HDL6 = 6, /*!< For connection handle 6 */ 490 ESP_BLE_PWR_TYPE_CONN_HDL7 = 7, /*!< For connection handle 7 */ 491 ESP_BLE_PWR_TYPE_CONN_HDL8 = 8, /*!< For connection handle 8 */ 492 ESP_BLE_PWR_TYPE_ADV = 9, /*!< For advertising */ 493 ESP_BLE_PWR_TYPE_SCAN = 10, /*!< For scan */ 494 ESP_BLE_PWR_TYPE_DEFAULT = 11, /*!< For default, if not set other, it will use default value */ 495 ESP_BLE_PWR_TYPE_NUM = 12, /*!< TYPE numbers */ 496 } esp_ble_power_type_t; 497 498 /** 499 * @brief Bluetooth TX power level(index), it's just a index corresponding to power(dbm). 500 */ 501 typedef enum { 502 ESP_PWR_LVL_N24 = 0, /*!< Corresponding to -24dbm */ 503 ESP_PWR_LVL_N21 = 1, /*!< Corresponding to -21dbm */ 504 ESP_PWR_LVL_N18 = 2, /*!< Corresponding to -18dbm */ 505 ESP_PWR_LVL_N15 = 3, /*!< Corresponding to -15dbm */ 506 ESP_PWR_LVL_N12 = 4, /*!< Corresponding to -12dbm */ 507 ESP_PWR_LVL_N9 = 5, /*!< Corresponding to -9dbm */ 508 ESP_PWR_LVL_N6 = 6, /*!< Corresponding to -6dbm */ 509 ESP_PWR_LVL_N3 = 7, /*!< Corresponding to -3dbm */ 510 ESP_PWR_LVL_N0 = 8, /*!< Corresponding to 0dbm */ 511 ESP_PWR_LVL_P3 = 9, /*!< Corresponding to +3dbm */ 512 ESP_PWR_LVL_P6 = 10, /*!< Corresponding to +6dbm */ 513 ESP_PWR_LVL_P9 = 11, /*!< Corresponding to +9dbm */ 514 ESP_PWR_LVL_P12 = 12, /*!< Corresponding to +12dbm */ 515 ESP_PWR_LVL_P15 = 13, /*!< Corresponding to +15dbm */ 516 ESP_PWR_LVL_P18 = 14, /*!< Corresponding to +18dbm */ 517 ESP_PWR_LVL_P21 = 15, /*!< Corresponding to +21dbm */ 518 ESP_PWR_LVL_INVALID = 0xFF, /*!< Indicates an invalid value */ 519 } esp_power_level_t; 520 521 /** 522 * @brief The enhanced type of which tx power, could set Advertising/Connection/Default and etc. 523 */ 524 typedef enum { 525 ESP_BLE_ENHANCED_PWR_TYPE_DEFAULT = 0, 526 ESP_BLE_ENHANCED_PWR_TYPE_ADV, 527 ESP_BLE_ENHANCED_PWR_TYPE_SCAN, 528 ESP_BLE_ENHANCED_PWR_TYPE_INIT, 529 ESP_BLE_ENHANCED_PWR_TYPE_CONN, 530 ESP_BLE_ENHANCED_PWR_TYPE_MAX, 531 } esp_ble_enhanced_power_type_t; 532 533 /** 534 * @brief Set BLE TX power 535 * Connection Tx power should only be set after connection created. 536 * @param power_type : The type of which tx power, could set Advertising/Connection/Default and etc 537 * @param power_level: Power level(index) corresponding to absolute value(dbm) 538 * @return ESP_OK - success, other - failed 539 */ 540 esp_err_t esp_ble_tx_power_set(esp_ble_power_type_t power_type, esp_power_level_t power_level); 541 542 /** 543 * @brief Get BLE TX power 544 * Connection Tx power should only be get after connection created. 545 * @param power_type : The type of which tx power, could set Advertising/Connection/Default and etc 546 * @return >= 0 - Power level, < 0 - Invalid 547 */ 548 esp_power_level_t esp_ble_tx_power_get(esp_ble_power_type_t power_type); 549 550 /** 551 * @brief ENHANCED API for Setting BLE TX power 552 * Connection Tx power should only be set after connection created. 553 * @param power_type : The enhanced type of which tx power, could set Advertising/Connection/Default and etc. 554 * @param handle : The handle of Advertising or Connection and the value 0 for other enhanced power types. 555 * @param power_level: Power level(index) corresponding to absolute value(dbm) 556 * @return ESP_OK - success, other - failed 557 */ 558 esp_err_t esp_ble_tx_power_set_enhanced(esp_ble_enhanced_power_type_t power_type, uint16_t handle, esp_power_level_t power_level); 559 560 /** 561 * @brief ENHANCED API of Getting BLE TX power 562 * Connection Tx power should only be get after connection created. 563 * @param power_type : The enhanced type of which tx power, could set Advertising/Connection/Default and etc 564 * @param handle : The handle of Advertising or Connection and the value 0 for other enhanced power types. 565 * @return >= 0 - Power level, < 0 - Invalid 566 */ 567 esp_power_level_t esp_ble_tx_power_get_enhanced(esp_ble_enhanced_power_type_t power_type, uint16_t handle); 568 569 /** 570 * @brief Initialize BT controller to allocate task and other resource. 571 * This function should be called only once, before any other BT functions are called. 572 * @param cfg: Initial configuration of BT controller. Different from previous version, there's a mode and some 573 * connection configuration in "cfg" to configure controller work mode and allocate the resource which is needed. 574 * @return ESP_OK - success, other - failed 575 */ 576 esp_err_t esp_bt_controller_init(esp_bt_controller_config_t *cfg); 577 578 /** 579 * @brief De-initialize BT controller to free resource and delete task. 580 * You should stop advertising and scanning, as well as 581 * disconnect all existing connections before de-initializing BT controller. 582 * 583 * This function should be called only once, after any other BT functions are called. 584 * This function is not whole completed, esp_bt_controller_init cannot called after this function. 585 * @return ESP_OK - success, other - failed 586 */ 587 esp_err_t esp_bt_controller_deinit(void); 588 589 /** 590 * @brief Enable BT controller. 591 * Due to a known issue, you cannot call esp_bt_controller_enable() a second time 592 * to change the controller mode dynamically. To change controller mode, call 593 * esp_bt_controller_disable() and then call esp_bt_controller_enable() with the new mode. 594 * @param mode : the mode(BLE/BT/BTDM) to enable. For compatible of API, retain this argument. This mode must be 595 * equal as the mode in "cfg" of esp_bt_controller_init(). 596 * @return ESP_OK - success, other - failed 597 */ 598 esp_err_t esp_bt_controller_enable(esp_bt_mode_t mode); 599 600 /** 601 * @brief Disable BT controller 602 * @return ESP_OK - success, other - failed 603 */ 604 esp_err_t esp_bt_controller_disable(void); 605 606 /** 607 * @brief Get BT controller is initialised/de-initialised/enabled/disabled 608 * @return status value 609 */ 610 esp_bt_controller_status_t esp_bt_controller_get_status(void); 611 612 uint16_t esp_bt_get_tx_buf_num(void); 613 614 /** @brief esp_vhci_host_callback 615 * used for vhci call host function to notify what host need to do 616 */ 617 typedef struct esp_vhci_host_callback { 618 void (*notify_host_send_available)(void); /*!< callback used to notify that the host can send packet to controller */ 619 int (*notify_host_recv)(uint8_t *data, uint16_t len); /*!< callback used to notify that the controller has a packet to send to the host*/ 620 } esp_vhci_host_callback_t; 621 622 /** @brief esp_vhci_host_check_send_available 623 * used for check actively if the host can send packet to controller or not. 624 * @return true for ready to send, false means cannot send packet 625 */ 626 bool esp_vhci_host_check_send_available(void); 627 628 /** @brief esp_vhci_host_send_packet 629 * host send packet to controller 630 * 631 * Should not call this function from within a critical section 632 * or when the scheduler is suspended. 633 * 634 * @param data the packet point 635 * @param len the packet length 636 */ 637 void esp_vhci_host_send_packet(uint8_t *data, uint16_t len); 638 639 /** @brief esp_vhci_host_register_callback 640 * register the vhci reference callback 641 * struct defined by vhci_host_callback structure. 642 * @param callback esp_vhci_host_callback type variable 643 * @return ESP_OK - success, ESP_FAIL - failed 644 */ 645 esp_err_t esp_vhci_host_register_callback(const esp_vhci_host_callback_t *callback); 646 647 /** @brief esp_bt_controller_mem_release 648 * release the controller memory as per the mode 649 * 650 * This function releases the BSS, data and other sections of the controller to heap. The total size is about 70k bytes. 651 * 652 * esp_bt_controller_mem_release(mode) should be called only before esp_bt_controller_init() 653 * or after esp_bt_controller_deinit(). 654 * 655 * Note that once BT controller memory is released, the process cannot be reversed. It means you cannot use the bluetooth 656 * mode which you have released by this function. 657 * 658 * If your firmware will later upgrade the Bluetooth controller mode (BLE -> BT Classic or disabled -> enabled) 659 * then do not call this function. 660 * 661 * If the app calls esp_bt_controller_enable(ESP_BT_MODE_BLE) to use BLE only then it is safe to call 662 * esp_bt_controller_mem_release(ESP_BT_MODE_CLASSIC_BT) at initialization time to free unused BT Classic memory. 663 * 664 * If the mode is ESP_BT_MODE_BTDM, then it may be useful to call API esp_bt_mem_release(ESP_BT_MODE_BTDM) instead, 665 * which internally calls esp_bt_controller_mem_release(ESP_BT_MODE_BTDM) and additionally releases the BSS and data 666 * consumed by the BT/BLE host stack to heap. For more details about usage please refer to the documentation of 667 * esp_bt_mem_release() function 668 * 669 * @param mode : the mode want to release memory 670 * @return ESP_OK - success, other - failed 671 */ 672 esp_err_t esp_bt_controller_mem_release(esp_bt_mode_t mode); 673 674 /** @brief esp_bt_mem_release 675 * release controller memory and BSS and data section of the BT/BLE host stack as per the mode 676 * 677 * This function first releases controller memory by internally calling esp_bt_controller_mem_release(). 678 * Additionally, if the mode is set to ESP_BT_MODE_BTDM, it also releases the BSS and data consumed by the BT/BLE host stack to heap 679 * 680 * Note that once BT memory is released, the process cannot be reversed. It means you cannot use the bluetooth 681 * mode which you have released by this function. 682 * 683 * If your firmware will later upgrade the Bluetooth controller mode (BLE -> BT Classic or disabled -> enabled) 684 * then do not call this function. 685 * 686 * If you never intend to use bluetooth in a current boot-up cycle, you can call esp_bt_mem_release(ESP_BT_MODE_BTDM) 687 * before esp_bt_controller_init or after esp_bt_controller_deinit. 688 * 689 * For example, if a user only uses bluetooth for setting the WiFi configuration, and does not use bluetooth in the rest of the product operation". 690 * In such cases, after receiving the WiFi configuration, you can disable/deinit bluetooth and release its memory. 691 * Below is the sequence of APIs to be called for such scenarios: 692 * 693 * esp_bluedroid_disable(); 694 * esp_bluedroid_deinit(); 695 * esp_bt_controller_disable(); 696 * esp_bt_controller_deinit(); 697 * esp_bt_mem_release(ESP_BT_MODE_BTDM); 698 * 699 * @param mode : the mode whose memory is to be released 700 * @return ESP_OK - success, other - failed 701 */ 702 esp_err_t esp_bt_mem_release(esp_bt_mode_t mode); 703 704 /** 705 * @brief enable bluetooth to enter modem sleep 706 * 707 * Note that this function shall not be invoked before esp_bt_controller_enable() 708 * 709 * There are currently two options for bluetooth modem sleep, one is ORIG mode, and another is EVED Mode. EVED Mode is intended for BLE only. 710 * 711 * For ORIG mode: 712 * Bluetooth modem sleep is enabled in controller start up by default if CONFIG_BTDM_CONTROLLER_MODEM_SLEEP is set and "ORIG mode" is selected. In ORIG modem sleep mode, bluetooth controller will switch off some components and pause to work every now and then, if there is no event to process; and wakeup according to the scheduled interval and resume the work. It can also wakeup earlier upon external request using function "esp_bt_controller_wakeup_request". 713 * 714 * @return 715 * - ESP_OK : success 716 * - other : failed 717 */ 718 esp_err_t esp_bt_sleep_enable(void); 719 720 721 /** 722 * @brief disable bluetooth modem sleep 723 * 724 * Note that this function shall not be invoked before esp_bt_controller_enable() 725 * 726 * If esp_bt_sleep_disable() is called, bluetooth controller will not be allowed to enter modem sleep; 727 * 728 * If ORIG modem sleep mode is in use, if this function is called, bluetooth controller may not immediately wake up if it is dormant then. 729 * In this case, esp_bt_controller_wakeup_request() can be used to shorten the time for wakeup. 730 * 731 * @return 732 * - ESP_OK : success 733 * - other : failed 734 */ 735 esp_err_t esp_bt_sleep_disable(void); 736 737 /** 738 * @brief to check whether bluetooth controller is sleeping at the instant, if modem sleep is enabled 739 * 740 * Note that this function shall not be invoked before esp_bt_controller_enable() 741 * This function is supposed to be used ORIG mode of modem sleep 742 * 743 * @return true if in modem sleep state, false otherwise 744 */ 745 bool esp_bt_controller_is_sleeping(void); 746 747 /** 748 * @brief request controller to wakeup from sleeping state during sleep mode 749 * 750 * Note that this function shall not be invoked before esp_bt_controller_enable() 751 * Note that this function is supposed to be used ORIG mode of modem sleep 752 * Note that after this request, bluetooth controller may again enter sleep as long as the modem sleep is enabled 753 * 754 * Profiling shows that it takes several milliseconds to wakeup from modem sleep after this request. 755 * Generally it takes longer if 32kHz XTAL is used than the main XTAL, due to the lower frequency of the former as the bluetooth low power clock source. 756 */ 757 void esp_bt_controller_wakeup_request(void); 758 759 /** 760 * @brief notify bluetooth controller task to process the event upon Tx or Rx done 761 * 762 * Note that this function shall not be invoked before esp_bt_controller_enable() 763 * This function can be called in both ISR and non-ISR context 764 * 765 */ 766 int esp_bt_h4tl_eif_io_event_notify(int event); 767 768 /** 769 * @brief bt Wi-Fi power domain power on 770 */ 771 void esp_wifi_bt_power_domain_on(void); 772 773 /** 774 * @brief bt Wi-Fi power domain power off 775 */ 776 void esp_wifi_bt_power_domain_off(void); 777 778 /** 779 * @brief Get the Bluetooth module sleep clock source. 780 * 781 * Note that this function shall not be invoked before esp_bt_controller_init() 782 * 783 * @return clock source used in Bluetooth low power mode 784 */ 785 esp_bt_sleep_clock_t esp_bt_get_lpclk_src(void); 786 787 #ifdef __cplusplus 788 } 789 #endif 790 791 #endif /* __ESP_BT_H__ */ 792
