Prevent ble delay on deep sleep wake; add CIRCUITPY_BLE_WORKFLOW; doc editing

docs/environment.rst

@@ -73,57 +73,64 @@ You can also include any other key/value pairs in the file for use with your own
 Keys that affect CircuitPython behavior
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-CIRCUITPY_BLE_NAME
-~~~~~~~~~~~~~~~~~~
+CIRCUITPY_BLE_NAME (string)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 If supplied, sets the BLE name the board advertises as, including for the BLE workflow.
 Otherwise, defaults to ``CIRCUITPYxxxx``, where ``xxxx`` varies per board.
 
-CIRCUITPY_HEAP_START_SIZE
-~~~~~~~~~~~~~~~~~~~~~~~~~
+CIRCUITPY_BLE_WORKFLOW (boolean)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If ``false``, disable the BLE workflow. Defaults to ``true``. If ``false``,
+changing ``supervisor.runtime.ble_workflow`` has no effect.
+
+
+CIRCUITPY_HEAP_START_SIZE (integer)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Sets the initial size of the python heap, allocated from the outer heap. Must be a multiple of 4.
 The default is currently 8192.
 The python heap will grow by doubling and redoubling this initial size until it cannot fit in the outer heap.
 Larger values will reserve more RAM for python use and prevent the supervisor and SDK
 from large allocations of their own.
 Smaller values will likely grow sooner than large start sizes.
 
-CIRCUITPY_PYSTACK_SIZE
-~~~~~~~~~~~~~~~~~~~~~~
+CIRCUITPY_PYSTACK_SIZE (integer)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Sets the size of the python stack. Must be a multiple of 4. The default value is currently 1536.
 Increasing the stack reduces the size of the heap available to python code.
 Used to avoid "Pystack exhausted" errors when the code can't be reworked to avoid it.
 
-CIRCUITPY_WEB_API_PASSWORD
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+CIRCUITPY_WEB_API_PASSWORD (string)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Password required to make modifications to the board from the Web Workflow.
 If the password is not specified, the Web Workflow is not enabled.
 
-CIRCUITPY_WEB_API_PORT
-~~~~~~~~~~~~~~~~~~~~~~
+CIRCUITPY_WEB_API_PORT (integer)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 TCP port number used for the Web Workflow HTTP API. Defaults to 80 when omitted.
 
-CIRCUITPY_WEB_INSTANCE_NAME
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+CIRCUITPY_WEB_INSTANCE_NAME (string)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Human-friendly name the board advertises over mDNS for the Web Workflow.
 Defaults to the human-readable board name if omitted.
 This is not the hostname.
 
-CIRCUITPY_WIFI_SSID
-~~~~~~~~~~~~~~~~~~~
-CIRCUITPY_WIFI_PASSWORD
-~~~~~~~~~~~~~~~~~~~~~~~
+CIRCUITPY_WIFI_SSID (string)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+CIRCUITPY_WIFI_PASSWORD (string)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 If these values are supplied, connects automatically to a local WiFi network
 with the specified SSID and password before ``boot.py`` and/or ``code.py`` are run.
 
-CIRCUITPY_WIFI_HOSTNAME
-~~~~~~~~~~~~~~~~~~~~~~~
+CIRCUITPY_WIFI_HOSTNAME (string)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 If supplied, sets the initial ``wifi.radio.hostname`` to the given value.
 Otherwise, the default value is ``cpy-<board_name>-<mac_address>``,
 with some shortening for length if necessary.
 If the supplied value is an invalid hostname or is too long, it is ignored.
 
-CIRCUITPY_SDCARD_USB
-^^^^^^^^^^^^^^^^^^^^
+CIRCUITPY_SDCARD_USB (boolean)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Present a mounted SD card as a USB MSC device. If the board has default pins for an SD card socket,
 the card is mounted automatically on startup.
 Only one card can be presented.
@@ -135,8 +142,10 @@ so set this to ``false`` if you don't need this feature.
 Additional board-specific keys
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-CIRCUITPY_DISPLAY_WIDTH (Sunton, MaTouch)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+CIRCUITPY_DISPLAY_WIDTH (integer)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+(Sunton, MaTouch boards)
+
 Selects the correct screen resolution (1024x600 or 800x640) for the particular board variant.
 If the CIRCUITPY_DISPLAY_WIDTH parameter is set to a value of 1024 the display is initialized
 during power up at 1024x600 otherwise the display will be initialized at a resolution
