update Python API according to review comments

Author: dhalbert

ports/nrf/bluetooth/ble_uart.c

@@ -40,7 +40,7 @@
 #include "shared-bindings/_bleio/Service.h"
 #include "shared-bindings/_bleio/UUID.h"
 
-#if CIRCUITPY_REPL_BLE
+#if CIRCUITPY_CONSOLE_BLE
 
 static const char default_name[] = "CP-REPL"; // max 8 chars or uuid won't fit in adv data
 static const char NUS_UUID[] = "6e400001-b5a3-f393-e0a9-e50e24dcca9e";
@@ -188,4 +188,4 @@ void mp_hal_stdout_tx_strn(const char *str, size_t len) {
     }
 }
 
-#endif // CIRCUITPY_REPL_BLE
+#endif // CIRCUITPY_CONSOLE_BLE

ports/nrf/supervisor/serial.c

@@ -28,15 +28,15 @@
 
 #include "supervisor/serial.h"
 
-#if CIRCUITPY_REPL_BLE
+#if CIRCUITPY_CONSOLE_BLE
 #include "ble_uart.h"
-#elif CIRCUITPY_REPL_UART
+#elif CIRCUITPY_CONSOLE_UART
 #include <string.h>
 #include "nrf_gpio.h"
 #include "nrfx_uarte.h"
 #endif
 
-#if CIRCUITPY_REPL_BLE
+#if CIRCUITPY_CONSOLE_BLE
 
 void serial_init(void) {
     ble_uart_init();
@@ -58,7 +58,7 @@ void serial_write(const char *text) {
     ble_uart_stdout_tx_str(text);
 }
 
-#elif CIRCUITPY_REPL_UART
+#elif CIRCUITPY_CONSOLE_UART
 
 uint8_t serial_received_char;
 nrfx_uarte_t serial_instance = NRFX_UARTE_INSTANCE(0);
@@ -124,4 +124,4 @@ void serial_write_substring(const char *text, uint32_t len) {
     }
 }
 
-#endif  // CIRCUITPY_REPL_UART
+#endif  // CIRCUITPY_CONSOLE_UART

py/circuitpy_mpconfig.mk

@@ -133,6 +133,12 @@ CFLAGS += -DCIRCUITPY_DIGITALIO=$(CIRCUITPY_DIGITALIO)
 CIRCUITPY_COMPUTED_GOTO_SAVE_SPACE ?= 0
 CFLAGS += -DCIRCUITPY_COMPUTED_GOTO_SAVE_SPACE=$(CIRCUITPY_COMPUTED_GOTO_SAVE_SPACE)
 
+CIRCUITPY_CONSOLE_BLE ?= 0
+CFLAGS += -DCIRCUITPY_CONSOLE_BLE=$(CIRCUITPY_CONSOLE_BLE)
+
+CIRCUITPY_CONSOLE_UART ?= 0
+CFLAGS += -DCIRCUITPY_CONSOLE_UART=$(CIRCUITPY_CONSOLE_UART)
+
 CIRCUITPY_COUNTIO ?= $(CIRCUITPY_FULL_BUILD)
 CFLAGS += -DCIRCUITPY_COUNTIO=$(CIRCUITPY_COUNTIO)
 
@@ -246,12 +252,6 @@ CFLAGS += -DCIRCUITPY_RE=$(CIRCUITPY_RE)
 CIRCUITPY_RE_DEBUG ?= 0
 CFLAGS += -DCIRCUITPY_RE_DEBUG=$(CIRCUITPY_RE_DEBUG)
 
-CIRCUITPY_REPL_BLE ?= 0
-CFLAGS += -DCIRCUITPY_REPL_BLE=$(CIRCUITPY_REPL_BLE)
-
-CIRCUITPY_REPL_UART ?= 0
-CFLAGS += -DCIRCUITPY_REPL_UART=$(CIRCUITPY_REPL_UART)
-
 # Should busio.I2C() check for pullups?
 # Some boards in combination with certain peripherals may not want this.
 CIRCUITPY_REQUIRE_I2C_PULLUPS ?= 1
@@ -337,8 +337,8 @@ CFLAGS += -DCIRCUITPY_USB=$(CIRCUITPY_USB)
 
 CIRCUITPY_USB_CDC ?= 1
 CFLAGS += -DCIRCUITPY_USB_CDC=$(CIRCUITPY_USB_CDC)
