2016-04-26 22:29:14 +00:00
|
|
|
:mod:`utime` -- time related functions
|
2016-04-27 11:11:27 +00:00
|
|
|
======================================
|
2014-10-31 01:37:19 +00:00
|
|
|
|
2016-04-26 22:29:14 +00:00
|
|
|
.. module:: utime
|
2014-10-31 01:37:19 +00:00
|
|
|
:synopsis: time related functions
|
|
|
|
|
2016-04-26 22:29:14 +00:00
|
|
|
The ``utime`` module provides functions for getting the current time and date,
|
2014-10-31 01:37:19 +00:00
|
|
|
and for sleeping.
|
|
|
|
|
|
|
|
Functions
|
|
|
|
---------
|
|
|
|
|
|
|
|
.. function:: localtime([secs])
|
|
|
|
|
|
|
|
Convert a time expressed in seconds since Jan 1, 2000 into an 8-tuple which
|
|
|
|
contains: (year, month, mday, hour, minute, second, weekday, yearday)
|
|
|
|
If secs is not provided or None, then the current time from the RTC is used.
|
2014-10-31 22:21:37 +00:00
|
|
|
year includes the century (for example 2014).
|
|
|
|
|
|
|
|
* month is 1-12
|
|
|
|
* mday is 1-31
|
|
|
|
* hour is 0-23
|
|
|
|
* minute is 0-59
|
|
|
|
* second is 0-59
|
|
|
|
* weekday is 0-6 for Mon-Sun
|
|
|
|
* yearday is 1-366
|
2014-10-31 01:37:19 +00:00
|
|
|
|
|
|
|
.. function:: mktime()
|
|
|
|
|
|
|
|
This is inverse function of localtime. It's argument is a full 8-tuple
|
|
|
|
which expresses a time as per localtime. It returns an integer which is
|
|
|
|
the number of seconds since Jan 1, 2000.
|
|
|
|
|
2016-04-27 11:30:59 +00:00
|
|
|
.. only:: port_unix or port_pyboard or port_esp8266
|
2014-10-31 01:37:19 +00:00
|
|
|
|
2015-06-10 21:29:56 +00:00
|
|
|
.. function:: sleep(seconds)
|
|
|
|
|
|
|
|
Sleep for the given number of seconds. Seconds can be a floating-point number to
|
2016-04-27 12:28:12 +00:00
|
|
|
sleep for a fractional number of seconds. Note that other MicroPython ports may
|
|
|
|
not accept floating-point argument, for compatibility with them use ``sleep_ms()``
|
|
|
|
and ``sleep_us()`` functions.
|
2015-06-10 21:29:56 +00:00
|
|
|
|
2016-04-27 11:30:59 +00:00
|
|
|
.. only:: port_wipy
|
2015-06-10 21:29:56 +00:00
|
|
|
|
|
|
|
.. function:: sleep(seconds)
|
|
|
|
|
|
|
|
Sleep for the given number of seconds.
|
|
|
|
|
2016-04-27 11:30:59 +00:00
|
|
|
.. only:: port_unix or port_pyboard or port_wipy or port_esp8266
|
2015-10-14 10:32:01 +00:00
|
|
|
|
|
|
|
.. function:: sleep_ms(ms)
|
|
|
|
|
|
|
|
Delay for given number of milliseconds, should be positive or 0.
|
|
|
|
|
|
|
|
.. function:: sleep_us(us)
|
|
|
|
|
|
|
|
Delay for given number of microseconds, should be positive or 0
|
|
|
|
|
|
|
|
.. function:: ticks_ms()
|
|
|
|
|
|
|
|
Returns an increasing millisecond counter with arbitrary reference point,
|
|
|
|
that wraps after some (unspecified) value. The value should be treated as
|
|
|
|
opaque, suitable for use only with ticks_diff().
|
|
|
|
|
|
|
|
.. function:: ticks_us()
|
|
|
|
|
|
|
|
Just like ``ticks_ms`` above, but in microseconds.
|
|
|
|
|
2016-04-27 11:30:59 +00:00
|
|
|
.. only:: port_wipy or port_pyboard
|
|
|
|
|
2015-10-14 10:32:01 +00:00
|
|
|
.. function:: ticks_cpu()
|
|
|
|
|
|
|
|
Similar to ``ticks_ms`` and ``ticks_us``, but with higher resolution (usually CPU clocks).
|
|
|
|
|
2016-04-27 11:30:59 +00:00
|
|
|
.. only:: port_unix or port_pyboard or port_wipy or port_esp8266
|
|
|
|
|
2015-10-14 10:32:01 +00:00
|
|
|
.. function:: ticks_diff(old, new)
|
|
|
|
|
|
|
|
Measure period between consecutive calls to ticks_ms(), ticks_us(), or ticks_cpu().
|
|
|
|
The value returned by these functions may wrap around at any time, so directly
|
|
|
|
subtracting them is not supported. ticks_diff() should be used instead. "old" value should
|
|
|
|
actually precede "new" value in time, or result is undefined. This function should not be
|
|
|
|
used to measure arbitrarily long periods of time (because ticks_*() functions wrap around
|
|
|
|
and usually would have short period). The expected usage pattern is implementing event
|
|
|
|
polling with timeout::
|
|
|
|
|
|
|
|
# Wait for GPIO pin to be asserted, but at most 500us
|
|
|
|
start = time.ticks_us()
|
|
|
|
while pin.value() == 0:
|
|
|
|
if time.ticks_diff(start, time.ticks_us()) > 500:
|
|
|
|
raise TimeoutError
|
|
|
|
|
2014-10-31 01:37:19 +00:00
|
|
|
.. function:: time()
|
|
|
|
|
2016-04-27 12:23:11 +00:00
|
|
|
Returns the number of seconds, as an integer, since a port-specific reference point
|
|
|
|
in time (for embedded boards without RTC, usually since power up or reset). If you
|
|
|
|
want to develop portable MicroPython application, you should not rely on this
|
|
|
|
function to provide higher than second precision, or on a specific reference time
|
|
|
|
point. If you need higher precision, use ``ticks_ms()`` and ``ticks_us()`` functions,
|
|
|
|
if you need calendar time, ``localtime()`` without argument is the best possibility
|
|
|
|
to get it.
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
**CPython difference:** In CPython, this function returns number of
|
|
|
|
seconds since Unix epoch, 1970-01-01 00:00 UTC, as a floating-point,
|
|
|
|
usually having microsecond precision. With MicroPython, only Unix port
|
|
|
|
uses the same reference point, and if floating-point precision allows,
|
|
|
|
returns sub-second precision. Embedded hardware usually doesn't have
|
|
|
|
floating-point precision to represent both long time ranges and subsecond
|
|
|
|
precision, so use integer value with second precision. Most embedded
|
|
|
|
hardware also lacks battery-powered RTC, so returns number of seconds
|
|
|
|
since last power-up or from other relative, hardware-specific point
|
|
|
|
(e.g. reset).
|