Deep Sleep #85

MrSurly · 2017-05-11T21:24:56Z

EXT0 wake:

import machine as m
p = m.Pin(4)
r = m.RTC()
p.init(p.IN, p.PULL_UP)
r.wake_on_ext0(pin = p, level = 0)
m.deepsleep()

EXT1 wake:

import machine as m
pins = (m.Pin(2), m.Pin(4))
for p in pins: 
    p.init(m.Pin.IN, m.Pin.PULL_UP)
r = m.RTC()
r.wake_on_ext1(pins = pins, level = r.WAKEUP_ALL_LOW)
m.deepsleep()

Timer wake:

import machine as m
m.deepsleep(sleep_ms = 3000)

Datetime:

import machine as m
r = m.rtc()
r.datetime() # Get: (1970, 1, 1, 5, 0, 0, 3, 62)
r.datetime((2017, 5, 17, None, 15, 21, 00, 128)) # set, weekday not used

pacmac · 2017-06-13T10:38:45Z

how can I merge this into my local rep so that I can compile and test it ?

annejan · 2017-06-13T12:16:09Z

@pacmac git pull git@github.com:MrSurly/micropython-esp32.git dev-deepsleep is one way . .

pacmac · 2017-06-13T12:33:10Z

Thanks so much, simple when you know how :-)

I learnt something today.

17o2 · 2017-07-17T18:50:04Z

Will this allow to wake up on either an external interrupt (pin) or a timeout (RTC) if no pin triggers it within a certain timeframe? Because that would be awesome. Can't wait!

MrSurly · 2017-07-17T19:08:24Z

Will this allow to wake up on either an external interrupt (pin) or a timeout (RTC) if no pin triggers it within a certain timeframe? Because that would be awesome. Can't wait!

@formatc1702: Yes, that should work.

SmileyChris · 2017-08-07T06:05:04Z

I've compiled this and tested, with everything working as expected.

I also merged against the latest esp32 branch and everything still worked as expected.

@formatc1702 I explicitly checked your case and it works fine - the following code will wake after 30 seconds or as soon as the pin is brought low:

p.init(p.IN, p.PULL_UP)
r.wake_on_ext0(pin = p, level = 0)
m.deepsleep(sleep_ms=30000)

@MrSurly I'm not sure what relevance the datetime code has to the deep sleep feature being implemented. Should that really be part of this PR?

SmileyChris · 2017-08-07T06:53:42Z

Out of interest I tried uncommenting the wake_on_touch function. If wake_on_touch(True) then machine.deepsleep() raises:
E (75307) deepsleep: Conflicting wake-up trigger: ext0

That can totally be a separate feature I feel. Let's just get the basics in!

MrSurly · 2017-08-07T13:50:05Z

@MrSurly I'm not sure what relevance the datetime code has to the deep sleep feature being implemented. Should that really be part of this PR?

This PR could be better named "Implement machine.RTC." In upstream μPy, datetime is part of machine.RTC. All of the "wake" functionality, internally, is tied to the RTC.

nickzoic · 2017-08-07T23:44:28Z

Yeah, I think the connection comes about because on some of the other platforms the RTC is what wakes the CPU from deepsleep (eg: machine.RTC.wakeup)

MrSurly · 2017-08-12T03:10:07Z

@nickzoic Speaking of which -- are there any more roadblocks to merging this?

pacmac · 2017-09-03T04:09:28Z

Are we ever going to have deepsleep on the esp32 ?, this seems to be taking a VERY long time and so many real-life projects are dependant upon this.

nickzoic · 2017-09-12T01:27:42Z

@dpgeorge if you're generally happy w/ this approach I'm happy to do some testing ...

MrSurly · 2017-09-12T03:09:35Z

I'll fix up the conflicts.

dpgeorge · 2017-09-12T07:10:30Z

@MrSurly did you consider changing the API for pin-wakeup as proposed here: #32 (comment) ?

MrSurly · 2017-09-12T14:46:12Z

