ESP32蓝牙Bluetooth Controller API介绍

Posted 2022-12-04 Wireless_Link

前言：

本文章主要介绍下ESP32 蓝牙controller的API，通过此文章你将会有以下收获：

1）ESP32的蓝牙架构

2）ESP32蓝牙controller API的使用

零. 声明

本专栏文章我们会以连载的方式持续更新，本专栏计划更新内容如下：

第一篇:ESP-IDF基本介绍，主要会涉及模组，芯片，开发板的介绍，环境搭建，程序编译下载，启动流程等一些基本的操作，让你对ESP-IDF开发有一个总体的认识，比我们后续学习打下基础！

第二篇:ESP32-IDF外设驱动介绍，主要会根据esp-idf现有的driver，提供各个外设的驱动，比如LED,OLED,SPI LCD,TOUCH,红外,Codec ic等等，在这一篇中，我们不仅仅来做外设驱动，还会对常用的外设总线做一个介绍，让大家知其然又知其所以然！

第三篇:目前比较火热的GUI LVGL介绍，主要会设计LVGL7.1,LVGL8的移植介绍,并且也会介绍各个组件，知道原理后，最后，我们会推出一款组态软件来构建我们的GUI，来提升我们的效率！

第四篇:ESP32-蓝牙，熟悉我的，应该都知道，我即使从事蓝牙协议栈的开发的，所以这个是我们独有的优势，在这一篇章，我们会提供不仅仅是蓝牙应用方法的知识，也会应用结合蓝牙底层协议栈的理论，让你彻底从上到下打通蓝牙任督二脉！

第五篇：Wi-Fi介绍，熟悉我的，应该也知道，我们也做过一款sdio wifi的驱动教程板子，所以在wifi这方面我们也是有独有的优势，在这一篇章，我们同样不仅仅提供Wi-Fi应用方面的知识，也会结合底层理论，让你对Wi-Fi有一个清晰的认知！

另外，我们的教程包括但是不局限于以上篇章，为了给你一个更好的导航，以下信息尤其重要，请详细查看！！

------------------------------------------------------------------------------------------------------------------------------------------

购买开发板(点击我)

文档目录(点击我)

Github代码仓库(点击我)

蓝牙交流扣扣群：539357317

微信公众号↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓

​​​​

------------------------------------------------------------------------------------------------------------------------------------------

一.概述

在前面的章节中，我们看了ESP32的蓝牙架构，如下图所示

我们本章节就来介绍下蓝牙controller相关的API，API文档链接如下：

Controller && VHCI - ESP32 - — ESP-IDF 编程指南 v4.4.1 文档

遗憾的是：ESP32不开放Controller的source code，所以我们只能看API docu!

二. API介绍

controller部分的API在bt/include/esp32/include/esp_bt.h 文件中

esp_err_t esp_ble_tx_power_set (esp_ble_power_type_t power_type, esp_power_level_t power_level)

作用：设置BLE的tx power，分为广播/搜索/连接的，连接的TX power只能在连接后使用

