wip: initial code changes, starting from @tannewt's sleepio branch

20 files changed, 754 insertions, 58 deletions

diff --git a/shared-bindings/_typing/__init__.pyi b/shared-bindings/_typing/__init__.pyi
index 48e68a8d5..3b3f18cb9 100644
--- a/shared-bindings/_typing/__init__.pyi
+++ b/shared-bindings/_typing/__init__.pyi
@@ -52,3 +52,15 @@ FrameBuffer = Union[rgbmatrix.RGBMatrix]
 
   - `rgbmatrix.RGBMatrix`
 """
+
+Alarm = Union[
+    alarm_time.Time, alarm_pin.PinLevel, alarm_touch.PinTouch
+]
+"""Classes that implement the audiosample protocol
+
+  - `alarm_time.Time`
+  - `alarm_pin.PinLevel`
+  - `alarm_touch.PinTouch`
+
+  You can play use these alarms to wake from light or deep sleep.
+"""
diff --git a/shared-bindings/alarm_io/__init__.c b/shared-bindings/alarm_io/__init__.c
new file mode 100644
index 000000000..4e42f9a2e
--- /dev/null
+++ b/shared-bindings/alarm_io/__init__.c
@@ -0,0 +1,53 @@
+#include "py/obj.h"
+
+#include "shared-bindings/alarm_io/__init__.h"
+#include "shared-bindings/microcontroller/Pin.h"
+
+//| """alarm_io module
+//|
+//| The `alarm_io` module implements deep sleep."""
+
+STATIC mp_obj_t alarm_io_pin_state(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
+    enum { ARG_level, ARG_pull };
+    static const mp_arg_t allowed_args[] = {
+        { MP_QSTR_level, MP_ARG_INT | MP_ARG_KW_ONLY | MP_ARG_REQUIRED },
+        { MP_QSTR_pull, MP_ARG_INT | MP_ARG_KW_ONLY, {.u_bool = false} },
+    };
+
+    mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
+    mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
+
+    mcu_pin_obj_t *pin = validate_obj_is_pin(pos_args[0]);
+    alarm_io_obj_t *self = m_new_obj(alarm_io_obj_t);
+
+    self->base.type = &alarm_io_type;
+    self->gpio = pin->number;
+    self->level = args[ARG_level].u_int;
+    self->pull = args[ARG_pull].u_bool;
+
+    return common_hal_alarm_io_pin_state(self);
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_KW(alarm_io_pin_state_obj, 1, alarm_io_pin_state);
+
+STATIC mp_obj_t alarm_io_disable(void) {
+    common_hal_alarm_io_disable();
+    return mp_const_none;
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_0(alarm_io_disable_obj, alarm_io_disable);
+
+STATIC const mp_rom_map_elem_t alarm_io_module_globals_table[] = {
+    { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_alarm_io) },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_PinState), MP_ROM_PTR(&alarm_io_pin_state_obj) },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_Disable), MP_ROM_PTR(&alarm_io_disable_obj) },
+};
+STATIC MP_DEFINE_CONST_DICT(alarm_io_module_globals, alarm_io_module_globals_table);
+
+const mp_obj_module_t alarm_io_module = {
+    .base = { &mp_type_module },
+    .globals = (mp_obj_dict_t*)&alarm_io_module_globals,
+};
+
+const mp_obj_type_t alarm_io_type = {
+    { &mp_type_type },
+    .name = MP_QSTR_ioAlarm,
+};
diff --git a/shared-bindings/alarm_io/__init__.h b/shared-bindings/alarm_io/__init__.h
new file mode 100644
index 000000000..0a53497c0
--- /dev/null
+++ b/shared-bindings/alarm_io/__init__.h
@@ -0,0 +1,17 @@
+#ifndef MICROPY_INCLUDED_SHARED_BINDINGS_ALARM_IO___INIT___H
+#define MICROPY_INCLUDED_SHARED_BINDINGS_ALARM_IO___INIT___H
+
+#include "py/runtime.h"
+
+typedef struct {
+    mp_obj_base_t base;
+    uint8_t gpio, level;
+    bool pull;
+} alarm_io_obj_t;
+
+extern const mp_obj_type_t alarm_io_type;
+
+extern mp_obj_t common_hal_alarm_io_pin_state (alarm_io_obj_t *self_in);
+extern void common_hal_alarm_io_disable (void);
+
+#endif //MICROPY_INCLUDED_SHARED_BINDINGS_ALARM_IO___INIT___H
diff --git a/shared-bindings/alarm_time/Time.c b/shared-bindings/alarm_time/Time.c
new file mode 100644
index 000000000..904bf522e
--- /dev/null
+++ b/shared-bindings/alarm_time/Time.c
@@ -0,0 +1,76 @@
+/*
+ * This file is part of the MicroPython project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2020 Scott Shawcroft
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#include "py/obj.h"
+#include "shared-bindings/alarm_time/__init__.h"
+
+//| """alarm_time module
+//|
+//| The `alarm_time` module implements deep sleep."""
+
+STATIC mp_obj_t alarm_time_duration(mp_obj_t seconds_o) {
+    #if MICROPY_PY_BUILTINS_FLOAT
+    mp_float_t seconds = mp_obj_get_float(seconds_o);
+    mp_float_t msecs = 1000.0f * seconds + 0.5f;
+    #else
+    mp_int_t seconds = mp_obj_get_int(seconds_o);
+    mp_int_t msecs = 1000 * seconds;
+    #endif
+
+    if (seconds < 0) {
+        mp_raise_ValueError(translate("sleep length must be non-negative"));
+    }
+    common_hal_alarm_time_duration(msecs);
+
+    alarm_time_obj_t *self = m_new_obj(alarm_time_obj_t);
+    self->base.type = &alarm_time_type;
+
+    return self;
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_1(alarm_time_duration_obj, alarm_time_duration);
+
+STATIC mp_obj_t alarm_time_disable(void) {
+    common_hal_alarm_time_disable();
+    return mp_const_none;
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_0(alarm_time_disable_obj, alarm_time_disable);
+
+STATIC const mp_rom_map_elem_t alarm_time_module_globals_table[] = {
+    { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_alarm_time) },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_Duration), MP_ROM_PTR(&alarm_time_duration_obj) },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_Disable), MP_ROM_PTR(&alarm_time_disable_obj) },
+};
+STATIC MP_DEFINE_CONST_DICT(alarm_time_module_globals, alarm_time_module_globals_table);
+
+const mp_obj_module_t alarm_time_module = {
+    .base = { &mp_type_module },
+    .globals = (mp_obj_dict_t*)&alarm_time_module_globals,
+};
+
+const mp_obj_type_t alarm_time_type = {
+    { &mp_type_type },
+    .name = MP_QSTR_timeAlarm,
+};
diff --git a/shared-bindings/alarm_time/Time.h b/shared-bindings/alarm_time/Time.h
new file mode 100644
index 000000000..9962c26f2
--- /dev/null
+++ b/shared-bindings/alarm_time/Time.h
@@ -0,0 +1,42 @@
+/*
+ * This file is part of the Micro Python project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2020 Scott Shawcroft for Adafruit Industries
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#ifndef MICROPY_INCLUDED_SHARED_BINDINGS_ALARM_TIME_TIME_H
+#define MICROPY_INCLUDED_SHARED_BINDINGS_ALARM_TIME_TIME_H
+
+#include "py/runtime.h"
+
+typedef struct {
+    mp_obj_base_t base;
+    uint64_t time_to_alarm;
+} alarm_time_time_obj_t;
+
+extern const mp_obj_type_t alarm_time_time_type;
+
+void common_hal_alarm_time_time_construct(alarm_time_time_obj_t* self,
+                                          uint64_t ticks_ms);
+
+#endif //MICROPY_INCLUDED_SHARED_BINDINGS_ALARM_TIME_TIME_H
diff --git a/shared-bindings/alarm_time/__init__.c b/shared-bindings/alarm_time/__init__.c
new file mode 100644
index 000000000..904bf522e
--- /dev/null
+++ b/shared-bindings/alarm_time/__init__.c
@@ -0,0 +1,76 @@
+/*
+ * This file is part of the MicroPython project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2020 Scott Shawcroft
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#include "py/obj.h"
+#include "shared-bindings/alarm_time/__init__.h"
+
+//| """alarm_time module
+//|
+//| The `alarm_time` module implements deep sleep."""
+
+STATIC mp_obj_t alarm_time_duration(mp_obj_t seconds_o) {
+    #if MICROPY_PY_BUILTINS_FLOAT
+    mp_float_t seconds = mp_obj_get_float(seconds_o);
+    mp_float_t msecs = 1000.0f * seconds + 0.5f;
+    #else
+    mp_int_t seconds = mp_obj_get_int(seconds_o);
+    mp_int_t msecs = 1000 * seconds;
+    #endif
+
+    if (seconds < 0) {
+        mp_raise_ValueError(translate("sleep length must be non-negative"));
+    }
+    common_hal_alarm_time_duration(msecs);
+
+    alarm_time_obj_t *self = m_new_obj(alarm_time_obj_t);
+    self->base.type = &alarm_time_type;
+
+    return self;
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_1(alarm_time_duration_obj, alarm_time_duration);
+
+STATIC mp_obj_t alarm_time_disable(void) {
+    common_hal_alarm_time_disable();
+    return mp_const_none;
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_0(alarm_time_disable_obj, alarm_time_disable);
+
+STATIC const mp_rom_map_elem_t alarm_time_module_globals_table[] = {
+    { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_alarm_time) },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_Duration), MP_ROM_PTR(&alarm_time_duration_obj) },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_Disable), MP_ROM_PTR(&alarm_time_disable_obj) },
+};
+STATIC MP_DEFINE_CONST_DICT(alarm_time_module_globals, alarm_time_module_globals_table);
+
+const mp_obj_module_t alarm_time_module = {
+    .base = { &mp_type_module },
+    .globals = (mp_obj_dict_t*)&alarm_time_module_globals,
+};
+
+const mp_obj_type_t alarm_time_type = {
+    { &mp_type_type },
+    .name = MP_QSTR_timeAlarm,
+};
diff --git a/shared-bindings/alarm_time/__init__.h b/shared-bindings/alarm_time/__init__.h
new file mode 100644
index 000000000..a96383069
--- /dev/null
+++ b/shared-bindings/alarm_time/__init__.h
@@ -0,0 +1,15 @@
+#ifndef MICROPY_INCLUDED_SHARED_BINDINGS_ALARM_TIME___INIT___H
+#define MICROPY_INCLUDED_SHARED_BINDINGS_ALARM_TIME___INIT___H
+
+#include "py/runtime.h"
+
+typedef struct {
+    mp_obj_base_t base;
+} alarm_time_obj_t;
+
+extern const mp_obj_type_t alarm_time_type;
+
+extern void common_hal_alarm_time_duration (uint32_t);
+extern void common_hal_alarm_time_disable (void);
+
+#endif //MICROPY_INCLUDED_SHARED_BINDINGS_ALARM_TIME___INIT___H
diff --git a/shared-bindings/canio/BusState.c b/shared-bindings/canio/BusState.c
new file mode 100644
index 000000000..e0501b8d8
--- /dev/null
+++ b/shared-bindings/canio/BusState.c
@@ -0,0 +1,70 @@
+/*
+ * This file is part of the MicroPython project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2020 Jeff Epler for Adafruit Industries
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#include "py/enum.h"
+
+#include "shared-bindings/canio/BusState.h"
+
+MAKE_ENUM_VALUE(canio_bus_state_type, bus_state, ERROR_ACTIVE, BUS_STATE_ERROR_ACTIVE);
+MAKE_ENUM_VALUE(canio_bus_state_type, bus_state, ERROR_PASSIVE, BUS_STATE_ERROR_PASSIVE);
+MAKE_ENUM_VALUE(canio_bus_state_type, bus_state, ERROR_WARNING, BUS_STATE_ERROR_WARNING);
+MAKE_ENUM_VALUE(canio_bus_state_type, bus_state, BUS_OFF, BUS_STATE_OFF);
+
+//| class BusState:
+//|     """The state of the CAN bus"""
+//|
+//|     ERROR_ACTIVE: object
+//|     """The bus is in the normal (active) state"""
+//|
+//|     ERROR_WARNING: object
+//|     """The bus is in the normal (active) state, but a moderate number of errors have occurred recently.
+//|
+//|     NOTE: Not all implementations may use ERROR_WARNING.  Do not rely on seeing ERROR_WARNING before ERROR_PASSIVE."""
+//|
+//|     ERROR_PASSIVE: object
+//|     """The bus is in the passive state due to the number of errors that have occurred recently.
+//|
+//|     This device will acknowledge packets it receives, but cannot transmit messages.
+//|     If additional errors occur, this device may progress to BUS_OFF.
+//|     If it successfully acknowledges other packets on the bus, it can return to ERROR_WARNING or ERROR_ACTIVE and transmit packets.
+//|     """
+//|
+//|     BUS_OFF: object
+//|     """The bus has turned off due to the number of errors that have
+//|     occurred recently.  It must be restarted before it will send or receive
+//|     packets.  This device will neither send or acknowledge packets on the bus."""
+//|
+MAKE_ENUM_MAP(canio_bus_state) {
+    MAKE_ENUM_MAP_ENTRY(bus_state, ERROR_ACTIVE),
+    MAKE_ENUM_MAP_ENTRY(bus_state, ERROR_PASSIVE),
+    MAKE_ENUM_MAP_ENTRY(bus_state, ERROR_WARNING),
+    MAKE_ENUM_MAP_ENTRY(bus_state, BUS_OFF),
+};
+STATIC MP_DEFINE_CONST_DICT(canio_bus_state_locals_dict, canio_bus_state_locals_table);
+
+MAKE_PRINTER(canio, canio_bus_state);
+
+MAKE_ENUM_TYPE(canio, BusState, canio_bus_state);
diff --git a/shared-bindings/canio/BusState.h b/shared-bindings/canio/BusState.h
new file mode 100644
index 000000000..e24eba92c
--- /dev/null
+++ b/shared-bindings/canio/BusState.h
@@ -0,0 +1,33 @@
+/*
+ * This file is part of the MicroPython project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2020 Jeff Epler for Adafruit Industries
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#pragma once
+
+typedef enum {
+    BUS_STATE_ERROR_ACTIVE, BUS_STATE_ERROR_PASSIVE, BUS_STATE_ERROR_WARNING, BUS_STATE_OFF
+} canio_bus_state_t;
+
+extern const mp_obj_type_t canio_bus_state_type;
diff --git a/shared-bindings/canio/__init__.c b/shared-bindings/canio/__init__.c
index f29d3ab8a..451a68c9e 100644
--- a/shared-bindings/canio/__init__.c
+++ b/shared-bindings/canio/__init__.c
@@ -24,6 +24,16 @@
  * THE SOFTWARE.
  */
 