@@ -146,8 +155,8 @@ of 800x480.
 `Sunton ESP32-2432S028 <https://circuitpython.org/board/sunton_esp32_2432S028/>`_
 `Sunton ESP32-2432S024C <https://circuitpython.org/board/sunton_esp32_2432S024C/>`_
 
-CIRCUITPY_DISPLAY_ROTATION
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+CIRCUITPY_DISPLAY_ROTATION (integer)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Selects the correct screen rotation (0, 90, 180 or 270) for the particular board variant.
 If the CIRCUITPY_DISPLAY_ROTATION parameter is set the display will be initialized
 during power up with the selected rotation, otherwise the display will be initialized with
@@ -158,8 +167,8 @@ a rotation of 0. Attempting to initialize the screen with a rotation other than
 `Adafruit Feather RP2350 <https://circuitpython.org/board/adafruit_feather_rp2350/>`_
 `Adafruit Metro RP2350 <https://circuitpython.org/board/adafruit_metro_rp2350/>`_
 
-CIRCUITPY_DISPLAY_FREQUENCY
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+CIRCUITPY_DISPLAY_FREQUENCY (integer)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Allows the entry of a display frequency used during the "dotclock" framebuffer construction.
 If a valid frequency is not defined the board will initialize the framebuffer with a
 frequency of 12500000hz (12.5Mhz). The value should be entered as an integer in hertz
@@ -169,8 +178,8 @@ display frequency.
 `Sunton ESP32-8048S050 <https://circuitpython.org/board/sunton_esp32_8048S050/>`_
 
 
-CIRCUITPY_PICODVI_ENABLE
-~~~~~~~~~~~~~~~~~~~~~~~~
+CIRCUITPY_PICODVI_ENABLE (string)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Whether to configure the display at board initialization time, one of the following:
 
 .. code-block::
@@ -186,8 +195,16 @@ until it is released by ``displayio.release_displays()``. It does not appear at
 `Adafruit Feather RP2350 <https://circuitpython.org/board/adafruit_feather_rp2350/>`_
 `Adafruit Metro RP2350 <https://circuitpython.org/board/adafruit_metro_rp2350/>`_
 
-CIRCUITPY_DISPLAY_WIDTH, CIRCUITPY_DISPLAY_HEIGHT, and CIRCUITPY_DISPLAY_COLOR_DEPTH (RP2350 boards with DVI or HSTX connector)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+CIRCUITPY_DISPLAY_WIDTH (integer)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+CIRCUITPY_DISPLAY_HEIGHT (integer)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+CIRCUITPY_DISPLAY_COLOR_DEPTH (integer)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+(RP2350 boards with DVI or HSTX connector)
+
 Selects the desired resolution and color depth.
 
 Supported resolutions are:
@@ -213,15 +230,15 @@ Example: Configure the display to 640x480 black and white (1 bit per pixel):
 `Adafruit Feather RP2350 <https://circuitpython.org/board/adafruit_feather_rp2350/>`_
 `Adafruit Metro RP2350 <https://circuitpython.org/board/adafruit_metro_rp2350/>`_
 
-CIRCUITPY_SAFEMODE_DELAY
-~~~~~~~~~~~~~~~~~~~~~~~~
-Wait for the specified amount of time, in seconds (as a float), for the user to press the reset button
+CIRCUITPY_SAFEMODE_DELAY (float)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Wait for the specified amount of time, in seconds, for the user to press the reset button
 to initiate safe mode after a hard reset.
 The status LED blinks during this time.
 If not specified, use the default delay, which is one second.
 
-CIRCUITPY_TERMINAL_SCALE
-~~~~~~~~~~~~~~~~~~~~~~~~
+CIRCUITPY_TERMINAL_SCALE (integer)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Allows the entry of a display scaling factor used during the terminalio console construction.
 The entered scaling factor only affects the terminalio console and has no impact on
 the UART, Web Workflow, BLE Workflow, etc consoles.
