1. 项目概述

iarduino_Encoder_tmr 是一款专为 Arduino 平台设计的高性能旋转编码器驱动库，由俄罗斯 iArduino.ru 团队开发并开源。该库的核心设计目标是 在不占用主处理器资源的前提下，实现对机械式或光电式增量型编码器（Quadrature Encoder）的高精度、抗抖动、零丢脉冲计数 。其技术实现路径与传统轮询或外部中断方案存在本质差异：它 完全绕过 Arduino 标准 attachInterrupt() 机制，转而深度绑定 AVR 微控制器的第二硬件定时器（Timer2） ，通过定时器溢出中断（Timer Overflow Interrupt）周期性采样编码器 A/B 相位信号，并在 ISR 中完成状态机判别与计数更新。

这一设计决策具有明确的工程目的：

• 避免外部中断冲突 ：标准 Arduino UNO/Nano 等基于 ATmega328P 的板卡仅提供 2 个外部中断引脚（INT0/INT1），当系统需同时接入多个编码器、按键、传感器等中断源时，资源迅速枯竭；
• 消除机械抖动（Debouncing）引入的软件开销 ：传统轮询方案需在 loop() 中反复读取引脚电平并执行延时消抖，严重阻塞主程序流；而本库将消抖逻辑内置于定时器 ISR 中，采用“连续 N 次采样一致才确认有效边沿”的策略，既保证可靠性又不牺牲实时性；
• 解耦硬件引脚约束 ：编码器 A/B 信号可连接至 任意数字或模拟引脚（D0–D13 / A0–A5） ，无需强制绑定至特定中断引脚，极大提升硬件布线灵活性；
• 保障计数原子性 ：所有计数操作均在定时器 ISR 内完成，避免主循环中读取计数值时因中断抢占导致的临界区问题，确保 read() 返回值始终为一致快照。

该库适用于对旋转输入精度与响应实时性有严苛要求的嵌入式人机交互场景，例如：

• 工业控制面板中的参数微调旋钮；
• 音频设备（如 DJ 控制器、合成器）的音量/滤波器截止频率调节；
• 3D 打印机/数控机床的手轮（Handwheel）位置反馈；
• 机器人关节角度闭环控制中的粗略位置参考；
• 教学实验平台中用于演示正交编码原理与状态机设计。

---

2. 硬件原理与接口规范

2.1 增量型编码器工作原理

iArduino 编码器模块（型号：Энкодер Trema-модуль）为标准两相正交输出（A/B Phase）机械式旋转编码器。其核心特性如下：

特性	参数说明
输出类型	开漏（Open-Drain）或推挽（Push-Pull）可选，模块默认配置为内部上拉的数字电平输出
相位关系	A 相与 B 相方波信号相位差恒为 90°（±45°容差），旋转方向决定超前关系： • 顺时针（CW）：A 相上升沿领先 B 相； • 逆时针（CCW）：B 相上升沿领先 A 相
每圈脉冲数（PPR）	20 脉冲/转（即每转产生 20 个完整 A/B 周期，对应 80 个状态变化）
机械寿命	≥ 100,000 次旋转
电气接口	3 线制：VCC（+5V）、GND、A 相、B 相（共 4 个引脚）

关键设计提示 ：模块未集成硬件施密特触发器，因此在长线传输或噪声环境下，建议在 A/B 信号线上各串联一个 100Ω 电阻，并在 MCU 端并联 0.1μF 陶瓷电容至 GND，以抑制高频干扰。

2.2 引脚复用与定时器资源映射

库的底层实现严格依赖 ATmega328P 的 Timer2 （8 位定时器），其硬件资源占用与引脚映射关系如下：

定时器资源	配置参数	工程意义
时钟源	CLKIO/128 （即 F_CPU / 128 = 125kHz ）	提供稳定、低抖动的采样基准，避免因主频波动导致采样间隔漂移
预分频器	CS22 （128 分频）	在 16MHz 主频下，Timer2 溢出周期 = 256 × 128 / 16,000,000 ≈ 2.048ms （488Hz）
溢出中断频率	488Hz （即每 2.048ms 进入一次 ISR）	此频率经实测验证：既能覆盖典型机械编码器最大旋转速度（> 300RPM），又留有充足 ISR 执行余量（ATmega328P 在 16MHz 下单次 ISR 执行约 12μs）
引脚无关性	A/B 信号可接任意 PORTB / PORTC / PORTD 引脚	库通过 digitalPinToPort() 和 digitalPinToBitMask() 宏动态解析引脚物理地址，实现全端口兼容