+#include "py/obj.h"
+
+#include "shared-bindings/canio/__init__.h"
+
+#include "shared-bindings/canio/BusState.h"
+#include "shared-bindings/canio/CAN.h"
+#include "shared-bindings/canio/Match.h"
+#include "shared-bindings/canio/Message.h"
+#include "shared-bindings/canio/Listener.h"
+
 //| """CAN bus access
 //|
 //| The `canio` module contains low level classes to support the CAN bus
@@ -57,56 +67,6 @@
 //| """
 //|
 
-#include "py/obj.h"
-#include "py/enum.h"
-
-#include "shared-bindings/canio/__init__.h"
-#include "shared-bindings/canio/CAN.h"
-#include "shared-bindings/canio/Match.h"
-#include "shared-bindings/canio/Message.h"
-#include "shared-bindings/canio/Listener.h"
-
-MAKE_ENUM_VALUE(canio_bus_state_type, bus_state, ERROR_ACTIVE, BUS_STATE_ERROR_ACTIVE);
-MAKE_ENUM_VALUE(canio_bus_state_type, bus_state, ERROR_PASSIVE, BUS_STATE_ERROR_PASSIVE);
-MAKE_ENUM_VALUE(canio_bus_state_type, bus_state, ERROR_WARNING, BUS_STATE_ERROR_WARNING);
-MAKE_ENUM_VALUE(canio_bus_state_type, bus_state, BUS_OFF, BUS_STATE_OFF);
-
-//| class BusState:
-//|     """The state of the CAN bus"""
-//|
-//|     ERROR_ACTIVE: object
-//|     """The bus is in the normal (active) state"""
-//|
-//|     ERROR_WARNING: object
-//|     """The bus is in the normal (active) state, but a moderate number of errors have occurred recently.
-//|
-//|     NOTE: Not all implementations may use ERROR_WARNING.  Do not rely on seeing ERROR_WARNING before ERROR_PASSIVE."""
-//|
-//|     ERROR_PASSIVE: object
-//|     """The bus is in the passive state due to the number of errors that have occurred recently.
-//|
-//|     This device will acknowledge packets it receives, but cannot transmit messages.
-//|     If additional errors occur, this device may progress to BUS_OFF.
-//|     If it successfully acknowledges other packets on the bus, it can return to ERROR_WARNING or ERROR_ACTIVE and transmit packets.
-//|     """
-//|
-//|     BUS_OFF: object
-//|     """The bus has turned off due to the number of errors that have
-//|     occurred recently.  It must be restarted before it will send or receive
-//|     packets.  This device will neither send or acknowledge packets on the bus."""
-//|
-MAKE_ENUM_MAP(canio_bus_state) {
-    MAKE_ENUM_MAP_ENTRY(bus_state, ERROR_ACTIVE),
-    MAKE_ENUM_MAP_ENTRY(bus_state, ERROR_PASSIVE),
-    MAKE_ENUM_MAP_ENTRY(bus_state, ERROR_WARNING),
-    MAKE_ENUM_MAP_ENTRY(bus_state, BUS_OFF),
-};
-STATIC MP_DEFINE_CONST_DICT(canio_bus_state_locals_dict, canio_bus_state_locals_table);
-
-MAKE_PRINTER(canio, canio_bus_state);
-
-MAKE_ENUM_TYPE(canio, BusState, canio_bus_state);
-
 STATIC const mp_rom_map_elem_t canio_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR_BusState), MP_ROM_PTR(&canio_bus_state_type) },
     { MP_ROM_QSTR(MP_QSTR_CAN), MP_ROM_PTR(&canio_can_type) },
