企业官网建设流程全解析

ESP IoT Solution 中的 BLE TX Power Service（0x1804）：协议实现、API 与实战示例

【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution

导读

TX Power Service（发射功率服务）是 Bluetooth LE GATT 体系中的一个标准服务，用于在连接期间对外公开设备当前的射频发射功率水平（单位 dBm），帮助对端设备或调试工具评估链路质量与信号强度。本文以 esp-iot-solution 仓库中的 TX Power Service 组件（components/bluetooth/ble_services/tps）为核心，从标准定义、组件源码实现、公开 API 到完整的 GATT Server 示例，逐层讲解该服务在 docs/zh_CN/bluetooth/ble_tps.rst 基础上如何落地为可直接编译运行的工程代码，读完即可在自己的 BLE 外设工程中接入 TX Power 服务。

TX Power Service 是什么

服务与特性 UUID

TX Power Service 是 Bluetooth SIG 定义的标准 GATT 服务，其用途正如文档所述：在连接状态下公开设备的当前发射功率水平。它只包含一个必选特性——TX Power Level。

这两个 UUID 在组件头文件 esp_tps.h 中以宏形式公开：

/* 16 Bit TX Power Service UUID */ #define BLE_TPS_UUID16 0x1804 /* 16 Bit TX Power Service Characteristic UUIDs */ #define BLE_TPS_CHR_UUID16_TX_POWER_LEVEL 0x2A07

TX Power Level 的取值为有符号 8 位整数，单位 dBm，例如 3 表示 +3 dBm。对端设备读取该特性后，可以结合 RSSI（接收信号强度）间接评估无线链路质量。

与 BLE 连接管理框架的关系

从源码结构看，esp-iot-solution 的 TX Power Service 并非独立实现完整 GATT 栈，而是构建在仓库自带的ble_conn_mgr（BLE 连接管理器）框架之上。esp_ble_tps_init()的底层实现只有一行核心逻辑：

esp_err_t esp_ble_tps_init(void) { return esp_ble_conn_add_svc(&svc); }

即把 TPS 服务描述结构注册进连接管理器维护的 GATT 服务表中（源码见 esp_tps.c）。这意味着使用该组件前，需要先初始化ble_conn_mgr，并在组件依赖中声明它（见后文示例工程的idf_component.yml）。

服务实现剖析

服务与特性的描述表

在 esp_tps.c 中，服务通过两张表描述：特性查找表（nu_lookup_table）与服务结构体（svc）。

特性查找表将tx_power_level特性映射为 16 位 UUID0x2A07、只读（BLE_CONN_GATT_CHR_READ）属性，并绑定其读取回调esp_tps_tx_power_level_cb：

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}, };

服务结构体声明服务 UUID 为0x1804，并挂载上述特性表：

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

读取回调与错误处理

当 GATT 客户端发起读操作时，框架调用esp_tps_tx_power_level_cb。回调内部校验参数（inbuf必须为空、outbuf/outlen必须非空），然后动态分配缓冲区并拷贝当前功率值，最后设置 ATT 状态码：

• ESP_IOT_ATT_SUCCESS：读取成功；
• ESP_IOT_ATT_INTERNAL_ERROR：参数非法时的内部错误；
• ESP_IOT_ATT_INSUF_RESOURCE：内存分配失败、资源不足。

功率值的存取基于静态变量s_ble_tps_tx_power_level，由下述公开 API 维护。

API 参考

组件通过 esp_tps.h 对外提供三个接口，覆盖初始化、读取与设置三个操作维度：

使用示例：

#include "esp_tps.h" esp_ble_tps_init(); // 注册 TX Power 服务 esp_ble_tps_set_tx_power_level(3); // 设置功率为 +3 dBm int8_t level = esp_ble_tps_get_tx_power_level(); // 读取，返回 3

Kconfig 开关

组件提供 Kconfig 开关BLE_TPS（"GATT TX Power Service"），定义于 Kconfig.in。启用方式为在应用工程中设置：

idf.py menuconfig

并在sdkconfig.defaults中加入：

CONFIG_BLE_TPS=y

实战：BLE_TPS 示例工程

工程结构与依赖

示例位于 examples/bluetooth/ble_services/ble_tps，支持 ESP32、ESP32-C3、ESP32-C2、ESP32-S3、ESP32-H2 等目标芯片。其组件依赖声明于 main/idf_component.yml，通过override_path指向仓库内本地组件：

