esp-iot-solution 蓝牙体成分服务BLE BCS开发指南从 GATT 特性设计到示例集成【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution导读本文基于 Espressif esp-iot-solution 仓库中的 BLE 标准服务组件系统讲解Body Composition ServiceBCS体成分服务的完整实现从 BCS 在 GATT 协议中的服务/特征定义、Feature 位掩码与 Measurement 数据标志位的设计到esp_ble_bcs_init()与esp_ble_bcs_set_measurement()两个核心 API 的调用流程再到基于ble_conn_mgr的可运行示例。读完本文你将掌握如何在 ESP32 系列芯片上快速启用一个符合 BLE 标准的体成分服务体脂秤、健康秤、运动健身设备并理解其底层数据打包与指示Indication发送机制。BCS 服务是什么Body Composition ServiceBCS由蓝牙 SIG 定义用于将体成分分析仪Server测量到的身体成分数据暴露给客户端Client面向消费级医疗健康以及运动/健身类应用场景。它基于 GATT 服务器模型工作设备上电后启动广播等待手机 App 等 GATT 客户端连接随后将测量数据以 Indication指示方式主动推送给客户端。在 esp-iot-solution 中该服务由 components/bluetooth/ble_services/bcs 组件实现并配套提供了完整可运行的示例工程 examples/bluetooth/ble_services/ble_bcs。BCS 服务与特征定义根据蓝牙规范BCS 使用 16 位服务 UUID其核心定义位于头文件 components/bluetooth/ble_services/bcs/include/esp_bcs.h名称UUID说明Body Composition Service0x181BBCS 服务 UUIDBody Composition Feature 特征0x2A9B描述设备支持的体成分测量项可读可选指示Body Composition Measurement 特征0x2A9C承载实际测量数据通过 Indication 发送同时头文件定义了单条 GATT 属性值的最大长度BLE_BCS_MAX_VAL_LEN 100字节esp_bcs.h用于限定内部打包缓冲区的上限。从源码结构看该服务的特征注册表定义在 esp_bcs.c 中static const esp_ble_conn_character_t nu_lookup_table[] { { feature, BLE_CONN_UUID_TYPE_16, BLE_CONN_GATT_CHR_READ #ifdef CONFIG_BLE_BCS_FEATURE_INDICATE_ENABLE | BLE_CONN_GATT_CHR_INDICATE #endif , { BLE_BCS_CHR_UUID16_FEATURE }, bcs_feature_cb }, { measurement, BLE_CONN_UUID_TYPE_16, BLE_CONN_GATT_CHR_INDICATE , { BLE_BCS_CHR_UUID16_MEASUREMENT }, NULL }, };即该服务包含两个特征feature0x2A9B具备Read权限当使能CONFIG_BLE_BCS_FEATURE_INDICATE_ENABLE时额外具备Indicate权限其读取回调bcs_feature_cb会把当前设备的体成分 Feature 位掩码返回给客户端。measurement0x2A9C仅支持Indicate用于向已连接客户端推送测量数据。服务本身通过esp_ble_conn_svc_t结构注册到连接管理器static const esp_ble_conn_svc_t svc { .type BLE_CONN_UUID_TYPE_16, .uuid { .uuid16 BLE_BCS_UUID16 }, .nu_lookup_count sizeof(nu_lookup_table) / sizeof(nu_lookup_table[0]), .nu_lookup (esp_ble_conn_character_t *)nu_lookup_table };Feature 位掩码声明设备支持哪些测量项Feature 特征以 32 位位掩码形式向客户端声明设备支持的体成分测量项。完整定义见 esp_bcs.h位宏含义bit0BLE_BCS_FEAT_TIME_STAMP支持时间戳bit1BLE_BCS_FEAT_MULTI_USER支持多用户 IDbit2BLE_BCS_FEAT_BASAL_METABOLISM支持基础代谢bit3BLE_BCS_FEAT_MUSCLE_PERCENTAGE支持肌肉百分比bit4BLE_BCS_FEAT_MUSCLE_MASS支持肌肉量bit5BLE_BCS_FEAT_FAT_FREE_MASS支持去脂体重bit6BLE_BCS_FEAT_SOFT_LEAN_MASS支持软瘦体重bit7BLE_BCS_FEAT_BODY_WATER_MASS支持身体水分量bit8BLE_BCS_FEAT_IMPEDENCE支持阻抗bit9BLE_BCS_FEAT_WEIGHT支持体重bit10BLE_BCS_FEAT_HEIGHT支持身高bit11–bit14BLE_BCS_FEAT_MASS_MEASUREMENT_RESOLUTION体重分辨率000 未定义001 0.5kg/1lb010 0.2kg/0.5lb011 0.1kg/0.2lb100 0.05kg/0.1lb101 0.02kg/0.05lb110 0.01kg/0.02lb111 0.005kg/0.01lbbit15–bit17BLE_BCS_FEAT_HEIGHT_RESOLUTION身高分辨率000 未定义001 0.01m/1ft010 0.005m/0.5ft011 0.001m/0.1ft在组件默认实现中body_composition_feature静态变量会将上述所有位时间戳、多用户、基础代谢……直至身高分辨率一并置位esp_bcs.c即默认宣称设备支持全部体成分测量能力。客户端读取 feature 特征时bcs_feature_cb会动态分配 4 字节缓冲区并拷贝当前位掩码返回esp_bcs.c。Measurement 标志位与数据结构测量数据的携带载体是esp_bcs_val_t结构体同样定义在 esp_bcs.h并通过__attribute__((packed))保证内存布局与 BLE 线上传输格式一致typedef struct { uint32_t bcs_flag; /*! Body Composition flag field */ struct { uint16_t year; /*! 公历年份有效范围 1582 至 9999 */ uint8_t month; /*! 1一月到 12十二月 */ uint8_t day; /*! 1 到 31 */ uint8_t hours; /*! 0 到 23 */ uint8_t minutes; /*! 0 到 59 */ uint8_t seconds; /*! 0 到 59 */ } __attribute__((packed)) timestamp; /*! 日期和时间 */ uint8_t user_id; /*! 用户 ID 字段 */ uint16_t basal_metabolism; /*! 基础代谢字段 */ uint16_t muscle_percentage; /*! 肌肉百分比字段 */ uint16_t muscle_mass; /*! 肌肉量字段 */ uint16_t fat_free_mass; /*! 去脂体重字段 */ uint16_t soft_lean_mass; /*! 软瘦体重字段 */ uint16_t body_water_mass; /*! 身体水分量字段 */ uint8_t impedance; /*! 阻抗字段 */ uint16_t weight; /*! 体重字段 */ uint16_t height; /*! 身高字段 */ } __attribute__((packed)) esp_bcs_val_t;bcs_flag是 32 位的 Measurement Flags 位掩码决定本次测量数据中实际携带了哪些字段。其位定义esp_bcs.h与 Feature 位掩码一一对应额外包含bit12BLE_BCS_FLAG_MULTIPLE_PACKET多包标志用于长数据分帧传输。其余 bit0–bit11 分别对应测量单位、时间戳、多用户、基础代谢、肌肉百分比、肌肉量、去脂体重、软瘦体重、身体水分量、阻抗、体重、身高。需要特别留意的是单位语义当BLE_BCS_FLAG_MEASUREMENT_UNITSbit0置位时表示英制单位lb/英尺清零时表示公制单位kg/米客户端应依据该位完成单位换算。核心 API 与实现原理BCS 组件对外只暴露两个 APIesp_bcs.h1. esp_ble_bcs_init()esp_err_t esp_ble_bcs_init(void);初始化体成分服务。实现中直接调用连接管理器注册服务接口esp_ble_conn_add_svc(svc)esp_bcs.c其中esp_ble_conn_add_svc声明于 components/bluetooth/ble_conn_mgr/include/esp_ble_conn_mgr.h。返回值成功返回ESP_OK初始化错误返回ESP_ERR_INVALID_ARG其他错误返回ESP_FAIL。2. esp_ble_bcs_set_measurement()esp_err_t esp_ble_bcs_set_measurement(esp_bcs_val_t *in_val, bool need_send);设置体成分测量值。参数in_val为待上报的测量数据指针need_send为true时将数据以 Indication 发送给远端客户端。其内部逻辑分为两段esp_bcs.c同步 Feature 位掩码根据in_val-bcs_flag中置位的标志将对应的BLE_BCS_FEAT_*位写入body_composition_feature确保 feature 特征返回值与本次测量数据声明的字段一致。打包并发送可选在CONFIG_BLE_BCS_FEATURE_INDICATE_ENABLE使能且need_send true时调用内部函数build_bcs_ind_buf()将结构体按标志位逐个字段拼装成 BLE 线上字节流随后构造esp_ble_conn_data_t并通过esp_ble_conn_write()声明于 esp_ble_conn_mgr.h发送 Indication。数据打包细节build_bcs_ind_buf()esp_bcs.c严格遵循 BCS 规范的可变长度打包格式首先写入 4 字节bcs_flag随后按照bcs_flag中置位的标志依次追加时间戳7 字节、用户 ID1 字节、基础代谢2 字节、肌肉百分比2 字节、肌肉量2 字节、去脂体重2 字节、软瘦体重2 字节、身体水分量2 字节、阻抗1 字节、体重2 字节、身高2 字节最终得到的数据长度写入out_buf-len。发送时构造的esp_ble_conn_data_t使用 16 位 UUID 类型指向BLE_BCS_CHR_UUID16_MEASUREMENT0x2A9C从而精确匹配 measurement 特征句柄esp_bcs.c。组件使能配置KconfigBCS 组件通过 Kconfig 开关控制配置入口见 components/bluetooth/ble_services/bcs/Kconfig.inmenuconfig BLE_BCS bool GATT Body Composition Service if BLE_BCS config BLE_BCS_FEATURE_INDICATE_ENABLE bool Body Composition Feature Indication default y help Set y to support Indication or n to disable it. endif # BLE_BCSBLE_BCS总开关关闭后整个服务不会被注册。BLE_BCS_FEATURE_INDICATE_ENABLE默认使能y。开启后 feature 特征额外支持 Indication且esp_ble_bcs_set_measurement()的need_send参数才真正生效关闭后测量数据只更新本地状态、不主动上报。示例工程实践官方示例位于 examples/bluetooth/ble_services/ble_bcs支持 ESP32、ESP32-C3、ESP32-C2、ESP32-S3、ESP32-H2 等目标芯片。环境与编译先设置目标芯片再进入配置菜单idf.py set-target chip_name idf.py menuconfig在Example Configuration菜单中可修改广播名Advertisement name默认BLE_BCS在BLE Standard Services菜单中可通过GATT Body Composition Service选择可选功能。随后编译烧录并监视串口idf.py -p PORT flash monitor退出串口监视器按Ctrl-]。示例的默认配置sdkconfig.defaults已预设关键项CONFIG_BT_ENABLEDy CONFIG_BT_NIMBLE_ENABLEDy CONFIG_BLE_CONN_MGR_ROLE_PERIPHERALy CONFIG_BLE_BCSy即启用蓝牙、选择 NimBLE 协议栈、让 ble_conn_mgr 工作在外设Peripheral角色并打开 BCS 组件。主程序调用链示例主程序 app_main.c 展示了标准接入流程初始化 NVSnvs_flash_init()失败时擦除重试创建默认事件循环并向BLE_CONN_MGR_EVENTS注册事件回调通过esp_ble_conn_init(config)初始化连接管理器声明于 esp_ble_conn_mgr.h其中config.device_name取自CONFIG_EXAMPLE_BLE_ADV_NAME调用esp_ble_bcs_init()注册 BCS 服务调用esp_ble_conn_start()启动广播失败时依次执行esp_ble_conn_stop()、esp_ble_conn_deinit()并注销事件回调。在连接事件回调中示例构造了一份完整的esp_bcs_val_t数据含 2024-11-05 15:15:06 时间戳、用户 ID1、基础代谢、肌肉百分比、肌肉量、去脂体重、软瘦体重、身体水分量、阻抗、体重 0x42、身高 0x33并在ESP_BLE_CONN_EVENT_CONNECTED事件里调用esp_ble_bcs_set_measurement(bcs_val, true);即客户端连接成功的瞬间设备立即将体成分测量数据以 Indication 推送给对方。连接断开事件ESP_BLE_CONN_EVENT_DISCONNECTED则用于日志打印与后续重连逻辑。运行输出示例连接并读取特征后串口典型输出如下I (420) blecm_nimble: BLE Host Task Started I (420) blecm_nimble: No characteristic(0x2a00) found I (430) NimBLE: GAP procedure initiated: stop advertising. I (440) NimBLE: GAP procedure initiated: advertise; I (440) NimBLE: disc_mode2 I (450) NimBLE: adv_channel_map0 own_addr_type0 adv_filter_policy0 adv_itvl_min256 adv_itvl_max256可以看到设备以 NimBLE 协议栈启动并进入广播状态。测试时使用任意 BLE 扫描 App如 nRF Connect即可发现名为BLE_BCS的设备连接后可读取 feature 特征、接收 measurement 特征的 Indication 数据。设计要点与注意事项字段按需声明bcs_flag是数据可扩展性的关键。并非每次测量都必须携带全部字段未置位的标志对应字段不会被打包进数据帧可显著节省广播/连接带宽。Feature 与 Measurement 联动esp_ble_bcs_set_measurement()会根据每次数据的bcs_flag动态更新 Feature 位掩码客户端读取到的能力声明始终与最近一次测量数据的实际内容一致。多用户与时间戳BLE_BCS_FEAT_MULTI_USER与BLE_BCS_FEAT_TIME_STAMP使设备可区分多个家庭成员并记录测量时刻这是体脂秤等消费健康产品的常见需求。单位一致性置位BLE_BCS_FLAG_MEASUREMENT_UNITS表示数据为英制单位应用层需按规范换算避免体重/身高数据被错误解读。依赖关系BCS 组件强依赖ble_conn_mgrBLE 连接管理组件完成 GATT 注册与数据下发实际开发中应保证CONFIG_BLE_CONN_MGR_ROLE_PERIPHERALy使设备工作在外设角色。延伸阅读BCS 组件头文件components/bluetooth/ble_services/bcs/include/esp_bcs.hBCS 组件实现components/bluetooth/ble_services/bcs/src/esp_bcs.c连接管理器 APIcomponents/bluetooth/ble_conn_mgr/include/esp_ble_conn_mgr.h可运行示例examples/bluetooth/ble_services/ble_bcs仓库中其他 BLE 标准服务体重秤 WSS、心率 HRS、体温 HTS 等的文档索引见 docs/en/bluetooth/ble_services.rstBCS 专页见 docs/en/bluetooth/ble_bcs.rst【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考