-CIRCUITPY_USB_CDC_REPL_ENABLED_DEFAULT ?= 1
-CFLAGS += -DCIRCUITPY_USB_CDC_REPL_ENABLED_DEFAULT=$(CIRCUITPY_USB_CDC_REPL_ENABLED_DEFAULT)
+CIRCUITPY_USB_CDC_CONSOLE_ENABLED_DEFAULT ?= 1
+CFLAGS += -DCIRCUITPY_USB_CDC_CONSOLE_ENABLED_DEFAULT=$(CIRCUITPY_USB_CDC_CONSOLE_ENABLED_DEFAULT)
 CIRCUITPY_USB_CDC_DATA_ENABLED_DEFAULT ?= 0
 CFLAGS += -DCIRCUITPY_USB_CDC_DATA_ENABLED_DEFAULT=$(CIRCUITPY_USB_CDC_DATA_ENABLED_DEFAULT)
 

shared-bindings/storage/__init__.c

@@ -158,33 +158,45 @@ mp_obj_t storage_erase_filesystem(void) {
 }
 MP_DEFINE_CONST_FUN_OBJ_0(storage_erase_filesystem_obj, storage_erase_filesystem);
 
-//| def configure_usb(enabled: bool = True) -> None:
-//|     """Configure the USB mass storage device.
-//|     Enable or disable presenting ``CIRCUITPY`` as a USB mass storage device.
+//| def disable_usb_drive() -> None:
+//|     """Disable presenting ``CIRCUITPY`` as a USB mass storage device.
 //|     By default, the device is enabled and ``CIRCUITPY`` is visible.
-//|     Can be called in ``boot.py``, before USB is connected.
+//|     Can be called in ``boot.py``, before USB is connected."""
+//|     ...
 //|