@dpgeorge I did definitely consider it, and I put a lot of weight on matching existing API. However, that API is very closely tied to the PyBoard hardware, and I personally don't think it's a good idea trying to make substantially different hardware adhere to it.

To recap:

ext0 wake is a single-pin wake-on-level, which isn't much different from how the PyBoard works.
ext1 allows you to define a set of multiple pins, which can be configured as either wake on "all low" or "any high"

It's ext1 that is problematic. If we do the per-pin configuration, what's the behavior for conflicting wake-up types?

I'm totally OK with changing the API, but I need a concrete example of how it could work with the ESP32 capabilities in a way that isn't unnecessarily confusing.

dpgeorge · 2017-09-13T14:32:55Z

However, that API is very closely tied to the PyBoard hardware, and I personally don't think it's a good idea trying to make substantially different hardware adhere to it.

That API was also designed with the cc3200 in mind and the cc3200 port does implement it (for the most part). It was hoped that that API would be good enough for other MCU's as well.

It's ext1 that is problematic. If we do the per-pin configuration, what's the behavior for conflicting wake-up types?

Option 1: use the Pin.irq() method to configure everything and make it smart so it selects ext0 and/or ext1, and raises an exception if the combination of wake pins isn't supported. Eg:

pin1.irq(trigger=Pin.IRQ_LOW_LEVEL, wake=machine.DEEPSLEEP) # configures ext0
pin2.irq(trigger=Pin.IRQ_HIGH_LEVEL, wake=machine.DEEPSLEEP) # configures ext1 with "any high"
pin3.irq(trigger=Pin.IRQ_HIGH_LEVEL, wake=machine.DEEPSLEEP) # reconfigures ext1 with "any high" with pin2 and pin3
pin4.irq(trigger=Pin.IRQ_LOW_LEVEL, wake=machine.DEEPSLEEP) # raises an exception, no resources left

Note that pin.irq(wake=None) will disable that pin from waking.

Option 2: use the Pin.irq() method just to configure 1 pin using ext0, then a special esp method for ext1. Eg:

pin1.irq(trigger=Pin.IRQ_LOW_LEVEL, wake=machine.DEEPSLEEP) # configures ext0
pin2.irq(trigger=Pin.IRQ_HIGH_LEVEL, wake=machine.DEEPSLEEP) # raises an exception, no resources left
import esp
esp.wake_on_ext1(pins=(...), level=...) # configure special ext1

Option 2 is simpler to implement and at least gives a similar API for the simplest case of 1 pin waking the device. But Option 1 is not that much more difficult to implement and gives more generality.

MrSurly · 2017-09-13T16:21:54Z

Maybe a hybrid approach. I place value on code readability, thus I think EXT1 should be explicit. I get that the code should work the same as other ports (though arguably this is definitely hardware specific), at least for EXT0, so perhaps:

pin1.irq(trigger=Pin.IRQ_LOW_LEVEL, wake=machine.DEEPSLEEP) # configures ext0, matches CC3200
pin2.irq(trigger=Pin.IRQ_LOW_LEVEL, wake=machine.DEEPSLEEP) # Raises exception, no resources left

pin1.irq(wake=None) # removed Pin 1 from wake
pin2.irq(trigger=Pin.IRQ_LOW_LEVEL, wake=machine.DEEPSLEEP) # Now pin 2 works for EXT0

pin5.irq(trigger=Pin.EXT1_ANY_HIGH, wake=machine.DEEPSLEEP) # configures ext1 with "any high"
pin6.irq(trigger=Pin.EXT1_ANY_HIGH, wake=machine.DEEPSLEEP) # reconfigures ext1 with "any high" with pin2 and pin3
pin7.irq(trigger=Pin.EXT1_ALL_LOW, wake=machine.DEEPSLEEP) # raises an exception, no resources left

One other thing to consider is the wake = machine.DEEPSLEEP idiom, which kind of breaks down now that we have "light sleep".

Presently:

