CoyoPedal

Het scherm is een onderdeel van één specifieke board-variant; dezelfde firmware kan ook worden gebouwd voor een kale ESP32-S3-module zonder paneel. In dat geval zijn de versterker, de effecten en de presets identiek, en dient de BOOT-knop als voetschakelaar.

Er is ook een WebAssembly-versie beschikbaar die in de browser kan worden gespeeld. Deze bevat dezelfde UI, DSP, neurale amp-modellen en laat je gitaar via een audio-interface spelen, zonder dat er hardware nodig is.

Belangrijkste Kenmerken

  • Full-size NAM A2-modellen op 48 kHz: De 23-laags, acht-kanaals WaveNet draait in block floating point met handgeschreven Xtensa-kernels, verdeeld over beide cores en verwerkt in blokken van 64 frames.
  • Eigen captures laden: Kopieer originele .nam-bestanden naar een microSD-kaart of wijs in de browser-versie een map aan. Het pedaal parseert, valideert en bereidt deze op het apparaat voor; er is geen desktop-converter nodig.
  • Effectketen: Rondom de versterker bevindt zich een keten bestaande uit een gate, compressor, chorus en drive (ervoor), en een digitale delay en stereo spring reverb (erna).
  • Presets: Presets voor de versterker, bedieningselementen en effecten worden op het pedaal opgeslagen, inclusief een on-screen toetsenbord voor het benoemen ervan.
  • Tuner: Een tuner op hetzelfde scherm, waarbij de output wordt gedempt tijdens het stemmen.
  • Onderhoudsmodus: Voorzien van geauthenticeerde Wi-Fi OTA-updates, remote diagnostiek en BLE-discovery. De radio's zijn volledig uitgeschakeld tijdens het spelen.

Hardware

Ondersteunde boards

BoardAliasFlashKenmerkenBediening
Waveshare ESP32-S3-Touch-AMOLED-2.06amoled32 MBESP32-S3R8, 8 MB PSRAM, 410 × 502 AMOLED, touch, AXP2101 PMIC, microSD-slotTouchscreen; BOOT: tikken om te bypassen, 1,5 s vasthouden voor onderhoud
ESP32-S3-DevKitC-1 N16R8, en kale S3R8 moduless3-devkit16 MBESP32-S3R8, 8 MB PSRAM, geen paneel, geen PMIC, geen SD-slotBOOT: tikken om in/uit te schakelen, 1,5 s vasthouden voor onderhoudsmodus

Het AMOLED-board is het referentiemodel. De fabrieksinstellingen, de browser-build en de screenshots zijn hierop gebaseerd. Een board zonder scherm draait dezelfde versterker via dezelfde DSP op 48 kHz. Gemeten op de devkit verbruikt dit 91% tot 94% van het budget van 1.333 µs per blok over de twee cores, zonder gemiste deadlines. Configuratie gebeurt via de maintenance API in plaats van handmatig.

Vereisten voor elk board: Een ESP32-S3 met 8 MB PSRAM (nodig voor het A2-model) en een USB-poort die de chip als host kan aansturen. Een kaal module heeft geen PMIC en geen batterijpad; in tegenstelling tot de AMOLED voedt deze de host-poort niet zelf, waardoor de interface een eigen stroomvoorziening nodig heeft.

Overige componenten

OnderdeelNotities
AudioEen USB Audio Class 2 interface op de USB-poort van het board, die functioneert als USB-host op 48 kHz.
OpslagOptionele microSD-kaart (op boards met slot) voor eigen captures.

Getest met: XTONE Pro en IK Multimedia iRig HD X; iRig HD 2 via een specifiek UAC1-profiel. Elke interface die een 48 kHz UAC2-ingang en -uitgang biedt, zou moeten werken.

Gebruik van het pedaal

Het startscherm toont de signaalketen in volgorde. Tik op een blok om het aan of uit te zetten, of houd het vast om het te bewerken: sleep een schuifregelaar om een waarde te wijzigen en gebruik ‹ › om door de bedieningselementen te bladeren. Houd het 'Amp'-blok vast om de capture-browser te openen, waarin fabrieks-captures, geïmporteerde captures en mappen op de SD-kaart worden getoond. De schakelaar rechtsboven bypasses het hele pedaal, en 'Tuner' opent de stemmer. Tik op de preset-naam om presets te wisselen, op te slaan, te hernoemen, te verwijderen of aan te maken. Een nieuwe preset begint met het huidige geluid.

