Wireless, Networking Support for Pico W, Pico 2 W (#416)

* Add StringConfigPoint

* Add wifi connection implementation

* Add wifi, NTP configurations to `experimental_config`

* Add NTP implementation for realtime clock support

* Add additional module dependencies needed for NTP

* Catch import errors in the wifi and ntp modules as appropriate, re-raising them with our wrapper errors

* Update the programming instructions for all pico-family variants, not just the Pico 2

* Add basic HTTP server to `experimental`, HTTP-based `contrib` script

* Remove the optional fields from `datetime` tuples; make length consistently 8 to include yearday; this keeps all sources compatible with `machine.RTC`

* Divide the experimental configuration editor into sections like the main config editor since the number of options is growing a lot

* Add a dedicated text logging class so we can have consistent text output across the firmware

* Add Open Sound Control (OSC) module to `experimental` and a basic `contrib` script that uses it

* Add TouchOSC setup instructions & screenshots

* Add WebREPL support via experimental_config

* Add desktop interface program for converting 8mu's MIDI messages to OSC for EuroPi

* Fix the default i2c timeout in the config documentation

Author: chrisib

contributing.md

@@ -225,6 +225,31 @@ Changes or additions to public API functions must include the corresponding upda
 
 All existing automated tests must pass. An effort should be made to improve the test suite by adding tests for new or changed functionality.
 
+## Desktop Scripts
+
+Python programs intended to be run on a laptop or desktop computer connected to EuroPi (either via USB or serial communication, or over WiFi) should be located
+in the `software/desktop` directory:
+
+```
+software
+├── contrib/
+├── desktop/
+│   └── my_desktop_program.md
+│   └── my_desktop_program.py
+├── firmware/
+```
+
+As with `contrib` scripts, you should include a `.md` file explaining how your desktop program operates, any additional libraries it depends on (and how to install them),
+and any configuration the user must do to set up your program.  Also include whether or not EuroPi requires a specific program to be started or a command to be run
+in order to facilitate the communication between the desktop and EuroPi.
+
+Desktop scripts should target Python 3, ideally Python 3.10 or later. If you need a very specific version of Python (e.g. because of a particular dependency that is
+only available on some versions) this should be noted in the `.md` file.
+
+Any desktop programs should be written in Python, with only the necessary `.py` files included; do not include IDE-specific project files, Python bytecode (`*.pyc`) files,
+or any other generated files. Additional source files, e.g. `.proto` (Protocol Buffer definitions), `.ui` (Qt GUI definitions), and the like may be included if they are
+required for the program and have their dependencies explained in the `.md` file.
+
 ## License
 
 All software in this repository is licensed under the [Apache 2.0](/software/LICENSE) license. In accordance with this license, please place a comment block at the top of your Python source files indicating the copyright and license:

software/CONFIGURATION.md

@@ -19,15 +19,17 @@ default configuration:
     "EXTERNAL_I2C_SCL": 3,
     "EXTERNAL_I2C_CHANNEL": 1,
     "EXTERNAL_I2C_FREQUENCY": 100000,
-    "EXTERNAL_I2C_TIMEOUT": 50000,
+    "EXTERNAL_I2C_TIMEOUT": 1000,
     "MAX_OUTPUT_VOLTAGE": 10.0,
     "MAX_INPUT_VOLTAGE": 10.0,
     "GATE_VOLTAGE": 5.0,
     "MENU_AFTER_POWER_ON": false
 }
 ```
 
-System options:
+## System
+
+Options:
 - `EUROPI_MODEL` specifies the type of EuroPi module. Currently only `"europi"` is supported. Default: `"europi"`
 - `PICO_MODEL` must be one of
   - `"pico"`,
@@ -41,7 +43,9 @@ System options:
 - `MENU_AFTER_POWER_ON` is a boolean indicating whether or not the module should always return to the main menu when
   it powers on.  By default the EuroPi will re-launch the last-used program instead of returning to the main menu. Default: `false`
 
-Display options:
+## Display
+
+Options:
 - `ROTATE_DISPLAY` must be one of `false` or `true`. Default: `false`
 - `DISPLAY_WIDTH` is the width of the screen in pixels. The standard EuroPi screen is 128 pixels wide. Default: `128`
 - `DISPLAY_HEIGHT` is the height of the screen in pixels. The standard EuroPi screen is 32 pixels tall. Default: `32`
@@ -50,14 +54,18 @@ Display options:
 - `DISPLAY_CHANNEL` is the I²C channel used for the display, either 0 or 1. Default: `0`
 - `DISPLAY_CONTRAST` is a value indicating the display contrast. Higher numbers give higher contrast. `0` to `255`. Default: `255`
 
-External I²C options:
+## External I²C
+
+Options:
 - `EXTERNAL_I2C_SDA` is the I²C SDA pin used for the external I²C interface. Only SDA capable pis can be selected. Default: `2`
 - `EXTERNAL_I2C_SCL` is the I²C SCL pin used for the external I²C interface. Only SCL capable pins can be selected. Default: `3`
 - `EXTERNAL_I2C_CHANNEL` is the I²C channel used for the external I²C interface, either 0 or 1. Default: `1`
 - `EXTERNAL_I2C_FREQUENCY` is the I²C frequency used for the external I²C interface. Default: `100000`
 - `EXTERNAL_I2C_TIMEOUT` is the I²C timeout in milliseconds for the external I²C interface. Default: `1000`
 
-I/O voltage options:
+## I/O voltage
+
+Options:
 - `MAX_OUTPUT_VOLTAGE` is a float in the range `[0.0, 10.0]` indicating the maximum voltage CV output can generate. Default: `10.0`
   The hardware is capable of 10V maximum
 - `MAX_INPUT_VOLTAGE` is a float in the range `[0.0, 12.0]` indicating the maximum allowed voltage into the `ain` jack.
@@ -71,36 +79,92 @@ limits are intended for broad compatibility configuration, not for precise tunin
 If you assembled your module with the Raspberry Pi Pico 2 (or a clone featuring the RP2350 microcontroller) make sure to
 set the `PICO_MODEL` setting to `"pico2"`.
 
-
 # Experimental configuration
 
 Other configuration properties are used by [experimental features](/software/firmware/experimental/__init__.py)
 and can be set using a similar static configuration file. This file is located at `/config/ExperimentalConfig.json`
-on the Raspberry Pi Pico. If this file does not exist, default settings will be loaded.  The following
-shows the default configuration:
+on the Raspberry Pi Pico. If this file does not exist, default settings will be loaded.
 
-```json
-{
-    "VOLTS_PER_OCTAVE": 1.0,
-    "RTC_IMPLEMENTATION": "",
-    "UTC_OFFSET_HOURS": 0,
-    "UTC_OFFSET_MINUTES": 0,
-}
-```
+## Quantization
 
-Quantization options:
+Options:
 - `VOLTS_PER_OCTAVE` must be one of `1.0` (Eurorack standard) or `1.2` (Buchla standard). Default: `1.0`
 
-RTC options:
+## Realtime Clock (RTC)
+
+Options:
 - `RTC_IMPLEMENTATION` is one of the following, representing the realtime clock enabled on your module:
   - `""`: there is no RTC present. (default)
   - `"ds3231"`: use a DS3231 module connected to the external I2C interface
   - `"ds1307"`: use a DS1307 module connected to the external I2C interface (THIS IS UNTESTED! USE AT YOUR OWN RISK)
+  - `"ntp"`: use an NTP source as the external clock. Requires wifi-supported Pico (e.g. Rasperry Pi Pico W or Pico 2 W)
+    and valid network configuration (see [WiFi connection](#wifi-connection), below)
 
-Timezone options:
+## Timezone
+
+Options:
 - `UTC_OFFSET_HOURS`: The number of hours ahead/behind UTC the local timezone is (-24 to +24)
 - `UTC_OFFSET_MINUTES`: The number of minutes ahead/behind UTC the local timezone is (-59 to +59)
 
+## WiFi Connection
+
+Options:
+- `WIFI_MODE`: the wireless operation mode, one of:
+  - `"access_point"` (default): EuroPi acts as a wireless access point for other devices to connect to
+  -`"client"`: connect EuroPi to an external wireless router or accesspoint (DHCP required)
+- `WIFI_SSID`: the SSID of the wireless network to connect to (in `client` mode) or to broadcast
+  (in `access_point` mode). Default: `"EuroPi"`
+- `WIFI_BSSID`: the optional BSSID of the network to connect to (e.g. access point MAC address). Default: `""`
+- `WIFI_PASSWORD`: the password of the wireless network. Default: `"europi"`
+- `WIFI_CHANNEL`: the WiFi channel 1-13 to use in `access_point` mode; ignored in `client` mode. Default: `10`
+- `WIFI_DHCP`: ignored if `WIFI_MODE` is `access_point`. Otherwise this controls whether or not
+  EuroPi requests a DHCP lease from the external access point. Default: `true`.
+- `WIFI_IP`: a static IP address to use in `client` mode if DHCP is disabled. Default: `192.168.4.1`
+- `WIFI_GATEWAY`: the static gateway in `client` mode when DHCP is disabled. Default: `0.0.0.0`
+- `WIFI_NETMASK`: the netmask to use in `client` mode, if DHCP is disabled. Default: `255.255.255.0`
+- `WIFI_DNS`: the IP address of the DNS server to use when DHCP is disabled. Default: `8.8.8.8`
+
+WiFi options are only applicable if EuroPi has the Raspberry Pi Pico W or Raspberry Pi Pico 2 W board;
+other Pico models do not contain wireless support.
+
+**NOTE**: At the time of writing, the latest Micropython firmware for the Raspberry Pi Pico 2 W has a bug in
+which the wireless card will not reliably work if the CPU is overclocked. If you have problems using wifi please
+try changing `CPU_FREQ` to `normal` in `EuroPiConfig.json`.
+
+### WiFi Security
+
+If `WIFI_PASSWORD` is empty EuroPi will assume the network is _unencrypted_. This applies to both `client` and
+`access_point` modes. If `WIFI_PASSWORD` contains any text, WPA/WPA2 will be used (WPA2 is preferred, but
+in `client` mode WPA will be used if the router requires it).
+
+Other wireless authentication models, including the use of cerfificates, VPN connections, etc... are not supported
+at this time on the Raspberry Pi Pico (2) W.
+
+## WebREPL Configuration
+
+`WebREPL` allows accessing the Python shell over WiFi, as well as enabling sending/receiving files wirelessly.
+This can be useful if you lack a USB cable long enought to reach from your computer to your EuroPi.
+
+Enabling `WebREPL` requires a Raspberry Pi Pico W or Pico 2 W, as well as a valid wifi configuration (see above).
+
+When enabled, `WebREPL` will use the password `EuroPi` by default. To change this password you will need to modify
+`/webrepl_cfg.py` to enter your new password.
+
+To access `WebREPL`, direct your computer's browser to `http://<EuroPi's IP address>:8622`, e.g.
+`http://192.168.4.1:8622`. Alternatively you can configure Thonny's terminal to connect via `WebREPL`
+by selecting Run > Configure Interpreter, selecting `WebREPL` from the drop-down, and entering
+EuroPi's IP address and port 8622.
+
+Options:
+- `ENABLE_WEBREPL`: enable or disable `WebREPL`. Default: `false`
+
+### `WebREPL` Security
+
+Enabling `WebREPL` can be a security risk: it potentially allows anyone to access the Python interpreter of
+your EuroPi, giving them complete access to run code, modify files, etc.... If you choose to enable `WebREPL`
+it is highly recommended that you choose a strong password and that you make sure your wifi connection is
+using WPA2 (see [WiFi Security](#wifi-security), above).
+
 # Accessing config members in Python code
 
 The firmware converts the JSON file into a `ConfigSettings` object, where the JSON keys are converted

software/contrib/README.md

@@ -167,6 +167,14 @@ The division of the master clock that each LFO runs at, as well as each of their
 <i>Author: [roryjamesallen](https://github.com/roryjamesallen)</i>
 <br><i>Labels: LFO</i>
 
+### HTTP Interface \[ [documentation](/software/contrib/http_control.md) | [script](/software/contrib/http_control.py) \]
+
+Control the levels of CV1-6 using sliders in a web interface. Requires installation and configuration
+of a Raspberry Pi Pico W or Pico 2 W.
+
+<i>Author: [chrisib](https://github.com/chrisib)</i>
+<br><i>Labels: cv, http, wifi</i>
+
 ### Itty Bitty \[ [documentation](/software/contrib/itty_bitty.md) | [script](/software/contrib/itty_bitty.py) \]
 
 Dual-channel 8-bit trigger+gate+cv sequencer based on the binary representation of an 8-bit number.
@@ -221,6 +229,16 @@ Users have a copy of the original trigger signal, a sample and hold and a track
 <i>Author: [seanbechhofer](https://github.com/seanbechhofer)</i>
 <br><i>Labels: gates, sample&hold, track&hold</i>
 
+### OSC Interface \[ [documentation](/software/contrib/osc_control.md) | [script](/software/contrib/osc_control.py) \]
+
+Interface program for sending & receiving Open Sound Control (OSC) packets over UDP. Compatible with TouchOSC and
+other programs that support OSC over UDP.
+
+Requires a Raspberry Pi Pico W or Pico 2 W with a properly-configured wifi connection to your other devices.
+
+<i>Author: [chrisib](https://github.com/chrisib)</i>
+<br><i>Labels: osc, wifi</i>
+
 ### Pam's "EuroPi" Workout \[ [documentation](/software/contrib/pams.md) | [script](/software/contrib/pams.py) \]
 
 A re-imaging of [ALM/Busy Circuit's Pamela's "NEW" Workout](https://busycircuits.com/alm017/). Turns the EuroPi into a clocked modulation

software/contrib/http_control.md

@@ -0,0 +1,29 @@
+# HTTP Interface
+
+This program provides a simple HTTP interface to control the levels of CV1-6.
+
+It requires that your EuroPi have a Raspberry Pi Pico W or Pico 2 W. See
+[wireless configuration](/software/CONFIGURATION.md#wifi-connection) for
+instructions on configuring the Pico W/Pico 2 W's wifi.
+
+## Accessing the web interface
+
+To access the web interface, connect your device (phone/tablet/desktop/laptop/etc...)
+to the same wifi network at EuroPi (or to EuroPi's access point if you have
+the wifi interface set up in AP mode).  Then navigate to the IP address
+displayed on the screen, e.g. `http://192.168.4.1`.
+
+The web interface has six sliders. Each of these can be moved to set the output voltage
+of one of the corresponding outputs.
+
+## I/O Summary
+
+CV1-6 will output voltages as specified by the web interface.
+
+The buttons, knobs, `ain`, and `din` are not used by this program.
+
+## Note on concurrent users
+
+There is no authentication no restriction on the number of concurrent
+browser connections. It is recommended to only use one device at a time
+to control EuroPi over HTTP.