参数1: power_type tx power的类型	typedef enum ESP_BLE_PWR_TYPE_CONN_HDL0 = 0, /*!< For connection handle 0 */ ESP_BLE_PWR_TYPE_CONN_HDL1 = 1, /*!< For connection handle 1 */ ESP_BLE_PWR_TYPE_CONN_HDL2 = 2, /*!< For connection handle 2 */ ESP_BLE_PWR_TYPE_CONN_HDL3 = 3, /*!< For connection handle 3 */ ESP_BLE_PWR_TYPE_CONN_HDL4 = 4, /*!< For connection handle 4 */ ESP_BLE_PWR_TYPE_CONN_HDL5 = 5, /*!< For connection handle 5 */ ESP_BLE_PWR_TYPE_CONN_HDL6 = 6, /*!< For connection handle 6 */ ESP_BLE_PWR_TYPE_CONN_HDL7 = 7, /*!< For connection handle 7 */ ESP_BLE_PWR_TYPE_CONN_HDL8 = 8, /*!< For connection handle 8 */ ESP_BLE_PWR_TYPE_ADV = 9, /*!< For advertising */ ESP_BLE_PWR_TYPE_SCAN = 10, /*!< For scan */ ESP_BLE_PWR_TYPE_DEFAULT = 11, /*!< For default, if not set other, it will use default value */ ESP_BLE_PWR_TYPE_NUM = 12, /*!< TYPE numbers */ esp_ble_power_type_t;
参数2: power_level tx power的级别	typedef enum ESP_PWR_LVL_N12 = 0, /*!< Corresponding to -12dbm */ ESP_PWR_LVL_N9 = 1, /*!< Corresponding to -9dbm */ ESP_PWR_LVL_N6 = 2, /*!< Corresponding to -6dbm */ ESP_PWR_LVL_N3 = 3, /*!< Corresponding to -3dbm */ ESP_PWR_LVL_N0 = 4, /*!< Corresponding to 0dbm */ ESP_PWR_LVL_P3 = 5, /*!< Corresponding to +3dbm */ ESP_PWR_LVL_P6 = 6, /*!< Corresponding to +6dbm */ ESP_PWR_LVL_P9 = 7, /*!< Corresponding to +9dbm */ ESP_PWR_LVL_N14 = ESP_PWR_LVL_N12, /*!< Backward compatibility! Setting to -14dbm will actually result to -12dbm */ ESP_PWR_LVL_N11 = ESP_PWR_LVL_N9, /*!< Backward compatibility! Setting to -11dbm will actually result to -9dbm */ ESP_PWR_LVL_N8 = ESP_PWR_LVL_N6, /*!< Backward compatibility! Setting to -8dbm will actually result to -6dbm */ ESP_PWR_LVL_N5 = ESP_PWR_LVL_N3, /*!< Backward compatibility! Setting to -5dbm will actually result to -3dbm */ ESP_PWR_LVL_N2 = ESP_PWR_LVL_N0, /*!< Backward compatibility! Setting to -2dbm will actually result to 0dbm */ ESP_PWR_LVL_P1 = ESP_PWR_LVL_P3, /*!< Backward compatibility! Setting to +1dbm will actually result to +3dbm */ ESP_PWR_LVL_P4 = ESP_PWR_LVL_P6, /*!< Backward compatibility! Setting to +4dbm will actually result to +6dbm */ ESP_PWR_LVL_P7 = ESP_PWR_LVL_P9, /*!< Backward compatibility! Setting to +7dbm will actually result to +9dbm */ esp_power_level_t;
返回值: esp_err_t	typedef int esp_err_t; /* Definitions for error constants. */ #define ESP_OK 0 /*!< esp_err_t value indicating success (no error) */ #define ESP_FAIL -1 /*!< Generic esp_err_t code indicating failure */ #define ESP_ERR_NO_MEM 0x101 /*!< Out of memory */ #define ESP_ERR_INVALID_ARG 0x102 /*!< Invalid argument */ #define ESP_ERR_INVALID_STATE 0x103 /*!< Invalid state */ #define ESP_ERR_INVALID_SIZE 0x104 /*!< Invalid size */ #define ESP_ERR_NOT_FOUND 0x105 /*!< Requested resource not found */ #define ESP_ERR_NOT_SUPPORTED 0x106 /*!< Operation or feature not supported */ #define ESP_ERR_TIMEOUT 0x107 /*!< Operation timed out */ #define ESP_ERR_INVALID_RESPONSE 0x108 /*!< Received response was invalid */ #define ESP_ERR_INVALID_CRC 0x109 /*!< CRC or checksum was invalid */ #define ESP_ERR_INVALID_VERSION 0x10A /*!< Version was invalid */ #define ESP_ERR_INVALID_MAC 0x10B /*!< MAC address was invalid */ #define ESP_ERR_WIFI_BASE 0x3000 /*!< Starting number of WiFi error codes */ #define ESP_ERR_MESH_BASE 0x4000 /*!< Starting number of MESH error codes */ #define ESP_ERR_FLASH_BASE 0x6000 /*!< Starting number of flash error codes */ #define ESP_ERR_HW_CRYPTO_BASE 0xc000 /*!< Starting number of HW cryptography module error codes */