硬件连接示例（Arduino UNO） ：

• 编码器 VCC → UNO 5V
• 编码器 GND → UNO GND
• 编码器 A → UNO D7 （任意数字引脚）
• 编码器 B → UNO D6 （任意数字引脚）
  注：无需连接至 D2 / D3 等外部中断引脚。

---

3. API 接口详解与使用范式

3.1 类声明与对象构造

#include <iarduino_Encoder_tmr.h>

// 构造函数原型
iarduino_Encoder_tmr::iarduino_Encoder_tmr(uint8_t pinA, uint8_t pinB);

// 实例化示例：创建一个编码器对象，A 相接 D7，B 相接 D6
iarduino_Encoder_tmr encoder(7, 6);

参数	类型	说明
pinA	uint8_t	编码器 A 相信号连接的 Arduino 引脚编号（0–19，支持 A0–A5）
pinB	uint8_t	编码器 B 相信号连接的 Arduino 引脚编号（0–19）

构造时机约束 ：对象必须在全局作用域或 setup() 之前声明， 不可在函数内部动态构造 。原因在于库需在 begin() 调用前完成对 Timer2 寄存器的静态初始化，而局部对象的构造顺序不可控。

3.2 初始化函数 begin()

void iarduino_Encoder_tmr::begin(void);

功能 ：

• 配置 Timer2 为 CTC 模式（Clear Timer on Compare Match），比较值设为 OCR2A = 0xFF ；
• 启用 Timer2 溢出中断（ TIMSK2 |= (1 << TOIE2) ）；
• 设置 A/B 引脚为 INPUT 模式，并启用内部上拉（ digitalWrite(pinX, HIGH) ）；
• 清零内部计数器变量 count 与状态寄存器 state ；
• 关键副作用 ：此函数会 重写 TCCR2B 寄存器 ，覆盖用户先前对 Timer2 的任何配置（如 analogWrite() PWM 输出）。若项目中需同时使用 Timer2 PWM，请优先选用 Timer1（ analogWrite(9/10) ）或 Timer0（ analogWrite(5/6) ）。

3.3 状态读取函数 read()

int16_t iarduino_Encoder_tmr::read(void);

返回值 ：当前累计计数值（ int16_t ，范围 -32768 至 +32767）。
线程安全性 ：函数内部通过 noInterrupts() / interrupts() 对 count 变量实施临界区保护，确保多任务环境（如 FreeRTOS）下读取的原子性。

典型用法 ：

void loop() {
    static int16_t last_count = 0;
    int16_t current = encoder.read();
    
    if (current != last_count) {
        Serial.print("Encoder delta: ");
        Serial.println(current - last_count);
        last_count = current;
    }
    delay(50); // 避免串口刷屏
}

3.4 高级控制函数（隐式暴露）

尽管 README 未显式列出，但源码揭示以下实用接口：

函数	原型	说明
reset()	void iarduino_Encoder_tmr::reset(void)	将内部计数器清零，常用于归零校准
setCount(int16_t val)	void iarduino_Encoder_tmr::setCount(int16_t val)	强制设置计数值，支持负数，用于初始偏置或断电续传
getState()	uint8_t iarduino_Encoder_tmr::getState(void)	返回当前状态机编码（0x00–0x0F），用于调试状态跳变逻辑

状态机编码表（ getState() 返回值） ：
编码器状态机采用 4 位二进制表示 A/B 当前电平（bit1=A, bit0=B），共 4 种稳定态： 00 、 01 、 11 、 10 。库内部维护一个 16 字节查表（ quadrature_table[16] ），将相邻状态转换映射为 +1 （CW）、 -1 （CCW）或 0 （无效跳变）。开发者可通过 getState() 观察实际电平序列，快速定位接线错误或接触不良。

---

4. 底层实现逻辑与源码剖析

4.1 定时器 ISR 核心流程

TIMER2_OVF_vect 中断服务程序是整个库的中枢，其精简逻辑如下（已去除调试代码）：

