ESP-IDF 经典蓝牙Bluetooth ClassicAPI 全览GAP、L2CAP、SPP、A2DP、AVRCP、HFP 与 HID 实践指南【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idfESP-IDF 经典蓝牙 API 是 Espressif 官方开发框架中用于实现传统蓝牙Bluetooth BR/EDR即经典蓝牙功能的完整接口集合覆盖音频流传输、设备通信、串口数据交换、免提通话与人机交互设备等场景。本文基于 docs/zh_CN/api-reference/bluetooth/classic_bt.rst 展开系统梳理经典蓝牙 API 的分层结构与各配置文件Profile的职责划分并结合仓库内 examples/bluetooth/bluedroid/classic_bt 下的真实示例帮助你快速定位所需模块、理解初始化调用链并上手第一个经典蓝牙应用。经典蓝牙 API 能做什么经典蓝牙 API 提供用于实现传统蓝牙功能的 API包括音频流传输、设备通信以及通过串口配置文件进行数据交换。它支持多种蓝牙配置文件使 ESP 设备能够在无线音频、远程控制和数据传输等场景中同时扮演源设备Source或接收设备Sink/Acceptor的角色。经典蓝牙 API 提供以下主要功能核心协议支持GAP通用访问配置文件、L2CAP逻辑链路控制与适配协议和 SDP服务发现协议串行数据通信SPP串口配置文件高质量音频流传输A2DP高级音频分发配置文件媒体播放控制AVRCP音视频远程控制配置文件免提通话支持HFP免提配置文件输入设备连接HID人机接口设备支持主机和外设角色这些功能使得一块 ESP 开发板既可以作为蓝牙音箱、耳机A2DP Sink HFP HF也可以作为音频发射端A2DP Source、键盘鼠标HID Device、串口透传设备SPP Acceptor/Initiator等。API 分层结构与模块地图经典蓝牙 API 在 ESP-IDF 中划分为三大层次核心协议、通信配置文件、音频与媒体配置文件以及 HFP 与 HID 两大专项。每个部分在 API 文档中通常包含概述、应用示例和 API 参考三个板块涵盖用途、主要功能、示例用法及详细 API 文档。核心协议层核心协议是经典蓝牙一切功能的地基由三个 API 组成Bluetooth GAP通用访问配置文件负责设备发现、配对及安全管理是应用与底层蓝牙协议栈交互的主要入口。Bluetooth L2CAP逻辑链路控制与适配协议负责数据多路复用和通道管理是上层配置文件承载数据的传输管道。Bluetooth SDP服务发现协议用于发现远程设备的服务和属性使设备之间能够互相告知“我能提供什么服务”。通信配置文件Bluetooth SPP串口配置文件通过蓝牙模拟串行通信通道进行数据交换SPP API 同时提供 Initiator客户端和 Acceptor服务端两种角色的创建能力并可运行在不同安全要求下。音频与媒体配置文件Bluetooth A2DP高级音频分发配置文件提供高质量音频流传输同时支持源Source和接收端Sink两种角色。Bluetooth AVRCP音视频远程控制配置文件提供媒体播放控制包括播放、暂停、音量调节、切歌以及媒体元数据如封面图的获取。免提配置文件HFPHFP 按角色拆分为三个紧密相关的文档Bluetooth HFP DefineHFP 角色共享的核心定义包含呼叫管理、音频控制、网络状态上报所需的常量、枚举与结构体。Bluetooth HFP Client实现免提单元Hands-Free Unit, HF角色例如耳机、车载套件。Bluetooth HFP AG实现音频网关Audio Gateway, AG角色例如手机。人机接口设备HIDBluetooth HID Device实现外设角色如键盘、鼠标或游戏手柄。Bluetooth HID Host实现主机角色用于连接远程 HID 外设。说明上述各子文档的中文页面docs/zh_CN/api-reference/bluetooth/目录与英文页面内容保持一致例如 esp_gap_bt.rst 通过.. include::指令直接复用英文源文件确保多语言文档不漂移。从零搭建经典蓝牙应用初始化调用链无论使用哪个配置文件经典蓝牙应用都遵循一条共同的初始化路径。以 bt_discovery 示例支持 ESP32 与 ESP32-S31为例可以清晰看到完整调用链1. 头文件引入#include esp_bt.h // 配置蓝牙控制器与主机侧 VHCI #include esp_bt_main.h // 初始化并启用 Bluedroid 协议栈 #include esp_bt_device.h // 设备配置如设备地址与设备名称 #include esp_gap_bt_api.h // GAP 配置经典蓝牙设备与服务发现其中esp_bt.h负责配置蓝牙控制器和 VHCI主机控制器接口的虚拟实现esp_bt_main.h负责初始化并启用 Bluedroid 协议栈esp_gap_bt_api.h实现 GAP 配置esp_bt_device.h实现设备地址、设备名等配置。2. NVS 初始化Bluetooth 功能需要非易失存储NVS来保存 PHY 校准数据等键值对esp_err_t ret nvs_flash_init(); if (ret ESP_ERR_NVS_NO_FREE_PAGES || ret ESP_ERR_NVS_NEW_VERSION_FOUND) { ESP_ERROR_CHECK(nvs_flash_erase()); ret nvs_flash_init(); } ESP_ERROR_CHECK(ret);3. 释放未使用模式的控制器内存若只使用经典蓝牙不启用 BLE应释放 BLE 对应的控制器内存以节省 RAMESP_ERROR_CHECK(esp_bt_controller_mem_release(ESP_BT_MODE_BLE));控制器内存只能在初始化蓝牙控制器之前或反初始化之后释放且一旦释放不可逆——被释放的模式将无法再使用。如果需要双模BLE 经典蓝牙共存则控制器应以ESP_BT_MODE_BTDM模式使能且不能释放 BLE 内存。4. 初始化并启用蓝牙控制器蓝牙控制器实现 HCI 控制器侧、链路层LL和物理层PHY对用户应用不可见。使用BT_CONTROLLER_INIT_CONFIG_DEFAULT()宏生成默认配置含栈大小、优先级、HCI 波特率等再调用esp_bt_controller_init()与esp_bt_controller_enable()esp_bt_controller_config_t bt_cfg BT_CONTROLLER_INIT_CONFIG_DEFAULT(); ESP_ERROR_CHECK(esp_bt_controller_init(bt_cfg)); ESP_ERROR_CHECK(esp_bt_controller_enable(ESP_BT_MODE_CLASSIC_BT));ESP-IDF 共支持四种蓝牙模式模式含义ESP_BT_MODE_IDLE蓝牙未运行ESP_BT_MODE_BLE仅 BLE 模式ESP_BT_MODE_CLASSIC_BT仅经典蓝牙模式ESP_BT_MODE_BTDM双模BLE 经典蓝牙5. 初始化并启用 Bluedroid 协议栈Bluedroid 协议栈包含经典蓝牙与 BLE 共用的定义与 API同样采用“默认配置宏 init enable”三步esp_bluedroid_config_t bluedroid_cfg BT_BLUEDROID_INIT_CONFIG_DEFAULT(); ESP_ERROR_CHECK(esp_bluedroid_init_with_cfg(bluedroid_cfg)); ESP_ERROR_CHECK(esp_bluedroid_enable());完成以上步骤后应用即可注册 GAP 回调、设置设备名称、设置可发现/可连接模式并启动设备发现流程。设备发现与服务发现GAP 的典型用法bt_discovery 是理解 GAP 的最佳入门示例其流程为查询附近设备 → 依据 CoDClass of Device设备类别字段筛选目标 → 停止查询 → 通过 SDP 执行服务发现。设置设备信息与启动查询应用先注册 GAP 事件回调设置设备名称并使其可被发现、可被连接esp_bt_gap_register_callback(bt_app_gap_cb); esp_bt_gap_set_device_name(ESP_GAP_INQRUIY); esp_bt_gap_set_scan_mode(ESP_BT_CONNECTABLE, ESP_BT_GENERAL_DISCOVERABLE);随后调用esp_bt_gap_start_discovery()发起常规查询general inquiry持续 10 秒esp_bt_gap_start_discovery(ESP_BT_INQ_MODE_GENERAL_INQUIRY, 10, 0);从发现结果中提取设备属性查询过程中GAP 回调会收到ESP_BT_GAP_DISC_RES_EVT其结果中包含多个属性property示例中通过属性类型逐一解析 CoD、RSSI、设备名BDNAME与 EIR扩展查询结果switch (p-type) { case ESP_BT_GAP_DEV_PROP_COD: cod *(uint32_t *)(p-val); break; case ESP_BT_GAP_DEV_PROP_RSSI: rssi *(int8_t *)(p-val); break; case ESP_BT_GAP_DEV_PROP_BDNAME: bdname_len (p-len ESP_BT_GAP_MAX_BDNAME_LEN) ? ESP_BT_GAP_MAX_BDNAME_LEN : (uint8_t)p-len; bdname (uint8_t *)(p-val); break; case ESP_BT_GAP_DEV_PROP_EIR: eir_len p-len; eir (uint8_t *)(p-val); break; }值得注意的是部分蓝牙设备把设备名放在 EIR 数据中因此当 BDNAME 为空时需要从 EIR 中提取名称get_name_from_eir()。依据 CoD 筛选目标设备示例依据 CoD 字段查找主设备类型为“Phone电话”或“Audio/Video音视频”的设备过滤无效 CoDif (!esp_bt_gap_is_valid_cod(cod) || (!(esp_bt_gap_get_cod_major_dev(cod) ESP_BT_COD_MAJOR_DEV_PHONE) !(esp_bt_gap_get_cod_major_dev(cod) ESP_BT_COD_MAJOR_DEV_AV))) { return; }找到目标设备后调用esp_bt_gap_cancel_discovery()停止查询并进入服务发现阶段。SDP 服务发现查询停止后回调收到ESP_BT_GAP_DISC_STATE_CHANGED_EVT状态为ESP_BT_GAP_DISCOVERY_STOPPED。随后调用esp_bt_gap_get_remote_services(p_dev-bda);服务发现结果通过ESP_BT_GAP_RMT_SRVCS_EVT事件返回其中包含远程设备的服务 UUID 列表应用可据此判断目标设备支持哪些服务如 A2DP、SPP、HFP 等从而决定后续建立哪种连接。各配置文件的角色与对应示例经典蓝牙的每个配置文件都对应仓库 examples/bluetooth/bluedroid/classic_bt 下的真实可运行示例下表汇总了角色与示例的对应关系配置文件角色/能力对应示例GAP设备发现、配对、安全管理bt_discoveryL2CAP数据多路复用、通道管理bt_l2cap_client、bt_l2cap_serverSDP服务与属性发现、记录发布内嵌于bt_l2cap_client/bt_l2cap_serverSPP虚拟串口通信Initiator / Acceptorbt_spp_initiator、bt_spp_acceptor、bt_spp_vfs_initiator、bt_spp_vfs_acceptorA2DP高质量音频流Source / Sinka2dp_source、a2dp_sink_stream、a2dp_source_aac、a2dp_sink_stream_aacAVRCP媒体播放控制、绝对音量、元数据、封面图avrcp_absolute_volume、avrcp_ct_metadata、avrcp_ct_cover_artHFP免提通话HF / AGhfp_hf、hfp_agHID输入设备Device / Hostbt_hid_mouse_device外设角色以下按配置文件逐一展开其核心能力与示例要点。SPP通过虚拟串口交换数据SPP 让两个蓝牙设备通过虚拟串行链路交换数据API 同时支持创建 Initiator客户端和 Acceptor服务端并可配置不同的安全要求bt_spp_acceptor创建作为服务端的 SPP Acceptor并集成安全简单配对SSP同时提供与 Initiator 通信的演示。bt_spp_initiator创建作为客户端的 SPP Initiator同样集成 SSP。bt_spp_vfs_initiator使用虚拟文件系统VFS接口收发数据的 SPP Initiator 版本——通过 VFS 抽象SPP 通道可以像操作文件一样被读写显著简化上层数据流处理。仓库中还有配套的 ESP32_SSP.md 文档说明 SSP安全简单配对的集成方式适合关注配对安全细节的读者。A2DP高质量音频流传输A2DP 用于在蓝牙设备之间传输高质量音频典型场景是从手机、电脑、媒体播放器等源设备向蓝牙音箱、耳机、车载音响等接收设备推流。ESP-IDF 的 A2DP API 支持收发双向音频流a2dp_sink_stream实现 A2DP 接收端Sink接收音频流并通过 I2S 接口输出是搭建“ESP32 蓝牙音箱”的参考实现其tutorial子目录还包含逐步讲解。a2dp_source使用 A2DP API 发送音频流Source 角色。a2dp_sink_stream_aac 与 a2dp_source_aac分别在 Sink 与 Source 侧使用 AAC 编解码器适用于需要 AAC 而非默认 SBC 编码的应用。此外examples/bluetooth/bluedroid/coex/a2dp_gatts_coex 演示了 A2DP 与 BLE GATT 服务共存Coexistence的用法——当 A2DP 与 GATT 需同时运行时可从该示例了解内存与无线资源分配方式。AVRCP媒体播放控制AVRCP 让设备能够远程控制音频/视频设备的播放行为。ESP-IDF 提供三个递进式示例avrcp_absolute_volume实现绝对音量控制。avrcp_ct_metadata获取媒体元数据如歌曲名、艺术家等并配有pytest_classic_bt_metadata_test.py测试。avrcp_ct_cover_art获取并展示封面图Cover Art这是 AVRCP 较新扩展能力其测试位于 pytest_classic_bt_cover_art_test.py。HFP免提通话HFP 按角色拆分为两个示例与 API 文档的 HF/AG 划分一一对应hfp_hf实现免提单元HF角色即耳机、车载套件侧与实现了音频网关HF-AG的设备如智能手机通信。hfp_ag实现音频网关AG角色与实现 HF 角色的设备如耳机通信提供配置项目、建立连接、控制音量、接听/拒接来电等命令。两个示例均提供sdkconfig.ci.all、sdkconfig.ci.extcodec、sdkconfig.ci.vohci等 CI 配置变体extcodec与vohci分别涉及扩展编解码与基于 HCI 的语音传输可作为功能裁剪的参考。HID人机接口设备bt_hid_mouse_device实现 HID 外设角色示例中表现为蓝牙鼠标可作为实现键盘、游戏手柄等其他输入设备的起点。主机角色示例见 examples/bluetooth/esp_hid_host用于连接远程 HID 外设。L2CAP 与 SDP 的配合以 bt_l2cap 示例为例L2CAP 与 SDP 通常是配合使用的客户端通过 SDP 搜索远程设备的服务记录从中解析出 L2CAP 的 PSMProtocol/Service Multiplexer协议/服务复用器值再据此建立 L2CAP 通道。bt_l2cap_client注册 SDP 回调、初始化 SDP调用esp_sdp_search_record()搜索远程服务记录并从结果中取得 L2CAP PSM 值以建立连接。其 tutorial 目录配有两张示意图辅助理解流程。bt_l2cap_server注册 SDP 回调、初始化 SDP调用esp_sdp_create_record()创建携带 L2CAP PSM 信息的服务记录使服务对远程客户端可见可查。构建、烧录与验证经典蓝牙示例与 ESP-IDF 其他项目一样通过idf.py完成配置、构建与烧录。以 bt_discovery 为例idf.py menuconfig # 配置项目 idf.py -p PORT build flash monitor # 构建、烧录并打开串口监视器退出串口监视器使用快捷键Ctrl-]。运行 bt_discovery 后串口日志会依次打印发现到的设备属性CoD、RSSI、设备名在找到目标设备后打印其地址与名称再打印通过 SDP 发现的远程服务 UUID 列表。在硬件方面经典蓝牙示例通常面向支持 BR/EDR 的芯片如 ESP32、ESP32-S31仓库中的示例普遍带有sdkconfig.defaults与sdkconfig.defaults.esp32s31等按芯片区分的默认配置使用前请确认目标芯片对经典蓝牙BR/EDR的支持情况以及是否需要为双模共存调整内存分配。小结ESP-IDF 经典蓝牙 API 是一个层次清晰、示例完备的协议栈接口集合底层由 GAP、L2CAP、SDP 三大核心协议支撑上层由 SPP、A2DP、AVRCP、HFP、HID 等配置文件提供具体业务能力且每个模块均可在 examples/bluetooth/bluedroid/classic_bt 中找到对应实现作为上手蓝本。阅读对应子文档如 esp_gap_bt.rst、esp_a2dp.rst、esp_spp.rst 等可获取各 API 的完整参考结合示例代码即可快速搭建无线音频、远程控制、串口透传或免提通话等经典蓝牙应用。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ESP-IDF 经典蓝牙（Bluetooth Classic）API 全览：GAP、L2CAP、SPP、A2DP、AVRCP、HFP 与 HID 实践指南
ESP-IDF 经典蓝牙Bluetooth ClassicAPI 全览GAP、L2CAP、SPP、A2DP、AVRCP、HFP 与 HID 实践指南【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idfESP-IDF 经典蓝牙 API 是 Espressif 官方开发框架中用于实现传统蓝牙Bluetooth BR/EDR即经典蓝牙功能的完整接口集合覆盖音频流传输、设备通信、串口数据交换、免提通话与人机交互设备等场景。本文基于 docs/zh_CN/api-reference/bluetooth/classic_bt.rst 展开系统梳理经典蓝牙 API 的分层结构与各配置文件Profile的职责划分并结合仓库内 examples/bluetooth/bluedroid/classic_bt 下的真实示例帮助你快速定位所需模块、理解初始化调用链并上手第一个经典蓝牙应用。经典蓝牙 API 能做什么经典蓝牙 API 提供用于实现传统蓝牙功能的 API包括音频流传输、设备通信以及通过串口配置文件进行数据交换。它支持多种蓝牙配置文件使 ESP 设备能够在无线音频、远程控制和数据传输等场景中同时扮演源设备Source或接收设备Sink/Acceptor的角色。经典蓝牙 API 提供以下主要功能核心协议支持GAP通用访问配置文件、L2CAP逻辑链路控制与适配协议和 SDP服务发现协议串行数据通信SPP串口配置文件高质量音频流传输A2DP高级音频分发配置文件媒体播放控制AVRCP音视频远程控制配置文件免提通话支持HFP免提配置文件输入设备连接HID人机接口设备支持主机和外设角色这些功能使得一块 ESP 开发板既可以作为蓝牙音箱、耳机A2DP Sink HFP HF也可以作为音频发射端A2DP Source、键盘鼠标HID Device、串口透传设备SPP Acceptor/Initiator等。API 分层结构与模块地图经典蓝牙 API 在 ESP-IDF 中划分为三大层次核心协议、通信配置文件、音频与媒体配置文件以及 HFP 与 HID 两大专项。每个部分在 API 文档中通常包含概述、应用示例和 API 参考三个板块涵盖用途、主要功能、示例用法及详细 API 文档。核心协议层核心协议是经典蓝牙一切功能的地基由三个 API 组成Bluetooth GAP通用访问配置文件负责设备发现、配对及安全管理是应用与底层蓝牙协议栈交互的主要入口。Bluetooth L2CAP逻辑链路控制与适配协议负责数据多路复用和通道管理是上层配置文件承载数据的传输管道。Bluetooth SDP服务发现协议用于发现远程设备的服务和属性使设备之间能够互相告知“我能提供什么服务”。通信配置文件Bluetooth SPP串口配置文件通过蓝牙模拟串行通信通道进行数据交换SPP API 同时提供 Initiator客户端和 Acceptor服务端两种角色的创建能力并可运行在不同安全要求下。音频与媒体配置文件Bluetooth A2DP高级音频分发配置文件提供高质量音频流传输同时支持源Source和接收端Sink两种角色。Bluetooth AVRCP音视频远程控制配置文件提供媒体播放控制包括播放、暂停、音量调节、切歌以及媒体元数据如封面图的获取。免提配置文件HFPHFP 按角色拆分为三个紧密相关的文档Bluetooth HFP DefineHFP 角色共享的核心定义包含呼叫管理、音频控制、网络状态上报所需的常量、枚举与结构体。Bluetooth HFP Client实现免提单元Hands-Free Unit, HF角色例如耳机、车载套件。Bluetooth HFP AG实现音频网关Audio Gateway, AG角色例如手机。人机接口设备HIDBluetooth HID Device实现外设角色如键盘、鼠标或游戏手柄。Bluetooth HID Host实现主机角色用于连接远程 HID 外设。说明上述各子文档的中文页面docs/zh_CN/api-reference/bluetooth/目录与英文页面内容保持一致例如 esp_gap_bt.rst 通过.. include::指令直接复用英文源文件确保多语言文档不漂移。从零搭建经典蓝牙应用初始化调用链无论使用哪个配置文件经典蓝牙应用都遵循一条共同的初始化路径。以 bt_discovery 示例支持 ESP32 与 ESP32-S31为例可以清晰看到完整调用链1. 头文件引入#include esp_bt.h // 配置蓝牙控制器与主机侧 VHCI #include esp_bt_main.h // 初始化并启用 Bluedroid 协议栈 #include esp_bt_device.h // 设备配置如设备地址与设备名称 #include esp_gap_bt_api.h // GAP 配置经典蓝牙设备与服务发现其中esp_bt.h负责配置蓝牙控制器和 VHCI主机控制器接口的虚拟实现esp_bt_main.h负责初始化并启用 Bluedroid 协议栈esp_gap_bt_api.h实现 GAP 配置esp_bt_device.h实现设备地址、设备名等配置。2. NVS 初始化Bluetooth 功能需要非易失存储NVS来保存 PHY 校准数据等键值对esp_err_t ret nvs_flash_init(); if (ret ESP_ERR_NVS_NO_FREE_PAGES || ret ESP_ERR_NVS_NEW_VERSION_FOUND) { ESP_ERROR_CHECK(nvs_flash_erase()); ret nvs_flash_init(); } ESP_ERROR_CHECK(ret);3. 释放未使用模式的控制器内存若只使用经典蓝牙不启用 BLE应释放 BLE 对应的控制器内存以节省 RAMESP_ERROR_CHECK(esp_bt_controller_mem_release(ESP_BT_MODE_BLE));控制器内存只能在初始化蓝牙控制器之前或反初始化之后释放且一旦释放不可逆——被释放的模式将无法再使用。如果需要双模BLE 经典蓝牙共存则控制器应以ESP_BT_MODE_BTDM模式使能且不能释放 BLE 内存。4. 初始化并启用蓝牙控制器蓝牙控制器实现 HCI 控制器侧、链路层LL和物理层PHY对用户应用不可见。使用BT_CONTROLLER_INIT_CONFIG_DEFAULT()宏生成默认配置含栈大小、优先级、HCI 波特率等再调用esp_bt_controller_init()与esp_bt_controller_enable()esp_bt_controller_config_t bt_cfg BT_CONTROLLER_INIT_CONFIG_DEFAULT(); ESP_ERROR_CHECK(esp_bt_controller_init(bt_cfg)); ESP_ERROR_CHECK(esp_bt_controller_enable(ESP_BT_MODE_CLASSIC_BT));ESP-IDF 共支持四种蓝牙模式模式含义ESP_BT_MODE_IDLE蓝牙未运行ESP_BT_MODE_BLE仅 BLE 模式ESP_BT_MODE_CLASSIC_BT仅经典蓝牙模式ESP_BT_MODE_BTDM双模BLE 经典蓝牙5. 初始化并启用 Bluedroid 协议栈Bluedroid 协议栈包含经典蓝牙与 BLE 共用的定义与 API同样采用“默认配置宏 init enable”三步esp_bluedroid_config_t bluedroid_cfg BT_BLUEDROID_INIT_CONFIG_DEFAULT(); ESP_ERROR_CHECK(esp_bluedroid_init_with_cfg(bluedroid_cfg)); ESP_ERROR_CHECK(esp_bluedroid_enable());完成以上步骤后应用即可注册 GAP 回调、设置设备名称、设置可发现/可连接模式并启动设备发现流程。设备发现与服务发现GAP 的典型用法bt_discovery 是理解 GAP 的最佳入门示例其流程为查询附近设备 → 依据 CoDClass of Device设备类别字段筛选目标 → 停止查询 → 通过 SDP 执行服务发现。设置设备信息与启动查询应用先注册 GAP 事件回调设置设备名称并使其可被发现、可被连接esp_bt_gap_register_callback(bt_app_gap_cb); esp_bt_gap_set_device_name(ESP_GAP_INQRUIY); esp_bt_gap_set_scan_mode(ESP_BT_CONNECTABLE, ESP_BT_GENERAL_DISCOVERABLE);随后调用esp_bt_gap_start_discovery()发起常规查询general inquiry持续 10 秒esp_bt_gap_start_discovery(ESP_BT_INQ_MODE_GENERAL_INQUIRY, 10, 0);从发现结果中提取设备属性查询过程中GAP 回调会收到ESP_BT_GAP_DISC_RES_EVT其结果中包含多个属性property示例中通过属性类型逐一解析 CoD、RSSI、设备名BDNAME与 EIR扩展查询结果switch (p-type) { case ESP_BT_GAP_DEV_PROP_COD: cod *(uint32_t *)(p-val); break; case ESP_BT_GAP_DEV_PROP_RSSI: rssi *(int8_t *)(p-val); break; case ESP_BT_GAP_DEV_PROP_BDNAME: bdname_len (p-len ESP_BT_GAP_MAX_BDNAME_LEN) ? ESP_BT_GAP_MAX_BDNAME_LEN : (uint8_t)p-len; bdname (uint8_t *)(p-val); break; case ESP_BT_GAP_DEV_PROP_EIR: eir_len p-len; eir (uint8_t *)(p-val); break; }值得注意的是部分蓝牙设备把设备名放在 EIR 数据中因此当 BDNAME 为空时需要从 EIR 中提取名称get_name_from_eir()。依据 CoD 筛选目标设备示例依据 CoD 字段查找主设备类型为“Phone电话”或“Audio/Video音视频”的设备过滤无效 CoDif (!esp_bt_gap_is_valid_cod(cod) || (!(esp_bt_gap_get_cod_major_dev(cod) ESP_BT_COD_MAJOR_DEV_PHONE) !(esp_bt_gap_get_cod_major_dev(cod) ESP_BT_COD_MAJOR_DEV_AV))) { return; }找到目标设备后调用esp_bt_gap_cancel_discovery()停止查询并进入服务发现阶段。SDP 服务发现查询停止后回调收到ESP_BT_GAP_DISC_STATE_CHANGED_EVT状态为ESP_BT_GAP_DISCOVERY_STOPPED。随后调用esp_bt_gap_get_remote_services(p_dev-bda);服务发现结果通过ESP_BT_GAP_RMT_SRVCS_EVT事件返回其中包含远程设备的服务 UUID 列表应用可据此判断目标设备支持哪些服务如 A2DP、SPP、HFP 等从而决定后续建立哪种连接。各配置文件的角色与对应示例经典蓝牙的每个配置文件都对应仓库 examples/bluetooth/bluedroid/classic_bt 下的真实可运行示例下表汇总了角色与示例的对应关系配置文件角色/能力对应示例GAP设备发现、配对、安全管理bt_discoveryL2CAP数据多路复用、通道管理bt_l2cap_client、bt_l2cap_serverSDP服务与属性发现、记录发布内嵌于bt_l2cap_client/bt_l2cap_serverSPP虚拟串口通信Initiator / Acceptorbt_spp_initiator、bt_spp_acceptor、bt_spp_vfs_initiator、bt_spp_vfs_acceptorA2DP高质量音频流Source / Sinka2dp_source、a2dp_sink_stream、a2dp_source_aac、a2dp_sink_stream_aacAVRCP媒体播放控制、绝对音量、元数据、封面图avrcp_absolute_volume、avrcp_ct_metadata、avrcp_ct_cover_artHFP免提通话HF / AGhfp_hf、hfp_agHID输入设备Device / Hostbt_hid_mouse_device外设角色以下按配置文件逐一展开其核心能力与示例要点。SPP通过虚拟串口交换数据SPP 让两个蓝牙设备通过虚拟串行链路交换数据API 同时支持创建 Initiator客户端和 Acceptor服务端并可配置不同的安全要求bt_spp_acceptor创建作为服务端的 SPP Acceptor并集成安全简单配对SSP同时提供与 Initiator 通信的演示。bt_spp_initiator创建作为客户端的 SPP Initiator同样集成 SSP。bt_spp_vfs_initiator使用虚拟文件系统VFS接口收发数据的 SPP Initiator 版本——通过 VFS 抽象SPP 通道可以像操作文件一样被读写显著简化上层数据流处理。仓库中还有配套的 ESP32_SSP.md 文档说明 SSP安全简单配对的集成方式适合关注配对安全细节的读者。A2DP高质量音频流传输A2DP 用于在蓝牙设备之间传输高质量音频典型场景是从手机、电脑、媒体播放器等源设备向蓝牙音箱、耳机、车载音响等接收设备推流。ESP-IDF 的 A2DP API 支持收发双向音频流a2dp_sink_stream实现 A2DP 接收端Sink接收音频流并通过 I2S 接口输出是搭建“ESP32 蓝牙音箱”的参考实现其tutorial子目录还包含逐步讲解。a2dp_source使用 A2DP API 发送音频流Source 角色。a2dp_sink_stream_aac 与 a2dp_source_aac分别在 Sink 与 Source 侧使用 AAC 编解码器适用于需要 AAC 而非默认 SBC 编码的应用。此外examples/bluetooth/bluedroid/coex/a2dp_gatts_coex 演示了 A2DP 与 BLE GATT 服务共存Coexistence的用法——当 A2DP 与 GATT 需同时运行时可从该示例了解内存与无线资源分配方式。AVRCP媒体播放控制AVRCP 让设备能够远程控制音频/视频设备的播放行为。ESP-IDF 提供三个递进式示例avrcp_absolute_volume实现绝对音量控制。avrcp_ct_metadata获取媒体元数据如歌曲名、艺术家等并配有pytest_classic_bt_metadata_test.py测试。avrcp_ct_cover_art获取并展示封面图Cover Art这是 AVRCP 较新扩展能力其测试位于 pytest_classic_bt_cover_art_test.py。HFP免提通话HFP 按角色拆分为两个示例与 API 文档的 HF/AG 划分一一对应hfp_hf实现免提单元HF角色即耳机、车载套件侧与实现了音频网关HF-AG的设备如智能手机通信。hfp_ag实现音频网关AG角色与实现 HF 角色的设备如耳机通信提供配置项目、建立连接、控制音量、接听/拒接来电等命令。两个示例均提供sdkconfig.ci.all、sdkconfig.ci.extcodec、sdkconfig.ci.vohci等 CI 配置变体extcodec与vohci分别涉及扩展编解码与基于 HCI 的语音传输可作为功能裁剪的参考。HID人机接口设备bt_hid_mouse_device实现 HID 外设角色示例中表现为蓝牙鼠标可作为实现键盘、游戏手柄等其他输入设备的起点。主机角色示例见 examples/bluetooth/esp_hid_host用于连接远程 HID 外设。L2CAP 与 SDP 的配合以 bt_l2cap 示例为例L2CAP 与 SDP 通常是配合使用的客户端通过 SDP 搜索远程设备的服务记录从中解析出 L2CAP 的 PSMProtocol/Service Multiplexer协议/服务复用器值再据此建立 L2CAP 通道。bt_l2cap_client注册 SDP 回调、初始化 SDP调用esp_sdp_search_record()搜索远程服务记录并从结果中取得 L2CAP PSM 值以建立连接。其 tutorial 目录配有两张示意图辅助理解流程。bt_l2cap_server注册 SDP 回调、初始化 SDP调用esp_sdp_create_record()创建携带 L2CAP PSM 信息的服务记录使服务对远程客户端可见可查。构建、烧录与验证经典蓝牙示例与 ESP-IDF 其他项目一样通过idf.py完成配置、构建与烧录。以 bt_discovery 为例idf.py menuconfig # 配置项目 idf.py -p PORT build flash monitor # 构建、烧录并打开串口监视器退出串口监视器使用快捷键Ctrl-]。运行 bt_discovery 后串口日志会依次打印发现到的设备属性CoD、RSSI、设备名在找到目标设备后打印其地址与名称再打印通过 SDP 发现的远程服务 UUID 列表。在硬件方面经典蓝牙示例通常面向支持 BR/EDR 的芯片如 ESP32、ESP32-S31仓库中的示例普遍带有sdkconfig.defaults与sdkconfig.defaults.esp32s31等按芯片区分的默认配置使用前请确认目标芯片对经典蓝牙BR/EDR的支持情况以及是否需要为双模共存调整内存分配。小结ESP-IDF 经典蓝牙 API 是一个层次清晰、示例完备的协议栈接口集合底层由 GAP、L2CAP、SDP 三大核心协议支撑上层由 SPP、A2DP、AVRCP、HFP、HID 等配置文件提供具体业务能力且每个模块均可在 examples/bluetooth/bluedroid/classic_bt 中找到对应实现作为上手蓝本。阅读对应子文档如 esp_gap_bt.rst、esp_a2dp.rst、esp_spp.rst 等可获取各 API 的完整参考结合示例代码即可快速搭建无线音频、远程控制、串口透传或免提通话等经典蓝牙应用。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考