diff --git a/Documentation/index.rst b/Documentation/index.rst index 57c5b3d7d56847de6f2b56ed3e15ea7b56c864d8..1fe90f2eb24532ce0c2d017bedcfe42ea30cb380 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -25,6 +25,7 @@ Last but not least, if you want to start hacking the lower-level firmware, the pycardium/display pycardium/leds pycardium/light-sensor + pycardium/utime pycardium/vibra .. toctree:: diff --git a/Documentation/pycardium/utime.rst b/Documentation/pycardium/utime.rst new file mode 100644 index 0000000000000000000000000000000000000000..457e948e3156e94ba7d15ff7003ed21eca6d481f --- /dev/null +++ b/Documentation/pycardium/utime.rst @@ -0,0 +1,67 @@ +``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 :py:func:`utime.alarm` function for setting an RTC +alarm. + +.. |time| replace:: ``time`` +.. _time: https://docs.python.org/3/library/time.html + +.. py:function:: utime.sleep(secs) + + Sleep for ``secs`` seconds. Can take a floating-point value. + +.. py:function:: utime.sleep_ms(msecs) + + Sleep for ``msecs`` milliseconds. Only takes integer values. + +.. py:function:: utime.sleep_us(usecs) + + Sleep for ``usecs`` microseconds. Only takes integer values. + +.. py:function:: utime.time() + + Return the current timestamp in seconds since 2000-01-01 + +.. py:function:: utime.localtime([secs]) + + Return the current time as a timestruct tuple. If ``secs`` is given, return + its timestruct tuple instead. Timestruct tuple looks like: + + .. code-block:: python + + (year, month, mday, hour, min, sec, wday, yday) + # 0 1 2 3 4 5 6 7 + +.. py:function:: utime.mktime(t) + + Convert timestruct tuple into a seconds time stamp. See + :py:func:`utime.localtime` for details about timestruct tuples. + + :returns: Seconds since 2000-01-01 + +.. py:function:: 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, :c:func:`utime.alarm` will also enable the RTC alarm + interrupt. + + **Example**: + + .. code-block:: python + + import utime + + def minute_timer(x): + current = utime.time() + print("Current: " + str(current)) + alarm = (current // 60 + 1) * 60 + utime.alarm(alarm, minute_timer) + + minute_timer(None)