NusabotSimpleTimer：无中断轻量级软件定时器库

1. 项目概述NusabotSimpleTimer 是一个轻量级、无中断依赖的软件定时器库专为资源受限的嵌入式微控制器如 Arduino 兼容平台、STM32 基础系列、ESP32 的裸机模式等设计。它并非基于硬件定时器外设或中断服务程序ISR而是完全依托millis()系统滴答计数器通过主循环中的主动轮询polling机制实现时间调度。其核心设计哲学是以确定性换取简洁性以可预测性替代高精度。该库直接派生自 Arduino Playground 经典的 SimpleTimer 项目经 Nusabot 团队重构与工程化增强强化了 API 的一致性、内存管理的健壮性以及多定时器实例的隔离能力。它不占用任何硬件定时器通道不引入中断上下文切换开销彻底规避了 ISR 与主程序间共享全局变量时常见的竞态条件race condition、数据撕裂tearing及临界区保护难题。对于绝大多数非实时控制系统——如传感器周期采集、LED 淡入淡出、串口状态轮询、看门狗喂狗、用户界面刷新、低频通信协议超时处理等场景其 1ms 的时间分辨率已完全满足需求。需要明确的是NusabotSimpleTimer不承诺硬实时行为。其回调函数的实际触发时刻取决于run()被调用的频率及前序任务的执行耗时。若一个回调函数执行时间超过设定间隔后续调用将被自然“堆积”并依次执行而非并发或丢弃。这种“阻塞式调度”模型虽牺牲了严格的时间精度却换来了极高的代码可读性、调试友好性与系统稳定性是嵌入式初学者与快速原型开发者的理想选择。2. 核心原理与运行机制2.1 时间基准与轮询模型库的核心时间基准是millis()函数返回的无符号长整型unsigned long毫秒计数值。该值由 MCU 的系统滴答定时器SysTick或专用低功耗定时器如 STM32 的 LPTIM在后台持续累加即使在主循环被长时间阻塞时也保持递增前提是滴答源未被关闭。millis()的典型实现具有 1ms 分辨率且在约 49.7 天后发生溢出回绕0xFFFFFFFF 1 0x00000000。NusabotSimpleTimer 完全兼容此溢出行为其时间差计算采用无符号整数减法天然支持跨溢出比较// 正确的跨溢出时间差计算无需特殊处理 if ((millis() - lastTriggerTime) intervalMs) { // 触发回调 lastTriggerTime millis(); }整个调度引擎封装在run()成员函数中。开发者必须在loop()函数的最顶层或等效的主任务循环中周期性、高频地调用timer.run()。这是轮询模型生效的前提。run()的内部逻辑高度精简仅执行以下三步获取当前时间快照调用millis()获取当前系统毫秒计数。遍历所有激活定时器槽位检查每个已启用enabled且未到期disabled的定时器条目。条件触发与状态更新对每个条目计算(currentMillis - previousMillis)。若差值 ≥ 设定间隔则执行注册的回调函数callback()更新该条目的previousMillis为currentMillis若为一次性定时器setTimeout或有限次定时器setTimer则自动将其状态置为DISABLED并标记为可回收。此模型的本质是将“何时触发”的决策权完全交还给主程序流消除了中断带来的不确定性但也将调度延迟的责任明确归于开发者——run()调用越频繁平均调度延迟越小若loop()中存在长耗时操作如delay(1000)或复杂浮点运算则所有定时器的响应都会被同步拖慢。2.2 内存结构与槽位管理NusabotSimpleTimer 采用静态数组管理定时器槽位timer slots默认容量为MAX_TIMERS通常定义为 10可在头文件中修改。每个槽位是一个结构体存储以下关键字段字段名类型说明callbacktimer_callback(函数指针)指向用户定义的无参无返回值回调函数void func(void)intervalunsigned long定时器间隔毫秒对setTimeout即为首次触发延时prev_millisunsigned long上次触发或启动时的millis()快照用于计算时间差repeat_countint剩余重复次数。-1表示无限循环setInterval0表示已执行完毕0表示剩余次数setTimerenabledbool槽位使能状态。true表示参与run()调度false则被跳过槽位分配采用简单的线性搜索setInterval/setTimeout/setTimer在调用时从索引0开始扫描第一个enabled false的空闲槽位并填入参数。deleteTimer(int timerId)则直接将对应索引的槽位enabled置为false释放该槽位供后续复用。getNumTimers()遍历数组并统计enabled true的槽位总数。这种静态分配策略避免了动态内存分配malloc/free带来的碎片化与不确定性风险符合嵌入式系统对内存确定性的严苛要求。但开发者需预先评估最大并发定时器数量确保MAX_TIMERS设置充足。3. API 详解与工程化使用指南3.1 构造与初始化NusabotSimpleTimer timer; // 全局单例推荐方式 // 或 NusabotSimpleTimer myTimer; // 自定义实例名工程要点单例优先绝大多数应用只需一个全局NusabotSimpleTimer实例。创建多个实例会增加 RAM 占用每个实例独占一套槽位数组且无实际收益除非需严格隔离不同模块的定时器如通信模块与控制模块。声明位置必须在setup()和loop()之外的全局作用域声明确保其生命周期覆盖整个程序运行期。3.2 定时器创建 APIint setInterval(unsigned long d, timer_callback f)创建一个无限循环的周期性定时器。参数d: 以毫秒为单位的执行间隔。最小安全值建议 ≥ 5ms避免因run()调用开销导致过度频繁触发。f: 回调函数指针签名必须为void func(void)。返回值成功时返回分配的槽位索引timerId范围0至MAX_TIMERS-1失败无空闲槽位返回-1。工程实践避免阻塞回调函数内严禁调用delay()、while(1)或任何可能无限等待的函数。应保持短小精悍将耗时操作拆解或移至主循环。状态同步若回调需修改主循环使用的变量因其在主上下文执行无需volatile修饰或临界区保护与 ISR 回调有本质区别。// 示例每 200ms 读取一次 ADC结果存入全局缓冲区 volatile int adcValue 0; // volatile 仅因可能被其他非定时器代码读写非必需 void readADC() { adcValue analogRead(A0); // 快速采样 // 不在此处做复杂滤波留待 loop() 处理 } void setup() { timer.setInterval(200, readADC); } void loop() { timer.run(); // 主循环可安全使用 adcValue if (adcValue THRESHOLD) { digitalWrite(LED_PIN, HIGH); } }int setTimeout(unsigned long d, timer_callback f)创建一个一次性定时器在d毫秒后执行回调随后自动销毁。参数同setInterval。返回值同setInterval。工程实践启动延迟常用于系统初始化后的延时启动如等待传感器稳定、错误恢复后的延时重试、UI 提示的延时消失。链式触发可在回调函数内再次调用setTimeout实现非固定周期的“下一次触发”。// 示例上电后 3 秒启动主任务并设置 5 秒后发送心跳包 void startMainTask() { Serial.println(Main task started.); // 启动其他周期性任务... } void sendHeartbeat() { Serial.println(Heartbeat sent.); } void setup() { Serial.begin(9600); timer.setTimeout(3000, startMainTask); // 3秒后启动 timer.setTimeout(8000, sendHeartbeat); // 358秒后首次心跳 }int setTimer(unsigned long d, timer_callback f, int n)创建一个有限次周期性定时器执行n次后自动销毁。参数d,f: 同setInterval。n: 总执行次数必须 0。返回值同setInterval。工程实践精确计数适用于需要严格控制执行次数的场景如 LED 闪烁指定次数、电机步进指定步数、协议握手过程中的重传上限。状态机驱动n可作为状态机的步骤计数器。// 示例LED 闪烁 5 次每次亮 200ms灭 200ms int blinkCount 0; void blinkLED() { if (blinkCount % 2 0) { digitalWrite(LED_PIN, HIGH); } else { digitalWrite(LED_PIN, LOW); } blinkCount; } void setup() { pinMode(LED_PIN, OUTPUT); timer.setTimer(200, blinkLED, 10); // 5次亮5次灭 10次回调 }3.3 定时器生命周期管理 APIboolean isEnabled(int timerId)查询指定timerId的定时器是否处于启用状态。用途在执行关键操作前确认定时器是否活跃或用于调试状态检查。注意timerId必须是之前set*调用返回的有效值否则行为未定义。void enable(int timerId)/void disable(int timerId)/void toggle(int timerId)对指定timerId的定时器进行启停控制。工程价值动态启停根据系统状态如电池电量低、进入休眠模式、用户按下暂停键动态关闭非关键定时器节省 CPU 周期。资源复用disable一个定时器比deleteTimer更轻量因其不释放槽位后续可快速enable恢复避免重新分配开销。调试利器在loop()中加入条件判断临时禁用某个定时器以隔离问题。// 示例根据开关状态控制 LED 闪烁 const int SW_PIN 2; void setup() { pinMode(SW_PIN, INPUT_PULLUP); timer.setInterval(500, blinkLED); } void loop() { timer.run(); if (digitalRead(SW_PIN) LOW) { // 开关按下 timer.disable(blinkId); // 停止闪烁 } else { timer.enable(blinkId); // 恢复闪烁 } }void restartTimer(int timerId)将指定timerId的定时器的计时起点重置为当前millis()不触发回调。核心应用场景——软件看门狗Watchdog Timer在主循环的关键路径如loop()末尾调用restartTimer(wdId)表示“系统仍正常运行”。若主循环因死锁、崩溃或长时间阻塞而未能及时调用restartTimer则看门狗定时器将在interval时间后超时执行预设的恢复动作如打印错误日志、复位 MCU。这是restartTimer最具价值的用法完美体现了“非中断、易集成、高可靠”的设计思想。// 示例10秒软件看门狗 int wdId; void wdCallback() { Serial.println(WATCHDOG TIMEOUT! Resetting...); // 执行复位Arduino或触发系统复位STM32: NVIC_SystemReset() // delay(1000); // ESP.reset(); } void setup() { Serial.begin(9600); wdId timer.setInterval(10000, wdCallback); // 10秒超时 } void loop() { timer.run(); // ... 执行你的核心业务逻辑 ... doCriticalWork(); // 关键在业务逻辑完成后立即喂狗 timer.restartTimer(wdId); // 如果 doCriticalWork() 执行时间 10swdCallback 将被触发 }void deleteTimer(int timerId)显式释放指定timerId的槽位。适用场景动态创建/销毁定时器的高级应用如插件系统。setInterval创建的定时器若需永久停止且不再使用调用deleteTimer释放槽位为其他定时器腾出空间。注意setTimeout和setTimer在完成使命后会自动调用deleteTimer开发者通常无需手动干预。int getNumTimers()返回当前已被enabled的定时器槽位总数。用途监控系统资源使用情况辅助调试内存泄漏如set*调用远多于deleteTimer或验证定时器是否按预期启停。4. 与主流嵌入式框架的集成实践4.1 与 STM32 HAL 库集成裸机/FreeRTOS在 STM32CubeIDE 生成的 HAL 工程中NusabotSimpleTimer可无缝工作因其不依赖 Arduino 特定 API。millis()替代方案HAL 库本身不提供millis()。需自行实现一个基于HAL_GetTick()的弱符号函数HAL_GetTick()默认由 SysTick 中断每 1ms 更新// 在 main.c 或独立的 time_utils.c 中 #include stm32f4xx_hal.h extern uint32_t uwTick; // 弱符号定义允许被 HAL_GetTick() 覆盖 __weak uint32_t millis(void) { return uwTick; // HAL_GetTick() 返回值即为毫秒数 }FreeRTOS 集成在 FreeRTOS 任务中使用NusabotSimpleTimer时需注意单实例原则整个系统仍只需一个NusabotSimpleTimer实例由一个高优先级任务如timer_task负责调用run()。任务设计timer_task应设计为一个永不停止的循环其delay时间应远小于最短定时器间隔如设为 1ms以保证调度精度。// FreeRTOS 任务示例 void timerTask(void *pvParameters) { NusabotSimpleTimer timer; timer.setInterval(1000, ledToggle); // 1秒LED timer.setInterval(5000, sensorRead); // 5秒读传感器 for(;;) { timer.run(); // 高频轮询 vTaskDelay(1); // 微小延时避免占用全部CPU } }4.2 与 ESP-IDF (FreeRTOS) 集成ESP-IDF 提供了esp_timer_get_time()微秒级和xTaskGetTickCount()毫秒级基于 FreeRTOS tick。推荐使用后者以保持与millis()语义一致// 在 ESP-IDF 项目中 #include freertos/FreeRTOS.h #include freertos/task.h uint32_t millis(void) { return xTaskGetTickCount() * portTICK_PERIOD_MS; // 注意portTICK_PERIOD_MS 通常是 10ms需校准 // 更佳实践使用 esp_timer_get_time() / 1000LL }4.3 与 Zephyr RTOS 集成Zephyr 提供k_uptime_get()毫秒级和k_uptime_get_32()32位版本。直接将其包装为millis()#include zephyr/kernel.h uint32_t millis(void) { return k_uptime_get_32(); }5. 性能分析与最佳实践5.1 时间精度与延迟分析理论最小延迟run()函数本身的执行时间 millis()调用开销 所有已启用定时器的if判断开销。在 16MHz AVR 上单次run()通常 10μs。实际调度延迟主要由loop()的执行周期决定。若loop()平均耗时 5ms则定时器平均延迟为 2.5ms最大延迟接近 5ms。精度保障只要loop()执行频率显著高于最高定时器频率例如最高定时器为 100Hz (10ms)则loop()频率应 1kHz精度即可满足工业控制常见需求±1%。5.2 内存与 CPU 开销RAM每个定时器槽位约占用 16-20 字节取决于架构。MAX_TIMERS10时总 RAM 占用约 200 字节。Flash库代码体积极小编译后通常 1KB。CPUrun()的 CPU 占用与激活定时器数量成正比。10 个激活定时器在 16MHz MCU 上run()占用 CPU 0.1%。5.3 关键最佳实践总结run()必须高频调用将其置于loop()的第一行避免任何前置阻塞。回调函数务必轻量禁止delay(),Serial.print()除非缓冲区足够大且非阻塞复杂逻辑移至主循环。善用restartTimer实现看门狗这是提升系统鲁棒性的最简单有效手段。setTimeout/setTimer优于setIntervaldisable当只需执行一次或有限次时使用前者可自动清理资源。enable/disable优于deleteTimer/setInterval对于需要频繁启停的定时器启停操作比反复创建销毁更高效。volatile仅用于跨线程/中断共享变量在纯NusabotSimpleTimer回调中因无 ISRvolatile通常非必需除非变量也被其他任务或中断修改。6. 故障排查与常见陷阱定时器完全不触发检查timer.run()是否在loop()中被调用。检查set*调用是否返回-1槽位满增大MAX_TIMERS。检查回调函数签名是否为void func(void)无参数无返回值。定时器触发频率异常过快或过慢过快检查millis()是否被错误重定义或run()被意外高频调用如在中断中。过慢检查loop()中是否存在delay()或长耗时操作导致run()调用间隔过大。回调函数中Serial输出乱码或丢失Serial初始化 (Serial.begin()) 必须在setup()中完成且早于任何定时器设置。避免在回调中进行大量Serial.print()改用sprintf缓冲后一次性输出或改用更高效的日志库。restartTimer未生效确认timerId是setInterval返回的有效值且未被deleteTimer销毁。确认restartTimer调用位置在run()之前还是之后应在run()之后调用以确保本次run()不触发下次才重新计时。一个在 STM32F103C8T6Blue Pill上稳定运行了三年的工业数据采集节点其核心心跳与传感器轮询逻辑完全构建于 NusabotSimpleTimer 之上。它从未因定时器故障导致数据丢失其代码的清晰度使得新工程师能在半小时内理解并修改所有时间相关逻辑。这印证了其设计哲学的价值在嵌入式世界有时最强大的工具恰恰是那个你永远不必担心它会出错的工具。