Op elk board fungeert de BOOT-knop als voetschakelaar:

  • Korte druk: Schakelt het pedaal in of bypasses het.
  • 1,5 seconden vasthouden: Schakelt tussen audio-modus en onderhoudsmodus (maintenance mode). Het scherm geeft aan wanneer je kunt loslaten. Korte drukken doen niets in de onderhoudsmodus.

Op een board zonder scherm worden presets, captures en overige bedieningselementen bereikt vanuit de onderhoudsmodus via tools/esp32/amoled_remote.py. Het pedaal start standaard ingeschakeld met de onthouden preset, of de eerste preset (Silver Lining - clean) als er geen selectie is opgeslagen.

Eigen captures

Ondersteunde modellen zijn 48 kHz, acht-kanaals NAM A2 ("A2-Full") WaveNets, inclusief een matching member van een SlimmableContainer. Andere architecturen, sample rates en layer shapes worden geweigerd met een foutmelding. Voorbereide .namb-bestanden worden evenredig geaccepteerd.

Installatie via SD-kaart:

  1. Formatteer een kaart als FAT.
  2. Plaats .nam of .namb bestanden in een map genaamd nam op de root van de kaart (tot zes niveaus diep).
  3. De browser toont deze mappenstructuur en een capture wordt vernoemd naar het bestand.
  4. Bestandsnamen moeten binnen 127 bytes passen en bestanden maximaal 2 MiB zijn.
  5. Plaats de kaart voordat het apparaat wordt ingeschakeld en kies de capture in de Amp-browser.

Bij de eerste selectie van een capture pauzeert het audio-signaal terwijl het pedaal het bestand voorbereidt. Dit kan tientallen seconden duren. Als de kaart beschrijfbaar is, slaat het pedaal een geverifieerd .s3cache-bestand op naast het origineel, waardoor latere ladingen snel gaan. Het originele bestand wordt nooit gewijzigd.

De volledige VoLum-bibliotheek is gepubliceerd in de VoLum-repository en kan naar een gekoppelde kaart worden gekopieerd via: npm run fetch:volum -- /Volumes/SDCARD

Captures in de browser

Op coyopedal.playtaurus.com draait de firmware zelf. Omdat er geen kaartslot is, vraagt de site om een map. De captures verschijnen onder 'SD card' in de amp-browser. De site bereidt originele .nam-bestanden voor en cached ze als .s3cache, precies zoals het board dat doet. Presets worden gespiegeld naar de map als coyopedal-presets.json.

Chrome en Edge kunnen terugschrijven naar de map; Safari en Firefox staan alleen lezen toe, waardoor schrijfacties daar in de browser-opslag worden bewaard.

Bouwen

Vereisten

  • Git en Node.js 22.13 of nieuwer.
  • Python 3 met Pillow en fontTools (voor het rasteriseren van het UI-lettertype).
  • Een C++20 compiler en CMake (voor host-tests).
  • Emscripten SDK op de PATH (alleen voor de web-build).
  • De Gea CLI installeert overige zaken, inclusief ESP-IDF.

Setup

  1. Installeer de Gea CLI:

npm i -g @geastack/cli

  1. Installeer ESP-IDF 6.0.2 en de ESP32-S3 toolchain:

gea setup --esp-idf

  1. Clone de repository en installeer afhankelijkheden:

git clone git@github.com:dashersw/coyopedal.git cd coyopedal npm ci

  1. Genereer de Wi-Fi configuratie (nodig voor onderhoudsmodus, OTA en remote tools):

npm run remote:configure -- --ssid JOUW_WIFI

  1. Verbind het board via USB en registreer het:

gea setup (Kies Known supported board → Waveshare ESP32-S3 Touch AMOLED 2.06 en behoud de alias amoled).

  1. Controleer de toolchain en het board:

gea doctor

Build en Flash

  • Builden: gea build --board amoled (Het firmware-image komt in build/pedalboard.bin).
  • Flashen: gea flash --board amoled (De eerste flash moet via USB gebeuren voor de partitietabel en fabrieksgegevens).

