djsundog/circuitpython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs/machine: Change sleep to lightsleep and add timeout arguments.

Browse Source 
The machine.sleep() function can be misleading because it clashes with
time.sleep() which has quite different semantics.  So change it to
machine.lightsleep() which shows that it is closer in behaviour to
machine.deepsleep().

Also, add an optional argument to these two sleep functions to specify a
maximum time to sleep for.  This is a common operation and underlying
hardware usually has a special way of performing this operation.

The existing machine.sleep() function will remain for backwards
compatibility purposes, and it can simply be an alias for
machine.lightsleep() without arguments.  The behaviour will be the same.
This commit is contained in:
Damien George 2018-12-15 16:20:18 +11:00
parent e33bc59712
commit b16146d189
1 changed files with 23 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
docs/library/machine.rst
View File

@ -63,16 +63,31 @@ Power related functions
.. function:: sleep()
Stops the CPU and disables all peripherals except for WLAN. Execution is resumed from
the point where the sleep was requested. For wake up to actually happen, wake sources
should be configured first.
.. note:: This function is deprecated, use `lightsleep()` instead with no arguments.
.. function:: deepsleep()
.. function:: lightsleep([time_ms])
deepsleep([time_ms])
Stops the CPU and all peripherals (including networking interfaces, if any). Execution
is resumed from the main script, just as with a reset. The reset cause can be checked
to know that we are coming from `machine.DEEPSLEEP`. For wake up to actually happen,
wake sources should be configured first, like `Pin` change or `RTC` timeout.
Stops execution in an attempt to enter a low power state.
If *time_ms* is specified then this will be the maximum time in milliseconds that
the sleep will last for. Otherwise the sleep can last indefinitely.
With or without a timout, execution may resume at any time if there are events
that require processing. Such events, or wake sources, should be configured before
sleeping, like `Pin` change or `RTC` timeout.
The precise behaviour and power-saving capabilities of lightsleep and deepsleep is
highly dependent on the underlying hardware, but the general properties are:
* A lightsleep has full RAM and state retention. Upon wake execution is resumed
from the point where the sleep was requested, with all subsystems operational.
* A deepsleep may not retain RAM or any other state of the system (for example
peripherals or network interfaces). Upon wake execution is resumed from the main
script, similar to a hard or power-on reset. The `reset_cause()` function will
return `machine.DEEPSLEEP` and this can be used to distinguish a deepsleep wake
from other resets.
.. function:: wake_reason()