re-basing EEZ branch to latest main

.github/workflows/ci.yaml

@@ -0,0 +1,92 @@
+name: ESP-IDF Build
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:  # Allows manual triggering from the Actions page
+
+env:
+  JSON_CONFIG_FILE: "source/esp_idf_project_configuration.json"
+
+jobs:
+  extract-config:
+    runs-on: ubuntu-latest
+    outputs:
+      platforms: ${{ steps.extract-platforms.outputs.platforms }}
+    steps:
+      - run: env | sort
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          sparse-checkout: |
+            ${{ env.JSON_CONFIG_FILE }}
+          sparse-checkout-cone-mode: false
+
+      - run: find . -type f
+
+      - run: which jq && jq --version
+
+      - name: Extract the keys (platform names) from the JSON file
+        id: extract-platforms
+        run: echo "platforms=$(jq -c 'keys' ${{ env.JSON_CONFIG_FILE }})" | tee -a ${GITHUB_OUTPUT}
+
+  build:
+    name: Build ${{ matrix.platform }}
+    needs: extract-config
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        platform: ${{ fromJson(needs.extract-config.outputs.platforms) }}
+
+    steps:
+      - run: env | sort
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          clean: true
+          # submodules: 'recursive'
+          sparse-checkout: |
+            source/
+
+      - name: Setup ccache
+        uses: hendrikmuhs/ccache-action@v1
+        with:
+          key: ${{ github.job }}-${{ matrix.platform }}
+          evict-old-files: 'job'
+
+      - run: find . -type f -and -not -path './.git/*' -not -path './.ccache/*'
+
+      - run: which jq && jq --version
+
+      - name: Set SDKCONFIG_DEFAULTS for ${{ matrix.platform }}
+        run: echo "SDKCONFIG_DEFAULTS=$(jq -r '.${{ matrix.platform }}.build.sdkconfigDefaults | join(";")' ${{ env.JSON_CONFIG_FILE }})" | tee -a ${GITHUB_ENV:?}
+
+      - run: env | sort
+
+      - name: esp-idf build
+        uses: espressif/esp-idf-ci-action@v1
+        with:
+          path: 'source'
+          esp_idf_version: v5.5.1 # optional, default is latest
+          target: esp32s3 # optional, default is esp32
+          extra_docker_args: "-v ./.ccache:/root/.ccache -e CCACHE_DIR=/root/.ccache -e SDKCONFIG_DEFAULTS"
+          command: "idf.py build"
+
+      - run: find ./source/build -type f
+
+      - run: ccache --print-stat
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: build-${{ matrix.platform }}
+          path: |
+            source/build/**/*.bin
+            source/build/flasher_args.json
+          if-no-files-found: error

.gitignore

@@ -1,6 +1,26 @@
 # macOS folder attributes
 .DS_Store
 
+build_distrib/temp
+
 # ignore SquareLine Studio files
 ui_design/backup
-ui_design/cache
+ui_design/cache
+ui_design/autosave
+ui_design_0.85/backup
+ui_design_0.85/cache
+ui_design_0.85/autosave
+ui_design_1.69/backup
+ui_design_1.69/cache
+ui_design_1.69/autosave
+ui_design_1.69_land/backup
+ui_design_1.69_land/cache
+ui_design_1.69_land/autosave
+ui_design_1.9/backup
+ui_design_1.9/cache
+ui_design_1.9/autosave
+ui_design_480x320land/backup
+ui_design_480x320land/cache
+ui_design_480x320land/autosave
+
+

FirmwareDevelopment.md

@@ -1,8 +1,8 @@
-# Tonex One Controller: An open-source controller and display interface for the IK Multimedia Tonex One guitar pedal
-This project uses a low-cost embedded controller (Espressif ESP32-S3) to form a bridge to the IK Multimedia Tonex One guitar pedal (which does not have native Midi capability.)
+# Tonex Controller: An open-source controller and display interface for the IK Multimedia Tonex One and Tonex pedal
+This project uses a low-cost embedded controller (Espressif ESP32-S3) to form a bridge to the IK Multimedia Tonex One guitar pedal (which does not have native Midi capability) and also the Tonex Pedal.
 
 # Development Info
-The code is written in C, for the Espressif ESP-IDF development environment version 5.0.2, and using the FreeRTOS operating system.
+The code is written in C, for the Espressif ESP-IDF development environment version 5.4.1, and using the FreeRTOS operating system.
 The LVGL library is used as the graphics engine.
 
 ## Task overview:
