ESP IoT Solution 中的 BLE TX Power Service0x1804协议实现、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 是什么服务与特性 UUIDTX Power Service 是 Bluetooth SIG 定义的标准 GATT 服务其用途正如文档所述在连接状态下公开设备的当前发射功率水平。它只包含一个必选特性——TX Power Level。项目值说明服务 UUID0x1804TX Power Service 的 16 位标准 UUID特性 UUID0x2A07TX Power Level 特性携带 1 字节有符号整数int8特性属性Read可读对端客户端可随时读取当前发射功率这两个 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 0x2A07TX Power Level 的取值为有符号 8 位整数单位 dBm例如 3 表示 3 dBm。对端设备读取该特性后可以结合 RSSI接收信号强度间接评估无线链路质量。与 BLE 连接管理框架的关系从源码结构看esp-iot-solution 的 TX Power Service 并非独立实现完整 GATT 栈而是构建在仓库自带的ble_conn_mgrBLE 连接管理器框架之上。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_cbstatic 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 对外提供三个接口覆盖初始化、读取与设置三个操作维度函数原型功能初始化esp_err_t esp_ble_tps_init(void)向 BLE 连接管理器注册 TX Power 服务返回ESP_OK表示成功ESP_ERR_INVALID_ARG表示初始化参数错误ESP_FAIL表示其他错误读取功率int8_t esp_ble_tps_get_tx_power_level(void)返回设备当前 TX Power LeveldBm设置功率esp_err_t esp_ble_tps_set_tx_power_level(int8_t tx_power_level)设置设备当前 TX Power Level返回ESP_OK或ESP_ERR_INVALID_ARG使用示例#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(); // 读取返回 3Kconfig 开关组件提供 Kconfig 开关BLE_TPSGATT TX Power Service定义于 Kconfig.in。启用方式为在应用工程中设置idf.py menuconfig并在sdkconfig.defaults中加入CONFIG_BLE_TPSy实战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_servicesble_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_ENABLEDy CONFIG_BT_NIMBLE_ENABLEDy CONFIG_BLE_CONN_MGR_ROLE_PERIPHERALy CONFIG_BLE_TPSy退出串口监视器按Ctrl-]。配置广播名称运行idf.py menuconfig后在Example Configuration菜单中可以配置Advertisement nameEXAMPLE_BLE_ADV_NAME设备广播名默认BLE_TPSSubsequent advertisement dataEXAMPLE_BLE_SUB_ADV后续广播数据默认SUB_ADV。对应配置定义见 main/Kconfig.projbuild。主程序流程主程序 main/app_main.c 完整演示了 TPS 与连接管理器的协作方式初始化 NVS必要时擦除重建创建默认事件循环并注册BLE_CONN_MGR_EVENTS事件处理器调用esp_ble_conn_init(config)初始化连接管理器config.device_name取自CONFIG_EXAMPLE_BLE_ADV_NAME调用app_ble_tps_init()完成 TPS 注册与功率设置static void app_ble_tps_init(void) { esp_ble_tps_init(); esp_ble_tps_set_tx_power_level(3); }调用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 Service0x1804通过一个只读的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ESP IoT Solution 中的 BLE TX Power Service（0x1804）：协议实现、API 与实战示例
ESP IoT Solution 中的 BLE TX Power Service0x1804协议实现、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 是什么服务与特性 UUIDTX Power Service 是 Bluetooth SIG 定义的标准 GATT 服务其用途正如文档所述在连接状态下公开设备的当前发射功率水平。它只包含一个必选特性——TX Power Level。项目值说明服务 UUID0x1804TX Power Service 的 16 位标准 UUID特性 UUID0x2A07TX Power Level 特性携带 1 字节有符号整数int8特性属性Read可读对端客户端可随时读取当前发射功率这两个 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 0x2A07TX Power Level 的取值为有符号 8 位整数单位 dBm例如 3 表示 3 dBm。对端设备读取该特性后可以结合 RSSI接收信号强度间接评估无线链路质量。与 BLE 连接管理框架的关系从源码结构看esp-iot-solution 的 TX Power Service 并非独立实现完整 GATT 栈而是构建在仓库自带的ble_conn_mgrBLE 连接管理器框架之上。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_cbstatic 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 对外提供三个接口覆盖初始化、读取与设置三个操作维度函数原型功能初始化esp_err_t esp_ble_tps_init(void)向 BLE 连接管理器注册 TX Power 服务返回ESP_OK表示成功ESP_ERR_INVALID_ARG表示初始化参数错误ESP_FAIL表示其他错误读取功率int8_t esp_ble_tps_get_tx_power_level(void)返回设备当前 TX Power LeveldBm设置功率esp_err_t esp_ble_tps_set_tx_power_level(int8_t tx_power_level)设置设备当前 TX Power Level返回ESP_OK或ESP_ERR_INVALID_ARG使用示例#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(); // 读取返回 3Kconfig 开关组件提供 Kconfig 开关BLE_TPSGATT TX Power Service定义于 Kconfig.in。启用方式为在应用工程中设置idf.py menuconfig并在sdkconfig.defaults中加入CONFIG_BLE_TPSy实战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_servicesble_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_ENABLEDy CONFIG_BT_NIMBLE_ENABLEDy CONFIG_BLE_CONN_MGR_ROLE_PERIPHERALy CONFIG_BLE_TPSy退出串口监视器按Ctrl-]。配置广播名称运行idf.py menuconfig后在Example Configuration菜单中可以配置Advertisement nameEXAMPLE_BLE_ADV_NAME设备广播名默认BLE_TPSSubsequent advertisement dataEXAMPLE_BLE_SUB_ADV后续广播数据默认SUB_ADV。对应配置定义见 main/Kconfig.projbuild。主程序流程主程序 main/app_main.c 完整演示了 TPS 与连接管理器的协作方式初始化 NVS必要时擦除重建创建默认事件循环并注册BLE_CONN_MGR_EVENTS事件处理器调用esp_ble_conn_init(config)初始化连接管理器config.device_name取自CONFIG_EXAMPLE_BLE_ADV_NAME调用app_ble_tps_init()完成 TPS 注册与功率设置static void app_ble_tps_init(void) { esp_ble_tps_init(); esp_ble_tps_set_tx_power_level(3); }调用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 Service0x1804通过一个只读的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考