Skip to content

docs: Add Power Management documentation. #754

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Sep 5, 2022
Merged

docs: Add Power Management documentation. #754

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
57ad425
docs: Add Power Management documentation.
microbit-carlos Apr 25, 2022
a72b2d7
docs: Merge the wake_source() function into deep_sleep().
microbit-carlos Jun 28, 2022
0825744
docs: Merge power.deep_sleep() `pins` & `buttons` params into `wake_on`.
microbit-carlos Aug 23, 2022
42db7bc
docs: Move power examples to Python files, and the tech details to th…
microbit-carlos Sep 5, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
docs: Merge the wake_source() function into deep_sleep().
  • Loading branch information
@microbit-carlos
microbit-carlos committed Aug 23, 2022
commit a72b2d78dce3a07c279045b2a7d554db507ee104
32 changes: 11 additions & 21 deletions docs/power.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,33 +81,27 @@ Functions
will start running from the beginning.


.. py:function:: deep_sleep()
.. py:function:: deep_sleep(ms=None, pins=None, buttons=None, run_every=False)
Copy link
Member

@dpgeorge dpgeorge Aug 21, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pins and buttons could actually be combined into, eg, events. Because the code can check the type of the objects passed in. Eg deep_sleep(events=(button_a, pin0)).

Copy link
Collaborator Author

@microbit-carlos microbit-carlos Aug 22, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, having the buttons for only 2 options doesn't feel quite right. Although I'm not 100% sure about the word events though, it doesn't feel very obvious deep_sleep(events=(pin1,pin2)), but it's warming up on me.

Do you think using pins and include buttons in the same argument would be confusing? deep_sleep(pins=(pin1, button_a))

Copy link
Member

@dpgeorge dpgeorge Aug 23, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about wake_on or wake_by? Eg deep_sleep(wake_on=(pin1, button_a)).

Copy link
Collaborator Author

@microbit-carlos microbit-carlos Aug 23, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wake_on sounds good 👍
Added in 0825744.

Copy link
Member

@dpgeorge dpgeorge Aug 24, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, now implemented.


Set the micro:bit into a low power mode where it can wake up and continue
operation.

The programme state is preserved and when it wakes up it will resume
operation where it left off.

The wake up sources are configured with the ``wake_source()`` function.
Deep Sleep mode will consume more battery power than Off mode.

The wake up sources are configured via arguments.

If no wake up sources have been configured it will sleep until the reset
button is pressed (which resets the Target MCU) or, in battery power,
when the USB cable is inserted.

Deep Sleep mode will consume more battery power than Off mode.

.. py:function:: wake_source(pins=None, buttons=None, ms=None, run_every=False)

Configure the "Deep Sleep" wake-up sources.

These wake-up source will not work for the Off mode.

:param ms: A time in milliseconds to wait before it wakes up.
:param pins: A single instance or a tuple of pins, e.g.
``wake_source(pins=(pin0, pin2))``.
``deep_sleep(pins=(pin0, pin2))``.
:param buttons: A single instance or a tuple of buttons, e.g.
``wake_source(buttons=button_a)``.
:param ms: A time in milliseconds to wait before it wakes up.
``deep_sleep(buttons=button_a)``.
:param run_every: Set to ``True`` to wake up with each
``microbit.run_every`` scheduled run.

Expand Down Expand Up @@ -138,15 +132,13 @@ Example programme showing the power management API::
display.show(Image.SURPRISED)
elif button_b.is_pressed():
display.scroll("Sleep")
# First let's configure the wake up sources for deep sleep
power.wake_source(
# Go into Deep Sleep with multiple wake up sources
power.deep_sleep(
pins=(pin0, pin1),
buttons=button_a,
ms=5*60*1000, # In 5 minutes it wakes up anyway
run_every=False, # Blocks run_every from waking up the board
)
# Now let's go to sleep
power.deep_sleep()
# When the micro:bit wakes up will it continue running from here
display.show(Image.ASLEEP)
sleep(1000)
Expand All @@ -164,11 +156,9 @@ Example using data logging::
def log_temperature():
log.add(temp=temperature())

# Configure the wake up sources to wake up with run_every & button A
power.wake_source(buttons=button_a, run_every=True)

while True:
if button_a.is_pressed():
# Display the temperature when button A is pressed
display.scroll(temperature())
power.deep_sleep()
# To go sleep and wake up with run_every or button A
power.deep_sleep(buttons=button_a, run_every=True)