Eurorack busboard singlerow

Maddie Synths

• More details on each firmware is on my site
• More about me at madelyn.sh
• You can purchase some of my work from my etsy store

Licensing

The repo-wide default is MIT (LICENSE.md at the root, © 2026 Madelyn Yeary). Every source file carries a License: notice in its header saying which terms apply to it and where the code came from.

That default is overridden per directory: any directory containing its own LICENSE.md is governed by that file instead, for everything beneath it. The overrides exist because the work there either came from somewhere else or is deliberately released on different terms

Repo layout

.
├── firmwares/                  Arduino sketches — grouped by hardware platform
│   ├── hagiwo-mod1/mod1-*/     Arduino Nano modules  (mod1-euclidean.ino, …)
│   ├── hagiwo-mod2/mod2-*/     XIAO RP2350 modules   (mod2-vco.ino, …)
│   ├── hagiwo-30/hagiwo30-*/   HAGIWO #30 sequencer variants (Nano)
│   ├── rabid-audio-clk/        rabid.audio port, bare ATmega328P (Nano FQBN)
│   └── shared/                 repo-local Arduino library root
│       ├── SynthCore/src/      platform-pure DSP cores (*Core.h) shared with VCV
│       ├── Mod1Common/         Nano board helpers (pins, ADC, PWM)
│       ├── Mod2Common/         RP2350 board helpers (audio I/O, panel modes)
│       ├── Hagiwo30Common/     OLED + encoder UI for the #30 platform
│       └── Hagiwo30Sequencers/ sequencer engines for the #30 platform
│
├── rack-plugins/               VCV Rack 2 plugin (slug: maddie-synths)
│
├── panels/                     KiCad faceplate projects, grouped by platform
│   ├── hagiwo-mod1/<module>/   MOD1 faceplates      (blanks/ + house-style plates)
│   ├── hagiwo-mod2/<module>/   MOD2 faceplates
│   └── rabid-audio-clk/        rabid.audio CLK faceplate
├── hardware/                   KiCad PCBs and mechanical parts
│   ├── lib/                    shared KiCad symbol + footprint libraries
│   ├── m-power/                eurorack PSU (has its own CLAUDE.md)
│   ├── eurorack-busboard/      bus board
│   ├── maddie-sequencerV2/     sequencer PCB

Naming is mirrored across layers: firmwares/hagiwo-mod2/mod2-vco/mod2-vco.ino, rack-plugins/src/mod2-vco.cpp, panels/hagiwo-mod2/mod2-vco/, and firmwares/shared/SynthCore/src/VcoCore.h are the same module.

Tooling (macOS/linux + Homebrew)

• Install tools:
  • brew install arduino-cli python
• Optional GUI IDE:
  • brew install --cask arduino-ide

Repo-local Arduino CLI config

This repo uses arduino-cli.yaml at the root.

It currently includes RP2040 board index support and works for both:

• Arduino Nano (official core)
• Raspberry Pi Pico (Earle Philhower core)

One-time core install

• Arduino Nano / AVR:
  • arduino-cli core install arduino:avr --config-file ./arduino-cli.yaml
• Raspberry Pi Pico / RP2040:
  • arduino-cli core install rp2040:rp2040 --config-file ./arduino-cli.yaml

One-time library install

Install external libraries used by the hagiwo30-* sketches (the same set CI installs in .github/workflows/_firmware.yml):

• arduino-cli lib install "Encoder" "FastGPIO" "Adafruit GFX Library" "Adafruit SSD1306"

Adafruit SSD1306 pulls Adafruit GFX Library and Adafruit BusIO automatically.

MOD2 Braids / Tides (Mutable Instruments port)

mod2-braids and mod2-tides depend on Mutable Instruments DSP code and two helper libraries that are not vendored in this repo. Install them once into your Arduino libraries folder (default ~/Documents/Arduino/libraries).

1. Library Manager dependencies:

   • arduino-cli lib install "Bounce2" "RPI_PICO_TimerInterrupt"

2. Mutable Instruments libraries from poetaster/arduinoMI (the modules live in separate submodule repos — clone the three we need over HTTPS straight into the libraries folder):

   • git clone https://github.com/poetaster/STMLIB.git ~/Documents/Arduino/libraries/STMLIB
   • git clone https://github.com/poetaster/BRAIDS.git ~/Documents/Arduino/libraries/BRAIDS
   • git clone https://github.com/poetaster/TIDES.git ~/Documents/Arduino/libraries/TIDES

3. TIDES packaging fix. The TIDES library ships its sub-sources as .cc files and amalgamates them in src/tides_all.cpp, so arduino-cli compiles them twice and the link fails with multiple definition errors. BRAIDS already uses .inc for the same trick; make TIDES match by renaming its three sub-sources and updating the includes:

   cd ~/Documents/Arduino/libraries/TIDES/src
   for f in resources poly_slope_generator ramp_extractor; do
     mv "tides2/$f.cc" "tides2/$f.inc"
   done
   sed -i '' -E 's#(tides2/[a-z_]+)\.cc#\1.inc#' tides_all.cpp

PWMAudio.h (used by both) ships with the rp2040:rp2040 core, so no extra install is needed for it. After this, make mod2-braids and make mod2-tides build cleanly.

