Diff: WakeUp.h

Revision:

8:8d9a6ac0fba8

Parent:

2:648712aa15b4

Child:

10:c41bc9154a7c

--- a/WakeUp.h	Wed Jul 23 19:54:52 2014 +0000
+++ b/WakeUp.h	Thu Jul 24 12:59:16 2014 +0000
@@ -1,22 +1,46 @@
 #include "mbed.h"
 
 /**
-* Class to make use of the LPC81x's and KL25Zs low power wake-up timer.
-*
-* One of the methods of waking up from deepsleep/powerdown is using the wake-up timer.
-* This is an ultra low-power timer that can run from an always-on clock source.
-* So while normal timers are shut-down, this one still runs, consuming only roughly 1uA.
-* If the timer does not need to run everything is shut down again by the library.
-*
-* Example program for the LPC812: http://mbed.org/users/Sissors/code/LPC812_Sleep_HelloWorld/
-*/
+ * Class to make wake up a microcontroller from deepsleep using a low-power timer. 
+ *
+ * @code
+ * // Depending on the LED connections either the LED is off the 2 seconds
+ * // the target spends in deepsleep(), and on for the other second. Or it is inverted 
+ * 
+ * #include "mbed.h"
+ * #include "WakeUp.h"
+ * 
+ * DigitalOut myled(LED1);
+ * 
+ * int main() {
+ *     //The low-power oscillator can be quite inaccurate on some targets
+ *     //this function calibrates it against the main clock
+ *     WakeUp::calibrate();
+ *    
+ *     while(1) {
+ *         //Set LED to zero
+ *         myled = 0;
+ *         
+ *         //Set wakeup time for 2 seconds
+ *         WakeUp::set_ms(2000);
+ *         
+ *         //Enter deepsleep, the program won't go beyond this point until it is woken up
+ *         deepsleep();
+ *         
+ *         //Set LED for 1 second to one
+ *         myled = 1;
+ *         wait(1);
+ *     }
+ * }
+ * @endcode
+ */
 class WakeUp
 {
 public:
     /**
     * Set the timeout
     *
-    * @param s - required time in seconds
+    * @param s required time in seconds
     */
     static void set(uint32_t s) {
         set_ms(1000 * s);
@@ -25,7 +49,7 @@
     /**
     * Set the timeout
     *
-    * @param ms - required time in milliseconds
+    * @param ms required time in milliseconds
     */
     static void set_ms(uint32_t ms);
     
@@ -35,10 +59,15 @@
     * This is optional, if you just want to wake up you 
     * do not need to attach a function.
     *
+    * Important: Many targets will run the wake-up routine
+    * at reduced clock speed, afterwards clock speed is restored.
+    * This means that clock speed dependent functions, such as printf
+    * might end up distorted.
+    *
     * Also supports normal way to attach member functions
     * (not documented for simplicity)
     *
-    * @param *function - function to call
+    * @param *function function to call
     */
     static void attach(void (*function)(void)) {
         callback.attach(function);
@@ -52,12 +81,8 @@
     /**
     * Calibrate the timer
     *
-    * The LPC812's low-power timer has a very bad accuracy: +/- 45%.
-    * This function calibrates it for 100ms against the main clock.
-    * So you get almost that accuracy by calling this function.
-    *
-    * For the KL25 it is less of a problem, with an accuracy of +/- 10%
-    * Still it can be useful for your application
+    * Some of the low-power timers have very bad accuracy.
+    * This function calibrates it against the main timer.
     *
     * Warning: Blocks for 100ms!
     */