注意

这是最新开发分支配套的文档，可能包含已发布版本中尚未提供的功能。如果您要查看特定版本的文档，请使用左侧的下拉菜单并选择所需要的版本。

Timer 使用教程

什么是 Timer？

machine.Timer 用于在超时后执行回调函数。K230 提供硬件定时器和软件定时器，适合单次延迟、周期采样、状态上报和超时控制等场景。

Timer 的两个概念需要区分：

• 定时器来源由编号决定：0 至 5 是硬件定时器，-1 是软件定时器。

• 回调执行方式由 hard 决定：hard=True 在中断上下文执行，hard=False 在普通 Python 上下文执行。

这两个选择相互独立。硬件定时器配合 hard=False 仍然由硬件计时，只是 Python 回调会延后执行。

K230 Timer 特性

特性	描述
硬件定时器数量	6 个，编号为 0 至 5
软件定时器	1 个，编号为 -1，不占用硬件定时器资源
最小 period	5 ms
支持模式	单次模式（Timer.ONE_SHOT）、周期模式（Timer.PERIODIC）
回调方式	中断上下文（hard=True）或普通 Python 上下文（hard=False）

推荐用法：普通 Python 回调

对于打印、传感器读取、文件或网络操作等普通 Python 逻辑，请使用 hard=False。下面的示例先执行一次单次回调，再等待周期回调执行 3 次后释放定时器。

from machine import Timer
import time

count = 0


def one_shot_callback(timer):
    print("one-shot callback")


def periodic_callback(timer):
    global count
    count += 1
    print("periodic callback", count)


# -1 表示软件定时器；也可使用 0 至 5 选择硬件定时器
tim = Timer(-1)

# ms 后触发一次
tim.init(
    period=100,
    mode=Timer.ONE_SHOT,
    callback=one_shot_callback,
    hard=False,
)
time.sleep_ms(150)

# 每秒触发一次，直到已经收到 3 次回调
tim.init(
    freq=1,
    mode=Timer.PERIODIC,
    callback=periodic_callback,
    hard=False,
)
while count < 3:
    # 让解释器处理已调度的回调，避免忙等。
    time.sleep_ms(10)

tim.deinit()

不要用 time.sleep(3) 后立即调用 deinit() 来断言 1 Hz 回调一定执行 3 次。第三次到期可能恰好与 sleep() 返回和 deinit() 竞争，尤其是软件定时器或 hard=False 回调还可能存在调度延迟。需要等待指定次数时，应像上例一样使用计数器、标志位或事件同步。

参数说明

参数名	类型	说明
index	整数	-1 为软件定时器；0 至 5 为硬件定时器。
period	整数（ms）	定时时间，最小为 5 ms。
freq	整数（Hz）	定时频率。设置后优先于 period，实际周期按 1000 // freq 毫秒计算。
mode	常量	Timer.ONE_SHOT（单次）或 Timer.PERIODIC（周期）。
callback	函数	定时器到期时调用，接收一个 Timer 参数。
hard	布尔值	仅关键字参数，默认为 True。决定回调的 Python 执行上下文。

回调方式

hard=False：普通 Python 上下文

到期事件先由定时器中断处理，再将 Python 回调安排到普通 Python 上下文执行。

• 可以使用 print()，并执行会分配内存的普通 Python 代码。

• 回调执行时间受系统调度和 Python 负载影响，不是硬实时。

• 同一个定时器在回调等待执行期间只保留一个待执行任务；定时器到期过快时，多个事件可能合并或丢失。

这是大多数 Python 应用的推荐选择。

hard=True：中断上下文

这是默认值。Python 回调由定时器中断直接调用，延迟较低，但限制严格：

• 回调必须非常短。

• 不要调用 print()、sleep()、阻塞 I/O、网络或文件系统 API。

• 不要创建 Python 对象或执行可能分配内存的操作。

违反这些限制可能导致异常、回调丢失或系统不稳定。需要复杂处理时，可在 hard=True 回调中仅设置一个预先准备好的状态，再由主循环处理；通常直接使用 hard=False 更合适。

模式详解

单次模式 Timer.ONE_SHOT

tim.init(period=100, mode=Timer.ONE_SHOT, callback=func, hard=False)

• 定时器只触发一次。

• 到期后自动停止。

周期模式 Timer.PERIODIC

tim.init(freq=2, mode=Timer.PERIODIC, callback=func, hard=False)

• 以配置的周期持续触发，直到重新初始化或调用 deinit()。

• freq=2 对应约 500 ms 的周期。

资源和生命周期

• 每个硬件定时器编号只能被一个 Timer 使用。

• Timer(-1) 只有一个软件定时器实例；重复创建会获得同一个对象。

• 对运行中的定时器再次调用 init() 会替换原有配置。

• deinit() 会停止定时器并释放资源。释放后的对象不能再次调用 init()，需要重新创建 Timer。

应用场景举例

• 周期采样：读取传感器数据

• 超时控制：任务执行超时处理

• 系统心跳：周期更新状态或输出日志

• 低延迟的简单中断操作：使用 hard=True，并保持回调短小且不分配内存

提示

Timer 模块完整参数说明请参考 K230 Timer API 文档