machine.Timer.rst

.. currentmodule:: machine

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

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.