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 #ifdef CONFIG_BT_ENABLED 21 22 #define SOC_MEM_BT_DATA_START 0x3ffae6e0 23 #define SOC_MEM_BT_DATA_END 0x3ffaff10 24 #define SOC_MEM_BT_EM_START 0x3ffb0000 25 #define SOC_MEM_BT_EM_END 0x3ffb7cd8 26 #define SOC_MEM_BT_EM_BTDM0_START 0x3ffb0000 27 #define SOC_MEM_BT_EM_BTDM0_END 0x3ffb09a8 28 #define SOC_MEM_BT_EM_BLE_START 0x3ffb09a8 29 #define SOC_MEM_BT_EM_BLE_END 0x3ffb1ddc 30 #define SOC_MEM_BT_EM_BTDM1_START 0x3ffb1ddc 31 #define SOC_MEM_BT_EM_BTDM1_END 0x3ffb2730 32 #define SOC_MEM_BT_EM_BREDR_START 0x3ffb2730 33 #define SOC_MEM_BT_EM_BREDR_NO_SYNC_END 0x3ffb6388 //Not calculate with synchronize connection support 34 #define SOC_MEM_BT_EM_BREDR_END 0x3ffb7cd8 //Calculate with synchronize connection support 35 #define SOC_MEM_BT_EM_SYNC0_START 0x3ffb6388 36 #define SOC_MEM_BT_EM_SYNC0_END 0x3ffb6bf8 37 #define SOC_MEM_BT_EM_SYNC1_START 0x3ffb6bf8 38 #define SOC_MEM_BT_EM_SYNC1_END 0x3ffb7468 39 #define SOC_MEM_BT_EM_SYNC2_START 0x3ffb7468 40 #define SOC_MEM_BT_EM_SYNC2_END 0x3ffb7cd8 41 #define SOC_MEM_BT_BSS_START 0x3ffb8000 42 #define SOC_MEM_BT_BSS_END 0x3ffb9a20 43 #define SOC_MEM_BT_MISC_START 0x3ffbdb28 44 #define SOC_MEM_BT_MISC_END 0x3ffbdb5c 45 46 #define SOC_MEM_BT_EM_PER_SYNC_SIZE 0x870 47 48 #define SOC_MEM_BT_EM_BREDR_REAL_END (SOC_MEM_BT_EM_BREDR_NO_SYNC_END + 0 * SOC_MEM_BT_EM_PER_SYNC_SIZE) 49 50 #endif //CONFIG_BT_ENABLED 51 52 /** 53 * @brief Internal use only 54 * 55 * @note Please do not modify this value. 56 */ 57 #define ESP_BT_CONTROLLER_CONFIG_MAGIC_VAL 0x20241024 58 59 #if defined(CONFIG_BT_CTLR_TX_PWR_PLUS_9) 60 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_P9 61 #elif defined(CONFIG_BT_CTLR_TX_PWR_PLUS_6) 62 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_P6 63 #elif defined(CONFIG_BT_CTLR_TX_PWR_PLUS_3) 64 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_P3 65 #elif defined(CONFIG_BT_CTLR_TX_PWR_0) 66 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_N0 67 #elif defined(CONFIG_BT_CTLR_TX_PWR_MINUS_3) 68 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_N3 69 #elif defined(CONFIG_BT_CTLR_TX_PWR_MINUS_6) 70 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_N6 71 #elif defined(CONFIG_BT_CTLR_TX_PWR_MINUS_9) 72 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_N9 73 #elif defined(CONFIG_BT_CTLR_TX_PWR_MINUS_12) 74 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_N12 75 #else 76 /* use 0dB TX power as default */ 77 #define ESP32_RADIO_TXP_DEFAULT ESP_PWR_LVL_N0 78 #endif 79 80 /** 81 * @brief Bluetooth Controller mode 82 */ 83 typedef enum { 84 ESP_BT_MODE_IDLE = 0x00, /*!< Bluetooth is not operating. */ 85 ESP_BT_MODE_BLE = 0x01, /*!< Bluetooth is operating in BLE mode. */ 86 ESP_BT_MODE_CLASSIC_BT = 0x02, /*!< Bluetooth is operating in Classic Bluetooth mode. */ 87 ESP_BT_MODE_BTDM = 0x03, /*!< Bluetooth is operating in Dual mode. */ 88 } esp_bt_mode_t; 89 90 /** 91 * @brief BLE sleep clock accuracy (SCA) 92 * 93 * @note Currently only ESP_BLE_SCA_500PPM and ESP_BLE_SCA_250PPM are supported. 94 */ 95 typedef enum { 96 ESP_BLE_SCA_500PPM = 0, /*!< BLE SCA at 500 ppm */ 97 ESP_BLE_SCA_250PPM, /*!< BLE SCA at 250 ppm */ 98 ESP_BLE_SCA_150PPM, /*!< BLE SCA at 150 ppm */ 99 ESP_BLE_SCA_100PPM, /*!< BLE SCA at 100 ppm */ 100 ESP_BLE_SCA_75PPM, /*!< BLE SCA at 75 ppm */ 101 ESP_BLE_SCA_50PPM, /*!< BLE SCA at 50 ppm */ 102 ESP_BLE_SCA_30PPM, /*!< BLE SCA at 30 ppm */ 103 ESP_BLE_SCA_20PPM, /*!< BLE SCA at 20 ppm */ 104 } esp_ble_sca_t; 105 106 #ifdef CONFIG_BT_ENABLED 107 /* While scanning, if the free memory value in controller is less than SCAN_SEND_ADV_RESERVED_SIZE, 108 the adv packet will be discarded until the memory is restored. */ 109 #define SCAN_SEND_ADV_RESERVED_SIZE 1000 110 /* enable controller log debug when adv lost */ 111 #define CONTROLLER_ADV_LOST_DEBUG_BIT (0<<0) 112 113 #ifdef CONFIG_BTDM_CTRL_HCI_UART_NO 114 #define BT_HCI_UART_NO_DEFAULT CONFIG_BTDM_CTRL_HCI_UART_NO 115 #else 116 #define BT_HCI_UART_NO_DEFAULT 1 117 #endif /* BT_HCI_UART_NO_DEFAULT */ 118 119 #ifdef CONFIG_BTDM_CTRL_HCI_UART_BAUDRATE 120 #define BT_HCI_UART_BAUDRATE_DEFAULT CONFIG_BTDM_CTRL_HCI_UART_BAUDRATE 121 #else 122 #define BT_HCI_UART_BAUDRATE_DEFAULT 921600 123 #endif /* BT_HCI_UART_BAUDRATE_DEFAULT */ 124 125 #ifdef CONFIG_BTDM_SCAN_DUPL_TYPE 126 #define SCAN_DUPLICATE_TYPE_VALUE CONFIG_BTDM_SCAN_DUPL_TYPE 127 #else 128 #define SCAN_DUPLICATE_TYPE_VALUE 0 129 #endif 130 131 /* normal adv cache size */ 132 #ifdef CONFIG_BTDM_SCAN_DUPL_CACHE_SIZE 133 #define NORMAL_SCAN_DUPLICATE_CACHE_SIZE CONFIG_BTDM_SCAN_DUPL_CACHE_SIZE 134 #else 135 #define NORMAL_SCAN_DUPLICATE_CACHE_SIZE 20 136 #endif 137 138 #ifndef CONFIG_BTDM_BLE_MESH_SCAN_DUPL_EN 139 #define CONFIG_BTDM_BLE_MESH_SCAN_DUPL_EN FALSE 140 #endif 141 142 #define SCAN_DUPLICATE_MODE_NORMAL_ADV_ONLY 0 143 #define SCAN_DUPLICATE_MODE_NORMAL_ADV_MESH_ADV 1 144 145 #if CONFIG_BTDM_BLE_MESH_SCAN_DUPL_EN 146 #define SCAN_DUPLICATE_MODE SCAN_DUPLICATE_MODE_NORMAL_ADV_MESH_ADV 147 #ifdef CONFIG_BTDM_MESH_DUPL_SCAN_CACHE_SIZE 148 #define MESH_DUPLICATE_SCAN_CACHE_SIZE CONFIG_BTDM_MESH_DUPL_SCAN_CACHE_SIZE 149 #else 150 #define MESH_DUPLICATE_SCAN_CACHE_SIZE 50 151 #endif 152 #else 153 #define SCAN_DUPLICATE_MODE SCAN_DUPLICATE_MODE_NORMAL_ADV_ONLY 154 #define MESH_DUPLICATE_SCAN_CACHE_SIZE 0 155 #endif 156 157 #ifdef CONFIG_BTDM_SCAN_DUPL_CACHE_REFRESH_PERIOD 158 #define SCAN_DUPL_CACHE_REFRESH_PERIOD CONFIG_BTDM_SCAN_DUPL_CACHE_REFRESH_PERIOD 159 #else 160 #define SCAN_DUPL_CACHE_REFRESH_PERIOD 0 161 #endif 162 163 #if defined(CONFIG_BTDM_CTRL_MODE_BLE_ONLY) 164 #define BTDM_CONTROLLER_MODE_EFF ESP_BT_MODE_BLE 165 #elif defined(CONFIG_BTDM_CTRL_MODE_BR_EDR_ONLY) 166 #define BTDM_CONTROLLER_MODE_EFF ESP_BT_MODE_CLASSIC_BT 167 #else 168 #define BTDM_CONTROLLER_MODE_EFF ESP_BT_MODE_BTDM 169 #endif 170 171 #ifdef CONFIG_BTDM_CTRL_AUTO_LATENCY_EFF 172 #define BTDM_CTRL_AUTO_LATENCY_EFF CONFIG_BTDM_CTRL_AUTO_LATENCY_EFF 173 #else 174 #define BTDM_CTRL_AUTO_LATENCY_EFF false 175 #endif 176 177 #ifdef CONFIG_BTDM_CTRL_HLI 178 #define BTDM_CTRL_HLI CONFIG_BTDM_CTRL_HLI 179 #else 180 #define BTDM_CTRL_HLI false 181 #endif 182 183 #ifdef CONFIG_BTDM_CTRL_LEGACY_AUTH_VENDOR_EVT_EFF 184 #define BTDM_CTRL_LEGACY_AUTH_VENDOR_EVT_EFF CONFIG_BTDM_CTRL_LEGACY_AUTH_VENDOR_EVT_EFF 185 #else 186 #define BTDM_CTRL_LEGACY_AUTH_VENDOR_EVT_EFF false 187 #endif 188 189 #define BTDM_CONTROLLER_BLE_MAX_CONN_LIMIT 9 //Maximum BLE connection limitation 190 #define BTDM_CONTROLLER_BR_EDR_MAX_ACL_CONN_LIMIT 7 //Maximum ACL connection limitation 191 #define BTDM_CONTROLLER_BR_EDR_MAX_SYNC_CONN_LIMIT 3 //Maximum SCO/eSCO connection limitation 192 193 #define BTDM_CONTROLLER_SCO_DATA_PATH_HCI 0 // SCO data is routed to HCI 194 #define BTDM_CONTROLLER_SCO_DATA_PATH_PCM 1 // SCO data path is PCM 195 196 #ifdef CONFIG_BTDM_CTRL_SCAN_BACKOFF_UPPERLIMITMAX 197 #define BTDM_CTRL_SCAN_BACKOFF_UPPERLIMITMAX CONFIG_BTDM_CTRL_SCAN_BACKOFF_UPPERLIMITMAX 198 #else 199 #define BTDM_CTRL_SCAN_BACKOFF_UPPERLIMITMAX 0 200 #endif 201 202 #ifdef CONFIG_BTDM_BLE_LLCP_CONN_UPDATE 203 #define BTDM_BLE_LLCP_CONN_UPDATE (1<<0) 204 #else 205 #define BTDM_BLE_LLCP_CONN_UPDATE (0<<0) 206 #endif 207 208 #ifdef CONFIG_BTDM_BLE_LLCP_CHAN_MAP_UPDATE 209 #define BTDM_BLE_LLCP_CHAN_MAP_UPDATE (1<<1) 210 #else 211 #define BTDM_BLE_LLCP_CHAN_MAP_UPDATE (0<<1) 212 #endif 213 214 #define BTDM_BLE_LLCP_DISC_FLAG (BTDM_BLE_LLCP_CONN_UPDATE | BTDM_BLE_LLCP_CHAN_MAP_UPDATE) 215 216 #ifdef CONFIG_BTDM_CTRL_CHECK_CONNECT_IND_ACCESS_ADDRESS 217 #define BTDM_CTRL_CHECK_CONNECT_IND_ACCESS_ADDRESS_ENABLED CONFIG_BTDM_CTRL_CHECK_CONNECT_IND_ACCESS_ADDRESS 218 #else 219 #define BTDM_CTRL_CHECK_CONNECT_IND_ACCESS_ADDRESS_ENABLED 0 220 #endif 221 222 #if defined(CONFIG_BTDM_BLE_CHAN_ASS_EN) 223 #define BTDM_BLE_CHAN_ASS_EN (CONFIG_BTDM_BLE_CHAN_ASS_EN) 224 #else 225 #define BTDM_BLE_CHAN_ASS_EN (0) 226 #endif 227 228 #if defined(CONFIG_BTDM_BLE_PING_EN) 229 #define BTDM_BLE_PING_EN (CONFIG_BTDM_BLE_PING_EN) 230 #else 231 #define BTDM_BLE_PING_EN (0) 232 #endif 233 234 /** 235 * @brief Default Bluetooth Controller configuration 236 */ 237 #define BT_CONTROLLER_INIT_CONFIG_DEFAULT() { \ 238 .controller_task_stack_size = CONFIG_ESP32_BT_CONTROLLER_STACK_SIZE, \ 239 .controller_task_prio = CONFIG_ESP32_BT_CONTROLLER_TASK_PRIO, \ 240 .hci_uart_no = BT_HCI_UART_NO_DEFAULT, \ 241 .hci_uart_baudrate = BT_HCI_UART_BAUDRATE_DEFAULT, \ 242 .scan_duplicate_mode = SCAN_DUPLICATE_MODE, \ 243 .scan_duplicate_type = SCAN_DUPLICATE_TYPE_VALUE, \ 244 .normal_adv_size = NORMAL_SCAN_DUPLICATE_CACHE_SIZE, \ 245 .mesh_adv_size = MESH_DUPLICATE_SCAN_CACHE_SIZE, \ 246 .send_adv_reserved_size = SCAN_SEND_ADV_RESERVED_SIZE, \ 247 .controller_debug_flag = CONTROLLER_ADV_LOST_DEBUG_BIT, \ 248 .mode = ESP_BT_MODE_BLE, \ 249 .ble_max_conn = 3, \ 250 .bt_max_acl_conn = 2, \ 251 .bt_sco_datapath = 0, \ 252 .auto_latency = BTDM_CTRL_AUTO_LATENCY_EFF, \ 253 .bt_legacy_auth_vs_evt = BTDM_CTRL_LEGACY_AUTH_VENDOR_EVT_EFF, \ 254 .bt_max_sync_conn = 0, \ 255 .ble_sca = 1, \ 256 .pcm_role = 0, \ 257 .pcm_polar = 0, \ 258 .pcm_fsyncshp = 0, \ 259 .hli = BTDM_CTRL_HLI, \ 260 .dup_list_refresh_period = SCAN_DUPL_CACHE_REFRESH_PERIOD, \ 261 .ble_scan_backoff = BTDM_CTRL_SCAN_BACKOFF_UPPERLIMITMAX, \ 262 .ble_llcp_disc_flag = BTDM_BLE_LLCP_DISC_FLAG, \ 263 .ble_aa_check = BTDM_CTRL_CHECK_CONNECT_IND_ACCESS_ADDRESS_ENABLED, \ 264 .ble_chan_ass_en = BTDM_BLE_CHAN_ASS_EN, \ 265 .ble_ping_en = BTDM_BLE_PING_EN, \ 266 .magic = ESP_BT_CONTROLLER_CONFIG_MAGIC_VAL, \ 267 } 268 269 #else 270 /** 271 * @brief Default Bluetooth Controller configuration 272 */ 273 #define BT_CONTROLLER_INIT_CONFIG_DEFAULT() {0}; ESP_STATIC_ASSERT(0, "please enable bluetooth in menuconfig to use esp_bt.h"); 274 #endif 275 276 /** 277 * @brief Bluetooth Controller config options 278 * @note 279 * 1. For parameters configurable in menuconfig, please refer to menuconfig for details on range and default values. 280 * 2. It is not recommended to modify the default values of `controller_task_stack_size`, `controller_task_prio`. 281 */ 282 typedef struct { 283 uint16_t controller_task_stack_size; /*!< Bluetooth Controller task stack size in bytes */ 284 uint8_t controller_task_prio; /*!< Bluetooth Controller task priority */ 285 uint8_t hci_uart_no; /*!< UART number as HCI I/O interface. Configurable in menuconfig. 286 - 1 - URAT 1 (default) 287 - 2 - URAT 2 */ 288 uint32_t hci_uart_baudrate; /*!< UART baudrate. Configurable in menuconfig. 289 - Range: 115200 - 921600 290 - Default: 921600 */ 291 uint8_t scan_duplicate_mode; /*!< Scan duplicate filtering mode. Configurable in menuconfig. 292 - 0 - Normal scan duplicate filtering mode (default) 293 - 1 - Special scan duplicate filtering mode for BLE Mesh */ 294 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. 295 - 0 - Filter scan duplicates by device address only (default) 296 - 1 - Filter scan duplicates by advertising data only, even if they originate from different devices. 297 - 2 - Filter scan duplicated by device address and advertising data. */ 298 uint16_t normal_adv_size; /*!< Maximum number of devices in scan duplicate filtering list. Configurable in menuconfig 299 - Range: 10 - 1000 300 - Default: 100 */ 301 uint16_t mesh_adv_size; /*!< Maximum number of Mesh advertising packets in scan duplicate filtering list. Configurable in menuconfig 302 - Range: 10 - 1000 303 - Default: 100 */ 304 uint16_t send_adv_reserved_size; /*!< Controller minimum memory value in bytes. Internal use only */ 305 uint32_t controller_debug_flag; /*!< Controller debug log flag. Internal use only */ 306 uint8_t mode; /*!< Controller mode. Configurable in menuconfig 307 - 1 - BLE mode 308 - 2 - Classic Bluetooth mode 309 - 3 - Dual mode 310 - 4 - Others: Invalid */ 311 uint8_t ble_max_conn; /*!< Maximum number of BLE connections. Configurable in menuconfig 312 - Range: 1 - 9 313 - Default: 3 */ 314 uint8_t bt_max_acl_conn; /*!< Maximum number of BR/EDR ACL connections. Configurable in menuconfig 315 - Range: 1 - 7 316 - Default: 2 */ 317 uint8_t bt_sco_datapath; /*!< SCO data path. Configurable in menuconfig 318 - 0 - HCI module (default) 319 - 1 - PCM module */ 320 bool auto_latency; /*!< True if BLE auto latency is enabled, used to enhance Classic Bluetooth performance in the Dual mode; false otherwise (default). Configurable in menuconfig */ 321 bool bt_legacy_auth_vs_evt; /*!< True if BR/EDR Legacy Authentication Vendor Specific Event is enabled (default in the classic bluetooth or Dual mode), which is required to protect from BIAS attack; false otherwise. Configurable in menuconfig */ 322 uint8_t bt_max_sync_conn; /*!< Maximum number of BR/EDR synchronous connections. Configurable in menuconfig 323 - Range: 0 - 3 324 - Default: 0 */ 325 uint8_t ble_sca; /*!< BLE low power crystal accuracy index. Configurable in menuconfig 326 - 0 - `BTDM_BLE_DEFAULT_SCA_500PPM` 327 - 1 - `BTDM_BLE_DEFAULT_SCA_250PPM` (default) */ 328 uint8_t pcm_role; /*!< PCM role. Configurable in menuconfig 329 - 0 - PCM master (default) 330 - 1 - PCM slave (default) */ 331 uint8_t pcm_polar; /*!< PCM polarity (falling clk edge & rising clk edge). Configurable in menuconfig 332 - 0 - Falling Edge (default) 333 - 1 - Rising Edge */ 334 uint8_t pcm_fsyncshp; /*!< Physical shape of the PCM Frame Synchronization signal. Configurable in menuconfig 335 - 0 - Stereo Mode (default) 336 - 1 - Mono Mode 1 337 - 2 - Mono Mode 2 */ 338 bool hli; /*!< True if using high-level (level 4) interrupt (default); false otherwise. Configurable in menuconfig */ 339 uint16_t dup_list_refresh_period; /*!< Scan duplicate filtering list refresh period in seconds. Configurable in menuconfig 340 - Range: 0 - 100 seconds 341 - Default: 0 second */ 342 bool ble_scan_backoff; /*!< True if BLE scan backoff is enabled; false otherwise (default). Configurable in menuconfig */ 343 uint8_t ble_llcp_disc_flag; /*!< Flag indicating whether the Controller disconnects after Instant Passed (0x28) error occurs. Configurable in menuconfig. 344 - The Controller does not disconnect after Instant Passed (0x28) by default. */ 345 bool ble_aa_check; /*!< True if adds a verification step for the Access Address within the `CONNECT_IND` PDU; false otherwise (default). Configurable in menuconfig */ 346 uint8_t ble_chan_ass_en; /*!< True if BLE channel assessment is enabled (default), false otherwise. Configurable in menuconfig */ 347 uint8_t ble_ping_en; /*!< True if BLE ping procedure is enabled (default), false otherwise. Configurable in menuconfig */ 348 uint32_t magic; /*!< Magic number */ 349 } esp_bt_controller_config_t; 350 351 /** 352 * @brief Bluetooth Controller status 353 */ 354 typedef enum { 355 ESP_BT_CONTROLLER_STATUS_IDLE = 0, /*!< The Controller is not initialized or has been de-initialized.*/ 356 ESP_BT_CONTROLLER_STATUS_INITED, /*!< The Controller has been initialized, but not enabled or has been disabled. */ 357 ESP_BT_CONTROLLER_STATUS_ENABLED, /*!< The Controller has been initialized and enabled. */ 358 ESP_BT_CONTROLLER_STATUS_NUM, /*!< Number of Controller statuses */ 359 } esp_bt_controller_status_t; 360 361 /** 362 * @brief BLE TX power type 363 * @note 364 * 1. The connection TX power can only be set after the connection is established. 365 * After disconnecting, the corresponding TX power will not be affected. 366 * 2. `ESP_BLE_PWR_TYPE_DEFAULT` can be used to set the TX power for power types that have not been set before. 367 * It will not affect the TX power values which have been set for the following CONN0-8/ADV/SCAN power types. 368 * 3. If none of power type is set, the system will use `ESP_PWR_LVL_P3` as default for all power types. 369 */ 370 typedef enum { 371 ESP_BLE_PWR_TYPE_CONN_HDL0 = 0, /*!< TX power for connection handle 0 */ 372 ESP_BLE_PWR_TYPE_CONN_HDL1 = 1, /*!< TX power for connection handle 1 */ 373 ESP_BLE_PWR_TYPE_CONN_HDL2 = 2, /*!< TX power for connection handle 2 */ 374 ESP_BLE_PWR_TYPE_CONN_HDL3 = 3, /*!< TX power for connection handle 3 */ 375 ESP_BLE_PWR_TYPE_CONN_HDL4 = 4, /*!< TX power for connection handle 4 */ 376 ESP_BLE_PWR_TYPE_CONN_HDL5 = 5, /*!< TX power for connection handle 5 */ 377 ESP_BLE_PWR_TYPE_CONN_HDL6 = 6, /*!< TX power for connection handle 6 */ 378 ESP_BLE_PWR_TYPE_CONN_HDL7 = 7, /*!< TX power for connection handle 7 */ 379 ESP_BLE_PWR_TYPE_CONN_HDL8 = 8, /*!< TX power for connection handle 8 */ 380 ESP_BLE_PWR_TYPE_ADV = 9, /*!< TX power for advertising */ 381 ESP_BLE_PWR_TYPE_SCAN = 10, /*!< TX power for scan */ 382 ESP_BLE_PWR_TYPE_DEFAULT = 11, /*!< Default TX power type, which can be used to set the TX power for power types that have not been set before.*/ 383 ESP_BLE_PWR_TYPE_NUM = 12, /*!< Number of types */ 384 } esp_ble_power_type_t; 385 386 /** 387 * @brief Bluetooth TX power level (index). Each index corresponds to a specific power value in dBm. 388 */ 389 typedef enum { 390 ESP_PWR_LVL_N12 = 0, /*!< Corresponding to -12 dBm */ 391 ESP_PWR_LVL_N9 = 1, /*!< Corresponding to -9 dBm */ 392 ESP_PWR_LVL_N6 = 2, /*!< Corresponding to -6 dBm */ 393 ESP_PWR_LVL_N3 = 3, /*!< Corresponding to -3 dBm */ 394 ESP_PWR_LVL_N0 = 4, /*!< Corresponding to 0 dBm */ 395 ESP_PWR_LVL_P3 = 5, /*!< Corresponding to +3 dBm */ 396 ESP_PWR_LVL_P6 = 6, /*!< Corresponding to +6 dBm */ 397 ESP_PWR_LVL_P9 = 7, /*!< Corresponding to +9 dBm */ 398 ESP_PWR_LVL_N14 = ESP_PWR_LVL_N12, /*!< Backward compatibility! Setting to -14 dBm will actually result in -12 dBm */ 399 ESP_PWR_LVL_N11 = ESP_PWR_LVL_N9, /*!< Backward compatibility! Setting to -11 dBm will actually result in -9 dBm */ 400 ESP_PWR_LVL_N8 = ESP_PWR_LVL_N6, /*!< Backward compatibility! Setting to -8 dBm will actually result in -6 dBm */ 401 ESP_PWR_LVL_N5 = ESP_PWR_LVL_N3, /*!< Backward compatibility! Setting to -5 dBm will actually result in -3 dBm */ 402 ESP_PWR_LVL_N2 = ESP_PWR_LVL_N0, /*!< Backward compatibility! Setting to -2 dBm will actually result in 0 dBm */ 403 ESP_PWR_LVL_P1 = ESP_PWR_LVL_P3, /*!< Backward compatibility! Setting to +1 dBm will actually result in +3 dBm */ 404 ESP_PWR_LVL_P4 = ESP_PWR_LVL_P6, /*!< Backward compatibility! Setting to +4 dBm will actually result in +6 dBm */ 405 ESP_PWR_LVL_P7 = ESP_PWR_LVL_P9, /*!< Backward compatibility! Setting to +7 dBm will actually result in +9 dBm */ 406 } esp_power_level_t; 407 408 /** 409 * @brief Bluetooth audio data transport path 410 */ 411 typedef enum { 412 ESP_SCO_DATA_PATH_HCI = 0, /*!< data over HCI transport */ 413 ESP_SCO_DATA_PATH_PCM = 1, /*!< data over PCM interface */ 414 } esp_sco_data_path_t; 415 416 /** 417 * @brief Set BLE TX power 418 * 419 * @note Connection TX power should only be set after the connection is established. 420 * 421 * @param[in] power_type The type of TX power. It could be Advertising, Connection, Default, etc. 422 * @param[in] power_level Power level (index) corresponding to the absolute value (dBm) 423 * 424 * @return 425 * - ESP_OK: Success 426 * - ESP_ERR_INVALID_ARG: Invalid argument 427 */ 428 esp_err_t esp_ble_tx_power_set(esp_ble_power_type_t power_type, esp_power_level_t power_level); 429 430 /** 431 * @brief Get BLE TX power 432 * 433 * @note Connection TX power should only be retrieved after the connection is established. 434 * 435 * @param[in] power_type The type of TX power. It could be Advertising/Connection/Default and etc. 436 * 437 * @return 438 * - Power level 439 * 440 */ 441 esp_power_level_t esp_ble_tx_power_get(esp_ble_power_type_t power_type); 442 443 /** 444 * @brief Set BR/EDR TX power 445 * 446 * BR/EDR power control will use the power within the range of minimum value and maximum value. 447 * The power level will affect the global BR/EDR TX power for operations such as inquiry, page, and connection. 448 * 449 * @note 450 * 1. Please call this function after `esp_bt_controller_enable()` and before any functions that cause RF transmission, 451 * such as performing discovery, profile initialization, and so on. 452 * 2. For BR/EDR to use the new TX power for inquiry, call this function before starting an inquiry. 453 * If BR/EDR is already inquiring, restart the inquiry after calling this function. 454 * 455 * @param[in] min_power_level The minimum power level. The default value is `ESP_PWR_LVL_N0`. 456 * @param[in] max_power_level The maximum power level. The default value is `ESP_PWR_LVL_P3`. 457 * 458 * @return 459 * - ESP_OK: Success 460 * - ESP_ERR_INVALID_ARG: Invalid argument 461 * - ESP_ERR_INVALID_STATE: Invalid Bluetooth Controller state 462 */ 463 esp_err_t esp_bredr_tx_power_set(esp_power_level_t min_power_level, esp_power_level_t max_power_level); 464 465 /** 466 * @brief Get BR/EDR TX power 467 * 468 * The corresponding power levels will be stored into the arguments. 469 * 470 * @param[out] min_power_level Pointer to store the minimum power level 471 * @param[out] max_power_level The maximum power level 472 * 473 * @return 474 * - ESP_OK: Success 475 * - ESP_ERR_INVALID_ARG: Invalid argument 476 */ 477 esp_err_t esp_bredr_tx_power_get(esp_power_level_t *min_power_level, esp_power_level_t *max_power_level); 478 479 /** 480 * @brief Set default SCO data path 481 * 482 * @note This function should be called after the Controller is enabled, and before (e)SCO link is established. 483 * 484 * @param[in] data_path SCO data path 485 * 486 * @return 487 * - ESP_OK: Success 488 * - ESP_ERR_INVALID_STATE: Invalid Bluetooth Controller state 489 */ 490 esp_err_t esp_bredr_sco_datapath_set(esp_sco_data_path_t data_path); 491 492 /** 493 * @brief Initialize the Bluetooth Controller to allocate tasks and other resources 494 * 495 * @note This function should be called only once, before any other Bluetooth functions. 496 * 497 * @param[in] cfg Initial Bluetooth Controller configuration 498 * 499 * @return 500 * - ESP_OK: Success 501 * - ESP_ERR_INVALID_STATE: Invalid Bluetooth Controller state 502 */ 503 esp_err_t esp_bt_controller_init(esp_bt_controller_config_t *cfg); 504 505 /** 506 * @brief De-initialize Bluetooth Controller to free resources and delete tasks 507 * 508 * @note 509 * 1. You should stop advertising and scanning, and disconnect all existing connections before de-initializing Bluetooth Controller. 510 * 2. This function should be called only once, after any other Bluetooth functions. 511 * 512 * @return 513 * - ESP_OK: Success 514 * - ESP_ERR_INVALID_ARG: Invalid argument 515 * - ESP_ERR_INVALID_STATE: Invalid Bluetooth Controller state 516 * - ESP_ERR_NO_MEM: Out of memory 517 */ 518 esp_err_t esp_bt_controller_deinit(void); 519 520 /** 521 * @brief Enable Bluetooth Controller 522 * 523 * @note 524 * 1. Bluetooth Controller cannot be enabled in `ESP_BT_CONTROLLER_STATUS_IDLE` status. It has to be initialized first. 525 * 2. Due to a known issue, you cannot call `esp_bt_controller_enable()` for the second time 526 * to change the Controller mode dynamically. To change the Controller mode, call 527 * `esp_bt_controller_disable()` and then call `esp_bt_controller_enable()` with the new mode. 528 * 529 * @param[in] mode The Bluetooth Controller mode (BLE/Classic Bluetooth/BTDM) to enable 530 * 531 * For API compatibility, retain this argument. This mode must match the mode specified in the `cfg` of `esp_bt_controller_init()`. 532 * 533 * @return 534 * - ESP_OK: Success 535 * - ESP_ERR_INVALID_STATE: Invalid Bluetooth Controller state 536 */ 537 esp_err_t esp_bt_controller_enable(esp_bt_mode_t mode); 538 539 /** 540 * @brief Disable Bluetooth Controller 541 * 542 * @return 543 * - ESP_OK: Success 544 * - ESP_ERR_INVALID_STATE: Invalid Bluetooth Controller state 545 */ 546 esp_err_t esp_bt_controller_disable(void); 547 548 /** 549 * @brief Get Bluetooth Controller status 550 * 551 * @return 552 * - ESP_BT_CONTROLLER_STATUS_IDLE: The Controller is not initialized or has been de-initialized. 553 * - ESP_BT_CONTROLLER_STATUS_INITED: The Controller has been initialized, but not enabled or has been disabled. 554 * - ESP_BT_CONTROLLER_STATUS_ENABLED: The Controller has been initialized and enabled. 555 */ 556 esp_bt_controller_status_t esp_bt_controller_get_status(void); 557 558 /** 559 * @brief Vendor HCI (VHCI) callback functions to notify the Host on the next operation 560 */ 561 typedef struct esp_vhci_host_callback { 562 void (*notify_host_send_available)(void); /*!< Callback to notify the Host that the Controller is ready to receive the packet */ 563 int (*notify_host_recv)(uint8_t *data, uint16_t len); /*!< Callback to notify the Host that the Controller has a packet to send */ 564 } esp_vhci_host_callback_t; 565 566 typedef void (*workitem_handler_t)(void *arg); 567 568 /** 569 * @brief Check whether the Controller is ready to receive the packet 570 * 571 * If the return value is True, the Host can send the packet to the Controller. 572 * 573 * @note This function should be called before each `esp_vhci_host_send_packet()`. 574 * 575 * @return 576 * True if the Controller is ready to receive packets; false otherwise 577 */ 578 bool esp_vhci_host_check_send_available(void); 579 580 /** 581 * @brief Send the packet to the Controller 582 * 583 * @note 584 * 1. This function shall not be called within a critical section or when the scheduler is suspended. 585 * 2. This function should be called only if `esp_vhci_host_check_send_available()` returns True. 586 * 587 * @param[in] data Pointer to the packet data 588 * @param[in] len The packet length 589 */ 590 void esp_vhci_host_send_packet(uint8_t *data, uint16_t len); 591 592 /** 593 * @brief Register the VHCI callback funations defined in `esp_vhci_host_callback` structure. 594 * 595 * @param[in] callback `esp_vhci_host_callback` type variable 596 * 597 * @return 598 * - ESP_OK: Success 599 * - ESP_FAIL: Failure 600 */ 601 esp_err_t esp_vhci_host_register_callback(const esp_vhci_host_callback_t *callback); 602 603 /** 604 * @brief Release the Controller memory as per the mode 605 * 606 * This function releases the BSS, data and other sections of the Controller to heap. The total size is about 70 KB. 607 * 608 * @note 609 * 1. This function is optional and should be called only if you want to free up memory for other components. 610 * 2. This function should only be called when the controller is in `ESP_BT_CONTROLLER_STATUS_IDLE` status. 611 * 3. Once Bluetooth Controller memory is released, the process cannot be reversed. This means you cannot use the Bluetooth Controller mode that you have released using this function. 612 * 4. If your firmware will upgrade the Bluetooth Controller mode later (such as switching from BLE to Classic Bluetooth or from disabled to enabled), then do not call this function. 613 * 614 * If you never intend to use Bluetooth in a current boot-up cycle, calling `esp_bt_controller_mem_release(ESP_BT_MODE_BTDM)` could release the BSS and data consumed by both Classic Bluetooth and BLE Controller to heap. 615 * 616 * If you intend to use BLE only, calling `esp_bt_controller_mem_release(ESP_BT_MODE_CLASSIC_BT)` could release the BSS and data consumed by Classic Bluetooth Controller. You can then continue using BLE. 617 * 618 * If you intend to use Classic Bluetooth only, calling `esp_bt_controller_mem_release(ESP_BT_MODE_BLE)` could release the BSS and data consumed by BLE Controller. You can then continue using Classic Bluetooth. 619 * 620 * @param[in] mode The Bluetooth Controller mode 621 * 622 * @return 623 * - ESP_OK: Success 624 * - ESP_ERR_INVALID_STATE: Invalid Bluetooth Controller state 625 * - ESP_ERR_NOT_FOUND: Requested resource not found 626 */ 627 esp_err_t esp_bt_controller_mem_release(esp_bt_mode_t mode); 628 629 /** 630 * @brief Release the Controller memory, BSS and data section of the Classic Bluetooth/BLE Host stack as per the mode 631 * 632 * @note 633 * 1. This function is optional and should be called only if you want to free up memory for other components. 634 * 2. This function should only be called when the controller is in `ESP_BT_CONTROLLER_STATUS_IDLE` status. 635 * 3. Once Bluetooth Controller memory is released, the process cannot be reversed. This means you cannot use the Bluetooth Controller mode that you have released using this function. 636 * 4. If your firmware will upgrade the Bluetooth Controller mode later (such as switching from BLE to Classic Bluetooth or from disabled to enabled), then do not call this function. 637 * 638 * This function first releases Controller memory by internally calling `esp_bt_controller_mem_release()`, then releases Host memory. 639 * 640 * If you never intend to use Bluetooth in a current boot-up cycle, calling `esp_bt_mem_release(ESP_BT_MODE_BTDM)` could release the BSS and data consumed by both Classic Bluetooth and BLE stack to heap. 641 * 642 * If you intend to use BLE only, calling `esp_bt_mem_release(ESP_BT_MODE_CLASSIC_BT)` could release the BSS and data consumed by Classic Bluetooth. You can then continue using BLE. 643 * 644 * If you intend to use Classic Bluetooth only, calling `esp_bt_mem_release(ESP_BT_MODE_BLE)` could release the BSS and data consumed by BLE. You can then continue using Classic Bluetooth. 645 * 646 * For example, if you only use Bluetooth for setting the Wi-Fi configuration, and do not use Bluetooth in the rest of the product operation, 647 * after receiving the Wi-Fi configuration, you can disable/de-init Bluetooth and release its memory. 648 * Below is the sequence of APIs to be called for such scenarios: 649 * 650 * esp_bluedroid_disable(); 651 * esp_bluedroid_deinit(); 652 * esp_bt_controller_disable(); 653 * esp_bt_controller_deinit(); 654 * esp_bt_mem_release(ESP_BT_MODE_BTDM); 655 * 656 * @param[in] mode The Bluetooth Controller mode 657 * 658 * @return 659 * - ESP_OK: Success 660 * - ESP_ERR_INVALID_STATE: Invalid Bluetooth Controller state 661 * - ESP_ERR_NOT_FOUND: Requested resource not found 662 */ 663 esp_err_t esp_bt_mem_release(esp_bt_mode_t mode); 664 665 /** 666 * @brief Enable Bluetooth modem sleep 667 * 668 * There are currently two options for Bluetooth modem sleep: ORIG mode and EVED mode. The latter is intended for BLE only. 669 * The modem sleep mode could be configured in menuconfig. 670 * 671 * In ORIG mode, if there is no event to process, the Bluetooth Controller will periodically switch off some components and pause operation, then wake up according to the scheduled interval and resume work. 672 * It can also wakeup earlier upon external request using function `esp_bt_controller_wakeup_request()`. 673 * 674 * @note This function shall not be invoked before `esp_bt_controller_enable()`. 675 * 676 * @return 677 * - ESP_OK: Success 678 * - ESP_ERR_INVALID_STATE: Invalid Bluetooth Controller state 679 * - ESP_ERR_NOT_SUPPORTED: Operation or feature not supported 680 */ 681 esp_err_t esp_bt_sleep_enable(void); 682 683 684 /** 685 * @brief Disable Bluetooth modem sleep 686 * 687 * @note 688 * 1. Bluetooth Controller will not be allowed to enter modem sleep after calling this function. 689 * 2. In ORIG modem sleep mode, calling this function may not immediately wake up the Controller if it is currently dormant. 690 * In this case, `esp_bt_controller_wakeup_request()` can be used to shorten the wake-up time. 691 * 3. This function shall not be invoked before `esp_bt_controller_enable()`. 692 * 693 * @return 694 * - ESP_OK: Success 695 * - ESP_ERR_INVALID_STATE: Invalid Bluetooth Controller state 696 * - ESP_ERR_NOT_SUPPORTED: Operation or feature not supported 697 */ 698 esp_err_t esp_bt_sleep_disable(void); 699 700 /** 701 * @brief Manually clear the scan duplicate list 702 * 703 * @note 704 * 1. This function name is incorrectly spelled, it will be fixed in release 5.x version. 705 * 2. The scan duplicate list will be automatically cleared when the maximum amount of devices in the filter is reached. 706 * The amount of devices in the filter can be configured in menuconfig. 707 * 708 * @return 709 * - ESP_OK: Success 710 * - ESP_ERR_INVALID_STATE: Invalid Bluetooth Controller state 711 */ 712 esp_err_t esp_ble_scan_dupilcate_list_flush(void); 713 714 /** 715 * @brief Power on Bluetooth Wi-Fi power domain 716 * 717 * @note This function is not recommended to use due to potential risk. 718 */ 719 void esp_wifi_bt_power_domain_on(void); 720 721 /** 722 * @brief Power off Bluetooth Wi-Fi power domain 723 * 724 * @note This function is not recommended to use due to potential risk. 725 */ 726 void esp_wifi_bt_power_domain_off(void); 727 728 #ifdef __cplusplus 729 } 730 #endif 731 732 #endif /* __ESP_BT_H__ */ 733
