ESP-IDF 藍(lán)牙 API 參考指南Bluedroid 與 NimBLE 協(xié)議棧選型、VHCI 控制器接口與 BLE Mesh/ISO/Audio 擴(kuò)展生態(tài)【免費(fèi)下載鏈接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/es/esp-idf藍(lán)牙是物聯(lián)網(wǎng)設(shè)備最常用的短距離無線通信手段之一而 ESP-IDF 作為樂鑫 SoC 的官方開發(fā)框架內(nèi)置了完整且可配置的藍(lán)牙協(xié)議棧體系。本文以 ESP-IDF 官方中文文檔的「藍(lán)牙 API」章節(jié)為核心系統(tǒng)梳理 ESP-IDF 中的藍(lán)牙架構(gòu)兩種可切換的主機(jī)協(xié)議棧Bluedroid 與 NimBLE、主機(jī)與控制器之間的 VHCI 接口、BLE GAP/GATT 核心 API以及 ESP-BLE-MESH、ESP-BLE-ISO、ESP-BLE-AUDIO 等擴(kuò)展能力。讀完本文你將掌握在 menuconfig 中正確選型協(xié)議棧、定位各功能對應(yīng)的 API 文檔與示例代碼、并理解 NimBLE 的移植架構(gòu)與典型編程時(shí)序從而快速開啟自己的藍(lán)牙應(yīng)用開發(fā)。一、ESP-IDF 藍(lán)牙協(xié)議棧總覽兩種主機(jī)一個(gè)控制器ESP-IDF 的藍(lán)牙子系統(tǒng)遵循標(biāo)準(zhǔn)的分層架構(gòu)**控制器Controller**負(fù)責(zé)射頻收發(fā)、鏈路層狀態(tài)機(jī)等底層功能**主機(jī)Host**負(fù)責(zé) GAP、GATT、SM 等協(xié)議層的實(shí)現(xiàn)。ESP-IDF 支持兩種可切換的主機(jī)協(xié)議棧二者共用同一個(gè)控制器通過 VHCI 接口與主機(jī)通信主機(jī)協(xié)議棧支持的藍(lán)牙技術(shù)特點(diǎn)與適用場景Bluedroid默認(rèn)經(jīng)典藍(lán)牙BR/EDR 低功耗藍(lán)牙BLE雙模協(xié)議棧適合同時(shí)使用經(jīng)典藍(lán)牙與 BLE 的應(yīng)用如音頻、HID、傳統(tǒng)配對場景NimBLE僅低功耗藍(lán)牙BLE輕量級協(xié)議棧代碼體積小、內(nèi)存占用低適合資源受限的純 BLE 應(yīng)用這一選型邏輯在倉庫的 Kconfig 中有直接體現(xiàn)。components/bt/Kconfig 中通過choice BT_HOST提供了三個(gè)選項(xiàng)BT_BLUEDROID_ENABLEDBluedroid - Dual-mode注釋明確說明“推薦用于經(jīng)典藍(lán)牙或雙模使用場景”BT_NIMBLE_ENABLEDNimBLE - BLE only注釋說明“推薦用于純 BLE 場景以節(jié)省內(nèi)存”BT_CONTROLLER_ONLYDisabled完全禁用主機(jī)用于直接與控制器通信如配合外部主機(jī)協(xié)議棧。同時(shí)BT_CONTROLLER選項(xiàng)可獨(dú)立控制控制器是否啟用BT_CONTROLLER_ENABLED/BT_CONTROLLER_DISABLED后者適用于“僅主機(jī)Host only”場景。因此實(shí)際項(xiàng)目中你可以組合出“Bluedroid 控制器”“NimBLE 控制器”“僅控制器”等多種形態(tài)。二、控制器接口 APIVHCI 與樂鑫自定義 HCI 命令2.1 控制器接口文檔藍(lán)牙主機(jī)協(xié)議棧與控制器之間的底層接口由 控制器接口 API 文檔 提供。該文檔包含 VHCIVirtual HCI虛擬主機(jī)控制器接口相關(guān) API 的參考說明是理解“主機(jī)—控制器”通信的入口。2.2 樂鑫自定義 HCI 命令文檔特別強(qiáng)調(diào)樂鑫自定義 HCI 命令Espressif Vendor-Specific HCI Commands專為 Espressif 的藍(lán)牙主機(jī)協(xié)議?；騼?nèi)部調(diào)試用途設(shè)計(jì)應(yīng)用程序開發(fā)者不應(yīng)在應(yīng)用程序中初始化或調(diào)用這些命令。其詳細(xì)說明見 bt_vhci 文檔。2.3 控制器相關(guān)示例examples/bluetooth/hci 目錄提供了多個(gè)控制器/HCI 層面的實(shí)戰(zhàn)示例ble_adv_scan_combined演示如何使用樂鑫自定義 HCI 命令進(jìn)行藍(lán)牙廣播和掃描在沒有主機(jī)的情況下實(shí)現(xiàn)部分主機(jī)功能并顯示其他設(shè)備的掃描廣播報(bào)告適用于 ESP32controller_hci_uart_esp32配置 ESP32 上 BLE 控制器的 HCI 通過 UART 通信從而與外部藍(lán)牙主機(jī)協(xié)議棧對接controller_hci_uart_esp32c3_and_esp32s3上述 UART HCI 方案的 ESP32-C3 / ESP32-S3 版本controller_vhci_ble_adv使用 ESP-IDF 的ble_advertising應(yīng)用在無主機(jī)情況下進(jìn)行廣播并顯示從控制器接收到的 HCI 事件。這些示例與BT_CONTROLLER_ONLYKconfig 中Disabled選項(xiàng)的定位一致當(dāng)你希望繞過內(nèi)置主機(jī)、直接驅(qū)動控制器或?qū)拥谌街鳈C(jī)時(shí)HCI 相關(guān)示例是最直接的參考。三、Bluedroid 協(xié)議棧 API默認(rèn)主機(jī)Bluedroid 是 ESP-IDF 的默認(rèn)主機(jī)協(xié)議棧支持經(jīng)典藍(lán)牙與低功耗藍(lán)牙雙模。其 API 參考分為三大部分入口見 Bluedroid 協(xié)議棧 API 中的對應(yīng)小節(jié)。3.1 藍(lán)牙通用 APIbt_common藍(lán)牙通用 API 文檔 提供經(jīng)典藍(lán)牙和低功耗藍(lán)牙共用的定義與 API為各藍(lán)牙組件提供基礎(chǔ)功能統(tǒng)一負(fù)責(zé)藍(lán)牙的初始化、配置和設(shè)備管理。它由以下子部分構(gòu)成Bluetooth Defineesp_bt_defs提供兩種藍(lán)牙技術(shù)共用的定義和數(shù)據(jù)結(jié)構(gòu)Bluetooth Mainesp_bt_main提供核心 API用于初始化、啟用/禁用和管理藍(lán)牙主機(jī)協(xié)議棧Bluetooth Deviceesp_bt_device提供設(shè)備級 API管理設(shè)備屬性如地址、名稱、可見性和共存設(shè)置。每個(gè)子部分通常包含三類內(nèi)容概述主要用途、核心功能和關(guān)鍵接口、應(yīng)用示例典型使用場景、API 參考頭文件、函數(shù)、結(jié)構(gòu)體、宏、類型定義和枚舉的詳細(xì)說明。3.2 經(jīng)典藍(lán)牙 APIclassic_bt經(jīng)典藍(lán)牙BR/EDRAPI 僅在芯片支持經(jīng)典藍(lán)牙SOC_BT_CLASSIC_SUPPORTED時(shí)可用對應(yīng)文檔為 classic_bt其下進(jìn)一步拆分為 GAPesp_gap_bt、SPPesp_spp、A2DPesp_a2dp、AVRCPesp_avrc、HFPesp_hf_ag / esp_hf_client、HIDesp_hidd / esp_hidh、L2CAPesp_l2cap_bt、SDPesp_sdp等細(xì)分 API 文檔。該子章節(jié)只有在目標(biāo)芯片具備經(jīng)典藍(lán)牙能力時(shí)才會出現(xiàn)在文檔導(dǎo)航中對應(yīng) RST 中的:SOC_BT_CLASSIC_SUPPORTED:條件。3.3 低功耗藍(lán)牙 APIbt_le低功耗藍(lán)牙 API 文檔 是物聯(lián)網(wǎng)場景的核心章節(jié)涵蓋用于設(shè)備發(fā)現(xiàn)、數(shù)據(jù)交換以及通過 BLE 進(jìn)行 Wi-Fi 配網(wǎng)的 API。其包含的核心部分如下API 模塊文檔作用BLE GAPesp_gap_ble設(shè)備廣播、掃描、連接管理及安全操作BLE GATT Defineesp_gatt_defs定義 GATT 操作中使用的屬性、特征、UUID 及相關(guān)常量和數(shù)據(jù)類型BLE GATT Serveresp_gatts向遠(yuǎn)程客戶端提供服務(wù)和特征外圍設(shè)備角色BLE GATT Clientesp_gattc發(fā)現(xiàn)并訪問遠(yuǎn)程服務(wù)器的服務(wù)中心設(shè)備角色BLE BluFiesp_blufi通過 BLE 實(shí)現(xiàn) Wi-Fi 配網(wǎng)和配置僅SOC_BLUFI_SUPPORTED芯片其中 GATT Server/Client 構(gòu)成了 BLE 數(shù)據(jù)交互的主體外圍設(shè)備Peripheral通過 GATT Server 暴露服務(wù)和特征中心設(shè)備Central通過 GATT Client 發(fā)現(xiàn)并讀寫這些特征。而 BluFi 則是樂鑫生態(tài)中極具特色的能力——利用 BLE 通道完成 Wi-Fi 憑據(jù)的安全配網(wǎng)。四、NimBLE 協(xié)議棧 API輕量級 BLE 主機(jī)NimBLE 是 Apache MyNewt 項(xiàng)目中的 BLE 協(xié)議棧ESP-IDF 將其移植到 ESP32 平臺與 FreeRTOS 之上詳見 NimBLE 協(xié)議棧 API中文文檔通過 include 直接復(fù)用英文原版內(nèi)容。4.1 架構(gòu)NimBLE 主機(jī)與 ESP 控制器的橋接NimBLE 是一個(gè)高度可配置、可通過藍(lán)牙 SIG 認(rèn)證的 BLE 協(xié)議棧同時(shí)提供主機(jī)與控制器功能。在 ESP-IDF 中NimBLE 僅作為主機(jī)運(yùn)行底層控制器與 Bluedroid 方案完全一致同樣提供 VHCI 接口。原生 NimBLE 在主機(jī)與控制器之間支持 UART、RAM 等多種傳輸方式但RAM 傳輸無法直接用于 ESP 平臺——ESP 控制器基于 VHCI 接口且 NimBLE 主機(jī)的緩沖方案與 ESP 控制器不兼容。因此ESP-IDF 為 NimBLE 主機(jī)與 ESP 控制器之間新增了專門的傳輸層該層負(fù)責(zé)維護(hù)傳輸緩沖池并按雙方要求格式化主機(jī)與控制器之間交換的數(shù)據(jù)4.2 線程模型NimBLE 主機(jī)既可以在應(yīng)用程序線程內(nèi)運(yùn)行也可以擁有自己獨(dú)立的線程——這一靈活性是 NimBLE 設(shè)計(jì)固有的。默認(rèn)情況下移植函數(shù)nimble_port_freertos_init會創(chuàng)建一個(gè)獨(dú)立線程來運(yùn)行主機(jī)棧該行為可通過覆寫override此函數(shù)來改變。對于 BLE Mesh 場景還會額外使用一個(gè)廣播線程advertising thread持續(xù)向主線程投喂廣播事件。相關(guān)接口聲明見 nimble_port_freertos.hvoid nimble_port_freertos_init(TaskFunction_t host_task_fn);。4.3 典型編程時(shí)序使用 NimBLE 主機(jī)棧的典型開發(fā)流程如下前提在 menuconfig 中將藍(lán)牙主機(jī)選擇為 NimBLE即CONFIG_BT_HOST對應(yīng)的BT_NIMBLE_ENABLED選項(xiàng)調(diào)用nvs_flash_init()初始化 NVS Flash——因?yàn)?ESP 控制器在初始化過程中會使用 NVS調(diào)用nimble_port_init()初始化主機(jī)與控制器協(xié)議棧初始化所需的 NimBLE 主機(jī)配置參數(shù)與回調(diào)函數(shù)執(zhí)行應(yīng)用程序相關(guān)的任務(wù)/初始化調(diào)用nimble_port_freertos_init運(yùn)行主機(jī)協(xié)議棧線程。這五步構(gòu)成了所有 NimBLE 應(yīng)用廣播、掃描、GATT 客戶端/服務(wù)端、Mesh 等的公共骨架各場景的差異主要體現(xiàn)在第 3、4 步配置的具體參數(shù)與回調(diào)上。4.4 API 參考NimBLE 主機(jī) API 參考主要由esp_nimble_hci頭文件生成include-build-file機(jī)制完整的 NimBLE API 細(xì)節(jié)可參閱 Apache Mynewt NimBLE 官方用戶指南ESP-IDF 文檔中已提供外部鏈接。五、ESP-BLE-MESH API可管理的泛洪 Mesh 網(wǎng)絡(luò)當(dāng)芯片支持 BLE MeshSOC_BLE_MESH_SUPPORTED時(shí)ESP-BLE-MESH API 可用。ESP-BLE-MESH 在標(biāo)準(zhǔn) BLE 之上實(shí)現(xiàn)了 Mesh 協(xié)議適用于照明、傳感器等需要組網(wǎng)通信的場景構(gòu)建的是“可管理的泛洪managed floodingMesh 網(wǎng)絡(luò)”。5.1 核心概念配網(wǎng)、節(jié)點(diǎn)與 Provisioner配網(wǎng)ProvisioningESP32 要加入 BLE Mesh 網(wǎng)絡(luò)必須先完成配網(wǎng)。作為未配網(wǎng)設(shè)備Unprovisioned Device配網(wǎng)后加入網(wǎng)絡(luò)并成為ESP-BLE-MESH 節(jié)點(diǎn)Node可與無線射程內(nèi)外的其他節(jié)點(diǎn)通信Provisioner網(wǎng)絡(luò)中還有一種 ESP32 角色——配網(wǎng)器Provisioner它負(fù)責(zé)把未配網(wǎng)設(shè)備配成節(jié)點(diǎn)并對節(jié)點(diǎn)進(jìn)行各種功能配置。5.2 API 參考結(jié)構(gòu)ESP-BLE-MESH 的 API 劃分為四大塊ESP-BLE-MESH Definitions僅一個(gè)頭文件列出所有模型的 ID 與相關(guān)消息 opcode、model/element/Composition Data 的結(jié)構(gòu)體、配網(wǎng)用結(jié)構(gòu)體、收發(fā)消息結(jié)構(gòu)體、事件類型及事件參數(shù)ESP-BLE-MESH Core API Reference覆蓋六個(gè)組件——協(xié)議棧初始化、本地?cái)?shù)據(jù)信息讀取、低功耗操作更新中、發(fā)送/發(fā)布消息與添加本地 AppKey 等、Node/Provisioner 配網(wǎng)、GATT Proxy Server以及與 BLE 共存的相關(guān) APIESP-BLE-MESH Models API Reference六類模型——Configuration、Health、Generic、Sensor、Time and Scenes、Lighting 的 Client/Server 模型 APIServer 模型相關(guān)定義仍在持續(xù)更新ESP-BLE-MESH (v1.1) Core API Reference預(yù)覽版覆蓋十個(gè) v1.1 特性組件——Remote Provisioning遠(yuǎn)程配網(wǎng)、Directed Forwarding定向轉(zhuǎn)發(fā)、Subnet Bridge Configuration子網(wǎng)橋接、Mesh Private Beacon私有信標(biāo)、On-Demand Private Proxy按需私有代理、SAR 配置、Solicitation PDU RPL 配置、Opcodes Aggregator操作碼聚合、Large Composition Data大組合數(shù)據(jù)、Composition and Metadata組合與元數(shù)據(jù)此外還包含 Device Firmware Update設(shè)備固件升級與 Device Firmware Slots API。需要特別留意文檔明確注明v1.1 相關(guān)代碼為預(yù)覽版本涉及的結(jié)構(gòu)體、宏與 API 后續(xù)可能變更基于 v1.1 特性開發(fā)時(shí)需要關(guān)注版本演進(jìn)。六、ESP-BLE-ISO API等時(shí)通道CIS/BIS當(dāng)芯片支持 BLE 等時(shí)通道SOC_BLE_ISO_SUPPORTED時(shí)ESP-BLE-ISO API 可用。該模塊實(shí)現(xiàn) BLE 的等時(shí)通道CISConnected Isochronous Stream面向連接的等時(shí)流用于一對一/一對多的實(shí)時(shí)音頻等場景BISBroadcast Isochronous Stream廣播式等時(shí)流用于一對多的廣播場景。其典型應(yīng)用是**藍(lán)牙低功耗音頻LE Audio**以及需要時(shí)間同步的數(shù)據(jù)流傳輸。配套示例位于 examples/bluetooth/esp_ble_iso源碼實(shí)現(xiàn)位于 components/bt/esp_ble_iso包含 69 個(gè)頭文件與 33 個(gè) C 源文件是研究等時(shí)通道實(shí)現(xiàn)細(xì)節(jié)的入口。七、ESP-BLE-AUDIO API低功耗音頻配置與服務(wù)當(dāng)芯片支持 BLE 音頻SOC_BLE_AUDIO_SUPPORTED時(shí)ESP-BLE-AUDIO API 可用。ESP-BLE-AUDIO 提供了 LE Audio 生態(tài)的配置與服務(wù)支持覆蓋 BAP、PACS、VCP、HAS、CSIP 等核心 Profile/服務(wù)BAPBasic Audio Profile基礎(chǔ)音頻規(guī)范定義音頻流的建立與管理PACSPublished Audio Capabilities Service發(fā)布音頻能力VCPVolume Control Profile音量控制HASHearing Access Service助聽器接入服務(wù)CSIPCoordinated Set Identification Profile協(xié)調(diào)組識別如左右耳機(jī)組。相關(guān)示例與實(shí)現(xiàn)分別位于 examples/bluetooth/esp_ble_audio160 個(gè)文件與 components/bt/esp_ble_audio84 個(gè)頭文件、54 個(gè) C 源文件。若你計(jì)劃開發(fā) TWS 耳機(jī)、助聽器或 LE Audio 音頻設(shè)備這一模塊是核心依賴。八、示例與教程從文檔到可運(yùn)行代碼8.1 三類官方示例入口ESP-IDF 為各協(xié)議棧提供了豐富的可運(yùn)行示例均在 examples/bluetooth 目錄下Bluedroidexamples/bluetooth/bluedroid含 ble、ble_50、classic_bt、coex、bluedroid_host_only 等子目錄NimBLEexamples/bluetooth/nimble含 blecent、blehr、bleprph、blemesh、ble_l2cap_coc、ble_periodic_adv、ble_multi_conn、throughput_app 等 30 余個(gè)子目錄BLE UART Serviceexamples/bluetooth/ble_uart_service基于 NimBLE 或 Bluedroid 的即用型藍(lán)牙串口透傳外設(shè)提供標(biāo)準(zhǔn) BLE UART Service GATT 布局其倉庫中同時(shí)提供了sdkconfig.bluedroid、sdkconfig.defaults以及 CI 用的sdkconfig.ci.nimble/sdkconfig.ci.bluedroid配置可直觀對照兩種主機(jī)棧的配置差異。8.2 Bluedroid 分步教程Walkthrough官方為 Bluedroid 提供了六篇圖文并茂的分步示例教程從零講解 GATT 開發(fā)的各個(gè)環(huán)節(jié)GATT 客戶端示例教程GATT 服務(wù)端服務(wù)表格示例教程GATT 服務(wù)端示例教程GATT 客戶端安全性示例教程GATT 服務(wù)端安全性示例教程GATT 客戶端多連接示例教程這套教程覆蓋了“單連接客戶端/服務(wù)端 → 安全配對 → 多連接”的完整進(jìn)階路徑是學(xué)習(xí) Bluedroid BLE 開發(fā)的推薦起點(diǎn)。8.3 NimBLE 分步教程N(yùn)imBLE 同樣有三篇官方分步教程BLE 中心設(shè)備Central示例教程BLE 心率Heart Rate示例教程BLE 外圍設(shè)備Peripheral示例教程其中 blehr 是經(jīng)典的心率傳感器例程對外廣播心率服務(wù)bleprph 是通用外設(shè)例程blecent 則是與之配對連接的中心設(shè)備例程三者組合即可快速搭建一個(gè)完整的 BLE 采集鏈路。8.4 架構(gòu)與概念指南在動手編碼之前建議先通讀 API 指南API Guides中的架構(gòu)文檔它們與 API 參考互為補(bǔ)充藍(lán)牙架構(gòu)指南講解 ESP-IDF 藍(lán)牙子系統(tǒng)整體架構(gòu)經(jīng)典藍(lán)牙指南面向支持經(jīng)典藍(lán)牙的芯片僅SOC_BT_CLASSIC_SUPPORTED時(shí)提供BLE 指南BLE 概念與開發(fā)教程。九、開發(fā)選型速查與上手建議結(jié)合全文內(nèi)容給出如下選型與上手建議雙模需求經(jīng)典藍(lán)牙 BLE選擇Bluedroid默認(rèn)參考 examples/bluetooth/bluedroid音頻場景可關(guān)注 classic_bt 下的 A2DP/AVRCP/HFP 示例純 BLE 且資源受限選擇NimBLE以節(jié)省內(nèi)存參考 examples/bluetooth/nimble先跑通 bleprph/blecent/blehr 三個(gè)教程快速實(shí)現(xiàn)串口透傳直接使用 ble_uart_service按sdkconfig.bluedroid或 NimBLE 配置編譯即可組網(wǎng)場景照明、傳感器使用ESP-BLE-MESH從配網(wǎng)概念入手參考 examples/bluetooth/esp_ble_meshLE Audio / 時(shí)間同步流確認(rèn)芯片支持SOC_BLE_ISO_SUPPORTED/SOC_BLE_AUDIO_SUPPORTED后使用ESP-BLE-ISO / ESP-BLE-AUDIO參考 examples/bluetooth/esp_ble_iso 與 examples/bluetooth/esp_ble_audio外部主機(jī) / 裸控制器在 components/bt/Kconfig 中選擇BT_CONTROLLER_ONLY參考 examples/bluetooth/hci 下的 UART/VHCI 示例。所有 API 的最終權(quán)威細(xì)節(jié)函數(shù)簽名、結(jié)構(gòu)體、枚舉、宏均以對應(yīng)文檔頁中的API 參考部分由頭文件自動生成為準(zhǔn)開發(fā)時(shí)建議同時(shí)打開頭文件與示例交叉閱讀以獲得最準(zhǔn)確的調(diào)用信息?！久赓M(fèi)下載鏈接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/es/esp-idf創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考