.. currentmodule:: machine .. _machine.Timer:

class Timer -- control hardware timers

Timer class provides the ability to trigger a Python callback function after an expiry time, or periodically at a regular interval.

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 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.

Any additional parameters are handled the same as :func:Timer.init().

Methods

.. method:: Timer.init(*, mode=Timer.PERIODIC, freq=-1, period=-1, callback=None, hard=True)

Initialise the timer. Example::

   def mycallback(t):
       pass

   # periodic at 1kHz
   tim.init(mode=Timer.PERIODIC, freq=1000, callback=mycallback)

   # periodic with 100ms period
   tim.init(period=100, callback=mycallback)

   # one shot firing after 1000ms
   tim.init(mode=Timer.ONE_SHOT, period=1000, callback=mycallback)

Keyword arguments:

 - ``mode`` can be one of:

   - ``Timer.ONE_SHOT`` - The timer runs once until the configured
     period of the channel expires.
   - ``Timer.PERIODIC`` - The timer runs periodically at the configured
     frequency of the channel.

 - ``freq`` - The timer frequency, in units of Hz.  The upper bound of
   the frequency is dependent on the port.  When both the ``freq`` and
   ``period`` arguments are given, ``freq`` has a higher priority and
   ``period`` is ignored.

 - ``period`` - The timer period, in milliseconds.

 - ``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`. 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 parameter is port-specific for historical reasons.

.. method:: Timer.deinit()

Deinitialises the timer. Stops the timer, and disables the timer peripheral.

Constants

.. data:: Timer.ONE_SHOT Timer.PERIODIC

Timer operating mode.