diff --git a/shared-bindings/canio/__init__.h b/shared-bindings/canio/__init__.h
index e24eba92c..20b6638cd 100644
--- a/shared-bindings/canio/__init__.h
+++ b/shared-bindings/canio/__init__.h
@@ -25,9 +25,3 @@
  */
 
 #pragma once
-
-typedef enum {
-    BUS_STATE_ERROR_ACTIVE, BUS_STATE_ERROR_PASSIVE, BUS_STATE_ERROR_WARNING, BUS_STATE_OFF
-} canio_bus_state_t;
-
-extern const mp_obj_type_t canio_bus_state_type;
diff --git a/shared-bindings/microcontroller/__init__.c b/shared-bindings/microcontroller/__init__.c
index 2e58bdcc2..bbc1640f7 100644
--- a/shared-bindings/microcontroller/__init__.c
+++ b/shared-bindings/microcontroller/__init__.c
@@ -39,7 +39,6 @@
 #include "shared-bindings/microcontroller/Pin.h"
 #include "shared-bindings/microcontroller/Processor.h"
 
-#include "py/runtime.h"
 #include "supervisor/shared/translate.h"
 
 //| """Pin references and cpu functionality
@@ -136,6 +135,13 @@ STATIC mp_obj_t mcu_reset(void) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_0(mcu_reset_obj, mcu_reset);
 
