From dea853d3a334ce5def51e803112d66b5dc8ecc3f Mon Sep 17 00:00:00 2001
From: Damien George <damien.p.george@gmail.com>
Date: Tue, 21 Apr 2015 22:35:17 +0100
Subject: [PATCH] docs: Document pyb.stop, pyb.standby and pyb.RTC.wakeup.

---
 docs/library/pyb.RTC.rst | 11 +++++++++++
 docs/library/pyb.rst     | 27 +++++++++++++++++++++++----
 2 files changed, 34 insertions(+), 4 deletions(-)

diff --git a/docs/library/pyb.RTC.rst b/docs/library/pyb.RTC.rst
index 2f9114ac2..eeefa100c 100644
--- a/docs/library/pyb.RTC.rst
+++ b/docs/library/pyb.RTC.rst
@@ -38,6 +38,17 @@ Methods
    
    ``subseconds`` counts down from 255 to 0
 
+.. method:: rtc.wakeup(timeout, callback=None)
+
+   Set the RTC wakeup timer to trigger repeatedly at every ``timeout``
+   milliseconds.  This trigger can wake the pyboard from both the sleep
+   states: :meth:`pyb.stop` and :meth:`pyb.standby`.
+
+   If ``timeout`` is ``None`` then the wakeup timer is disabled.
+
+   If ``callback`` is given then it is executed at every trigger of the
+   wakeup timer.  ``callback`` must take exactly one argument.
+
 .. method:: rtc.info()
 
    Get information about the startup time and reset source.
diff --git a/docs/library/pyb.rst b/docs/library/pyb.rst
index 91b8cccbd..7cad587f9 100644
--- a/docs/library/pyb.rst
+++ b/docs/library/pyb.rst
@@ -133,14 +133,33 @@ Power related functions
 
 .. function:: wfi()
 
-   Wait for an interrupt.
-   This executies a ``wfi`` instruction which reduces power consumption
-   of the MCU until an interrupt occurs, at which point execution continues.
+   Wait for an internal or external interrupt.
+
+   This executes a ``wfi`` instruction which reduces power consumption
+   of the MCU until any interrupt occurs (be it internal or external),
+   at which point execution continues.  Note that the system-tick interrupt
+   occurs once every millisecond (1000Hz) so this function will block for
+   at most 1ms.
+
+.. function:: stop()
+
+   Put the pyboard in a "sleeping" state.
+
+   This reduces power consumption to less than 500 uA.  To wake from this
+   sleep state requires an external interrupt or a real-time-clock event.
+   Upon waking execution continues where it left off.
+
+   See :meth:`rtc.wakeup` to configure a real-time-clock wakeup event.
 
 .. function:: standby()
 
+   Put the pyboard into a "deep sleep" state.
 
-.. function:: stop()
+   This reduces power consumption to less than 50 uA.  To wake from this
+   sleep state requires an external interrupt or a real-time-clock event.
+   Upon waking the system undergoes a hard reset.
+
+   See :meth:`rtc.wakeup` to configure a real-time-clock wakeup event.
 
 Miscellaneous functions
 -----------------------