pin1.irq(trigger=Pin.IRQ_LOW_LEVEL, wake=machine.DEEPSLEEP)
machine.deepsleep()```

But what does the following do?

```python
pin1.irq(trigger=Pin.IRQ_LOW_LEVEL, wake=machine.DEEPSLEEP)
machine.lightsleep()

I'd argue to deprecate machine.deepsleep(), and creating machine.SLEEP and machine.sleep(). That way the sleep type is triggered by something like this:

pin1.irq(trigger=Pin.IRQ_LOW_LEVEL, wake=machine.SLEEP) # << Note 'SLEEP' instead of 'DEEPSLEEP'

machine.deepsleep() # deprecated, but still exists as an alias for machine.sleep(type = machine.DEEPSLEEP)
# or
machine.sleep(type = machine.DEEPSLEEP)
# or
machine.sleep(type = machine.LIGHTSLEEP)

Using machine.DEEPSLEEP or machine.LIGHTSLEEP for the wake parameter of Pin.irq is OK, they'd be considered synonyms for machine.SLEEP.

dpgeorge · 2017-09-14T06:35:43Z

Maybe a hybrid approach. I place value on code readability, thus I think EXT1 should be explicit.

I get your point, but the idea of machine is to be generic and provide a unified interface for all ports. Ports should try their best to conform to the API, rather than adding lots of specific things. The idea of "EXT1" is very specific to esp32 so I think if you want to make it clear that your using this special feature then it should go in the esp module (perhaps even an esp32 module since esp8266 doesn't have this feature...).

One other thing to consider is the wake = machine.DEEPSLEEP idiom, which kind of breaks down now that we have "light sleep".

The machine module has sleep() and deepsleep(). The former is used exactly in the case where execution resums from where it left off. In fact, I'd argue that machine.sleep() should be renamed to machine.lightsleep() to make this behaviour a bit more clear, and also to disambiguate from time.sleep() which has different semantics (it's not a low-power sleep).

There are also machine.SLEEP and machine.DEEPSLEEP constants to say that you want the entity (eg pin) to wake the device from these sleep states. So I think the existing API does cover the esp32's deepsleep and ligthsleep modes.

MrSurly · 2017-09-15T06:05:45Z

I get your point, but the idea of machine is to be generic and provide a unified interface for all ports. Ports should try their best to conform to the API, rather than adding lots of specific things. The idea of "EXT1" is very specific to esp32 so I think if you want to make it clear that your using this special feature then it should go in the esp module (perhaps even an esp32 module since esp8266 doesn't have this feature...).

Okay, then, how about:

Make ext0 will work as closely as possible to the current Pin.irq idiom for other ports, with the caveat that only 1 pin can be used -- configuring a second pin without deconfiguring the first means a "no resources" exception.
Move the ext1 and wake-on-touch to a new top-level esp32 module
Keep the rtc module, if only for datetime?

Issues:

Wake and IRQ are different concepts on the ESP32
- Wake only supports levels, and not edges -- what to do when wake parameter is set, and the trigger is edge-based? Exception?
- Other?

The machine module has sleep() and deepsleep(). The former is used exactly in the case where execution resums from where it left off. In fact, I'd argue that machine.sleep() should be renamed to machine.lightsleep() to make this behaviour a bit more clear, and also to disambiguate from time.sleep() which has different semantics (it's not a low-power sleep).

There are also machine.SLEEP and machine.DEEPSLEEP constants to say that you want the entity (eg pin) to wake the device from these sleep states. So I think the existing API does cover the esp32's deepsleep and ligthsleep modes.

Ah, okay. Showing my ignorance =P That will work well, then.

pacmac · 2017-09-27T13:23:01Z

Hello all, has this stalled again ??

MrSurly · 2017-09-27T16:07:27Z

Hello all, has this stalled again ??

Welcome to open source development, where everyone is busy, and nobody gets paid.

(Apologies to Whose Line Is It Anyway?)

In all seriousness, it is open source -- there's nothing stopping you from using the code right now.

Others (e.g. the SHA2017 folks) simply make their own fork and cherry pick the PRs they want. Presumably with the hope of reconciling their Python code with whatever final API shakes out in the future.

