merge from upstream; complicated webusb merge

Author: dhalbert

.github/workflows/build.yml

@@ -208,6 +208,7 @@ jobs:
         - "datum_imu"
         - "datum_light"
         - "datum_weather"
+        - "dynalora_usb"
         - "dynossat_edu_eps"
         - "dynossat_edu_obc"
         - "electronut_labs_blip"

WEBUSB_README.md

@@ -0,0 +1,94 @@
+<!--
+SPDX-FileCopyrightText: 2014 MicroPython & CircuitPython contributors (https://github.com/adafruit/circuitpython/graphs/contributors)
+
+SPDX-License-Identifier: MIT
+-->
+
+# WebUSB Serial Support
+
+To date, this has only been tested on one port (esp32s2), on one board (espressif_kaluga_1).
+
+## What it does
+
+If you have ever used CircuitPython on a platform with a graphical LCD display, you have probably
+already seen multiple "consoles" in use (although the LCD console is "output only").
+
+New compile-time option CIRCUITPY_USB_VENDOR enables an additional "console" that can be used in
+parallel with the original (CDC) serial console.
+
+Web pages that support the WebUSB standard can connect to the "vendor" interface and activate
+this WebUSB serial console at any time.
+
+You can type into either console, and CircuitPython output is sent to all active consoles.
+
+One example of a web page you can use to test drive this feature can be found at:
+
+https://adafruit.github.io/Adafruit_TinyUSB_Arduino/examples/webusb-serial/index.html
+
+## How to enable
+
+Update your platform's mpconfigboard.mk file to enable and disable specific types of USB interfaces.
+
+CIRCUITPY_USB_HID = xxx
+CIRCUITPY_USB_MIDI = xxx
+CIRCUITPY_USB_VENDOR = xxx
+
+On at least some of the hardware platforms, the maximum number of USB endpoints is fixed.
+For example, on the ESP32S2, you must pick only one of the above 3 interfaces to be enabled.
+
+Original espressif_kaluga_1 mpconfigboard.mk settings:
+
+CIRCUITPY_USB_HID = 1
+CIRCUITPY_USB_MIDI = 0
+CIRCUITPY_USB_VENDOR = 0
+
+Settings to enable WebUSB instead:
+
+CIRCUITPY_USB_HID = 0
+CIRCUITPY_USB_MIDI = 0
+CIRCUITPY_USB_VENDOR = 1
+
+Notice that to enable VENDOR on ESP32-S2, we had to give up HID. There may be platforms that can have both, or even all three.
+
+## Implementation Notes
+
+CircuitPython uses the tinyusb library.
+
+The tinyusb library already has support for WebUSB serial.
+The tinyusb examples already include a "WebUSB serial" example.
+
+    Sidenote - The use of the term "vendor" instead of "WebUSB" was done to match tinyusb.
+
+Basically, this feature was ported into CircuitPython by pulling code snippets out of the
+tinyusb example, and putting them where they best belonged in the CircuitPython codebase.
+
+There was one complication:
+
+tinyusb uses C preprocessor macros to define things like USB descriptors.
+
+CircuitPython uses a Python program (tools/gen_usb_descriptor.py) to create USB descriptors (etc.)
+using "helper objects" from another repo (adafruit_usb_descriptor). This means some of the example
+code had to be adapted to the new programing model, and gen_usb_descriptor gained new command-line
+options to control the generated code.
+
+The generated files go into the "build" directory, look for autogen_usb_descriptor.c and
+genhdr/autogen_usb_descriptor.h.
+
+
+Also worth pointing out - the re-use of the CDC connect/disconnect mechanism is not actually part
+of the WebUSB standard, it's more of "common idiom". We make use of it here because we need to know
+when we should be paying attention to the WebUSB serial interface, and when we should ignore it..
+
+## Possible future work areas
+
+The current code uses the existing Python infrastructure to create the Interface descriptor, but
+simply outputs the code snippets from the original tinyusb demo code to create the WEBUSB_URL,
+BOS, and MS_OS_20 descriptors. I suppose additional work could be done to add these to the
+adafruit_usb_descriptor project, and then gen_usb_descriptor.py could be modified to make use
+of them.
+
+Program gen_usb_descriptor.py creates objects for most interface types, regardless of whether or
+not they are actually enabled. This increases the size of a generated string table. I made the
+new vendor-interface-related code not do this (because some of the ARM platforms would no longer
+build), but I did not go back and do this for the other interface types (CDC, MIDI, HID, etc.)
+Some FLASH savings are probably possible if this is done.

docs/index.rst

@@ -46,6 +46,7 @@ Full Table of Contents
    ../BUILDING
    ../CODE_OF_CONDUCT
    ../license.rst
+   ../WEBUSB_README
 
 Indices and tables
 ==================

locale/ID.po

@@ -642,6 +642,10 @@ msgstr ""
 "Tidak dapat melakukan reset ke bootloader karena tidak ada bootloader yang "
 "terisi"
 
+#: ports/esp32s2/common-hal/socketpool/Socket.c
+msgid "Cannot set socket options"
+msgstr ""
+
 #: shared-bindings/digitalio/DigitalInOut.c
 msgid "Cannot set value when direction is input."
 msgstr "Tidak dapat menetapkan nilai saat arah input."
@@ -884,7 +888,7 @@ msgstr "Channel EXTINT sedang digunakan"
 msgid "Error in regex"
 msgstr "Error pada regex"
 
-#: shared-bindings/socketpool/Socket.c
+#: shared-bindings/socketpool/Socket.c shared-bindings/ssl/SSLSocket.c
 msgid "Error: Failure to bind"
 msgstr ""
 
@@ -943,7 +947,7 @@ msgstr "FFT didefinisikan hanya untuk ndarrays"
 msgid "FFT is implemented for linear arrays only"
 msgstr ""
 
-#: ports/esp32s2/common-hal/socketpool/Socket.c
+#: ports/esp32s2/common-hal/ssl/SSLSocket.c
 msgid "Failed SSL handshake"
 msgstr ""
 
@@ -1316,18 +1320,14 @@ msgstr "security_mode tidak valid"
 msgid "Invalid size"
 msgstr ""
 
-#: ports/esp32s2/common-hal/socketpool/Socket.c
+#: ports/esp32s2/common-hal/ssl/SSLContext.c
 msgid "Invalid socket for TLS"
 msgstr ""
 
 #: ports/esp32s2/bindings/espidf/__init__.c ports/esp32s2/esp_error.c
 msgid "Invalid state"
 msgstr ""
 
-#: ports/esp32s2/common-hal/socketpool/Socket.c
-msgid "Invalid use of TLS Socket"
-msgstr ""
-
 #: shared-bindings/audiomixer/Mixer.c
 msgid "Invalid voice"
 msgstr "Suara tidak valid"
@@ -1344,10 +1344,6 @@ msgstr "File wave tidak valid"
 msgid "Invalid word/bit length"
 msgstr "Panjang kata/bit tidak valid"
 
-#: ports/esp32s2/common-hal/socketpool/Socket.c
-msgid "Issue setting SO_REUSEADDR"
-msgstr ""
-
 #: shared-bindings/aesio/aes.c
 msgid "Key must be 16, 24, or 32 bytes long"
 msgstr "Panjang kunci harus 16, 24, atau 32 byte"
@@ -1560,6 +1556,12 @@ msgstr ""
 msgid "No out in program"
 msgstr ""
 
+#: ports/atmel-samd/common-hal/busio/I2C.c ports/esp32s2/common-hal/busio/I2C.c
+#: ports/mimxrt10xx/common-hal/busio/I2C.c ports/nrf/common-hal/busio/I2C.c
+#: ports/raspberrypi/common-hal/busio/I2C.c
+msgid "No pull up found on SDA or SCL; check your wiring"
+msgstr ""
+
 #: shared-module/touchio/TouchIn.c
 msgid "No pulldown on pin; 1Mohm recommended"
 msgstr "Tidak ada pull-down pada pin; 1Mohm direkomendasikan"
@@ -1674,7 +1676,7 @@ msgstr ""
 msgid "Out of memory"
 msgstr ""
 
-#: ports/esp32s2/common-hal/socketpool/Socket.c
+#: ports/esp32s2/common-hal/socketpool/SocketPool.c
 msgid "Out of sockets"
 msgstr ""
 
@@ -1825,13 +1827,18 @@ msgstr "Kesalahan DeInit RNG"
 msgid "RNG Init Error"
 msgstr "Kesalahan Init RNG"
 
+#: ports/nrf/common-hal/busio/UART.c
+msgid "RS485 Not yet supported on this device"
+msgstr ""
+
 #: ports/esp32s2/common-hal/busio/UART.c
 #: ports/mimxrt10xx/common-hal/busio/UART.c
 msgid "RS485 inversion specified when not in RS485 mode"
 msgstr "Pembalikan RS485 ditentukan saat tidak dalam mode RS485"
 
 #: ports/cxd56/common-hal/rtc/RTC.c ports/esp32s2/common-hal/rtc/RTC.c
 #: ports/mimxrt10xx/common-hal/rtc/RTC.c ports/nrf/common-hal/rtc/RTC.c
+#: ports/raspberrypi/common-hal/rtc/RTC.c
 msgid "RTC calibration is not supported on this board"
 msgstr "Kalibrasi RTC tidak didukung pada board ini"
 
@@ -1840,7 +1847,7 @@ msgid "RTC is not supported on this board"
 msgstr "RTC tidak didukung di board ini"
 
 #: ports/atmel-samd/common-hal/busio/UART.c ports/cxd56/common-hal/busio/UART.c
-#: ports/nrf/common-hal/busio/UART.c ports/stm/common-hal/busio/UART.c
+#: ports/stm/common-hal/busio/UART.c
 msgid "RTS/CTS/RS485 Not yet supported on this device"
 msgstr "RTS/CTS/RS485 Belum didukung pada perangkat ini"
 
@@ -1898,12 +1905,6 @@ msgstr ""
 msgid "SD card CSD format not supported"
 msgstr ""
 
-#: ports/atmel-samd/common-hal/busio/I2C.c ports/esp32s2/common-hal/busio/I2C.c
-#: ports/mimxrt10xx/common-hal/busio/I2C.c ports/nrf/common-hal/busio/I2C.c
-#: ports/raspberrypi/common-hal/busio/I2C.c
-msgid "SDA or SCL needs a pull up"
-msgstr "SDA atau SCL membutuhkan pull up"
-
 #: ports/stm/common-hal/sdioio/SDCard.c
 #, c-format
 msgid "SDIO GetCardInfo Error %d"
@@ -2203,7 +2204,7 @@ msgstr ""
 msgid "Unexpected nrfx uuid type"
 msgstr "Tipe urf nrfx tak sesuai"
 
-#: ports/esp32s2/common-hal/socketpool/Socket.c
+#: ports/esp32s2/common-hal/ssl/SSLSocket.c
 #, c-format
 msgid "Unhandled ESP TLS error %d %d %x %d"
 msgstr ""
@@ -2512,7 +2513,7 @@ msgstr ""
 msgid "buffer too small"
 msgstr ""
 
-#: shared-bindings/socketpool/Socket.c
+#: shared-bindings/socketpool/Socket.c shared-bindings/ssl/SSLSocket.c
 msgid "buffer too small for requested bytes"
 msgstr ""
 
@@ -3673,6 +3674,10 @@ msgstr "Muncul dari PulseIn yang kosong"
 msgid "pop from empty %q"
 msgstr ""
 
+#: shared-bindings/socketpool/Socket.c shared-bindings/ssl/SSLSocket.c
+msgid "port must be >= 0"
+msgstr ""
+
 #: py/objint_mpz.c
 msgid "pow() 3rd argument cannot be 0"
 msgstr ""
@@ -4202,6 +4207,9 @@ msgstr ""
 msgid "zi must be of shape (n_section, 2)"
 msgstr ""
 
+#~ msgid "SDA or SCL needs a pull up"
+#~ msgstr "SDA atau SCL membutuhkan pull up"
+
 #~ msgid "%d address pins and %d rgb pins indicate a height of %d, not %d"
 #~ msgstr "pin alamat %d dan pin rgb %d menunjukkan tinggi %d, bukan %d"
 

locale/circuitpython.pot

@@ -629,6 +629,10 @@ msgstr ""
 msgid "Cannot reset into bootloader because no bootloader is present."
 msgstr ""
 
+#: ports/esp32s2/common-hal/socketpool/Socket.c
+msgid "Cannot set socket options"
+msgstr ""
+
 #: shared-bindings/digitalio/DigitalInOut.c
 msgid "Cannot set value when direction is input."
 msgstr ""
@@ -865,7 +869,7 @@ msgstr ""
 msgid "Error in regex"
 msgstr ""
 
-#: shared-bindings/socketpool/Socket.c
+#: shared-bindings/socketpool/Socket.c shared-bindings/ssl/SSLSocket.c
 msgid "Error: Failure to bind"
 msgstr ""
 
@@ -924,7 +928,7 @@ msgstr ""
 msgid "FFT is implemented for linear arrays only"
 msgstr ""
 
-#: ports/esp32s2/common-hal/socketpool/Socket.c
+#: ports/esp32s2/common-hal/ssl/SSLSocket.c
 msgid "Failed SSL handshake"
 msgstr ""
 
@@ -1295,18 +1299,14 @@ msgstr ""
 msgid "Invalid size"
 msgstr ""
 
-#: ports/esp32s2/common-hal/socketpool/Socket.c
+#: ports/esp32s2/common-hal/ssl/SSLContext.c
 msgid "Invalid socket for TLS"
 msgstr ""
 
 #: ports/esp32s2/bindings/espidf/__init__.c ports/esp32s2/esp_error.c
 msgid "Invalid state"
 msgstr ""
 
-#: ports/esp32s2/common-hal/socketpool/Socket.c
-msgid "Invalid use of TLS Socket"
-msgstr ""
-
 #: shared-bindings/audiomixer/Mixer.c
 msgid "Invalid voice"
 msgstr ""
@@ -1323,10 +1323,6 @@ msgstr ""
 msgid "Invalid word/bit length"
 msgstr ""
 
-#: ports/esp32s2/common-hal/socketpool/Socket.c
-msgid "Issue setting SO_REUSEADDR"
-msgstr ""
-
 #: shared-bindings/aesio/aes.c
 msgid "Key must be 16, 24, or 32 bytes long"
 msgstr ""
@@ -1539,6 +1535,12 @@ msgstr ""
 msgid "No out in program"
 msgstr ""
 
+#: ports/atmel-samd/common-hal/busio/I2C.c ports/esp32s2/common-hal/busio/I2C.c
+#: ports/mimxrt10xx/common-hal/busio/I2C.c ports/nrf/common-hal/busio/I2C.c
+#: ports/raspberrypi/common-hal/busio/I2C.c
+msgid "No pull up found on SDA or SCL; check your wiring"
+msgstr ""
+
 #: shared-module/touchio/TouchIn.c
 msgid "No pulldown on pin; 1Mohm recommended"
 msgstr ""
@@ -1647,7 +1649,7 @@ msgstr ""
 msgid "Out of memory"
 msgstr ""
 
-#: ports/esp32s2/common-hal/socketpool/Socket.c
+#: ports/esp32s2/common-hal/socketpool/SocketPool.c
 msgid "Out of sockets"
 msgstr ""
 
@@ -1870,12 +1872,6 @@ msgstr ""
 msgid "SD card CSD format not supported"
 msgstr ""
 
-#: ports/atmel-samd/common-hal/busio/I2C.c ports/esp32s2/common-hal/busio/I2C.c
-#: ports/mimxrt10xx/common-hal/busio/I2C.c ports/nrf/common-hal/busio/I2C.c
-#: ports/raspberrypi/common-hal/busio/I2C.c
-msgid "SDA or SCL needs a pull up"
-msgstr ""
-
 #: ports/stm/common-hal/sdioio/SDCard.c
 #, c-format
 msgid "SDIO GetCardInfo Error %d"
@@ -2167,7 +2163,7 @@ msgstr ""
 msgid "Unexpected nrfx uuid type"
 msgstr ""
 
-#: ports/esp32s2/common-hal/socketpool/Socket.c
+#: ports/esp32s2/common-hal/ssl/SSLSocket.c
 #, c-format
 msgid "Unhandled ESP TLS error %d %d %x %d"
 msgstr ""
@@ -2466,7 +2462,7 @@ msgstr ""
 msgid "buffer too small"
 msgstr ""
 
-#: shared-bindings/socketpool/Socket.c
+#: shared-bindings/socketpool/Socket.c shared-bindings/ssl/SSLSocket.c
 msgid "buffer too small for requested bytes"
 msgstr ""
 
@@ -3626,6 +3622,10 @@ msgstr ""
 msgid "pop from empty %q"
 msgstr ""
 
+#: shared-bindings/socketpool/Socket.c shared-bindings/ssl/SSLSocket.c
+msgid "port must be >= 0"
+msgstr ""
+
 #: py/objint_mpz.c
 msgid "pow() 3rd argument cannot be 0"
 msgstr ""