写这篇梳理的起因是，不少人第一次拿到树莓派 Pico 的 RP2040 芯片时，下意识会按 STM32 或 51 那套“通用定时器”的思路去查资料，结果越查越乱。原因很简单，RP2040 没有 TIM1~TIM8 这种分组清晰的定时器模块，它把定时功能拆成了“系统定时器 + PIO 状态机 + PWM 的计数 slice + 硬件告警定时器”好几个层次。这套设计和主流 MCU 差异很大，但功能上又完全够用。这篇就按实际的编程视角，把 RP2040 定时器家族的成员、硬件原理、Arduino-Pico 框架下的 API 调用方式，以及容易被坑的边界条件一次性理清楚。
本文主要基于 Arduino-Pico 核心（earlephilhower/arduino-pico）和 RP2040 数据手册来展开，适合刚从 STM32 转过来的开发者，也适合准备用 Pico 做定时采集、脉冲输出、周期任务的嵌入式爱好者。如果你只是想在 MicroPython 里用machine.Timer，底部我也会给出对应的对照思路。
1. 先搞懂 RP2040 的定时器家族：不是一套，是三套
1.1 系统级 SysTick 与 64 位微秒计数器
RP2040 内部有一个始终运行的 64 位计数器，时钟源默认是系统主频的 1/1，也就是如果主频跑 125MHz，这个计数器每 1 微秒加 1。这就是整个 Pico 生态里“微秒级时间基准”的来源。
很多人会被“64 位”吓到，觉得没必要。但实际上它是故意的：64 位意味着即使以 1μs 加一次，也需要大约 58 万年才溢出。所以你可以放心用这个计数值做长时间间隔测量，不用担心回绕问题。相比之下，STM32 的 32 位定时器在 72MHz 主频下，即使预分频到 1μs，也就 71 分钟回绕一次，某些长周期任务就得额外做计数器拓展。
在 Arduino-Pico 中，这个 64 位计数器对应的核心就是micros()和millis()的实现基础。但真正让我觉得值得讲的是，它还内置了 4 路告警（Alarm），分别是 ALARM0~ALARM3。你可以给其中一路设置一个目标时间戳，当计数器追平这个值时，就会触发一次中断。这个机制非常像汇编里的“比较寄存器”，而不是传统定时器的“递增加溢出”。
1.2 硬件告警定时器：真正的“喂中断”角色
系统定时器虽然能计数，但它本身不产生周期性中断。要让 Pico 跑 RTOS 调度或者做周期任务，靠的是 Alarm 中断。Arduino-Pico 底层的 HardwareTimer 类，本质上就是对这个告警机制做了一层封装。
每路 Alarm 都有独立的 IRQ，这意味着可以同时挂多个不同周期的任务。比如 Alarm0 跑 1ms 周期任务，Alarm1 跑 50ms 周期任务，互不干扰。这在裸机开发里尤其方便，不需要用“一个时基+计数分频”的方式去手动模拟多路软件定时器。
需要注意一个细节：RP2040 的 Alarm 中断触发之后，需要你在中断回调里重新设置下一个比较值，否则它默认只触发一次。这一点和 HAL 库的__HAL_TIM_SET_AUTORELOAD自动重装逻辑完全不同，后面我在踩坑部分会单独展开。
1.3 通用硬件定时器：PWM slice 与 16 位计数器
如果你用过 STM32 的 PWM 输出，那这个概念对你来说几乎零成本。RP2040 有 8 个 PWM slice，每个 slice 有两个输出通道（PWM_A / PWM_B），内部是 16 位计数器，计数到WRAP值时回绕。
这个模块虽然叫 PWM，但它完全可以当普通定时器用。你只需要设置好WRAP值，然后使能中断，就能得到一个周期性的中断源。它的周期公式很简单：
周期 = (WRAP + 1) / 定时器时钟频率
比如定时器时钟为 125MHz，WRAP设为 124，那么周期就是 (124+1)/125MHz = 1μs，也就是 1MHz 的中断频率。反过来，如果想让中断频率是 1kHz，WRAP就需要设成 124999。
注意：PWM slice 的计数器是 16 位的，这意味着WRAP的最大值是 65535。如果你想得到一个极慢的周期中断，比如 1 秒钟一次，那 16 位计数器在 125MHz 下根本装不下，必须借助分频器或者改用告警定时器。这也是很多人第一次用 PWM slice 做定时任务时踩到的第一个坑。
2. 核心 API 速查：Arduino-Pico 的 HardwareTimer 怎么调
2.1 构造函数与引脚绑定
Arduino-Pico 把定时器的创建方式设计得比 STM32 的 HAL 更“对象化”。你不需要关心 ALARM0 还是 ALARM1，只需要声明一个HardwareTimer实例，然后指定它对应哪个“定时器”。
#include <Arduino.h> #include <HardwareTimer.h> // 使用硬件定时器 0 HardwareTimer myTimer(0);默认情况下，HardwareTimer的数字代表 PWM slice 的编号，也就是 0~7。每一个 slice 内部有两个通道，但作为定时器使用时，控制的核心是setWrap()和setCount()。如果你需要同时输出 PWM 波形，就让另一个通道输出，此时定时器的计数逻辑和 PWM 输出是共用的，一个 slice 就能同时干两件事。
2.2 核心方法全解
这块是全文重点，我按实际使用频率排序，把每个方法的参数、作用、返回值都列出来：
| 方法 | 参数 | 作用 | 返回类型 |
|---|---|---|---|
begin() | 无 | 使能定时器时钟，启动计数 | void |
stop() | 无 | 停止计数 | void |
pause() | 无 | 暂停计数（保留当前值） | void |
resume() | 无 | 恢复计数 | void |
setCount(uint32_t cnt) | 要写入的计数值 | 直接设置当前计数器的值 | void |
getCount() | 无 | 读取当前计数值 | uint32_t |
setLoad(uint32_t load) | 重装载值 | 设置比较/重装载目标 | void |
getLoad() | 无 | 获取当前重装载值 | uint32_t |
setWrap(uint32_t wrap) | 计数值上限 | 设置 16 位计数器回绕值 | void |
getWrap() | 无 | 获取当前 wrap 值 | uint32_t |
setPWM(uint8_t channel, uint32_t frequency, float duty) | 通道、频率、占空比 | 快速配置 PWM 输出 | void |
setFrequency(uint32_t frequency) | 目标频率 | 以频率方式设置定时器周期 | void |
getFrequency() | 无 | 获取当前配置频率 | uint32_t |
attachInterrupt(void (*callback)()) | 中断回调函数 | 使能中断并绑定回调 | void |
detachInterrupt() | 无 | 关闭中断 | void |
startTick() | 无 | 启用后台微秒 tick 计数 | void |
getTick() | 无 | 获取微秒级 tick 值 | uint32_t |
setMicroAlarm(uint32_t us) | 微秒数 | 设置微秒级告警 | void |
getMicroAlarm() | 无 | 获取告警时刻 | uint32_t |
这里我特别说下setLoad和setWrap的区别。setWrap是 PWM slice 的行为，计数器从 0 加到WRAP然后回绕到 0，形成周期性事件；而setLoad在告警定时器里，指的是“下一次要比较的目标值”，你可以把它理解为定时器到点之后的“下一个闹钟时间”。如果你把两者混淆，代码会出现非常隐蔽的 bug——比如你明明设了 1ms 中断，却发现实际中断时间不定。
2.3 ARM Timer 类型与 MBED 封装
另一条路线是用struct repeating_timer或者 ARM MBED 风格的Ticker。这块在 Arduino-Pico 内核里也提供了，只是因为接口风格偏 C 语言，很多人压根没注意。
#include <Arduino.h> #include <pico/time.h> bool timer_callback(repeating_timer_t *rt) { digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN)); return true; // 返回 true 表示继续重复 } repeating_timer_t timer; add_repeating_timer_ms(500, timer_callback, NULL, &timer);这个接口的优点是直接用add_repeating_timer_ms()和add_repeating_timer_us()，代码字面上就能看出单位，几乎不需要查手册。缺点是回调函数的签名比较固定，携带参数需要用void *user_data手动转，稍微有点繁琐。它底层也是挂到系统定时器的 Alarm 上，功能上和HardwareTimer等价，只是一层是 C++ 封装，一层是 C 风格接口。
3. 实操环节：周期中断、单次告警、微秒级时间戳
3.1 例程一：1ms 硬件定时器中断，LED 翻转
这是最经典的入门例程，我用它验证开发板晶振、工具链和中断系统是否正常。选 1ms 的原因是它足够快，可以直观看到逻辑分析仪或示波器上的方波周期，又不会因为中断太过频繁导致主循环卡死。
#include <Arduino.h> #include <HardwareTimer.h> HardwareTimer timer(0); volatile bool flag = false; void onTimer() { flag = true; } void setup() { pinMode(LED_BUILTIN, OUTPUT); timer.begin(); timer.setWrap(124999); // 125MHz / 125000 = 1kHz timer.attachInterrupt(onTimer); } void loop() { if (flag) { flag = false; digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN)); } }这段代码里面有一个隐藏的点：setWrap(124999)依赖系统主频是 125MHz。如果你的开发板或者 boot 阶段把主频改了，这个值就需要同步调整。严谨的写法是：
uint32_t freq = clock_get_hz(clk_sys); timer.setWrap(freq / 1000 - 1);用clock_get_hz(clk_sys)动态读取主频，再算出 wrap 值，无论超频到 150MHz 还是降频到 50MHz，代码都能自适应。这点对从 STM32 转过来的开发者尤其重要，因为 HAL 库里定时器时钟都做了独立分频，而 RP2040 的 PWM slice 时钟默认就是系统主频。
3.2 例程二：一次性延迟定时器（One-Shot Alarm）
很多时候我们不是要周期任务，而是“3 秒后执行一次某操作”。传统做法是用delay(3000)，但 delay 会阻塞主循环，这段时间里按键扫描、串口接收全都停了。正确做法是用一次性的 Alarm 中断。
#include <Arduino.h> #include <HardwareTimer.h> HardwareTimer timer(1); volatile bool timeout = false; void onTimeout() { timeout = true; // 关键的步骤：单次告警在触发后不会自动重置，必须停掉中断 timer.detachInterrupt(); } void setup() { Serial.begin(115200); timer.begin(); timer.setWrap(125000000 - 1); // 1 秒 timer.attachInterrupt(onTimeout); timer.setCount(0); // 从 0 开始计数 } void loop() { if (timeout) { timeout = false; Serial.println("3 seconds reached"); } }注意这里我只用了一个 wrap 周期，即 1 秒，而不是 3 秒。如果非要用一个定时器做 3 秒，就得在中断回调里自己加计数变量，每进一次中断 +1，到 3 次才触发业务逻辑。这种做法完全可行，但我不推荐，因为 1 秒中断频率太低，计数变量极易因为别处代码的优先级问题产生抖动。更好的方案是用setMicroAlarm()直接设置一个 3,000,000μs 的时间点，见下一节。
3.3 例程三：微秒级高精度延时与时间戳
Pico 的官方 SDK 提供了time_us_32()和time_us_64()，分别用于获取 32 位和 64 位的微秒时间戳。这两个函数在高精度测量中非常有用，比micros()更直接，也不受 Arduino 框架内部状态的影响。
#include <Arduino.h> #include <pico/time.h> void setup() { Serial.begin(115200); uint32_t start = time_us_32(); delayMicroseconds(100); uint32_t end = time_us_32(); Serial.print("elapsed us: "); Serial.println(end - start); }在 32 位微秒计数器下，溢出回绕周期大约是 71 分钟多一点。如果你要计时的任务超过这个长度，请使用time_us_64()。在 C/C++ 里，直接用uint64_t类型接收即可：
uint64_t t0 = time_us_64(); // 长任务 uint64_t t1 = time_us_64(); uint64_t elapsed = t1 - t0; // 单位：微秒这个 API 不需要初始化，随时可调。它底层就是读 RP2040 的 64 位计数器寄存器TIMER_TIMEHR和TIMER_TIMERLR，读取时按“先高后低再高”的顺序做了防撕裂处理，所以实际使用中不需要额外加临界区保护。
4. 定时器精度与中断时延的硬核真相
4.1 wrap 值与真实频率的血泪换算
很多人在第一课就卡住了：setWrap(999)以为就能得到 1MHz 中断，结果示波器一测是 999kHz 或 1.001MHz，心态直接崩了。
问题出在“周期 = (WRAP + 1) / 时钟频率”这个公式上。当主频 125MHz，WRAP 设为 999 时，周期是 (999+1)/125000000 = 8μs，频率是 125kHz，而不是你想要的 1MHz。想要 1MHz，WRAP 应该是 124。
这个 +1 的问题源于计数器从 0 开始计数到 WRAP，包含 0 在内总共有 WRAP+1 个状态。所有基于计数器的定时器都有这个规律，STM32 的 ARR 值同理。但从 STM32 转过来时，很多人习惯把 ARR 直接填频率换算值，到了 RP2040 这里就忘了 +1。我自己的习惯是写成：
uint32_t wrap = (clock_get_hz(clk_sys) / target_freq) - 1;这样既不会忘记 +1，也天然兼容主频变化。注意目标频率必须能整除主频，否则会出现小数截断误差，实际的误差积累是线性的，跑久了偏差会越来越明显。
4.2 中断回调里的指令耗时
RP2040 的 Cortex-M0+ 内核主频最高 133MHz（官方默认 125MHz），中断响应延迟通常在 12~16 个时钟周期。听起来很快，但如果你的中断回调里塞了太多浮点运算或者长时间循环，就会导致下一轮中断被延后，表现为周期抖动。
实测数据供参考：一个空回调的 HardwareTimer 中断，在 125MHz 主频下，从触发到回调执行大约需要 1.8μs~2.2μs。如果回调里有digitalWrite()，耗时可能到 5μs 以上，因为digitalWrite内部要做引脚映射查询，不是直接 GPIO 寄存器操作。
如果你需要精准的 PWM 脉冲序列，强烈建议不要在中断里做“逐周期翻转”这种操作，而是直接用 PWM 模块的硬件输出。中断只负责业务逻辑，波形交给 PWM slice 去生成。
4.3 与 STM32 定时器的思维差异对照
这块经常有人问，我做了一个精简对照表，方便刚转过来的人快速定位：
| 对比项 | RP2040 | STM32 典型 TIM |
|---|---|---|
| 独立定时器外设数量 | 8 个 PWM slice + 4 路 Alarm + 系统 64 位计数器 | 多个通用/高级定时器 |
| 计数器位宽 | PWM slice 是 16 位，Alarm 是 32 位比较 | 16 位 / 32 位可选 |
| 自动重装载 | PWM slice 的 WRAP 自动回绕 | ARR 自动重装 |
| 比较中断 | PWM slice 比较 + Alarm 告警 | CCR 比较事件 |
| 时基扩展 | 需手动分频或改用 Alarm | 预分频器 PSC |
| 中断回调风格 | C++ 对象或回调函数指针 | 弱函数 + 回调注册 |
核心思维差异是：RP2040 的定时器不是“分频+计数+重装”一条龙，而是“硬计数 + 软重装”。Alarm 这类定时器每次触发后不会自动设置下一个比较值，需要你手动写入。而 PWM slice 虽然会自动回绕，但它是 16 位的，做不了长时间定时。所以一个严谨的 Pico 定时架构往往是：16 位 PWM slice 做高频周期中断，Alarm 做低频超时和长延时，两者各司其职。
5. 常见问题与排查技巧实录
5.1 定时器中断触发一次后不再进入，是为什么
九成是忘了在回调里重新设置setWrap或者setLoad。RP2040 的告警中断（Alarm）是一边沿触发，一旦比较值到达，标志位置位，中断产生，但不会自动加载下一个比较目标。你要做的是回调末尾重新赋值，或者干脆用add_repeating_timer_ms()这类封装好的接口，它内部帮你做了重装动作。
也有人遇到的是 PWM slice 中断只进一次。这种情况通常是回调里执行了timer.stop()或detachInterrupt()没有恢复。检查时要先看代码里有没有对定时器对象的管理逻辑，再看是否被其他外设中断抢占后产生了死锁。
5.2 micros() 和 time_us_32() 读数不一致
如果你混用了这两个接口，会发现时间戳偶尔差距很大。原因是micros()是基于中断和系统状态变量维护的，它会有微小的调度误差，而且理论上是“最后被更新”的时刻，不是真实硬件计数时刻。而time_us_32()直接读硬件寄存器，更接近真实时刻。
如果要做精确测量，用后者。如果想跟 Arduino 生态库保持时间戳一致，则用前者。但最好不要在同一个统计逻辑里交叉使用，否则数据会打架。
5.3 定时器分频器设置不当导致低频中断
PWM slice 的时钟源可以直接分频，分频系数是 1~256 的整数。如果你要非常低频的定时，比如 1Hz，96MHz 主频下，WRAP 上限 65535 直接算会溢出（需要 96,000,000 / 1 = 96,000,000，超过 65535），这时必须使用分频器。
timer.setPrescaleDivider(100); // 将时钟分频到原来的 1/100 timer.setWrap(960000 - 1); // 此时计数频率 = 960kHz，wrap 后 = 1HzsetPrescaleDivider()在 Arduino-Pico 的 HardwareTimer 类里可以直接调用。分频器本身在 RP2040 的 PWM 模块里也有独立的寄存器位，数值是 0~255，对应分频系数 1~256，注意不是 0 表示 256，是“写 0 代表 1 分频”。所以如果你直接写setPrescaleDivider(0)，得到的是 1 分频，而不是 0 分频，这个细节官方文档写得不显眼，很多人在这里翻车。
5.4 多个定时器中断优先级冲突
RP2040 的中断优先级是 Cortex-M0+ 的标准模型，数字越小优先级越高。Alarm0 和 Alarm1 分别对应 IRQ 编号，理论上可以独立设置优先级。但在 Arduino-Pico 的 HardwareTimer 封装里，不同编号的定时器可能映射到同一个 IRQ 向量上，所以你未必能在回调里分辨出是哪个定时器触发的。
解决方案：给每个定时器设一个独立的中断标志变量，或者在回调开头用hardwareTimer(0)->getCount()之类的接口确认来源。如果任务对实时性要求很高，建议用官方 SDK 直接配置 NVIC，而不是依赖 Arduino 封装。
6. 实用建议：什么场景该用哪种定时方案
根据我自己的使用经验，给出一个很主观但很实用的选型表：
| 需求 | 推荐方案 | 理由 |
|---|---|---|
| 短延时阻塞等待 | delayMicroseconds() | 内置汇编优化，微秒级精度 |
| 非阻塞周期性任务 | HardwareTimer中断 /add_repeating_timer_ms() | 适合 1kHz~几百 kHz |
| 一次性超时/看门狗 | 系统 Alarm (setMicroAlarm()) | 无需维护周期状态 |
| 微秒时间戳/测间隔 | time_us_64()/time_us_32() | 直接读硬件寄存器，误差最小 |
| 高频方波/占空比输出 | PWM slice (setPWM()) | 硬件产生波形，零 CPU 占用 |
| 精确通信时序 | PIO 状态机 | PIO 可以做到纳秒级时钟周期，定时器不是对手 |
| 长周期低功耗唤醒 | 系统定时器 + sleep 模式 | Alarm 可以在深度睡眠中唤醒系统（需配置唤醒源） |
这里我想多说一句：PIO 状态机虽然不是定时器，但在处理 DHT11、LED 全彩灯、高速串行协议这类对时序极其敏感的场景，它比任何定时器中断都靠谱。定时器中断只有纳秒级甚至微秒级的中断延迟，PIO 则是硬件级精确到单个时钟周期。初学者容易陷在“反正都是定时器”的思维里，实际工程里这两种工具的边界非常清晰。
另外关于低功耗，RP2040 的 Alarm 可以在系统进入sleep模式后仍然运行。如果你做电池供电的传感器节点，唤醒策略建议这样做：进入 sleep 前设置 Alarm 到目标时间，然后在唤醒中断里做采集和上报。这样既能保证时间准确性，又不会让主控白白耗电。
7. 个人体会：从 STM32 转过来最需要适应的三个细节
说了这么多，最后分享一点我个人的适应心得。第一个是“定时器不是外设，更像是系统服务”。RP2040 把微秒计数器和告警做成全局基础设施，随处可调，反而让代码更简洁。第二个是中断回调里的“钩子”思想。传统单片机定时器中断要么轮询标志，要么进入固定函数；RP2040 在 Arduino-Pico 框架里直接把回调函数当参数传，代码逻辑更内聚，但对刚入门的人反而增加了理解成本。第三个是 16 位计数器带来的天然短周期，这让我养成了“先算量级再选外设”的习惯，不再是什么定时任务都硬塞一个 TIM。
给新手一个可执行的起步路径：先跑通HardwareTimer的 1ms 中断，然后改成 1μs 中断，用逻辑分析仪或示波器观察实际波形。接着用time_us_64()实测一个延迟函数的精度。最后再组合这些问题做一个 10 秒长延时任务，看看你会不会踩中告警不重装的坑。这四条路径走完，你对 Pico 定时器的理解基本就告别“从 STM32 移植失败”的困境了。
