class Timer – control internal timers¶
Timers can be used for a great variety of tasks, calling a function periodically, counting events, and generating a PWM signal are among the most common use cases. Each timer consists of two 16-bit channels and this channels can be tied together to form one 32-bit timer. The operating mode needs to be configured per timer, but then the period (or the frequency) can be independently configured on each channel. By using the callback method, the timer event can call a Python function.
Example usage to toggle an LED at a fixed frequency:
from machine import Timer from machine import Pin led = Pin('GP16', mode=Pin.OUT) # enable GP16 as output to drive the LED tim = Timer(3) # create a timer object using timer 3 tim.init(mode=Timer.PERIODIC) # initialize it in periodic mode tim_ch = tim.channel(Timer.A, freq=5) # configure channel A at a frequency of 5Hz tim_ch.irq(handler=lambda t:led.toggle(), trigger=Timer.TIMEOUT) # toggle a LED on every cycle of the timer
Example using named function for the callback:
from machine import Timer from machine import Pin tim = Timer(1, mode=Timer.PERIODIC, width=32) tim_a = tim.channel(Timer.A | Timer.B, freq=1) # 1 Hz frequency requires a 32 bit timer led = Pin('GP16', mode=Pin.OUT) # enable GP16 as output to drive the LED def tick(timer): # we will receive the timer object when being called global led led.toggle() # toggle the LED tim_a.irq(handler=tick, trigger=Timer.TIMEOUT) # create the interrupt
from machine import Timer tim1 = Timer(1, mode=Timer.ONE_SHOT) # initialize it in one shot mode tim2 = Timer(2, mode=Timer.PWM) # initialize it in PWM mode tim1_ch = tim1.channel(Timer.A, freq=10, polarity=Timer.POSITIVE) # start the event counter with a frequency of 10Hz and triggered by positive edges tim2_ch = tim2.channel(Timer.B, freq=10000, duty_cycle=5000) # start the PWM on channel B with a 50% duty cycle tim2_ch.freq(20) # set the frequency (can also get) tim2_ch.duty_cycle(3010) # set the duty cycle to 30.1% (can also get) tim2_ch.duty_cycle(3020, Timer.NEGATIVE) # set the duty cycle to 30.2% and change the polarity to negative tim2_ch.period(2000000) # change the period to 2 seconds
Memory can’t be allocated inside irq handlers (an interrupt) and so
exceptions raised within a handler don’t give much information. See
micropython.alloc_emergency_exception_buf() for how to get around this
Construct a new timer object of the given id.
idcan take values from 0 to 3.
init(mode, *, width=16)¶
Initialise the timer. Example:
tim.init(Timer.PERIODIC) # periodic 16-bit timer tim.init(Timer.ONE_SHOT, width=32) # one shot 32-bit timer
modecan 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.
Timer.PWM- Output a PWM signal on a pin.
widthmust be either 16 or 32 (bits). For really low frequencies < 5Hz (or large periods), 32-bit timers should be used. 32-bit mode is only available for
Deinitialises the timer. Disables all channels and associated IRQs. Stops the timer, and disables the timer peripheral.
channel(channel, **, freq, period, polarity=Timer.POSITIVE, duty_cycle=0)¶
If only a channel identifier passed, then a previously initialized channel object is returned (or
Noneif there is no previous channel).
Otherwise, a TimerChannel object is initialized and returned.
The operating mode is is the one configured to the Timer object that was used to create the channel.
channelif the width of the timer is 16-bit, then must be either
TIMER.B. If the width is 32-bit then it must be
TIMER.A | TIMER.B.
Keyword only arguments:
freqsets the frequency in Hz.
periodsets the period in microseconds.
periodmust be given, never both.
polaritythis is applicable for
PWM, and defines the polarity of the duty cycle
duty_cycleonly applicable to
PWM. It’s a percentage (0.00-100.00). Since the WiPy doesn’t support floating point numbers the duty cycle must be specified in the range 0-10000, where 10000 would represent 100.00, 5050 represents 50.50, and so on.
When the channel is in PWM mode, the corresponding pin is assigned automatically, therefore there’s no need to assign the alternate function of the pin via the
Pinclass. The pins which support PWM functionality are the following:
GP24on Timer 0 channel A.
GP25on Timer 1 channel A.
GP9on Timer 2 channel B.
GP10on Timer 3 channel A.
GP11on Timer 3 channel B.
class TimerChannel — setup a channel for a timer¶
Timer channels are used to generate/capture a signal using a timer.
TimerChannel objects are created using the Timer.channel() method.
irq(*, trigger, priority=1, handler=None)¶
The behavior of this callback is heavily dependent on the operating mode of the timer channel:
- If mode is
Timer.PERIODICthe callback is executed periodically with the configured frequency or period.
- If mode is
Timer.ONE_SHOTthe callback is executed once when the configured timer expires.
- If mode is
Timer.PWMthe callback is executed when reaching the duty cycle value.
The accepted params are:
prioritylevel of the interrupt. Can take values in the range 1-7. Higher values represent higher priorities.
handleris an optional function to be called when the interrupt is triggered.
Timer.TIMEOUTwhen the operating mode is either
Timer.ONE_SHOT. In the case that mode is
Timer.PWMthen trigger must be equal to
Returns a callback object.
- If mode is
Get or set the timer channel frequency (in Hz).
Get or set the timer channel period (in microseconds).
Get or set the duty cycle of the PWM signal. It’s a percentage (0.00-100.00). Since the WiPy doesn’t support floating point numbers the duty cycle must be specified in the range 0-10000, where 10000 would represent 100.00, 5050 represents 50.50, and so on.
Selects the timer operating mode.
Selects the timer channel. Must be ORed (
Timer.B) when using a 32-bit timer.
Timer channel polarity selection (only relevant in PWM mode).
Timer channel IRQ triggers.