esp_power_level_t esp_ble_tx_power_get(esp_ble_power_type_t power_type)

作用：根据特定的tx power类型，来获取ble tx power的等级

参数1：power_type tx power的级别

typedef enum ESP_BLE_PWR_TYPE_CONN_HDL0 = 0, /*!< For connection handle 0 */ ESP_BLE_PWR_TYPE_CONN_HDL1 = 1, /*!< For connection handle 1 */ ESP_BLE_PWR_TYPE_CONN_HDL2 = 2, /*!< For connection handle 2 */ ESP_BLE_PWR_TYPE_CONN_HDL3 = 3, /*!< For connection handle 3 */ ESP_BLE_PWR_TYPE_CONN_HDL4 = 4, /*!< For connection handle 4 */ ESP_BLE_PWR_TYPE_CONN_HDL5 = 5, /*!< For connection handle 5 */ ESP_BLE_PWR_TYPE_CONN_HDL6 = 6, /*!< For connection handle 6 */ ESP_BLE_PWR_TYPE_CONN_HDL7 = 7, /*!< For connection handle 7 */ ESP_BLE_PWR_TYPE_CONN_HDL8 = 8, /*!< For connection handle 8 */ ESP_BLE_PWR_TYPE_ADV = 9, /*!< For advertising */ ESP_BLE_PWR_TYPE_SCAN = 10, /*!< For scan */ ESP_BLE_PWR_TYPE_DEFAULT = 11, /*!< For default, if not set other, it will use default value */ ESP_BLE_PWR_TYPE_NUM = 12, /*!< TYPE numbers */ esp_ble_power_type_t;

返回值：power_level

typedef enum ESP_PWR_LVL_N12 = 0, /*!< Corresponding to -12dbm */ ESP_PWR_LVL_N9 = 1, /*!< Corresponding to -9dbm */ ESP_PWR_LVL_N6 = 2, /*!< Corresponding to -6dbm */ ESP_PWR_LVL_N3 = 3, /*!< Corresponding to -3dbm */ ESP_PWR_LVL_N0 = 4, /*!< Corresponding to 0dbm */ ESP_PWR_LVL_P3 = 5, /*!< Corresponding to +3dbm */ ESP_PWR_LVL_P6 = 6, /*!< Corresponding to +6dbm */ ESP_PWR_LVL_P9 = 7, /*!< Corresponding to +9dbm */ ESP_PWR_LVL_N14 = ESP_PWR_LVL_N12, /*!< Backward compatibility! Setting to -14dbm will actually result to -12dbm */ ESP_PWR_LVL_N11 = ESP_PWR_LVL_N9, /*!< Backward compatibility! Setting to -11dbm will actually result to -9dbm */ ESP_PWR_LVL_N8 = ESP_PWR_LVL_N6, /*!< Backward compatibility! Setting to -8dbm will actually result to -6dbm */ ESP_PWR_LVL_N5 = ESP_PWR_LVL_N3, /*!< Backward compatibility! Setting to -5dbm will actually result to -3dbm */ ESP_PWR_LVL_N2 = ESP_PWR_LVL_N0, /*!< Backward compatibility! Setting to -2dbm will actually result to 0dbm */ ESP_PWR_LVL_P1 = ESP_PWR_LVL_P3, /*!< Backward compatibility! Setting to +1dbm will actually result to +3dbm */ ESP_PWR_LVL_P4 = ESP_PWR_LVL_P6, /*!< Backward compatibility! Setting to +4dbm will actually result to +6dbm */ ESP_PWR_LVL_P7 = ESP_PWR_LVL_P9, /*!< Backward compatibility! Setting to +7dbm will actually result to +9dbm */ esp_power_level_t;