dependencies: idf: ">=4.3" ble_conn_mgr: version: "~1.*" override_path: "../../../../../components/bluetooth/ble_conn_mgr" ble_services: version: "~1.*" override_path: "../../../../../components/bluetooth/ble_services"

ble_services组件（即 components/bluetooth/ble_services）包含 tps 在内的全部标准 BLE 服务，编译时根据 Kconfig 开关决定是否链接 TPS。

编译与烧录

在示例目录下执行：

idf.py set-target <chip_name> # 例如 esp32s3 idf.py -p PORT flash monitor

其中sdkconfig.defaults已默认开启蓝牙栈与服务开关：

CONFIG_BT_ENABLED=y CONFIG_BT_NIMBLE_ENABLED=y CONFIG_BLE_CONN_MGR_ROLE_PERIPHERAL=y CONFIG_BLE_TPS=y

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

配置广播名称

运行idf.py menuconfig后，在Example Configuration菜单中可以配置：

• Advertisement name（EXAMPLE_BLE_ADV_NAME）：设备广播名，默认BLE_TPS；
• Subsequent advertisement data（EXAMPLE_BLE_SUB_ADV）：后续广播数据，默认SUB_ADV。

对应配置定义见 main/Kconfig.projbuild。

主程序流程

主程序 main/app_main.c 完整演示了 TPS 与连接管理器的协作方式：

1. 初始化 NVS（必要时擦除重建）；
2. 创建默认事件循环并注册BLE_CONN_MGR_EVENTS事件处理器；
3. 调用esp_ble_conn_init(&config)初始化连接管理器，config.device_name取自CONFIG_EXAMPLE_BLE_ADV_NAME；
4. 调用app_ble_tps_init()完成 TPS 注册与功率设置：

static void app_ble_tps_init(void) { esp_ble_tps_init(); esp_ble_tps_set_tx_power_level(3); }

5. 调用esp_ble_conn_start()启动广播，失败时依次执行esp_ble_conn_stop()、esp_ble_conn_deinit()并注销事件处理器。

在连接事件回调中，设备连接成功后会打印当前功率值：

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;

预期运行输出

使用任意 BLE 扫描工具（如 nRF Connect）连接并读取0x2A07特性，串口输出与 README.md 中的示例一致：

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 (406) NimBLE: GAP procedure initiated: advertise; I (54526) app_main: ESP_BLE_CONN_EVENT_CONNECTED I (54526) app_main: TX Power Level 3dBm I (58366) blecm_nimble: Read attempted for characteristic UUID = 0x2a07, attr_handle = 12

从日志可以看到：连接建立后打印TX Power Level 3dBm，客户端每读取一次0x2A07特性，blecm_nimble便会记录一次读取尝试，验证了特性注册与回调路径的有效性。

使用要点与注意事项

• 必须先初始化连接管理器：esp_ble_tps_init()依赖esp_ble_conn_add_svc()，因此在调用前需完成esp_ble_conn_init()，并在依赖中引入ble_conn_mgr。
• 服务在连接时生效：按照 BLE 规范，TX Power 服务在连接状态下公开功率水平，本示例基于BLE_CONN_MGR_ROLE_PERIPHERAL（外设角色）运行。
• 功率值为应用层维护的数值：esp_ble_tps_set_tx_power_level()仅更新服务对外暴露的值，实际射频发射功率由蓝牙控制器层控制，两者应保持语义一致（例如本示例设置为 3 dBm）。
• 属性为只读：TX Power Level 特性属性为BLE_CONN_GATT_CHR_READ，不支持写入与通知，GATT 客户端只能读取。
• 最小 IDF 版本：示例依赖idf: ">=4.3"，请确保 ESP-IDF 版本满足要求。

总结

TX Power Service（0x1804）通过一个只读的 TX Power Level 特性（0x2A07），在连接期间向对端公开设备当前发射功率，是评估 BLE 链路质量的常用辅助手段。在 esp-iot-solution 中，该服务由 components/bluetooth/ble_services/tps 组件基于ble_conn_mgr框架实现，通过esp_ble_tps_init()、esp_ble_tps_get_tx_power_level()、esp_ble_tps_set_tx_power_level()三个接口即可完成注册与功率维护；配套的 ble_tps 示例 提供了从 NVS 初始化、连接管理器启动到广播与事件处理的完整可运行参考，可直接作为其他 BLE 外设服务接入的模板。

【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution