ESP IoT Solution BLE TX Power Service（esp_tps）组件使用指南：从服务注册到发射功率上报的完整实践

ESP IoT Solution BLE TX Power Service（esp_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 Service（TPS，服务 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 UUID	BLE_TPS_UUID16	0x1804	16-bit Service UUID
TX Power Level 特征 UUID	BLE_TPS_CHR_UUID16_TX_POWER_LEVEL	0x2A07	16-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 Manager（ble_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); }

其工作机制为：

1. 组件定义一张“特征查找表”（nu_lookup_table），每个条目声明特征名称、UUID 类型（16-bit）、访问属性（只读）以及处理回调；
2. 将服务（UUID 0x1804）与其特征表打包成esp_ble_conn_svc_t结构体；
3. 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_cb：

static 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_ERROR（0x81）；
• 内存管理：动态分配输出缓冲区并拷贝当前功率值，分配失败时返回ESP_ERR_NO_MEM，同时将 ATT 状态置为ESP_IOT_ATT_INSUF_RESOURCE（0x11）；
• ATT 状态码：成功时显式置为ESP_IOT_ATT_SUCCESS（0x00）。完整的 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 Targets
ESP32
ESP32-C3
ESP32-C2
ESP32-S3
ESP32-H2

硬件上仅需一块上述任一 SoC 的开发板 + USB 线（供电与烧录），对端使用任意 BLE 扫描/调试 App（如 nRF Connect、LightBlue）即可完成验证。

4.2 配置项：广播名称与后续广播数据

示例在 menuconfig 中提供两个可配置项，定义于 Kconfig.projbuild：

配置项	类型	默认值	含义
EXAMPLE_BLE_ADV_NAME	string	BLE_TPS	广播包中的设备名称
EXAMPLE_BLE_SUB_ADV	string	SUB_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_ENABLED=y CONFIG_BT_NIMBLE_ENABLED=y CONFIG_BLE_CONN_MGR_ROLE_PERIPHERAL=y CONFIG_BLE_TPS=y

逐项说明：

• CONFIG_BT_ENABLED=y与CONFIG_BT_NIMBLE_ENABLED=y：启用蓝牙控制器与 NimBLE 主机栈（该示例基于 NimBLE）；
• CONFIG_BLE_CONN_MGR_ROLE_PERIPHERAL=y：将 ble_conn_mgr 配置为外设（Peripheral）角色，本示例作为 GATT Server 广播并接受连接；
• CONFIG_BLE_TPS=y：使能 TX Power Service 组件本身。对应地，tps 组件目录下的 Kconfig.in 负责该组件的编译开关。

构建与烧录：

idf.py -p PORT flash monitor

（退出串口监视器按Ctrl-]。）

4.4 主程序流程：七步搭建 TPS 外设

app_main.c 完整演示了 TPS 的接入流程，可拆解为七个步骤：

第 1 步：初始化 NVS

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);

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_handle=1 cid=4 mtu=256 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 的完整调用链：

1. GATT 发现：Client 通过服务发现找到 Service UUID 0x1804，再发现其下的 TX Power Level 特征（0x2A07），并订阅/发起 Read；
2. ATT Read 请求：NimBLE 协议栈将 Read PDU 交由 ble_conn_mgr 处理；ble_conn_mgr 依据特征 UUID 在服务注册表中查找到 TPS 组件注册的条目；
3. 回调触发：ble_conn_mgr 调用 esp_tps_tx_power_level_cb，组件校验参数、分配缓冲区、拷贝静态变量s_ble_tps_tx_power_level的值，并通过att_status返回协议层结果；
4. 响应回传：ble_conn_mgr 将 1 字节功率值（如0x03表示 +3 dBm）封装为 ATT Read Response 发送给 Client。

可见，应用层只需要通过esp_ble_tps_set_tx_power_level()维护好功率值、通过esp_ble_tps_init()完成注册，其余协议交互均由连接管理器与组件回调协作完成，这正是该组件"声明式"接入风格的体现。

六、常见问题与使用建议

1. 功率值设置后对端读不到？检查是否调用了esp_ble_tps_init()且顺序在esp_ble_conn_init()之后；同时确认工程已通过CONFIG_BLE_TPS=y开启组件编译（参照 sdkconfig.defaults）。
2. 期望读取到的值与实际射频功率不符？如前文所述，set_tx_power_level维护的是服务上报值，不等于控制器实际发射功率；若需要调整真实射频功率，应通过 BLE 控制器/GAP 的功率控制接口操作。
3. 想修改为加密读取？从 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等对应状态）。
4. 该服务与广播中的功率信息有何区别？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