2 files changed, 34 insertions, 4 deletions

diff --git a/docs/library/pyb.RTC.rst b/docs/library/pyb.RTC.rst
index 2f9114ac2b..eeefa100ce 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 91b8cccbde..7cad587f90 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
 -----------------------