esp-iot-solution 过零检测组件 zero_detection 完全指南事件机制、驱动模式与版本演进解析【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution过零检测Zero Cross Detection是交流电控制类应用继电器通断、调光、电机换相中的关键环节通过捕捉交流信号的过零点可以让开关动作恰好发生在电压为零的时刻从而减小电弧、延长器件寿命。Espressif 的 esp-iot-solution 仓库提供了名为zero_detection的官方组件它不只做简单的边沿计数而是能判断信号的有效/无效/超频/丢失并以事件回调的方式及时上报。本文以该组件的 CHANGELOG 功能演进为主线结合 组件源码、公开 API 头文件 与 完整示例工程带你掌握 zero_detection 的配置、事件体系、底层实现原理与版本迭代脉络。一、组件定位不只是一次中断而是一套信号质量评估体系zero_detection组件组件目录 components/zero_detection的设计目标是分析过零信号本身通过考察过零信号的周期period与触发边沿triggering edge判定信号的有效、无效、超出预期频率范围、以及是否存在信号丢失并把判定结果以**事件event**形式返回满足用户对信号处理的及时性需求见 组件 README。从 CHANGELOG 的 v0.0.12023-11-28First release version可以看到该组件的核心能力从诞生之初就是Support zero_cross_detection。其价值不在于检测到一次边沿而在于能区分信号质量有效/无效并支持防抖计数连续 N 次才判定有效/无效能识别信号频率是否超出设定范围如电网 50Hz ± 容差能检测信号丢失掉电、断线支持两种信号形态方波SQUARE_WAVE与脉冲PULSE_WAVE支持两种采集驱动MCPWM 捕获与GPIO 中断。二、快速上手创建对象、注册回调、接收事件组件以对象handle为操作单元。使用流程非常精简对应 API 头文件用默认宏ZERO_DETECTION_INIT_CONFIG_DEFAULT()初始化配置结构体调用zero_detect_create()创建过零检测对象调用zero_detect_register_cb()注册用户中断回调函数在回调中按事件类型处理业务。需要特别注意的是注册的回调函数必须添加IRAM_ATTR前缀组件 README 明确要求因为该回调会直接在中断上下文中被调用。#include zero_detection.h // 1. 默认配置 zero_detect_config_t config ZERO_DETECTION_INIT_CONFIG_DEFAULT(); config.capture_pin 2; config.freq_range_max_hz 65; config.freq_range_min_hz 45; config.valid_times 6; config.zero_signal_type SQUARE_WAVE; config.zero_driver_type GPIO_TYPE; // 或 MCPWM_TYPE芯片支持时 // 2. 创建对象 zero_detect_handle_t zcd zero_detect_create(config); // 3. 注册回调必须 IRAM_ATTR static void IRAM_ATTR zero_detection_event_cb(zero_detect_event_t evt, zero_detect_cb_param_t *param, void *usr_data) { switch (evt) { case SIGNAL_VALID: /* 信号有效 */ break; case SIGNAL_INVALID: /* 信号无效 */ break; case SIGNAL_FREQ_OUT_OF_RANGE: /* 频率超范围 */ break; case SIGNAL_LOST: /* 信号丢失 */ break; case SIGNAL_RISING_EDGE: /* 上升沿 */ break; case SIGNAL_FALLING_EDGE: /* 下降沿 */ break; default: break; } } zero_detect_register_cb(zcd, zero_detection_event_cb, NULL);2.1 配置结构体逐字段说明zero_detect_config_t的全部字段及其语义默认值见 头文件 中的ZERO_DETECTION_INIT_CONFIG_DEFAULT宏字段类型默认值说明capture_pinint32_t2过零信号捕获 GPIOvalid_timesuint16_t6判定信号有效所需的最少连续次数防抖invalid_timesuint16_t5判定信号无效所需的最少连续次数防抖signal_lost_time_usuint64_t100000判定信号丢失所需的最短持续时间微秒zero_signal_type枚举SQUARE_WAVE过零信号类型方波/脉冲zero_driver_type枚举GPIO_TYPE驱动类型GPIO 中断/MCPWM 捕获freq_range_max_hzdouble65判定有效信号的频率上限freq_range_min_hzdouble45判定有效信号的频率下限默认配置 45~65Hz 恰好覆盖 50/60Hz 两种工频电网场景valid_times6、invalid_times5提供了基本的连续判定防抖。参数防御从 zero_detection.c 的zero_detect_create()实现看组件对非法输入做了兜底——freq_range_max_hz/freq_range_min_hz为负数时回退到默认值 65/45capture_pin不满足GPIO_IS_VALID_GPIO时回退到 GPIO2。此外频率参数在内部被换算成周期微秒值存储zcd-freq_range_max_us 1000000 / config-freq_range_min_hz; // 频率下限 - 周期上限 zcd-freq_range_min_us 1000000 / config-freq_range_max_hz; // 频率上限 - 周期下限也就是说内部判定基于周期而非频率频率与周期互为倒数边界条件被精确映射。2.2 六个事件与回调参数联合体组件将判定结果封装为 6 种事件枚举zero_detect_event_t见 头文件事件触发条件SIGNAL_FREQ_OUT_OF_RANGE当前信号频率超出设定范围SIGNAL_VALID频率在范围内且连续出现次数达到valid_timesSIGNAL_INVALID频率超出范围且连续出现次数达到invalid_timesSIGNAL_LOST在signal_lost_time_us时间内未收到任何信号SIGNAL_RISING_EDGE信号上升沿SIGNAL_FALLING_EDGE信号下降沿回调参数是一个联合体zero_detect_cb_param_t按事件类型携带不同数据signal_freq_event_datacap_edge触发边沿、full_cycle_us当前信号周期微秒signal_valid_event_datacap_edge、full_cycle_us、valid_count有效计数signal_invalid_event_datacap_edge、full_cycle_us、invalid_count无效计数signal_rising_edge_event_data/signal_falling_edge_event_datavalid_count、invalid_count、full_cycle_us。边缘事件RISING/FALLING每来一个边沿就上报一次适合做需要精确过零时刻的开关动作而SIGNAL_VALID/SIGNAL_INVALID是质量结论带有计数防抖。三、底层原理双驱动模式与两种信号的周期计算组件的中枢是位于 zero_detection.c 的中断处理函数zero_cross_handle_interrupt()IRAM_ATTR。无论是 GPIO 中断还是 MCPWM 捕获回调最终都会汇聚到这个核心函数中处理。信号采集与周期计算的细节随驱动类型、信号类型不同而不同。3.1 GPIO 中断模式zero_detect_gpio_init()将捕获引脚配置为GPIO_INTR_ANYEDGE双边沿触发、输入模式、内部上拉并调用gpio_install_isr_service(ESP_INTR_FLAG_IRAM)安装 ISR 服务。中断触发后zero_detect_gpio_cb()构造一个空的捕获事件结构体并转交核心处理函数核心函数通过gpio_ll_get_level()读取引脚当前电平从而区分上升/下降沿。3.2 MCPWM 捕获模式需芯片支持在支持 MCPWM 的芯片上SOC_MCPWM_SUPPORTED定义时zero_detect_mcpwm_init()会依次完成创建捕获定时器mcpwm_new_capture_timer→ 创建捕获通道mcpwm_new_capture_channel配置为双边沿捕获 内部上拉flags.pos_edgetrue、flags.neg_edgetrue→ 注册on_cap回调 → 使能通道与定时器。MCPWM 硬件捕获带有精确的时间戳能力适合对周期测量精度要求更高的场景。驱动类型由编译期能力决定源码中zero_driver_type_t枚举在SOC_MCPWM_SUPPORTED未定义时只保留GPIO_TYPE且zero_detect_create()会强制回退为 GPIO 模式。3.3 方波与脉冲的周期计算差异这是组件最精巧的部分也是 CHANGELOG 与源码反复强调的两种信号计算方式不同方波SQUARE_WAVE高低电平各占半周期上升沿记录cap_val_begin_of_sample下降沿记录cap_val_end_of_sample两者之差即半周期乘以 2 得到全周期脉冲PULSE_WAVE窄脉冲的上升沿之间间隔才是信号周期因此算法把上一次上升沿时间存为cap_val_begin_of_sample本次上升沿记为cap_val_end_of_sample差值乘 2 得到周期。实现中对应两段逻辑上升沿分支里若zero_signal_type PULSE_WAVE采用相邻上升沿计算下降沿分支则只对方波生效zero_cross_handle_interrupt()中else if (!edge_status)分支内有if (zero_cross_dev-zero_signal_type SQUARE_WAVE)判断。同时频率超范围判定的执行条件也排除了脉冲信号的下降沿情况避免窄脉冲的下降沿造成误判。3.4 有效/无效的连续计数与溢出保护核心函数用两个计数器完成连续判定防抖周期落在[freq_range_min_us, freq_range_max_us]内 →valid_count、invalid_count清零当valid_count valid_times时上报SIGNAL_VALID周期越界 →valid_count清零、invalid_count当invalid_count invalid_times时上报SIGNAL_INVALID并同时上报SIGNAL_FREQ_OUT_OF_RANGE上报前还会检查cap_val_end_of_sample ! 0 cap_val_begin_of_sample ! 0避免在收到首个触发边沿采样值尚未就绪时就误判。其中valid_count采用uint16_t计数并做了防溢出处理当计数达到UINT16_MAX - 1时重置回valid_times这一修复正是 CHANGELOG v0.0.6 的Fix valid_count data overflow。3.5 信号丢失检测掉电保护定时器signal_lost_time_us通过定时器实现每次过零中断都会喂狗——esp_timer_restart()或gptimer_set_raw_count(..., 0)重置计数若在signal_lost_time_us时间内没有任何边沿到达定时器回调zero_source_power_invalid_cb()被触发将zero_source_power_invalid置位、清空周期与计数数据并上报SIGNAL_LOST。开发者可借此实现掉电保护例如断电瞬间立即断开继电器见下文示例。定时器的底层实现可通过 Kconfig 的CONFIG_USE_GPTIMER选项在GPTimer与ESPTimer之间切换默认关闭即使用 esp_timer启用后走gptimer路径配置 1MHz 分辨率、1 tick 1us见zero_detect_gptime_init()。四、CHANGELOG 逐版解读功能演进与修复脉络CHANGELOG 记录了组件从 v0.0.1 到 v0.1.0 的完整演进结合源码可以逐一印证每个版本的实际改动版本日期变更源码印证v0.0.12023-11-28首个发布版本支持过零检测组件基础框架v0.0.22023-12-26新增回调注册函数与获取信号类型函数zero_detect_register_cb()、zero_detect_get_signal_type()见 头文件v0.0.32024-01-03修复 C 编译错误头文件整体包裹extern C { ... }v0.0.42024-01-10新增signal_lost_time参数检测信号丢失修复关闭 Ccache 时丢失采集中断的问题配置结构体的signal_lost_time_us字段、SIGNAL_LOST事件与定时器喂狗机制v0.0.52024-03-12修复函数命名不规范问题当前 API 命名zero_detect_*前缀统一v0.0.62024-09-19修复valid_count数据溢出源码中UINT16_MAX - 1溢出保护逻辑v0.0.72025-01-02新增暂停pause命令zero_detect_pause()/zero_detect_resume()见 头文件v0.1.02025-02-24依赖的 cmake_utilities 版本更新为*idf_component.yml 中cmake_utilities: *4.1 v0.0.7 的暂停/恢复机制暂停功能的实现非常直观见 zero_detection.c设置is_paused true标志并立即卸载中断——GPIO 模式调用gpio_isr_handler_remove()MCPWM 模式调用mcpwm_capture_channel_disable()resume则反向操作重新挂载中断。核心处理函数入口处也会先检查is_paused直接返回。这为应用提供了临时停检能力例如示例工程中频率持续超范围时暂停检测。示例工程 zero_detect_example_main.c 演示了freq_out_of_range_count 5时暂停、relay_open_count 5时恢复的完整流程。4.2 v0.0.3 的 C 兼容从 API 头文件 可以看到整个声明区被#ifdef __cplusplus extern C { #endif包裹确保组件可被 C 工程直接#include而不会出现符号修饰mangling问题——这正是该版本修复的编译错误。五、状态查询与数据调试 API除事件机制外组件还提供一组轻量查询接口见 头文件zero_detect_get_power_status(handle)返回true表示电源信号源失效掉电标志zero_source_power_invalidzero_detect_singal_invaild_status(handle)返回true表示当前信号处于无效区间zero_detect_get_signal_type(handle)返回当前配置的信号类型SQUARE_WAVE/PULSE_WAVE对应 v0.0.2 新增的获取信号类型能力zero_show_data(handle)在日志中打印最近一次测量的周期与频率Measured Time: %.2fms Hz:%.2f首个边沿到来前会打印Waiting for the next triggering edge方便调试zero_detect_delete(handle)停止并释放定时器、卸载 GPIO ISR / 释放 MCPWM 通道与定时器、释放内存对应 v0.0.4 修复的关闭 Ccache 丢失中断相关问题保证资源可完全回收。六、实战示例过零检测 继电器控制examples/zero_cross_detection 演示了最典型的应用场景分析过零信号并控制继电器实现过零动作、掉电保护、频率异常保护。6.1 硬件连接与工程配置示例工程的 GPIO 规划见 示例 READMEGPIO方向配置CONFIG_ZERO_DETECT_INPUT_GPIO默认 GPIO2输入上拉双边沿中断接入过零信号CONFIG_ZERO_DETECT_OUTPUT_GPIO默认 GPIO5输出控制继电器工程通过 Kconfig.projbuild 提供三个可配置项输入 GPIO、输出 GPIO、信号类型SQUARE_WAVE/PULSE_WAVE使用idf.py menuconfig即可配置。构建与烧录idf.py set-target esp32s3 # 或其他目标芯片 idf.py menuconfig # 配置输入/输出 GPIO 与信号类型 idf.py -p PORT flash monitor6.2 示例中的事件驱动逻辑示例回调 zero_detection_event_cb 展示了过零检测的典型业务编排SIGNAL_FREQ_OUT_OF_RANGE根据cap_edge与relay_out_of_range策略决定继电器动作频率异常时立即断开或维持SIGNAL_VALID信号恢复正常后执行用户挂起的开关命令relay_suspend机制保证继电器只在过零时刻动作SIGNAL_LOST触发掉电保护——若配置了relay_status_after_power_loss立即断开继电器SIGNAL_INVALID信号无效期间按用户策略处理挂起的开关命令。示例中relay_on_off()仅设置目标状态并置relay_suspend true真正的 GPIO 动作发生在下一个有效的过零事件里从机制上保证了零电压切换。主循环每 500ms 调用zero_show_data()打印实时频率并通过zero_detect_get_power_status()监控电源有效性。6.3 预期串口输出示例 README 给出了典型日志片段节选可以看到频率从异常166.67Hz逐步回落到正常工频50Hz的过程中OUT OF RANGE COUNT停止增长、OPEN COUNT变为 1即继电器在信号有效后完成吸合I (5978) zero_detect: Measured Time: 16.00ms Hz:62.50 EVENT: OUT OF RANGE COUNT:1323 OFF COUNT:0 OPEN COUNT:1 I (6978) zero_detect: Measured Time: 18.00ms Hz:55.56 EVENT: OUT OF RANGE COUNT:1323 OFF COUNT:0 OPEN COUNT:1 I (7978) zero_detect: Measured Time: 20.00ms Hz:50.00 EVENT: OUT OF RANGE COUNT:1323 OFF COUNT:0 OPEN COUNT:1七、测试体系如何在 CI 中验证组件组件自带完整的测试工程 components/zero_detection/test_apps基于 Unity 框架覆盖两种信号形态test_zero_deteciotn.c 包含两个用例用 GPIO5 模拟产生 50Hz 方波/脉冲信号vTaskDelay构造周期输入到capture_pin2验证从信号产生到回调触发的事件延迟要求delay_gap 30us并断言不会出现SIGNAL_FREQ_OUT_OF_RANGE、SIGNAL_LOST、SIGNAL_INVALID等误报setUp/tearDown还会检查 8BIT/32BIT 内存泄漏pytest_zero_cross_detection.py 定义了 esp32s3 / esp32c3 双目标、zero_detection环境标签的自动化测试入口。按脚本注释可本地复现先python tools/build_apps.py components/zero_detection/test_apps -t esp32s3构建再pytest components/zero_detection/test_apps --target esp32s3运行。八、如何将组件加入你的工程组件已发布到 Espressif 组件仓库推荐通过组件管理器添加依赖见 组件 READMEidf.py add-dependency espressif/zero_detection*CMake 构建阶段会自动下载。组件 idf_component.yml 声明了约束依赖idf 5.0与cmake_utilitiesv0.1.0 起放开为*并内置了指向本仓库 示例工程 的examples元数据。从 CMakeLists.txt 看组件在 IDF 5.0 及以上版本注册zero_detection.c低版本会直接报错退出。九、版本现状与选型建议截至 CHANGELOG 记录v0.1.02025-02-24组件已经稳定迭代 8 个版本功能闭环完整检测v0.0.1→ 回调与类型查询v0.0.2→ C 兼容v0.0.3→ 信号丢失检测v0.0.4→ API 规范化v0.0.5→ 计数防溢出v0.0.6→ 暂停/恢复v0.0.7→ 依赖管理优化v0.1.0。如果你的产品需要过零时刻精确动作 掉电保护 频率异常保护这类能力照明调光、智能插座、交流电机控制等直接在 esp-iot-solution 中引入zero_detection组件配合 示例工程 的继电器控制骨架即可快速搭建一套可靠、可防抖、可容错的过零检测方案。补充说明本文中关于源码内部行为的描述如周期换算、计数防抖、定时器喂狗、暂停卸载中断等均可从 zero_detection.c 与 API 头文件 直接验证版本与日期信息以 CHANGELOG 为准。【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