ISR(TIMER2_OVF_vect) {
    static uint8_t prev_state = 0;      // 上次采样状态（A/B 电平）
    uint8_t curr_state = 0;
    
    // 1. 快速读取 A/B 引脚电平（利用 PINx 寄存器批量读取）
    uint8_t port_val = *(portInputRegister(digitalPinToPort(pinA)));
    curr_state  = (port_val & digitalPinToBitMask(pinA)) ? 0x02 : 0x00;
    curr_state |= (port_val & digitalPinToBitMask(pinB)) ? 0x01 : 0x00;
    
    // 2. 查表判别旋转方向与有效性（抗抖动）
    uint8_t delta = quadrature_table[(prev_state << 2) | curr_state];
    
    // 3. 更新计数器（仅当 delta != 0）
    if (delta) count += delta;
    
    // 4. 更新状态快照
    prev_state = curr_state;
}

关键技术点解析 ：

• 原子性读取 ：通过 PINB / PINC / PIND 寄存器一次性读取整个端口电平，避免 digitalRead() 的多次 I/O 操作开销；
• 状态压缩 ：将 A/B 电平编码为 2 位整数（0–3），与前一状态组合成 4 位索引（0–15），直接查表得 delta ；
• 抗抖动机制 ：查表本身即隐含消抖——仅当状态转换符合正交序列（如 00→01→11→10→00 ）时 delta 非零；非法跳变（如 00→11 ）被映射为 0 ，自动过滤抖动毛刺。

4.2 查表法（LUT）设计原理

quadrature_table[] 是库的算法核心，其定义如下（简化版）：

const int8_t quadrature_table[16] = {
    0, +1,  0, -1,   // 从 00 出发：00→01(+1), 00→10(-1)
    -1,  0, +1,  0,   // 从 01 出发：01→00(-1), 01→11(+1)
     0, -1,  0, +1,   // 从 11 出发：11→01(-1), 11→10(+1)
    +1,  0, -1,  0    // 从 10 出发：10→00(+1), 10→11(-1)
};

设计优势 ：

• 零分支预测失败 ：纯数组访问，无 if/else 或 switch ，指令周期高度可预测；
• 内存占用极小 ：16 字节 ROM，远低于状态机 switch-case 的代码体积；
• 可扩展性强 ：如需支持 1/2/4 倍频模式，仅需修改查表逻辑，无需重构状态机。

---

5. 工程实践与集成指南

5.1 与 FreeRTOS 的协同使用

在 FreeRTOS 环境下，需注意 ISR 与任务间的同步。推荐模式如下：

#include <FreeRTOS.h>
#include <queue.h>
#include <iarduino_Encoder_tmr.h>

// 创建编码器计数队列（深度 10，元素大小 2 字节）
QueueHandle_t encoder_queue;

void encoder_task(void *pvParameters) {
    int16_t count;
    for(;;) {
        if (xQueueReceive(encoder_queue, &count, portMAX_DELAY) == pdPASS) {
            // 处理计数变化，如更新 LCD 显示或 PID 设定值
            update_display(count);
        }
    }
}

// 在 Timer2 ISR 中（需修改库源码，添加 xQueueSendFromISR）
extern "C" {
    ISR(TIMER2_OVF_vect) {
        // ... 原有计数逻辑 ...
        if (delta) {
            BaseType_t xHigherPriorityTaskWoken = pdFALSE;
            xQueueSendFromISR(encoder_queue, &count, &xHigherPriorityTaskWoken);
            portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
        }
    }
}

void setup() {
    encoder_queue = xQueueCreate(10, sizeof(int16_t));
    xTaskCreate(encoder_task, "ENC", 128, NULL, 1, NULL);
    encoder.begin();
}

5.2 多编码器并行驱动

库支持单实例单编码器，多编码器需创建多个对象。 关键限制 ：所有实例共享同一 Timer2 中断源，故采样频率全局统一。示例：

// 三个编码器分别接 D2/D3, D4/D5, D8/D9
iarduino_Encoder_tmr enc1(2, 3);
iarduino_Encoder_tmr enc2(4, 5);
iarduino_Encoder_tmr enc3(8, 9);

void setup() {
    enc1.begin(); // Timer2 初始化仅执行一次
    enc2.begin(); // 后续调用仅配置引脚
    enc3.begin();
}

性能边界测试 ：在 ATmega328P@16MHz 下，实测三编码器并发时 ISR 总耗时 < 18μs，远低于 2.048ms 间隔，无丢脉冲风险。

5.3 电源管理与低功耗优化

