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

Rahix's avatar
Rahix committed
3
4
5
6
7
8
9
10
11
12
13
``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

Rahix's avatar
Rahix committed
14
.. py:function:: sleep(secs)
Rahix's avatar
Rahix committed
15
16
17

   Sleep for ``secs`` seconds.  Can take a floating-point value.

Rahix's avatar
Rahix committed
18
.. py:function:: sleep_ms(msecs)
Rahix's avatar
Rahix committed
19
20
21

   Sleep for ``msecs`` milliseconds.  Only takes integer values.

Rahix's avatar
Rahix committed
22
.. py:function:: sleep_us(usecs)
Rahix's avatar
Rahix committed
23
24
25

   Sleep for ``usecs`` microseconds.  Only takes integer values.

Rahix's avatar
Rahix committed
26
.. py:function:: time()
Rahix's avatar
Rahix committed
27

28
29
   Return the current timestamp in seconds since 2000-01-01 00:00 in
   the local timezone.
30

Hinerk's avatar
Hinerk committed
31
32
33
34
35
.. py:function:: time_ms()

   Return the current timestamp in milliseconds since 2000-01-01 00:00 in
   the local timezone.

36
37
38
39
40
41
42
43
44
45
46
47
.. py:function:: monotonic()

   Return a monotonically increasing timestamp.

   .. versionadded:: 1.11

.. py:function:: monotonic_ms()

   Return a monotonically increasing timestamp in milliseconds.

   .. versionadded:: 1.11

48
49
50
51
52
53
54
55
56
57
58
59
60
61
.. py:function:: ticks_ms()

   Return processor ticks (converted to milliseconds) since Pycardium startup.

   This function should be the preferred method for timing and profiling
   because it does not need an API call and thus is very fast.

.. py:function:: ticks_us()

   Return processor ticks (converted to microseconds) since Pycardium startup.

   This function should be the preferred method for timing and profiling
   because it does not need an API call and thus is very fast.

62
63
64
65
66
67
68
69
70
71
72
73
.. py:function:: unix_time()

   Return the current unix time as seconds since the epoch.

   .. versionadded:: 1.12

.. py:function:: unix_time_ms()

   Return the current unix time as milliseconds since the epoch.

   .. versionadded:: 1.12

Rahix's avatar
Rahix committed
74
.. py:function:: set_time(secs)
75

76
77
   Sets the time to ``secs`` seconds since 2000-01-01 00:00 in the local
   timezone.
78
79
80
81
82

   .. versionchanged:: 1.4
      :py:func:`utime.set_time` previously applied a wrong timezone offset,
      thus leading to wrong results.

83
84
85
86
87
88
89
.. py:function:: set_time_ms(msecs)

   Set the time to ``msecs`` seconds since 2000-01-01 00:00 in the local
   timezone.

   .. versionadded:: 1.12

Rahix's avatar
Rahix committed
90
.. py:function:: set_unix_time(secs)
91
92

   Sets the time to ``secs`` seconds since 1970-01-01 00:00 UTC.
93
   This corresponds to a regular Unix timestamp which can be obtained
94
95
   by running ``date +%s`` in a command line or ``int(time.time())``
   in Python.
Rahix's avatar
Rahix committed
96

97
98
99
100
101
102
.. py:function:: set_unix_time_ms(msecs)

   Set the time to ``msecs`` milliseconds since the unix epoch.

   .. versionadded:: 1.12

Rahix's avatar
Rahix committed
103
.. py:function:: localtime([secs])
Rahix's avatar
Rahix committed
104
105
106
107
108
109
110
111
112

   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

Rahix's avatar
Rahix committed
113
.. py:function:: mktime(t)
Rahix's avatar
Rahix committed
114
115
116
117
118
119

   Convert timestruct tuple into a seconds time stamp.  See
   :py:func:`utime.localtime` for details about timestruct tuples.

   :returns: Seconds since 2000-01-01

Rahix's avatar
Rahix committed
120
.. py:function:: alarm(secs, [callback])
Rahix's avatar
Rahix committed
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

   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)
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161

   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)