esp_err_t esp_bredr_tx_power_set(esp_power_level_t min_power_level, esp_power_level_t max_power_level)

作用：设置BR/EDR的tx power，这个函数会作用于整个传统蓝牙，包括搜索，paging,连接等，一定要在esp_bt_controller_enable函数之后以及在RF做TX的动作之前设置！

参数1：min_power_level 设置tx powr的最小值	typedef enum ESP_PWR_LVL_N12 = 0, /*!< Corresponding to -12dbm */ ESP_PWR_LVL_N9 = 1, /*!< Corresponding to -9dbm */ ESP_PWR_LVL_N6 = 2, /*!< Corresponding to -6dbm */ ESP_PWR_LVL_N3 = 3, /*!< Corresponding to -3dbm */ ESP_PWR_LVL_N0 = 4, /*!< Corresponding to 0dbm */ ESP_PWR_LVL_P3 = 5, /*!< Corresponding to +3dbm */ ESP_PWR_LVL_P6 = 6, /*!< Corresponding to +6dbm */ ESP_PWR_LVL_P9 = 7, /*!< Corresponding to +9dbm */ ESP_PWR_LVL_N14 = ESP_PWR_LVL_N12, /*!< Backward compatibility! Setting to -14dbm will actually result to -12dbm */ ESP_PWR_LVL_N11 = ESP_PWR_LVL_N9, /*!< Backward compatibility! Setting to -11dbm will actually result to -9dbm */ ESP_PWR_LVL_N8 = ESP_PWR_LVL_N6, /*!< Backward compatibility! Setting to -8dbm will actually result to -6dbm */ ESP_PWR_LVL_N5 = ESP_PWR_LVL_N3, /*!< Backward compatibility! Setting to -5dbm will actually result to -3dbm */ ESP_PWR_LVL_N2 = ESP_PWR_LVL_N0, /*!< Backward compatibility! Setting to -2dbm will actually result to 0dbm */ ESP_PWR_LVL_P1 = ESP_PWR_LVL_P3, /*!< Backward compatibility! Setting to +1dbm will actually result to +3dbm */ ESP_PWR_LVL_P4 = ESP_PWR_LVL_P6, /*!< Backward compatibility! Setting to +4dbm will actually result to +6dbm */ ESP_PWR_LVL_P7 = ESP_PWR_LVL_P9, /*!< Backward compatibility! Setting to +7dbm will actually result to +9dbm */ esp_power_level_t;
参数2：max_power_level 设置tx powr的最大值	typedef enum ESP_PWR_LVL_N12 = 0, /*!< Corresponding to -12dbm */ ESP_PWR_LVL_N9 = 1, /*!< Corresponding to -9dbm */ ESP_PWR_LVL_N6 = 2, /*!< Corresponding to -6dbm */ ESP_PWR_LVL_N3 = 3, /*!< Corresponding to -3dbm */ ESP_PWR_LVL_N0 = 4, /*!< Corresponding to 0dbm */ ESP_PWR_LVL_P3 = 5, /*!< Corresponding to +3dbm */ ESP_PWR_LVL_P6 = 6, /*!< Corresponding to +6dbm */ ESP_PWR_LVL_P9 = 7, /*!< Corresponding to +9dbm */ ESP_PWR_LVL_N14 = ESP_PWR_LVL_N12, /*!< Backward compatibility! Setting to -14dbm will actually result to -12dbm */ ESP_PWR_LVL_N11 = ESP_PWR_LVL_N9, /*!< Backward compatibility! Setting to -11dbm will actually result to -9dbm */ ESP_PWR_LVL_N8 = ESP_PWR_LVL_N6, /*!< Backward compatibility! Setting to -8dbm will actually result to -6dbm */ ESP_PWR_LVL_N5 = ESP_PWR_LVL_N3, /*!< Backward compatibility! Setting to -5dbm will actually result to -3dbm */ ESP_PWR_LVL_N2 = ESP_PWR_LVL_N0, /*!< Backward compatibility! Setting to -2dbm will actually result to 0dbm */ ESP_PWR_LVL_P1 = ESP_PWR_LVL_P3, /*!< Backward compatibility! Setting to +1dbm will actually result to +3dbm */ ESP_PWR_LVL_P4 = ESP_PWR_LVL_P6, /*!< Backward compatibility! Setting to +4dbm will actually result to +6dbm */ ESP_PWR_LVL_P7 = ESP_PWR_LVL_P9, /*!< Backward compatibility! Setting to +7dbm will actually result to +9dbm */ esp_power_level_t;
返回值：esp_err_t	在前面已经介绍