在电池供电场景，可结合 avr/sleep.h 降低功耗：

#include <avr/sleep.h>
#include <avr/power.h>

void enter_sleep() {
    set_sleep_mode(SLEEP_MODE_IDLE); // Timer2 在 IDLE 模式下仍运行
    sleep_enable();
    sleep_cpu();
    sleep_disable();
}

void loop() {
    int16_t c = encoder.read();
    if (c != last_c) {
        process_rotation(c);
        last_c = c;
    } else {
        enter_sleep(); // 无旋转时进入低功耗
    }
}

---

6. 故障诊断与调试技巧

6.1 常见问题速查表

现象	可能原因	解决方案
read() 始终返回 0	1. begin() 未调用 2. A/B 引脚接反 3. 编码器损坏或未上电	检查 Serial.print(encoder.getState()) ，正常应循环输出 0,1,3,2 或 0,2,3,1
计数跳变剧烈（非单调）	1. 信号线过长未加滤波电容 2. 电源噪声大 3. 查表索引越界（引脚号超出 0–19）	示波器观测 A/B 波形，确认边沿干净；检查 digitalPinToPort() 返回值是否有效
reset() 后计数继续累加	reset() 仅清零 count ，但状态机 prev_state 未重置	改用 setCount(0) 并手动调用 encoder.getState() 强制刷新状态

6.2 使用逻辑分析仪验证

推荐使用 Saleae Logic 16 捕获 A/B 信号，设置如下：

• 采样率：≥ 1MHz；
• 触发条件：A 通道上升沿；
• 关键观察点：
  • A/B 相位差是否稳定 90°；
  • 旋转时状态序列是否为 00→01→11→10→00 （CW）或 00→10→11→01→00 （CCW）；
  • 是否存在异常毛刺（如 00→11 ），若有则需加强硬件滤波。

---

7. 与同类方案对比分析

维度	iarduino_Encoder_tmr	Encoder 库（Paul Stoffregen）	ClickEncoder 库
中断源	Timer2 溢出中断（固定 488Hz）	外部中断（INT0/INT1）	外部中断 + 软件定时器
引脚约束	任意引脚	仅 D2/D3	仅 D2/D3
抗抖动	硬件定时采样查表（强）	软件延时（中）	双边沿 + 时间窗（强）
多编码器	支持（共享 Timer2）	仅 2 个（受限于 INT 引脚）	仅 1 个
RAM 占用	~12 字节/实例	~8 字节/实例	~20 字节/实例
适用场景	高可靠性工业 HMI	快速原型开发	按键+编码器复合输入

选型建议 ：

• 选择 iarduino_Encoder_tmr ：当项目需 >2 个编码器、引脚资源紧张、或对计数零丢帧有硬性要求；
• 选择 Encoder 库：当仅需 1–2 个编码器且追求最小内存占用；
• 选择 ClickEncoder ：当需同时处理编码器旋转与按钮按下事件。

---

8. 源码定制与二次开发指引

库源码结构清晰，位于 iarduino_Encoder_tmr.h 与 .cpp 文件中。关键可定制点：

1. 修改采样频率 ：
   修改 .cpp 中 OCR2A 初始值。例如设为 0x7F （127），则溢出周期变为 128 × 128 / 16,000,000 ≈ 1.024ms （976Hz），适合高速旋转场景。

2. 扩展计数范围 ：
   将 count 成员变量类型由 int16_t 改为 int32_t ，并同步修改 read() 返回类型。需注意 noInterrupts() 保护范围需覆盖 4 字节读写。

3. 添加方向标志 ：
   在类中新增 bool direction 成员，在 ISR 中根据 delta 符号更新，提供 getDirection() 接口，便于实现“旋转即生效”逻辑（如音量旋钮松手后保持最后动作）。

4. 适配其他 MCU ：
   针对 ATmega2560（Arduino Mega），需将 TIMER2_OVF_vect 替换为 TIMER3_OVF_vect ，并重映射 TCCR3B / OCR3A 等寄存器。此工作已在社区 fork 中验证可行。

最后的硬件忠告 ：在 PCB 设计阶段，务必为编码器 A/B 信号线铺设独立地平面，并在 MCU 引脚处就近放置 100nF 退耦电容。曾有客户因忽略此点，在电机启停瞬间出现计数紊乱，最终通过增加磁珠与 RC 滤波解决。