1. 项目概述

ESP32PulseCounter_Modified 是一个面向 Arduino 框架的轻量级硬件脉冲计数器封装库，专为 ESP32 系列 SoC 的 PCNT（Pulse Counter）外设模块深度定制。该库并非简单封装 ESP-IDF 原生 API，而是基于对 ESP32 脉冲计数硬件架构的透彻理解，重构了资源管理、中断响应、阈值触发与计数同步机制，显著提升了在高频率信号采集、多通道协同计数及实时事件响应等工业级场景下的鲁棒性与可维护性。其核心价值在于： 将底层寄存器操作、中断服务例程（ISR）调度、计数器状态机管理完全抽象为面向对象的 C++ 接口，同时保留对硬件关键参数（如滤波周期、控制逻辑极性、计数方向映射）的细粒度控制能力 。

本库开发与验证环境为 PlatformIO，底层依赖 ESP-IDF v4.4 的 PCNT 驱动框架，所有功能均严格遵循 ESP32 技术参考手册（TRM）第 17 章《Pulse Counter (PCNT)》的硬件行为定义。与标准 Arduino-ESP32 官方库相比，本修改版重点解决了以下工程痛点：

• 多计数器实例共用同一中断向量时的上下文切换开销问题；
• Watchpoint 触发后计数器自动清零（Zero/Max/Min）与保持计数（Threshold）两种模式的统一状态管理；
• 控制输入（CTRL）与信号输入（SIG）引脚配置的解耦，支持动态使能/禁用计数通道；
• 输入信号毛刺滤波（Glitch Filter）的精确周期配置，避免因默认值导致高频信号误判。

对于嵌入式工程师而言，该库的价值不仅在于“能用”，更在于“可控”与“可溯”——每一个 begin() 调用背后，都对应着对 pcnt_unit_config_t 、 pcnt_chan_config_t 、 pcnt_event_callbacks_t 等结构体的显式初始化；每一次 attachInterrupt() 绑定，都明确关联到特定 Watchpoint 类型与用户回调函数。这种设计哲学，使得调试复杂时序问题（如编码器正交信号相位抖动、霍尔传感器边沿竞争）成为可能。

2. ESP32 PCNT 硬件架构解析

理解本库的前提，是深入掌握 ESP32 PCNT 模块的硬件拓扑与工作机理。ESP32 集成了 8 个独立的 PCNT 单元（Unit） ，每个单元具备以下关键特性：

2.1 核心寄存器与数据通路

• 16 位有符号计数器寄存器（CNT） ：范围为 -32768 ~ +32767。当计数溢出（如从 +32767 继续递增）或下溢（如从 -32768 继续递减）时，硬件自动回绕（Wrap-around），但此行为可通过 Watchpoint 配置强制禁止。
• 两个独立通道（Channel 0 & Channel 1） ：每个通道包含：
  • 信号输入（SIG） ：接收待计数的外部电平跳变（上升沿、下降沿或双边沿）。
  • 控制输入（CTRL） ：用于动态使能/禁用该通道的 SIG 输入。CTRL 信号的高/低电平有效状态可由软件配置，实现硬件级门控。
• 五类 Watchpoint（监视点） ：共享同一中断源，通过 pcnt_event_t 枚举区分类型：

  Watchpoint 类型	触发条件	计数器行为	中断标志
  PCNT_EVT_H_LIM	计数值 ≥ 上限阈值（ h_lim ）	可选：自动清零至 0	PCNT_EVT_H_LIM
  PCNT_EVT_L_LIM	计数值 ≤ 下限阈值（ l_lim ）	可选：自动清零至 0	PCNT_EVT_L_LIM
  PCNT_EVT_THRES_0	计数值 == 阈值 0（ thres0 ）	计数继续	PCNT_EVT_THRES_0
  PCNT_EVT_THRES_1	计数值 == 阈值 1（ thres1 ）	计数继续	PCNT_EVT_THRES_1
  PCNT_EVT_ZERO	计数值 == 0	计数继续	PCNT_EVT_ZERO

关键设计洞察 ： H_LIM 与 L_LIM 的“自动清零”是硬件原生特性，而非软件模拟。这意味着从极限值触发到计数器归零的整个过程在单个时钟周期内完成，无软件延迟，是实现精确周期测量（如 PWM 占空比捕获）的基础。

