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

docs/library/machine.Timer.rst

@@ -1,53 +1,14 @@
 .. currentmodule:: machine
 
-class Timer -- control internal timers
+class Timer -- control hardware timers
 ======================================
 
-.. only:: port_wipy
+Hardware timers deal with timing of periods and events. Timers are perhaps
-
+the most flexible and heterogeneous kind of hardware in MCUs and SoCs,
-    Timers can be used for a great variety of tasks, calling a function periodically,
+differently greatly from a model to a model. MicroPython's Timer class
-    counting events, and generating a PWM signal are among the most common use cases.
+defines a baseline operation of executing a callback with a given period
-    Each timer consists of two 16-bit channels and this channels can be tied together to
+(or once after some delay), and allow specific boards to define more
-    form one 32-bit timer. The operating mode needs to be configured per timer, but then
+non-standard behavior (which thus won't be portable to other boards).
-    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
 
 .. note::
 
@@ -61,10 +22,8 @@ Constructors
 
 .. class:: Timer(id, ...)
 
-    .. only:: port_wipy
+   Construct a new timer object of the given id. Id of -1 constructs a
-
+   virtual timer (if supported by a board).
-       Construct a new timer object of the given id. ``id`` can take values from 0 to 3.
-
 
 Methods
 -------
@@ -94,8 +53,7 @@ Methods
 
 .. method:: Timer.deinit()
 
-   Deinitialises the timer. Disables all channels and associated IRQs.
+   Deinitialises the timer. Stops the timer, and disables the timer peripheral.
-   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.
+   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.

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

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

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.