esp-iot-solution 中 BLE Alert Notification Profile（ANP）组件：从 GATT 客户端 API 到实战调试-北京尧图网络

esp-iot-solution 中 BLE Alert Notification ProfileANP组件从 GATT 客户端 API 到实战调试【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution本篇技术指南围绕 esp-iot-solution 仓库中的ble_anp组件展开讲解如何基于 BLE Alert Notification ProfileANP / ANSGATT 客户端角色读取服务器端的新警报与未读警报类别、订阅通知并控制通知启停。读完本文你将掌握ble_anp组件的完整 API 语义、事件流、源码级实现细节以及如何用官方示例与串口控制台anp命令在 ESP32 系列芯片上完成联调验证。组件定位与适用场景ble_anp是 esp-iot-solution 中 Bluetooth 标准 Profile 家族的一员其定位在 idf_component.yml 中被描述为 BLE standard profile support Alert Notification。该组件在 GATT客户端一侧为访问常用的 BLE 警报通知Alert Notification功能提供一套简化 API 接口。Alert Notification ProfileANP是蓝牙 SIG 定义的经典 Profile 之一其核心服务为 Alert Notification ServiceANS16 位 UUID0x1811。典型使用场景包括智能手环/手表从手机接收来电、短信、邮件、日程等提醒设备作为 GATT 客户端连接具备 ANS 服务的对端通常是手机读取对端支持的新警报类别订阅 New Alert 与 Unread Alert Status 两个特征值的通知从而实时获知警报计数变化。组件结构非常精简全量代码仅有三个文件include/esp_anp.h对外公开的 API、事件、UUID 与常量定义src/esp_anp.c核心实现Kconfig组件级编译开关。快速接入组件依赖与示例工程添加组件依赖在项目目录下使用 ESP-IDF 组件管理器idf-component-manager的add-dependency命令即可将ble_anp加入项目依赖CMake 阶段会自动下载该组件idf.py add-dependency espressif/ble_anp*从示例模板创建工程组件管理器还提供create-project-from-example命令可直接从示例模板生成工程下载完成后即可进入目录编译烧录idf.py create-project-from-example espressif/ble_anp*:ble_anp此外示例源码也直接托管在 esp-iot-solution 仓库中examples/bluetooth/ble_profiles/ble_anp。该示例基于 NimBLE 控制器与 BLE 连接管理组件其 README 明确指出示例创建一个 GATT 客户端并执行被动扫描当对端设备广播可连接且主服务 UUID 为 Alert Notification Service0x1811时即发起连接。常见问题组件管理器报错原文档还记录了一个组件管理器使用时的典型问题在旧版本包管理器下执行create-project-from-example会报Executing action: create-project-from-example CMakeLists.txt not found in project directory /home/username解决办法是在 ESP-IDF 环境中升级组件管理器pip install -U idf-component-manager协议骨架ANS 服务 UUID 与特征值组件在 esp_anp.h 中定义了 ANS 服务及其全部特征值的 16 位 UUID常量UUID对应特征值BLE_ANP_UUID160x1811Alert Notification ServiceBLE_ANP_CHR_UUID16_SUP_NEW_ALERT_CAT0x2A47Supported New Alert CategoryBLE_ANP_CHR_UUID16_NEW_ALERT0x2A46New AlertBLE_ANP_CHR_UUID16_SUP_UNR_ALERT_CAT0x2A48Supported Unread Alert CategoryBLE_ANP_CHR_UUID16_UNR_ALERT_STAT0x2A45Unread Alert StatusBLE_ANP_CHR_UUID16_ALERT_NOT_CTRL_PT0x2A44Alert Notification Control Point警报类别Category与位掩码ANS 协议将警报划分为若干预定义类别。组件在 esp_anp.h 中同时给出类别 ID 与对应的位掩码便于在读取 Supported ... Category 特征值时按位判断类别 ID位掩码含义00x01Simple Alert简单警报10x02Email邮件20x04News新闻30x08Call来电40x10Missed Call未接来电50x20SMS/MMS短信60x40Voice Mail语音信箱70x80Schedule日程源码中的BLE_ANP_CAT_BM_NONE0x00表示无类别BLE_ANP_CAT_NUM定义为 8。代码注释保留了 TODO协议标准中还有 2 个可选类别Instant Message 与 Simple Alert 的扩展尚未加入。控制点命令Command ID对端服务器的 Alert Notification Control Point 特征值用于启停各类别的通知命令 ID 定义见 esp_anp.h命令常量值含义BLE_ANP_CMD_EN_NEW_ALERT_CAT0Enable New Alert CategoryBLE_ANP_CMD_EN_UNR_ALERT_CAT1Enable Unread Alert Status CategoryBLE_ANP_CMD_DIS_NEW_ALERT_CAT2Disable New Alert CategoryBLE_ANP_CMD_DIS_UNR_ALERT_CAT3Disable Unread Alert Status CategoryBLE_ANP_CMD_NOT_NEW_ALERT_IMMEDIATE4Notify New Alert ImmediatelyBLE_ANP_CMD_NOT_UNR_ALERT_IMMEDIATE5Notify Unread Alert Status Immediately对外 API 全解ble_anp的全部对外接口声明在 esp_anp.h共 6 个函数逻辑上分为 New Alert 与 Unread Alert 两组每组包含 Get / Set 两个操作外加 init / deinit。初始化与反初始化esp_err_t esp_ble_anp_init(void); esp_err_t esp_ble_anp_deinit(void);从 esp_anp.c 的实现看init 的本质是向事件循环注册 BLE 连接管理组件ble_conn_mgr的事件处理器esp_ble_anp_event监听其所有事件ESP_EVENT_ANY_IDdeinit 则相反注销该处理器。也就是说ble_anp本身并不发起连接而是依赖 components/bluetooth/ble_conn_mgr 完成 GATT 连接与数据收发并在收到特征值通知后解析转发。New Alert 类别读取与设置esp_err_t esp_ble_anp_get_new_alert(uint8_t cat_id, uint8_t *cat_val); esp_err_t esp_ble_anp_set_new_alert(uint8_t cat_id, esp_ble_anp_option_t option);esp_ble_anp_get_new_alert用于读取或检查 Supported New Alert Category 特征值其语义由cat_id决定cat_id 0xFF读取整个特征值即服务器支持的全部 New Alert 类别位图结果经cat_val返回cat_id为具体类别 ID检查该类别当前是启用还是禁用返回 1/0。从实现看esp_anp.c该函数通过esp_ble_conn_read()发起一次 GATT 读操作将读取结果缓存在静态变量ble_svc_ans_new_alert_cat中再按cat_id移位取值。esp_ble_anp_set_new_alert通过esp_ble_anp_alert_ctrl_set()向服务器的 Alert Notification Control Point 写命令option取值为选项值行为BLE_ANP_OPT_ENABLE0启用指定类别的 New Alert 通知并紧接着下发 Notify New Alert Immediately 命令请求服务器立即上报当前计数esp_anp.cBLE_ANP_OPT_DISABLE1禁用指定类别的 New Alert 通知BLE_ANP_OPT_RECOVER2连接丢失恢复对所有已启用类别cat_id 0xFF恢复通知并请求立即上报Unread Alert 类别读取与设置esp_err_t esp_ble_anp_get_unr_alert(uint8_t cat_id, uint8_t *cat_val); esp_err_t esp_ble_anp_set_unr_alert(uint8_t cat_id, esp_ble_anp_option_t option);两组函数完全对称get_unr_alert读取/检查 Supported Unread Alert Category 特征值esp_anp.cset_unr_alert则向控制点写入 Enable/Disable/Recover 命令esp_anp.c。两者的cat_id特殊值0xFF均表示全部类别。所有 API 在cat_id非法既不是 0~7 也不是0xFF或参数为空指针时返回ESP_ERR_INVALID_ARG成功返回ESP_OK。事件与数据结构组件定义了自己的事件基类BLE_ANP_EVENTS见 esp_anp.h在收到服务器通知后通过esp_event_post对外投递两类事件事件 ID 即特征值 UUIDBLE_ANP_CHR_UUID16_NEW_ALERT0x2A46携带新警报数据BLE_ANP_CHR_UUID16_UNR_ALERT_STAT0x2A45携带未读警报状态。事件数据统一封装在esp_ble_anp_data_t联合体中esp_anp.htypedef struct { union { struct { uint8_t cat_id; /*! 警报类别 ID */ uint8_t count; /*! 警报计数0~255 */ } unr_alert_stat; /*! 未读警报状态 */ struct { uint8_t cat_id; /*! 警报类别 ID */ uint8_t count; /*! 警报计数0~255 */ uint8_t cat_info[BLE_ANP_INFO_STR_MAX_LEN]; /*! 最后一条警报的简短文本 */ } new_alert_val; /*! 新警报状态 */ }; /*! 警报通知状态 */ } esp_ble_anp_data_t;注意New Alert 特征值0x2A46在协议中允许携带最多 18 字节的警报信息字符串BLE_ANP_INFO_STR_MAX_LEN加上 1 字节类别 ID 与 1 字节计数因此组件将内部缓存缓冲定义为BLE_ANP_NEW_ALERT_MAX_LEN 20esp_anp.h。源码级实现剖析控制点命令的构造与写操作核心私有函数esp_ble_anp_alert_ctrl_set()esp_anp.c完整演示了 ANS 控制点的操作流程构造esp_ble_conn_data_t写请求UUID 为0x2A44Control Point负载为 2 字节[cmd_id, cat_id]将cat_id映射为位掩码合法类别为(1 cat_id)0xFF表示全部类别其余返回ESP_ERR_INVALID_ARG依据命令 ID 更新内部缓存的启用类别位图ble_svc_ans_new_alert_cat/ble_svc_ans_unr_alert_catEnable 置位、Disable 清位对 Immediate 命令则打印将立即通知的类别调用esp_ble_conn_write()真正写入控制点成功后打印 Configure Alert Notification Control Point Success! 与负载 HEX 日志。该函数恰好对应了蓝牙规范中的 4.09 Configure Alert Notification Control Point 一节源码注释与示例日志中的 4.03 / 4.04 / 4.06 / 4.08 / 4.10 / 4.11 / 4.12 / 4.13 编号即 ANS 规范中各操作的章节号方便对照蓝牙核心规范逐条验证。通知接收与事件转发esp_ble_anp_eventesp_anp.c是组件与ble_conn_mgr之间的桥梁校验事件基类是否为BLE_CONN_MGR_EVENTS仅处理ESP_BLE_CONN_EVENT_DATA_RECEIVE数据接收事件按conn_data-uuid.uuid16分发0x2A46交给esp_ble_anp_handle_new_alert校验类别已启用后更新计数缓存并将可选的信息字符串截断复制到cat_info最多 18 字节见 esp_anp.c0x2A45交给esp_ble_anp_handle_unr_alert要求负载恰好 2 字节类别 ID 状态否则报错返回见 esp_anp.c将解析结果封装为esp_ble_anp_data_t通过esp_event_post(..., portMAX_DELAY)投递到BLE_ANP_EVENTS事件基类下供用户层注册的处理器消费。值得一提的是通知到达时会先检查(cat_bit_mask ble_svc_ans_new_alert_cat) 0即只有已被本端启用订阅的类别才会计数这避免了未授权类别数据被误解析。事件驱动模型与连接管理从 esp_anp.c 的ESP_EVENT_DEFINE_BASE(BLE_ANP_EVENTS)可以看出ble_anp完全构建在 ESP-IDF 的esp_event事件循环之上底层ble_conn_mgr把 GATT 层的连接/断开/数据接收翻译为BLE_CONN_MGR_EVENTS事件ble_anp消费并解析出 ANS 语义再以BLE_ANP_EVENTS重新投递。用户应用只需要esp_event_handler_register(BLE_ANP_EVENTS, ESP_EVENT_ANY_ID, ...)即可拿到解析后的警报数据无需关心 GATT 细节。配置开关与编译约束ble_anp提供 Kconfig 编译开关Kconfigmenu BLE Profile: Alert Notification config BLE_ALERT_NOTIFICATION_PROFILES bool Enable Alert Notification Profile default n help Enable support for Alert Notification Profile. endmenuBLE_ALERT_NOTIFICATION_PROFILES默认关闭n需要时在idf.py menuconfig中打开。组件版本信息见 CHANGELOG.md当前为 v0.1.0首个发布版本功能为 ANP: Support Alert Notification Profile。官方示例实操串口控制台完整调试示例工程位于 examples/bluetooth/ble_profiles/ble_anp其 README 声明支持 ESP32、ESP32-C3、ESP32-C2、ESP32-S3 四个目标芯片使用 NimBLE 控制器与ble_conn_mgr。硬件与工程配置硬件一块 ESP32 系列开发板如 ESP32-DevKitC、ESP-WROVER-KIT USB 数据线目标芯片与工程配置idf.py set-target chip_name idf.py menuconfig在Example Configuration菜单中可设置广播名称Advertisement name默认值为BLE_ANS对应 app_main.c 中的CONFIG_EXAMPLE_BLE_ADV_NAME与CONFIG_EXAMPLE_BLE_SUB_ADV。编译烧录与监视idf.py -p PORT flash monitor退出串口监视器按Ctrl-]。程序行为app_mainapp_main.c依次完成 NVS 初始化、创建默认事件循环、注册ble_conn_mgr连接事件、初始化串口控制台并注册anp命令、最后调用esp_ble_conn_init(config)与esp_ble_conn_start()启动 GATT 客户端。启动后设备执行被动扫描发现广播了 ANS 服务0x1811的可连接对端即自动连接。示例日志中可见完整的 GATT 服务发现、特征值发现与描述符发现过程。对端可以是任意支持 Alert Notification Service 的 BLE GATT 服务器应用如手机端 ANS 模拟 App。示例会对对端依次执行三类 GATT 操作读取 Supported New Alert Category 特征值、写入 Alert Notification Control Point 特征值、订阅 Unread Alert Status 特征值通知若对端声明的能力与实际 GATT 数据库不符或过程失败连接会被立即终止。anp命令用法示例注册了anp控制台命令注册逻辑见 app_anp.canp [-t 01~04] [-c 01~255] [-o 00~02] -t, --type01~04 01 Get supported new alert category 02 Set supported new alert category 03 Get supported unread alert status category 04 Set supported unread alert status category -c, --category01~255 Category ID -o, --option00~02 0: Enable, 1: Disable, 2: Recover三个参数均为必填由 argtable3 解析后路由到对应 API见 app_anp.c。New Alert 类别调试命令读取 Supported New Alert Category 特征值-c 1检查类别 1 是否启用-c 255即0xFF读取完整位图anp -t 1 -c 1 -o 0 anp -t 1 -c 255 -o 0启用类别 1 的 New Alert 通知计数变化时上报、禁用、以及断连后恢复anp -t 2 -c 1 -o 0 anp -t 2 -c 1 -o 1 anp -t 2 -c 1 -o 2Unread Alert 类别调试命令对称地读取 Supported Unread Alert Category 特征值anp -t 3 -c 1 -o 0 anp -t 3 -c 255 -o 0启用/禁用/恢复 Unread Alert 状态通知anp -t 4 -c 1 -o 0 anp -t 4 -c 1 -o 1 anp -t 4 -c 1 -o 2典型运行日志解读示例 README 给出的运行日志完整呈现了一次调用链。以下以anp -t 2 -c 3 -o 0启用类别 3 的 New Alert 通知为例I (27848) NimBLE: GATT procedure initiated: write; I (27928) esp_anp: Configure Alert Notification Control Point Success! I (27928) esp_anp: 00 03 I (27928) esp_anp: Request the New Alert in the server to notify immediately on current enabled categories 3 I (28028) esp_nimble: received notification; conn_handle1 attr_handle15 attr_len2 I (28038) esp_anp: Receive Notification of New Alert on cat_id 3 which count change to 0 I (28048) app_anp: Get the current message counts 3 from category 0 of supported new alert日志对应关系esp_anp: 00 03写入控制点的负载命令0x00Enable New Alert Category 类别0x03Call 来电esp_anp: Receive Notification of New Alert ...组件内部分发到esp_ble_anp_handle_new_alert并更新计数app_anp: Get the current message counts ...应用层app_anp_event_handlerapp_anp.c收到BLE_ANP_EVENTS事件后的解析输出。当服务器侧来电数量从 0 变为 1 时串口会再次输出count change to 1证明通知订阅链路控制点配置 → 服务器上报 →ble_conn_mgr收包 →esp_anp解析 → 应用层事件完全打通。小结ble_anp以极简的 6 个 API 封装了 ANS 客户端侧的全部核心操作读取/检查 Supported 类别、通过 Control Point 启停/恢复各类别通知、解析并转发 New Alert 与 Unread Alert 状态。其实现完全基于事件驱动与ble_conn_mgr解耦协作配合官方示例中的anp串口命令可以在 ESP32 系列开发板上快速完成从扫描连接 ANS 对端到实时接收警报计数的完整验证。如需深入协议细节可对照 esp_anp.c 中的规范章节编号注释逐条核对蓝牙核心规范中的 ANS 操作流程。【免费下载链接】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 Alert Notification Profile（ANP）组件：从 GATT 客户端 API 到实战调试

相关推荐

2024论文降重工具评测与使用技巧

2026年AI编程工具实战评估：真实开发场景下的可靠性与工程适配

Python + FastAPI 连接金仓 KingbaseES：从裸 SQL 到连接池的工程实践

更多资讯

Matter tv-app Android Common-API 模块详解：内容应用与 Matter Agent 服务的 AIDL 跨进程通信机制

ASP.NET在线考试系统：组卷、交卷并发与防作弊设计

Hello-Agents 共创实战：用 Reflection 反思机制构建 CodePlanAgent 智能代码规划工具

IEEE 802.11a/g物理层OFDM链路级仿真：从发射机到误码率统计的完整实现

Linux安装为何必须挂载/boot/efi：UEFI引导与ESP分区详解

从 .doc 到结构化题库：选择题文档解析与 JSON 转换全流程

今日更新

AReaL 调试指南：从 Agent Workflow 验证到分布式训练死锁诊断

MATLAB实现GPS L1 C/A信号仿真与二维捕获验证

彻底搞懂ASCII、Unicode与UTF-8：从乱码根源到编码实战

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？