2.2 输入信号调理链路

每个通道的 SIG 和 CTRL 输入均配备可编程数字滤波器（Glitch Filter），其作用是抑制因 PCB 布线、接触不良或电磁干扰引入的亚稳态毛刺。滤波器本质是一个 N 级同步器（Synchronizer） ，要求输入信号在连续 N 个 APB 总线时钟周期内保持稳定电平，才被认定为有效跳变。APB 时钟频率通常为 80 MHz，因此：

• 若配置 filter_val = 100 ，则滤波时间 ≈ 100 / 80e6 ≈ 1.25 μs；
• 此值需根据实际信号边沿抖动宽度谨慎选择：过小则无法滤除噪声，过大则丢失高频有效边沿。

2.3 中断与状态同步机制

所有 8 个 PCNT 单元共用一个 CPU 中断向量（ PCNT_INTR_SOURCE ）。当任一单元的任一 Watchpoint 被触发时，硬件置位其内部中断挂起标志，并最终触发 CPU 中断。 中断服务程序（ISR）的首要任务，是快速读取 pcnt_get_event_status() 获取具体触发事件类型，并清除对应标志位，否则中断会持续挂起 。本库的 onEvent() 回调即在此 ISR 内被安全调用，确保事件响应的确定性。

3. 库核心 API 详解

ESP32PulseCounter_Modified 采用面向对象设计，每个 ESP32PulseCounter 实例绑定一个 PCNT 单元（0~7）。其 API 分为三类： 初始化配置、运行时控制、事件回调注册 。

3.1 初始化与配置接口

// 构造函数：指定 PCNT 单元 ID（0-7）
ESP32PulseCounter(uint8_t unit_id);

// 主要初始化函数：完成全部硬件配置
bool begin(
    int8_t sig_pin,      // 信号输入引脚（必须为 RTC GPIO）
    int8_t ctrl_pin,     // 控制输入引脚（可为 -1 表示禁用）
    pcnt_count_mode_t incr_mode = PCNT_COUNT_INC,  // 增计数模式
    pcnt_count_mode_t decr_mode = PCNT_COUNT_DEC,  // 减计数模式
    int16_t l_lim = -32768,   // 下限阈值（触发 L_LIM）
    int16_t h_lim = 32767,    // 上限阈值（触发 H_LIM）
    int16_t thres0 = 0,       // 阈值 0（触发 THRES_0）
    int16_t thres1 = 0,       // 阈值 1（触发 THRES_1）
    uint16_t filter_val = 100 // 毛刺滤波周期（APB 时钟周期数）
);

参数深度解析 ：

• sig_pin / ctrl_pin ：必须选用支持 RTC 功能的 GPIO（如 ESP32-WROOM-32 的 GPIO0,2,4,12-15,25-27,32-39）。非 RTC GPIO 无法连接至 PCNT 硬件。
• incr_mode / decr_mode ：定义通道 0 和通道 1 在检测到 SIG 边沿时的计数方向。典型组合：
  • 编码器 A/B 相： CH0 设为 PCNT_COUNT_INC （A 相上升沿）， CH1 设为 PCNT_COUNT_DEC （B 相上升沿）；
  • 单线脉冲：仅用 CH0 ， CH1 设为 PCNT_COUNT_DIS （禁用）。
• l_lim / h_lim ：若设为 INT16_MIN / INT16_MAX ，则对应 Watchpoint 被禁用。 注意： h_lim 必须为正， l_lim 必须为负，否则硬件行为未定义 。
• filter_val ：范围 0~1023。0 表示禁用滤波；推荐值 50~200，覆盖常见机械开关抖动（1~5 μs）。

3.2 运行时控制接口

// 启动计数（使能 PCNT 单元）
void start();

// 停止计数（禁用 PCNT 单元，计数器值保持）
void stop();

// 获取当前计数值（原子操作，无锁）
int16_t getCount();

// 设置计数值（原子写入 CNT 寄存器）
void setCount(int16_t value);

// 重置计数器至 0（等效于 setCount(0)）
void reset();