MrSurly · 2017-09-28T14:53:27Z

Screwed up a rebase pretty badly, reopening

dpgeorge · 2017-10-05T03:10:27Z

@MrSurly your suggestions above in #85 (comment) sound good!

Wake only supports levels, and not edges -- what to do when wake parameter is set, and the trigger is edge-based? Exception?

Yes, it should just accept the level-based trigger in the pin.irq() method.

MrSurly · 2017-10-05T05:30:59Z

@dpgeorge
Ok, I'll move forward when time permits.

MrSurly · 2017-11-05T18:14:53Z

@dpgeorge
Revisiting this. The Pin.irq() documentation states:

trigger configures the event which can generate an interrupt. Possible values are:
Pin.IRQ_FALLING interrupt on falling edge.
Pin.IRQ_RISING interrupt on rising edge.
Pin.IRQ_LOW_LEVEL interrupt on low level.
Pin.IRQ_HIGH_LEVEL interrupt on high level.
These values can be OR’ed together to trigger on multiple events.

The IDF only allows falling, rising, any edge, low, or high, which makes sense. The documentation above seems a bit odd -- why would you combine an edge trigger with a level, or why would you combine both levels?

I'm going to move forward with implementing what the IDF can actually do.

MrSurly · 2017-11-05T23:46:53Z

Here's the plan I'm trying to pursue for ext0:

Modify Pin.irq() to accept IRQ_LOW_LEVEL and IRQ_HIGH_LEVEL for use with normal IRQ handlers. It presently doesn't. officially support this.
Have IRQ_LOW_LEVEL and IRQ_HIGH_LEVEL also be usable by the ext0 deep sleep mode.

Problems:

Level-based IRQs seem to freeze the cpu when the level is asserted -- presumably because the ISR is being continuously called?
You can have multiple pins with level-based IRQ, but only one pin for level-based wake. Even if level-based IRQ was working, how would level-based wake work? Would it raise 'no resources' when you call machine.deepsleep(), assuming you had configured more than one pin?

Possible solution:

rename IRQ_LOW_LEVEL and IRQ_HIGH_LEVEL to WAKE_LOW_LEVEL and WAKE_HIGH_LEVEL, and these would only be used for wake.

MrSurly · 2017-11-07T04:30:29Z

Current API:

Basic sleep

import machine
machine.deepsleep() # Sleep until hard reboot
machine.deepsleep(5000) # Deep sleep for 5 seconds

machine.sleep() is implemented, but currently throws an error. If/when the IDF "light sleep" works, this can be removed.

EXT0 wakeups, using the common Micropython idiom

EXT0 wakes are for a single pin, either high or low level.

This is separate from the IRQ handler; the WAKE_LOW and WAKE_HIGH only setup the EXT0 type wake. Using a value other than WAKE_LOW or WAKE_HIGH will clear the EXT0 wake from that pin.

Additionally, any EXT0 wake will fail if esp32.wake_from_touch(True) has been called, since wake from touch and EXT0 are mutually exclusive in the IDF.

>>> import machine
>>> def h(*args): print(args)
...
>>> p1 = machine.Pin(26)
>>> p2 = machine.Pin(27)
>>> p1.irq(trigger = machine.Pin.WAKE_LOW, wake = machine.DEEPSLEEP)
<IRQ>
>>> p2.irq(trigger = machine.Pin.WAKE_LOW, wake = machine.DEEPSLEEP) 
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: no resources
>>> p1.irq(trigger=machine.Pin.IRQ_RISING, handler = h) # Clears EXT0 wake
>>> p2.irq(trigger = machine.Pin.WAKE_LOW, wake = machine.DEEPSLEEP) # EXT0 now assigned to p2
<IRQ>

Other changes to `machine`

machine.reset_cause() has been implemented, though usually returns machine.WDT_RESET since most of the time the IDF doesn't reset properly. Does properly return machine.DEEPSLEEP_RESET when waking from deep sleep.

machine.wake_reason() has been implemented.

