Update documentation

Author: mikee47

docs/source/information/index.rst

@@ -5,6 +5,7 @@ Information
    :maxdepth: 1
 
    /_inc/Sming/building
+   events
    interrupts
    timers
    debugging

docs/source/information/timers.rst

@@ -1,5 +1,19 @@
 Timers
-------
+======
+
+.. highlight:: c++
+
+Generally, timers in Sming fall into two categories: Callback Timers and Polled Timers
+
+Callback Timers
+---------------
+
+A callback timer is operated by programming a time interval, then arming it. When the timer
+'fires' a function of your choosing gets called. Timers can be 'one-shot', for timing single
+events, or 'auto-reset' repetitive timers. A repetitive timer will ensure that time intervals
+between successive callbacks are consistent.
+
+There are two categories of callback timer.
 
 Hardware timers
    The ESP8266 has two main hardware timers. Timer1 is a countdown timer, which triggers
@@ -24,3 +38,96 @@ Software timers
    and delegate callback functions so you can use it with class methods, capturing lambdas, etc.
 
    The *SimpleTimer* class uses less RAM, but only supports regular function callbacks.
+
+Polled timers
+-------------
+
+Polled timers can be used to measure elapsed time intervals or to check for timeouts within code loops.
+Traditionally one might do this as follows::
+
+   #define TIMEOUT_MS 100
+
+   int timeout = millis() + TIMEOUT_MS;
+   while(millis() < timeout) {
+      // do some stuff
+   }
+   int elapsed = millis() - start;
+   Serial.print("Elapsed time: ");
+   Serial.print(elapsed);
+   Serial.println("ms");
+
+This looks OK, and will work until millis() approaches MAXINT at which point it falls over, a little under 25 days.
+With microseconds it'll happen in less than an hour. It should always be coded like this::
+
+   int start = millis();
+   while(millis() - start < TIMEOUT_MS) {
+      // do some stuff
+   }
+
+The easy way to get it right is to use a Polled Timer, like this::
+
+   OneShotFastMs timer(TIMEOUT_MS);
+   while(!timer.expired()) {
+      // do some stuff
+   }
+   auto elapsed = timer.elapsedTime(); // This obtains a `Time` object, containing a value plus time unit
+   Serial.print("Elapsed time: ");
+   Serial.println(elapsed); // Includes units in the elapsed time interval
+
+If you prefer to use microseconds, use *OneShotFastUs* instead. You can work with other units
+of time like this::
+
+   OneShotElapseTimer<NanoTime::Seconds>;
+
+Another advantage of polled timers is speed. Every call to millis (or micros) requires a calculation
+from clock ticks into milliseconds (or microseconds). It's also a function call.
+
+Polled timers measure time using hardware clock ticks, and queries the hardware timer register directly.
+The code is also compiled inline so there is no function call overhead. This makes them a much better
+choice for tight timing loops.
+
+See *PolledTimer.h* for more details.
+
+Clocks
+------
+
+Timers and their capabilities can vary considerably. For example, Timer1 can be configured with
+a prescaler of 1, 16 or 256 which affects both the resolution and range of the timer. One might
+also consider the CPU cycle counter to have a selectable prescaler of 1 or 2, depending on
+whether it's running at 80MHz or 160MHz.
+
+Each hardware timer has an associated *Clock* definition in `Platform/Clocks.h`, each of which
+simply defines the properties for each Clock source. It's defined as a class template.
+
+Clocks are made more useful by *TimeSource*, another class template defined in *NanoTime.h*.
+Any time you need to convert between time values and tick values, it'll be through a method
+of a TimeSource.
+
+Let's say we want a microsecond source using Timer2::
+
+   TimeSource<Timer2Clock, NanoTime::Microseconds, uint32_t> t2source;
+
+We can now call methods of *t2source* like this::
+
+   // What's the maximum Timer2 value in microseconds?
+   Serial.println(t2source.maxClockTime());
+
+   // How many clock ticks per microsecond ?
+   Serial.println(t2source.ticksPerUnit()); // 5/1
+
+   // How many clock ticks for 100us ?
+   Serial.println(t2source.template timeConst<100>().ticks());
+
+Note that all of these values are computed at compile time. Some runtime conversions::
+
+   Serial.println(t2source.timeToTicks(100));
+   Serial.println(t2source.ticksToTime(10000));
+
+The results of conversions are rounded rather than truncated, which provides more accurate
+results and reduces timing jitter.
+ 
+For debugging purposes you can print a description::
+
+   Serial.println(t2source.toString()); // "Timer2Clock/5MHz/32-bit/microseconds"
+
+See *NanoTime.h* for further details.