70 timer-底层定时器
一、概述
timer 是 LuatOS 的内核基础库，只提供两个「忙等」式延时接口：timer.mdelay 毫秒级、timer.udelay 微秒级。
这两个接口执行期间 不会 让出 CPU：sys 的协程调度、socket 收包、串口收发、音频播放这些依赖消息机制的工作全部停摆。因此本库在业务代码里几乎不该出现，除非你非常清楚自己在做什么——比如驱动时序里必须卡住几个微秒、或者在 sys.run() 之前做一次极短的初始化等待。
正常业务里的「等一会儿」请一律用 sys.wait / sys.waitUntil，它们会让出 CPU，不影响其它任务；需要定时器就用 sys.timerStart / sys.timerLoopStart，而不是用 mdelay 拼循环。
二、核心示例
-- 仅演示：单总线类器件要求拉低后保持 10us 以上，用 udelay 卡时序
gpio.setup(1, 0)
gpio.set(1, 0)
timer.udelay(20)
gpio.set(1, 1)
-- 反例：想在业务里「等 100ms」不要这么写，会卡住整个 sys
-- timer.mdelay(100)
sys.wait(100)
三、常量详解
本库没有对外常量。
四、函数详解
4.1 timer.mdelay(timeout)
功能
硬阻塞指定毫秒数，期间 CPU 一直被占用。
参数
timeout
参数含义：阻塞时长
数据类型：number
取值范围：1~1023，单位毫秒；超出范围时接口直接返回、不做任何延时
是否必选：是
注意事项：上限 1024ms（不含），实际使用强烈建议不要超过 200ms，越久越容易丢包、丢事件。
返回值
无返回值。
示例
timer.mdelay(10)
注意事项
- 阻塞期间没有任何 Lua 代码执行，包括底层消息处理机制，联网业务下长时间阻塞会掉线；
- 需要「等一会儿再继续」请用
sys.wait(ms)，它会让出 CPU 给其它任务； - 不要在中断回调、socket 回调里调用，容易把上层业务拖死。
4.2 timer.udelay(timeout)
功能
硬阻塞指定微秒数，用于对时序敏感的短延时。该接口在 2023.05.18 加入。
参数
timeout
参数含义：阻塞时长
数据类型：number
取值范围：1~3000，单位微秒；超出范围直接返回
是否必选：是
注意事项：实际阻塞时长有波动，不要拿它当精密计时。
返回值
无返回值。
示例
timer.udelay(10)
注意事项
- 微秒级延时受调度与中断影响，实测值会比设定值偏大，做时序余量时按最坏情况算；
- 单次上限 3000us，更长的等待请用
timer.mdelay或sys.wait； - 同样不建议在业务主流程里使用。
五、产品支持说明
timer 是内核基础库，各型号 LuatOS 固件基本都包含，具体以对应型号的固件支持列表为准：