MidiTheremin

TinyGo firmware that turns a GaudiLabs OpenTheremin V3 shield into a USB MIDI controller. Built for an Adafruit Metro M4 Express AirLift Lite (ATSAMD51J19), and portable to other Arduino UNO form factor boards.

The shield's analogue front end is used as designed: two antenna oscillators heterodyned against a crystal reference, auto-tuned through the on-board MCP4922. The two difference frequencies become MIDI note, pitch bend and controller messages. No audio is synthesised.

Copyright (c) Mike Hughes <mike AT mikehughes DOT info> 2026

---

Shield modification

The OpenTheremin V3 is a 5 V design. The SAMD51 is not 5 V tolerant, so on an unmodified shield the two beat signals (D2, D8) and the four pot wipers (A0–A3) all exceed what the MCU may see.

Every active part on the shield is rated well below 3.3 V. The counters and flip-flop are 74HC parts, the oscillator inverter already runs from 3V3, and both DACs take 2.7–5.5 V. Running the whole shield from 3.3 V solves these problems. The fix consists of bending one pin and soldering one short jumper wire.

Do these steps in order! Soldering the jumper wire before disconnecting the 5 V pin will short the board's 5 V rail to its 3.3 V rail and back-feed the regulator. Do step 1 first, and verify it with a multimeter.

1. With the shield off the board, find the pin on the shield's power header that lines up with the 5V socket. Bend it outwards about 30° so it sits beside the socket instead of entering it.
2. Seat the shield with USB unplugged and measure resistance between 5V and 3V3. It must read open. A few ohms means the pin is still making contact.
3. On the top of the shield, solder a short wire between the 5V and 3V3 header pads. They are adjacent pins, so use a wire rather than a solder bridge.
4. Make sure useExternalAREF = false in config.go.

Power up and check the serial console. Two resting beat frequencies near the target mean the references are running:

autotune pitch: zero beat near DAC 2176
autotune pitch: DAC 2166, resting beat 707 Hz
autotune volume: zero beat near DAC 2304
autotune volume: DAC 2269, resting beat 677 Hz

Building

Requires TinyGo 0.42 or later and a Go toolchain the TinyGo release accepts.

cd src/theremin
tinygo build -target=metro-m4-airlift -size=short -o firmware.uf2 .

Flash by putting the device into BOOTSEL or FLASH mode and copying firmware.uf2 onto it, or:

tinygo flash -target=metro-m4-airlift .

Wrapper scripts do both. On Linux and macOS:

./build.sh             # writes firmware.uf2
./build.sh --flash     # builds and flashes
./build.sh --offline   # GOPROXY=off, for when the module proxy stalls
./build.sh --help      # all options

On Windows:

.\build.ps1            # writes firmware.uf2
.\build.ps1 -Flash     # builds and flashes
.\build.ps1 -Offline   # GOPROXY=off, for when the module proxy stalls

Both take --target / -Target to build for a different board.

The device enumerates as a composite CDC + MIDI device, so one cable carries the MIDI port and a serial console. Set debugSerial = false in config.go to silence the console.

---

Using it

Button

Knobs

Numbered in reading order on the board: P1 top-left, P2 top-right, P3 bottom-left, P4 bottom-right.

LEDs

Amber is D4 on A5, red is D3 on A4. Swap pinLEDRed and pinLEDAmber in config.go if they come out reversed.

Calibration

Hold the button for eight seconds. The sequence takes about fifteen seconds and drives itself from the LEDs:

1. Both LEDs dark, 1.5 s - release the button, hands away.
2. LEDs alternating - oscillator auto-tune. Keep your hands off.
3. Both LEDs solid, 2 s - bring a hand close to each antenna, as near as you would actually play. Do not touch them: contact gives a beat tens of times the resting one and skews the captured range.
4. Amber blinking, 3 s - sweep both hands out to your furthest playing point.
5. Amber slow blink - saved. Fast alternation means nothing moved and the previous calibration was kept.

Both extremes of both beat periods are recorded across the whole window, so the sweep can go in either direction. Results are stored in internal flash and survive a power cycle. Auto-tune runs again on every power-up, but a stored tuning still close to target is accepted as-is, so a warm start takes under a second.

Before the first calibration the firmware falls back to a synthetic range, so the device is playable immediately.

---

How it works

The 74HC74 samples each antenna oscillator with the crystal reference, so F_PITCH and F_VOL are square waves at the difference of the two frequencies: a few hundred Hz with the hands away, rising as a hand approaches. A pin interrupt timestamps every rising edge against a free-running cycle counter, and the mean period across the last few edges is smoothed with an IIR filter.

Pitch position is linear in the period difference between the far point and now. Frequency then rises linearly with that position across playingRangeOctaves, which keeps a real theremin's crowding of the upper register. The note number is the base-2 log of that:

note = transpose + 12 · log₂(1 + x · (2^octaves − 1))

The continuous note is shaped by knob 2, then split into a MIDI note plus pitch bend. The note is held for as long as the bend can cover the deviation, which stops a smooth setting retriggering on every semitone; at bend = 0 the hold window collapses to half a semitone so every step becomes a fresh note. Note changes send the new note before releasing the old one, for legato on a monophonic synth.

The firmware transmits RPN 0 at start-up requesting bendRangeSemitones. Synths that ignore RPN need their bend range set to match by hand.

The volume antenna drives a controller continuously and gates note on/off, with hysteresis around the trigger point. Note-on velocity comes from hand position plus how fast the hand left the antenna.

---

Porting to another UNO form factor board

Most of the firmware is board-independent. machine.D2, machine.A0 and so on resolve to whichever MCU pin a board places at that header position, so the pin map in config.go needs no change as long as the target defines those names.

These are the parts that do:

Everything else, dac.go, autotune.go, calibrate.go, voice.go, midiout.go, ui.go, debug.go, uses only the portable machine API.

Two requirements the target must be met: TinyGo USB MIDI support, and two pins that can take edge interrupts (D2 and D8 in the UNO footprint).

---

Configuration

Everything adjustable is in config.go:

---

Source layout