+STATIC mp_obj_t mcu_sleep(void) {
+    common_hal_mcu_deep_sleep();
+    // We won't actually get here because mcu is going into sleep.
+    return mp_const_none;
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_0(mcu_sleep_obj, mcu_sleep);
+
 //| nvm: Optional[ByteArray]
 //| """Available non-volatile memory.
 //| This object is the sole instance of `nvm.ByteArray` when available or ``None`` otherwise.
@@ -171,6 +177,8 @@ STATIC const mp_rom_map_elem_t mcu_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR_enable_interrupts), MP_ROM_PTR(&mcu_enable_interrupts_obj) },
     { MP_ROM_QSTR(MP_QSTR_on_next_reset), MP_ROM_PTR(&mcu_on_next_reset_obj) },
     { MP_ROM_QSTR(MP_QSTR_reset), MP_ROM_PTR(&mcu_reset_obj) },
+    //ToDo: Remove MP_QSTR_sleep when sleep on code.py exit implemented.
+    { MP_ROM_QSTR(MP_QSTR_sleep), MP_ROM_PTR(&mcu_sleep_obj) },
     #if CIRCUITPY_INTERNAL_NVM_SIZE > 0
     { MP_ROM_QSTR(MP_QSTR_nvm),  MP_ROM_PTR(&common_hal_mcu_nvm_obj) },
     #else
