djsundog/circuitpython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs/machine.Timer: Move WiPy adhoc parts to its documentation.

Browse Source
This commit is contained in:
Paul Sokolovsky 2017-01-28 11:55:48 +03:00
parent 300ecac336
commit 56e7ebf07a
4 changed files with 94 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
docs/library/machine.Timer.rst
View File

@ -1,53 +1,14 @@
.. currentmodule:: machine
class Timer -- control internal timers
class Timer -- control hardware timers
======================================
.. only:: port_wipy
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
Further examples::
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
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).
.. note::
@ -61,10 +22,8 @@ Constructors
.. class:: Timer(id, ...)
.. only:: port_wipy
Construct a new timer object of the given id. ``id`` can take values from 0 to 3.
Construct a new timer object of the given id. Id of -1 constructs a
virtual timer (if supported by a board).
Methods
-------
@ -94,8 +53,7 @@ Methods
.. method:: Timer.deinit()
Deinitialises the timer. Disables all channels and associated IRQs.
Stops the timer, and disables the timer peripheral.
Deinitialises the timer. Stops the timer, and disables the timer peripheral.
.. only:: port_wipy
@ -138,18 +96,18 @@ Methods
- ``GP10`` on Timer 3 channel A.
- ``GP11`` on 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.
Methods
-------
.. only:: port_wipy
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
-------
.. method:: timerchannel.irq(\*, trigger, priority=1, handler=None)
The behavior of this callback is heavily dependent on the operating
@ -194,22 +152,5 @@ Constants
.. data:: Timer.ONE_SHOT
.. data:: Timer.PERIODIC
.. data:: Timer.PWM
Selects the timer operating mode.
.. data:: Timer.A
.. data:: Timer.B
Selects the timer channel. Must be ORed (``Timer.A`` | ``Timer.B``) when
using a 32-bit timer.
.. data:: Timer.POSITIVE
.. data:: Timer.NEGATIVE
Timer channel polarity selection (only relevant in PWM mode).
.. data:: Timer.TIMEOUT
.. data:: Timer.MATCH
Timer channel IRQ triggers.
Timer operating mode.

3
docs/wipy/quickref.rst
View File

@ -44,7 +44,8 @@ See :ref:`machine.Pin <machine.Pin>`. ::
Timers
------
See :ref:`machine.Timer <machine.Timer>` and :ref:`machine.Pin <machine.Pin>`. ::
See :ref:`machine.Timer <machine.Timer>` and :ref:`machine.Pin <machine.Pin>`.
Timer ``id``'s take values from 0 to 3.::
from machine import Timer
from machine import Pin

1
docs/wipy/tutorial/index.rst
View File

@ -14,4 +14,5 @@ for instructions see :ref:`OTA How-To <wipy_firmware_upgrade>`.
repl.rst
blynk.rst
wlan.rst
timer.rst
reset.rst

70
docs/wipy/tutorial/timer.rst Normal file
View File

@ -0,0 +1,70 @@
Hardware 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
Further examples::
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
Additional constants for Timer class
------------------------------------
.. data:: Timer.PWM
PWM timer operating mode.
.. data:: Timer.A
.. data:: Timer.B
Selects the timer channel. Must be ORed (``Timer.A`` | ``Timer.B``) when
using a 32-bit timer.
.. data:: Timer.POSITIVE
.. data:: Timer.NEGATIVE
Timer channel polarity selection (only relevant in PWM mode).
.. data:: Timer.TIMEOUT
.. data:: Timer.MATCH
Timer channel IRQ triggers.