npm run build:firmware en npm run flash:firmware voeren dezelfde commando's uit. Voor een headless board gebruik je --board s3-devkit.

Op de AMOLED is de flash verdeeld in twee 8 MB OTA-slots, een fabriek-model partitie, een fabriek-preset partitie en een partitie voor geïmporteerde modellen. Opgeslagen presets staan in NVS en worden bij het flashen niet gewist.

Andere boards

De firmware is modulair. Twee vragen bepalen de configuratie:

  1. Is er een scherm? Als een target-definitie geen chips.display of canvas heeft, wordt GEAEMBEDDEDNO_DISPLAY=1 gebruikt. Dit bespaart ongeveer 1 MB aan image en 1,25 MB PSRAM.
  2. Is er een PMIC? Zonder power chip wordt GEABOARDHAS_POWER=0 gebruikt, waardoor de power-driver een no-op wordt.

Om een nieuw board toe te voegen:

  • Kies of schrijf een target-definitie in @geastack/targets.
  • Registreer een alias via gea setup of handmatig in .gea/boards.json.
  • Voeg bij een afwijkende flash-grootte de partitie-layout toe in package.json onder gea.targets.esp32.partitionsByTarget.

Checks en tests

  • npm test: Test USB-descriptors, effecten, presets en het voorbereide NAM-model.
  • npm run check: Linting, TypeScript en formatting.

GitHub Actions voert deze tests uit bij elke push en pull request, en bouwt ook het firmware-image en de web-module.

Browser-builds

Er zijn twee browser-versies:

  1. DOM Preview (npm run dev): Een snelle iteratieversie waarbij TSX is gecompileerd naar een web-framework.
  2. WASM Build (npm run build:web-wasm): De deployed pagina. Geatsc converteert de TSX naar C++ en linkt dit met dezelfde Gea layout en paint engine als de firmware. Wat je hier ziet, is exact wat het paneel toont.

Voor lokale weergave is npm run serve-web nodig, omdat de audio-graph draait in een AudioWorklet over shared memory, wat specifieke cross-origin isolatie-headers vereist.

Onderhoudsmodus en OTA-updates

De onderhoudsmodus ontlaadt de audio-graph en start Wi-Fi en BLE. Je activeert dit via:

  • Het scherm: Preset-naam → Setup → Maintenance mode.
  • Hardware: Houd de BOOT-knop circa 1,5 seconde vast tot het scherm "Please wait" toont.

Houd de knop opnieuw ingedrukt of kies "Return to pedalboard" om terug te keren naar de audio-modus (waarbij de radio's weer uitgaan).

Wi-Fi-gegevens en het authenticatietoken worden gecompileerd vanuit src/native/services/remote_config.h. Zonder dit bestand wordt de gehele service (Wi-Fi, BLE, HTTP-server) weggelaten uit het image.

Met het pedaal in onderhoudsmodus kan tools/esp32/amoled_remote.py worden gebruikt voor:

  • Discovery: npm run remote -- discover
  • OTA-update: npm run remote -- --host PEDAL_IP ota

Repository structuur

  • src/ui/: Touchscreen app (TSX, CSS, stores) voor apparaat en browser.
  • src/preview/: Browser-adapter met gesimuleerd pedaal.
  • src/audio/: Effecten, tuner en audio-processor per blok.
  • src/nam/: NAM A2-engine en ESP32-S3 assembly kernels.
  • src/native/: Firmware (Boot, drivers, storage, services, UI-bridge).
  • web/: De pagina die de WASM-build host.
  • assets/: Fabrieks-captures, index en presets.
  • scripts/: Helpers voor build, deploy en tests.
  • tools/: Asset packers en maintenance client.
  • docs/: Architectuur, geheugenlayout en USB-audio notities.

Fabrieks-captures

De firmware wordt geleverd met twee captures van VoLum by Lum:

  • Diezel Herbert, kanaal 1, V30 cabinet.
  • Ampete One, kanaal 4, V30 cabinet.

Deze zijn gedistribueerd onder de MIT-licentie.

Bijdragen en Licentie

Issues en pull requests zijn welkom. Raadpleeg CONTRIBUTING.md voor regels over formatting en checks.

Dit project is gelicentieerd onder de GNU General Public License v3.0. Componenten van derden behouden hun eigen licenties.