The same libraries also power the Tiny Tides and Tiny Braids VCV Rack modules (rack-plugins/src/mod2-{tides,braids}.cpp, library bodies compiled once in src/mi-libs.cpp), which are part of the default Rack build. The Rack Makefile finds them via MI_LIB_DIR (default ~/Documents/Arduino/libraries); CI fetches them automatically at the commits pinned in .github/mi-libs.env — to move to newer upstream commits, test locally first, then bump the SHAs there. Building without the libraries stops with a clear #error; to opt out instead, exclude mi-libs.cpp and both module .cpps the usual three-place way (WIP_SOURCES in rack-plugins/Makefile, the modelTinyTides / modelTinyBraids lines in plugin.{hpp,cpp}, and moving their plugin.json entries to wipModules).

Makefile firmware builds

• Build every firmware into dist/<firmware>/:
  • make
• Build for a different board target (MOD1_FQBN covers mod1-*/hagiwo30-* and any other ATmega328P sketch such as rabid-audio-*, MOD2_FQBN covers mod2-*):
  • make MOD2_FQBN=rp2040:rp2040:rpipico
• Build a single firmware target:
  • make mod1-trigger-burst
• List discovered firmware targets:
  • make list
• Flash a firmware (discover ports with make board-list):
  • make upload FW=mod1-euclidean PORT=/dev/ttyACM0
• Remove build output:
  • make clean

The Makefile discovers every sketch folder under firmwares/ that contains a same-named .ino entry file and excludes firmwares/shared/.

Flashing a bare ATmega328P over ISP

make upload drives a serial bootloader, so it needs a board with a USB-serial bridge. The rabid-audio-* ports run on a bare ATmega328P, which has no bootloader to talk to — and on the CLK board no serial either, since its 7-segment lines occupy the whole of PORTD, D0/D1 (RX/TX) included. Those chips are programmed in-circuit through the ICSP header with an ISP programmer:

make fuses-rabid-audio-clk     # ONCE per chip — sets the 16 MHz clock fuses
make isp-rabid-audio-clk       # build + flash, as often as you like

Do not skip the fuses- step on a new chip. A factory ATmega328P runs its internal 8 MHz RC divided by 8, so 1 MHz, while the firmware hard-assumes 16 MHz (sc::kClkTimerHz is 16 MHz / 1024). Flash a virgin part and it runs — just 16x slow, with nothing else to point at the cause. fuses- burns low_fuses=0xFF (full-swing external crystal, no CKDIV8) to match the board's 16 MHz crystal.

The programmer defaults to ISP=usbasp. Override it for other hardware; run arduino-cli board details --fqbn arduino:avr:nano --list-programmers for the valid ids, and note that arduinoasisp also wants a PORT=:

make isp-rabid-audio-clk ISP=usbtinyisp
make isp-rabid-audio-clk ISP=arduinoasisp PORT=/dev/cu.usbmodemXXXX

If the programmer can't see the chip, its SCK is probably too fast for a virgin 1 MHz part — the ISP clock has to stay under a quarter of the target's. On a USBasp, close the slow-SCK jumper (JP3) and run fuses- again; once the crystal fuses are set the part is at 16 MHz and the jumper can come off. make isp-help repeats all of this at the terminal.

VCV Rack plugin builds

The same root Makefile also drives the VCV Rack plugin in rack-plugins/ (which shares the platform-agnostic voice cores in firmwares/shared/SynthCore):

• Build the plugin:
  • make rack
• Build + install into Rack's user plugins folder:
  • make rack-install
• Package a distributable .vcvplugin:
  • make rack-dist
• Remove the plugin build output:
  • make rack-clean
• Build everything (all firmwares + the plugin):
  • make everything
• Build against a non-vendored Rack SDK:
  • make rack RACK_DIR=~/Rack-SDK

The plugin manifest is the canonical plugin.json at the repo root; the rack-plugins/ Makefile syncs a build-time copy into its own folder (which the Rack SDK requires) so the manifest lives in exactly one place. See rack-plugins/README.md and rack-plugins/PORTING.md for details.

CI and releases

.github/workflows/ci.yml runs on every push and pull request and builds only what changed: the Rack plugin when rack-plugins/**, plugin.json, or firmwares/shared/SynthCore/** is touched, and each firmware whose sketch changed (all of them when anything under firmwares/shared/ changes). The actual builds live in two reusable workflows:

• _rack.yml — make rack-dist against a freshly downloaded Rack SDK for Linux, macOS (x64 + arm64), and Windows.
• _firmware.yml — arduino-cli builds grouped by board (.hex for AVR, .uf2 for RP2040). Individual compile failures are tolerated and skipped, mirroring make dist — the repo intentionally carries some WIP sketches that don't compile in a clean checkout (license-gated sample.h, un-vendored Mutable libraries).

release.yml runs on release tags, builds every Rack platform and every firmware, and publishes a GitHub release whose assets are one .vcvplugin per platform plus one flashable binary per firmware. Push a tag to trigger it:

• vYYMM.DD → dated release (e.g. v2608.15)
• vYYMM.DD-next → pre-release / nightly (version stamped with the commit)

Use scripts/release-tag.fish to cut one from today's date rather than typing the tag by hand.

The workflow derives the plugin version from the tag, so the tag is the single source of truth for a release's version. The date lands in the MINOR.REVISION half only — the MAJOR stays 2 because VCV reads it as the Rack generation the plugin was built for, not as our release number, so v2608.15 publishes plugin version 2.2608.15. Stable (non pre-release) tags also force-move a rolling latest tag to the same commit with the same assets, so download URLs like .../releases/download/latest/mod2-vco.uf2 always resolve to the newest stable build. A manual workflow_dispatch run builds everything without publishing, for testing.