diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/library/machine.Timer.rst | 95 | ||||
| -rw-r--r-- | docs/wipy/quickref.rst | 3 | ||||
| -rw-r--r-- | docs/wipy/tutorial/index.rst | 1 | ||||
| -rw-r--r-- | docs/wipy/tutorial/timer.rst | 70 |
4 files changed, 91 insertions, 78 deletions
diff --git a/docs/library/machine.Timer.rst b/docs/library/machine.Timer.rst index 12db58d5c4..318443348e 100644 --- a/docs/library/machine.Timer.rst +++ b/docs/library/machine.Timer.rst @@ -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,17 +96,17 @@ Methods - ``GP10`` on Timer 3 channel A. - ``GP11`` on Timer 3 channel B. -class TimerChannel --- setup a channel for a timer -================================================== +.. only:: port_wipy -Timer channels are used to generate/capture a signal using a timer. + class TimerChannel --- setup a channel for a timer + ================================================== -TimerChannel objects are created using the Timer.channel() method. + Timer channels are used to generate/capture a signal using a timer. -Methods -------- + TimerChannel objects are created using the Timer.channel() method. -.. only:: port_wipy + Methods + ------- .. method:: timerchannel.irq(\*, trigger, priority=1, handler=None) @@ -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. diff --git a/docs/wipy/quickref.rst b/docs/wipy/quickref.rst index 7a4ea7f7f3..2505eb35f0 100644 --- a/docs/wipy/quickref.rst +++ b/docs/wipy/quickref.rst @@ -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 diff --git a/docs/wipy/tutorial/index.rst b/docs/wipy/tutorial/index.rst index c3d51e2e5d..816de27b5a 100644 --- a/docs/wipy/tutorial/index.rst +++ b/docs/wipy/tutorial/index.rst @@ -14,4 +14,5 @@ for instructions see :ref:`OTA How-To <wipy_firmware_upgrade>`. repl.rst blynk.rst wlan.rst + timer.rst reset.rst diff --git a/docs/wipy/tutorial/timer.rst b/docs/wipy/tutorial/timer.rst new file mode 100644 index 0000000000..c87ac44959 --- /dev/null +++ b/docs/wipy/tutorial/timer.rst @@ -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. |