diff options
Diffstat (limited to 'docs/library/machine.Timer.rst')
| -rw-r--r-- | docs/library/machine.Timer.rst | 193 |
1 files changed, 193 insertions, 0 deletions
diff --git a/docs/library/machine.Timer.rst b/docs/library/machine.Timer.rst new file mode 100644 index 0000000000..4814da8603 --- /dev/null +++ b/docs/library/machine.Timer.rst @@ -0,0 +1,193 @@ +.. _machine.Timer: + +class Timer -- control internal timers +====================================== + +.. only:: port_wipy + + .. note:: + + Contrary with the rest of the API, timer IDs start at 1, not a t zero. This is because + the ``Timer`` API is still provisional. A new MicroPython wide API will come soon. + + 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 2 16-bit channels and this channels can be tied together to + form 1 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:: + + tim = machine.Timer(4) # create a timer object using timer 4 + tim.init(mode=Timer.PERIODIC) # initialize it in periodic mode + tim_ch = tim.channel(Timer.A, freq=2) # configure channel A at a frequency of 2Hz + tim_ch.callback(handler=lambda t:led.toggle()) # toggle a LED on every cycle of the timer + + Example using named function for the callback:: + + tim = Timer(1, mode=Timer.PERIODIC) + tim_a = tim.channel(Timer.A, freq=1000) + + led = Pin('GPIO2', af=0, mode=Pin.OUT) + + def tick(timer): # we will receive the timer object when being called + print(timer.time()) # show current timer's time value (is microseconds) + led.toggle() # toggle the LED + + tim_a.callback(handler=tick) + + Further examples:: + + tim1 = machine.Timer(2, mode=Timer.EVENT_COUNT) # initialize it capture mode + tim2 = machine.Timer(1, mode=Timer.PWM) # initialize it in PWM mode + tim_ch = tim1.channel(Timer.A, freq=1, polarity=Timer.POSITIVE) # start the event counter with a frequency of 1Hz and triggered by positive edges + tim_ch = tim2.channel(Timer.B, freq=10000, duty_cycle=50) # start the PWM on channel B with a 50% duty cycle + tim_ch.time() # get the current time in usec (can also be set) + tim_ch.freq(20) # set the frequency (can also get) + tim_ch.duty_cycle(30) # set the duty cycle to 30% (can also get) + tim_ch.duty_cycle(30, Timer.NEGATIVE) # set the duty cycle to 30% and change the polarity to negative + tim_ch.event_count() # get the number of captured events + tim_ch.event_time() # get the the time of the last captured event + tim_ch.period(2000000) # change the period to 2 seconds + + +.. note:: + + Memory can't be allocated during a callback (an interrupt) and so + exceptions raised within a callback don't give much information. See + :func:`micropython.alloc_emergency_exception_buf` for how to get around this + limitation. + +Constructors +------------ + +.. class:: machine.Timer(id, ...) + + .. only:: port_wipy + + Construct a new timer object of the given id. If additional + arguments are given, then the timer is initialised by ``init(...)``. + ``id`` can be 1 to 4. + + +Methods +------- + +.. only:: port_wipy + + .. method:: timer.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 + + 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. + - ``Timer.EDGE_TIME`` - Meaure the time pin level changes. + - ``Timer.EDGE_COUNT`` - Count the number of pin level changes. + + - ``width`` must be either 16 or 32 (bits). For really low frequencies <= ~1Hz + (or large periods), 32-bit timers should be used. 32-bit mode is only available + for ``ONE_SHOT`` AND ``PERIODIC`` modes. + +.. method:: timer.deinit() + + Deinitialises the timer. Disables all channels and associated IRQs. + Stops the timer, and disables the timer peripheral. + +.. only:: port_wipy + + .. method:: timer.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 ``None`` if there is no previous channel). + + Othwerwise, 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. + + - ``channel`` if the width of the timer is 16-bit, then must be either ``TIMER.A``, ``TIMER.B``. + If the width is 32-bit then it **must be** ``TIMER.A | TIMER.B``. + + Keyword only arguments: + + - ``freq`` sets the frequency in Hz. + - ``period`` sets the period in microseconds. + + .. note:: + + Either ``freq`` or ``period`` must be given, never both. + + - ``polarity`` this is applicable for: + + - ``PWM``, defines the polarity of the duty cycle + - ``EDGE_TIME`` and ``EDGE_COUNT``, defines the polarity of the pin level change to detect. + To detect both rising and falling edges, make ``polarity=Timer.POSITIVE | Timer.NEGATIVE``. + - ``duty_cycle`` only applicable to ``PWM``. It's a percentage (0-100) + +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. + +Methods +------- + +.. only:: port_wipy + + .. method:: timerchannel.irq(\*, trigger, priority=1, handler=None) + + The behavior of this callback is heaviliy dependent on the operating + mode of the timer channel: + + - If mode is ``Timer.PERIODIC`` the callback is executed periodically + with the configured frequency or period. + - If mode is ``Timer.ONE_SHOT`` the callback is executed once when + the configured timer expires. + - If mode is ``Timer.PWM`` the callback is executed when reaching the duty + cycle value. + + The accepted params are: + + - ``priority`` level of the interrupt. Can take values in the range 1-7. + Higher values represent higher priorities. + - ``handler`` is an optional function to be called when the interrupt is triggered. + + Returns a callback object. + +.. only:: port_wipy + + .. method:: timerchannel.freq([value]) + + Get or set the timer channel frequency (in Hz). + + .. method:: timerchannel.period([value]) + + Get or set the timer channel period (in microseconds). + + .. method:: timerchannel.time([value]) + + Get or set the timer channel current **time** value (in microseconds). + + .. method:: timerchannel.event_count() + + Get the number of edge events counted. + + .. method:: timerchannel.event_time() + + Get the time of ocurrance of the last event. + + .. method:: timerchannel.duty_cycle([value]) + + Get or set the duty cycle of the PWM signal (in the range of 0-100). |