utime - 时间相关功能

2024-11-09

utime模块用于获取当前时间、测量时间间隔和休眠。该模块实现相应CPython模块的子集。更多信息请参阅CPython文档：time

示例：

import utime
import log

# 设置日志输出级别
log.basicConfig(level=log.INFO)
time_log = log.getLogger("LocalTime")

if __name__ == '__main__':
    # 获取本地时间，返回元组
    tupe_t = utime.localtime()
    time_log.info(tupe_t)
    # 返回当前时间戳，参数为元组
    t = utime.mktime(utime.localtime())
    time_log.info(t)
    # 休眠sleep示例
    for i in [0, 1, 2, 3, 4, 5]:
        utime.sleep(1)   # 休眠(单位 m)
        time_log.info(i)

    for i in [0, 1, 2, 3, 4, 5]:
        utime.sleep_ms(1000)   # 休眠(单位 ms)
        time_log.info(i)

当前时间相关功能

utime.localtime

utime.localtime()
utime.localtime(secs)

如有参数，secs需为UTC时间戳，此接口将UTC时间戳转换为UTC日期时间加8时区后的日期时间格式。

参数描述：

  • 无参数。返回本地日期时间，即UTC日期时间加设备所设置的时区后的日期时间。
  • 有参数，secs-int类型，单位秒。返回UTC日期时间加8时区后的日期时间。

返回值描述：

(year, month, day, hour, minute, second, weekday, yearday)-类型为元组，包含了年、月、日、时、分、秒、星期、一年中第几天。当提供参数secs时，返回转换后的时间。当参数secs没有提供时，则返回本地RTC的时间。返回值含义如下：

元组成员 范围及类型 含义
year int型 年份
month int型，1~12 月份
day int型，1~31 日，当月多少号
hour int型，0~23 小时
minute int型，0~59 分钟
second int型，0~59 秒
weekday int型，周一到周日是0~6 星期
yearday int型 一年中的第多少天

注意

有参数的模式下，如期望参数secs转换为设备所设置的时区的本地时间，请调用utime.localtime_ex(secs)接口。

示例：

>>> import utime
>>> utime.localtime()
(2020, 9, 29, 8, 54, 42, 1, 273)
>>> utime.localtime(646898736)
(1990, 7, 2, 14, 5, 36, 0, 183)

utime.localtime_ex

utime.localtime_ex()
utime.localtime_ex(secs)

如有参数，secs需为UTC时间戳。

参数描述：

  • 无参数。返回当前本地时间(UTC+时区)。
  • 有参数，secs-int类型，单位秒。返回secs代表的UTC日期时间加设备设置的时区后的日期时间，例如，当前设备时区为3，secs转成UTC时间日期为2024-07-09 16：30：00，此函数返回时间为，2024-07-09 19：30：00 。

返回值描述：

(year, month, day, hour, minute, second, weekday, yearday)-类型为元组，包含了年、月、日、时、分、秒、星期、一年中第几天。当提供参数secs时，返回转换后的时间。当参数secs没有提供时，则返回本地RTC的时间。返回值含义如下：

元组成员 范围及类型 含义
year int型 年份
month int型，1~12 月份
day int型，1~31 日，当月多少号
hour int型，0~23 小时
minute int型，0~59 分钟
second int型，0~59 秒
weekday int型，周一到周日是0~6 星期
yearday int型 一年中的第多少天

示例：

>>> import utime
>>> utime.setTimeZone(3)
0
>>> utime.getTimeZone()
3
>>> date=utime.localtime_ex()
>>> date
(2024, 7, 9, 13, 59, 30, 1, 191)
>>> utime.mktime_ex(date)
1720522770
>>> utime.localtime_ex(1720522770)
(2024, 7, 9, 13, 59, 30, 1, 191)
>>>

utime.mktime

utime.mktime(date)

date需为UTC日期时间加8时区后的日期时间，此接口将8时区的日期时间转换为UTC时间戳。

参数描述：

  • date-日期格式的时间，类型为元组，格式：(year, month, mday, hour, minute, second, weekday, yearday)。

返回值描述：

int类型。

注意

如date不为8时区日期时间，期望按照模组的本地时间转换成UTC时间戳，请调用接口utime.mktime_ex(date)。

示例：

>>> import utime
>>> date = (2020, 9, 29, 8, 54, 42, 1, 273)
>>> utime.mktime(date)
1601340882

utime.mktime_ex

utime.mktime_ex(date)

date需为设备的本地时间，此接口将date转换为UTC时间戳。例如，当前时区为3，输入日期为2024-07-09 19：30：00，此函数将返回1720542600，此时间戳为UTC时间戳，UTC时间为2024-07-09 16：30：00。

参数描述：

  • date-日期格式的时间，类型为元组，格式：(year, month, mday, hour, minute, second, weekday, yearday)。

