Skip to content

Commit c564169

Browse files
committed
docs/utime: Describe time() peculiarities in MicroPython.
1 parent dc2c8f0 commit c564169

1 file changed

Lines changed: 20 additions & 1 deletion

File tree

docs/library/utime.rst

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -90,4 +90,23 @@ Functions
9090

9191
.. function:: time()
9292

93-
Returns the number of seconds, as an integer, since 1/1/2000.
93+
Returns the number of seconds, as an integer, since a port-specific reference point
94+
in time (for embedded boards without RTC, usually since power up or reset). If you
95+
want to develop portable MicroPython application, you should not rely on this
96+
function to provide higher than second precision, or on a specific reference time
97+
point. If you need higher precision, use ``ticks_ms()`` and ``ticks_us()`` functions,
98+
if you need calendar time, ``localtime()`` without argument is the best possibility
99+
to get it.
100+
101+
.. note::
102+
103+
**CPython difference:** In CPython, this function returns number of
104+
seconds since Unix epoch, 1970-01-01 00:00 UTC, as a floating-point,
105+
usually having microsecond precision. With MicroPython, only Unix port
106+
uses the same reference point, and if floating-point precision allows,
107+
returns sub-second precision. Embedded hardware usually doesn't have
108+
floating-point precision to represent both long time ranges and subsecond
109+
precision, so use integer value with second precision. Most embedded
110+
hardware also lacks battery-powered RTC, so returns number of seconds
111+
since last power-up or from other relative, hardware-specific point
112+
(e.g. reset).

0 commit comments

Comments
 (0)