Skip to content

Commit 56e7ebf

Browse files
pfalconpfalcon
committed
docs/machine.Timer: Move WiPy adhoc parts to its documentation.
1 parent 300ecac commit 56e7ebf

File tree

4 files changed

+91
-78
lines changed

4 files changed

+91
-78
lines changed

‎docs/library/machine.Timer.rst‎

Lines changed: 18 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,14 @@
11
.. currentmodule:: machine
22

3-
class Timer -- control internal timers
3+
class Timer -- control hardware timers
44
======================================
55

6-
.. only:: port_wipy
7-
8-
Timers can be used for a great variety of tasks, calling a function periodically,
9-
counting events, and generating a PWM signal are among the most common use cases.
10-
Each timer consists of two 16-bit channels and this channels can be tied together to
11-
form one 32-bit timer. The operating mode needs to be configured per timer, but then
12-
the period (or the frequency) can be independently configured on each channel.
13-
By using the callback method, the timer event can call a Python function.
14-
15-
Example usage to toggle an LED at a fixed frequency::
16-
17-
from machine import Timer
18-
from machine import Pin
19-
led = Pin('GP16', mode=Pin.OUT) # enable GP16 as output to drive the LED
20-
tim = Timer(3) # create a timer object using timer 3
21-
tim.init(mode=Timer.PERIODIC) # initialize it in periodic mode
22-
tim_ch = tim.channel(Timer.A, freq=5) # configure channel A at a frequency of 5Hz
23-
tim_ch.irq(handler=lambda t:led.toggle(), trigger=Timer.TIMEOUT) # toggle a LED on every cycle of the timer
24-
25-
Example using named function for the callback::
26-
27-
from machine import Timer
28-
from machine import Pin
29-
tim = Timer(1, mode=Timer.PERIODIC, width=32)
30-
tim_a = tim.channel(Timer.A | Timer.B, freq=1) # 1 Hz frequency requires a 32 bit timer
31-
32-
led = Pin('GP16', mode=Pin.OUT) # enable GP16 as output to drive the LED
33-
34-
def tick(timer): # we will receive the timer object when being called
35-
global led
36-
led.toggle() # toggle the LED
37-
38-
tim_a.irq(handler=tick, trigger=Timer.TIMEOUT) # create the interrupt
39-
40-
Further examples::
41-
42-
from machine import Timer
43-
tim1 = Timer(1, mode=Timer.ONE_SHOT) # initialize it in one shot mode
44-
tim2 = Timer(2, mode=Timer.PWM) # initialize it in PWM mode
45-
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
46-
tim2_ch = tim2.channel(Timer.B, freq=10000, duty_cycle=5000) # start the PWM on channel B with a 50% duty cycle
47-
tim2_ch.freq(20) # set the frequency (can also get)
48-
tim2_ch.duty_cycle(3010) # set the duty cycle to 30.1% (can also get)
49-
tim2_ch.duty_cycle(3020, Timer.NEGATIVE) # set the duty cycle to 30.2% and change the polarity to negative
50-
tim2_ch.period(2000000) # change the period to 2 seconds
6+
Hardware timers deal with timing of periods and events. Timers are perhaps
7+
the most flexible and heterogeneous kind of hardware in MCUs and SoCs,
8+
differently greatly from a model to a model. MicroPython's Timer class
9+
defines a baseline operation of executing a callback with a given period
10+
(or once after some delay), and allow specific boards to define more
11+
non-standard behavior (which thus won't be portable to other boards).
5112

5213
.. note::
5314

@@ -61,10 +22,8 @@ Constructors
6122

6223
.. class:: Timer(id, ...)
6324

64-
.. only:: port_wipy
65-
66-
Construct a new timer object of the given id. ``id`` can take values from 0 to 3.
67-
25+
Construct a new timer object of the given id. Id of -1 constructs a
26+
virtual timer (if supported by a board).
6827

6928
Methods
7029
-------
@@ -94,8 +53,7 @@ Methods
9453

9554
.. method:: Timer.deinit()
9655

97-
Deinitialises the timer. Disables all channels and associated IRQs.
98-
Stops the timer, and disables the timer peripheral.
56+
Deinitialises the timer. Stops the timer, and disables the timer peripheral.
9957

10058
.. only:: port_wipy
10159

@@ -138,17 +96,17 @@ Methods
13896
- ``GP10`` on Timer 3 channel A.
13997
- ``GP11`` on Timer 3 channel B.
14098

141-
class TimerChannel --- setup a channel for a timer
142-
==================================================
99+
.. only:: port_wipy
143100

144-
Timer channels are used to generate/capture a signal using a timer.
101+
class TimerChannel --- setup a channel for a timer
102+
==================================================
145103

146-
TimerChannel objects are created using the Timer.channel() method.
104+
Timer channels are used to generate/capture a signal using a timer.
147105

148-
Methods
149-
-------
106+
TimerChannel objects are created using the Timer.channel() method.
150107

151-
.. only:: port_wipy
108+
Methods
109+
-------
152110

153111
.. method:: timerchannel.irq(\*, trigger, priority=1, handler=None)
154112

@@ -194,22 +152,5 @@ Constants
194152

195153
.. data:: Timer.ONE_SHOT
196154
.. data:: Timer.PERIODIC
197-
.. data:: Timer.PWM
198-
199-
Selects the timer operating mode.
200-
201-
.. data:: Timer.A
202-
.. data:: Timer.B
203-
204-
Selects the timer channel. Must be ORed (``Timer.A`` | ``Timer.B``) when
205-
using a 32-bit timer.
206-
207-
.. data:: Timer.POSITIVE
208-
.. data:: Timer.NEGATIVE
209-
210-
Timer channel polarity selection (only relevant in PWM mode).
211-
212-
.. data:: Timer.TIMEOUT
213-
.. data:: Timer.MATCH
214155

215-
Timer channel IRQ triggers.
156+
Timer operating mode.

‎docs/wipy/quickref.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,8 @@ See :ref:`machine.Pin <machine.Pin>`. ::
4444
Timers
4545
------
4646

47-
See :ref:`machine.Timer <machine.Timer>` and :ref:`machine.Pin <machine.Pin>`. ::
47+
See :ref:`machine.Timer <machine.Timer>` and :ref:`machine.Pin <machine.Pin>`.
48+
Timer ``id``'s take values from 0 to 3.::
4849

4950
from machine import Timer
5051
from machine import Pin

‎docs/wipy/tutorial/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,4 +14,5 @@ for instructions see :ref:`OTA How-To <wipy_firmware_upgrade>`.
1414
repl.rst
1515
blynk.rst
1616
wlan.rst
17+
timer.rst
1718
reset.rst

‎docs/wipy/tutorial/timer.rst‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
Hardware timers
2+
===============
3+
4+
Timers can be used for a great variety of tasks, calling a function periodically,
5+
counting events, and generating a PWM signal are among the most common use cases.
6+
Each timer consists of two 16-bit channels and this channels can be tied together to
7+
form one 32-bit timer. The operating mode needs to be configured per timer, but then
8+
the period (or the frequency) can be independently configured on each channel.
9+
By using the callback method, the timer event can call a Python function.
10+
11+
Example usage to toggle an LED at a fixed frequency::
12+
13+
from machine import Timer
14+
from machine import Pin
15+
led = Pin('GP16', mode=Pin.OUT) # enable GP16 as output to drive the LED
16+
tim = Timer(3) # create a timer object using timer 3
17+
tim.init(mode=Timer.PERIODIC) # initialize it in periodic mode
18+
tim_ch = tim.channel(Timer.A, freq=5) # configure channel A at a frequency of 5Hz
19+
tim_ch.irq(handler=lambda t:led.toggle(), trigger=Timer.TIMEOUT) # toggle a LED on every cycle of the timer
20+
21+
Example using named function for the callback::
22+
23+
from machine import Timer
24+
from machine import Pin
25+
tim = Timer(1, mode=Timer.PERIODIC, width=32)
26+
tim_a = tim.channel(Timer.A | Timer.B, freq=1) # 1 Hz frequency requires a 32 bit timer
27+
28+
led = Pin('GP16', mode=Pin.OUT) # enable GP16 as output to drive the LED
29+
30+
def tick(timer): # we will receive the timer object when being called
31+
global led
32+
led.toggle() # toggle the LED
33+
34+
tim_a.irq(handler=tick, trigger=Timer.TIMEOUT) # create the interrupt
35+
36+
Further examples::
37+
38+
from machine import Timer
39+
tim1 = Timer(1, mode=Timer.ONE_SHOT) # initialize it in one shot mode
40+
tim2 = Timer(2, mode=Timer.PWM) # initialize it in PWM mode
41+
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
42+
tim2_ch = tim2.channel(Timer.B, freq=10000, duty_cycle=5000) # start the PWM on channel B with a 50% duty cycle
43+
tim2_ch.freq(20) # set the frequency (can also get)
44+
tim2_ch.duty_cycle(3010) # set the duty cycle to 30.1% (can also get)
45+
tim2_ch.duty_cycle(3020, Timer.NEGATIVE) # set the duty cycle to 30.2% and change the polarity to negative
46+
tim2_ch.period(2000000) # change the period to 2 seconds
47+
48+
49+
Additional constants for Timer class
50+
------------------------------------
51+
52+
.. data:: Timer.PWM
53+
54+
PWM timer operating mode.
55+
56+
.. data:: Timer.A
57+
.. data:: Timer.B
58+
59+
Selects the timer channel. Must be ORed (``Timer.A`` | ``Timer.B``) when
60+
using a 32-bit timer.
61+
62+
.. data:: Timer.POSITIVE
63+
.. data:: Timer.NEGATIVE
64+
65+
Timer channel polarity selection (only relevant in PWM mode).
66+
67+
.. data:: Timer.TIMEOUT
68+
.. data:: Timer.MATCH
69+
70+
Timer channel IRQ triggers.

0 commit comments

Comments
 (0)