2016-06-07 22:46:27 +01:00
|
|
|
.. currentmodule:: machine
|
2017-04-18 06:27:37 +01:00
|
|
|
.. _machine.Timer:
|
2015-10-14 11:32:01 +01:00
|
|
|
|
2017-01-28 08:55:48 +00:00
|
|
|
class Timer -- control hardware timers
|
2015-10-14 11:32:01 +01:00
|
|
|
======================================
|
|
|
|
|
2017-01-28 08:55:48 +00:00
|
|
|
Hardware timers deal with timing of periods and events. Timers are perhaps
|
|
|
|
the most flexible and heterogeneous kind of hardware in MCUs and SoCs,
|
|
|
|
differently greatly from a model to a model. MicroPython's Timer class
|
|
|
|
defines a baseline operation of executing a callback with a given period
|
|
|
|
(or once after some delay), and allow specific boards to define more
|
|
|
|
non-standard behavior (which thus won't be portable to other boards).
|
2015-10-14 11:32:01 +01:00
|
|
|
|
2017-01-28 09:08:25 +00:00
|
|
|
See discussion of :ref:`important constraints <machine_callbacks>` on
|
|
|
|
Timer callbacks.
|
|
|
|
|
2015-10-14 11:32:01 +01:00
|
|
|
.. note::
|
|
|
|
|
2015-10-20 15:24:25 +01:00
|
|
|
Memory can't be allocated inside irq handlers (an interrupt) and so
|
|
|
|
exceptions raised within a handler don't give much information. See
|
2015-10-14 11:32:01 +01:00
|
|
|
:func:`micropython.alloc_emergency_exception_buf` for how to get around this
|
|
|
|
limitation.
|
|
|
|
|
|
|
|
Constructors
|
|
|
|
------------
|
|
|
|
|
2016-06-09 01:03:53 +01:00
|
|
|
.. class:: Timer(id, ...)
|
2015-10-14 11:32:01 +01:00
|
|
|
|
2017-01-28 08:55:48 +00:00
|
|
|
Construct a new timer object of the given id. Id of -1 constructs a
|
|
|
|
virtual timer (if supported by a board).
|
2015-10-14 11:32:01 +01:00
|
|
|
|
|
|
|
Methods
|
|
|
|
-------
|
|
|
|
|
|
|
|
.. only:: port_wipy
|
|
|
|
|
2016-06-07 23:33:49 +01:00
|
|
|
.. method:: Timer.init(mode, \*, width=16)
|
2015-10-14 11:32:01 +01:00
|
|
|
|
|
|
|
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.
|
2016-02-14 12:46:04 +00:00
|
|
|
- ``Timer.PWM`` - Output a PWM signal on a pin.
|
2015-10-14 11:32:01 +01:00
|
|
|
|
2016-02-14 12:46:04 +00:00
|
|
|
- ``width`` must be either 16 or 32 (bits). For really low frequencies < 5Hz
|
2015-10-14 11:32:01 +01:00
|
|
|
(or large periods), 32-bit timers should be used. 32-bit mode is only available
|
|
|
|
for ``ONE_SHOT`` AND ``PERIODIC`` modes.
|
|
|
|
|
2016-06-07 23:33:49 +01:00
|
|
|
.. method:: Timer.deinit()
|
2015-10-14 11:32:01 +01:00
|
|
|
|
2017-01-28 08:55:48 +00:00
|
|
|
Deinitialises the timer. Stops the timer, and disables the timer peripheral.
|
2015-10-14 11:32:01 +01:00
|
|
|
|
|
|
|
.. only:: port_wipy
|
|
|
|
|
2016-06-07 23:33:49 +01:00
|
|
|
.. method:: Timer.channel(channel, \**, freq, period, polarity=Timer.POSITIVE, duty_cycle=0)
|
2015-10-14 11:32:01 +01:00
|
|
|
|
|
|
|
If only a channel identifier passed, then a previously initialized channel
|
|
|
|
object is returned (or ``None`` if there is no previous channel).
|
2016-02-14 12:46:04 +00:00
|
|
|
|
2016-08-01 00:52:00 +01:00
|
|
|
Otherwise, a TimerChannel object is initialized and returned.
|
2015-10-14 11:32:01 +01:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2016-02-14 12:46:04 +00:00
|
|
|
- ``polarity`` this is applicable for ``PWM``, and defines the polarity of the duty cycle
|
|
|
|
- ``duty_cycle`` only 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.
|
|
|
|
|
2016-02-23 18:53:26 +00:00
|
|
|
.. note::
|
|
|
|
|
|
|
|
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 ``Pin`` class. The pins which
|
|
|
|
support PWM functionality are the following:
|
|
|
|
|
|
|
|
- ``GP24`` on Timer 0 channel A.
|
|
|
|
- ``GP25`` on Timer 1 channel A.
|
|
|
|
- ``GP9`` on Timer 2 channel B.
|
|
|
|
- ``GP10`` on Timer 3 channel A.
|
|
|
|
- ``GP11`` on Timer 3 channel B.
|
2015-10-14 11:32:01 +01:00
|
|
|
|
2017-01-28 08:55:48 +00:00
|
|
|
.. only:: port_wipy
|
2015-10-14 11:32:01 +01:00
|
|
|
|
2017-01-28 08:55:48 +00:00
|
|
|
class TimerChannel --- setup a channel for a timer
|
|
|
|
==================================================
|
2015-10-14 11:32:01 +01:00
|
|
|
|
2017-01-28 08:55:48 +00:00
|
|
|
Timer channels are used to generate/capture a signal using a timer.
|
2015-10-14 11:32:01 +01:00
|
|
|
|
2017-01-28 08:55:48 +00:00
|
|
|
TimerChannel objects are created using the Timer.channel() method.
|
2015-10-14 11:32:01 +01:00
|
|
|
|
2017-01-28 08:55:48 +00:00
|
|
|
Methods
|
|
|
|
-------
|
2015-10-14 11:32:01 +01:00
|
|
|
|
|
|
|
.. method:: timerchannel.irq(\*, trigger, priority=1, handler=None)
|
|
|
|
|
2016-08-01 00:52:00 +01:00
|
|
|
The behavior of this callback is heavily dependent on the operating
|
2015-10-14 11:32:01 +01:00
|
|
|
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.
|
2016-02-14 12:46:04 +00:00
|
|
|
- ``trigger`` must be ``Timer.TIMEOUT`` when the operating mode is either ``Timer.PERIODIC`` or
|
|
|
|
``Timer.ONE_SHOT``. In the case that mode is ``Timer.PWM`` then trigger must be equal to
|
|
|
|
``Timer.MATCH``.
|
2015-10-14 11:32:01 +01:00
|
|
|
|
|
|
|
Returns a callback object.
|
|
|
|
|
|
|
|
.. only:: port_wipy
|
|
|
|
|
|
|
|
.. method:: timerchannel.freq([value])
|
2016-02-14 12:46:04 +00:00
|
|
|
|
2015-10-14 11:32:01 +01:00
|
|
|
Get or set the timer channel frequency (in Hz).
|
|
|
|
|
|
|
|
.. method:: timerchannel.period([value])
|
|
|
|
|
|
|
|
Get or set the timer channel period (in microseconds).
|
|
|
|
|
2016-02-14 12:46:04 +00:00
|
|
|
.. method:: timerchannel.duty_cycle([value])
|
2015-10-14 11:32:01 +01:00
|
|
|
|
2016-02-23 19:18:45 +00:00
|
|
|
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.
|
2015-10-14 11:32:01 +01:00
|
|
|
|
2016-02-14 12:46:04 +00:00
|
|
|
Constants
|
|
|
|
---------
|
2015-10-14 11:32:01 +01:00
|
|
|
|
2016-02-14 12:46:04 +00:00
|
|
|
.. data:: Timer.ONE_SHOT
|
|
|
|
.. data:: Timer.PERIODIC
|
|
|
|
|
2017-01-28 08:55:48 +00:00
|
|
|
Timer operating mode.
|