@@ -230,8 +247,8 @@ This feature is not enabled on boards that the CIRCUITPY_SETTINGS_TOML (or CIRCU
 flag has been set to 0. Currently this is primarily boards with limited flash including some
 of the Atmel_samd boards based on the SAMD21/M0 microprocessor.
 
-CIRCUITPY_TERMINAL_FONT
-~~~~~~~~~~~~~~~~~~~~~~~
+CIRCUITPY_TERMINAL_FONT (string)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Specifies a custom font file path to use for the terminalio console instead of the default
 ``/fonts/terminal.lvfontbin``. This allows users to create and use custom fonts for the
 CircuitPython console.

docs/workflows.md

@@ -4,11 +4,11 @@ Workflows are the process used to 1) manipulate files on the CircuitPython devic
 with the serial connection to CircuitPython. The serial connection is usually used to access the
 REPL.
 
-Starting with CircuitPython 3.x we moved to a USB-only workflow. Prior to that, we used the serial
-connection alone to do the whole workflow. In CircuitPython 7.x, a BLE workflow was added with the
-advantage of working with mobile devices. CircuitPython 8.x added a web workflow that works over the
-local network (usually Wi-Fi) and a web browser. Other clients can also use the Web REST API. Boards
-should clearly document which workflows are supported.
+CircuitPython started with a USB mass storage device workflow for filesystem operations.
+CircuitPython 7.x added a BLE workflow with the advantage of working with mobile devices.
+CircuitPython 8.x added a web workflow that works over the
+local network (usually Wi-Fi) and a web browser.
+Other clients can also use the Web REST API. Boards should clearly document which workflows are supported.
 
 Code for workflows lives in `supervisor/shared`.
 
@@ -21,63 +21,76 @@ device has been plugged into a host.
 
 ### Mass Storage
 CircuitPython exposes a standard mass storage (MSC) interface to enable file manipulation over a
-standard interface. (This is how USB drives work.) This interface works underneath the file system at
+standard interface. The board appears as a USB drive. This interface works underneath the file system at
 the block level so using it excludes other types of workflows from manipulating the file system at
 the same time.
 
 CircuitPython 10.x adds multiple Logical Units (LUNs) to the mass storage interface. This allows for
 multiple drives to be accessed and ejected independently.
 
 #### CIRCUITPY drive
-The CIRCUITPY drive is the main drive that CircuitPython uses. It is writable by the host by default
+The CIRCUITPY drive is the main drive that CircuitPython presents. It is writable by the host by default
 and read-only to CircuitPython. `storage.remount()` can be used to remount the drive to
 CircuitPython as read-write.
 
 #### CPSAVES drive
-The board may also expose a CPSAVES drive. (This is based on the ``CIRCUITPY_SAVES_PARTITION_SIZE``
-setting in ``mpconfigboard.h``.) It is a portion of the main flash that is writable by CircuitPython
-by default. It is read-only to the host. `storage.remount()` can be used to remount the drive to the
-host as read-write.
+The board may also expose a CPSAVES drive. (This is based on the `CIRCUITPY_SAVES_PARTITION_SIZE`
+setting in `mpconfigboard.h`.) It is a portion of the main flash that is writable by CircuitPython
+by default.  The CPSAVES drive becomes visible to the attached host computer after a few seconds.
+By default it is read-only to the host, but `storage.remount()` can be used to remount the drive
+as read-write to the host
 
 #### SD card drive
-A few boards have SD card automounting. (This is based on the ``DEFAULT_SD`` settings in
-``mpconfigboard.h``.) The card is writable from CircuitPython by default and read-only to the host.
+A few boards auomatically mount an SD card, if present, to the `/sd` mount point.
+Boards that do this have `DEFAULT_SD` settings in`mpconfigboard.h` which allow detecting the
+presence of an SD card, and fixed pin settings for the SD card socket.
+The mounted SD card is writable from CircuitPython by default and read-only to the host.
 `storage.remount()` can be used to remount the drive to the host as read-write.
 
