Merge pull request #2 from adafruit/master

Master

7 files changed, 148 insertions, 106 deletions

diff --git a/shared-bindings/microcontroller/Pin.c b/shared-bindings/microcontroller/Pin.c
index e79663107..765e602e5 100644
--- a/shared-bindings/microcontroller/Pin.c
+++ b/shared-bindings/microcontroller/Pin.c
@@ -33,18 +33,14 @@
 #include "py/runtime.h"
 #include "supervisor/shared/translate.h"
 
-//| .. currentmodule:: microcontroller
+//| class Pin:
+//|     """Identifies an IO pin on the microcontroller."""
 //|
-//| :class:`Pin` --- Pin reference
-//| ------------------------------------------
-//|
-//| Identifies an IO pin on the microcontroller.
-//|
-//| .. class:: Pin
-//|
-//|    Identifies an IO pin on the microcontroller. They are fixed by the
-//|    hardware so they cannot be constructed on demand. Instead, use
-//|    `board` or `microcontroller.pin` to reference the desired pin.
+//|     def __init__(self, ):
+//|         """Identifies an IO pin on the microcontroller. They are fixed by the
+//|         hardware so they cannot be constructed on demand. Instead, use
+//|         `board` or `microcontroller.pin` to reference the desired pin."""
+//|         ...
 //|
 
 static void get_pin_name(const mcu_pin_obj_t *self, qstr* package, qstr* module, qstr* name) {
@@ -84,10 +80,35 @@ const mp_obj_type_t mcu_pin_type = {
     .print = mcu_pin_print
 };
 
-void assert_pin(mp_obj_t obj, bool none_ok) {
-    if ((obj != mp_const_none || !none_ok) && !MP_OBJ_IS_TYPE(obj, &mcu_pin_type)) {
+mcu_pin_obj_t *validate_obj_is_pin(mp_obj_t obj) {
+    if (!MP_OBJ_IS_TYPE(obj, &mcu_pin_type)) {
         mp_raise_TypeError_varg(translate("Expected a %q"), mcu_pin_type.name);
     }
+    return MP_OBJ_TO_PTR(obj);
+}
+
+// Validate that the obj is a pin or None. Return an mcu_pin_obj_t* or NULL, correspondingly.
+mcu_pin_obj_t *validate_obj_is_pin_or_none(mp_obj_t obj) {
+    if (obj == mp_const_none) {
+        return NULL;
+    }
+    return validate_obj_is_pin(obj);
+}
+
+mcu_pin_obj_t *validate_obj_is_free_pin(mp_obj_t obj) {
+    mcu_pin_obj_t *pin = validate_obj_is_pin(obj);
+    assert_pin_free(pin);
+    return pin;
+}
+
+// Validate that the obj is a free pin or None. Return an mcu_pin_obj_t* or NULL, correspondingly.
+mcu_pin_obj_t *validate_obj_is_free_pin_or_none(mp_obj_t obj) {
+    if (obj == mp_const_none) {
+        return NULL;
+    }
+    mcu_pin_obj_t *pin = validate_obj_is_pin(obj);
+    assert_pin_free(pin);
+    return pin;
 }
 
 void assert_pin_free(const mcu_pin_obj_t* pin) {
diff --git a/shared-bindings/microcontroller/Pin.h b/shared-bindings/microcontroller/Pin.h
index ed831b258..bb5256b55 100644
--- a/shared-bindings/microcontroller/Pin.h
+++ b/shared-bindings/microcontroller/Pin.h
@@ -33,9 +33,21 @@
 // Type object used in Python. Should be shared between ports.
 extern const mp_obj_type_t mcu_pin_type;
 
-void assert_pin(mp_obj_t obj, bool none_ok);
+mcu_pin_obj_t *validate_obj_is_pin(mp_obj_t obj);
+mcu_pin_obj_t *validate_obj_is_pin_or_none(mp_obj_t obj);
+mcu_pin_obj_t *validate_obj_is_free_pin(mp_obj_t obj);
+mcu_pin_obj_t *validate_obj_is_free_pin_or_none(mp_obj_t obj);
+
 void assert_pin_free(const mcu_pin_obj_t* pin);
 
 bool common_hal_mcu_pin_is_free(const mcu_pin_obj_t* pin);
+void common_hal_never_reset_pin(const mcu_pin_obj_t* pin);
+void common_hal_reset_pin(const mcu_pin_obj_t* pin);
+uint8_t common_hal_mcu_pin_number(const mcu_pin_obj_t* pin);
+void common_hal_mcu_pin_claim(const mcu_pin_obj_t* pin);
+void common_hal_mcu_pin_claim_number(uint8_t pin_no);
+void common_hal_mcu_pin_reset_number(uint8_t pin_no);
+
+#define COMMON_HAL_MCU_NO_PIN ((uint8_t)0xff)
 
 #endif  // MICROPY_INCLUDED_SHARED_BINDINGS_MICROCONTROLLER_PIN_H
diff --git a/shared-bindings/microcontroller/Processor.c b/shared-bindings/microcontroller/Processor.c
index be685b0a8..c4b249124 100644
--- a/shared-bindings/microcontroller/Processor.c
+++ b/shared-bindings/microcontroller/Processor.c
@@ -34,29 +34,24 @@
 
 #include "py/runtime.h"
 
-//| .. currentmodule:: microcontroller
+//| class Processor:
+//|     """Microcontroller CPU information and control
 //|
-//| :class:`Processor` --- Microcontroller CPU information and control
-//| ------------------------------------------------------------------
+//|     Usage::
 //|
-//| Get information about the microcontroller CPU and control it.
-//|
-//| Usage::
-//|
-//|    import microcontroller
-//|    print(microcontroller.cpu.frequency)
-//|    print(microcontroller.cpu.temperature)
+//|        import microcontroller
+//|        print(microcontroller.cpu.frequency)
+//|        print(microcontroller.cpu.temperature)"""
 //|
 
-//| .. class:: Processor()
-//|
-//|     You cannot create an instance of `microcontroller.Processor`.
-//|     Use `microcontroller.cpu` to access the sole instance available.
+//|     def __init__(self, ):
+//|         """You cannot create an instance of `microcontroller.Processor`.
+//|         Use `microcontroller.cpu` to access the sole instance available."""
+//|         ...
 //|
 
-//|     .. attribute:: frequency
-//|
-//|       The CPU operating frequency as an `int`, in Hertz. (read-only)
+//|     frequency: int = ...
+//|     """The CPU operating frequency in Hertz. (read-only)"""
 //|
 STATIC mp_obj_t mcu_processor_get_frequency(mp_obj_t self) {
     return mp_obj_new_int_from_uint(common_hal_mcu_processor_get_frequency());
@@ -72,11 +67,10 @@ const mp_obj_property_t mcu_processor_frequency_obj = {
     },
 };
 
-//|     .. attribute:: temperature
-//|
-//|       The on-chip temperature, in Celsius, as a float. (read-only)
+//|     temperature: Any = ...
+//|     """The on-chip temperature, in Celsius, as a float. (read-only)
 //|
-//|       Is `None` if the temperature is not available.
+//|     Is `None` if the temperature is not available."""
 //|
 STATIC mp_obj_t mcu_processor_get_temperature(mp_obj_t self) {
     float temperature = common_hal_mcu_processor_get_temperature();
@@ -93,9 +87,8 @@ const mp_obj_property_t mcu_processor_temperature_obj = {
     },
 };
 
-//|     .. attribute:: uid
-//|
-//|       The unique id (aka serial number) of the chip as a `bytearray`. (read-only)
+//|     uid: Any = ...
+//|     """The unique id (aka serial number) of the chip as a `bytearray`. (read-only)"""
 //|
 STATIC mp_obj_t mcu_processor_get_uid(mp_obj_t self) {
     uint8_t raw_id[COMMON_HAL_MCU_PROCESSOR_UID_LENGTH];
@@ -113,10 +106,31 @@ const mp_obj_property_t mcu_processor_uid_obj = {
     },
 };
 
+//|     voltage: Any = ...
+//|     """The input voltage to the microcontroller, as a float. (read-only)
+//|
+//|     Is `None` if the voltage is not available."""
+//|
+STATIC mp_obj_t mcu_processor_get_voltage(mp_obj_t self) {
+    float voltage = common_hal_mcu_processor_get_voltage();
+    return isnan(voltage) ? mp_const_none : mp_obj_new_float(voltage);
+}
+
+MP_DEFINE_CONST_FUN_OBJ_1(mcu_processor_get_voltage_obj, mcu_processor_get_voltage);
+
+const mp_obj_property_t mcu_processor_voltage_obj = {
+    .base.type = &mp_type_property,
+    .proxy = {(mp_obj_t)&mcu_processor_get_voltage_obj,  // getter
+              (mp_obj_t)&mp_const_none_obj,            // no setter
+              (mp_obj_t)&mp_const_none_obj,            // no deleter
+    },
+};
+
 STATIC const mp_rom_map_elem_t mcu_processor_locals_dict_table[] = {
     { MP_ROM_QSTR(MP_QSTR_frequency), MP_ROM_PTR(&mcu_processor_frequency_obj) },
     { MP_ROM_QSTR(MP_QSTR_temperature), MP_ROM_PTR(&mcu_processor_temperature_obj) },
     { MP_ROM_QSTR(MP_QSTR_uid), MP_ROM_PTR(&mcu_processor_uid_obj) },
+    { MP_ROM_QSTR(MP_QSTR_voltage), MP_ROM_PTR(&mcu_processor_voltage_obj) },
 };
 
 STATIC MP_DEFINE_CONST_DICT(mcu_processor_locals_dict, mcu_processor_locals_dict_table);
diff --git a/shared-bindings/microcontroller/Processor.h b/shared-bindings/microcontroller/Processor.h
index 28f054420..1088112f4 100644
--- a/shared-bindings/microcontroller/Processor.h
+++ b/shared-bindings/microcontroller/Processor.h
@@ -36,5 +36,6 @@ const mp_obj_type_t mcu_processor_type;
 uint32_t common_hal_mcu_processor_get_frequency(void);
 float common_hal_mcu_processor_get_temperature(void);
 void common_hal_mcu_processor_get_uid(uint8_t raw_id[]);
+float common_hal_mcu_processor_get_voltage(void);
 
 #endif  // MICROPY_INCLUDED_SHARED_BINDINGS_MICROCONTROLLER_PROCESSOR_H
diff --git a/shared-bindings/microcontroller/RunMode.c b/shared-bindings/microcontroller/RunMode.c
index 7c3f84fca..6db315d8d 100644
--- a/shared-bindings/microcontroller/RunMode.c
+++ b/shared-bindings/microcontroller/RunMode.c
@@ -26,28 +26,28 @@
 
 #include "shared-bindings/microcontroller/RunMode.h"
 
-//| .. currentmodule:: microcontroller
+//| class RunMode:
+//|     """run state of the microcontroller"""
 //|
-//| :class:`RunMode` -- run state of the microcontroller
-//| =============================================================
+//|     def __init__(self, ):
+//|         """Enum-like class to define the run mode of the microcontroller and
+//|         CircuitPython."""
 //|
-//| .. class:: microcontroller.RunMode
+//|     NORMAL: Any = ...
+//|     """Run CircuitPython as normal.
 //|
-//|     Enum-like class to define the run mode of the microcontroller and
-//|     CircuitPython.
+//|     :type microcontroller.RunMode:"""
 //|
-//|     .. data:: NORMAL
+//|     SAFE_MODE: Any = ...
+//|     """Run CircuitPython in safe mode. User code will not be run and the
+//|     file system will be writeable over USB.
 //|
-//|       Run CircuitPython as normal.
+//|     :type microcontroller.RunMode:"""
 //|
-//|     .. data:: SAFE_MODE
+//|     BOOTLOADER: Any = ...
+//|     """Run the bootloader.
 //|
-//|       Run CircuitPython in safe mode. User code will not be run and the
-//|       file system will be writeable over USB.
-//|
-//|     .. data:: BOOTLOADER
-//|
-//|       Run the bootloader.
+//|     :type microcontroller.RunMode:"""
 //|
 const mp_obj_type_t mcu_runmode_type;
 
diff --git a/shared-bindings/microcontroller/__init__.c b/shared-bindings/microcontroller/__init__.c
index da8d0bd94..88fe9c224 100644
--- a/shared-bindings/microcontroller/__init__.c
+++ b/shared-bindings/microcontroller/__init__.c
@@ -42,41 +42,26 @@
 #include "py/runtime.h"
 #include "supervisor/shared/translate.h"
 
-//| :mod:`microcontroller` --- Pin references and cpu functionality
-//| ================================================================
-//|
-//| .. module:: microcontroller
-//|   :synopsis: Pin references and core functionality
-//|   :platform: SAMD21, ESP8266
+//| """Pin references and cpu functionality
 //|
 //| The `microcontroller` module defines the pins from the perspective of the
-//| microcontroller. See `board` for board-specific pin mappings.
-//|
-//| Libraries
-//|
-//| .. toctree::
-//|     :maxdepth: 3
-//|
-//|     Pin
-//|     Processor
-//|     RunMode
+//| microcontroller. See `board` for board-specific pin mappings."""
 //|
 
-//| .. attribute:: cpu
-//|
-//|   CPU information and control, such as ``cpu.temperature`` and ``cpu.frequency``
-//|   (clock frequency).
-//|   This object is the sole instance of `microcontroller.Processor`.
+//| cpu: Processor = ...
+//| """CPU information and control, such as ``cpu.temperature`` and ``cpu.frequency``
+//| (clock frequency).
+//| This object is the sole instance of `microcontroller.Processor`."""
 //|
 
-//| .. method:: delay_us(delay)
-//|
-//|   Dedicated delay method used for very short delays. **Do not** do long delays
-//|   because this stops all other functions from completing. Think of this as an empty
-//|   ``while`` loop that runs for the specified ``(delay)`` time. If you have other
-//|   code or peripherals (e.g audio recording) that require specific timing or
-//|   processing while you are waiting, explore a different avenue such as using
-//|   `time.sleep()`.
+//| def delay_us(delay: Any) -> Any:
+//|     """Dedicated delay method used for very short delays. **Do not** do long delays
+//|     because this stops all other functions from completing. Think of this as an empty
+//|     ``while`` loop that runs for the specified ``(delay)`` time. If you have other
+//|     code or peripherals (e.g audio recording) that require specific timing or
+//|     processing while you are waiting, explore a different avenue such as using
+//|     `time.sleep()`."""
+//|     ...
 //|
 STATIC mp_obj_t mcu_delay_us(mp_obj_t delay_obj) {
     uint32_t delay = mp_obj_get_int(delay_obj);
@@ -87,9 +72,9 @@ STATIC mp_obj_t mcu_delay_us(mp_obj_t delay_obj) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_1(mcu_delay_us_obj, mcu_delay_us);
 
-//| .. method:: disable_interrupts()
-//|
-//|   Disable all interrupts. Be very careful, this can stall everything.
+//| def disable_interrupts() -> Any:
+//|     """Disable all interrupts. Be very careful, this can stall everything."""
+//|     ...
 //|
 STATIC mp_obj_t mcu_disable_interrupts(void) {
     common_hal_mcu_disable_interrupts();
@@ -97,9 +82,9 @@ STATIC mp_obj_t mcu_disable_interrupts(void) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_0(mcu_disable_interrupts_obj, mcu_disable_interrupts);
 
-//| .. method:: enable_interrupts()
-//|
-//|   Enable the interrupts that were enabled at the last disable.
+//| def enable_interrupts() -> Any:
+//|     """Enable the interrupts that were enabled at the last disable."""
+//|     ...
 //|
 STATIC mp_obj_t mcu_enable_interrupts(void) {
     common_hal_mcu_enable_interrupts();
@@ -107,12 +92,12 @@ STATIC mp_obj_t mcu_enable_interrupts(void) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_0(mcu_enable_interrupts_obj, mcu_enable_interrupts);
 
-//| .. method:: on_next_reset(run_mode)
-//|
-//|   Configure the run mode used the next time the microcontroller is reset but
-//|   not powered down.
+//| def on_next_reset(run_mode: microcontroller.RunMode) -> Any:
+//|     """Configure the run mode used the next time the microcontroller is reset but
+//|     not powered down.
 //|
-//|   :param ~microcontroller.RunMode run_mode: The next run mode
+//|     :param ~microcontroller.RunMode run_mode: The next run mode"""
+//|     ...
 //|
 STATIC mp_obj_t mcu_on_next_reset(mp_obj_t run_mode_obj) {
     mcu_runmode_t run_mode;
@@ -132,14 +117,14 @@ STATIC mp_obj_t mcu_on_next_reset(mp_obj_t run_mode_obj) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_1(mcu_on_next_reset_obj, mcu_on_next_reset);
 
-//| .. method:: reset()
+//| def reset() -> Any:
+//|     """Reset the microcontroller. After reset, the microcontroller will enter the
+//|     run mode last set by `on_next_reset`.
 //|
-//|   Reset the microcontroller. After reset, the microcontroller will enter the
-//|   run mode last set by `on_next_reset`.
-//|
-//|   .. warning:: This may result in file system corruption when connected to a
-//|     host computer. Be very careful when calling this! Make sure the device
-//|     "Safely removed" on Windows or "ejected" on Mac OSX and Linux.
+//|     .. warning:: This may result in file system corruption when connected to a
+//|       host computer. Be very careful when calling this! Make sure the device
+//|       "Safely removed" on Windows or "ejected" on Mac OSX and Linux."""
+//|     ...
 //|
 STATIC mp_obj_t mcu_reset(void) {
     common_hal_mcu_reset();
@@ -148,20 +133,21 @@ STATIC mp_obj_t mcu_reset(void) {
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_0(mcu_reset_obj, mcu_reset);
 
-//| .. attribute:: nvm
+//| nvm: Any = ...
+//| """Available non-volatile memory.
+//| This object is the sole instance of `nvm.ByteArray` when available or ``None`` otherwise.
 //|
-//|   Available non-volatile memory.
-//|   This object is the sole instance of `nvm.ByteArray` when available or ``None`` otherwise.
+//| :type: nvm.ByteArray or None"""
 //|
 
-//| :mod:`microcontroller.pin` --- Microcontroller pin names
+//| """:mod:`microcontroller.pin` --- Microcontroller pin names
 //| --------------------------------------------------------
 //|
 //| .. module:: microcontroller.pin
 //|   :synopsis: Microcontroller pin names
 //|   :platform: SAMD21
 //|
-//| References to pins as named by the microcontroller
+//| References to pins as named by the microcontroller"""
 //|
 const mp_obj_module_t mcu_pin_module = {
     .base = { &mp_type_module },
@@ -181,6 +167,11 @@ STATIC const mp_rom_map_elem_t mcu_module_globals_table[] = {
     #else
     { MP_ROM_QSTR(MP_QSTR_nvm),  MP_ROM_PTR(&mp_const_none_obj) },
     #endif
+    #if CIRCUITPY_WATCHDOG
+    { MP_ROM_QSTR(MP_QSTR_watchdog),  MP_ROM_PTR(&common_hal_mcu_watchdogtimer_obj) },
+    #else
+    { MP_ROM_QSTR(MP_QSTR_watchdog),  MP_ROM_PTR(&mp_const_none_obj) },
+    #endif
     { MP_ROM_QSTR(MP_QSTR_RunMode),  MP_ROM_PTR(&mcu_runmode_type) },
     { MP_ROM_QSTR(MP_QSTR_Pin),  MP_ROM_PTR(&mcu_pin_type) },
     { MP_ROM_QSTR(MP_QSTR_pin),  MP_ROM_PTR(&mcu_pin_module) },
diff --git a/shared-bindings/microcontroller/__init__.h b/shared-bindings/microcontroller/__init__.h
index e1487c555..8abdff763 100644
--- a/shared-bindings/microcontroller/__init__.h
+++ b/shared-bindings/microcontroller/__init__.h
@@ -49,10 +49,13 @@ extern const mcu_processor_obj_t common_hal_mcu_processor_obj;
 
 
 #if CIRCUITPY_INTERNAL_NVM_SIZE > 0
-
 #include "common-hal/nvm/ByteArray.h"
 extern const nvm_bytearray_obj_t common_hal_mcu_nvm_obj;
+#endif
 
+#if CIRCUITPY_WATCHDOG
+#include "common-hal/watchdog/WatchDogTimer.h"
+extern watchdog_watchdogtimer_obj_t common_hal_mcu_watchdogtimer_obj;
 #endif
 
 #endif  // MICROPY_INCLUDED_SHARED_BINDINGS_MICROCONTROLLER___INIT___H