ESP IoT Solution BLE 警报通知服务（ANS）开发指南：特性、API 与示例实战

ESP IoT Solution BLE 警报通知服务ANS开发指南特性、API 与示例实战【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution警报通知服务Alert Notification Service简称 ANS是蓝牙 SIG 定义的 GATT 服务用于把设备上的警报信息警报类型、来电显示等文本、新警报计数、未读警报计数通过 BLE 连接开放给手机等客户端。在乐鑫 esp-iot-solution 仓库中该服务以独立组件components/bluetooth/ble_services/ans的形式实现并与ble_conn_mgr连接管理组件深度集成。本文以 警报通知服务文档 为骨架结合组件源码与配套示例讲解 ANS 的架构、数据模型、API 用法与调试方法读完你可以直接在 ESP32 系列芯片上把 ANS 集成进自己的 BLE 外设应用。什么是警报通知服务ANSANS 是一种 GATT 服务器端服务用于向已连接的客户端如手机 App公开设备中发生的警报信息。根据 警报通知服务文档 的说明这些信息包括四类设备中发生的警报类型如简单警报、邮件、来电、短信等附加的文本信息如来电显示Caller ID或发件人 IDSender ID新警报New Alert的计数未读警报项Unread Alert的计数典型应用场景是把手机上的来电、短信、邮件、日程等通知实时转发到腕表、手环、桌面提示器等低功耗外设上外设侧运行 ANS 服务手机作为 GATT 客户端写入/订阅从而完成通知的推送与状态同步。仓库中的 ANS 组件与示例esp-iot-solution 中与 ANS 直接相关的资源有两处服务组件ans 组件 包含头文件 esp_ans.h 与实现 esp_ans.c以及组件级开关 Kconfig.inmenuconfig 项BLE_ANS。配套示例ble_ans 示例它构建一个 GATT 服务器并启动广播等待 GATT 客户端连接同时通过串口提供一个交互式 shellans命令来模拟 ANS 行为方便在没有真实手机 App 的情况下验证服务逻辑。示例基于 BLE 连接管理ble_conn_mgr实现官方支持的芯片目标为 ESP32、ESP32-C3、ESP32-C2、ESP32-S3、ESP32-H2见示例 README 顶部的支持列表。ANS 的 GATT 数据模型服务与特征值 UUIDANS 的服务 UUID 为0x1811其下共 5 个特征值全部定义在 esp_ans.h特征值名称UUID属性见 esp_ans.c 注册表说明Supported New Alert Category0x2A47READ支持的新警报分类位图New Alert0x2A46NOTIFY新警报通知分类 ID 计数 文本Supported Unread Alert Category0x2A48READ支持的未读警报分类位图Unread Alert Status0x2A45NOTIFY未读警报状态通知分类 ID 计数Alert Notification Control Point0x2A44WRITE控制点启用/禁用分类、立即通知等命令这 5 个特征值在 esp_ans.c 的注册表 中一一列出每个条目包含特征名、UUID 类型16 位、访问属性标志与对应的读写回调sup_new_alert_catREAD→esp_ans_sup_new_alert_cat_cbnew_alertNOTIFY→esp_ans_new_alert_cbsup_unr_alert_catREAD→esp_ans_sup_unr_alert_cat_cbunr_alert_statNOTIFY→esp_ans_unr_alert_stat_cbalert_notify_ctrlWRITE→esp_ans_alert_notify_ctrl_cb警报分类CategoryANS 使用 8 个标准分类来区分不同类型的警报源码中用位掩码Bit Mask和分类 ID 两种形式同时给出esp_ans.h分类 ID位掩码含义00x01Simple Alert简单警报10x02Email邮件20x04News新闻30x08Call来电40x10Missed Call未接来电50x20SMS短信60x40Voice Mail语音邮件70x80Schedule日程分类总数为BLE_ANS_CAT_NUM8。源码注释指出还剩余 2 个可选分类规范中定义共 10 类当前实现暂未加入使用时可留意这一限制。Supported New Alert Category与Supported Unread Alert Category两个特征值的值就是这些位掩码的按位或某一位为 1 表示该分类被启用客户端可以通过读这两个特征值了解服务端当前支持哪些分类。控制点命令Control Point客户端通过向Alert Notification Control Point0x2A44写入两字节数据来配置服务端命令 ID 定义于 esp_ans.h命令 ID宏名称作用0BLE_ANS_CMD_EN_NEW_ALERT_CAT启用新警报分类1BLE_ANS_CMD_EN_UNR_ALERT_CAT启用未读警报分类2BLE_ANS_CMD_DIS_NEW_ALERT_CAT禁用新警报分类3BLE_ANS_CMD_DIS_UNR_ALERT_CAT禁用未读警报分类4BLE_ANS_CMD_NOT_NEW_ALERT_IMMEDIATE立即发送新警报通知5BLE_ANS_CMD_NOT_UNR_ALERT_IMMEDIATE立即发送未读警报通知控制点的处理逻辑在 esp_ans_alert_notify_ctrl_cb 中实现首字节为命令 ID次字节为分类 ID。分类 ID 会被转换为位掩码1 cat_id特殊值0xff表示所有分类——此时启用/禁用命令会直接作用于整个位图而两个立即通知命令则会遍历所有已启用分类逐个发送通知。命令 ID 无效时返回ESP_ERR_INVALID_ARG并设置 ATT 状态为ESP_IOT_ATT_INTERNAL_ERROR。通知数据格式New Alert 通知0x2A46长度为2 文本长度第 1 字节为分类 ID第 2 字节为新警报计数其后为最长 18 字节BLE_ANS_INFO_STR_MAX_LEN的文本信息。总上限BLE_ANS_NEW_ALERT_MAX_LEN 20见 esp_ans.h。发送前实现会先清空缓冲区避免残留旧文本见 ble_ans_new_alert_notify。Unread Alert Status 通知0x2A45固定 2 字节第 1 字节为分类 ID第 2 字节为未读计数见 ble_ans_unr_alert_notify。API 速查四个核心接口ANS 组件的公开 API 全部声明在 esp_ans.h 中共 5 个函数esp_ble_ans_init()初始化并注册 ANS 服务到 GATT 数据库。实现上仅一行esp_ble_conn_add_svc(svc)esp_ans.c把上文的服务注册表交给连接管理组件。成功返回ESP_OK参数错误返回ESP_ERR_INVALID_ARG其他错误返回ESP_FAIL。esp_ble_ans_get_new_alert(uint8_t cat_id, uint8_t *cat_val)读取/查询支持的新警报分类状态。cat_id传0xFF时读出整个位图值传具体分类 ID 时返回该分类是启用1还是禁用0。分类 ID 非法时返回ESP_ERR_INVALID_ARG。esp_ble_ans_set_new_alert(uint8_t cat_id, const char *cat_info)向指定分类发送新警报通知cat_info为随通知携带的文本如来电显示。实现会先检查该分类是否已启用未启用则返回ESP_ERR_INVALID_ARG然后把该分类计数加 1再通过ble_ans_new_alert_notify发起通知esp_ans.c。esp_ble_ans_get_unread_alert(uint8_t cat_id, uint8_t *cat_val)读取/查询支持的未读警报分类状态用法与esp_ble_ans_get_new_alert一致。esp_ble_ans_set_unread_alert(uint8_t cat_id)把指定分类的未读计数加 1 并发送未读警报状态通知同样要求该分类已启用否则返回ESP_ERR_INVALID_ARGesp_ans.c。关于cat_id传0xFF的语义头文件在esp_ble_ans_get_new_alert/esp_ble_ans_get_unread_alert的注释中作了明确说明0xFF表示读取整个支持的分类位图其他值表示查询该分类是否启用。与 ble_conn_mgr 的集成原理ANS 组件不直接操作 NimBLE/GAP 事件而是完全依托 ble_conn_mgr 提供的抽象层服务注册通过esp_ble_conn_add_svc(const esp_ble_conn_svc_t *svc)把esp_ble_conn_svc_t结构UUID 特征值回调表注册进连接管理组件声明见 esp_ble_conn_mgr.h。通知发送ble_ans_new_alert_notify与ble_ans_unr_alert_notify最终都调用esp_ble_conn_notify(const esp_ble_conn_data_t *inbuff)esp_ble_conn_mgr.h把esp_ble_conn_data_t16 位 UUID 数据缓冲 长度交给底层栈广播出去。特征值回调每个特征的读写都对应一个esp_ble_conn_cb_t回调签名见 esp_ble_conn_mgr.h回调通过inbuf是否为 NULL 区分读/写读操作inbuf为 NULL回调负责分配outbuf并返回数据写操作inbuf携带写入内容。回调返回后outbuf由连接管理组件负责释放因此实现中使用calloc分配。所有回调统一通过*att_status输出 ATT 状态码如ESP_IOT_ATT_SUCCESS、ESP_IOT_ATT_INTERNAL_ERROR、ESP_IOT_ATT_INSUF_RESOURCE定义见 esp_ble_conn_mgr.h。从源码结构看esp_ans.c内部用 4 个静态全局变量维护服务状态两个分类位图ble_ans_new_alert_cat/ble_ans_unr_alert_cat两组每分类计数ble_ans_new_alert_cnt/ble_ans_unr_alert_cnt以及三个特征值缓冲区。应用层调用esp_ble_ans_set_new_alert等 API 时正是通过修改这些内部状态后再触发通知实现计数 通知的一体化语义。示例实战构建、烧录与ans命令调试构建与烧录示例位于 examples/bluetooth/ble_services/ble_ans构建前先用idf.py set-target指定芯片示例 README 支持的 ESP32 / ESP32-C3 / ESP32-C2 / ESP32-S3 / ESP32-H2idf.py set-target esp32c3然后进入示例目录打开配置菜单idf.py menuconfig在Example Configuration菜单中对应 Kconfig.projbuild可配置两个选项EXAMPLE_BLE_ADV_NAME广播中的设备名默认BLE_ANSEXAMPLE_BLE_SUB_ADV后续广播数据默认SUB_ADV。接着编译、烧录并打开串口监视器idf.py -p PORT flash monitor退出监视器按Ctrl-]。硬件上仅需一块开发板加一根 USB 线供电 烧录。测试客户端可用任意 BLE 扫描/调试 App 连接设备订阅相关特征即可收到通知。主程序初始化流程app_main.c 展示了完整的初始化顺序初始化 NVS必要时先擦除esp_event_loop_create_default()创建默认事件循环并注册BLE_CONN_MGR_EVENTS上的连接事件处理器示例中打印ESP_BLE_CONN_EVENT_CONNECTED/ESP_BLE_CONN_EVENT_DISCONNECTEDapp_console_init()初始化交互式控制台app_ans_register()注册ans命令以esp_ble_conn_config_t配置设备名取CONFIG_EXAMPLE_BLE_ADV_NAME广播数据取CONFIG_EXAMPLE_BLE_SUB_ADV调用esp_ble_conn_init(config)调用esp_ble_ans_init()注册 ANS 服务esp_ble_conn_start()启动 BLE 会话并进入广播若失败则依次stop、deinit并注销事件处理器。ans命令用法示例通过串口控制台注册了ans命令实现见 app_ans.c用于模拟 ANS 服务端行为参数如下ans [-t 01~04] [-c 00~07] [-o 00~01]-t/--type操作类型01查询支持的新警报分类、02发送新警报、03查询支持的未读警报分类、04发送未读警报-c/--category分类 ID取值00~07-o/--option1启用、0禁用对发送类操作而言传1时携带预设文本传0时不带文本。app_ans_runapp_ans.c把命令参数映射到上述 ANS APItype1调esp_ble_ans_get_new_alert、type2调esp_ble_ans_set_new_alertoption非 0 时附带对应分类的文本如Call、SMS、Email等预设字符串、type3调esp_ble_ans_get_unread_alert、type4调esp_ble_ans_set_unread_alert。示例 README 给出的一组典型命令序列读取支持的新警报分类ans -t 1 -c 1 -o 0启用指定分类的新警报通知ans -t 2 -c 1 -o 0禁用指定分类的新警报通知ans -t 2 -c 1 -o 1读取支持的未读警报分类ans -t 3 -c 1 -o 0启用指定分类的未读警报通知ans -t 4 -c 1 -o 0禁用指定分类的未读警报通知ans -t 4 -c 1 -o 1运行输出解读以 ESP32-C3 为例连接成功并执行命令后串口输出大致如下节选自示例 README 的 Example Output 章节I (437) blecm_nimble: BLE Host Task Started I (457) NimBLE: GAP procedure initiated: stop advertising. I (467) NimBLE: GAP procedure initiated: advertise; esp32c3 ans -t 1 -c 3 -o 0 I (15227) app_ans: Category 3 of Supported New Alert Category is Disabled esp32c3 ans -t 2 -c 3 -o 0 I (50387) NimBLE: GATT procedure initiated: notify; I (50387) NimBLE: att_handle15 I (50387) app_ans: Notify New Alert of Supported Category ID 3日志中值得关注的点Write attempt for uuid 0x2a44表示客户端向控制点写入了命令启用分类等随后服务端才会允许对应分类发送通知GATT procedure initiated: notify与att_handle...来自 NimBLE 协议栈表明一次真正的 GATT 通知已发出app_ans: Category N ... is Enabled/Disabled与app_ans: Notify New Alert of Supported Category ID N来自示例应用层反映ans命令的执行结果。注意只有先通过控制点或等价途径启用某分类esp_ble_ans_set_new_alert/esp_ble_ans_set_unread_alert才会真正生效——源码中两者都会先检查cat_bit_mask ble_ans_new_alert_cat/ble_ans_unr_alert_cat是否非零分类未启用时直接返回ESP_ERR_INVALID_ARG。接入自有应用的集成步骤要在自己的 BLE 外设工程中启用 ANS可按以下步骤添加组件依赖把components/bluetooth/ble_services/ans与components/bluetooth/ble_conn_mgr加入工程的组件搜索路径示例通过 idf_component.yml 管理依赖可参考。开启配置项在 menuconfig 中使能BLE_ANS见 Kconfig.in。初始化在esp_ble_conn_init(config)之后调用esp_ble_ans_init()然后esp_ble_conn_start()启动广播。上报警报应用侧在事件发生时调用esp_ble_ans_set_new_alert(cat_id, info_text)或esp_ble_ans_set_unread_alert(cat_id)即可触发对应分类的 GATT 通知用esp_ble_ans_get_new_alert/esp_ble_ans_get_unread_alert查询分类启用状态。监听客户端控制客户端通过0x2A44控制点写入的启用/禁用/立即通知命令由esp_ans_alert_notify_ctrl_cb自动处理应用无需额外介入。小结警报通知服务ANS为 BLE 外设提供了一套标准化的警报发布机制覆盖分类管理、计数统计、文本附注与控制点交互。esp-iot-solution 的 ans 组件 通过 ble_conn_mgr 以回调注册表的方式完成 GATT 服务注册与通知发送接口精简、耦合度低ble_ans 示例 则提供了完整的可运行代码与串口调试手段是理解 ANS 协议细节和快速起步的最佳入口。无论是来电/短信转发、通知中心同步还是其他依赖 BLE 的告警场景都可以基于这套组件快速落地。【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考