utime.rst 2.95 KB
Newer Older
1
2
.. py:module:: utime

Rahix's avatar
Rahix committed
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
``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()

28
29
30
31
32
33
34
35
36
37
38
39
   Return the current timestamp in seconds since 2000-01-01 00:00.

.. py:function:: utime.set_time(secs)

   Sets the time to ``secs`` seconds since 2000-01-01 00:00.
   
.. py:function:: utime.set_unix_time(secs)

   Sets the time to ``secs`` seconds since 1970-01-01 00:00 UTC.
   This corresponds a regular Unix timestamp which can be obtained
   by running ``date +%s`` in a command line or ``int(time.time())``
   in Python.
Rahix's avatar
Rahix committed
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

.. 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)
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

   Alternatively, you can register a callback using the interrupt module and
   then call :py:func:`utime.alarm` without a ``callback`` parameter:

   .. code-block:: python

      import interrupt, utime

      def 5_second_timer(x):
         current = utime.time()
         print("Current: " + str(current))
         alarm = (current // 10) * 10 + 5
         utime.alarm(alarm)

      # This time, we need to register and enable the callback manually
      interrupt.set_callback(interrupt.RTC_ALARM, 5_second_timer)
      interrupt.enable_callback(interrupt.RTC_ALARM)

      5_second_timer(None)