Add Timer class definition (WIP)

Hardware-API.md

@@ -375,6 +375,45 @@ Methods:
 **Note:**
 _danicampora_: Just as WLAN below, I think it should be possible to retrieve the existing WDT instance when calling the constructor with no params besides the id.
 
+## The Timer class
+
+The `Timer` class provide access to the hardware timers of the SoC. It allows to generate periodic events, count events, and create PWM signals.
+
+Constructor:
+
+`timer = Timer(id, mode=Timer.PERIODIC, *, frequency, period_ns, counter_config=(prescaler, period_counts))`
+
+Since timers are used for various applications, many of which require high accuracy, having 3 ways of setting the timer frequency (freq itself, period in us or ns, and period in timer counts together with the prescaler) it's important. Having period in time units also helps readability and ease of use.
+
+**Suggestion:** On some devices, all channels of a timer must have the same frequency, but the mode can be changed. On some other devices is the other way around. Proposal: The basic API ties both things to the Timer object, but we could also accept the following:
+
+`timer = Timer(id, mode=(Timer.PERIODIC, Timer.PWM) *, ....)`
+
+Which setups the timer and configures channel 0 in periodic mode and channel 1 in PWM mode. The same could be done for the frequency:
+
+`timer = Timer(id, mode=Timer.PERIODIC *, frequency=(1000, 100))`
+
+And of course, both mode and frequency could accept a tuple. The availability of this would be hardware dependent and needs to be documented properly. Requirement is that all ports support at least the first method that fixes all channels to have the same mode and frequency. 
+
+Timer methods:
+
+- `timer.init()` re-init.
+- `timer.deinit()` disables the Timer and all it's channels.
+- `timer.counter()` gets or sets the value of the timer counter.
+- `timer.time()` gets or sets the current timer time (in ns or us, TBD). Only makes sense in PERIODIC or ONE_SHOT_MODE.
+- `timer.period()` gets or sets the timer period in ns or us.
+- `timer.counter_config()` gets or sets the `(prescaler, period_counts)` tuple.
+- `timer.frequency()` gets or sets the timer frequency/frequencies.
+- `timer.channel(id)` returns a TimerChannel object.
+
+TimerChannel methods:
+
+- `timerchannel.irq()` create a irq object associated with the channel.
+- `timerchannel.pulse_width()` in PWM mode, change the pulse width in timer count units.
+- `timerchannel.pulse_width_percent()` change the pulse width in percentage (0-100). Accepts floating point numbers if the port supports it.
+- `timerchannel.capture()`
+- `timerchannel.compare()`
+
 ## The WLAN class
 
 The WLAN class belongs to the network module.