Merge remote-tracking branch 'adafruit/main' into from_bytes-check-parameters

Author: dhalbert

.github/workflows/build.yml

@@ -287,12 +287,13 @@ jobs:
         fetch-depth: 1
     - name: Get CP deps
       run: python tools/ci_fetch_deps.py ${{ matrix.board }} ${{ github.sha }}
+    - uses: carlosperate/arm-none-eabi-gcc-action@v1
+      with:
+        release: '10-2020-q4'
     - name: Install dependencies
       run: |
         sudo apt-get install -y gettext
         pip install -r requirements-ci.txt -r requirements-dev.txt
-        wget --no-verbose https://adafruit-circuit-python.s3.amazonaws.com/gcc-arm-none-eabi-10-2020-q4-major-x86_64-linux.tar.bz2
-        sudo tar -C /usr --strip-components=1 -xaf gcc-arm-none-eabi-10-2020-q4-major-x86_64-linux.tar.bz2
     - name: Versions
       run: |
         gcc --version
@@ -487,8 +488,9 @@ jobs:
         pip install -r requirements-ci.txt -r requirements-dev.txt
         wget --no-verbose https://adafruit-circuit-python.s3.amazonaws.com/gcc-arm-10.3-2021.07-x86_64-aarch64-none-elf.tar.xz
         sudo tar -C /usr --strip-components=1 -xaf gcc-arm-10.3-2021.07-x86_64-aarch64-none-elf.tar.xz
-        wget --no-verbose https://adafruit-circuit-python.s3.amazonaws.com/gcc-arm-none-eabi-10-2020-q4-major-x86_64-linux.tar.bz2
-        sudo tar -C /usr --strip-components=1 -xaf gcc-arm-none-eabi-10-2020-q4-major-x86_64-linux.tar.bz2
+    - uses: carlosperate/arm-none-eabi-gcc-action@v1
+      with:
+        release: '10-2020-q4'
     - name: Install mkfs.fat
       run: |
         wget https://github.com/dosfstools/dosfstools/releases/download/v4.2/dosfstools-4.2.tar.gz

BUILDING.md

@@ -70,7 +70,7 @@ The test suite in the top level `tests` directory.  It needs the unix port to ru
 Then you can run the test suite:
 
     cd ../../tests
-    ./run-tests
+    ./run-tests.py
 
 A successful run will say something like
 

README.rst

@@ -90,9 +90,11 @@ If you'd like to use the term "CircuitPython" and Blinka for your product here i
 * Your product is listed on `circuitpython.org <https://circuitpython.org>`__ (source
   `here <https://github.com/adafruit/circuitpython-org/>`_). This is to ensure that a user of your
   product can always download the latest version of CircuitPython from the standard place.
-* Your product has a user accessible USB plug which appears as a CIRCUITPY drive when plugged in
-  AND/OR provides file and serial access over Bluetooth Low Energy. Boards that do not support USB
-  should be clearly marked as BLE-only CircuitPython.
+* Your product supports at least one standard "`Workflow <https://docs.circuitpython.org/en/latest/docs/workflows.html>`__" for serial and file access:
+  * With a user accessible USB plug which appears as a CIRCUITPY drive when plugged in.
+  * With file and serial access over Bluetooth Low Energy using the BLE Workflow.
+  * With file access over WiFi using the WiFi Workflow with serial access over USB and/or WebSocket.
+* Boards that do not support the USB Workflow should be clearly marked.
 
 If you choose not to meet these requirements, then we ask you call your version of CircuitPython
 something else (for example, SuperDuperPython) and not use the Blinka logo. You can say it is

devices/ble_hci/common-hal/_bleio/Adapter.c

@@ -49,6 +49,10 @@
 #include "shared-bindings/_bleio/ScanEntry.h"
 #include "shared-bindings/time/__init__.h"
 
+#if CIRCUITPY_DOTENV
+#include "shared-module/dotenv/__init__.h"
+#endif
+
 #define MSEC_TO_UNITS(TIME, RESOLUTION) (((TIME) * 1000) / (RESOLUTION))
 #define SEC_TO_UNITS(TIME, RESOLUTION) (((TIME) * 1000000) / (RESOLUTION))
 #define UNITS_TO_SEC(TIME, RESOLUTION) (((TIME)*(RESOLUTION)) / 1000000)