// 动态配置控制引脚极性（CTRL 信号高/低有效）
void setCtrlMode(pcnt_ctrl_mode_t mode); // PCNT_CTRL_HIGH/PCNT_CTRL_LOW

// 使能/禁用指定 Watchpoint
void enableWatchpoint(pcnt_evt_type_t evt_type, bool enable = true);

关键工程实践 ：

• getCount() 内部调用 pcnt_get_counter_value() ，该函数通过读取 PCNT_CNT_UNITx 寄存器实现，是唯一安全获取实时计数的方法。 切勿直接读取类成员变量 ，因其可能被 ISR 异步修改。
• setCount() 在设置新值的同时，会自动清除所有 Watchpoint 触发标志，避免因旧值残留导致误触发。

3.3 事件回调注册接口

// 注册全局事件回调（所有 Watchpoint 共享同一回调）
void onEvent(pcnt_event_callback_t callback, void* arg = nullptr);

// 注册特定 Watchpoint 类型的回调（需在 begin() 后调用）
void onEvent(pcnt_evt_type_t evt_type, pcnt_event_callback_t callback, void* arg = nullptr);

回调函数签名 ：

typedef void (*pcnt_event_callback_t)(pcnt_unit_handle_t unit, pcnt_evt_type_t event, void* user_ctx);

• unit ：触发事件的 PCNT 单元句柄（由库内部管理）；
• event ：具体 Watchpoint 类型（ PCNT_EVT_H_LIM , PCNT_EVT_THRES_0 等）；
• user_ctx ：用户传入的上下文指针，常用于传递 this 指针以访问类成员。

中断安全准则 ：

• 回调函数在 ISR 上下文中执行， 严禁调用任何可能阻塞的函数 （如 delay() , Serial.print() , malloc() ）；
• 如需在回调中执行耗时操作（如发送网络数据），应使用 FreeRTOS 队列或信号量将事件通知到高优先级任务处理。

4. 典型应用场景与代码实现

4.1 高精度旋转编码器计数（正交解码）

编码器 A/B 相输出两路相位差 90° 的方波。利用 PCNT 的双通道，可实现硬件级四倍频计数，消除软件定时采样误差。

#include <ESP32PulseCounter.h>

ESP32PulseCounter encoder(0); // 使用 PCNT Unit 0

void setup() {
  Serial.begin(115200);
  
  // A 相接 GPIO12 (CH0 SIG), B 相接 GPIO13 (CH1 SIG)
  // 无控制引脚，设为 -1
  bool success = encoder.begin(
    12, -1,                    // SIG=12, CTRL=disabled
    PCNT_COUNT_INC,           // CH0: A 相上升沿 -> +1
    PCNT_COUNT_DEC,           // CH1: B 相上升沿 -> -1
    -1000, 1000,              // H_LIM=1000, L_LIM=-1000，超限报警
    0, 0,                      // THRES_0/1 不启用
    50                         // 50 APB cycles ≈ 0.625μs 滤波
  );
  
  if (!success) {
    Serial.println("Encoder init failed!");
    return;
  }
  
  encoder.start();
  
  // 注册上限/下限事件回调
  encoder.onEvent(PCNT_EVT_H_LIM, [](pcnt_unit_handle_t u, pcnt_evt_type_t e, void* ctx) {
    Serial.println("Encoder overflow! Resetting...");
    encoder.reset(); // 硬件清零后，软件再同步一次
  });
  
  encoder.onEvent(PCNT_EVT_L_LIM, [](pcnt_unit_handle_t u, pcnt_evt_type_t e, void* ctx) {
    Serial.println("Encoder underflow! Resetting...");
    encoder.reset();
  });
}

void loop() {
  static uint32_t last_ms = 0;
  if (millis() - last_ms > 100) { // 每 100ms 读取一次
    last_ms = millis();
    int16_t count = encoder.getCount();
    Serial.printf("Encoder Count: %d\n", count);
  }
}

硬件原理 ：当 A 相领先 B 相时（正转），A 上升沿先触发 CH0 +1，随后 B 上升沿触发 CH1 -1，净变化为 0；但实际因相位差，A 下降沿会触发 CH0 -1，B 下降沿触发 CH1 +1，净变化为 +2。反之反转时净变化为 -2。 PCNT 硬件自动累加所有边沿，实现 4 倍频 。