esp_err_t esp_bredr_tx_power_get(esp_power_level_t *min_power_level, esp_power_level_t *max_power_level)

作用：获取BR/EDR的tx power的最小/大值

参数1：*min_power_level 指针，返回的最小的tx power	在前面已经介绍
参数2：*max_power_level 指针，返回的最大的tx power	在前面已经介绍
返回值:esp_err_t	在前面已经介绍

esp_err_t esp_bredr_sco_datapath_set(esp_sco_data_path_t data_path)

作用：设置BR/EDR的sco的数据通路，应该在controller enable之后调用，并且在(e)SCO链接前建立

参数1：data_path sco的数据通路	typedef enum ESP_SCO_DATA_PATH_HCI = 0, /*!< data over HCI transport */ ESP_SCO_DATA_PATH_PCM = 1, /*!< data over PCM interface */ esp_sco_data_path_t;
返回值：esp_err_t	在前面已经介绍

esp_err_t esp_bt_controller_init(esp_bt_controller_config_t *cfg)

作用：根据config的参数来进行controller的初始化

参数1：*cfg controller的配置参数

typedef struct /* * Following parameters can be configured runtime, when call esp_bt_controller_init() */ uint16_t controller_task_stack_size; /*!< Bluetooth controller task stack size */ uint8_t controller_task_prio; /*!< Bluetooth controller task priority */ uint8_t hci_uart_no; /*!< If use UART1/2 as HCI IO interface, indicate UART number */ uint32_t hci_uart_baudrate; /*!< If use UART1/2 as HCI IO interface, indicate UART baudrate */ uint8_t scan_duplicate_mode; /*!< scan duplicate mode */ uint8_t scan_duplicate_type; /*!< scan duplicate type */ uint16_t normal_adv_size; /*!< Normal adv size for scan duplicate */ uint16_t mesh_adv_size; /*!< Mesh adv size for scan duplicate */ uint16_t send_adv_reserved_size; /*!< Controller minimum memory value */ uint32_t controller_debug_flag; /*!< Controller debug log flag */ uint8_t mode; /*!< Controller mode: BR/EDR, BLE or Dual Mode */ uint8_t ble_max_conn; /*!< BLE maximum connection numbers */ uint8_t bt_max_acl_conn; /*!< BR/EDR maximum ACL connection numbers */ uint8_t bt_sco_datapath; /*!< SCO data path, i.e. HCI or PCM module */ bool auto_latency; /*!< BLE auto latency, used to enhance classic BT performance */ bool bt_legacy_auth_vs_evt; /*!< BR/EDR Legacy auth complete event required to protect from BIAS attack */ /* * Following parameters can not be configured runtime when call esp_bt_controller_init() * It will be overwrite with a constant value which in menuconfig or from a macro. * So, do not modify the value when esp_bt_controller_init() */ uint8_t bt_max_sync_conn; /*!< BR/EDR maximum ACL connection numbers. Effective in menuconfig */ uint8_t ble_sca; /*!< BLE low power crystal accuracy index */ uint8_t pcm_role; /*!< PCM role (master & slave)*/ uint8_t pcm_polar; /*!< PCM polar trig (falling clk edge & rising clk edge) */ uint32_t magic; /*!< Magic number */ esp_bt_controller_config_t;

