Skip to content

Commit f20cfad

Browse files
committed
docs/library/machine.Timer: Explain the id parameter in more detail.
As noted in discussion on PR micropython#18263, the id parameter is optional on ports that support virtual timers. Add some more general explanation of hardware vs virtual timers. This work was funded through GitHub Sponsors. Signed-off-by: Angus Gratton <angus@redyak.com.au>
1 parent 2082a4d commit f20cfad

File tree

1 file changed

+16
-3
lines changed

1 file changed

+16
-3
lines changed

docs/library/machine.Timer.rst

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,10 @@ defines a baseline operation of executing a callback with a given period
1111
(or once after some delay), and allow specific boards to define more
1212
non-standard behaviour (which thus won't be portable to other boards).
1313

14+
Many MicroPython ports also support support "virtual timers" which are managed
15+
in software. These are generally more flexible, and multiple virtual timers can
16+
be allocated at once.
17+
1418
See discussion of :ref:`important constraints <machine_callbacks>` on
1519
Timer callbacks.
1620

@@ -30,11 +34,20 @@ Constructors
3034

3135
.. class:: Timer(id, /, ...)
3236

33-
Construct a new timer object of the given ``id``. ``id`` of -1 constructs a
34-
virtual timer (if supported by a board).
37+
Construct a new timer object with the given ``id``.
38+
39+
If the port supports virtual timers then the ``id`` parameter can be omitted
40+
or set to value ``-1`` to construct a virtual timer. It's recommended to use
41+
virtual timers if the port supports this, unless you need very precise
42+
sub-millisecond callback timing (with hard interrupt context).
43+
44+
To construct a hardware timer, the ``id`` parameter must be set to a
45+
non-negative integer value. Most microcontroller ports support hardware
46+
timers, except the Zephyr and RP2 ports which support virtual timers only.
47+
3548
``id`` shall not be passed as a keyword argument.
3649

37-
See ``init`` for parameters of initialisation.
50+
Any additional parameters are handled the same as :func:`Timer.init()`.
3851

3952
Methods
4053
-------

0 commit comments

Comments
 (0)