docs: Update Power Mgm to change run_every behaviour. (#769)

* docs: Update Power Mgm to change run_every behaviour.

From waking up the board when the next function is scheduled, to
allow the scheduled functions to continue running indefinitely
while the boards sleeps.

* docs: Tweak Power Mgm run_every description & indicate UART wakeup.

docs/power.rst

@@ -9,7 +9,7 @@ There are two micro:bit board low power modes that can be requested from
 MicroPython:
 
 - **Deep Sleep**: Low power mode where the board can be woken up via
-  multiple sources (pins, button presses, or a timer) and resume
+  multiple sources (pins, button presses, uart data, or a timer) and resume
   operation.
 - **Off**: The power mode with the lowest power consumption, the only way to
   wake up the board is via the reset button, or by plugging the USB cable while
@@ -37,7 +37,7 @@ Functions
     will start running from the beginning.
 
 
-.. py:function:: deep_sleep(ms=None, wake_on=None, run_every=False)
+.. py:function:: deep_sleep(ms=None, wake_on=None, run_every=True)
 
     Set the micro:bit into a low power mode where it can wake up and continue
     operation.
@@ -49,16 +49,21 @@ Functions
 
     The wake up sources are configured via arguments.
 
-    If no wake up sources have been configured it will sleep until the reset
+    The board will always wake up when receiving UART data, when the reset
     button is pressed (which resets the board) or, in battery power,
     when the USB cable is inserted.
 
+    When the ``run_every`` parameter is set to ``True`` (the default), any
+    function scheduled with :py:meth:`microbit.run_every<microbit.run_every>`
+    will momentarily wake up the board to run and when it finishes it will go
+    back to sleep.
+
     :param ms: A time in milliseconds to wait before it wakes up.
     :param wake_on: A single instance or a tuple of pins and/or buttons to
         wake up the board, e.g. ``deep_sleep(wake_on=button_a)`` or
         ``deep_sleep(wake_on=(pin0, pin2, button_b))``.
-    :param run_every: Set to ``True`` to wake up with each
-        ``microbit.run_every`` scheduled run.
+    :param run_every: A boolean to configure if the functions scheduled with
+        ``microbit.run_every`` will continue to run while it sleeps.
 
 Examples
 ========
@@ -124,3 +129,13 @@ the USB connection.
 +------------------+-----------------+--------------------+
 | **Off**          | 📴 Power Down   | 📴 Power Down      |
 +------------------+-----------------+--------------------+
+
+Deep Sleep & run_every
+----------------------
+
+To make sure the :py:meth:`microbit.run_every<microbit.run_every>`
+functions continue to run during "Deep Sleep", the micro:bit will wake up
+at the correct time to run the next scheduled ``run_every``,
+and then go back to "Deep Sleep" mode as soon as that ``run_every`` completes.
+It will continue to do this until the deep sleep finishes due
+to the ``ms`` timeout being reached, or a ``wake_on`` event occurs.

examples/datalog-sleep.py

@@ -3,13 +3,14 @@
 import log
 
 # Log the temperature every 5 minutes
-@run_every(s=5)
+@run_every(min=5)
 def log_temperature():
     log.add(temp=temperature())
 
 while True:
+    # Display the temperature when button A is pressed
     if button_a.is_pressed():
-        # Display the temperature when button A is pressed
         display.scroll(temperature())
-    # To go sleep and wake up with run_every or button A
+    # To go sleep, wake up when button A is pressed, and ensure the
+    # function scheduled with run_every still executes in the background
     power.deep_sleep(wake_on=button_a, run_every=True)