utime - Time

The utime module loosely follows CPython’s time module, but is heavily stripped down. Instead, it has a few time related functions which are not in CPython but wouldn’t fit anywhere else in our implementation. Most prominently, this is the utime.alarm() function for setting an RTC alarm.

Like all other u-name modules, utime can also imported using the standard import time statement.

utime.sleep(secs)

Sleep for secs seconds. Can take a floating-point value.

utime.sleep_ms(msecs)

Sleep for msecs milliseconds. Only takes integer values.

utime.sleep_us(usecs)

Sleep for usecs microseconds. Only takes integer values.

utime.time()

Return the current timestamp in seconds since 2000-01-01 00:00 in the local timezone.

utime.time_ms()

Return the current timestamp in milliseconds since 2000-01-01 00:00 in the local timezone.

utime.monotonic()

Return a monotonically increasing timestamp.

New in version 1.11.

utime.monotonic_ms()

Return a monotonically increasing timestamp in milliseconds.

New in version 1.11.

utime.ticks_ms()

Return processor ticks (converted to milliseconds) since Pycardium startup.

This function should be the preferred method for timing and profiling because it does not need an API call and thus is very fast.

New in version 1.13.

utime.ticks_us()

Return processor ticks (converted to microseconds) since Pycardium startup.

This function should be the preferred method for timing and profiling because it does not need an API call and thus is very fast.

New in version 1.13.

utime.unix_time()

Return the current unix time as seconds since the epoch.

New in version 1.12.

utime.unix_time_ms()

Return the current unix time as milliseconds since the epoch.

New in version 1.12.

utime.set_time(secs)

Sets the time to secs seconds since 2000-01-01 00:00 in the local timezone.

Changed in version 1.4: utime.set_time() previously applied a wrong timezone offset, thus leading to wrong results.

utime.set_time_ms(msecs)

Set the time to msecs seconds since 2000-01-01 00:00 in the local timezone.

New in version 1.12.

utime.set_unix_time(secs)

Sets the time to secs seconds since 1970-01-01 00:00 UTC. This corresponds to a regular Unix timestamp which can be obtained by running date +%s in a command line or int(time.time()) in Python.

utime.set_unix_time_ms(msecs)

Set the time to msecs milliseconds since the unix epoch.

New in version 1.12.

utime.localtime([secs])

Return the current time as a timestruct tuple. If secs is given, return its timestruct tuple instead. Timestruct tuple looks like:

(year, month, mday, hour, min, sec, wday, yday)
#   0      1     2     3    4    5     6     7
utime.mktime(t)

Convert timestruct tuple into a seconds time stamp. See utime.localtime() for details about timestruct tuples.

Returns

Seconds since 2000-01-01

utime.alarm(secs[, callback])

Register the next RTC alarm for the timestamp secs. secs is seconds since 2000-01-01.

If an optional callback is given, it will be registered for the RTC alarm interrupt. This will overwrite any previous interrupt handler. If callback is given, utime.alarm() will also enable the RTC alarm interrupt.

Example:

import time

def minute_timer(x):
   current = time.time()
   print("Current: " + str(current))
   alarm = (current // 60 + 1) * 60
   time.alarm(alarm, minute_timer)

minute_timer(None)

Alternatively, you can register a callback using the interrupt module and then call utime.alarm() without a callback parameter:

import interrupt, time

def 5_second_timer(x):
   current = time.time()
   print("Current: " + str(current))
   alarm = (current // 10) * 10 + 5
   time.alarm(alarm)

# This time, we need to register and enable the callback manually
interrupt.set_callback(interrupt.RTC_ALARM, 5_second_timer)
interrupt.enable_callback(interrupt.RTC_ALARM)

5_second_timer(None)