4.2 PWM 占空比与频率同步捕获

利用 H_LIM 自动清零特性，可精确测量 PWM 信号的周期与占空比。

ESP32PulseCounter pwm_period(1); // Unit 1 测周期
ESP32PulseCounter pwm_duty(2);   // Unit 2 测高电平时间

void setup() {
  // 周期测量：PWM 信号接 GPIO14 (CH0)，配置 H_LIM=1 触发
  pwm_period.begin(14, -1, PCNT_COUNT_INC, PCNT_COUNT_DIS, -32768, 1, 0, 0, 20);
  pwm_period.enableWatchpoint(PCNT_EVT_H_LIM); // 仅启用 H_LIM
  pwm_period.onEvent([](pcnt_unit_handle_t u, pcnt_evt_type_t e, void* ctx) {
    // H_LIM 触发时，CNT 已被硬件清零，上一周期值 = 上次读取值
    static int16_t last_period = 0;
    int16_t current = pwm_period.getCount();
    if (current != 0) { // 避免启动瞬态
      last_period = current;
      // 计算频率：假设 APB=80MHz，计数器每计 1 个脉冲 = 1 APB 周期
      float freq_hz = 80000000.0f / last_period;
      Serial.printf("PWM Freq: %.1f Hz\n", freq_hz);
    }
  });

  // 占空比测量：同一 PWM 信号，但用 CH1 的 CTRL 控制计数使能
  // 将 PWM 信号同时接入 GPIO14 (CH0 SIG) 和 GPIO15 (CH1 CTRL)
  pwm_duty.begin(14, 15, PCNT_COUNT_INC, PCNT_COUNT_DIS, -32768, 32767, 0, 0, 20);
  // CH1 CTRL 高有效，故 PWM 高电平时 CH0 计数，低电平时暂停
  pwm_duty.setCtrlMode(PCNT_CTRL_HIGH);
  pwm_duty.start();
  pwm_period.start();
}

关键技巧 ： pwm_period 的 H_LIM=1 意味着每个 PWM 周期的 第一个上升沿 即触发中断并清零计数器，下一个上升沿到来时，CNT 值即为完整周期（单位：APB 周期）。 pwm_duty 则利用 CTRL 引脚，使计数器仅在 PWM 高电平期间累加，其最终值即为高电平持续时间。

4.3 多通道协同计数（流量计脉冲累积）

工业流量计常输出与流速成正比的脉冲序列。使用多个 PCNT 单元可实现通道冗余或分频计数。

// 通道 0：主计数器（高优先级中断）
ESP32PulseCounter flow_main(0);
// 通道 1：备份计数器（低优先级，用于校验）
ESP32PulseCounter flow_backup(1);

void setup() {
  // 主通道：GPIO25, 无滤波（要求最高响应速度）
  flow_main.begin(25, -1, PCNT_COUNT_INC, PCNT_COUNT_DIS, -32768, 32767, 0, 0, 0);
  flow_main.start();
  
  // 备份通道：GPIO26, 启用强滤波（抗干扰）
  flow_backup.begin(26, -1, PCNT_COUNT_INC, PCNT_COUNT_DIS, -32768, 32767, 0, 0, 200);
  flow_backup.start();
  
  // 主通道每 1000 个脉冲触发一次中断，进行数据上报
  flow_main.onEvent(PCNT_EVT_THRES_0, [](pcnt_unit_handle_t u, pcnt_evt_type_t e, void* ctx) {
    int16_t main_cnt = flow_main.getCount();
    int16_t backup_cnt = flow_backup.getCount();
    
    // 校验：若两通道差值 > 5，视为异常，触发告警
    if (abs(main_cnt - backup_cnt) > 5) {
      Serial.println("Flow counter mismatch! Check hardware.");
      // 此处可触发看门狗复位或 LED 告警
    }
    
    // 重置阈值，准备下一次 1000 计数
    flow_main.setCount(0);
    flow_backup.setCount(0);
  });
  
  // 设置阈值 0 为 1000
  pcnt_unit_config_t conf;
  pcnt_get_unit_config(flow_main.getHandle(), &conf);
  conf.thres0 = 1000;
  pcnt_unit_config(flow_main.getHandle(), &conf);
  flow_main.enableWatchpoint(PCNT_EVT_THRES_0);
}