返回值描述：

int类型。
示例：

>>> import utime
>>> utime.setTimeZone(3)
0
>>> utime.getTimeZone()
3
>>> date=utime.localtime_ex()
>>> date
(2024, 7, 9, 13, 59, 30, 1, 191)
>>> utime.mktime_ex(date)
1720522770
>>> utime.localtime_ex(1720522770)
(2024, 7, 9, 13, 59, 30, 1, 191)
>>>

utime.time

utime.time()

返回自设备开机以来的秒数。

返回值描述：

int类型。

utime.getTimeZone

utime.getTimeZone()

获取当前时区。

返回值描述：

int类型，单位小时，范围[-12, 12]，负值表示西时区，正值表示东时区，0表示零时区。

utime.setTimeZone

utime.setTimeZone(offset)

设置时区。设置时区后，本地时间会随之变化为对应时区的时间。

参数描述：

  • int类型，单位小时，范围[-12, 12]，负值表示西时区，正值表示东时区，0表示零时区。

返回值描述：

int类型，成功返回0，失败抛异常。

utime.getTimeZoneEx

utime.getTimeZoneEx()

获取当前时区（增强型），精度更高，可获取非整数时区。

返回值描述：

float类型，单位小时，范围[-12.0, 12.0]，负值表示西时区，正值表示东时区，0.0表示零时区。

增强型时区读取/设置接口须成对使用，如使用原有的时区接口读取非整数时区，会造成精度丢失。当前仅 EC200A 系列支持该功能。

utime.setTimeZoneEx

utime.setTimeZoneEx(offset)

设置时区（增强型），精度更高，可设置非整数时区。设置时区后，本地时间会随之变化为对应时区的时间。

参数描述：

  • float类型，单位小时，范围[-12.0, 12.0]，最大精度为0.25小时（即参数须为0.25的整数倍）负值表示西时区，正值表示东时区，0.0表示零时区。

返回值描述：

int类型，成功返回0，失败抛异常。

增强型时区读取/设置接口须成对使用，如使用原有的时区接口读取非整数时区，会造成精度丢失。当前仅 EC200A 系列支持该功能。

测量时间间隔相关功能

utime.ticks_ms

utime.ticks_ms()

返回不断递增的毫秒计数器，在超过0x3FFFFFFF值后会重新计数。

返回值描述：

int类型，毫秒计数值，计数值本身无特定意义，只适合用在 ticks_diff()函数中。

utime.ticks_us

utime.ticks_us()

返回不断递增的微秒计数器，在超过0x3FFFFFFF值后会重新计数。

返回值描述：

int类型，微秒计数值，计数值本身无特定意义，只适合用在 ticks_diff()函数中。

utime.ticks_cpu

utime.ticks_cpu()

返回不断递增的cpu计数器，单位不确定，取决于硬件平台底层的时钟。

返回值描述：

int类型，计数值，计数值本身无特定意义，只适合用在 ticks_diff()函数中。

utime.ticks_diff

utime.ticks_diff(ticks1, ticks2)

计算两次调用ticks_ms， ticks_us，或 ticks_cpu之间的时间间隔。因为ticks_xxx这些函数的计数值可能会回绕，所以不能直接相减，需要使用 ticks_diff函数。通常用法是在带超时的轮询事件中调用。

参数描述：

  • ticks1-int类型，第二次调用ticks_ms， ticks_us，或 ticks_cpu获取的tick值。
  • ticks2-int类型，第一次调用ticks_ms， ticks_us，或 ticks_cpu获取的tick值。

返回值描述：

int类型，时间间隔，两次调用ticks_ms， ticks_us，或 ticks_cpu之间的时间间隔。单位和传入的ticks2和ticks1的单位一致。

ticks2和ticks1的顺序不能颠倒，否则结果无法确定。且这个函数不要用在计算很长的时间间隔，具体限制为ticks2和ticks1的tick差值不能超过0x1FFFFFFF，否则结果无法确定。

示例：

import utime
start = utime.ticks_us()
while True:
    if utime.ticks_diff(utime.ticks_us(), start) > 500:
        print('Timeout')
        break

休眠相关功能

utime.sleep

utime.sleep(seconds)

休眠给定秒数的时间。

参数描述：

  • seconds-int类型，休眠的时长，单位秒。

utime.sleep_ms

utime.sleep_ms(ms)

休眠给定毫秒数的时间。

参数描述：

  • ms-int类型，休眠的时长，单位毫秒。

utime.sleep_us

utime.sleep_us(us)

休眠给定微秒数的时间。

参数描述：

  • us-int类型，休眠的时长，单位微秒。

utime.sleep、utime.sleep_ms及utime.sleep_us函数的调用会导致程序休眠阻塞。