The new top-level `esp32` module

esp32.wake_on_touch(<True|False>) Configures waking on touch. Throws ValueError('no resources') in the event that EXT0 is already configured, since they are not compatible. For this to work, you need to use machine.TouchPad().config() to configure the threshold; an interrupt handler is not required.

esp32.wake_on_ext0(<Pin>, level = <0 | 1>). Configures the EXT0 wake. This will raise ValueError('no resources') if esp32.wake_on_touch(True) has been called. It will not raise this error if another pin has already been configured, it will simply configure the new pin for EXT0 and deconfigure the old pin. If level is not specified, then it is unchanged, and defaults to 0 (low).

esp32.wake_on_ext1(pins = <sequence of Pin object>, level = <esp32.WAKEUP_ALL_LOW | esp32.WAKEUP_ANY_HIGH> ): As described above, wake on multiple pins, either "all low" or "any high".

The new `machine.RTC` module

machine.RTC.datetime() and machine.RTC.init() work as documented in mainline MicroPython.

machine.RTC.memory() Without arguments returns the RTC nonvolatile memory, as bytes. To write memory, pass a bytes, bytearray, or str object.

MrSurly · 2017-11-07T04:31:54Z

@pacmac @nickzoic @SmileyChris

Any testing/comments you could provide would be appreciated.

MrSurly · 2017-11-07T04:35:40Z

Oh, also, shout out to @manningt for the RTC.memory() implementation.

MrSurly · 2017-11-07T05:07:33Z

Squashed, pushed.

* Implement deep sleep using the Pin.irq() idiom * Stub for light sleep, when it works in the IDF * Implement machine.reset_cause() * Implement machine.wake_reason() * Add top-level esp32 module * esp32.wake_on_touch() * esp32.wake_on_ext0() * esp32.wake_on_ext1() * Implement machine.RTC * machine.RTC.datetime() * machine.RTC.memory()

MrSurly · 2017-11-10T00:08:10Z

NUDGE

Ready for testing/merging

nickzoic · 2017-11-10T01:26:04Z

I'll have a look as soon as I get a chance ...

mactijn · 2017-12-01T13:10:43Z

I've been running a prototype alarm clock with this branch for a few days now on an MH-ET Live Mini. Works completely as expected using the ntptime module from esp8266. Thanks for your work!

EDIT: if there's anything specific you'd like to have feedback on, please say so, I'd be happy to test things out.

brandond · 2017-12-08T20:45:18Z

Just started hacking on ESP32s this week. Would love to see this land ASAP!

carstenblt · 2017-12-26T10:55:55Z

Nice work, RTC() works as expected for me.

utime however counts from 2000, whereas RTC() counts from 1970 - utime.localtime() is off by 30 years.

manningt · 2017-12-26T11:15:11Z

Counting from year 2000 is intended - refer to: https://docs.micropython.org/en/latest/esp8266/library/utime.html?highlight=utime

MrSurly · 2017-12-27T02:53:27Z

utime however counts from 2000, whereas RTC() counts from 1970 - utime.localtime() is off by 30 years.

utime is correct. Just read the docs for RTC(), and it doesn't specify if RTC.init() is supposed to be 1970 or 2000. I think it needs to be 2000.

MrSurly · 2017-12-31T01:29:48Z

Moved to the main MP repo

choies1 · 2018-02-16T13:08:21Z

I downloaded "esp32-20180216-v1.9.3-315-g73d1d20b.bin (latest)" in 'http://www.micropython.org/download#esp32' to my ESP32 board.

However, I can't use RTC. What should I do to use RTC?

Followings are error messages.

>>> from machine import RTC
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ImportError: cannot import name RTC

dpgeorge · 2018-02-16T14:20:47Z

@choies1 this feature (machine.RTC) was only just merged. It should appear in the next latest build, shortly.

choies1 · 2018-02-17T23:20:03Z

RTC works from 'esp32-20180217-v1.9.3-318-g60c6b880.bin (latest)'.

MrSurly mentioned this pull request May 11, 2017

