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_15MS	15 ms	快速响应传感器事件
WDTO_30MS	30 ms	平衡功耗与响应速度
WDTO_60MS	60 ms	通用低功耗监控
WDTO_120MS	120 ms	电池供电设备长周期采样
WDTO_250MS	250 ms	人机交互（按键扫描）
WDTO_500MS	500 ms	LED 状态指示
WDTO_1S	1 s	环境参数（温湿度）周期上报
WDTO_2S	2 s	低频数据日志记录
WDTO_4S	4 s	极致省电（如土壤湿度监测）
WDTO_8S	8 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 的寄存器直控哲学，恰是对嵌入式本质的一次致敬——真正的实时性，永远诞生于对硬件最诚实的对话之中。