庐山派MicroPython utime模块API详解从时间同步到高精度计时大家好我是老李一个在嵌入式领域摸爬滚打多年的工程师。最近在用庐山派开发板做一个小项目需要精确控制传感器采样间隔还要计算程序循环的帧率这就离不开对时间模块的深入理解。庐山派的MicroPython提供了utime模块功能很全但官方文档比较简洁很多朋友反映用起来有点懵。今天我就结合自己的使用经验给大家手把手拆解utime模块的每一个API。无论你是想从网络同步时间还是需要毫秒、微秒级的精准延时或者是测量代码执行时间、计算FPS看完这篇你都能搞定。1. 时间基础与庐山派的RTC在开始敲代码之前咱们得先搞清楚几个基本概念这样后面用起来才不会糊涂。什么是纪元时间在计算机世界里需要一个公认的“时间起点”这个起点就是纪元Epoch。对于庐山派这样的Unix-like系统这个起点是1970年1月1日 00:00:00 UTC。utime.time()函数返回的秒数就是从这一刻开始计算的。庐山派的实时时钟RTCRTC可以理解成板子上的一块小电池供电的“电子表”即使系统断电它也能继续走时。庐山派开发板是支持RTC的这点很重要这意味着我们可以设置一个准确的日期和时间系统重启后时间也不会归零。注意有些开发板没有RTC硬件所以utime.ntp_sync()这类函数对它们无效。但庐山派是支持的大家可以放心用。维护这个“电子表”的校准是底层操作系统RTOS的活儿。MicroPython不负责调时间它只是通过操作系统提供的接口去“看时间”。所以我们通过utime模块设置或获取的时间最终都是操作系统在管理。2. 获取与转换日历时间这部分函数帮你处理我们人类熟悉的“年月日时分秒”。2.1utime.localtime([secs])把秒数变成日期元组这个函数非常常用。它能把一个从纪元开始计算的秒数比如utime.time()返回的值转换成一个包含8个信息的元组。import utime # 获取当前RTC时间并以元组形式展示 current_tuple utime.localtime() print(current_tuple) # 输出可能类似(2023, 10, 27, 15, 30, 45, 4, 300)如果不传参数它就返回RTC的当前时间。你也可以传入一个秒数让它转换指定的时间点。元组里每个位置的含义我给大家列个表一目了然索引含义范围例子0年份带世纪如 202320231月份1-12102日月中的天数1-31273小时0-23154分钟0-59305秒0-59456星期几0周一到6周日4代表周五7一年中的第几天1-3663002.2utime.mktime(tuple)把日期元组变回秒数这个函数是localtime()的“反函数”。当你有一个日期元组时可以用它计算出对应的纪元秒数。import utime # 定义一个时间点2023年10月27日 15点30分45秒 my_time_tuple (2023, 10, 27, 15, 30, 45, 4, 300) seconds_since_epoch utime.mktime(my_time_tuple) print(对应的秒数, seconds_since_epoch)2.3utime.time()获取当前的纪元秒数这个函数最简单也最核心。它直接返回从1970年1月1日到现在经过的秒数。import utime current_seconds utime.time() print(自1970年以来的秒数, current_seconds)重要提示如果庐山派的RTC没有被设置过比如新板子第一次上电这个函数返回的将是系统启动以来经过的秒数而不是真实的日历时间。所以我们需要先同步时间。3. 同步网络时间NTP想让庐山派知道现在几点几分最方便的办法就是联网从网络时间服务器NTP同步。3.1utime.ntp_sync()一键同步时间这个函数用起来超级简单但前提是你的庐山派必须已经连接到互联网比如通过Wi-Fi。import utime import network # 假设你已经配置并连接了Wi-Fi # wifi network.WLAN(network.STA_IF) # wifi.active(True) # wifi.connect(你的SSID, 你的密码) # 联网后同步时间 sync_result utime.ntp_sync() if sync_result: print(时间同步成功) print(当前时间, utime.localtime()) else: print(时间同步失败请检查网络或开发板是否支持RTC。)函数会返回一个布尔值True表示同步成功False表示失败。对于庐山派失败通常是因为网络没连通。同步成功后utime.time()和utime.localtime()返回的就是准确的北京时间了。我一般会在系统启动后网络连接成功的回调里调用一次ntp_sync()这样就能保证设备时间一直是准的。4. 精准延时让程序“等一会儿”做控制、读传感器经常需要让程序暂停一段时间。utime提供了三个不同精度的延时函数。4.1utime.sleep(seconds)秒级延时这是最常用的延时参数是秒可以是整数也可以是小数。import utime print(开始) utime.sleep(2.5) # 程序在这里暂停2.5秒 print(2.5秒后)4.2utime.sleep_ms(ms)和utime.sleep_us(us)毫秒/微秒级延时对于嵌入式开发秒级延时太粗糙了。我们经常需要毫秒甚至微秒级的精准控制。import utime # 毫秒级延时让LED闪烁 while True: led.on() utime.sleep_ms(500) # 亮500毫秒 led.off() utime.sleep_ms(500) # 灭500毫秒 # 微秒级延时用于非常精确的时序如驱动某些传感器 def send_start_signal(): pin.high() utime.sleep_us(10) # 维持高电平10微秒 pin.low()实战经验虽然sleep()支持小数来实现毫秒延时如sleep(0.1)但为了代码清晰和更好的兼容性我强烈建议你统一使用sleep_ms()和sleep_us()来处理亚秒级延时。这样一看就知道是精确延时而不是大概等一会儿。5. 高精度计时与性能测量有时候我们不光要“等”还要“测”——测一段代码跑了多久算算循环的帧率。这就需要用到ticks系列函数。5.1ticks_ms()和ticks_us()获取系统嘀嗒数这两个函数返回一个不断递增的计数器分别以毫秒和微秒为单位。这个计数器的起点是随机的系统内部某个时刻而且计数值会回绕增加到最大值后归零。import utime start_ms utime.ticks_ms() # 记录开始时刻的嘀嗒数 # ... 执行一些耗时操作 ... end_ms utime.ticks_ms() # 记录结束时刻的嘀嗒数 # 直接相减可能出错因为计数器可能回绕了 # elapsed end_ms - start_ms # 错误做法5.2ticks_diff(ticks1, ticks2)正确处理回绕的时间差由于计数器会回绕直接相减计算时间差是危险的。ticks_diff()就是用来安全计算两个ticks值之差的它会自动处理回绕情况。参数顺序很重要ticks_diff(新时间, 旧时间)import utime start utime.ticks_ms() utime.sleep_ms(1500) # 模拟一个耗时操作 end utime.ticks_ms() # 正确计算耗时 elapsed_ms utime.ticks_diff(end, start) # 新时间在前旧时间在后 print(f操作耗时{elapsed_ms} 毫秒)5.3ticks_add(ticks, delta)计算未来的时间点这个函数用于设定一个未来的超时时间点。比如你想设定一个“从现在开始100毫秒后”的截止时间。import utime timeout_point utime.ticks_add(utime.ticks_ms(), 100) # 100毫秒后的时间点 while utime.ticks_diff(timeout_point, utime.ticks_ms()) 0: # 在这个循环里执行任务直到100毫秒超时 print(等待超时...) utime.sleep_ms(10) print(时间到)5.4ticks_cpu()最高精度的计数器这个函数提供与CPU时钟相关的最髙分辨率计数用于极端情况下的高精度基准测试或紧凑的实时循环。对于大多数应用ticks_us()已经足够精确了。6. 计算帧率FPS的利器clock类如果你在做图形显示、动画或者只是想监控主循环的速度utime.clock()类是你的好帮手。6.1 基本使用测量帧率clock类用起来非常直观看下面的例子就明白了import utime # 创建一个时钟对象 fps_clock utime.clock() while True: # 在每一帧开始的时候标记一下 fps_clock.tick() # 这里是你的主循环代码比如刷新屏幕、处理数据 # ... utime.sleep_ms(16) # 模拟一帧耗时约16毫秒接近60FPS # 计算并打印上一帧的帧率 current_fps fps_clock.fps() print(fFPS: {current_fps:.2f})tick()方法记录当前时间点fps()方法则根据上一次tick()被调用的时间间隔计算出帧率Frame Per Second。这个在调试游戏或动画流畅度时特别有用。6.2 更多方法重置与平均耗时import utime clock utime.clock() for i in range(5): clock.tick() utime.sleep_ms(i * 10) # 每轮循环睡眠时间递增 print(f本轮FPS: {clock.fps()} 平均每帧耗时: {clock.avg()} 毫秒) # 重置时钟清空所有记录 clock.reset() print(时钟已重置)reset(): 清空时钟对象内部的所有计时标记让它回到初始状态。avg(): 计算调用tick()之间的平均时间间隔单位毫秒。这对于评估循环的稳定性很有帮助。7. 实战技巧与常见坑点结合我自己的项目经验分享几个使用utime模块的实战技巧1. 时间同步的最佳实践不要在主循环里频繁调用ntp_sync()这会产生大量网络请求。正确的做法是在系统启动、网络连接成功后同步一次之后可以每隔几小时或每天同步一次。2. 延时函数的阻塞性sleep()、sleep_ms()、sleep_us()都是阻塞式的。调用它们时整个程序包括其他任务都会停下来等待。在需要同时处理多个任务的场景比如一边读传感器一边响应网络请求要考虑使用非阻塞的定时方式比如检查ticks_ms()是否超时。3. 测量短时间间隔用ticks_us()如果你要测量的代码段执行时间非常短几十微秒到几毫秒一定要用ticks_us()来获取开始和结束点并用ticks_diff()计算差值。用ticks_ms()的话精度不够可能测出来总是0。4. 关于ticks的回绕周期不同平台ticks计数器的位数和回绕周期不同。在庐山派上你不需要太担心因为ticks_diff()已经帮你处理好了。但如果你自己写比较逻辑一定要用ticks_diff()不要直接比较两个ticks值的大小。好了关于庐山派MicroPython的utime模块核心的用法和坑点就讲这么多。从设置时间、精准延时到性能测量这些功能覆盖了嵌入式开发中大部分与时间相关的需求。大家在实际项目中多练练手很快就能熟练掌握了。如果遇到问题回头看看这篇文章或者去社区里和大家交流总能找到解决办法。
1.3 庐山派MicroPython utime模块API详解：从时间同步到高精度计时
发布时间：2026/7/6 7:50:01
庐山派MicroPython utime模块API详解从时间同步到高精度计时大家好我是老李一个在嵌入式领域摸爬滚打多年的工程师。最近在用庐山派开发板做一个小项目需要精确控制传感器采样间隔还要计算程序循环的帧率这就离不开对时间模块的深入理解。庐山派的MicroPython提供了utime模块功能很全但官方文档比较简洁很多朋友反映用起来有点懵。今天我就结合自己的使用经验给大家手把手拆解utime模块的每一个API。无论你是想从网络同步时间还是需要毫秒、微秒级的精准延时或者是测量代码执行时间、计算FPS看完这篇你都能搞定。1. 时间基础与庐山派的RTC在开始敲代码之前咱们得先搞清楚几个基本概念这样后面用起来才不会糊涂。什么是纪元时间在计算机世界里需要一个公认的“时间起点”这个起点就是纪元Epoch。对于庐山派这样的Unix-like系统这个起点是1970年1月1日 00:00:00 UTC。utime.time()函数返回的秒数就是从这一刻开始计算的。庐山派的实时时钟RTCRTC可以理解成板子上的一块小电池供电的“电子表”即使系统断电它也能继续走时。庐山派开发板是支持RTC的这点很重要这意味着我们可以设置一个准确的日期和时间系统重启后时间也不会归零。注意有些开发板没有RTC硬件所以utime.ntp_sync()这类函数对它们无效。但庐山派是支持的大家可以放心用。维护这个“电子表”的校准是底层操作系统RTOS的活儿。MicroPython不负责调时间它只是通过操作系统提供的接口去“看时间”。所以我们通过utime模块设置或获取的时间最终都是操作系统在管理。2. 获取与转换日历时间这部分函数帮你处理我们人类熟悉的“年月日时分秒”。2.1utime.localtime([secs])把秒数变成日期元组这个函数非常常用。它能把一个从纪元开始计算的秒数比如utime.time()返回的值转换成一个包含8个信息的元组。import utime # 获取当前RTC时间并以元组形式展示 current_tuple utime.localtime() print(current_tuple) # 输出可能类似(2023, 10, 27, 15, 30, 45, 4, 300)如果不传参数它就返回RTC的当前时间。你也可以传入一个秒数让它转换指定的时间点。元组里每个位置的含义我给大家列个表一目了然索引含义范围例子0年份带世纪如 202320231月份1-12102日月中的天数1-31273小时0-23154分钟0-59305秒0-59456星期几0周一到6周日4代表周五7一年中的第几天1-3663002.2utime.mktime(tuple)把日期元组变回秒数这个函数是localtime()的“反函数”。当你有一个日期元组时可以用它计算出对应的纪元秒数。import utime # 定义一个时间点2023年10月27日 15点30分45秒 my_time_tuple (2023, 10, 27, 15, 30, 45, 4, 300) seconds_since_epoch utime.mktime(my_time_tuple) print(对应的秒数, seconds_since_epoch)2.3utime.time()获取当前的纪元秒数这个函数最简单也最核心。它直接返回从1970年1月1日到现在经过的秒数。import utime current_seconds utime.time() print(自1970年以来的秒数, current_seconds)重要提示如果庐山派的RTC没有被设置过比如新板子第一次上电这个函数返回的将是系统启动以来经过的秒数而不是真实的日历时间。所以我们需要先同步时间。3. 同步网络时间NTP想让庐山派知道现在几点几分最方便的办法就是联网从网络时间服务器NTP同步。3.1utime.ntp_sync()一键同步时间这个函数用起来超级简单但前提是你的庐山派必须已经连接到互联网比如通过Wi-Fi。import utime import network # 假设你已经配置并连接了Wi-Fi # wifi network.WLAN(network.STA_IF) # wifi.active(True) # wifi.connect(你的SSID, 你的密码) # 联网后同步时间 sync_result utime.ntp_sync() if sync_result: print(时间同步成功) print(当前时间, utime.localtime()) else: print(时间同步失败请检查网络或开发板是否支持RTC。)函数会返回一个布尔值True表示同步成功False表示失败。对于庐山派失败通常是因为网络没连通。同步成功后utime.time()和utime.localtime()返回的就是准确的北京时间了。我一般会在系统启动后网络连接成功的回调里调用一次ntp_sync()这样就能保证设备时间一直是准的。4. 精准延时让程序“等一会儿”做控制、读传感器经常需要让程序暂停一段时间。utime提供了三个不同精度的延时函数。4.1utime.sleep(seconds)秒级延时这是最常用的延时参数是秒可以是整数也可以是小数。import utime print(开始) utime.sleep(2.5) # 程序在这里暂停2.5秒 print(2.5秒后)4.2utime.sleep_ms(ms)和utime.sleep_us(us)毫秒/微秒级延时对于嵌入式开发秒级延时太粗糙了。我们经常需要毫秒甚至微秒级的精准控制。import utime # 毫秒级延时让LED闪烁 while True: led.on() utime.sleep_ms(500) # 亮500毫秒 led.off() utime.sleep_ms(500) # 灭500毫秒 # 微秒级延时用于非常精确的时序如驱动某些传感器 def send_start_signal(): pin.high() utime.sleep_us(10) # 维持高电平10微秒 pin.low()实战经验虽然sleep()支持小数来实现毫秒延时如sleep(0.1)但为了代码清晰和更好的兼容性我强烈建议你统一使用sleep_ms()和sleep_us()来处理亚秒级延时。这样一看就知道是精确延时而不是大概等一会儿。5. 高精度计时与性能测量有时候我们不光要“等”还要“测”——测一段代码跑了多久算算循环的帧率。这就需要用到ticks系列函数。5.1ticks_ms()和ticks_us()获取系统嘀嗒数这两个函数返回一个不断递增的计数器分别以毫秒和微秒为单位。这个计数器的起点是随机的系统内部某个时刻而且计数值会回绕增加到最大值后归零。import utime start_ms utime.ticks_ms() # 记录开始时刻的嘀嗒数 # ... 执行一些耗时操作 ... end_ms utime.ticks_ms() # 记录结束时刻的嘀嗒数 # 直接相减可能出错因为计数器可能回绕了 # elapsed end_ms - start_ms # 错误做法5.2ticks_diff(ticks1, ticks2)正确处理回绕的时间差由于计数器会回绕直接相减计算时间差是危险的。ticks_diff()就是用来安全计算两个ticks值之差的它会自动处理回绕情况。参数顺序很重要ticks_diff(新时间, 旧时间)import utime start utime.ticks_ms() utime.sleep_ms(1500) # 模拟一个耗时操作 end utime.ticks_ms() # 正确计算耗时 elapsed_ms utime.ticks_diff(end, start) # 新时间在前旧时间在后 print(f操作耗时{elapsed_ms} 毫秒)5.3ticks_add(ticks, delta)计算未来的时间点这个函数用于设定一个未来的超时时间点。比如你想设定一个“从现在开始100毫秒后”的截止时间。import utime timeout_point utime.ticks_add(utime.ticks_ms(), 100) # 100毫秒后的时间点 while utime.ticks_diff(timeout_point, utime.ticks_ms()) 0: # 在这个循环里执行任务直到100毫秒超时 print(等待超时...) utime.sleep_ms(10) print(时间到)5.4ticks_cpu()最高精度的计数器这个函数提供与CPU时钟相关的最髙分辨率计数用于极端情况下的高精度基准测试或紧凑的实时循环。对于大多数应用ticks_us()已经足够精确了。6. 计算帧率FPS的利器clock类如果你在做图形显示、动画或者只是想监控主循环的速度utime.clock()类是你的好帮手。6.1 基本使用测量帧率clock类用起来非常直观看下面的例子就明白了import utime # 创建一个时钟对象 fps_clock utime.clock() while True: # 在每一帧开始的时候标记一下 fps_clock.tick() # 这里是你的主循环代码比如刷新屏幕、处理数据 # ... utime.sleep_ms(16) # 模拟一帧耗时约16毫秒接近60FPS # 计算并打印上一帧的帧率 current_fps fps_clock.fps() print(fFPS: {current_fps:.2f})tick()方法记录当前时间点fps()方法则根据上一次tick()被调用的时间间隔计算出帧率Frame Per Second。这个在调试游戏或动画流畅度时特别有用。6.2 更多方法重置与平均耗时import utime clock utime.clock() for i in range(5): clock.tick() utime.sleep_ms(i * 10) # 每轮循环睡眠时间递增 print(f本轮FPS: {clock.fps()} 平均每帧耗时: {clock.avg()} 毫秒) # 重置时钟清空所有记录 clock.reset() print(时钟已重置)reset(): 清空时钟对象内部的所有计时标记让它回到初始状态。avg(): 计算调用tick()之间的平均时间间隔单位毫秒。这对于评估循环的稳定性很有帮助。7. 实战技巧与常见坑点结合我自己的项目经验分享几个使用utime模块的实战技巧1. 时间同步的最佳实践不要在主循环里频繁调用ntp_sync()这会产生大量网络请求。正确的做法是在系统启动、网络连接成功后同步一次之后可以每隔几小时或每天同步一次。2. 延时函数的阻塞性sleep()、sleep_ms()、sleep_us()都是阻塞式的。调用它们时整个程序包括其他任务都会停下来等待。在需要同时处理多个任务的场景比如一边读传感器一边响应网络请求要考虑使用非阻塞的定时方式比如检查ticks_ms()是否超时。3. 测量短时间间隔用ticks_us()如果你要测量的代码段执行时间非常短几十微秒到几毫秒一定要用ticks_us()来获取开始和结束点并用ticks_diff()计算差值。用ticks_ms()的话精度不够可能测出来总是0。4. 关于ticks的回绕周期不同平台ticks计数器的位数和回绕周期不同。在庐山派上你不需要太担心因为ticks_diff()已经帮你处理好了。但如果你自己写比较逻辑一定要用ticks_diff()不要直接比较两个ticks值的大小。好了关于庐山派MicroPython的utime模块核心的用法和坑点就讲这么多。从设置时间、精准延时到性能测量这些功能覆盖了嵌入式开发中大部分与时间相关的需求。大家在实际项目中多练练手很快就能熟练掌握了。如果遇到问题回头看看这篇文章或者去社区里和大家交流总能找到解决办法。
