timer

machine Module

Class Timer

---

This class includes support for using ESP32 hardware timer peripheral

The ESP32 chip contains two hardware timer groups. Each group has two general-purpose hardware timers. They are all 64-bit generic timers based on 16-bit prescalers and 64-bit auto-reload-capable up / down counters.

Features

• Several timer operational modes are available:

Mode	Description
ONE_SHOT	When timer is started, it runs for defined time and stops. If given, the callback function is executed when the defined time elapses.
PERIODIC	Timer runs repeatedly until explicitly stopped. When defined time elapses the callback function is executed, if given
CHRONO	Used for measuring the elapsed time with µs precision. Can be started, paused, resumed and stopped
EXTBASE	Base timer for extended timers. Only timer 0 can be used in this mode.

• Up to 4 hardware timers can be used.
  
• Up to 8 extended timers can be used if timer 0 is configured in EXTBASE mode.
  That way total of 11 timers can be used.
  
• Extended timers can operate only in ONE_SHOT or PERIODIC modes.
• In CHRONO mode timers uses 1 MHz clock as timer base frequency to achieve 1 µs resolution.
• In other modes timers uses 2 kHz clock as timer base frequency, resulution of 1 ms is available.
• Each timer keeps track of number of timer events and number of executed callbacks

Warnng:

Due to MicroPython callback latency, some callbacks may not be executed if the timer period is less than 15 ms.
The number of events and executed callbacks can be checked using tm.events() method.

Create the Timer instance object

tm = machine.Timer(timer_no)

timer_no argument is the timer number to be used for the timer.
It can be 0 - 3 for 4 hardware timers or 4 - 11 for extended timers.
If extended timer is selected, timer 0 must already be configured in EXTBASE mode.

tm.init(period, mode, callback, dbgpin)

Argument	Description
period	Default: 10 ms Timer period in ms, only used for PERIODIC and ONE_SHOT timers
mode	Default: PERIODIC Timer mode of operation
callback	Default: None The Python callback function to be executed on timer event
dbgpin	Default: -1 (not used) GPIO pin to be used as debug output. If used, the gpio level will toggle on each timer event.

All arguments must be given as kw arguments (period=1000, mode=....)
The timer of the type CHRONO is not started after timer.init().

tm.deinit()

Deinitialize the timer, free the hardware timer resources.
Timer 0, running in EXTBASE mode, canno't be freed if some EXTENDED timers are still running.

tm.value()

Returns the current timer counter value in µs if timer mode is CHRONO or in ms for other modes.
Most useful for CHRONO mode timers, as it returns the actual elapsed time.

tm.pause()

Pause the timer.
Timer 0, running in EXTBASE mode, canno't be paused if some EXTENDED timers are running.

tm.stop()

Stop the timer. Alias for tm.pause()
Only use for timer in CHRONO mode.

tm.resume()

Resume the previously paused timer.

tm.start()

Resume the previously paused/stopped timer.
Same function as tm.resume(), but resets the timer value to 0.
Only use for timer in CHRONO mode.

tm.reshot()

Start the ONE_SHOT timer again.
Only use for timer in ONE_SHOT mode.

tm.timernum()

Returns the hw timer number this timer uses.

tm.events()

Returns the number of timer events and number of executed callbacks.
The tuple is returned: (num_events, num_cb).
If no callbacks were missed, num_events = num_cb.

tm.isrunning()

Returns True if the timmer is currently running, False if not.

tm.period([period])

Get or set the timer period.
Executed without argument, returns the current timer's period.
Executed with period argument, changes the timer's period to the new value.

tm.callback([cb_func])

Disable or change the timer's callback function.
Executed without argument, disables timer's callback.
Executed with cb_func argument, changes the timer's calback function to the new one.
Only use for timers in ONE_SHOT or PERIODIC modes.

Example

import machine

tcounter = 0

p1 = machine.Pin(27)
p1.init(p1.OUT)
p1.value(1)

def tcb(timer):
    global tcounter
    if tcounter & 1:
        p1.value(0)
    else:
        p1.value(1)
    tcounter += 1
    if (tcounter % 10000) == 0:
        print("[tcb] timer: {} counter: {}".format(timer.timernum(), tcounter))

t1 = machine.Timer(2)
t1.init(period=20, mode=t1.PERIODIC, callback=tcb)

# If period is less than 15 ms, some callbacks will be missed
>>> t1.period(10)

# After some time
>>> t1
Timer(2) Period: 10 ms; Repeat: True; Type: Periodic; Running: yes
         Events: 251923; Callbacks: 251604; Missed: 319

>>> t1.period(200)

>>> t1.events()
(261119, 260800)

>>> t1.isrunning()
True
>>> t1.pause()
>>> t1.isrunning()
False
>>> t1
Timer(2) Period: 20 ms; Repeat: True; Type: Periodic; Running: no
         Events: 265778; Callbacks: 265459; Missed: 319
>>> t1.resume()
>>> t1.isrunning()
True

>>> t2=machine.Timer(3)
>>> t2.init(mode=t1.CHRONO)
>>> t2
Timer(3) Period: 1 us; Type: Chrono; Running: no

>>> t2.start()
>>> t2
Timer(3) Period: 1 us; Type: Chrono; Running: yes

>>> t2.value()
10480001
>>> t2.pause()
>>> t2.value()
139999882
t2.value()
139999882
>>> t2.resume()
>>> t2.value()
142489205
>>> t2.start(); t2.value()
260
>>> 

tex = machine.Timer(0)
tex.init(mode=tex.EXTBASE)

tme1 = machine.Timer(6)
tme1.init(period=100, mode=tme1.PERIODIC, callback=tcb)