Make ResetReason and RunReason available

[dhalbert]

• microcontroller.ResetReason and supervisor.RunReason were missing from the corresponding module dictionaries, making them unavailable.
• The printer for ResetReason mistakenly was saying it was part of alarm.
• Fixed a typo in deep-sleep API documentation.
• Remove a blank line at the top of a file (found accidentally).

Testing:

>>> import microcontroller
>>> microcontroller.<tab>
Pin             Processor       ResetReason     RunMode
cpu             delay_us        disable_interrupts
enable_interrupts               nvm             on_next_reset
pin             reset           watchdog
>>> microcontroller.ResetReason.<tab>
BROWNOUT        DEEP_SLEEP_ALARM                POWER_ON
RESET_PIN       SOFTWARE        UNKNOWN         WATCHDOG
>>> microcontroller.cpu.reset_reason
microcontroller.ResetReason.POWER_ON
>>> microcontroller.cpu.reset_reason == microcontroller.ResetReason.POWER_ON
True
>>> microcontroller.cpu.reset_reason == microcontroller.ResetReason.BROWNOUT
False
>>> import supervisor
>>> supervisor.runtime.run_reason
supervisor.RunReason.STARTUP
>>> supervisor.RunReason.STARTUP == supervisor.runtime.run_reason
True

[ladyada]

hihi fyi on some chips the reset-reason register can have multiple bits set. so you can have "power on reset" bit and "reset pin" bits both set.

[dhalbert]

hihi fyi on some chips the reset-reason register can have multiple bits set. so you can have "power on reset" bit and "reset pin" bits both set.

I am trying to think of a use case for multiple reasons, and how to decide which one to use.

We could make microcontroller.cpu.reset_reason be plural (.reset_reasons), and make it a bit mask. Then it's no longer an enum that will print as a string.

RunReason is still one at a time.

Incomplete chip survey:

SAMD51 says only one of the bits is set at at time:

---

STM32Fxx is unclear:

---

nRF is one at at time, but register is cumulative:

---

i.MX RT1050 is multiple:

[ladyada]

theres' no particular reason youd want it but i know that some chips are like that. just an FYI that may be better to do if RESET_PIN in reset_reason) instead of == to account for it?

[anecdata]

Replicating Dan's tests on ESP32-S2, looks good:

Adafruit CircuitPython 6.1.0-beta.2-5-gacbc5fc7a on 2020-12-06; FeatherS2 with ESP32S2
>>> 
>>> import microcontroller
>>> microcontroller.cpu.reset_reason
microcontroller.ResetReason.POWER_ON
>>> microcontroller.cpu.reset_reason is microcontroller.cpu.reset_reason.POWER_ON
True
>>> microcontroller.cpu.reset_reason is microcontroller.ResetReason.POWER_ON
True
>>> microcontroller.cpu.reset_reason is microcontroller.ResetReason.UNKNOWN
False
>>> 
>>> import supervisor
>>> supervisor.runtime.run_reason
supervisor.RunReason.REPL_RELOAD
>>> supervisor.runtime.run_reason is supervisor.runtime.run_reason.REPL_RELOAD
True
>>> supervisor.runtime.run_reason is supervisor.RunReason.REPL_RELOAD
True
>>> supervisor.runtime.run_reason is supervisor.RunReason.STARTUP
False

I can re-test if / when there are changes.

[dhalbert]

theres' no particular reason youd want it but i know that some chips are like that. just an FYI that may be better to do if RESET_PIN in reset_reason) instead of == to account for it?

Yes, good point. we could make it microcontroller.cpu.reset_reasons and return a set or a tuple or something else that supports in, instead of requiring someone to do bit-checking, like microcontroller.cpu.reset_reasons & microcontroller.ResetReason.POWER_ON.

[tannewt]

My preference would be a set or tuple if we want to support multiple reasons. I'm not sure we do though.

I think we can simplify to one reason. For chips that are cumulative we can clear the state or prioritize the reason.

[tannewt]

Looks good to me!

[dhalbert]

My preference would be a set or tuple if we want to support multiple reasons. I'm not sure we do though.

I think we can simplify to one reason. For chips that are cumulative we can clear the state or prioritize the reason.

This is OK with me. I think we can prioritize the reasons: I think there will be an overriding one that the user will really care about.