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