is deepsleep() anywhere near to being implemented ? #32

Closed

mcauser mentioned this pull request May 16, 2017

Setting the time on an esp32 #87

Closed

annejan mentioned this pull request Jun 7, 2017

Proper deepsleep as proposed upstream SHA2017-badge/micropython-esp32#4

Merged

MrSurly mentioned this pull request Aug 12, 2017

Support for ULP processor #154

Closed

MrSurly closed this Sep 28, 2017

MrSurly reopened this Sep 28, 2017

MrSurly mentioned this pull request Nov 20, 2017

Implemented deepsleep, reset_cause and rtc functions memory, string a… #224

Closed

carstenblt mentioned this pull request Dec 25, 2017

Timezone support for "time" module micropython/micropython#2130

Open

mactijn mentioned this pull request Dec 30, 2017

backport of MrSurly/micropython-esp32@dev-deepsleep micropython/micropython#3529

Closed

MrSurly closed this Dec 31, 2017

linuskohler mentioned this pull request Sep 15, 2018

ESP32: RTC no function 'wake_on_ext0' micropython/micropython#4142

Open

Deep Sleep #85

Deep Sleep #85

Conversation

MrSurly commented May 11, 2017 • edited Loading

EXT0 wake:

EXT1 wake:

Timer wake:

Datetime:

pacmac commented Jun 13, 2017

annejan commented Jun 13, 2017

pacmac commented Jun 13, 2017

17o2 commented Jul 17, 2017 • edited Loading

MrSurly commented Jul 17, 2017

SmileyChris commented Aug 7, 2017 • edited Loading

SmileyChris commented Aug 7, 2017

MrSurly commented Aug 7, 2017

nickzoic commented Aug 7, 2017 via email • edited Loading

MrSurly commented Aug 12, 2017

pacmac commented Sep 3, 2017

nickzoic commented Sep 12, 2017

MrSurly commented Sep 12, 2017

dpgeorge commented Sep 12, 2017

MrSurly commented Sep 12, 2017

dpgeorge commented Sep 13, 2017

MrSurly commented Sep 13, 2017

dpgeorge commented Sep 14, 2017

MrSurly commented Sep 15, 2017 • edited Loading

pacmac commented Sep 27, 2017

MrSurly commented Sep 27, 2017

MrSurly commented Sep 28, 2017 • edited Loading

dpgeorge commented Oct 5, 2017

MrSurly commented Oct 5, 2017

MrSurly commented Nov 5, 2017

MrSurly commented Nov 5, 2017

MrSurly commented Nov 7, 2017 • edited Loading

Basic sleep

EXT0 wakeups, using the common Micropython idiom

Other changes to machine

The new top-level esp32 module

The new machine.RTC module

MrSurly commented Nov 7, 2017

MrSurly commented Nov 7, 2017

MrSurly commented Nov 7, 2017

MrSurly commented Nov 10, 2017

nickzoic commented Nov 10, 2017 via email

mactijn commented Dec 1, 2017 • edited Loading

brandond commented Dec 8, 2017

carstenblt commented Dec 26, 2017

manningt commented Dec 26, 2017

MrSurly commented Dec 27, 2017

MrSurly commented Dec 31, 2017

choies1 commented Feb 16, 2018 • edited Loading

dpgeorge commented Feb 16, 2018

choies1 commented Feb 17, 2018

MrSurly commented May 11, 2017 •

edited

Loading

17o2 commented Jul 17, 2017 •

edited

Loading

SmileyChris commented Aug 7, 2017 •

edited

Loading

nickzoic commented Aug 7, 2017 via email •

edited

Loading

MrSurly commented Sep 15, 2017 •

edited

Loading

MrSurly commented Sep 28, 2017 •

edited

Loading

MrSurly commented Nov 7, 2017 •

edited

Loading

Other changes to `machine`

The new top-level `esp32` module

The new `machine.RTC` module

mactijn commented Dec 1, 2017 •

edited

Loading

choies1 commented Feb 16, 2018 •

edited

Loading