utime

The utime module provides functions for getting the current time and date, measuring time intervals, and for delays.

Note

The utime module is a MicroPython implementation of the standard Python time module. It can be imported using both import utime and import time, but the module is the same.

Functions

utime.sleep(seconds)

Sleep for the given number of seconds. You can use a floating-point number to sleep for a fractional number of seconds, or use the utime.sleep_ms() and utime.sleep_us() functions.

utime.sleep_ms(ms)

Delay for given number of milliseconds, should be positive or 0.

utime.sleep_us(us)

Delay for given number of microseconds, should be positive or 0.

utime.ticks_ms()

Returns an increasing millisecond counter with an arbitrary reference point, that wraps around after some value.

utime.ticks_us()

Just like utime.ticks_ms() above, but in microseconds.

utime.ticks_add(ticks, delta)

Offset ticks value by a given number, which can be either positive or negative. Given a ticks value, this function allows to calculate ticks value delta ticks before or after it, following modular-arithmetic definition of tick values.

Example:

# Find out what ticks value there was 100ms ago
print(ticks_add(time.ticks_ms(), -100))

# Calculate deadline for operation and test for it
deadline = ticks_add(time.ticks_ms(), 200)
while ticks_diff(deadline, time.ticks_ms()) > 0:
    do_a_little_of_something()

# Find out TICKS_MAX used by this port
print(ticks_add(0, -1))
utime.ticks_diff(ticks1, ticks2)

Measure ticks difference between values returned from utime.ticks_ms() or ticks_us() functions, as a signed value which may wrap around.

The argument order is the same as for subtraction operator, ticks_diff(ticks1, ticks2) has the same meaning as ticks1 - ticks2.

utime.ticks_diff() is designed to accommodate various usage patterns, among them:

Polling with timeout. In this case, the order of events is known, and you will deal only with positive results of utime.ticks_diff():

# Wait for GPIO pin to be asserted, but at most 500us
start = time.ticks_us()
while pin.value() == 0:
    if time.ticks_diff(time.ticks_us(), start) > 500:
        raise TimeoutError

Scheduling events. In this case, utime.ticks_diff() result may be negative if an event is overdue:

# This code snippet is not optimized
now = time.ticks_ms()
scheduled_time = task.scheduled_time()
if ticks_diff(scheduled_time, now) > 0:
    print("Too early, let's nap")
    sleep_ms(ticks_diff(scheduled_time, now))
    task.run()
elif ticks_diff(scheduled_time, now) == 0:
    print("Right at time!")
    task.run()
elif ticks_diff(scheduled_time, now) < 0:
    print("Oops, running late, tell task to run faster!")
    task.run(run_faster=true)