@@ -278,17 +282,27 @@ char default_ble_name[] = { 'C', 'I', 'R', 'C', 'U', 'I', 'T', 'P', 'Y', 0, 0, 0
 // Get various values and limits set by the adapter.
 // Set event mask.
 STATIC void bleio_adapter_hci_init(bleio_adapter_obj_t *self) {
+    mp_int_t name_len = 0;
 
-    const size_t len = sizeof(default_ble_name);
-
-    bt_addr_t addr;
-    hci_check_error(hci_read_bd_addr(&addr));
-
-    default_ble_name[len - 4] = nibble_to_hex_lower[addr.val[1] >> 4 & 0xf];
-    default_ble_name[len - 3] = nibble_to_hex_lower[addr.val[1] & 0xf];
-    default_ble_name[len - 2] = nibble_to_hex_lower[addr.val[0] >> 4 & 0xf];
-    default_ble_name[len - 1] = nibble_to_hex_lower[addr.val[0] & 0xf];
-    self->name = mp_obj_new_str(default_ble_name, len);
+    #if CIRCUITPY_DOTENV
+    char ble_name[32];
+    name_len = dotenv_get_key("/.env", "CIRCUITPY_BLE_NAME", ble_name, sizeof(ble_name) - 1);
+    if (name_len > 0) {
+        self->name = mp_obj_new_str(ble_name, (size_t)name_len);
+    }
+    #endif
+
+    if (name_len <= 0) {
+        name_len = sizeof(default_ble_name);
+        bt_addr_t addr;
+        hci_check_error(hci_read_bd_addr(&addr));
+
+        default_ble_name[name_len - 4] = nibble_to_hex_lower[addr.val[1] >> 4 & 0xf];
+        default_ble_name[name_len - 3] = nibble_to_hex_lower[addr.val[1] & 0xf];
+        default_ble_name[name_len - 2] = nibble_to_hex_lower[addr.val[0] >> 4 & 0xf];
+        default_ble_name[name_len - 1] = nibble_to_hex_lower[addr.val[0] & 0xf];
+        self->name = mp_obj_new_str(default_ble_name, (uint8_t)name_len);
+    }
 
     // Get version information.
     if (hci_read_local_version(&self->hci_version, &self->hci_revision, &self->lmp_version,

docs/environment.rst

@@ -31,9 +31,17 @@ CircuitPython behavior
 CircuitPython will also read the environment to configure its behavior. Other
 keys are ignored by CircuitPython. Here are the keys it uses:
 
+CIRCUITPY_BLE_NAME
+~~~~~~~~~~~~~~~~~~
+Default BLE name the board advertises as, including for the BLE workflow.
+
+CIRCUITPY_WEB_API_PASSWORD
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Password required to make modifications to the board from the Web Workflow.
+
 CIRCUITPY_WIFI_PASSWORD
 ~~~~~~~~~~~~~~~~~~~~~~~
-Wi-Fi password used to auto connect to CIRCUITPY_WIFI_SSID
+Wi-Fi password used to auto connect to CIRCUITPY_WIFI_SSID.
 
 CIRCUITPY_WIFI_SSID
 ~~~~~~~~~~~~~~~~~~~

docs/library/hashlib.rst

@@ -5,6 +5,7 @@
 
 .. module:: hashlib
    :synopsis: hashing algorithms
+   :noindex:
 
 |see_cpython_module| :mod:`cpython:hashlib`.
 

docs/workflows.md

@@ -45,6 +45,10 @@ using a rotating key rather than a static one. Non-bonded devices won't be able
 connection, the central device can discover two default services. One for file transfer and one for
 CircuitPython specifically that includes serial characteristics.
 
+To change the default BLE advertising name without (or before) running user code, the desired name
+can be put in the `/.env` 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.
+
 ### File Transfer API
 
 CircuitPython uses [an open File Transfer API](https://github.com/adafruit/Adafruit_CircuitPython_BLE_File_Transfer)
@@ -286,6 +290,44 @@ not protected by basic auth in case the device is someone elses.
 
 Only `GET` requests are supported and will return `405 Method Not Allowed` otherwise.
 
+#### `/cp/devices.json`
+
+Returns information about other devices found on the network using MDNS.
+
+* `total`: Total MDNS response count. May be more than in `devices` if internal limits were hit.
+* `devices`: List of discovered devices.
+	* `hostname`: MDNS hostname
+	* `instance_name`: MDNS instance name. Defaults to human readable board name.
+	* `port`: Port of CircuitPython Web API
+	* `ip`: IP address
+
+Example:
+```sh
+curl -v -L http://circuitpython.local/cp/devices.json
+```
+
+```json
+{
+	"total": 1,
+	"devices": [
+		{
+			"hostname": "cpy-951032",
+			"instance_name": "Adafruit Feather ESP32-S2 TFT",
+			"port": 80,
+			"ip": "192.168.1.235"
+		}
+	]
+}
+```
+
+#### `/cp/serial/`
+
+
+Serves a basic serial terminal program when a `GET` request is received without the
+`Upgrade: websocket` header. Otherwise the socket is upgraded to a WebSocket. See WebSockets below for more detail.
+
+This is an authenticated endpoint in both modes.
+
 #### `/cp/version.json`
 
 Returns information about the device.
@@ -323,36 +365,6 @@ curl -v -L http://circuitpython.local/cp/version.json
 }
 ```
 
-#### `/cp/devices.json`
-
-Returns information about other devices found on the network using MDNS.
-
-* `total`: Total MDNS response count. May be more than in `devices` if internal limits were hit.
-* `devices`: List of discovered devices.
-	* `hostname`: MDNS hostname
-	* `instance_name`: MDNS instance name. Defaults to human readable board name.
-	* `port`: Port of CircuitPython Web API
-	* `ip`: IP address
-
-Example:
-```sh
-curl -v -L http://circuitpython.local/cp/devices.json
-```
-
-```json
-{
-	"total": 1,
-	"devices": [
-		{
-			"hostname": "cpy-951032",
-			"instance_name": "Adafruit Feather ESP32-S2 TFT",
-			"port": 80,
-			"ip": "192.168.1.235"
-		}
-	]
-}
-```
-
 ### Static files
 
 * `/favicon.ico` - Blinka
@@ -361,4 +373,12 @@ curl -v -L http://circuitpython.local/cp/devices.json
 
 ### WebSocket
 
-Coming soon!
+The CircuitPython serial interactions are available over a WebSocket. A WebSocket begins as a
+special HTTP request that gets upgraded to a WebSocket. Authentication happens before upgrading.
+
+WebSockets are *not* bare sockets once upgraded. Instead they have their own framing format for data.
+CircuitPython can handle PING and CLOSE opcodes. All others are treated as TEXT. Data to
+CircuitPython is expected to be masked UTF-8, as the spec requires. Data from CircuitPython to the
+client is unmasked. It is also unbuffered so the client will get a variety of frame sizes.
+
+Only one WebSocket at a time is supported.