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