-//|     :param enabled bool: Enable or disable the USB mass storage device.
-//|       True to enable; False to disable. Enabled by default."""
+STATIC mp_obj_t storage_disable_usb_drive(void) {
+    if (!common_hal_storage_disable_usb_drive()) {
+        mp_raise_RuntimeError(translate("Cannot change usb devices now"));
+    }
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_0(storage_disable_usb_drive_obj, storage_disable_usb_drive);
+
+//| def enable_usb_drive() -> None:
+//|     """Enabled presenting ``CIRCUITPY`` as a USB mass storage device.
+//|     By default, the device is enabled and ``CIRCUITPY`` is visible,
+//|     so you do not normally need to call this function.
+//|     Can be called in ``boot.py``, before USB is connected."""
 //|     ...
 //|
-STATIC mp_obj_t storage_configure_usb(mp_obj_t enabled) {
-    if (!common_hal_storage_configure_usb(mp_obj_is_true(enabled))) {
+STATIC mp_obj_t storage_enable_usb_drive(void) {
+    if (!common_hal_storage_enable_usb_drive()) {
         mp_raise_RuntimeError(translate("Cannot change usb devices now"));
     }
     return mp_const_none;
 }
-MP_DEFINE_CONST_FUN_OBJ_1(storage_configure_usb_obj, storage_configure_usb);
+MP_DEFINE_CONST_FUN_OBJ_0(storage_enable_usb_drive_obj, storage_enable_usb_drive);
 
 STATIC const mp_rom_map_elem_t storage_module_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_storage) },
 
-    { MP_ROM_QSTR(MP_QSTR_mount),            MP_ROM_PTR(&storage_mount_obj) },
-    { MP_ROM_QSTR(MP_QSTR_umount),           MP_ROM_PTR(&storage_umount_obj) },
-    { MP_ROM_QSTR(MP_QSTR_remount),          MP_ROM_PTR(&storage_remount_obj) },
-    { MP_ROM_QSTR(MP_QSTR_getmount),         MP_ROM_PTR(&storage_getmount_obj) },
-    { MP_ROM_QSTR(MP_QSTR_erase_filesystem), MP_ROM_PTR(&storage_erase_filesystem_obj) },
-    { MP_ROM_QSTR(MP_QSTR_configure_usb),    MP_ROM_PTR(&storage_configure_usb_obj) },
+    { MP_ROM_QSTR(MP_QSTR_mount),             MP_ROM_PTR(&storage_mount_obj) },
+    { MP_ROM_QSTR(MP_QSTR_umount),            MP_ROM_PTR(&storage_umount_obj) },
+    { MP_ROM_QSTR(MP_QSTR_remount),           MP_ROM_PTR(&storage_remount_obj) },
+    { MP_ROM_QSTR(MP_QSTR_getmount),          MP_ROM_PTR(&storage_getmount_obj) },
+    { MP_ROM_QSTR(MP_QSTR_erase_filesystem),  MP_ROM_PTR(&storage_erase_filesystem_obj) },
+    { MP_ROM_QSTR(MP_QSTR_disable_usb_drive), MP_ROM_PTR(&storage_disable_usb_drive_obj) },
+    { MP_ROM_QSTR(MP_QSTR_enable_usb_drive),  MP_ROM_PTR(&storage_enable_usb_drive_obj) },
 
 //| class VfsFat:
 //|     def __init__(self, block_device: str) -> None:

shared-bindings/storage/__init__.h

@@ -38,6 +38,8 @@ void common_hal_storage_umount_object(mp_obj_t vfs_obj);
 void common_hal_storage_remount(const char *path, bool readonly, bool disable_concurrent_write_protection);
 mp_obj_t common_hal_storage_getmount(const char *path);
 void common_hal_storage_erase_filesystem(void);
-bool common_hal_storage_configure_usb(bool enabled);
+
+bool common_hal_storage_disable_usb_drive(void);
+bool common_hal_storage_enable_usb_drive(void);
 
 #endif  // MICROPY_INCLUDED_SHARED_BINDINGS_STORAGE___INIT___H

shared-bindings/usb_cdc/__init__.c

@@ -39,60 +39,77 @@
 //| The `usb_cdc` module allows access to USB CDC (serial) communications.
 //|
 //| On Windows, each `Serial` is visible as a separate COM port. The ports will often
-//| be assigned consecutively, REPL first, but this is not always true.
+//| be assigned consecutively, `console` first, but this is not always true.
 //|
-//| On Linux, the ports are typically ``/dev/ttyACM0`` and ``/dev/ttyACM1``. The REPL
-//| is usually first.
+//| On Linux, the ports are typically ``/dev/ttyACM0`` and ``/dev/ttyACM1``.
+//| The `console` port will usually be first.
 //|
 //| On MacOS, the ports are typically ``/dev/cu.usbmodem<something>``. The something
-//| varies based on the USB bus and port used. The REPL is usually first.
+//| varies based on the USB bus and port used. The `console` port will usually be first.
 //| """
 //|
-//| repl: Optional[Serial]
-//| """The `Serial` object that can be used to communicate over the REPL serial
-//| channel. ``None`` if disabled.
+//| console: Optional[Serial]
+//| """The `console` `Serial` object is used for the REPL, and for `sys.stdin` and `sys.stdout`.
+//|    `console` is ``None`` if disabled.
 //|
-//| Note that`sys.stdin` and `sys.stdout` are also connected to the REPL, though
-//| they are text-based streams, and the `repl` object is a binary stream."""
+//| However, note that`sys.stdin` and `sys.stdout` are text-based streams,
+//| and the `console` object is a binary stream.
+//| You do not normally need to write to `console` unless you wnat to write binary data.
+//| """
 //|
 //| data: Optional[Serial]
 //| """A `Serial` object that can be used to send and receive binary data to and from
 //| the host.
-//| Note that `data` is *disabled* by default."""
+//| Note that `data` is *disabled* by default. ``data`` is ``None`` if disabled."""
+
+//| def disable() -> None:
+//|     """Do not present any USB CDC device to the host.
+//|     Can be called in ``boot.py``, before USB is connected.
+//|     Equivalent to ``usb_cdc.enable(console=False, data=False)``."""
+//|     ...
+//|
+STATIC mp_obj_t usb_cdc_disable(void) {
+    if (!common_hal_usb_cdc_disable()) {
+        mp_raise_RuntimeError(translate("Cannot change USB devices now"));
+    }
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_0(usb_cdc_disable_obj, usb_cdc_disable);
 
-//| def configure_usb(*, repl_enabled: bool = True, data_enabled: bool = False) -> None:
-//|     """Configure the USB CDC devices. Can be called in ``boot.py``, before USB is connected.
+//| def enable(*, console: bool = True, data: bool = False) -> None:
+//|     """Enable or disable each CDC device. Can be called in ``boot.py``, before USB is connected.
 //|
-//|     :param repl_enabled bool: Enable or disable the `repl` USB serial device.
+//|     :param console bool: Enable or disable the `console` USB serial device.
 //|       True to enable; False to disable. Enabled by default.
-//|     :param data_enabled bool: Enable or disable the `data` USB serial device.
+//|     :param data bool: Enable or disable the `data` USB serial device.
 //|       True to enable; False to disable. *Disabled* by default."""
 //|     ...
 //|
-STATIC mp_obj_t usb_cdc_configure_usb(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
-    enum { ARG_repl_enabled, ARG_data_enabled };
+STATIC mp_obj_t usb_cdc_enable(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
+    enum { ARG_console, ARG_data };
     static const mp_arg_t allowed_args[] = {
-        { MP_QSTR_repl_enabled, MP_ARG_KW_ONLY | MP_ARG_BOOL, {.u_bool = true } },
-        { MP_QSTR_data_enabled, MP_ARG_KW_ONLY | MP_ARG_BOOL, {.u_bool = false } },
+        { MP_QSTR_console, MP_ARG_KW_ONLY | MP_ARG_BOOL, {.u_bool = true } },
+        { MP_QSTR_data, MP_ARG_KW_ONLY | MP_ARG_BOOL, {.u_bool = false } },
     };
     mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
     mp_arg_parse_all(n_args, pos_args, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
 
-    if (!common_hal_usb_cdc_configure_usb(args[ARG_repl_enabled].u_bool, args[ARG_data_enabled].u_bool)) {
+    if (!common_hal_usb_cdc_enable(args[ARG_console].u_bool, args[ARG_data].u_bool)) {
         mp_raise_RuntimeError(translate("Cannot change USB devices now"));
     }
     return mp_const_none;
 }
-MP_DEFINE_CONST_FUN_OBJ_KW(usb_cdc_configure_usb_obj, 0, usb_cdc_configure_usb);
+MP_DEFINE_CONST_FUN_OBJ_KW(usb_cdc_enable_obj, 0, usb_cdc_enable);
 
-// The usb_cdc module dict is mutable so that .repl and .data may
+// The usb_cdc module dict is mutable so that .console and .data may
 // be set to a Serial or to None depending on whether they are enabled or not.
 static mp_map_elem_t usb_cdc_module_globals_table[] = {
-    { MP_ROM_QSTR(MP_QSTR___name__),      MP_ROM_QSTR(MP_QSTR_usb_cdc) },
-    { MP_ROM_QSTR(MP_QSTR_Serial),        MP_OBJ_FROM_PTR(&usb_cdc_serial_type) },
-    { MP_ROM_QSTR(MP_QSTR_repl),          mp_const_none },
-    { MP_ROM_QSTR(MP_QSTR_data),          mp_const_none },
-    { MP_ROM_QSTR(MP_QSTR_configure_usb), MP_OBJ_FROM_PTR(&usb_cdc_configure_usb_obj) },
+    { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_usb_cdc) },
+    { MP_ROM_QSTR(MP_QSTR_Serial),   MP_OBJ_FROM_PTR(&usb_cdc_serial_type) },
+    { MP_ROM_QSTR(MP_QSTR_console),  mp_const_none },
+    { MP_ROM_QSTR(MP_QSTR_data),     mp_const_none },
+    { MP_ROM_QSTR(MP_QSTR_disable),  MP_OBJ_FROM_PTR(&usb_cdc_disable_obj) },
+    { MP_ROM_QSTR(MP_QSTR_enable),   MP_OBJ_FROM_PTR(&usb_cdc_enable_obj) },
 };
 
 static MP_DEFINE_MUTABLE_DICT(usb_cdc_module_globals, usb_cdc_module_globals_table);
@@ -109,8 +126,8 @@ static void set_module_dict_entry(mp_obj_t key_qstr, mp_obj_t serial_obj) {
     }
 }
 
-void usb_cdc_set_repl(mp_obj_t serial_obj) {
-    set_module_dict_entry(MP_ROM_QSTR(MP_QSTR_repl), serial_obj);
+void usb_cdc_set_console(mp_obj_t serial_obj) {
+    set_module_dict_entry(MP_ROM_QSTR(MP_QSTR_console), serial_obj);
 }
 
 void usb_cdc_set_data(mp_obj_t serial_obj) {

shared-bindings/usb_cdc/__init__.h

@@ -30,9 +30,10 @@
 #include "shared-module/usb_cdc/__init__.h"
 
 //  Set the module dict entries.
-void usb_cdc_set_repl(mp_obj_t serial_obj);
+void usb_cdc_set_console(mp_obj_t serial_obj);
 void usb_cdc_set_data(mp_obj_t serial_obj);
 
-extern bool common_hal_usb_cdc_configure_usb(bool repl_enabled, bool data_enabled);
+extern bool common_hal_usb_cdc_disable(void);
+extern bool common_hal_usb_cdc_enable(bool console, bool data);
 
 #endif  // MICROPY_INCLUDED_SHARED_BINDINGS_USB_CDC___INIT___H

shared-bindings/usb_hid/Device.c

@@ -40,8 +40,8 @@
 //|
 
 //|     def __init__(self, *, descriptor: ReadableBuffer, usage_page: int, usage: int, in_report_length: int, out_report_length: int = 0, report_id_index: Optional[int]) -> None:
-//|         """Create a description of a USB HID device. To create an actual device,
-//|         pass a `Device` to `usb_hid.configure_usb()`.
+//|         """Create a description of a USB HID device. The actual device is created when you
+//|         pass a `Device` to `usb_hid.enable()`.
 //|
 //|         :param ReadableBuffer report_descriptor: The USB HID Report descriptor bytes. The descriptor is not
 //|           not verified for correctness; it is up to you to make sure it is not malformed.

shared-bindings/usb_hid/__init__.c

@@ -40,8 +40,19 @@
 //| """Tuple of all active HID device interfaces."""
 //|
 
-//| def configure_usb(devices: Optional[Sequence[Device]]) -> None:
-//|     """Configure the USB HID devices that will be available.
+//| def disable() -> None:
+//|     """Do not present any USB HID devices to the host computer.
+//|     Can be called in ``boot.py``, before USB is connected."""
+STATIC mp_obj_t usb_hid_disable(void) {
+    if (!common_hal_usb_hid_disable()) {
+        mp_raise_RuntimeError(translate("Cannot change USB devices now"));
+    }
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_0(usb_hid_disable_obj, usb_hid_disable);
+
+//| def enable(devices: Optional[Sequence[Device]]) -> None:
+//|     """Specify which USB HID devices that will be available.
 //|     Can be called in ``boot.py``, before USB is connected.
 //|
 //|     :param Sequence devices: `Device` objects.
@@ -51,7 +62,7 @@
 //|     """
 //|     ...
 //|
-STATIC mp_obj_t usb_hid_configure_usb(mp_obj_t devices) {
+STATIC mp_obj_t usb_hid_enable(mp_obj_t devices) {
     const mp_int_t len = mp_obj_get_int(mp_obj_len(devices));
     for (mp_int_t i = 0; i < len; i++) {
         mp_obj_t item = mp_obj_subscr(devices, MP_OBJ_NEW_SMALL_INT(i), MP_OBJ_SENTINEL);
@@ -60,20 +71,21 @@ STATIC mp_obj_t usb_hid_configure_usb(mp_obj_t devices) {
         }
     }
 
-    if (!common_hal_usb_hid_configure_usb(devices)) {
+    if (!common_hal_usb_hid_enable(devices)) {
         mp_raise_RuntimeError(translate("Cannot change USB devices now"));
     }
 
     return mp_const_none;
 }
-MP_DEFINE_CONST_FUN_OBJ_1(usb_hid_configure_usb_obj, usb_hid_configure_usb);
+MP_DEFINE_CONST_FUN_OBJ_1(usb_hid_enable_obj, usb_hid_enable);
 
 // usb_hid.devices is set once the usb devices are determined, after boot.py runs.
 STATIC mp_map_elem_t usb_hid_module_globals_table[] = {
-    { MP_ROM_QSTR(MP_QSTR___name__),      MP_OBJ_NEW_QSTR(MP_QSTR_usb_hid) },
-    { MP_ROM_QSTR(MP_QSTR_configure_usb), MP_OBJ_FROM_PTR(&usb_hid_configure_usb_obj) },
-    { MP_ROM_QSTR(MP_QSTR_devices),       mp_const_none },
-    { MP_ROM_QSTR(MP_QSTR_Device),        MP_OBJ_FROM_PTR(&usb_hid_device_type) },
+    { MP_ROM_QSTR(MP_QSTR___name__), MP_OBJ_NEW_QSTR(MP_QSTR_usb_hid) },
+    { MP_ROM_QSTR(MP_QSTR_Device),   MP_OBJ_FROM_PTR(&usb_hid_device_type) },
+    { MP_ROM_QSTR(MP_QSTR_devices),  mp_const_none },
+    { MP_ROM_QSTR(MP_QSTR_disable),  MP_OBJ_FROM_PTR(&usb_hid_disable_obj) },
+    { MP_ROM_QSTR(MP_QSTR_enable),   MP_OBJ_FROM_PTR(&usb_hid_enable_obj) },
 };
 
 STATIC MP_DEFINE_MUTABLE_DICT(usb_hid_module_globals, usb_hid_module_globals_table);

shared-bindings/usb_hid/__init__.h

@@ -35,6 +35,7 @@ extern mp_obj_tuple_t common_hal_usb_hid_devices;
 
 void usb_hid_set_devices(mp_obj_t devices);
 
-bool common_hal_usb_hid_configure_usb(const mp_obj_t devices_seq);
+bool common_hal_usb_hid_disable(void);
+bool common_hal_usb_hid_enable(const mp_obj_t devices_seq);
 
 #endif // SHARED_BINDINGS_USB_HID_H