-On most other boards, except for ``atmel-samd`` boards, an SD card mounted in user code
-at ``/sd`` will become visible after a few seconds on the attached host computer, as an
-additional drive besides CIRCUITPY and (if present) CPSAVES. It will present with the volume
-label on the SD card. Depending on the host operating system settings, the drive may or may not be
-auto-mounted on the host. Host writes to drives mounted by user code will not trigger a reload.
+If `CIRCUITPY_SDCARD_USB` in settings.toml is `true` (the default),
+an SD card mounted in user code at `/sd` will become visible on the attached host computer
+after a few seconds, as an additional drive besides CIRCUITPY and (if present) CPSAVES.
+It will present with the volume label on the SD card.
+Depending on the host operating system settings, the drive may or may not be
+auto-mounted on the host.
+Host writes to drives mounted by user code will not trigger a reload.
 
 ### CDC serial
-CircuitPython exposes one CDC USB interface for CircuitPython serial. This is a standard serial
-USB interface.
+CircuitPython exposes a standard serial CDC USB interface for the CircuitPython REPL.
+Setting the CDC's baudrate 1200 and disconnecting will reboot the board into a bootloader.
+This technique was first used by Arduino boards and the Arduino IDE to trigger a reset into bootloader.
 
-TODO: Document how it designates itself from the user CDC.
+A second CDC interface is optionally available for binary data transfer (see `usb_cdc`).
 
-Setting baudrate 1200 and disconnecting will reboot into a bootloader. (Used by Arduino to trigger
-a reset into bootloader.)
 
 ## BLE
 
-The BLE workflow is enabled for Nordic boards. By default, to prevent malicious access, it is disabled.
-To connect to the BLE workflow, press the reset button while the status led blinks blue quickly
-after the safe mode blinks. The board will restart and broadcast the file transfer service UUID
-(`0xfebb`) along with the board's [Creation IDs](https://github.com/creationid/creators). This
-public broadcast is done at a lower transmit level so the devices must be closer. On connection, the
-device will need to pair and bond. Once bonded, the device will broadcast whenever disconnected
-using a rotating key rather than a static one. Non-bonded devices won't be able to resolve it. After
-connection, the central device can discover two default services. One for file transfer and one for
-CircuitPython specifically that includes serial characteristics.
+The BLE workflow provides file transfer and REPL access over BLE.
+It can be controlled by setting `CIRCUITPY_BLE_WORKFLOW` to be `true` or `false`.
+in `settings.toml`. The default is `true`.
+
+To prevent malicious access, even if `CIRCUITPY_BLE_WORKFLOW=true`,
+the user must initiate a bonded connection with the host.
+To bond, press the reset button when the status led blinks blue quickly after reset,
+after the safe mode blinks.
+The board will restart and advertise the file transfer service UUID (`0xfebb`)
+along with the board's [Creation ID](https://github.com/creationid/creators).
+This public advertisement is done at a lower transmit level so the devices must be closer.
+On connection, the device will need to pair and bond.
+Once bonded, the device will advertise whenever disconnected,
+using a rotating key rather than a static one.
+Non-bonded devices won't be able to resolve it.
+
+After connection, will discover two default services: one is for file transfer and
+the other provides version information and a serial connection to the CircuitPython REPL.
 
 To change the default BLE advertising name without (or before) running user code, the desired name
-can be put in the `settings.toml` file. The key is `CIRCUITPY_BLE_NAME`. It's limited to approximately
-30 characters depending on the port's settings and will be truncated if longer.
+can be put in the `settings.toml` using the `CIRCUITPY_BLE_NAME` key. The name is limited to approximately
+30 characters, depending on the port, and will be truncated if longer.
 
 ### File Transfer API
 
