ESP IoT Solution BLE TX Power Serviceesp_tps组件使用指南从服务注册到发射功率上报的完整实践【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution本文面向在 ESP32 系列芯片上基于 esp-iot-solution 构建 BLE GATT 外设的开发者系统讲解 TX Power ServiceTPS服务 UUID 0x1804组件的设计原理、API 用法与完整示例实践。文章以仓库文档 docs/en/bluetooth/ble_tps.rst 为核心骨架结合 esp_tps 组件源码 与 ble_tps 示例工程 进行纵深展开。阅读本文后你将掌握如何在连接状态下向对端Client暴露本机当前发射功率TX Power Level单位 dBm并能独立完成从 NVS 初始化、BLE 连接管理初始化到服务注册、功率读取与事件回调的完整链路开发。一、服务概述连接期功率信息的标准化暴露TX Power Service 是 Bluetooth SIG 定义的 GATT 服务之一其作用正如 官方组件文档 所描述在设备处于连接状态时向对端暴露设备当前的发射功率水平The Tx power service expose the current transmit power level of a device when in a connection。该服务在 BLE 生态中的典型价值在于链路预算与路径损耗评估对端读取本机的发射功率后可结合自身收到的 RSSI 估算无线路径损耗从而辅助做距离估计或链路质量判断发射功率协商与节能配合 HCI/其他控制通道主机可依据上报的功率调整策略实现更精细的功耗与覆盖管理协议栈标准化无需自定义私有特征直接使用 SIG 标准 UUID任何标准 BLE 客户端手机 App、nRF Connect、LightBlue 等均可直接读取天然具备互操作性。1.1 标准 UUID 定义在 esp-iot-solution 中该服务与特征 UUID 定义于 esp_tps.h名称宏定义UUID类型TX Power Service UUIDBLE_TPS_UUID160x180416-bit Service UUIDTX Power Level 特征 UUIDBLE_TPS_CHR_UUID16_TX_POWER_LEVEL0x2A0716-bit Characteristic UUID其中0x2A07是 SIG 为 TX Power Level 特征分配的标准 16-bit UUID该特征为1 字节有符号整数int8_t单位 dBm且通常为只读Read。1.2 服务角色与能力边界需要注意该服务的定位边界避免误用仅连接时有效功率值通过 GATT 读取只在链路建立连接后由对端主动 Read 获得广播包中的功率不属于本服务范畴只读特征从 esp_tps.c 中的属性定义 可以看到特征属性仅为BLE_CONN_GATT_CHR_READ只读对端不可写单值上报服务一次只维护一个当前发射功率值反映的是“当前连接下的发射功率水平”。二、组件架构与 BLE Connection Manager 的协同TX Power Service 组件并非独立实现整个 GATT 协议栈而是构建在 esp-iot-solution 的BLE Connection Managerble_conn_mgr之上——这是理解本组件代码的关键前提。2.1 注册机制以表驱动方式挂接服务从 esp_tps.c 源码 可以清晰看到组件的实现骨架static const esp_ble_conn_character_t nu_lookup_table[] { {tx_power_level, BLE_CONN_UUID_TYPE_16, BLE_CONN_GATT_CHR_READ, { BLE_TPS_CHR_UUID16_TX_POWER_LEVEL }, esp_tps_tx_power_level_cb}, }; static const esp_ble_conn_svc_t svc { .type BLE_CONN_UUID_TYPE_16, .uuid { .uuid16 BLE_TPS_UUID16, }, .nu_lookup_count sizeof(nu_lookup_table) / sizeof(nu_lookup_table[0]), .nu_lookup (esp_ble_conn_character_t *)nu_lookup_table }; esp_err_t esp_ble_tps_init(void) { return esp_ble_conn_add_svc(svc); }其工作机制为组件定义一张“特征查找表”nu_lookup_table每个条目声明特征名称、UUID 类型16-bit、访问属性只读以及处理回调将服务UUID 0x1804与其特征表打包成esp_ble_conn_svc_t结构体esp_ble_tps_init()调用 esp_ble_conn_add_svc() 将该服务注册进 BLE 连接管理器管理的 GATT 数据库中。也就是说TPS 组件只负责服务内容的定义服务的生命周期、GATT 数据库管理与属性ATT协议交互全部由 ble_conn_mgr 统一承载。这种表驱动 回调的架构使得新增一个标准服务变得非常轻量。2.2 只读特征的读取回调当对端发起对该特征0x2A07的 Read 请求时ble_conn_mgr 会调用组件注册的回调 esp_tps_tx_power_level_cbstatic esp_err_t esp_tps_tx_power_level_cb(const uint8_t *inbuf, uint16_t inlen, uint8_t **outbuf, uint16_t *outlen, void *priv_data, uint8_t *att_status) { if (inbuf || !outbuf || !outlen) { *att_status ESP_IOT_ATT_INTERNAL_ERROR; return ESP_ERR_INVALID_ARG; } *outlen sizeof(s_ble_tps_tx_power_level); *outbuf (uint8_t *)calloc(1, *outlen); if (!(*outbuf)) { *att_status ESP_IOT_ATT_INSUF_RESOURCE; return ESP_ERR_NO_MEM; } memcpy(*outbuf, s_ble_tps_tx_power_level, *outlen); *att_status ESP_IOT_ATT_SUCCESS; return ESP_OK; }回调的健壮性处理值得借鉴参数校验对于只读特征inbuf必须为空、outbuf/outlen必须有效否则返回ESP_ERR_INVALID_ARG并置 ATT 状态为ESP_IOT_ATT_INTERNAL_ERROR0x81内存管理动态分配输出缓冲区并拷贝当前功率值分配失败时返回ESP_ERR_NO_MEM同时将 ATT 状态置为ESP_IOT_ATT_INSUF_RESOURCE0x11ATT 状态码成功时显式置为ESP_IOT_ATT_SUCCESS0x00。完整的 ATT 错误码集合定义于 esp_ble_conn_mgr.h涵盖ESP_IOT_ATT_INVALID_HANDLE、ESP_IOT_ATT_READ_NOT_PERMIT、ESP_IOT_ATT_INSUF_ENCRYPTION等标准错误码便于组件作者精确控制协议层响应。三、API 说明三个函数的完整契约esp_tps.h 对外仅暴露三个 API接口极简符合该服务小而专的定位。3.1 esp_ble_tps_init()esp_err_t esp_ble_tps_init(void);功能初始化 TX Power Service将服务及特征表注册到 BLE 连接管理器返回值ESP_OK成功ESP_ERR_INVALID_ARG初始化参数错误ESP_FAIL其他错误调用时机必须在esp_ble_conn_init()之后、服务启动之前调用详见第四节示例的调用顺序。3.2 esp_ble_tps_set_tx_power_level()esp_err_t esp_ble_tps_set_tx_power_level(int8_t tx_power_level);功能设置设备当前的发射功率水平int8_t单位 dBm参数tx_power_level——目标功率值如3表示 3 dBm返回值当前实现恒返回ESP_OK从 源码实现 可见其仅做静态变量赋值注意该接口设置的是服务对外上报的值并不直接改变射频发射功率底层射频功率由 BLE 控制器管理如 NimBLE 栈的 GAP 功率控制两者是独立的概念使用时需区分。3.3 esp_ble_tps_get_tx_power_level()int8_t esp_ble_tps_get_tx_power_level(void);功能读取当前服务维护的发射功率水平返回值当前功率值dBm由静态变量s_ble_tps_tx_power_level维护源码位置典型用途在连接事件回调中打印、上报或用于本地日志见示例代码。四、实战示例ble_tps 示例工程的完整剖析仓库提供了可直接编译运行的参考工程 examples/bluetooth/ble_services/ble_tps/它创建一个 GATT Server 并开始广播等待 GATT Client 连接后读取 TX Power Level 特征。4.1 支持目标与硬件要求根据 示例 README该示例支持以下目标芯片Supported TargetsESP32ESP32-C3ESP32-C2ESP32-S3ESP32-H2硬件上仅需一块上述任一 SoC 的开发板 USB 线供电与烧录对端使用任意 BLE 扫描/调试 App如 nRF Connect、LightBlue即可完成验证。4.2 配置项广播名称与后续广播数据示例在 menuconfig 中提供两个可配置项定义于 Kconfig.projbuild配置项类型默认值含义EXAMPLE_BLE_ADV_NAMEstringBLE_TPS广播包中的设备名称EXAMPLE_BLE_SUB_ADVstringSUB_ADV后续广播数据内容配置方法idf.py set-target chip_name # 先设置目标芯片如 esp32c3 idf.py menuconfig # 在 Example Configuration 菜单中修改广播名称4.3 工程依赖与 sdkconfig 默认值示例的 sdkconfig.defaults 明确了跑通该服务所需的关键配置# Override some defaults so BT stack is enabled # by default in this example CONFIG_BT_ENABLEDy CONFIG_BT_NIMBLE_ENABLEDy CONFIG_BLE_CONN_MGR_ROLE_PERIPHERALy CONFIG_BLE_TPSy逐项说明CONFIG_BT_ENABLEDy与CONFIG_BT_NIMBLE_ENABLEDy启用蓝牙控制器与 NimBLE 主机栈该示例基于 NimBLECONFIG_BLE_CONN_MGR_ROLE_PERIPHERALy将 ble_conn_mgr 配置为外设Peripheral角色本示例作为 GATT Server 广播并接受连接CONFIG_BLE_TPSy使能 TX Power Service 组件本身。对应地tps 组件目录下的 Kconfig.in 负责该组件的编译开关。构建与烧录idf.py -p PORT flash monitor退出串口监视器按Ctrl-]。4.4 主程序流程七步搭建 TPS 外设app_main.c 完整演示了 TPS 的接入流程可拆解为七个步骤第 1 步初始化 NVSret 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);BLE 协议栈运行需要 NVS 存储控制器信息如 MAC、校准数据等。此处针对 NVS 空间不足或版本更新的常见情况做了擦除重试处理是 BLE 工程的标配写法。第 2 步创建默认事件循环并注册连接事件处理esp_event_loop_create_default(); esp_event_handler_register(BLE_CONN_MGR_EVENTS, ESP_EVENT_ANY_ID, app_ble_conn_event_handler, NULL);app_ble_conn_event_handler监听 BLE_CONN_MGR_EVENTS 事件在ESP_BLE_CONN_EVENT_CONNECTED时打印当前功率值在ESP_BLE_CONN_EVENT_DISCONNECTED时打印断开日志case ESP_BLE_CONN_EVENT_CONNECTED: ESP_LOGI(TAG, ESP_BLE_CONN_EVENT_CONNECTED); ESP_LOGI(TAG, TX Power Level %ddBm, esp_ble_tps_get_tx_power_level()); break; case ESP_BLE_CONN_EVENT_DISCONNECTED: ESP_LOGI(TAG, ESP_BLE_CONN_EVENT_DISCONNECTED); break;第 3 步配置并初始化 BLE 连接管理器esp_ble_conn_config_t config { .device_name CONFIG_EXAMPLE_BLE_ADV_NAME, .broadcast_data CONFIG_EXAMPLE_BLE_SUB_ADV }; ... esp_ble_conn_init(config);广播名称与广播数据均取自 menuconfig 配置项。第 4 步初始化 TPS 服务并设置功率值static void app_ble_tps_init(void) { esp_ble_tps_init(); esp_ble_tps_set_tx_power_level(3); }这里演示了典型用法注册服务后立即将功率设置为 3 dBm后续对端读取即可拿到该值。第 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); }启动失败时按逆序做资源回收展示了规范的错误处理路径。4.5 运行输出验证根据 示例 README 的输出日志完整运行链路如下I (376) blecm_nimble: BLE Host Task Started I (376) blecm_nimble: getting characteristic(0x2a00) I (386) blecm_nimble: getting characteristic(0x2a01) I (396) blecm_nimble: getting characteristic(0x2a05) I (396) NimBLE: GAP procedure initiated: stop advertising. I (406) NimBLE: GAP procedure initiated: advertise; ... I (54526) app_main: ESP_BLE_CONN_EVENT_CONNECTED I (54526) app_main: TX Power Level 3dBm I (54976) blecm_nimble: mtu update event; conn_handle1 cid4 mtu256 I (58366) blecm_nimble: Read attempted for characteristic UUID 0x2a02, attr_handle 12 I (61006) blecm_nimble: Read attempted for characteristic UUID 0x2a07, attr_handle 12关键日志解读启动阶段ble_conn_mgr 依次加载标准服务特征0x2a00 设备名、0x2a01 外观、0x2a05 服务变更随后开始广播ESP_BLE_CONN_EVENT_CONNECTED后立即打印TX Power Level 3dBm即示例设置的功率值Read attempted for characteristic UUID 0x2a07, attr_handle 12对端调试 App成功发现并读取 TX Power Level 特征UUID 0x2A07说明整条对端 Read → 回调 → 返回功率值链路完全打通。五、工作原理纵深一个 Read 请求的完整旅程结合源码我们可以还原一次对端读取 TX Power Level 的完整调用链GATT 发现Client 通过服务发现找到 Service UUID 0x1804再发现其下的 TX Power Level 特征0x2A07并订阅/发起 ReadATT Read 请求NimBLE 协议栈将 Read PDU 交由 ble_conn_mgr 处理ble_conn_mgr 依据特征 UUID 在服务注册表中查找到 TPS 组件注册的条目回调触发ble_conn_mgr 调用 esp_tps_tx_power_level_cb组件校验参数、分配缓冲区、拷贝静态变量s_ble_tps_tx_power_level的值并通过att_status返回协议层结果响应回传ble_conn_mgr 将 1 字节功率值如0x03表示 3 dBm封装为 ATT Read Response 发送给 Client。可见应用层只需要通过esp_ble_tps_set_tx_power_level()维护好功率值、通过esp_ble_tps_init()完成注册其余协议交互均由连接管理器与组件回调协作完成这正是该组件声明式接入风格的体现。六、常见问题与使用建议功率值设置后对端读不到检查是否调用了esp_ble_tps_init()且顺序在esp_ble_conn_init()之后同时确认工程已通过CONFIG_BLE_TPSy开启组件编译参照 sdkconfig.defaults。期望读取到的值与实际射频功率不符如前文所述set_tx_power_level维护的是服务上报值不等于控制器实际发射功率若需要调整真实射频功率应通过 BLE 控制器/GAP 的功率控制接口操作。想修改为加密读取从 esp_ble_conn_mgr.h 可以看到连接管理器还提供BLE_CONN_GATT_CHR_READ_ENC、BLE_CONN_GATT_CHR_READ_AUTHEN、BLE_CONN_GATT_CHR_READ_AUTHOR等属性位可结合安全需求调整特征属性注意 ATT 错误码中也有ESP_IOT_ATT_INSUF_ENCRYPTION等对应状态。该服务与广播中的功率信息有何区别TPS 走 GATT 连接期读取广播功率则由广播参数Advertising管理二者用途不同、互不替代。七、总结本文从 ble_tps.rst 文档 出发完整覆盖了 TX Power Service 的标准定义、esp-iot-solution 中的组件实现、三个对外 API、示例工程的七步接入流程与运行验证并通过源码剖析还原了 Read 请求的底层调用链。该组件以极简的接口一个初始化、一个设值、一个取值依托 BLE Connection Manager 完成了标准服务接入非常适合作为开发者学习 esp-iot-solution GATT 服务组件编写范式的入门案例。若需继续深入可参考同一机制下的其他标准服务组件ble_services 目录以及 ble_conn_mgr 的 组件文档 与 示例总览。【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考