1 files changed, 112 insertions, 0 deletions
diff --git a/docs/tutorial/timer.rst b/docs/tutorial/timer.rst
new file mode 100644
index 0000000000..22cfc012e0
--- /dev/null
+++ b/docs/tutorial/timer.rst
@@ -0,0 +1,112 @@
+The Timers
+==========
+
+The pyboard has 14 timers which each consist of an independent counter
+running at a user-defined frequency.  They can be set up to run a function
+at specific intervals.
+The 14 timers are numbered 1 through 14, but 3 is reserved
+for internal use, and 5 and 6 are used for servo and ADC/DAC control.
+Avoid using these timers if possible.
+
+Let's create a timer object::
+
+    >>> tim = pyb.Timer(4)
+
+Now let's see what we just created::
+
+    >>> tim
+    Timer(4)
+
+The pyboard is telling us that ``tim`` is attached to timer number 4, but
+it's not yet initialised.  So let's initialise it to trigger at 10 Hz
+(that's 10 times per second)::
+
+    >>> tim.init(freq=10)
+
+Now that it's initialised, we can see some information about the timer::
+
+    >>> tim
+    Timer(4, prescaler=255, period=32811, mode=0, div=0)
+
+The information means that this timer is set to run at the peripheral
+clock speed divided by 255, and it will count up to 32811, at which point
+it triggers an interrupt, and then starts counting again from 0.  These
+numbers are set to make the timer trigger at 10 Hz.
+
+Timer counter
+-------------
+
+So what can we do with our timer?  The most basic thing is to get the
+current value of its counter::
+
+    >>> tim.counter()
+    21504
+
+This counter will continuously change, and counts up.
+
+Timer callbacks
+---------------
+
+The next thing we can do is register a callback function for the timer to
+execute when it triggers (see the [switch tutorial](tut-switch) for an
+introduction to callback functions)::
+
+    >>> tim.callback(lambda t:pyb.LED(1).toggle())
+
+This should start the red LED flashing right away.  It will be flashing
+at 5 Hz (2 toggle's are needed for 1 flash, so toggling at 10 Hz makes
+it flash at 5 Hz).  You can change the frequency by re-initialising the
+timer::
+
+    >>> tim.init(freq=20)
+
+You can disable the callback by passing it the value ``None``::
+
+    >>> tim.callback(None)
+
+The function that you pass to callback must take 1 argument, which is
+the timer object that triggered.  This allows you to control the timer
+from within the callback function.
+
+We can create 2 timers and run them independently::
+
+    >>> tim4 = pyb.Timer(4, freq=10)
+    >>> tim7 = pyb.Timer(7, freq=20)
+    >>> tim4.callback(lambda t: pyb.LED(1).toggle())
+    >>> tim7.callback(lambda t: pyb.LED(2).toggle())
+
+Because the callbacks are proper hardware interrupts, we can continue
+to use the pyboard for other things while these timers are running.
+
+Making a microsecond counter
+----------------------------
+
+You can use a timer to create a microsecond counter, which might be
+useful when you are doing something which requires accurate timing.
+We will use timer 2 for this, since timer 2 has a 32-bit counter (so
+does timer 5, but if you use timer 5 then you can't use the Servo
+driver at the same time).
+
+We set up timer 2 as follows::
+
+    >>> micros = pyb.Timer(2, prescaler=83, period=0x3fffffff)
+
+The prescaler is set at 83, which makes this timer count at 1 MHz.
+This is because the CPU clock, running at 168 MHz, is divided by
+2 and then by prescaler+1, giving a freqency of 168 MHz/2/(83+1)=1 MHz
+for timer 2.  The period is set to a large number so that the timer
+can count up to a large number before wrapping back around to zero.
+In this case it will take about 17 minutes before it cycles back to
+zero.
+
+To use this timer, it's best to first reset it to 0::
+
+    >>> micros.counter(0)
+
+and then perform your timing::
+
+    >>> start_micros = micros.counter()
+
+    ... do some stuff ...
+
+    >>> end_micros = micros.counter()