From b4246ffdaec84663da9c44def29f50356dc8da83 Mon Sep 17 00:00:00 2001
From: Rahix <rahix@rahix.de>
Date: Thu, 1 Aug 2019 01:12:42 +0200
Subject: [PATCH] docs: Document utime module
Signed-off-by: Rahix <rahix@rahix.de>
---
Documentation/index.rst | 1 +
Documentation/pycardium/utime.rst | 67 +++++++++++++++++++++++++++++++
2 files changed, 68 insertions(+)
create mode 100644 Documentation/pycardium/utime.rst
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 57c5b3d7..1fe90f2e 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 00000000..457e948e
--- /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)
--
GitLab