This is the v1.27.0 version of the MicroPython documentation. The latest development version of this page may be more current.

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 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 Writing interrupt handlers.) Most microcontroller ports support hardware timers, except Zephyr and RP2 which only support virtual timers.

Constructors

class machine.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 Timer.init().

Methods

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 Writing interrupt handlers. 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.

Timer.deinit()

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

Constants

Timer.ONE_SHOT
Timer.PERIODIC

Timer operating mode.