-CircuitPython uses [an open File Transfer API](https://github.com/adafruit/Adafruit_CircuitPython_BLE_File_Transfer)
+The file transfer service provides [an open File Transfer API](https://github.com/adafruit/Adafruit_CircuitPython_BLE_File_Transfer)
 to enable file system access.
 
 ### CircuitPython Service
@@ -87,22 +100,22 @@ replaced by the four specific digits below. The service itself is `0001`.
 
 #### TX - `0002` / RX - `0003`
 
-These characteristic work just like the Nordic Uart Service (NUS) but have different UUIDs to prevent
-conflicts with user created NUS services.
+The TX and RX characteristics for the CircuitPython service work just like the Nordic Uart Service (NUS)
+but have different UUIDs to prevent conflicts with user-created NUS services.
 
 #### Version - `0100`
-Read-only characteristic that returns the UTF-8 encoded version string.
+The Version characteristic is read-only and returns the UTF-8 encoded version string.
 
 ## Web
 If the keys `CIRCUITPY_WIFI_SSID` and `CIRCUITPY_WIFI_PASSWORD` are set in `settings.toml`,
 CircuitPython will automatically connect to the given Wi-Fi network on boot and upon reload.
 
-If `CIRCUITPY_WEB_API_PASSWORD` is set, MDNS and the http server for the web workflow will also start.
+If `CIRCUITPY_WEB_API_PASSWORD` is set, MDNS and the HTTP server for the web workflow will also start.
 
-The webserver is on port 80 unless overridden by `CIRCUITPY_WEB_API_PORT`. It also enables MDNS.
+The webserver is on port 80 unless overridden by `CIRCUITPY_WEB_API_PORT`. It also enables mDNS.
 The name of the board as advertised to the network can be overridden by `CIRCUITPY_WEB_INSTANCE_NAME`.
 
-Here is an example `/settings.toml`:
+Here is an example `settings.toml`:
 
 ```bash
 # To auto-connect to Wi-Fi
@@ -249,7 +262,7 @@ curl -v -u :passw0rd -X PUT -L --location-trusted http://circuitpython.local/fs/
 ```
 
 ##### Move
-Moves the directory at the given path to ``X-Destination``. Also known as rename.
+Moves the directory at the given path to `X-Destination`. Also known as rename.
 
 The custom `X-Destination` header stores the destination path of the directory.
 
@@ -335,7 +348,7 @@ curl -v -u :passw0rd -L --location-trusted http://circuitpython.local/fs/lib/hel
 
 
 ##### Move
-Moves the file at the given path to the ``X-Destination``. Also known as rename.
+Moves the file at the given path to the `X-Destination`. Also known as rename.
 
 The custom `X-Destination` header stores the destination path of the file.
 

main.c

@@ -657,7 +657,7 @@ static bool __attribute__((noinline)) run_code_py(safe_mode_t safe_mode, bool *s
         #if CIRCUITPY_ALARM
         if (_exec_result.return_code & PYEXEC_DEEP_SLEEP) {
             const bool awoke_from_true_deep_sleep =
-                common_hal_mcu_processor_get_reset_reason() == RESET_REASON_DEEP_SLEEP_ALARM;
+                common_hal_mcu_processor_get_reset_reason() == MCU_RESET_REASON_DEEP_SLEEP_ALARM;
 
             if (fake_sleeping) {
                 // This waits until a pretend deep sleep alarm occurs. They are set

ports/analog/common-hal/microcontroller/Processor.c

@@ -42,5 +42,5 @@ mcu_reset_reason_t common_hal_mcu_processor_get_reset_reason(void) {
     #if CIRCUITPY_ALARM
     // TODO: (low prior.) add reset reason in alarm / deepsleep cases (should require alarm peripheral API in "peripherals")
     #endif
-    return RESET_REASON_UNKNOWN;
+    return MCU_RESET_REASON_UNKNOWN;
 }

ports/atmel-samd/common-hal/microcontroller/Processor.c

@@ -328,5 +328,5 @@ void common_hal_mcu_processor_get_uid(uint8_t raw_id[]) {
 }
 
 mcu_reset_reason_t common_hal_mcu_processor_get_reset_reason(void) {
-    return RESET_REASON_UNKNOWN;
+    return MCU_RESET_REASON_UNKNOWN;
 }

ports/broadcom/common-hal/microcontroller/Processor.c

@@ -31,5 +31,5 @@ void common_hal_mcu_processor_get_uid(uint8_t raw_id[]) {
 }
 
 mcu_reset_reason_t common_hal_mcu_processor_get_reset_reason(void) {
-    return RESET_REASON_UNKNOWN;
+    return MCU_RESET_REASON_UNKNOWN;
 }

ports/cxd56/common-hal/microcontroller/Processor.c

@@ -30,5 +30,5 @@ void common_hal_mcu_processor_get_uid(uint8_t raw_id[]) {
 }
 
 mcu_reset_reason_t common_hal_mcu_processor_get_reset_reason(void) {
-    return RESET_REASON_UNKNOWN;
+    return MCU_RESET_REASON_UNKNOWN;
 }