esp-iot-solution BLE Services 组件实战指南在 esp_ble_conn_mgr 上接入 ANS/BAS/HRS/OTA 等标准 GATT 服务【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution本指南基于 esp-iot-solution 仓库中的 BLE Services 文档 及 组件源码 展开系统介绍如何在 ESP32 系列芯片上以统一、简化的 API 接入蓝牙标准 GATT 服务ANS、BAS、BCS、CTS、DIS、HRS、HTS、IAS、MIDI、OTA、OTS、TPS、UDS、WSS。读完本文你将掌握ble_services组件的安装方式、与ble_conn_mgr的集成初始化流程、各服务的能力与 UUID 定义并能参照示例快速实现电池电量上报、心率采集、设备信息广播、BLE 空中升级等真实场景。一、BLE Services 组件是什么在 BLE GATT 开发中逐个定义服务、特征Characteristic、描述符并手动处理读写回调往往繁琐且易错。esp-iot-solution 提供的ble_services组件 在 GATT Server 之上封装了一层简化 API 接口把蓝牙 SIG 定义的常用标准服务以及 ESP 自定义的 OTA 服务封装成可直接调用的函数开发者只需注册服务 读写特征值即可完成大部分业务。组件 READMEcomponents/bluetooth/ble_services/README.md明确指出其职责Theble_servicescomponent provides a simplified API interface for accessing commonly used standard and custom BLE services functionality on a GATT server.组件共包含 14 个服务每个服务在components/bluetooth/ble_services/下拥有独立子目录ans/、bas/、bcs/、cts/、dis/、hrs/、hts/、ias/、midi/、ota/、ots/、tps/、uds/、wss/目录内统一组织为include/esp_xxx.h服务公共 API 头文件UUID 宏、数据结构、读写/订阅函数、回调注册函数src/esp_xxx.c基于esp_ble_conn_mgr的 GATT 注册与数据收发实现Kconfig.in该服务的 menuconfig 开关。从源码结构看这是一个连接管理 服务注册解耦的架构连接、广播、事件分发由ble_conn_mgr统一负责ble_services只负责把各服务注册进 GATT 表二者通过esp_ble_conn_add_svc()等接口衔接。组件 README 也特别提示本组件依赖ble_conn_mgr才能工作。二、服务全景14 个服务的用途与 UUID 一览以下汇总了各服务在 BLE 生态中的典型用途、服务 UUID 及本文档/示例对应位置。其中服务 UUID 均可在各服务头文件中的BLE_XXX_UUID16宏确认如 esp_ias.h 中的BLE_IAS_UUID16 0x1802、esp_bas.h 中的BLE_BAS_UUID16 0x180F。服务全称服务 UUID用途概述示例ANSAlert Notification Service0x1811暴露设备告警信息ble_ansBASBattery Service0x180F暴露电池电量及充放电信息ble_basBCSBody Composition Service0x181B体成分分析仪数据健身/医疗ble_bcsCTSCurrent Time Service0x1805日期与时间信息暴露/同步ble_ctsDISDevice Information Service0x180A制造商/厂商信息ble_disHRSHeart Rate Service0x180D心率传感器数据健身场景ble_hrsHTSHealth Thermometer Service0x1809体温计温度数据医疗场景ble_htsIASImmediate Alert Service0x1802远程触发立即告警如防丢见 ble_ias.rstMIDIMIDI Service0x1804MIDI 音乐数据传输组件内midi/OTAESP BLE OTA Service0x8018ESP 自定义的 BLE 升级传输服务ble_otaOTSObject Transfer Service0x1825基于 L2CAP CoC 的大数据对象传输ble_otsTPSTX Power Service0x1804连接中当前发射功率ble_tpsUDSUser Data Service0x181C用户资料远程访问/同步运动、家居、医疗ble_udsWSSWeight Scale Service0x181D体重秤体重及相关数据ble_wss说明ble_services.rst文档目录页docs/en/bluetooth/ble_services.rst收录了除 MIDI 外的 13 个服务子页而组件源码中 MIDI 同样被实现见 Kconfig 中的midi/Kconfig.in故本文按组件实际能力介绍 14 个服务。各子页文档如 ble_ans.rst、ble_hrs.rst对服务的语义做了精确定义例如ANS暴露设备中发生的告警信息包括①告警类型②附加文本信息如来电号码、发送者 ID③新告警计数④未读告警计数。BAS在电池与设备电气连接的语境下暴露 Battery Level 及其他电池信息。HRS暴露面向健身应用的心率及其他心率传感器数据。HTS暴露面向医疗应用的温度计温度及相关数据。DIS暴露设备的制造商和/或厂商信息。CTS定义蓝牙设备如何向其他蓝牙设备暴露日期和时间信息。OTS提供批量数据传输的管理与控制能力数据本体经由独立的 L2CAP 面向连接通道CoC传输。TPS暴露设备处于连接状态时当前的发射功率水平。UDS在运动健身、家居或医疗环境中暴露用户相关数据支持客户端远程访问/更新以及服务端与客户端之间的数据同步。WSS暴露来自体重秤的体重及相关数据面向消费医疗和运动健身应用。三、快速上手安装组件与创建示例工程ble_services已发布到 ESP 组件仓库Component Registry推荐使用IDF 组件管理器idf-component-manager引入CMake 阶段会自动下载。1. 添加依赖到你的工程idf.py add-dependency espressif/ble_services*2. 从示例模板直接创建工程以 Device Information Service 为例idf.py create-project-from-example espressif/ble_services*:ble_dis示例会被下载到当前目录随后即可按常规流程idf.py build、idf.py flash monitor。仓库中也内置了可直接浏览的完整示例源码位于 examples/bluetooth/ble_services包括ble_ans、ble_bas、ble_bcs、ble_cts、ble_dis、ble_hrs、ble_hts、ble_ots、ble_tps、ble_uds、ble_wss等目录每个示例都包含main/目录app_main.c 服务相关源码、sdkconfig.defaults与sdkconfig.ci.nimble表明示例在 CI 中基于 NimBLE 协议栈验证。常见问题组件 README 的 QA若执行create-project-from-example时报错CMakeLists.txt not found in project directory /home/username说明使用的组件管理器版本过旧请在 ESP-IDF 环境下执行pip install -U idf-component-manager更新后再试。四、统一初始化流程服务如何挂载到 ble_conn_mgrble_services的所有服务都不是独立运行的而是注册到连接管理器之上。以 ble_bas 示例的 app_main.c 为例标准流程如下#include esp_ble_conn_mgr.h #include esp_bas.h void app_main(void) { esp_ble_conn_config_t config { .device_name CONFIG_EXAMPLE_BLE_ADV_NAME, // 广播名称menuconfig 可配 .broadcast_data CONFIG_EXAMPLE_BLE_SUB_ADV // 广播数据 }; // 1. 初始化 NVS首次失败时擦除重试 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); // 2. 创建默认事件循环注册连接事件处理器可选用于打印连接/断开日志 esp_event_loop_create_default(); esp_event_handler_register(BLE_CONN_MGR_EVENTS, ESP_EVENT_ANY_ID, app_ble_conn_event_handler, NULL); // 3. 注册服务组件前先初始化连接管理器 esp_ble_conn_init(config); // 4. 注册具体的 GATT 服务此处为 Battery Service esp_ble_bas_init(); // 5. 启动广播与连接 if (esp_ble_conn_start() ! ESP_OK) { esp_ble_conn_stop(); esp_ble_conn_deinit(); esp_event_handler_unregister(BLE_CONN_MGR_EVENTS, ESP_EVENT_ANY_ID, app_ble_conn_event_handler); } }这套流程在所有服务示例中高度一致对比 ble_ans 示例 可见仅把esp_ble_bas_init()换成esp_ble_ans_init()并引入对应头文件esp_ans.h可归纳为五个固定步骤NVS 初始化BLE 地址等参数需要持久化存储事件循环与连接事件注册监听BLE_CONN_MGR_EVENTSESP_BLE_CONN_EVENT_CONNECTED/ESP_BLE_CONN_EVENT_DISCONNECTEDesp_ble_conn_init(config)用设备名、广播数据等配置初始化连接管理器esp_ble_xxx_init()在 GATT Server 上注册对应服务必须在esp_ble_conn_init()之后、esp_ble_conn_start()之前调用esp_ble_conn_start()开始广播并等待连接失败时需依次stop、deinit、注销事件处理器完成回滚。五、深度解析一Battery ServiceBASBAS 是 BLE 设备最常用的服务之一。从 esp_bas.h 可以看出该组件实现的 BAS 远不止基础的电量等级还覆盖了 Battery Service v1.1 中新增的丰富特征特征名称特征 UUID说明Battery Level0x2A19电池电量百分比0–100Battery Level Status0x2BED电量等级状态功率状态、充电状态、充电类型、充电故障原因、附加状态等Estimated Service Date0x2BEF预计需要服务/更换电池的日期24bitBattery Critical Status0x2BE9关键电源状态、是否需立即维护Battery Energy Status0x2BF0可用电池容量、可用能量、充电速率、电压等Battery Time Status0x2BEE放电/待机时间、充电时间24bitBattery Health Status0x2BEA电池健康摘要、当前温度、循环次数、深度放电次数Battery Health Information0x2BEB设计循环寿命、设计工作温度范围Battery Information0x2BEC化学体系、设计容量、制造日期、失效日期、标称电压、可否充电/更换对应地头文件提供成对 APIesp_ble_bas_get_battery_level()/esp_ble_bas_set_battery_level()、esp_ble_bas_get_level_status()/esp_ble_bas_set_level_status()、esp_ble_bas_get_estimated_date()/esp_ble_bas_set_estimated_date()、esp_ble_bas_get_critical_status()/esp_ble_bas_set_critical_status()、esp_ble_bas_get_energy_status()/esp_ble_bas_set_energy_status()、esp_ble_bas_get_time_status()/esp_ble_bas_set_time_status()、esp_ble_bas_get_health_status()/esp_ble_bas_set_health_status()、esp_ble_bas_get_health_info()/esp_ble_bas_set_health_info()、esp_ble_bas_get_battery_info()/esp_ble_bas_set_battery_info()。头文件同时定义了丰富的位掩码与取值宏例如功率状态中WIRED_EXTERNAL_POWER_SOURCE_*未连接/已连接/未知/RFU、电池充电状态未知/充电中/放电激活/放电非激活、充电类型恒流/恒压/涓流/浮充、充电故障原因无故障/电池故障/外部电源故障/其他等便于开发者用可读的宏而非裸数字填装特征值。示例工程 app_bas.c 将这些 API 封装成 ESP Console 命令bas便于在串口终端上联调bas -t 00~01 -c 01~09-t操作类型0为 Set向特征写值1为 Get读取特征-c特征编号01Battery Level、02Battery Level Status、03Estimated Service Date、04Battery Critical Status、05Battery Energy Status、06Battery Time Status、07Battery Health Status、08Battery Health Information、09Battery Information。示例内部用esp_random() % N生成随机测试值如电量取0~100、电压取0~220可以快速验证 GATT 读写链路是否打通。六、深度解析二Immediate Alert ServiceIASIAS 是防丢器、寻物标签类产品的经典服务。其语义很简单暴露一个Alert Level特征UUID 0x2A06服务 UUID 0x1802对端写入后设备立即发出声音或震动提示。ble_ias.rst 与 esp_ias.h 共同给出了完整接入说明Alert Level 是一个单字节值仅三档合法取值宏定义数值含义ESP_BLE_IAS_ALERT_LEVEL_NO_ALERT0x00无告警ESP_BLE_IAS_ALERT_LEVEL_MILD_ALERT0x01轻度告警ESP_BLE_IAS_ALERT_LEVEL_HIGH_ALERT0x02高度告警接入步骤文档原文要点在 menuconfig 中使能CONFIG_BLE_IAS用esp_ble_conn_init()初始化 BLE 连接管理器如工程需要还需创建默认事件循环连接管理器初始化完成后、esp_ble_conn_start()之前调用esp_ble_ias_init()把 IAS 注册到 GATT Server在esp_ble_ias_init()之后再调用esp_ble_ias_register_alert_cb()注册告警回调——先保证服务已存在再挂接处理有效 Alert Level 写入的处理器。对应 API 及语义见 esp_ias.hesp_ble_ias_init()注册 IAS 服务返回ESP_OK或来自esp_ble_conn_add_svc()的错误码esp_ble_ias_register_alert_cb(esp_ble_ias_alert_cb_t cb, void *priv)注册/注销传NULLAlert Level 写入回调回调携带对端写入的alert_level与用户私有指针privesp_ble_ias_get_alert_level(uint8_t *level)读取客户端最近一次写入的 Alert Level默认ESP_BLE_IAS_ALERT_LEVEL_NO_ALERTlevel为NULL时返回ESP_ERR_INVALID_ARG。IAS 没有独立的示例工程文档建议参照其他 BLE 服务示例 的初始化模式来接入。七、深度解析三ESP BLE OTA 传输服务ble_services中的 OTA 服务esp_ble_ota_svc.h是一个传输层transport-levelGATT 服务定义在0x8018只负责固件数据的收发通道可被不同的 OTA profile 逻辑复用。文档 ble_ota_svc.rst 给出了四个特征特征UUID方向与用途RECV_FW0x8020固件数据写入Write w/o rsp 固件 ACK 通知NotifyPROGRESS_BAR0x8021升级进度值Read NotifyCOMMAND0x8022OTA 命令写入Write w/o rsp 命令 ACK 通知NotifyCUSTOMER0x8023厂商自定义数据通道Write w/o rsp Notify源码中几个关键设计点载荷上限BLE_OTA_ATT_PAYLOAD_MAX_LEN 512单次 ATT 写入/通知最大 512 字节超限返回ESP_ERR_INVALID_SIZE进度条编码BLE_OTA_PROGRESS_BAR_LEN 2空中传输顺序为整数部分0–100在前、百分位0–99在后两个字节当整数部分为 100 时百分位必须为 0。esp_ble_ota_notify_progress_bar_raw(low_octet, high_octet)负责校验范围并同时更新本地值esp_ble_ota_progress_bar_local_get()可读取本地进度小端序下低 8 位为整数部分、高 8 位为百分位弱符号钩子weak hook服务对三个写入通道各暴露一个弱函数esp_ble_ota_recv_fw_data()、esp_ble_ota_recv_cmd_data()、esp_ble_ota_recv_customer_data()上层 profile 或应用只需用强符号覆盖同名函数即可在 ATT 载荷长度校验通过后接管固件包/命令/厂商数据的解析这正是传输层可复用的落地机制向后兼容别名esp_ble_ota_on_recv_fw、esp_ble_ota_on_command、esp_ble_ota_on_customer分别等价于上述三个钩子旧代码可无缝迁移新代码建议使用新名字生命周期esp_ble_ota_svc_init()注册服务、esp_ble_ota_svc_deinit()移除服务发送通道esp_ble_ota_notify_recv_fw_raw()、esp_ble_ota_notify_command_raw()、esp_ble_ota_notify_customer_raw()分别向三个通道发送 ACK/通知载荷。需要特别区分的是本服务不是ble_otaprofile 组件。头文件明确提示不要与ble_otaprofile 中的esp_ble_ota_init()混淆——本服务只对应esp_ble_ota_svc_init()。当与ble_ota_rawprofile 配合使用时命令与固件载荷的解析由 profile 层完成见 ble_ota_svc.rst。完整的端到端示例位于 examples/bluetooth/ble_profiles/ble_ota。八、menuconfig 配置与协议栈适配所有服务都是可裁剪的。组件根 Kconfig 定义了菜单BLE Standard Services通过orsource引入各服务的Kconfig.inmenu BLE Standard Services orsource ./ans/Kconfig.in orsource ./bas/Kconfig.in orsource ./bcs/Kconfig.in orsource ./cts/Kconfig.in orsource ./dis/Kconfig.in orsource ./hrs/Kconfig.in orsource ./hts/Kconfig.in orsource ./ias/Kconfig.in orsource ./midi/Kconfig.in orsource ./ots/Kconfig.in orsource ./ota/Kconfig.in orsource ./tps/Kconfig.in orsource ./uds/Kconfig.in orsource ./wss/Kconfig.in endmenu工程中只需idf.py menuconfig勾选需要的服务如 IAS 对应CONFIG_BLE_IAS未启用的服务不会被编译进固件从而节省 Flash/RAM 资源。这种按需裁剪与ble_conn_mgr的连接管理配合可以组合出不同的设备形态。协议栈方面示例工程均携带sdkconfig.ci.nimble如 ble_bas/sdkconfig.ci.nimble说明这些服务示例在 NimBLEesp_nimble协议栈下经过 CI 验证部分仓库示例也保留了 Bluedroid 配置如蓝牙其他模块中的*.bluedroid文件实际使用时应按工程选定的协议栈配置CONFIG_BT_NIMBLE或CONFIG_BT_BLUEDROID。九、从文档到工程可继续深入的位置如果你想进一步深入以下是本仓库中与本文强相关、可直接查阅的资料组件根文档components/bluetooth/ble_services/README.md——依赖关系、添加依赖命令、示例清单与组件管理器 QA组件配置components/bluetooth/ble_services/Kconfig——服务裁剪菜单服务 API 头文件esp_bas.h、esp_ias.h、esp_ble_ota_svc.h 及ans/、cts/、dis/、hrs/、hts/、ots/、tps/、uds/、wss/、bcs/、midi/下对应头文件运行示例examples/bluetooth/ble_services每个子目录含app_main.c与可配置项、examples/bluetooth/ble_profiles/ble_otaOTA 服务端到端示例文档子页ble_ias.rst含 IAS 完整接入步骤、ble_ota_svc.rstOTA 服务定义、以及 docs/en/bluetooth 下其余ble_*.rst服务子页依赖组件components/bluetooth/ble_conn_mgr——连接管理器所有服务注册的前提。十、总结ble_services组件把 BLE GATT 开发中最高频的 14 个服务13 个 SIG 标准服务 ESP BLE OTA 传输服务封装为一个esp_ble_xxx_init()即可注册、一组get/set/notify函数即可读写的简洁接口并深度集成于ble_conn_mgr的初始化流程之中。从 BAS 的 9 个特征与成对 API、IAS 的三档 Alert Level 与回调注册顺序到 OTA 服务的四通道设计与弱符号钩子机制本文已覆盖文档全部核心内容并结合仓库源码补充了 UUID 表、API 语义与示例命令。开发者可据此按需勾选服务、参照示例工程快速搭建心率计、体温计、体重秤、防丢器、BLE 升级等产品原型。【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 esp-iot-solution BLE Services 组件实战指南：在 esp_ble_conn_mgr 上接入 ANS/BAS/HRS/OTA 等标准 GATT 服务
esp-iot-solution BLE Services 组件实战指南在 esp_ble_conn_mgr 上接入 ANS/BAS/HRS/OTA 等标准 GATT 服务【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution本指南基于 esp-iot-solution 仓库中的 BLE Services 文档 及 组件源码 展开系统介绍如何在 ESP32 系列芯片上以统一、简化的 API 接入蓝牙标准 GATT 服务ANS、BAS、BCS、CTS、DIS、HRS、HTS、IAS、MIDI、OTA、OTS、TPS、UDS、WSS。读完本文你将掌握ble_services组件的安装方式、与ble_conn_mgr的集成初始化流程、各服务的能力与 UUID 定义并能参照示例快速实现电池电量上报、心率采集、设备信息广播、BLE 空中升级等真实场景。一、BLE Services 组件是什么在 BLE GATT 开发中逐个定义服务、特征Characteristic、描述符并手动处理读写回调往往繁琐且易错。esp-iot-solution 提供的ble_services组件 在 GATT Server 之上封装了一层简化 API 接口把蓝牙 SIG 定义的常用标准服务以及 ESP 自定义的 OTA 服务封装成可直接调用的函数开发者只需注册服务 读写特征值即可完成大部分业务。组件 READMEcomponents/bluetooth/ble_services/README.md明确指出其职责Theble_servicescomponent provides a simplified API interface for accessing commonly used standard and custom BLE services functionality on a GATT server.组件共包含 14 个服务每个服务在components/bluetooth/ble_services/下拥有独立子目录ans/、bas/、bcs/、cts/、dis/、hrs/、hts/、ias/、midi/、ota/、ots/、tps/、uds/、wss/目录内统一组织为include/esp_xxx.h服务公共 API 头文件UUID 宏、数据结构、读写/订阅函数、回调注册函数src/esp_xxx.c基于esp_ble_conn_mgr的 GATT 注册与数据收发实现Kconfig.in该服务的 menuconfig 开关。从源码结构看这是一个连接管理 服务注册解耦的架构连接、广播、事件分发由ble_conn_mgr统一负责ble_services只负责把各服务注册进 GATT 表二者通过esp_ble_conn_add_svc()等接口衔接。组件 README 也特别提示本组件依赖ble_conn_mgr才能工作。二、服务全景14 个服务的用途与 UUID 一览以下汇总了各服务在 BLE 生态中的典型用途、服务 UUID 及本文档/示例对应位置。其中服务 UUID 均可在各服务头文件中的BLE_XXX_UUID16宏确认如 esp_ias.h 中的BLE_IAS_UUID16 0x1802、esp_bas.h 中的BLE_BAS_UUID16 0x180F。服务全称服务 UUID用途概述示例ANSAlert Notification Service0x1811暴露设备告警信息ble_ansBASBattery Service0x180F暴露电池电量及充放电信息ble_basBCSBody Composition Service0x181B体成分分析仪数据健身/医疗ble_bcsCTSCurrent Time Service0x1805日期与时间信息暴露/同步ble_ctsDISDevice Information Service0x180A制造商/厂商信息ble_disHRSHeart Rate Service0x180D心率传感器数据健身场景ble_hrsHTSHealth Thermometer Service0x1809体温计温度数据医疗场景ble_htsIASImmediate Alert Service0x1802远程触发立即告警如防丢见 ble_ias.rstMIDIMIDI Service0x1804MIDI 音乐数据传输组件内midi/OTAESP BLE OTA Service0x8018ESP 自定义的 BLE 升级传输服务ble_otaOTSObject Transfer Service0x1825基于 L2CAP CoC 的大数据对象传输ble_otsTPSTX Power Service0x1804连接中当前发射功率ble_tpsUDSUser Data Service0x181C用户资料远程访问/同步运动、家居、医疗ble_udsWSSWeight Scale Service0x181D体重秤体重及相关数据ble_wss说明ble_services.rst文档目录页docs/en/bluetooth/ble_services.rst收录了除 MIDI 外的 13 个服务子页而组件源码中 MIDI 同样被实现见 Kconfig 中的midi/Kconfig.in故本文按组件实际能力介绍 14 个服务。各子页文档如 ble_ans.rst、ble_hrs.rst对服务的语义做了精确定义例如ANS暴露设备中发生的告警信息包括①告警类型②附加文本信息如来电号码、发送者 ID③新告警计数④未读告警计数。BAS在电池与设备电气连接的语境下暴露 Battery Level 及其他电池信息。HRS暴露面向健身应用的心率及其他心率传感器数据。HTS暴露面向医疗应用的温度计温度及相关数据。DIS暴露设备的制造商和/或厂商信息。CTS定义蓝牙设备如何向其他蓝牙设备暴露日期和时间信息。OTS提供批量数据传输的管理与控制能力数据本体经由独立的 L2CAP 面向连接通道CoC传输。TPS暴露设备处于连接状态时当前的发射功率水平。UDS在运动健身、家居或医疗环境中暴露用户相关数据支持客户端远程访问/更新以及服务端与客户端之间的数据同步。WSS暴露来自体重秤的体重及相关数据面向消费医疗和运动健身应用。三、快速上手安装组件与创建示例工程ble_services已发布到 ESP 组件仓库Component Registry推荐使用IDF 组件管理器idf-component-manager引入CMake 阶段会自动下载。1. 添加依赖到你的工程idf.py add-dependency espressif/ble_services*2. 从示例模板直接创建工程以 Device Information Service 为例idf.py create-project-from-example espressif/ble_services*:ble_dis示例会被下载到当前目录随后即可按常规流程idf.py build、idf.py flash monitor。仓库中也内置了可直接浏览的完整示例源码位于 examples/bluetooth/ble_services包括ble_ans、ble_bas、ble_bcs、ble_cts、ble_dis、ble_hrs、ble_hts、ble_ots、ble_tps、ble_uds、ble_wss等目录每个示例都包含main/目录app_main.c 服务相关源码、sdkconfig.defaults与sdkconfig.ci.nimble表明示例在 CI 中基于 NimBLE 协议栈验证。常见问题组件 README 的 QA若执行create-project-from-example时报错CMakeLists.txt not found in project directory /home/username说明使用的组件管理器版本过旧请在 ESP-IDF 环境下执行pip install -U idf-component-manager更新后再试。四、统一初始化流程服务如何挂载到 ble_conn_mgrble_services的所有服务都不是独立运行的而是注册到连接管理器之上。以 ble_bas 示例的 app_main.c 为例标准流程如下#include esp_ble_conn_mgr.h #include esp_bas.h void app_main(void) { esp_ble_conn_config_t config { .device_name CONFIG_EXAMPLE_BLE_ADV_NAME, // 广播名称menuconfig 可配 .broadcast_data CONFIG_EXAMPLE_BLE_SUB_ADV // 广播数据 }; // 1. 初始化 NVS首次失败时擦除重试 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); // 2. 创建默认事件循环注册连接事件处理器可选用于打印连接/断开日志 esp_event_loop_create_default(); esp_event_handler_register(BLE_CONN_MGR_EVENTS, ESP_EVENT_ANY_ID, app_ble_conn_event_handler, NULL); // 3. 注册服务组件前先初始化连接管理器 esp_ble_conn_init(config); // 4. 注册具体的 GATT 服务此处为 Battery Service esp_ble_bas_init(); // 5. 启动广播与连接 if (esp_ble_conn_start() ! ESP_OK) { esp_ble_conn_stop(); esp_ble_conn_deinit(); esp_event_handler_unregister(BLE_CONN_MGR_EVENTS, ESP_EVENT_ANY_ID, app_ble_conn_event_handler); } }这套流程在所有服务示例中高度一致对比 ble_ans 示例 可见仅把esp_ble_bas_init()换成esp_ble_ans_init()并引入对应头文件esp_ans.h可归纳为五个固定步骤NVS 初始化BLE 地址等参数需要持久化存储事件循环与连接事件注册监听BLE_CONN_MGR_EVENTSESP_BLE_CONN_EVENT_CONNECTED/ESP_BLE_CONN_EVENT_DISCONNECTEDesp_ble_conn_init(config)用设备名、广播数据等配置初始化连接管理器esp_ble_xxx_init()在 GATT Server 上注册对应服务必须在esp_ble_conn_init()之后、esp_ble_conn_start()之前调用esp_ble_conn_start()开始广播并等待连接失败时需依次stop、deinit、注销事件处理器完成回滚。五、深度解析一Battery ServiceBASBAS 是 BLE 设备最常用的服务之一。从 esp_bas.h 可以看出该组件实现的 BAS 远不止基础的电量等级还覆盖了 Battery Service v1.1 中新增的丰富特征特征名称特征 UUID说明Battery Level0x2A19电池电量百分比0–100Battery Level Status0x2BED电量等级状态功率状态、充电状态、充电类型、充电故障原因、附加状态等Estimated Service Date0x2BEF预计需要服务/更换电池的日期24bitBattery Critical Status0x2BE9关键电源状态、是否需立即维护Battery Energy Status0x2BF0可用电池容量、可用能量、充电速率、电压等Battery Time Status0x2BEE放电/待机时间、充电时间24bitBattery Health Status0x2BEA电池健康摘要、当前温度、循环次数、深度放电次数Battery Health Information0x2BEB设计循环寿命、设计工作温度范围Battery Information0x2BEC化学体系、设计容量、制造日期、失效日期、标称电压、可否充电/更换对应地头文件提供成对 APIesp_ble_bas_get_battery_level()/esp_ble_bas_set_battery_level()、esp_ble_bas_get_level_status()/esp_ble_bas_set_level_status()、esp_ble_bas_get_estimated_date()/esp_ble_bas_set_estimated_date()、esp_ble_bas_get_critical_status()/esp_ble_bas_set_critical_status()、esp_ble_bas_get_energy_status()/esp_ble_bas_set_energy_status()、esp_ble_bas_get_time_status()/esp_ble_bas_set_time_status()、esp_ble_bas_get_health_status()/esp_ble_bas_set_health_status()、esp_ble_bas_get_health_info()/esp_ble_bas_set_health_info()、esp_ble_bas_get_battery_info()/esp_ble_bas_set_battery_info()。头文件同时定义了丰富的位掩码与取值宏例如功率状态中WIRED_EXTERNAL_POWER_SOURCE_*未连接/已连接/未知/RFU、电池充电状态未知/充电中/放电激活/放电非激活、充电类型恒流/恒压/涓流/浮充、充电故障原因无故障/电池故障/外部电源故障/其他等便于开发者用可读的宏而非裸数字填装特征值。示例工程 app_bas.c 将这些 API 封装成 ESP Console 命令bas便于在串口终端上联调bas -t 00~01 -c 01~09-t操作类型0为 Set向特征写值1为 Get读取特征-c特征编号01Battery Level、02Battery Level Status、03Estimated Service Date、04Battery Critical Status、05Battery Energy Status、06Battery Time Status、07Battery Health Status、08Battery Health Information、09Battery Information。示例内部用esp_random() % N生成随机测试值如电量取0~100、电压取0~220可以快速验证 GATT 读写链路是否打通。六、深度解析二Immediate Alert ServiceIASIAS 是防丢器、寻物标签类产品的经典服务。其语义很简单暴露一个Alert Level特征UUID 0x2A06服务 UUID 0x1802对端写入后设备立即发出声音或震动提示。ble_ias.rst 与 esp_ias.h 共同给出了完整接入说明Alert Level 是一个单字节值仅三档合法取值宏定义数值含义ESP_BLE_IAS_ALERT_LEVEL_NO_ALERT0x00无告警ESP_BLE_IAS_ALERT_LEVEL_MILD_ALERT0x01轻度告警ESP_BLE_IAS_ALERT_LEVEL_HIGH_ALERT0x02高度告警接入步骤文档原文要点在 menuconfig 中使能CONFIG_BLE_IAS用esp_ble_conn_init()初始化 BLE 连接管理器如工程需要还需创建默认事件循环连接管理器初始化完成后、esp_ble_conn_start()之前调用esp_ble_ias_init()把 IAS 注册到 GATT Server在esp_ble_ias_init()之后再调用esp_ble_ias_register_alert_cb()注册告警回调——先保证服务已存在再挂接处理有效 Alert Level 写入的处理器。对应 API 及语义见 esp_ias.hesp_ble_ias_init()注册 IAS 服务返回ESP_OK或来自esp_ble_conn_add_svc()的错误码esp_ble_ias_register_alert_cb(esp_ble_ias_alert_cb_t cb, void *priv)注册/注销传NULLAlert Level 写入回调回调携带对端写入的alert_level与用户私有指针privesp_ble_ias_get_alert_level(uint8_t *level)读取客户端最近一次写入的 Alert Level默认ESP_BLE_IAS_ALERT_LEVEL_NO_ALERTlevel为NULL时返回ESP_ERR_INVALID_ARG。IAS 没有独立的示例工程文档建议参照其他 BLE 服务示例 的初始化模式来接入。七、深度解析三ESP BLE OTA 传输服务ble_services中的 OTA 服务esp_ble_ota_svc.h是一个传输层transport-levelGATT 服务定义在0x8018只负责固件数据的收发通道可被不同的 OTA profile 逻辑复用。文档 ble_ota_svc.rst 给出了四个特征特征UUID方向与用途RECV_FW0x8020固件数据写入Write w/o rsp 固件 ACK 通知NotifyPROGRESS_BAR0x8021升级进度值Read NotifyCOMMAND0x8022OTA 命令写入Write w/o rsp 命令 ACK 通知NotifyCUSTOMER0x8023厂商自定义数据通道Write w/o rsp Notify源码中几个关键设计点载荷上限BLE_OTA_ATT_PAYLOAD_MAX_LEN 512单次 ATT 写入/通知最大 512 字节超限返回ESP_ERR_INVALID_SIZE进度条编码BLE_OTA_PROGRESS_BAR_LEN 2空中传输顺序为整数部分0–100在前、百分位0–99在后两个字节当整数部分为 100 时百分位必须为 0。esp_ble_ota_notify_progress_bar_raw(low_octet, high_octet)负责校验范围并同时更新本地值esp_ble_ota_progress_bar_local_get()可读取本地进度小端序下低 8 位为整数部分、高 8 位为百分位弱符号钩子weak hook服务对三个写入通道各暴露一个弱函数esp_ble_ota_recv_fw_data()、esp_ble_ota_recv_cmd_data()、esp_ble_ota_recv_customer_data()上层 profile 或应用只需用强符号覆盖同名函数即可在 ATT 载荷长度校验通过后接管固件包/命令/厂商数据的解析这正是传输层可复用的落地机制向后兼容别名esp_ble_ota_on_recv_fw、esp_ble_ota_on_command、esp_ble_ota_on_customer分别等价于上述三个钩子旧代码可无缝迁移新代码建议使用新名字生命周期esp_ble_ota_svc_init()注册服务、esp_ble_ota_svc_deinit()移除服务发送通道esp_ble_ota_notify_recv_fw_raw()、esp_ble_ota_notify_command_raw()、esp_ble_ota_notify_customer_raw()分别向三个通道发送 ACK/通知载荷。需要特别区分的是本服务不是ble_otaprofile 组件。头文件明确提示不要与ble_otaprofile 中的esp_ble_ota_init()混淆——本服务只对应esp_ble_ota_svc_init()。当与ble_ota_rawprofile 配合使用时命令与固件载荷的解析由 profile 层完成见 ble_ota_svc.rst。完整的端到端示例位于 examples/bluetooth/ble_profiles/ble_ota。八、menuconfig 配置与协议栈适配所有服务都是可裁剪的。组件根 Kconfig 定义了菜单BLE Standard Services通过orsource引入各服务的Kconfig.inmenu BLE Standard Services orsource ./ans/Kconfig.in orsource ./bas/Kconfig.in orsource ./bcs/Kconfig.in orsource ./cts/Kconfig.in orsource ./dis/Kconfig.in orsource ./hrs/Kconfig.in orsource ./hts/Kconfig.in orsource ./ias/Kconfig.in orsource ./midi/Kconfig.in orsource ./ots/Kconfig.in orsource ./ota/Kconfig.in orsource ./tps/Kconfig.in orsource ./uds/Kconfig.in orsource ./wss/Kconfig.in endmenu工程中只需idf.py menuconfig勾选需要的服务如 IAS 对应CONFIG_BLE_IAS未启用的服务不会被编译进固件从而节省 Flash/RAM 资源。这种按需裁剪与ble_conn_mgr的连接管理配合可以组合出不同的设备形态。协议栈方面示例工程均携带sdkconfig.ci.nimble如 ble_bas/sdkconfig.ci.nimble说明这些服务示例在 NimBLEesp_nimble协议栈下经过 CI 验证部分仓库示例也保留了 Bluedroid 配置如蓝牙其他模块中的*.bluedroid文件实际使用时应按工程选定的协议栈配置CONFIG_BT_NIMBLE或CONFIG_BT_BLUEDROID。九、从文档到工程可继续深入的位置如果你想进一步深入以下是本仓库中与本文强相关、可直接查阅的资料组件根文档components/bluetooth/ble_services/README.md——依赖关系、添加依赖命令、示例清单与组件管理器 QA组件配置components/bluetooth/ble_services/Kconfig——服务裁剪菜单服务 API 头文件esp_bas.h、esp_ias.h、esp_ble_ota_svc.h 及ans/、cts/、dis/、hrs/、hts/、ots/、tps/、uds/、wss/、bcs/、midi/下对应头文件运行示例examples/bluetooth/ble_services每个子目录含app_main.c与可配置项、examples/bluetooth/ble_profiles/ble_otaOTA 服务端到端示例文档子页ble_ias.rst含 IAS 完整接入步骤、ble_ota_svc.rstOTA 服务定义、以及 docs/en/bluetooth 下其余ble_*.rst服务子页依赖组件components/bluetooth/ble_conn_mgr——连接管理器所有服务注册的前提。十、总结ble_services组件把 BLE GATT 开发中最高频的 14 个服务13 个 SIG 标准服务 ESP BLE OTA 传输服务封装为一个esp_ble_xxx_init()即可注册、一组get/set/notify函数即可读写的简洁接口并深度集成于ble_conn_mgr的初始化流程之中。从 BAS 的 9 个特征与成对 API、IAS 的三档 Alert Level 与回调注册顺序到 OTA 服务的四通道设计与弱符号钩子机制本文已覆盖文档全部核心内容并结合仓库源码补充了 UUID 表、API 语义与示例命令。开发者可据此按需勾选服务、参照示例工程快速搭建心率计、体温计、体重秤、防丢器、BLE 升级等产品原型。【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考