1 // Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef __ESP_BT_H__ 16 #define __ESP_BT_H__ 17 18 #include <stdint.h> 19 #include <stdbool.h> 20 #include "esp_err.h" 21 #include "sdkconfig.h" 22 #include "esp_task.h" 23 24 #ifdef __cplusplus 25 extern "C" { 26 #endif 27 28 #define ESP_BT_CONTROLLER_CONFIG_MAGIC_VAL 0x20200622 29 30 /** 31 * @brief Bluetooth mode for controller enable/disable 32 */ 33 typedef enum { 34 ESP_BT_MODE_IDLE = 0x00, /*!< Bluetooth is not running */ 35 ESP_BT_MODE_BLE = 0x01, /*!< Run BLE mode */ 36 ESP_BT_MODE_CLASSIC_BT = 0x02, /*!< Run Classic BT mode */ 37 ESP_BT_MODE_BTDM = 0x03, /*!< Run dual mode */ 38 } esp_bt_mode_t; 39 40 /** 41 * @brief BLE sleep clock accuracy(SCA), values for ble_sca field in esp_bt_controller_config_t, 42 * currently only ESP_BLE_SCA_500PPM and ESP_BLE_SCA_250PPM are supported 43 */ 44 enum { 45 ESP_BLE_SCA_500PPM = 0, /*!< BLE SCA at 500ppm */ 46 ESP_BLE_SCA_250PPM, /*!< BLE SCA at 250ppm */ 47 ESP_BLE_SCA_150PPM, /*!< BLE SCA at 150ppm */ 48 ESP_BLE_SCA_100PPM, /*!< BLE SCA at 100ppm */ 49 ESP_BLE_SCA_75PPM, /*!< BLE SCA at 75ppm */ 50 ESP_BLE_SCA_50PPM, /*!< BLE SCA at 50ppm */ 51 ESP_BLE_SCA_30PPM, /*!< BLE SCA at 30ppm */ 52 ESP_BLE_SCA_20PPM, /*!< BLE SCA at 20ppm */ 53 }; 54 55 #ifdef CONFIG_BT_ENABLED 56 /* While scanning, if the free memory value in controller is less than SCAN_SEND_ADV_RESERVED_SIZE, 57 the adv packet will be discarded until the memory is restored. */ 58 #define SCAN_SEND_ADV_RESERVED_SIZE 1000 59 /* enable controller log debug when adv lost */ 60 #define CONTROLLER_ADV_LOST_DEBUG_BIT (0<<0) 61 62 #ifdef CONFIG_BTDM_CTRL_HCI_UART_NO 63 #define BT_HCI_UART_NO_DEFAULT CONFIG_BTDM_CTRL_HCI_UART_NO 64 #else 65 #define BT_HCI_UART_NO_DEFAULT 1 66 #endif /* BT_HCI_UART_NO_DEFAULT */ 67 68 #ifdef CONFIG_BTDM_CTRL_HCI_UART_BAUDRATE 69 #define BT_HCI_UART_BAUDRATE_DEFAULT CONFIG_BTDM_CTRL_HCI_UART_BAUDRATE 70 #else 71 #define BT_HCI_UART_BAUDRATE_DEFAULT 921600 72 #endif /* BT_HCI_UART_BAUDRATE_DEFAULT */ 73 74 #ifdef CONFIG_BTDM_SCAN_DUPL_TYPE 75 #define SCAN_DUPLICATE_TYPE_VALUE CONFIG_BTDM_SCAN_DUPL_TYPE 76 #else 77 #define SCAN_DUPLICATE_TYPE_VALUE 0 78 #endif 79 80 /* normal adv cache size */ 81 #ifdef CONFIG_BTDM_SCAN_DUPL_CACHE_SIZE 82 #define NORMAL_SCAN_DUPLICATE_CACHE_SIZE CONFIG_BTDM_SCAN_DUPL_CACHE_SIZE 83 #else 84 #define NORMAL_SCAN_DUPLICATE_CACHE_SIZE 20 85 #endif 86 87 #ifndef CONFIG_BTDM_BLE_MESH_SCAN_DUPL_EN 88 #define CONFIG_BTDM_BLE_MESH_SCAN_DUPL_EN 0 89 #endif 90 91 #define SCAN_DUPLICATE_MODE_NORMAL_ADV_ONLY 0 92 #define SCAN_DUPLICATE_MODE_NORMAL_ADV_MESH_ADV 1 93 94 #if CONFIG_BTDM_BLE_MESH_SCAN_DUPL_EN 95 #define SCAN_DUPLICATE_MODE SCAN_DUPLICATE_MODE_NORMAL_ADV_MESH_ADV 96 #ifdef CONFIG_BTDM_MESH_DUPL_SCAN_CACHE_SIZE 97 #define MESH_DUPLICATE_SCAN_CACHE_SIZE CONFIG_BTDM_MESH_DUPL_SCAN_CACHE_SIZE 98 #else 99 #define MESH_DUPLICATE_SCAN_CACHE_SIZE 50 100 #endif 101 #else 102 #define SCAN_DUPLICATE_MODE SCAN_DUPLICATE_MODE_NORMAL_ADV_ONLY 103 #define MESH_DUPLICATE_SCAN_CACHE_SIZE 0 104 #endif 105 106 #if defined(CONFIG_BTDM_CTRL_MODE_BLE_ONLY) 107 #define BTDM_CONTROLLER_MODE_EFF ESP_BT_MODE_BLE 108 #elif defined(CONFIG_BTDM_CTRL_MODE_BR_EDR_ONLY) 109 #define BTDM_CONTROLLER_MODE_EFF ESP_BT_MODE_CLASSIC_BT 110 #else 111 #define BTDM_CONTROLLER_MODE_EFF ESP_BT_MODE_BTDM 112 #endif 113 114 #ifdef CONFIG_BTDM_CTRL_AUTO_LATENCY_EFF 115 #define BTDM_CTRL_AUTO_LATENCY_EFF CONFIG_BTDM_CTRL_AUTO_LATENCY_EFF 116 #else 117 #define BTDM_CTRL_AUTO_LATENCY_EFF false 118 #endif 119 120 #ifdef CONFIG_BTDM_CTRL_LEGACY_AUTH_VENDOR_EVT_EFF 121 #define BTDM_CTRL_LEGACY_AUTH_VENDOR_EVT_EFF CONFIG_BTDM_CTRL_LEGACY_AUTH_VENDOR_EVT_EFF 122 #else 123 #define BTDM_CTRL_LEGACY_AUTH_VENDOR_EVT_EFF false 124 #endif 125 126 #define BTDM_CONTROLLER_BLE_MAX_CONN_LIMIT 9 //Maximum BLE connection limitation 127 #define BTDM_CONTROLLER_BR_EDR_MAX_ACL_CONN_LIMIT 7 //Maximum ACL connection limitation 128 #define BTDM_CONTROLLER_BR_EDR_MAX_SYNC_CONN_LIMIT 3 //Maximum SCO/eSCO connection limitation 129 130 #define BTDM_CONTROLLER_SCO_DATA_PATH_HCI 0 // SCO data is routed to HCI 131 #define BTDM_CONTROLLER_SCO_DATA_PATH_PCM 1 // SCO data path is PCM 132 133 #define BT_CONTROLLER_INIT_CONFIG_DEFAULT() { \ 134 .controller_task_stack_size = ESP_TASK_BT_CONTROLLER_STACK, \ 135 .controller_task_prio = ESP_TASK_BT_CONTROLLER_PRIO, \ 136 .hci_uart_no = BT_HCI_UART_NO_DEFAULT, \ 137 .hci_uart_baudrate = BT_HCI_UART_BAUDRATE_DEFAULT, \ 138 .scan_duplicate_mode = SCAN_DUPLICATE_MODE, \ 139 .scan_duplicate_type = SCAN_DUPLICATE_TYPE_VALUE, \ 140 .normal_adv_size = NORMAL_SCAN_DUPLICATE_CACHE_SIZE, \ 141 .mesh_adv_size = MESH_DUPLICATE_SCAN_CACHE_SIZE, \ 142 .send_adv_reserved_size = SCAN_SEND_ADV_RESERVED_SIZE, \ 143 .controller_debug_flag = CONTROLLER_ADV_LOST_DEBUG_BIT, \ 144 .mode = BTDM_CONTROLLER_MODE_EFF, \ 145 .ble_max_conn = CONFIG_BTDM_CTRL_BLE_MAX_CONN_EFF, \ 146 .bt_max_acl_conn = CONFIG_BTDM_CTRL_BR_EDR_MAX_ACL_CONN_EFF, \ 147 .bt_sco_datapath = CONFIG_BTDM_CTRL_BR_EDR_SCO_DATA_PATH_EFF, \ 148 .auto_latency = BTDM_CTRL_AUTO_LATENCY_EFF, \ 149 .bt_legacy_auth_vs_evt = BTDM_CTRL_LEGACY_AUTH_VENDOR_EVT_EFF, \ 150 .bt_max_sync_conn = CONFIG_BTDM_CTRL_BR_EDR_MAX_SYNC_CONN_EFF, \ 151 .ble_sca = CONFIG_BTDM_BLE_SLEEP_CLOCK_ACCURACY_INDEX_EFF, \ 152 .pcm_role = CONFIG_BTDM_CTRL_PCM_ROLE_EFF, \ 153 .pcm_polar = CONFIG_BTDM_CTRL_PCM_POLAR_EFF, \ 154 .magic = ESP_BT_CONTROLLER_CONFIG_MAGIC_VAL, \ 155 }; 156 157 #else 158 #define BT_CONTROLLER_INIT_CONFIG_DEFAULT() {0}; _Static_assert(0, "please enable bluetooth in menuconfig to use bt.h"); 159 #endif 160 161 /** 162 * @brief Controller config options, depend on config mask. 163 * Config mask indicate which functions enabled, this means 164 * some options or parameters of some functions enabled by config mask. 165 */ 166 typedef struct { 167 /* 168 * Following parameters can be configured runtime, when call esp_bt_controller_init() 169 */ 170 uint16_t controller_task_stack_size; /*!< Bluetooth controller task stack size */ 171 uint8_t controller_task_prio; /*!< Bluetooth controller task priority */ 172 uint8_t hci_uart_no; /*!< If use UART1/2 as HCI IO interface, indicate UART number */ 173 uint32_t hci_uart_baudrate; /*!< If use UART1/2 as HCI IO interface, indicate UART baudrate */ 174 uint8_t scan_duplicate_mode; /*!< scan duplicate mode */ 175 uint8_t scan_duplicate_type; /*!< scan duplicate type */ 176 uint16_t normal_adv_size; /*!< Normal adv size for scan duplicate */ 177 uint16_t mesh_adv_size; /*!< Mesh adv size for scan duplicate */ 178 uint16_t send_adv_reserved_size; /*!< Controller minimum memory value */ 179 uint32_t controller_debug_flag; /*!< Controller debug log flag */ 180 uint8_t mode; /*!< Controller mode: BR/EDR, BLE or Dual Mode */ 181 uint8_t ble_max_conn; /*!< BLE maximum connection numbers */ 182 uint8_t bt_max_acl_conn; /*!< BR/EDR maximum ACL connection numbers */ 183 uint8_t bt_sco_datapath; /*!< SCO data path, i.e. HCI or PCM module */ 184 bool auto_latency; /*!< BLE auto latency, used to enhance classic BT performance */ 185 bool bt_legacy_auth_vs_evt; /*!< BR/EDR Legacy auth complete event required to protect from BIAS attack */ 186 /* 187 * Following parameters can not be configured runtime when call esp_bt_controller_init() 188 * It will be overwrite with a constant value which in menuconfig or from a macro. 189 * So, do not modify the value when esp_bt_controller_init() 190 */ 191 uint8_t bt_max_sync_conn; /*!< BR/EDR maximum ACL connection numbers. Effective in menuconfig */ 192 uint8_t ble_sca; /*!< BLE low power crystal accuracy index */ 193 uint8_t pcm_role; /*!< PCM role (master & slave)*/ 194 uint8_t pcm_polar; /*!< PCM polar trig (falling clk edge & rising clk edge) */ 195 uint32_t magic; /*!< Magic number */ 196 } esp_bt_controller_config_t; 197 198 /** 199 * @brief Bluetooth controller enable/disable/initialised/de-initialised status 200 */ 201 typedef enum { 202 ESP_BT_CONTROLLER_STATUS_IDLE = 0, 203 ESP_BT_CONTROLLER_STATUS_INITED, 204 ESP_BT_CONTROLLER_STATUS_ENABLED, 205 ESP_BT_CONTROLLER_STATUS_NUM, 206 } esp_bt_controller_status_t; 207 208 /** 209 * @brief BLE tx power type 210 * ESP_BLE_PWR_TYPE_CONN_HDL0-8: for each connection, and only be set after connection completed. 211 * when disconnect, the correspond TX power is not effected. 212 * ESP_BLE_PWR_TYPE_ADV : for advertising/scan response. 213 * ESP_BLE_PWR_TYPE_SCAN : for scan. 214 * ESP_BLE_PWR_TYPE_DEFAULT : if each connection's TX power is not set, it will use this default value. 215 * if neither in scan mode nor in adv mode, it will use this default value. 216 * If none of power type is set, system will use ESP_PWR_LVL_P3 as default for ADV/SCAN/CONN0-9. 217 */ 218 typedef enum { 219 ESP_BLE_PWR_TYPE_CONN_HDL0 = 0, /*!< For connection handle 0 */ 220 ESP_BLE_PWR_TYPE_CONN_HDL1 = 1, /*!< For connection handle 1 */ 221 ESP_BLE_PWR_TYPE_CONN_HDL2 = 2, /*!< For connection handle 2 */ 222 ESP_BLE_PWR_TYPE_CONN_HDL3 = 3, /*!< For connection handle 3 */ 223 ESP_BLE_PWR_TYPE_CONN_HDL4 = 4, /*!< For connection handle 4 */ 224 ESP_BLE_PWR_TYPE_CONN_HDL5 = 5, /*!< For connection handle 5 */ 225 ESP_BLE_PWR_TYPE_CONN_HDL6 = 6, /*!< For connection handle 6 */ 226 ESP_BLE_PWR_TYPE_CONN_HDL7 = 7, /*!< For connection handle 7 */ 227 ESP_BLE_PWR_TYPE_CONN_HDL8 = 8, /*!< For connection handle 8 */ 228 ESP_BLE_PWR_TYPE_ADV = 9, /*!< For advertising */ 229 ESP_BLE_PWR_TYPE_SCAN = 10, /*!< For scan */ 230 ESP_BLE_PWR_TYPE_DEFAULT = 11, /*!< For default, if not set other, it will use default value */ 231 ESP_BLE_PWR_TYPE_NUM = 12, /*!< TYPE numbers */ 232 } esp_ble_power_type_t; 233 234 /** 235 * @brief Bluetooth TX power level(index), it's just a index corresponding to power(dbm). 236 */ 237 typedef enum { 238 ESP_PWR_LVL_N12 = 0, /*!< Corresponding to -12dbm */ 239 ESP_PWR_LVL_N9 = 1, /*!< Corresponding to -9dbm */ 240 ESP_PWR_LVL_N6 = 2, /*!< Corresponding to -6dbm */ 241 ESP_PWR_LVL_N3 = 3, /*!< Corresponding to -3dbm */ 242 ESP_PWR_LVL_N0 = 4, /*!< Corresponding to 0dbm */ 243 ESP_PWR_LVL_P3 = 5, /*!< Corresponding to +3dbm */ 244 ESP_PWR_LVL_P6 = 6, /*!< Corresponding to +6dbm */ 245 ESP_PWR_LVL_P9 = 7, /*!< Corresponding to +9dbm */ 246 ESP_PWR_LVL_N14 = ESP_PWR_LVL_N12, /*!< Backward compatibility! Setting to -14dbm will actually result to -12dbm */ 247 ESP_PWR_LVL_N11 = ESP_PWR_LVL_N9, /*!< Backward compatibility! Setting to -11dbm will actually result to -9dbm */ 248 ESP_PWR_LVL_N8 = ESP_PWR_LVL_N6, /*!< Backward compatibility! Setting to -8dbm will actually result to -6dbm */ 249 ESP_PWR_LVL_N5 = ESP_PWR_LVL_N3, /*!< Backward compatibility! Setting to -5dbm will actually result to -3dbm */ 250 ESP_PWR_LVL_N2 = ESP_PWR_LVL_N0, /*!< Backward compatibility! Setting to -2dbm will actually result to 0dbm */ 251 ESP_PWR_LVL_P1 = ESP_PWR_LVL_P3, /*!< Backward compatibility! Setting to +1dbm will actually result to +3dbm */ 252 ESP_PWR_LVL_P4 = ESP_PWR_LVL_P6, /*!< Backward compatibility! Setting to +4dbm will actually result to +6dbm */ 253 ESP_PWR_LVL_P7 = ESP_PWR_LVL_P9, /*!< Backward compatibility! Setting to +7dbm will actually result to +9dbm */ 254 } esp_power_level_t; 255 256 /** 257 * @brief Bluetooth audio data transport path 258 */ 259 typedef enum { 260 ESP_SCO_DATA_PATH_HCI = 0, /*!< data over HCI transport */ 261 ESP_SCO_DATA_PATH_PCM = 1, /*!< data over PCM interface */ 262 } esp_sco_data_path_t; 263 264 /** 265 * @brief Set BLE TX power 266 * Connection Tx power should only be set after connection created. 267 * @param power_type : The type of which tx power, could set Advertising/Connection/Default and etc 268 * @param power_level: Power level(index) corresponding to absolute value(dbm) 269 * @return ESP_OK - success, other - failed 270 */ 271 esp_err_t esp_ble_tx_power_set(esp_ble_power_type_t power_type, esp_power_level_t power_level); 272 273 /** 274 * @brief Get BLE TX power 275 * Connection Tx power should only be get after connection created. 276 * @param power_type : The type of which tx power, could set Advertising/Connection/Default and etc 277 * @return >= 0 - Power level, < 0 - Invalid 278 */ 279 esp_power_level_t esp_ble_tx_power_get(esp_ble_power_type_t power_type); 280 281 /** 282 * @brief Set BR/EDR TX power 283 * BR/EDR power control will use the power in range of minimum value and maximum value. 284 * The power level will effect the global BR/EDR TX power, such inquire, page, connection and so on. 285 * Please call the function after esp_bt_controller_enable and before any function which cause RF do TX. 286 * So you can call the function before doing discovery, profile init and so on. 287 * For example, if you want BR/EDR use the new TX power to do inquire, you should call 288 * this function before inquire. Another word, If call this function when BR/EDR is in inquire(ING), 289 * please do inquire again after call this function. 290 * Default minimum power level is ESP_PWR_LVL_N0, and maximum power level is ESP_PWR_LVL_P3. 291 * @param min_power_level: The minimum power level 292 * @param max_power_level: The maximum power level 293 * @return ESP_OK - success, other - failed 294 */ 295 esp_err_t esp_bredr_tx_power_set(esp_power_level_t min_power_level, esp_power_level_t max_power_level); 296 297 /** 298 * @brief Get BR/EDR TX power 299 * If the argument is not NULL, then store the corresponding value. 300 * @param min_power_level: The minimum power level 301 * @param max_power_level: The maximum power level 302 * @return ESP_OK - success, other - failed 303 */ 304 esp_err_t esp_bredr_tx_power_get(esp_power_level_t *min_power_level, esp_power_level_t *max_power_level); 305 306 /** 307 * @brief Set default SCO data path 308 * Should be called after controller is enabled, and before (e)SCO link is established 309 * @param data_path: SCO data path 310 * @return ESP_OK - success, other - failed 311 */ 312 esp_err_t esp_bredr_sco_datapath_set(esp_sco_data_path_t data_path); 313 314 /** 315 * @brief Initialize BT controller to allocate task and other resource. 316 * This function should be called only once, before any other BT functions are called. 317 * @param cfg: Initial configuration of BT controller. Different from previous version, there's a mode and some 318 * connection configuration in "cfg" to configure controller work mode and allocate the resource which is needed. 319 * @return ESP_OK - success, other - failed 320 */ 321 esp_err_t esp_bt_controller_init(esp_bt_controller_config_t *cfg); 322 323 /** 324 * @brief De-initialize BT controller to free resource and delete task. 325 * 326 * This function should be called only once, after any other BT functions are called. 327 * @return ESP_OK - success, other - failed 328 */ 329 esp_err_t esp_bt_controller_deinit(void); 330 331 /** 332 * @brief Enable BT controller. 333 * Due to a known issue, you cannot call esp_bt_controller_enable() a second time 334 * to change the controller mode dynamically. To change controller mode, call 335 * esp_bt_controller_disable() and then call esp_bt_controller_enable() with the new mode. 336 * @param mode : the mode(BLE/BT/BTDM) to enable. For compatible of API, retain this argument. This mode must be 337 * equal as the mode in "cfg" of esp_bt_controller_init(). 338 * @return ESP_OK - success, other - failed 339 */ 340 esp_err_t esp_bt_controller_enable(esp_bt_mode_t mode); 341 342 /** 343 * @brief Disable BT controller 344 * @return ESP_OK - success, other - failed 345 */ 346 esp_err_t esp_bt_controller_disable(void); 347 348 /** 349 * @brief Get BT controller is initialised/de-initialised/enabled/disabled 350 * @return status value 351 */ 352 esp_bt_controller_status_t esp_bt_controller_get_status(void); 353 354 /** @brief esp_vhci_host_callback 355 * used for vhci call host function to notify what host need to do 356 */ 357 typedef struct esp_vhci_host_callback { 358 void (*notify_host_send_available)(void); /*!< callback used to notify that the host can send packet to controller */ 359 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*/ 360 } esp_vhci_host_callback_t; 361 362 /** @brief esp_vhci_host_check_send_available 363 * used for check actively if the host can send packet to controller or not. 364 * @return true for ready to send, false means cannot send packet 365 */ 366 bool esp_vhci_host_check_send_available(void); 367 368 /** @brief esp_vhci_host_send_packet 369 * host send packet to controller 370 * 371 * Should not call this function from within a critical section 372 * or when the scheduler is suspended. 373 * 374 * @param data the packet point 375 * @param len the packet length 376 */ 377 void esp_vhci_host_send_packet(uint8_t *data, uint16_t len); 378 379 /** @brief esp_vhci_host_register_callback 380 * register the vhci reference callback 381 * struct defined by vhci_host_callback structure. 382 * @param callback esp_vhci_host_callback type variable 383 * @return ESP_OK - success, ESP_FAIL - failed 384 */ 385 esp_err_t esp_vhci_host_register_callback(const esp_vhci_host_callback_t *callback); 386 387 /** @brief esp_bt_controller_mem_release 388 * release the controller memory as per the mode 389 * 390 * This function releases the BSS, data and other sections of the controller to heap. The total size is about 70k bytes. 391 * 392 * esp_bt_controller_mem_release(mode) should be called only before esp_bt_controller_init() 393 * or after esp_bt_controller_deinit(). 394 * 395 * Note that once BT controller memory is released, the process cannot be reversed. It means you cannot use the bluetooth 396 * mode which you have released by this function. 397 * 398 * If your firmware will later upgrade the Bluetooth controller mode (BLE -> BT Classic or disabled -> enabled) 399 * then do not call this function. 400 * 401 * If the app calls esp_bt_controller_enable(ESP_BT_MODE_BLE) to use BLE only then it is safe to call 402 * esp_bt_controller_mem_release(ESP_BT_MODE_CLASSIC_BT) at initialization time to free unused BT Classic memory. 403 * 404 * 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, 405 * which internally calls esp_bt_controller_mem_release(ESP_BT_MODE_BTDM) and additionally releases the BSS and data 406 * consumed by the BT/BLE host stack to heap. For more details about usage please refer to the documentation of 407 * esp_bt_mem_release() function 408 * 409 * @param mode : the mode want to release memory 410 * @return ESP_OK - success, other - failed 411 */ 412 esp_err_t esp_bt_controller_mem_release(esp_bt_mode_t mode); 413 414 /** @brief esp_bt_mem_release 415 * release controller memory and BSS and data section of the BT/BLE host stack as per the mode 416 * 417 * This function first releases controller memory by internally calling esp_bt_controller_mem_release(). 418 * 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 419 * 420 * Note that once BT memory is released, the process cannot be reversed. It means you cannot use the bluetooth 421 * mode which you have released by this function. 422 * 423 * If your firmware will later upgrade the Bluetooth controller mode (BLE -> BT Classic or disabled -> enabled) 424 * then do not call this function. 425 * 426 * If you never intend to use bluetooth in a current boot-up cycle, you can call esp_bt_mem_release(ESP_BT_MODE_BTDM) 427 * before esp_bt_controller_init or after esp_bt_controller_deinit. 428 * 429 * 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". 430 * In such cases, after receiving the WiFi configuration, you can disable/deinit bluetooth and release its memory. 431 * Below is the sequence of APIs to be called for such scenarios: 432 * 433 * esp_bluedroid_disable(); 434 * esp_bluedroid_deinit(); 435 * esp_bt_controller_disable(); 436 * esp_bt_controller_deinit(); 437 * esp_bt_mem_release(ESP_BT_MODE_BTDM); 438 * 439 * @note In case of NimBLE host, to release BSS and data memory to heap, the mode needs to be 440 * set to ESP_BT_MODE_BTDM as controller is dual mode. 441 * @param mode : the mode whose memory is to be released 442 * @return ESP_OK - success, other - failed 443 */ 444 esp_err_t esp_bt_mem_release(esp_bt_mode_t mode); 445 446 /** 447 * @brief enable bluetooth to enter modem sleep 448 * 449 * Note that this function shall not be invoked before esp_bt_controller_enable() 450 * 451 * 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. 452 * 453 * For ORIG mode: 454 * Bluetooth modem sleep is enabled in controller start up by default if CONFIG_CTRL_BTDM_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". 455 * 456 * @return 457 * - ESP_OK : success 458 * - other : failed 459 */ 460 esp_err_t esp_bt_sleep_enable(void); 461 462 463 /** 464 * @brief disable bluetooth modem sleep 465 * 466 * Note that this function shall not be invoked before esp_bt_controller_enable() 467 * 468 * If esp_bt_sleep_disable() is called, bluetooth controller will not be allowed to enter modem sleep; 469 * 470 * 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. 471 * In this case, esp_bt_controller_wakeup_request() can be used to shorten the time for wakeup. 472 * 473 * @return 474 * - ESP_OK : success 475 * - other : failed 476 */ 477 esp_err_t esp_bt_sleep_disable(void); 478 479 /** 480 * @brief Manually clear scan duplicate list 481 * 482 * Note that scan duplicate list will be automatically cleared when the maximum amount of device in the filter is reached 483 * the amount of device in the filter can be configured in menuconfig. 484 * 485 * @note This function name is incorrectly spelled, it will be fixed in release 5.x version. 486 * 487 * @return 488 * - ESP_OK : success 489 * - other : failed 490 */ 491 esp_err_t esp_ble_scan_dupilcate_list_flush(void); 492 493 #ifdef __cplusplus 494 } 495 #endif 496 497 #endif /* __ESP_BT_H__ */ 498