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

Constructors#

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

Timer.deinit()

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

Constants#

Timer.ONE_SHOT Timer.PERIODIC

Timer operating mode.