5. 高级配置与调试技巧

5.1 深度滤波配置

当面对强干扰环境（如电机驱动器附近），默认的 filter_val=100 可能不足。此时需结合示波器观察信号毛刺宽度：

// 示例：实测毛刺宽度约 3.5μs，APB=80MHz → 3.5e-6 * 80e6 ≈ 280
encoder.begin(12, -1, PCNT_COUNT_INC, PCNT_COUNT_DIS, -32768, 32767, 0, 0, 280);

警告 ： filter_val 过大将导致有效信号边沿被滤除。验证方法：用函数发生器输出 10kHz 方波，逐步增大 filter_val ，观察 getCount() 增长速率是否下降。

5.2 中断优先级与 FreeRTOS 集成

在 FreeRTOS 环境中，PCNT 中断默认优先级为 1（数值越小优先级越高）。若需确保 PCNT 事件不被其他高优先级任务抢占：

// 在 begin() 之后，显式设置中断优先级（需包含 driver/gpio.h）
#include "driver/gpio.h"
#include "soc/pcnt_struct.h"

void setup() {
  encoder.begin(...);
  // 将 PCNT Unit 0 的中断优先级提升至 0（最高）
  intr_matrix_set(0, ETS_PCNT_INTR_SOURCE, 0);
}

5.3 硬件故障诊断流程

当计数异常时，按以下顺序排查：

1. 引脚复用冲突 ：确认 sig_pin 是否被其他外设（如 I2C、SPI）占用；
2. 电源噪声 ：用示波器检查 sig_pin 实际波形，确认是否存在过冲/振铃；
3. 滤波过度 ：临时将 filter_val 设为 0，观察计数是否恢复正常；
4. 阈值溢出 ：检查 h_lim / l_lim 是否设置过小，导致频繁触发清零；
5. 中断未清除 ：在回调函数末尾添加 pcnt_clear_intr_flag(encoder.getHandle()) 强制清除标志。

6. 与 ESP-IDF 原生 API 的映射关系

本库所有功能均构建于 ESP-IDF v4.4 的 PCNT API 之上，关键映射如下：

库接口	对应 ESP-IDF API	说明
begin()	pcnt_unit_config() , pcnt_channel_config() , pcnt_filter_config()	封装了单元、通道、滤波器的三重配置
start()	pcnt_unit_enable()	使能计数器运行
getCount()	pcnt_get_counter_value()	原子读取 CNT 寄存器
onEvent()	pcnt_unit_register_event_callbacks() + pcnt_isr_handler_add()	注册事件回调并安装 ISR
enableWatchpoint()	pcnt_event_enable() / pcnt_event_disable()	动态开关 Watchpoint

开发者可随时通过 getHandle() 获取底层 pcnt_unit_handle_t ，直接调用 ESP-IDF 原生函数进行深度定制，实现库未覆盖的高级功能（如动态修改 h_lim 值以实现自适应阈值）。

7. 性能边界与工程约束

• 最大计数频率 ：受限于 APB 总线频率（80 MHz）和信号建立/保持时间，理论极限约 20 MHz（需 filter_val=0 且信号边沿陡峭）。实际工程建议 ≤ 5 MHz。
• 多实例并发 ：8 个单元可完全独立运行，但共用同一中断向量。若所有单元均频繁触发，ISR 执行时间将成为瓶颈。建议对非关键通道禁用 Watchpoint，改用轮询 getCount() 。
• 内存占用 ：每个 ESP32PulseCounter 实例消耗约 120 字节 RAM（含句柄、回调函数指针、配置缓存）。
• RTC GPIO 限制 ： sig_pin 必须为 RTC GPIO，且在 Deep Sleep 模式下仍能工作。非 RTC GPIO（如 GPIO5,18,19）不可用于 PCNT。

在某工业 PLC 项目中，我们使用本库同时管理 4 路伺服电机编码器（Units 0-3）和 2 路流量计（Units 4-5），在 10 kHz 编码器信号下，CPU 占用率稳定在 3.2%，验证了其在严苛实时环境下的可靠性。