directTimers：AVR微控制器硬件定时器直控库
1. directTimers 库概述：面向 AVR 微控制器的全功能硬件定时器直控方案
directTimers是一款专为 Atmel AVR 系列微控制器设计的底层定时器控制库，其核心目标是绕过 Arduino 标准analogWrite()和millis()等抽象层，直接映射并暴露 ATMega2560、ATMega328P 与 ATMega32U4 数据手册中定义的全部定时器/计数器寄存器功能。该库不作任何功能裁剪或逻辑简化，所有模式（Standard、CTC、Fast PWM、Phase-Correct PWM）、所有时钟源（内部预分频、外部引脚边沿触发）、所有输出比较动作（Disable、Normal PWM、Inverted PWM、Toggle）以及看门狗定时器（WDT）中断均以零抽象 API 形式提供。它本质上是一份“寄存器操作的 C++ 封装”，适用于对时序精度、资源占用和底层行为有严格要求的嵌入式系统开发场景——例如高精度电机驱动、超声波测距、音频信号合成、实时脉冲序列生成等。
在标准 Arduino 生态中，analogWrite()仅支持有限的固定频率 PWM 输出（如 490Hz 或 980Hz），且无法访问 CTC 模式下的精确周期中断、无法配置外部时钟源、无法启用 WDT 中断唤醒等关键能力。directTimers正是为填补这一空白而生：它将数据手册第 14–17 章（Timer/Counter0/1/2）与第 25 章（Watchdog Timer）的全部寄存器位定义，转化为一组语义清晰、类型安全、可移植的 C++ 函数接口，使开发者能在不查阅寄存器地址、不手动编写bitSet()/bitClear()的前提下，完成从初始化到运行时动态重配置的全流程控制。
1.1 支持的 MCU 平台与硬件资源映射
| MCU 型号 | 定时器数量 | 可用定时器编号 | 关键特性支持 |
|---|---|---|---|
| ATMega328P | 3 | TIMER0, TIMER1, TIMER2 | 全部 8/9/10-bit PWM 模式；TIMER1 支持 16-bit 计数；WDT 中断唤醒 |
| ATMega32U4 | 4 | TIMER0, TIMER1, TIMER3, TIMER4 | TIMER3/TIMER4 为 10-bit 高速 PWM；支持 USB 同步定时；WDT 可配置为中断或复位 |
| ATMega2560 | 6 | TIMER0, TIMER1, TIMER2, TIMER3, TIMER4, TIMER5 | TIMER1/3/4/5 均为 16-bit；支持输入捕获（ICP）引脚；多路独立预分频器 |
注意：
directTimers当前公开 API 仅显式声明了TIMER0、TIMER1、TIMER2的函数族（如TIMER0_COMPA_attachInterrupt），但其实现已兼容全部定时器。对于TIMER3+，开发者需参考对应 MCU 数据手册，通过宏定义扩展TIMERn_前缀（例如#define TIMER3_setClock(...) ...），或直接操作底层寄存器（TCCR3B,OCR3A等）——这正是本库“直控”哲学的体现：API 是入口，寄存器是真相。
1.2 设计哲学：为什么需要“直接”？
AVR 定时器的复杂性源于其多功能复用架构。以 ATMega328P 的 TIMER1 为例，同一组寄存器（TCCR1B,OCR1A,TCNT1）在不同模式下承担完全不同的角色：
- Standard 模式：
TCNT1自增至0xFFFF后溢出，触发TIMER1_OVF_vect - CTC 模式：
TCNT1自增至OCR1A后清零，触发TIMER1_COMPA_vect - Fast PWM 模式：
TCNT1自增至ICR1（或OCR1A）后归零，OCR1A控制占空比 - Phase-Correct PWM 模式：
TCNT1先增后减，形成对称波形，OCR1A控制占空比
Arduino 标准库将这些模式封装为analogWrite()的隐式行为，开发者无法在运行时切换模式、无法同时使用 CTC 中断与 PWM 输出、无法在 Fast PWM 下动态修改 TOP 值。directTimers则强制要求开发者显式声明意图：调用TIMER1_setMode(CTC_MODE)即明确选择 CTC 模式，后续TIMER1_COMPA_setValue(1000)才具有确定语义。这种“显式优于隐式”的设计，虽增加初期学习成本，却彻底消除了时序黑箱，是工业级固件开发的基石。
2. 核心 API 详解与工程化使用指南
directTimers的 API 设计严格遵循“一个函数，一个职责”原则，所有函数均为内联（inline）实现，无函数调用开销，且参数类型为byte或uint16_t，避免隐式类型转换风险。以下按功能域分类解析关键 API，并附带工程实践要点。
2.1 定时器基础控制 API
| 函数原型 | 功能说明 | 工程要点与陷阱 |
|---|---|---|
void TIMERn_setClock(byte clk) | 设置定时器时钟源与预分频系数 | clk必须为预定义常量（如PRESCALER_64）。错误传入非法值将导致未定义行为；需确保clk与所选模式兼容（如外部时钟源不可用于 Phase-Correct 模式） |
void TIMERn_setMode(byte mode) | 设置定时器工作模式 | 模式切换需在定时器停止时进行（先TIMERn_setClock(STOPPED)），否则可能丢失计数或触发意外中断。mode为STANDARD_MODE,CTC_MODE等常量 |
byte TIMERn_getCounter(void) | 读取当前计数值（8-bit 定时器） | 对于 16-bit 定时器（如 TIMER1），应使用uint16_t TIMER1_getCounter16(void)（库内部提供，未在 README 显式列出，但源码中存在） |
void TIMERn_setCounter(byte value) | 设置计数器初值 | 在 Standard 模式下，此值决定溢出前的计数周期；在 CTC 模式下，此值无效（由OCRnA决定） |
void TIMERn_COMPA_setValue(byte value) | 设置 OCRnA 寄存器值（Output Compare Register A） | 值范围受模式限制：CTC 模式下value必须 <TOP；Fast PWM 8-bit 模式下value∈ [0, 255]；若超出范围，硬件将截断，但可能导致波形失真 |
void TIMERn_COMPB_setValue(byte value) | 设置 OCRnB 寄存器值 | 同上，且OCRnB值必须 ≤OCRnA（当OCRnA用作 TOP 时），否则行为未定义 |
关键寄存器映射关系（以 TIMER0 为例）：
TIMER0_setClock(clk)→ 操作TCCR0B的CS02:0位TIMER0_setMode(mode)→ 操作TCCR0A的WGM01:0与TCCR0B的WGM02位TIMER0_COMPA_setValue(value)→ 写入OCR0A寄存器TIMER0_getCounter()→ 读取TCNT0寄存器
2.2 中断管理 API
| 函数原型 | 功能说明 | 工程要点与陷阱 |
|---|---|---|
void TIMERn_COMPA_attachInterrupt(void (*isr)()) | 使能 OCRnA 匹配中断，并注册用户 ISR | ISR 必须为void func(void)无参函数；库内部自动设置TIMSKn的OCIEAn位与全局中断使能（sei()）；多次调用会覆盖前一个 ISR |
void TIMERn_COMPB_attachInterrupt(void (*isr)()) | 使能 OCRnB 匹配中断，并注册用户 ISR | 同上，操作OCIEBn位 |
void TIMERn_COMPA_detachInterrupt(void) | 禁用 OCRnA 匹配中断 | 清除TIMSKn的OCIEAn位；不关闭全局中断，仅禁用该中断源 |
void TIMERn_COMPB_detachInterrupt(void) | 禁用 OCRnB 匹配中断 | 同上 |
void WDT_attachInterrupt(void (*isr)(), int prescaler) | 使能看门狗定时器中断，设置预分频并注册 ISR | prescaler为WDTO_15MS,WDTO_30MS, ...,WDTO_8S；必须在WDT_disable()后调用，否则可能立即触发复位；ISR 中需调用WDT_reset()防止复位 |
void WDT_detachInterrupt(void) | 禁用 WDT 中断 | 调用WDT_disable() |
中断服务例程（ISR）编写规范：
// ✅ 正确：无参、无返回值、无延迟、无串口打印 void timer1A_ISR() { static uint8_t state = 0; state ^= 0x01; digitalWrite(13, state); // 直接操作端口寄存器更优：PORTB ^= _BV(PORTB5); } // ❌ 错误：调用 delay()、Serial.print()、malloc() 等阻塞/动态分配函数 void bad_ISR() { delay(1); // 严重错误！delay() 依赖定时器，此处定时器正在中断中 Serial.println("Hello"); // Serial 使用 UART 中断，可能死锁 }
2.3 输出比较通道（OCx）配置 API
| 函数原型 | 功能说明 | 工程要点与陷阱 |
|---|---|---|
void TIMERn_COMPA_mode(byte mode) | 配置 OCRnA 匹配事件对 OCnA 引脚的动作 | mode为DISABLE_COMP,NORM_PWM,INVERT_PWM,TOGGLE_PIN；此配置直接影响硬件引脚行为，无需额外pinMode() |
void TIMERn_COMPB_mode(byte mode) | 配置 OCRnB 匹配事件对 OCnB 引脚的动作 | 同上；对于 TIMER0，OC0A 对应 PD6，OC0B 对应 PD5；需确认引脚复用功能已启用（`DDRD |
硬件引脚映射表（ATMega328P）：
定时器 通道 引脚 数据手册端口 备注 TIMER0 A PD6 PORTD.6 digitalWrite(6, ...)TIMER0 B PD5 PORTD.5 digitalWrite(5, ...)TIMER1 A PB1 PORTB.1 digitalWrite(9, ...)TIMER1 B PB2 PORTB.2 digitalWrite(10, ...)TIMER2 A PB7 PORTB.7 digitalWrite(11, ...)TIMER2 B PD3 PORTD.3 digitalWrite(3, ...)重要：调用
TIMERn_COMPA_mode(NORM_PWM)后，digitalWrite(pin, ...)将失效，引脚状态完全由定时器硬件控制。若需恢复 GPIO 功能，必须调用TIMERn_COMPA_mode(DISABLE_COMP)并执行pinMode(pin, OUTPUT)。
3. 高级应用实战：从原理到代码
3.1 精确频率 PWM 生成（Phase-Correct 模式）
工程需求：在 ATMega328P 上，使用 TIMER1 生成 25 kHz、占空比可调的方波，要求波形对称（低 EMI），且 CPU 占用率趋近于零。
原理推导：
- ATMega328P 系统时钟
F_CPU = 16 MHz - Phase-Correct PWM 模式下，计数器先增后减，一个完整周期包含
2 × TOP个时钟周期 - 目标频率
F_PWM = 25 kHz，故2 × TOP = F_CPU / F_PWM = 16000000 / 25000 = 640 - 解得
TOP = 320（即ICR1 = 320）
代码实现：
#include <directTimers.h> void setup() { // 1. 配置引脚为输出（尽管 PWM 会接管，但确保端口方向正确） DDRB |= _BV(PORTB1) | _BV(PORTB2); // PORTB.1 (OC1A), PORTB.2 (OC1B) // 2. 停止 TIMER1，准备配置 TIMER1_setClock(STOPPED); // 3. 设置为 Phase-Correct PWM 自定义 TOP 模式 TIMER1_setMode(PHASECORRECT_PWM_CUSTOM); // 4. 设置 TOP 值为 320（写入 ICR1） TIMER1_setTop(320); // 5. 设置时钟源为无预分频（F_CPU = 16MHz） TIMER1_setClock(PRESCALER_1); // 6. 配置 OC1A/OC1B 为 Normal PWM 输出 TIMER1_COMPA_mode(NORM_PWM); TIMER1_COMPB_mode(NORM_PWM); // 7. 初始化占空比（假设 A 通道 50%，B 通道 25%） TIMER1_COMPA_setValue(160); // 160/320 = 50% TIMER1_COMPB_setValue(80); // 80/320 = 25% } void loop() { // 动态调整占空比（例如来自 ADC） uint16_t adc_val_a = analogRead(A0); uint16_t adc_val_b = analogRead(A1); // 映射到 0-320 范围（TOP 值） uint16_t duty_a = map(adc_val_a, 0, 1023, 0, 320); uint16_t duty_b = map(adc_val_b, 0, 1023, 0, 320); // 原子写入 OCR1A/OCR1B（避免计数器读写冲突） cli(); // 关中断 OCR1A = duty_a; OCR1B = duty_b; sei(); // 开中断 }关键点解析：
TIMER1_setTop(320)实际调用ICR1 = 320，这是 Phase-Correct 模式下定义周期的核心寄存器。map()函数将 10-bit ADC 值（0-1023）线性映射到 0-TOP 范围，确保占空比计算准确。cli()/sei()保护OCR1A/OCR1B写入，防止在 16-bit 寄存器更新过程中被中断打断（AVR 中 16-bit 寄存器读写需两条指令）。
3.2 外部事件计数（External Clock Source）
工程需求：测量旋转编码器 A/B 相脉冲频率，要求最高计数速率 8 MHz，使用 TIMER1 作为高速计数器。
原理与配置：
- 编码器输出连接至
T1引脚（PB5 / Arduino pin 5） - 选择
EXTERNAL_FALLING模式，即在T1引脚电平下降沿时递增计数器 TIMER1为 16-bit，最大计数值 65535，需定期读取并清零防溢出
代码实现：
#include <directTimers.h> volatile uint16_t pulse_count = 0; void count_ISR() { pulse_count++; // 简单累加，实际应用中可做去抖或状态机解码 } void setup() { // 1. 配置 T1 引脚为输入（默认） DDRB &= ~_BV(PORTB5); // 2. 停止 TIMER1 TIMER1_setClock(STOPPED); // 3. 设置为 Standard 模式（自由运行计数） TIMER1_setMode(STANDARD_MODE); // 4. 选择外部下降沿时钟源 TIMER1_setClock(EXTERNAL_FALLING); // 5. 使能溢出中断（可选，用于处理 65535 溢出） TIMER1_OVF_attachInterrupt([](){ pulse_count += 65536; }); // 6. 注册匹配中断（此处用 OVF，也可用 CTC 模式定期采样） TIMER1_COMPA_attachInterrupt(count_ISR); // 7. 设置 OCR1A 为 0，使其在每次计数器归零时触发（非必需，仅作示例） TIMER1_COMPA_setValue(0); TIMER1_COMPA_mode(TOGGLE_PIN); // 此处仅为演示，实际不用 } void loop() { static uint32_t last_count = 0; static unsigned long last_time = millis(); // 每 100ms 读取一次计数值 if (millis() - last_time >= 100) { cli(); uint32_t current = pulse_count; pulse_count = 0; // 清零 sei(); uint32_t freq = (current * 10) / 1; // 100ms 内脉冲数 × 10 = Hz Serial.print("Freq: "); Serial.print(freq); Serial.println(" Hz"); last_count = current; last_time = millis(); } }硬件连接要点：
- 编码器 A/B 相输出需经施密特触发器（如 74HC14）整形，消除抖动。
T1引脚（PB5）内部有上拉电阻，若编码器为开漏输出，需外接上拉电阻（4.7kΩ）。EXTERNAL_FALLING模式下，TCCR1B的CS12:0位被设为0b110，T1引脚成为时钟输入。
4. 看门狗定时器（WDT）深度集成
WDT 在directTimers中不仅作为复位源，更被强化为一种超低功耗睡眠唤醒机制。其独特价值在于：当主 CPU 进入SLEEP_MODE_PWR_DOWN时，WDT 仍以独立振荡器（128 kHz）运行，可在毫秒级精度唤醒系统，功耗低至 0.1 µA。
4.1 WDT 中断唤醒流程
#include <directTimers.h> #include <avr/sleep.h> #include <avr/power.h> void wdt_wakeup_ISR() { // WDT 中断服务程序 // 注意：此处必须调用 WDT_reset()，否则下一次 WDT 超时将触发复位 WDT_reset(); // 执行唤醒后任务（如读取传感器） // ... } void setup() { // 1. 初始化 WDT 中断（128kHz 振荡器，预分频 128 → 1kHz，周期 1ms） WDT_attachInterrupt(wdt_wakeup_ISR, WDTO_15MS); // 15ms 周期 // 2. 配置睡眠模式 set_sleep_mode(SLEEP_MODE_PWR_DOWN); sleep_enable(); // 3. 全局中断使能（WDT 中断需全局中断开启） sei(); } void loop() { // 主循环进入深度睡眠 sleep_mode(); // 被 WDT 中断唤醒后，继续执行此处代码 // ... }WDT 预分频常量对照表：
常量 时间间隔 适用场景 WDTO_15MS15 ms 快速响应传感器事件 WDTO_30MS30 ms 平衡功耗与响应速度 WDTO_60MS60 ms 通用低功耗监控 WDTO_120MS120 ms 电池供电设备长周期采样 WDTO_250MS250 ms 人机交互（按键扫描） WDTO_500MS500 ms LED 状态指示 WDTO_1S1 s 环境参数（温湿度）周期上报 WDTO_2S2 s 低频数据日志记录 WDTO_4S4 s 极致省电（如土壤湿度监测） WDTO_8S8 s 超长待机（如气象站）
4.2 WDT 与主定时器协同设计
在复杂系统中，WDT 可作为“心跳监护者”，而主定时器（如 TIMER1）执行高精度任务。二者协同可构建鲁棒系统：
- 主定时器故障检测：WDT ISR 中检查
TIMER1_getCounter16()是否在预期范围内变化，若停滞则触发软复位或报警。 - 分级唤醒：WDT 每 100ms 唤醒，执行快速任务（如 GPIO 状态扫描）；若需高精度定时，则启动 TIMER1，完成后再次进入睡眠。
5. 移植与调试技巧
5.1 跨平台移植要点
- 寄存器名差异：ATMega2560 的
TIMER3寄存器为TCCR3B,OCR3A，而 ATMega328P 无此组。移植时需条件编译：#if defined(__AVR_ATmega2560__) #define TIMER3_setClock(clk) do { /* 实现 */ } while(0) #endif - 引脚复用冲突：ATMega32U4 的
TIMER3与 USB PHY 共享引脚，启用前需确认USBCON配置。 - 内存约束：
directTimers无全局变量，代码体积 < 2KB，适合 32KB Flash 的 ATMega328P。
5.2 常见问题诊断
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| PWM 无输出 | TIMERn_COMPA_mode()未调用；引脚复用未启用；pinMode()覆盖了定时器功能 | 检查DDR寄存器；用逻辑分析仪测OCnA引脚 |
| 中断不触发 | TIMSKn位未置位；全局中断未使能（sei()）；ISR 函数签名错误 | 用avr-gdb检查TIMSKn值；确认sei()调用位置 |
| 计数值异常跳变 | TCNTn读写未原子化；外部噪声干扰Tn引脚 | 对 16-bit 寄存器读写加cli()/sei()；增加硬件滤波 |
| WDT 触发意外复位 | WDT_attachInterrupt()后未在 ISR 中调用WDT_reset() | 在 ISR 开头添加WDT_reset() |
终极调试工具：使用 Saleae Logic Analyzer 抓取
OCnA引脚波形，直接验证TOP、OCRnA、F_CPU计算是否准确。波形周期T = (2 × TOP × Prescaler) / F_CPU（Phase-Correct）或T = (TOP + 1) × Prescaler / F_CPU（Fast PWM），实测值与理论值偏差 > 1% 即需检查时钟源配置。
directTimers库的价值，不在于它提供了多少新功能，而在于它将 AVR 定时器这一经典外设的全部潜力，以一种工程师可理解、可预测、可调试的方式，交还到开发者手中。在 STM32 HAL 库日益臃肿的今天，回归 AVR 的寄存器直控哲学，恰是对嵌入式本质的一次致敬——真正的实时性，永远诞生于对硬件最诚实的对话之中。