返回值：esp_err_t

在前面已经介绍

esp_err_t esp_bt_controller_deinit(void)

作用：De-initialize BT controller

esp_err_t esp_bt_controller_enable(esp_bt_mode_t mode)

作用：Enable 蓝牙controller

参数1：mode	typedef enum ESP_BT_MODE_IDLE = 0x00, /*!< Bluetooth is not running */ ESP_BT_MODE_BLE = 0x01, /*!< Run BLE mode */ ESP_BT_MODE_CLASSIC_BT = 0x02, /*!< Run Classic BT mode */ ESP_BT_MODE_BTDM = 0x03, /*!< Run dual mode */ esp_bt_mode_t;
返回值：esp_err_t	在前面已经介绍

esp_err_t esp_bt_controller_disable(void)

作用：Disable蓝牙controller

esp_bt_controller_status_t esp_bt_controller_get_status(void)

作用：获取controller的状态

返回值：esp_bt_controller_status_t

typedef enum ESP_BT_CONTROLLER_STATUS_IDLE = 0, ESP_BT_CONTROLLER_STATUS_INITED, ESP_BT_CONTROLLER_STATUS_ENABLED, ESP_BT_CONTROLLER_STATUS_NUM, esp_bt_controller_status_t;

bool esp_vhci_host_check_send_available(void)

作用：检查是否可以向controller发送数据

void esp_vhci_host_send_packet(uint8_t *data, uint16_t len)

作用：Host发送数据给Controller

参数1： *data	Host准备发送给Controller的数据
参数2： len	Host准备发送给Controller的数据长度

esp_err_t esp_vhci_host_register_callback(const esp_vhci_host_callback_t *callback)

作用：host像controller注册callback函数，包括可发送的callback跟接收数据的callback

参数1：*callback	typedef struct esp_vhci_host_callback void (*notify_host_send_available)(void); /*!< callback used to notify that the host can send packet to controller */ 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*/ esp_vhci_host_callback_t;
返回值：esp_err_t	在前面已经介绍

esp_err_t esp_bt_controller_mem_release(esp_bt_mode_t mode)

作用：释放bt controller的bss,heap数据，节省内存，只能在esp_bt_controller_init函数之前调用或者esp_bt_controller_deinit函数之后调用，一般的用法是你用BR/EDR，那么你就释放BLE，如果你用BLE，那么就释放BR/EDR的

参数1：mode	typedef enum ESP_BT_MODE_IDLE = 0x00, /*!< Bluetooth is not running */ ESP_BT_MODE_BLE = 0x01, /*!< Run BLE mode */ ESP_BT_MODE_CLASSIC_BT = 0x02, /*!< Run Classic BT mode */ ESP_BT_MODE_BTDM = 0x03, /*!< Run dual mode */ esp_bt_mode_t;
返回值：esp_err_t	在前面已经介绍

esp_err_t esp_bt_mem_release(esp_bt_mode_t mode)

作用：释放内存，首先会先调用esp_bt_controller_mem_release函数

esp_err_t esp_bt_sleep_enable(void)

作用：使能bt controller的休眠

esp_err_t esp_bt_sleep_disable(void)

作用：禁止bt controller休眠

esp_err_t esp_ble_scan_dupilcate_list_flush(void)

作用：手动清除BLE scan列表()

我们最常用的就是esp_bt_controller_init/esp_bt_controller_enable/esp_bt_controller_disable/esp_bt_controller_deinit,我们大概来画下这几个函数的流程