diff --git a/shared-bindings/microcontroller/__init__.h b/shared-bindings/microcontroller/__init__.h
index 8abdff763..f5bcfaa08 100644
--- a/shared-bindings/microcontroller/__init__.h
+++ b/shared-bindings/microcontroller/__init__.h
@@ -28,8 +28,8 @@
 #ifndef MICROPY_INCLUDED_SHARED_BINDINGS_MICROCONTROLLER___INIT___H
 #define MICROPY_INCLUDED_SHARED_BINDINGS_MICROCONTROLLER___INIT___H
 
-#include "py/mpconfig.h"
 #include "py/obj.h"
+#include "py/mpconfig.h"
 
 #include "common-hal/microcontroller/Processor.h"
 
@@ -43,6 +43,8 @@ extern void common_hal_mcu_enable_interrupts(void);
 extern void common_hal_mcu_on_next_reset(mcu_runmode_t runmode);
 extern void common_hal_mcu_reset(void);
 
+extern void common_hal_mcu_deep_sleep(void);
+
 extern const mp_obj_dict_t mcu_pin_globals;
 
 extern const mcu_processor_obj_t common_hal_mcu_processor_obj;
diff --git a/shared-bindings/sleep/ResetReason.c b/shared-bindings/sleep/ResetReason.c
new file mode 100644
index 000000000..cce55a81a
--- /dev/null
+++ b/shared-bindings/sleep/ResetReason.c
@@ -0,0 +1,61 @@
+/*
+ * This file is part of the MicroPython project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2020 Scott Shawcroft for Adafruit Industries
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#include "py/enum.h"
+
+#include "shared-bindings/sleep/ResetReason.h"
+
+MAKE_ENUM_VALUE(sleep_reset_reason_type, reset_reason, POWER_VALID, RESET_REASON_POWER_VALID);
+MAKE_ENUM_VALUE(sleep_reset_reason_type, reset_reason, SOFTWARE, RESET_REASON_SOFTWARE);
+MAKE_ENUM_VALUE(sleep_reset_reason_type, reset_reason, DEEP_SLEEP_ALARM, RESET_REASON_DEEP_SLEEP_ALARM);
+MAKE_ENUM_VALUE(sleep_reset_reason_type, reset_reason, EXTERNAL, RESET_REASON_EXTERNAL);
+
+//| class ResetReason:
+//|     """The reason the chip was last reset"""
+//|
+//|     POWER_VALID: object
+//|     """The chip was reset and started once power levels were valid."""
+//|
+//|     SOFTWARE: object
+//|     """The chip was reset from software."""
+//|
+//|     DEEP_SLEEP_ALARM: object
+//|     """The chip was reset for deep sleep and started by an alarm."""
+//|
+//|     EXTERNAL: object
+//|     """The chip was reset by an external input such as a button."""
+//|
+MAKE_ENUM_MAP(sleep_reset_reason) {
+    MAKE_ENUM_MAP_ENTRY(reset_reason, POWER_VALID),
+    MAKE_ENUM_MAP_ENTRY(reset_reason, SOFTWARE),
+    MAKE_ENUM_MAP_ENTRY(reset_reason, DEEP_SLEEP_ALARM),
+    MAKE_ENUM_MAP_ENTRY(reset_reason, EXTERNAL),
+};
+STATIC MP_DEFINE_CONST_DICT(sleep_reset_reason_locals_dict, sleep_reset_reason_locals_table);
+
+MAKE_PRINTER(sleep, sleep_reset_reason);
+
+MAKE_ENUM_TYPE(sleep, ResetReason, sleep_reset_reason);
diff --git a/shared-bindings/sleep/ResetReason.h b/shared-bindings/sleep/ResetReason.h
new file mode 100644
index 000000000..2b312bb89
--- /dev/null
+++ b/shared-bindings/sleep/ResetReason.h
@@ -0,0 +1,36 @@
+/*
+ * This file is part of the MicroPython project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2020 Scott Shawcroft for Adafruit Industries
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#pragma once
+
+typedef enum {
+    RESET_REASON_POWER_APPLIED,
+    RESET_REASON_SOFTWARE,
+    RESET_REASON_DEEP_SLEEP_ALARM,
+    RESET_REASON_BUTTON,
+} sleep_reset_reason_t;
+
+extern const mp_obj_type_t sleep_reset_reason_type;
diff --git a/shared-bindings/sleep/__init__.c b/shared-bindings/sleep/__init__.c
new file mode 100644
index 000000000..a714e0021
--- /dev/null
+++ b/shared-bindings/sleep/__init__.c
@@ -0,0 +1,112 @@
+/*
+ * This file is part of the MicroPython project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2020 Scott Shawcroft
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#include "shared-bindings/alarm/__init__.h"
+
+//| """Light and deep sleep used to save power
+//|
+//| The `sleep` module provides sleep related functionality. There are two supported levels of
+//| sleep, light and deep.
+//|
+//| Light sleep leaves the CPU and RAM powered so that CircuitPython can resume where it left off
+//| after being woken up. Light sleep is automatically done by CircuitPython when `time.sleep()` is
+//| called. To light sleep until a non-time alarm use `sleep.sleep_until_alarm()`. Any active
+//| peripherals, such as I2C, are left on.
+//|
+//| Deep sleep shuts down power to nearly all of the chip including the CPU and RAM. This can save
+//| a more significant amount of power, but CircuitPython must start code.py from the beginning when woken
+//| up. CircuitPython will enter deep sleep automatically when the current program exits without error
+//| or calls `sys.exit(0)`.
+//| If an error causes CircuitPython to exit, error LED error flashes will be done periodically.
+//| An error includes an uncaught exception, or sys.exit called with a non-zero argumetn.
+//| To set alarms for deep sleep use `sleep.restart_on_alarm()` they will apply to next deep sleep only."""
+//|
+
+//| wake_alarm: Alarm
+//| """The most recent alarm to wake us up from a sleep (light or deep.)"""
+//|
+
+//| reset_reason: ResetReason
+//| """The reason the chip started up from reset state. This can may be power up or due to an alarm."""
+//|
+
+//| def sleep_until_alarm(alarm: Alarm, ...) -> Alarm:
+//|     """Performs a light sleep until woken by one of the alarms. The alarm that woke us up is
+//|        returned."""
+//|     ...
+//|
+
+STATIC mp_obj_t sleep_sleep_until_alarm(size_t n_args, const mp_obj_t *args) {
+}
+MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(sleep_sleep_until_alarm_obj, 1, MP_OBJ_FUN_ARGS_MAX, sleep_sleep_until_alarm);
+
+//| def restart_on_alarm(alarm: Alarm, ...) -> None:
+//|     """Set one or more alarms to wake up from a deep sleep. When awakened, ``code.py`` will restart
+//| from the beginning. The last alarm to wake us up is available as `wake_alarm`. """
+//|     ...
+//|
+STATIC mp_obj_t sleep_restart_on_alarm(size_t n_args, const mp_obj_t *args) {
+}
+MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(sleep_restart_on_alarm_obj, 1, MP_OBJ_FUN_ARGS_MAX, sleep_restart_on_alarm);
+
+
+mp_map_elem_t sleep_module_globals_table[] = {
+    { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_sleep) },
+
+    { MP_ROM_QSTR(MP_QSTR_wake_alarm), mp_const_none },
+    { MP_ROM_QSTR(MP_QSTR_reset_reason), mp_const_none },
+
+    { MP_ROM_QSTR(MP_QSTR_sleep_until_alarm), sleep_sleep_until_alarm_obj },
+    { MP_ROM_QSTR(MP_QSTR_restart_on_alarm), sleep_restart_on_alarm_obj },
+};
+STATIC MP_DEFINE_MUTABLE_DICT(sleep_module_globals, sleep_module_globals_table);
+
+// These are called from common hal code to set the current wake alarm.
+void common_hal_sleep_set_wake_alarm(mp_obj_t alarm) {
+    // Equivalent of:
+    // sleep.wake_alarm = alarm
+    mp_map_elem_t *elem =
+        mp_map_lookup(&sleep_module_globals_table, MP_ROM_QSTR(MP_QSTR_wake_alarm), MP_MAP_LOOKUP);
+    if (elem) {
+        elem->value = alarm;
+    }
+}
+
+// These are called from common hal code to set the current wake alarm.
+void common_hal_sleep_set_reset_reason(mp_obj_t reset_reason) {
+    // Equivalent of:
+    // sleep.reset_reason = reset_reason
+    mp_map_elem_t *elem =
+        mp_map_lookup(&sleep_module_globals_table, MP_ROM_QSTR(MP_QSTR_reset_reason), MP_MAP_LOOKUP);
+    if (elem) {
+        elem->value = reset_reason;
+    }
+}
+
+const mp_obj_module_t sleep_module = {
+    .base = { &mp_type_module },
+    .globals = (mp_obj_dict_t*)&sleep_module_globals,
+};
diff --git a/shared-bindings/sleep/__init__.h b/shared-bindings/sleep/__init__.h
new file mode 100644
index 000000000..cd23ba5e4
--- /dev/null
+++ b/shared-bindings/sleep/__init__.h
@@ -0,0 +1,9 @@
+#ifndef MICROPY_INCLUDED_SHARED_BINDINGS_SLEEP___INIT___H
+#define MICROPY_INCLUDED_SHARED_BINDINGS_SLEEP___INIT___H
+
+#include "py/obj.h"
+
+extern mp_obj_t common_hal_sleep_get_wake_alarm(void);
+extern sleep_reset_reason_t common_hal_sleep_get_reset_reason(void);
+
+#endif  // MICROPY_INCLUDED_SHARED_BINDINGS_SLEEPxs___INIT___H
diff --git a/shared-bindings/supervisor/RunReason.c b/shared-bindings/supervisor/RunReason.c
new file mode 100644
index 000000000..5233cf959
--- /dev/null
+++ b/shared-bindings/supervisor/RunReason.c
@@ -0,0 +1,62 @@
+/*
+ * This file is part of the MicroPython project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2020 Scott Shawcroft for Adafruit Industries
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#include "py/enum.h"
+
+#include "shared-bindings/supervisor/RunReason.h"
+
+MAKE_ENUM_VALUE(canio_bus_state_type, run_reason, ERROR_ACTIVE, RUN_REASON_STARTUP);
+MAKE_ENUM_VALUE(canio_bus_state_type, bus_state, ERROR_PASSIVE, RUN_REASON_AUTORELOAD);
+MAKE_ENUM_VALUE(canio_bus_state_type, bus_state, ERROR_WARNING, RUN_REASON_SUPERVISOR_RELOAD);
+MAKE_ENUM_VALUE(canio_bus_state_type, bus_state, BUS_OFF, RUN_REASON_RELOAD_HOTKEY);
+
+//| class RunReason:
+//|     """The state of the CAN bus"""
+//|
+//|     STARTUP: object
+//|     """The first VM was run after the microcontroller started up. See `microcontroller.start_reason`
+//|        for more detail why the microcontroller was started."""
+//|
+//|     AUTORELOAD: object
+//|     """The VM was run due to a USB write to the filesystem."""
+//|
+//|     SUPERVISOR_RELOAD: object
+//|     """The VM was run due to a call to `supervisor.reload()`."""
+//|
+//|     RELOAD_HOTKEY: object
+//|     """The VM was run due CTRL-D."""
+//|
+MAKE_ENUM_MAP(canio_bus_state) {
+    MAKE_ENUM_MAP_ENTRY(bus_state, ERROR_ACTIVE),
+    MAKE_ENUM_MAP_ENTRY(bus_state, ERROR_PASSIVE),
+    MAKE_ENUM_MAP_ENTRY(bus_state, ERROR_WARNING),
+    MAKE_ENUM_MAP_ENTRY(bus_state, BUS_OFF),
+};
+STATIC MP_DEFINE_CONST_DICT(canio_bus_state_locals_dict, canio_bus_state_locals_table);
+
+MAKE_PRINTER(canio, canio_bus_state);
+
+MAKE_ENUM_TYPE(canio, BusState, canio_bus_state);
diff --git a/shared-bindings/supervisor/RunReason.h b/shared-bindings/supervisor/RunReason.h
new file mode 100644
index 000000000..f9aaacae6
--- /dev/null
+++ b/shared-bindings/supervisor/RunReason.h
@@ -0,0 +1,36 @@
+/*
+ * This file is part of the MicroPython project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2020 Scott Shawcroft for Adafruit Industries
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#pragma once
+
+typedef enum {
+    RUN_REASON_STARTUP,
+    RUN_REASON_AUTORELOAD,
+    RUN_REASON_SUPERVISOR_RELOAD,
+    RUN_REASON_RELOAD_HOTKEY
+} supervisor_run_reason_t;
+
+extern const mp_obj_type_t canio_bus_state_type;
diff --git a/shared-bindings/supervisor/Runtime.c b/shared-bindings/supervisor/Runtime.c
index bfca6e7b1..f9db38c9b 100755
--- a/shared-bindings/supervisor/Runtime.c
+++ b/shared-bindings/supervisor/Runtime.c
@@ -90,9 +90,31 @@ const mp_obj_property_t supervisor_serial_bytes_available_obj = {
 };
 
 
+//|     run_reason: RunReason
+//|     """Returns why the Python VM was run this time."""
+//|
+STATIC mp_obj_t supervisor_get_run_reason(mp_obj_t self) {
+    if (!common_hal_get_serial_bytes_available()) {
+        return mp_const_false;
+    }
+    else {
+        return mp_const_true;
+    }
+}
+MP_DEFINE_CONST_FUN_OBJ_1(supervisor_get_run_reason_obj, supervisor_get_run_reason);
+
+const mp_obj_property_t supervisor_run_reason_obj = {
+    .base.type = &mp_type_property,
+    .proxy = {(mp_obj_t)&supervisor_get_run_reason_obj,
+              (mp_obj_t)&mp_const_none_obj,
+              (mp_obj_t)&mp_const_none_obj},
+};
+
+
 STATIC const mp_rom_map_elem_t supervisor_runtime_locals_dict_table[] = {
     { MP_ROM_QSTR(MP_QSTR_serial_connected), MP_ROM_PTR(&supervisor_serial_connected_obj) },
     { MP_ROM_QSTR(MP_QSTR_serial_bytes_available), MP_ROM_PTR(&supervisor_serial_bytes_available_obj) },
+    { MP_ROM_QSTR(MP_QSTR_run_reason), MP_ROM_PTR(&supervisor_run_reason_obj) },
 };
 
 STATIC MP_DEFINE_CONST_DICT(supervisor_runtime_locals_dict, supervisor_runtime_locals_dict_table);