From 2a38b7ad9c8064f9c94a0fd8a13734ec2ca26c1b Mon Sep 17 00:00:00 2001 From: Carlos Pereira Atencio Date: Mon, 24 Oct 2022 17:54:09 +0100 Subject: [PATCH] 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 | 25 ++++++++++++++++++++----- examples/datalog-sleep.py | 7 ++++--- 2 files changed, 24 insertions(+), 8 deletions(-) diff --git a/docs/power.rst b/docs/power.rst index ea64e54d3..09a431435 100644 --- a/docs/power.rst +++ b/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` + 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` +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. diff --git a/examples/datalog-sleep.py b/examples/datalog-sleep.py index c0f3ac3d3..ec6eecdb4 100644 --- a/examples/datalog-sleep.py +++ b/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)