diff --git a/docs/library/machine.Timer.rst b/docs/library/machine.Timer.rst
index 12db58d5c41c5292017f5b76e31e0914564f33fc..318443348e3ac9885f3f6217dac352f18753b264 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 7a4ea7f7f34b8f2247a0d690837f369ffd3e7d05..2505eb35f08c7ba8b7262bae51e3c5ef1dd04e09 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 c3d51e2e5d6a62d3ecd58d0ca2466dfc43a3b846..816de27b5aab04d4069d5833b26eab28285fcbde 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 0000000000000000000000000000000000000000..c87ac44959cf85d0b75287a12062efb7c7ac5f25
--- /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.