diff --git a/docs/library/utime.rst b/docs/library/utime.rst
index 109c3560cc26891f2f1ee86be029cba23704920e..0b47a036e6dfb751fd9b0d1948046bef1ac3cc39 100644
--- a/docs/library/utime.rst
+++ b/docs/library/utime.rst
@@ -58,7 +58,7 @@ Functions
.. only:: port_unix or port_pyboard or port_esp8266
.. function:: sleep(seconds)
-
+
Sleep for the given number of seconds. Seconds can be a floating-point number to
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()``
@@ -67,32 +67,32 @@ Functions
.. only:: port_wipy
.. function:: sleep(seconds)
-
+
Sleep for the given number of seconds.
.. only:: port_unix or port_pyboard or port_wipy or port_esp8266
- .. function:: sleep_ms(ms)
+ .. function:: sleep_ms(ms)
Delay for given number of milliseconds, should be positive or 0.
- .. function:: sleep_us(us)
+ .. function:: sleep_us(us)
- Delay for given number of microseconds, should be positive or 0
+ Delay for given number of microseconds, should be positive or 0.
- .. function:: ticks_ms()
+ .. function:: ticks_ms()
- Returns an increasing millisecond counter with an arbitrary reference point,
- that wraps around after some value. This value is not explicitly exposed,
- but we will refer to it as `TICKS_MAX` to simplify discussion. Period of
- the values is `TICKS_PERIOD = TICKS_MAX + 1`. `TICKS_PERIOD` is guaranteed
- to be a power of two, but otherwise may differ from port to port. The same
- period value is used for all of ticks_ms(), ticks_us(), ticks_cpu() functions
- (for simplicity). Thus, these functions will return a value in range
- [0 .. `TICKS_MAX`], inclusive, total `TICKS_PERIOD` values. Note that only
- non-negative values are used. For the most part, you should treat values
- returned by these functions as opaque. The only operations available for them
- are ``ticks_diff()`` and ``ticks_add()`` functions described below.
+ Returns an increasing millisecond counter with an arbitrary reference point, that
+ wraps around after some value. This value is not explicitly exposed, but we will
+ refer to it as ``TICKS_MAX`` to simplify discussion. Period of the values is
+ ``TICKS_PERIOD = TICKS_MAX + 1``. ``TICKS_PERIOD`` is guaranteed to be a power of
+ two, but otherwise may differ from port to port. The same period value is used
+ for all of ``ticks_ms()``, ``ticks_us()``, ``ticks_cpu()`` functions (for
+ simplicity). Thus, these functions will return a value in range [``0`` ..
+ ``TICKS_MAX``], inclusive, total ``TICKS_PERIOD`` values. Note that only
+ non-negative values are used. For the most part, you should treat values returned
+ by these functions as opaque. The only operations available for them are
+ ``ticks_diff()`` and ``ticks_add()`` functions described below.
Note: Performing standard mathematical operations (+, -) or relational
operators (<, <=, >, >=) directly on these value will lead to invalid
@@ -100,15 +100,15 @@ Functions
as arguments to ``ticks_diff()`` or ``ticks_add()`` will also lead to
invalid results from the latter functions.
- .. function:: ticks_us()
+ .. function:: ticks_us()
- Just like ``ticks_ms`` above, but in microseconds.
+ Just like ``ticks_ms()`` above, but in microseconds.
-.. function:: ticks_cpu()
+.. function:: ticks_cpu()
- Similar to ``ticks_ms`` and ``ticks_us``, but with the highest possible resolution
+ Similar to ``ticks_ms()`` and ``ticks_us()``, but with the highest possible resolution
in the system. This is usually CPU clocks, and that's why the function is named that
- way. But it doesn't have to a CPU clock, some other timing source available in a
+ way. But it doesn't have to be a CPU clock, some other timing source available in a
system (e.g. high-resolution timer) can be used instead. The exact timing unit
(resolution) of this function is not specified on ``utime`` module level, but
documentation for a specific port may provide more specific information. This
@@ -118,13 +118,13 @@ Functions
Availability: Not every port implements this function.
-.. function:: ticks_add(ticks, delta)
+.. function:: 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
(see ``ticks_ms()`` above). ``ticks`` parameter must be a direct result of call
- to ``tick_ms()``, ``ticks_us()``, ``ticks_cpu()`` functions (or from previous
+ to ``ticks_ms()``, ``ticks_us()``, or ``ticks_cpu()`` functions (or from previous
call to ``ticks_add()``). However, ``delta`` can be an arbitrary integer number
or numeric expression. ``ticks_add()`` is useful for calculating deadlines for
events/tasks. (Note: you must use ``ticks_diff()`` function to work with
@@ -133,35 +133,37 @@ Functions
Examples::
# Find out what ticks value there was 100ms ago
- print(tick_add(time.ticks_ms(), -100))
+ print(ticks_add(time.ticks_ms(), -100))
# Calculate deadline for operation and test for it
- deadline = tick_add(time.ticks_ms(), 200)
+ 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(tick_add(0, -1))
-
-
-.. function:: ticks_diff(ticks1, ticks2)
-
- Measure ticks difference between values returned from ticks_ms(), ticks_us(), or ticks_cpu()
- functions. The argument order is the same as for subtraction operator,
- ``tick_diff(ticks1, ticks2)`` has the same meaning as ``ticks1 - ticks2``. However, values returned by
- ticks_ms(), etc. functions may wrap around, so directly using subtraction on them will
- produce incorrect result. That is why ticks_diff() is needed, it implements modular
- (or more specifically, ring) arithmetics to produce correct result even for wrap-around
- values (as long as they not too distant inbetween, see below). The function returns
- **signed** value in the range [`-TICKS_PERIOD/2` .. `TICKS_PERIOD/2-1`] (that's a typical
- range definition for two's-complement signed binary integers). If the result is negative,
- it means that `ticks1` occured earlier in time than `ticks2`. Otherwise, it means that
- `ticks1` occured after `ticks2`. This holds `only` if `ticks1` and `ticks2` are apart from
- each other for no more than `TICKS_PERIOD/2-1` ticks. If that does not hold, incorrect
- result will be returned. Specifically, if 2 tick values are apart for `TICKS_PERIOD/2-1`
- ticks, that value will be returned by the function. However, if `TICKS_PERIOD/2` of
- real-time ticks has passed between them, the function will return `-TICKS_PERIOD/2`
- instead, i.e. result value will wrap around to the negative range of possible values.
+ print(ticks_add(0, -1))
+
+
+.. function:: ticks_diff(ticks1, ticks2)
+
+ Measure ticks difference between values returned from ``ticks_ms()``, ``ticks_us()``,
+ or ``ticks_cpu()`` functions. The argument order is the same as for subtraction
+ operator, ``ticks_diff(ticks1, ticks2)`` has the same meaning as ``ticks1 - ticks2``.
+ However, values returned by ``ticks_ms()``, etc. functions may wrap around, so
+ directly using subtraction on them will produce incorrect result. That is why
+ ``ticks_diff()`` is needed, it implements modular (or more specifically, ring)
+ arithmetics to produce correct result even for wrap-around values (as long as they not
+ too distant inbetween, see below). The function returns **signed** value in the range
+ [``-TICKS_PERIOD/2`` .. ``TICKS_PERIOD/2-1``] (that's a typical range definition for
+ two's-complement signed binary integers). If the result is negative, it means that
+ ``ticks1`` occured earlier in time than ``ticks2``. Otherwise, it means that
+ ``ticks1`` occured after ``ticks2``. This holds ``only`` if ``ticks1`` and ``ticks2``
+ are apart from each other for no more than ``TICKS_PERIOD/2-1`` ticks. If that does
+ not hold, incorrect result will be returned. Specifically, if two tick values are
+ apart for ``TICKS_PERIOD/2-1`` ticks, that value will be returned by the function.
+ However, if ``TICKS_PERIOD/2`` of real-time ticks has passed between them, the
+ function will return ``-TICKS_PERIOD/2`` instead, i.e. result value will wrap around
+ to the negative range of possible values.
Informal rationale of the constraints above: Suppose you are locked in a room with no
means to monitor passing of time except a standard 12-notch clock. Then if you look at
@@ -200,20 +202,21 @@ Functions
print("Oops, running late, tell task to run faster!")
task.run(run_faster=true)
- Note: Do not pass ``time()`` values to ``ticks_diff()``, and should use
+ Note: Do not pass ``time()`` values to ``ticks_diff()``, you should use
normal mathematical operations on them. But note that ``time()`` may (and will)
also overflow. This is known as https://en.wikipedia.org/wiki/Year_2038_problem .
.. function:: time()
- Returns the number of seconds, as an integer, since the Epoch, assuming that underlying
- RTC is set and maintained as described above. If an RTC is not set, this function returns
- number of seconds since a port-specific reference point in time (for embedded boards without
- a battery-backed 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. If you need higher precision, use ``ticks_ms()`` and ``ticks_us()`` functions,
- if you need calendar time, ``localtime()`` without an argument is a better choice.
+ Returns the number of seconds, as an integer, since the Epoch, assuming that
+ underlying RTC is set and maintained as described above. If an RTC is not set, this
+ function returns number of seconds since a port-specific reference point in time (for
+ embedded boards without a battery-backed 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. If you need higher precision, use
+ ``ticks_ms()`` and ``ticks_us()`` functions, if you need calendar time,
+ ``localtime()`` without an argument is a better choice.
.. admonition:: Difference to CPython
:class: attention