@@ -22,36 +22,64 @@ Building the application requires some skill and patience.
 Use the Menu Config system to select which components of the Controller you wish to enable.
 ![image](https://github.com/user-attachments/assets/593d48fb-aeea-4b20-87c7-dc9212952213)
 
-There are also a few settings that need changing between the Waveshare board with display and the Zero without a display, mainly due to the headless board having 4 MB flash versus 8MB on the display board:
 ### Partition Table
-- Waveshare Zero: "partitions_zero.csv"
-- All others: "partitions.csv"
+- All platforms: "partitions.csv"
 
 ### SPI RAM config
 Mode of SPI RAM chip in use:
-- Display board: "Octal Mode PSRAM"
-- No Display board: "Quad Mode PSRAM"
+- "Octal Mode PSRAM"
+- "Quad Mode PSRAM"
 
 ### Serial Flasher Config
 Flash Spi Mode:
-- Display board: "QIO" (Quad mode)
-- No Display board: "DIO" (Dual mode)
+- "QIO" (Quad mode)
+- "DIO" (Dual mode)
 
 ### Flash Size:
-- Display board: "8MB"
-- No Display board: "4MB"
-
-## Adding a new Platform
-To add support for a new PCB platform, the following steps are required:
-- Create sdkconfig.<boardname> in source folder, where <boardname> is a short descriptive name of the board. E.g. Waveshare 4.3B is "ws43B"
-- In this file, referring to the existing examples, configure the partition table, CPU speed, flash mode, and SPIRAM. If the board has a display, create a new descriptive Config for it. E.g. CONFIG_TONEX_CONTROLLER_DISPLAY_WAVESHARE_800_480
-- Edit the file "esp_idf_project_configuration.json" in the source folder. This file defines all supported platforms, and links a shot name to a build directory, and the sdkconfig file (created earlier)
-- If the board does not have a display, you should now be able to select the board from VS Code, and build it
-- If the board has a display, then more work is required, as follows
-- Ceate a new folder in the TonexOneController folder, called "ui_design_<descriptivename> where descriptive name is something uniqiue about the LCD, possibly its size or resolution
-- In this folder create a UI project using Squareline Studio, and design the UI. Refer to the other ui designs, and try to match the names of the screens and components as much as possible (this will minimise other code changes)
-- Set the Squareline Studio to export its files into "source/main/ui_generated_<descriptivename>"
-- Edit the file "source/main/CMakeLists.txt" and enter the unique Config you created before, and use that to set the include directory to the new ui_generated folder, and add the source files from it
-- Edit display.c to add your new Config, and inside that define, perform the display initialisation
-- Update the function update_ui_element() to handle the events needed. These events are sent from other parts of the system, for things like enabling/disabling Bluetooth status icon, setting the name of the preset etc
-
+- "8MB"
+- "4MB"
+
+# Wireshark USB Capture
+- Download and install the latest version of the free app "Wireshark" from https://www.wireshark.org/
+- Install it, ensuring the option for USB Pcap is enabled
+- Start the Wireshark app
+- Connect Tonex pedal to the same PC
+- In the Wireshark app, select the Capture interface to USBPcap
+<br>
+<img width="478" height="339" alt="image" src="https://github.com/user-attachments/assets/4e0f1296-274d-43be-b683-e0cf6bed2085" />
+<br><br>
+- Press the blue Sharkfin button to begin capturing all USB packets
+<br><br>
+<img width="438" height="168" alt="image" src="https://github.com/user-attachments/assets/ecbc74c8-8e70-47b5-8516-20a8735f9ed4" />
+<br><br>
+- Start the Tonex Editor software, and let it complete its sync process<br>
+- Press the red square button to stop capturing
+<br><br>
+<img width="753" height="348" alt="image" src="https://github.com/user-attachments/assets/75d66535-9cc0-48ba-8882-079bdd4fdfb8" />
+<br><br>
+- Use File -> Save As to save the captured data to disk
+
+# Debug Logs
+Extensive debug logging is used, in the form of serial printing from the main ESP32-S3 "UART" transmitter pin. To view these logs:
+- Obtain a USB serial adaptor, compatible with 3.3 volt TTL signals (low-cost example shown below)<br>
+<img width="1327" height="471" alt="image" src="https://github.com/user-attachments/assets/56b48788-f70c-4ccb-bbb5-fcd5f17531af" /><br> 
+- Connect the ground pin on the adaptor to a ground pin of the ESP32-S3
+- Connect the "RX" pin of the adaptor to TX pin of the ESP32-S3 board (pin locations shown for some platforms below.)
+<img width="480" height="308" alt="image" src="https://github.com/user-attachments/assets/7d6a7042-3ece-49e1-ba63-ebefd16ab469" /><br>
+<img width="868" height="539" alt="image" src="https://github.com/user-attachments/assets/4118ab86-c613-409a-8d8a-892eb4f12f29" /><br>
+<img width="909" height="600" alt="image" src="https://github.com/user-attachments/assets/5403c46d-c7d3-403c-9292-dfbce8568eea" /><br>
+<img width="991" height="368" alt="image" src="https://github.com/user-attachments/assets/dd7bcfcb-674a-4d42-b57f-afc069fc3c9f" /><br>
+- Download and install the latest version of the free app "Tera Term" from https://github.com/TeraTermProject/teraterm/releases (or use any other serial terminal program)
+- Connect the USB serial adaptor to your computer, and let it load any drivers it needs
+- Run Tera Term, and select the option for "Serial" and select the comm port corresponding to the USB serial adaptor
+<img width="771" height="448" alt="image" src="https://github.com/user-attachments/assets/7c8d4260-68c8-49a5-8e6e-d28ddb29dd8a" /><br>
+- Select "Setup" -> "Serial Port", and change the baud rate to 115200<br>
+<img width="406" height="324" alt="image" src="https://github.com/user-attachments/assets/45954e1a-027f-4476-af3e-5313747f34e0" /><br>
+- Power on the Controller board. Logging should appear on the Tera Term screen
+- To log the data to disk, select File -> Log
+
+
+
+
+
+

HardwarePlatform_Atom_S3R.md

@@ -0,0 +1,104 @@
+# Tonex One Controller: An open-source controller and display interface for the IK Multimedia Tonex One guitar pedal
+# M5Stack Atom S3R
+# Table of Contents
+ 1. [Connections](#connections)
+ 2. [Wired Footswitches - onboard](#footswitches)
+ 3. [Wired Footswitches - external](#footswitches_ext)
+ 4. [Wired Midi](#midi)
+ 5. [9 volt Power for 5 volt models](#9v_power)
+
+This hardware platform uses the M5Stack Atom S3R board (8MB flash, 8 MB PSRAM version.) 
+<br>
+https://shop.m5stack.com/products/atoms3r-dev-kit
+<br><br>
+<img width="320" height="323" alt="image" src="https://github.com/user-attachments/assets/b02bb831-21ab-4c67-9550-0e0bcce15e7c" />
+<br><br>
+This module is low cost, supports a tiny LCD display, and comes in a case. It requires a 5 volt DC power supply.
+Caution: do not directly connect a pedalboard 9v! If you do, you will probably blow up both the PCB and your Tonex One!<br>
+If you do wish to use 9v power, refer to [9 volt Power for 5 volt models](#9v_power)
+
+## Connections <a name="connections"></a>
+Note: the controller code relies on the Tonex One pedal being set to Stomp mode. Code is in place to do this automatically.
+- Connect a DC jack to the PCB via the 4 pin connector, as shown below. Note the positive and negative polarity must match your power supply
+- Connect the OTG USB-C port on the board to the ToneX One USB-C port
+- Connect 5 volts DC to the power input jack that you connected in the first step
+- Switch on the power supply
+- The board USB port will power the Tonex One
+- Optional: for the Bluetooth Client version of code, switch on a M-Vave Chocolate Midi pedal (https://www.cuvave.com/productinfo/724103.html). After a few seconds it should connect and the Bluetooth icon should change from gray to blue
+- Optional: for the Bluetooth Server version of code, the controller will be available as a peripheral for you to connect to via a Bluetooth Midi device. The Bluetooth icon should change from gray to blue when connected.
+![wiring_atom_s3r](https://github.com/user-attachments/assets/0829c254-23bb-4ef6-8695-c5a8d363d817)
+
+<br><br>
+## Wired Footswitches (onboard) <a name="footswitches"></a>
+Wired footswitches can optionally be used. These "onboard" switches connect directly to the controller with out needing any additional circuitry.<br>
+The footswitch must be a "momentary" type that is only has its contacts closed when it is pressed.
+The common pin of the footswitch must connect to the Controller ground pin, and the other wires connected as shown.
+<br><br>
+A maximum of 4 footswitches are supported.
+<br>
+Various modes are supported, set using the web configuration:
+- 2 switches, doing Next/Previous preset
+- 4 switches, doing banked switching (just like the M-vave Chocolate pedal does)
+- 4 switches, doing direct preset selection via binary (intended for relay control)<br>
+
+![footswitches_atoms3r](https://github.com/user-attachments/assets/e3c227f4-f3ba-480b-a41d-3ab54e3966d5)
+
+<br><br>
+## Wired Footswitches (external) <a name="footswitches_ext"></a>
+Starting from firmware version 1.0.8.2, with the use of an additional PCB, up to 16 footswitches can be connected.<br> 
+The footswitch must be a "momentary" type that is only has its contacts closed when it is pressed.
+<br><br>
+The additional PCB must use the "SX1509" chip. The recommeded one is the Sparkfun SX1509 breakout board:
+https://www.sparkfun.com/sparkfun-16-output-i-o-expander-breakout-sx1509.html
+<br>
+![image](https://github.com/user-attachments/assets/0575f0a0-1eb3-4aef-a7e2-c321876f7ed0)
+
+NOTE: other types of IO expander boards that use different chips are not supported and will not function. It must contain the SX1509 chip.
+
+### Address Setting 
+The SX1509 PCB has a selectable address system. This must be set correctly in order for the board to function with the controller.
+- Using a sharp knife, carefully cut the thin tracks between the pads as shown below
+- Use solder to bridge the pads as shown below
+- This sets the SX1509 adress to "11" which avoids conflicting with other parts on the controller boards
+![sx1509_address](https://github.com/user-attachments/assets/84030e88-f6e7-4fc0-8230-3fff6dc1235a)
+
+
+The common pin of each footswitch must connect to the SX1509 ground pins. The labels "0", "1" etc are the individual switch inputs. Footswitch 1 connected to input 0. Footswitch 2 to input 1 etc.
+<br><br>
+Multiple modes are supported, configured using the web configuration.
+![external_atom_3sr](https://github.com/user-attachments/assets/2c5db1a0-b66a-4516-96fd-47d03f7526da)
+
+
+## Wired Midi (firmware version V1.0.4.1 or above required) <a name="midi"></a>
+Note: Wired Midi is disabled by default. If it is enabled without the proper hardware (detailed below) being fitted, you may get "phantom" preset changes, due to the serial input "floating".
+Only enable wired Midi when hardware is connected!<br>
+Refer here for details on how to enable it, and set the Midi channel:
+https://github.com/Builty/TonexOneController/blob/main/WebConfiguration.md
+<br><br>
+Wired Midi is supported on all platforms. A extra PCB is required for all platforms, an "Adafruit Midi FeatherWing kit", for US$7.<br> 
+https://www.adafruit.com/product/4740 <br>
+This Midi board supports both 5-pin DIN sockets (included in kit) and 3.5mm jacks (not included in kit.)<br>
+<br>
+Midi Featherwing:<br>
+![midi_featherwing](https://github.com/user-attachments/assets/532d7d81-ae7e-485b-8d59-77ff6056e331)
+
+M5Stack Atom S3R to Midi Featherwing:<br>
+![midi_atoms3r](https://github.com/user-attachments/assets/1663b487-5ce2-44ac-8cf8-6fb71c7622a3)
+<br><br>
+## 9 volt Power for 5 volt Models<a name="9v_power"></a>
+The Atom-S3R board has a maximum of 5 volts input.
+<br>It is still possible however to run it from a 9 volt power supply, with the additional of another low cost off-the-shelf PCB.
+<br>**Caution:** This section requires some more advanced skills, such as using a multimeter to measure voltage. Incorrect voltage setting or polarity could cause damage to the PCB and/or your Tonex pedal.
+<br><br>Various electronic shops, and also suppliers like Amazon, often have low cost "switching regulators." These are a compact circuit that can convert the 9 volt pedalboard power down to the 5 volts required by the Zero and the 1.69. Sample photos are shown below.<br>
+Some of these may be a fixed voltage, in which case you must select one with a 5 volt output. Most models however are adjustable, using a small "trimpot."
+<br>For the adjustable types, it is necessary to set it to 5 volts output **before** connecting to the controller PCB.
+<br>
+- Connect the 9 volt input to the input terminals on the voltage regulator PCB. Ensure the positive and negative the right way around. The standard for pedal boards is usually negative to the centre pin of the DC jack, but this should be checked
+- Set the multimeter to measure DC voltage, then connect the multimeter probes to the voltage regulator output terminals
+- Adjust the trimpot on the voltage regulator PCB to achieve close to 5 volts. I doesn't have to be exactly 5 volts, but should be in the range of 4.95v to 5.05v
+- Once this has been achieved, connect the voltage regulator output terminals to the board, in the same locations as shown in the prior wiring diagram
+- Keep the Tonex pedal disconnected, and power on the board. Check that it boots up and runs normally
+- Once this test has passed, then you can connect the Tonex pedal
+![image](https://github.com/user-attachments/assets/e59673c5-f741-4516-b471-5af0eb685d12)
+![image](https://github.com/user-attachments/assets/472394d5-a2c9-492d-909c-792480abcb4c)
+