diff options
Diffstat (limited to 'docs/library/machine.Timer.rst')
| -rw-r--r-- | docs/library/machine.Timer.rst | 60 |
1 files changed, 35 insertions, 25 deletions
diff --git a/docs/library/machine.Timer.rst b/docs/library/machine.Timer.rst index 5d228ea7b..69eea9d8d 100644 --- a/docs/library/machine.Timer.rst +++ b/docs/library/machine.Timer.rst @@ -4,37 +4,47 @@ class Timer -- control hardware timers ====================================== -Hardware timers deal with timing of periods and events. Timers are perhaps -the most flexible and heterogeneous kind of hardware in MCUs and SoCs, -differently greatly from a model to a model. MicroPython's Timer class -defines a baseline operation of executing a callback with a given period -(or once after some delay), and allow specific boards to define more -non-standard behaviour (which thus won't be portable to other boards). +Timer class provides the ability to trigger a Python callback function after an +expiry time, or periodically at a regular interval. -See discussion of :ref:`important constraints <machine_callbacks>` on -Timer callbacks. - -.. note:: - - Memory can't be allocated inside irq handlers (an interrupt) and so - exceptions raised within a handler don't give much information. See - :func:`micropython.alloc_emergency_exception_buf` for how to get around - this limitation, which applies to all callbacks of Timers created with - ``hard=True``. +The available features and restrictions of Timer objects vary depending on the +MicroPython board and port. If you are using a WiPy board please refer to :ref:`machine.TimerWiPy <machine.TimerWiPy>` instead of this class. +Timer Types +----------- + +There are two types of Timer in MicroPython, but not all ports support both: + +- Virtual timers. These are managed in software, and are generally more + flexible. Multiple virtual timers can be constructed and active at once. The + ``id`` of a virtual timer is ``-1``. Not all ports support virtual timers, but + it's recommended to use them when available. +- Hardware timers. Hardware timers have integer ``id`` values starting at ``0``. + The number of available ``id`` values is determined by the hardware. Hardware + timers may be more accurate for very fine sub-millisecond timing (especially + when ``hard=True`` is supported and set, see :ref:`isr_rules`.) Most + microcontroller ports support hardware timers, except Zephyr and RP2 which + only support virtual timers. + Constructors ------------ .. class:: Timer(id, /, ...) - Construct a new timer object of the given ``id``. ``id`` of -1 constructs a - virtual timer (if supported by a board). + Construct a new Timer object with the given ``id``. + + On ports which support virtual timers the ``id`` parameter is optional - the + default value is ``-1`` which constructs a virtual timer. + + On ports which support hardware timers, setting the ``id`` parameter to a + non-negative integer determines which timer to use. + ``id`` shall not be passed as a keyword argument. - See ``init`` for parameters of initialisation. + Any additional parameters are handled the same as :func:`Timer.init()`. Methods ------- @@ -73,22 +83,22 @@ Methods - ``callback`` - The callable to call upon expiration of the timer period. The callback must take one argument, which is passed the Timer object. + The ``callback`` argument shall be specified. Otherwise an exception will occur upon timer expiration: ``TypeError: 'NoneType' object isn't callable`` - ``hard`` can be one of: - - ``True`` - The callback will be executed in hard interrupt - context, which minimises delay and jitter but is subject to the - limitations described in :ref:`isr_rules` including being unable - to allocate on the heap. + - ``True`` - The callback will be executed in hard interrupt context, + which minimises delay and jitter but is subject to the limitations + described in :ref:`isr_rules`. Not all ports support hard interrupts, + see the port documentation for more information. - ``False`` - The callback will be scheduled as a soft interrupt, allowing it to allocate but possibly also introducing garbage-collection delays and jitter. - The default value of this option is port-specific for historical - reasons. + The default value of this parameter is port-specific for historical reasons. .. method:: Timer.deinit() |