diff options
Diffstat (limited to 'docs/library/machine.rst')
| -rw-r--r-- | docs/library/machine.rst | 31 |
1 files changed, 23 insertions, 8 deletions
diff --git a/docs/library/machine.rst b/docs/library/machine.rst index f734cccc3..a7b595776 100644 --- a/docs/library/machine.rst +++ b/docs/library/machine.rst @@ -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() |