Skip to content

Commit ffcd3a6

Browse files
microbit-carlosmicrobit-carlos
authored
docs: Add Power Management documentation. (#754)
* docs: Add Power Management documentation. * docs: Merge the wake_source() function into deep_sleep(). * docs: Merge power.deep_sleep() `pins` & `buttons` params into `wake_on`. * docs: Move power examples to Python files, and the tech details to the end of the page.
1 parent edc9da3 commit ffcd3a6

File tree

5 files changed

+178
-0
lines changed

5 files changed

+178
-0
lines changed

‎docs/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,7 @@ Projects related to MicroPython on the BBC micro:bit include:
9191
neopixel.rst
9292
os.rst
9393
pin.rst
94+
power.rst
9495
radio.rst
9596
random.rst
9697
speaker.rst

‎docs/power-mcus.png

103 KB
Loading

‎docs/power.rst

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
Power Management **V2**
2+
***********************
3+
4+
.. py:module:: power
5+
6+
This module lets you manage the power modes of the micro:bit V2.
7+
8+
There are two micro:bit board low power modes that can be requested from
9+
MicroPython:
10+
11+
- **Deep Sleep**: Low power mode where the board can be woken up via
12+
multiple sources (pins, button presses, or a timer) and resume
13+
operation.
14+
- **Off**: The power mode with the lowest power consumption, the only way to
15+
wake up the board is via the reset button, or by plugging the USB cable while
16+
on battery power.
17+
When the board wakes up it will restart and execute your programme from the
18+
beginning.
19+
20+
More information on how these low power modes work can be found in the
21+
`Detailed Information section <#detailed-information>`_.
22+
23+
Functions
24+
=========
25+
26+
.. py:function:: off()
27+
28+
Power down the board to the lowest possible power mode.
29+
30+
This is the equivalent to pressing the reset button for a few second,
31+
to set the board in "Off mode".
32+
33+
The micro:bit will only wake up if the reset button is pressed or,
34+
if on battery power, when a USB cable is connected.
35+
36+
When the board wakes up it will start for a reset state, so your programme
37+
will start running from the beginning.
38+
39+
40+
.. py:function:: deep_sleep(ms=None, wake_on=None, run_every=False)
41+
42+
Set the micro:bit into a low power mode where it can wake up and continue
43+
operation.
44+
45+
The programme state is preserved and when it wakes up it will resume
46+
operation where it left off.
47+
48+
Deep Sleep mode will consume more battery power than Off mode.
49+
50+
The wake up sources are configured via arguments.
51+
52+
If no wake up sources have been configured it will sleep until the reset
53+
button is pressed (which resets the board) or, in battery power,
54+
when the USB cable is inserted.
55+
56+
:param ms: A time in milliseconds to wait before it wakes up.
57+
:param wake_on: A single instance or a tuple of pins and/or buttons to
58+
wake up the board, e.g. ``deep_sleep(wake_on=button_a)`` or
59+
``deep_sleep(wake_on=(pin0, pin2, button_b))``.
60+
:param run_every: Set to ``True`` to wake up with each
61+
``microbit.run_every`` scheduled run.
62+
63+
Examples
64+
========
65+
66+
Example programme showing the power management API:
67+
68+
.. include:: ../examples/low-power.py
69+
:code: python
70+
71+
72+
Example using data logging:
73+
74+
.. include:: ../examples/datalog-sleep.py
75+
:code: python
76+
77+
78+
Detailed Information
79+
====================
80+
81+
The micro:bit board has two microcontrollers (MCUs), which can be
82+
independently asleep or awake:
83+
84+
- **Target MCU** - Where MicroPython and your code run.
85+
- **Interface MCU** - A secondary microcontroller that provides the USB
86+
functionality, like the ``MICROBIT`` USB drive, and the USB serial interface.
87+
88+
.. image:: power-mcus.png
89+
90+
Each MCU can be in one of these "MCU power modes":
91+
92+
- **Awake**: Running normally.
93+
- **Sleep**: A low power mode where the MCU can be woken up from different
94+
sources and continue operation.
95+
- **Power Down**: The lowest power mode for an individual MCU, when it wakes up
96+
it will start from reset.
97+
98+
The Python code can request a "board power mode", in this case **Deep Sleep**
99+
or **Off**, which will set the Target into a specific "MCU power mode",
100+
but the Interface MCU mode will depend on the micro:bit power source,
101+
i.e. if it's powered via USB (connector to a computer) or battery.
102+
103+
In essence, on battery power the Interface MCU can go into a low power mode,
104+
but when it is connected to a computer via USB, it will stay awake to maintain
105+
the USB connection.
106+
107+
+------------------+-----------------+--------------------+
108+
| .. centered:: USB Powered (Interface always awake) |
109+
+------------------+-----------------+--------------------+
110+
| Board Power Mode | Target MCU Mode | Interface MCU mode |
111+
+==================+=================+====================+
112+
| **Deep Sleep** | 💤 Sleep | ⏰ Awake |
113+
+------------------+-----------------+--------------------+
114+
| **Off** | 📴 Power Down | ⏰ Awake |
115+
| | | (red LED blinking) |
116+
+------------------+-----------------+--------------------+
117+
118+
+------------------+-----------------+--------------------+
119+
| .. centered:: Battery Powered |
120+
+------------------+-----------------+--------------------+
121+
| Board Power Mode | Target MCU Mode | Interface MCU mode |
122+
+==================+=================+====================+
123+
| **Deep Sleep** | 💤 Sleep | 💤 Sleep |
124+
+------------------+-----------------+--------------------+
125+
| **Off** | 📴 Power Down | 📴 Power Down |
126+
+------------------+-----------------+--------------------+

‎examples/datalog-sleep.py

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
from microbit import *
2+
import power
3+
import log
4+
5+
# Log the temperature every 5 minutes
6+
@run_every(s=5)
7+
def log_temperature():
8+
log.add(temp=temperature())
9+
10+
while True:
11+
if button_a.is_pressed():
12+
# Display the temperature when button A is pressed
13+
display.scroll(temperature())
14+
# To go sleep and wake up with run_every or button A
15+
power.deep_sleep(wake_on=button_a, run_every=True)

‎examples/low-power.py

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
"""
2+
Shows a silly face on the display every 10 seconds.
3+
When button A is pressed it goes into Deep Sleep mode, and wakes 30 minutes later,
4+
or by pressing button A again.
5+
When button B is pressed it goes into to Off mode.
6+
"""
7+
from microbit import *
8+
import power
9+
10+
@run_every(s=10)
11+
def silly_face():
12+
display.show(Image.SILLY)
13+
sleep(400)
14+
15+
while True:
16+
if button_b.is_pressed():
17+
display.scroll("Off")
18+
# In this mode the micro:bit can only wake up via the reset button
19+
power.off()
20+
# This line of code will never be executed, as waking up from this
21+
# mode starts the programme from the beginning
22+
display.show(Image.SURPRISED)
23+
elif button_a.is_pressed():
24+
display.show(Image.ASLEEP)
25+
sleep(300)
26+
# Go into Deep Sleep with multiple wake up sources
27+
power.deep_sleep(
28+
wake_on=(pin0, pin1, button_a),
29+
ms=30*1000, # In 30 seconds it wakes up anyway
30+
run_every=False, # Stops run_every from waking up the board
31+
)
32+
# When the micro:bit wakes up will it continue running from here
33+
# Blink a few times to show you are waking up
34+
display.show([Image("99099:09090:99099:09990"), Image.ASLEEP] * 3, 250)
35+
display.show(Image.HAPPY)
36+
sleep(200)

0 commit comments

Comments
 (0)