Ultrasonic theremin with real tone
Build it step by step
0 of 7 doneTest the amplifier
Play a fixed 440 Hz tone.
Test the distance sensors
Print both readings.
Map distance to pitch
Use the exponential curve.
Map distance to volume
Closer is louder.
Smooth the changes
Glide to avoid clicks.
Add the snap button
Quantise to a major scale.
Mount it
Fix the sensors on a board a hand-width apart.
How do you build an ultrasonic theremin with real tone?
An ultrasonic sensor sets the pitch and a ToF sensor sets the volume, played through an I2S amplifier for clean sound. You need ESP32 DevKit V1, HC-SR04 Ultrasonic Sensor, VL53L0X time-of-flight distance sensor, MAX98357A I2S amplifier breakout, Speaker 4 Ω 3 W, Breadboard 830 Tie Points, Jumper wires male to male (40 pcs, 20 cm), Resistor 1 kΩ, Resistor 4.7 kΩ and Tactile push button 6 mm. It takes 7 steps and about 180 minutes.
- Level
- Intermediate
- Time
- About 180 min
- Parts
- 10
Parts list
- Development BoardsBuyESP32 DevKit V1 × 1
- SensorsBuy
- SensorsBuy
- AudioBuy
- Motors & ActuatorsBuySpeaker 4 Ω 3 W × 1
- PrototypingBuy
- PrototypingBuy
- PassivesBuyResistor 1 kΩ × 1
- PassivesBuyResistor 4.7 kΩ × 1
- SwitchesBuy
Tick what you already own. It saves to My Garage, so “Build with what I have” knows.
Wiring
| From | To | Why |
|---|---|---|
| HC-SR04 VCC and GND | ESP32 5V (VIN) and GND | Sensor power |
| HC-SR04 TRIG | ESP32 GPIO5 | Trigger |
| HC-SR04 ECHO | 1 kΩ resistor to GPIO18, 4.7 kΩ from GPIO18 to GND | Divider brings 5 V down to about 4 V (better: 2 kΩ and 3.3 kΩ) |
| VL53L0X VIN and GND | ESP32 3V3 and GND | Sensor power |
| VL53L0X SDA and SCL | ESP32 GPIO21 and GPIO22 | I2C |
| MAX98357A VIN and GND | ESP32 5V (VIN) and GND | Amplifier power |
| MAX98357A BCLK | ESP32 GPIO26 | I2S bit clock |
| MAX98357A LRC | ESP32 GPIO25 | I2S word select |
| MAX98357A DIN | ESP32 GPIO27 | I2S data |
| Speaker | MAX98357A + and − | Sound |
| Button | ESP32 GPIO4 and GND | Snap to notes |
Code
The HC-SR04's echo pin outputs 5 V, which the ESP32's pins do not tolerate, so a divider is used; a 2 kΩ and 3.3 kΩ pair is better than the one in the wiring table if you have them. The sketch makes a sine wave in software and sends it over I2S to the MAX98357A, which makes a clean tone with no hiss. Pitch follows distance on an exponential curve so equal hand movements give equal musical steps. The volume sensor reads from 3 cm to 30 cm. Keep the volume modest; the amplifier is loud and the supply may sag from USB. Sounds repeat in short bursts if the sensor loses your hand, so stand still in front of both. Arduino IDE with the ESP32 boards package, board "ESP32 Dev Module".
Runs on a virtual ESP32 Dev Module in your browser, with sliders for the sensors. Happy with it? Verify and upload to your real board from the same page (Chrome or Edge on a computer).
// Ultrasonic theremin: HC-SR04 sets pitch, VL53L0X sets volume. Library: Adafruit VL53L0X.
// Uses the legacy I2S driver of ESP32 boards package 2.x (it still builds on 3.x with warnings).
#include <driver/i2s.h>
#include <Wire.h>
#include <Adafruit_VL53L0X.h>
#define TRIG 5
#define ECHO 18
#define SNAP_BTN 4
const int SR = 22050;
const float SCALE[7] = {0, 2, 4, 5, 7, 9, 11}; // major scale in semitones
Adafruit_VL53L0X tof;
float freq = 440, vol = 0.0, phase = 0;
bool snap = false;
unsigned long lastRead = 0, lastBtn = 0;
float noteSnap(float f) {
float semis = 12.0 * log(f / 261.63) / log(2.0);
int oct = floor(semis / 12.0), best = 0; float bestD = 99;
for (int i = 0; i < 7; i++) { float d = fabs(semis - (oct * 12 + SCALE[i])); if (d < bestD) { bestD = d; best = oct * 12 + SCALE[i]; } }
return 261.63 * pow(2.0, best / 12.0);
}
void setup() {
pinMode(TRIG, OUTPUT); pinMode(ECHO, INPUT); pinMode(SNAP_BTN, INPUT_PULLUP);
Wire.begin(21, 22);
tof.begin();
i2s_config_t cfg = {
.mode = (i2s_mode_t)(I2S_MODE_MASTER | I2S_MODE_TX), .sample_rate = SR,
.bits_per_sample = I2S_BITS_PER_SAMPLE_16BIT, .channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT,
.communication_format = I2S_COMM_FORMAT_STAND_I2S, .intr_alloc_flags = 0,
.dma_buf_count = 4, .dma_buf_len = 128, .use_apll = false, .tx_desc_auto_clear = true, .fixed_mclk = 0 };
i2s_pin_config_t pins = { .bck_io_num = 26, .ws_io_num = 25, .data_out_num = 27, .data_in_num = I2S_PIN_NO_CHANGE };
i2s_driver_install(I2S_NUM_0, &cfg, 0, NULL);
i2s_set_pin(I2S_NUM_0, &pins);
}
float readCm() {
digitalWrite(TRIG, LOW); delayMicroseconds(2);
digitalWrite(TRIG, HIGH); delayMicroseconds(10); digitalWrite(TRIG, LOW);
long us = pulseIn(ECHO, HIGH, 5000); // up to about 85 cm
return us ? us / 58.0 : -1;
}
void loop() {
if (!digitalRead(SNAP_BTN) && millis() - lastBtn > 300) { snap = !snap; lastBtn = millis(); }
if (millis() - lastRead > 40) { // read the sensors about 25 times a second
lastRead = millis();
float cm = readCm();
if (cm > 0) {
float target = 200.0 * pow(2.0, constrain(cm, 5, 60) / 60.0 * 3.0); // 200 Hz to 1600 Hz on a smooth curve
freq += (target - freq) * 0.3; // glide to avoid clicks
}
VL53L0X_RangingMeasurementData_t m; tof.rangingTest(&m, false);
float v = (m.RangeStatus != 4) ? constrain(m.RangeMilliMeter, 30, 300) : 300;
vol += ((300 - v) / 270.0 * 0.5 - vol) * 0.4; // closer hand = louder, maximum half scale
}
float f = snap ? noteSnap(freq) : freq;
int16_t buf[256];
for (int i = 0; i < 128; i++) {
int16_t s = (int16_t)(sin(phase) * vol * 20000);
buf[2 * i] = s; buf[2 * i + 1] = s;
phase += 2 * PI * f / SR; if (phase > 2 * PI) phase -= 2 * PI;
}
size_t written; i2s_write(I2S_NUM_0, buf, sizeof(buf), &written, portMAX_DELAY);
}Test checklist
What you should see at each check. If a reading is far off, stop and use the troubleshooting list.
| Check | Expected |
|---|---|
| Hand over the pitch sensor | Tone rises as the hand moves away |
| Hand over the volume sensor | Louder as it gets closer |
| Snap on | Notes land on scale steps |
| Hand removed | Sound fades to silence |
If it does not work
No sound
Check BCLK, LRC and DIN and the amplifier power.
Pitch jumps
Check the echo divider and smooth more.
Clicks
Lower the smoothing rate or raise the buffer count.
Sketch does not compile
Use the ESP32 boards package 2.0.x.
Still stuck? Find the fault step by step with your multimeter →
Common questions
What parts do I need for the ultrasonic theremin with real tone?
ESP32 DevKit V1, HC-SR04 Ultrasonic Sensor, VL53L0X time-of-flight distance sensor, MAX98357A I2S amplifier breakout, Speaker 4 Ω 3 W, Breadboard 830 Tie Points, Jumper wires male to male (40 pcs, 20 cm), Resistor 1 kΩ, Resistor 4.7 kΩ and Tactile push button 6 mm.
How long does the ultrasonic theremin with real tone take to build?
About 180 minutes for a intermediate maker, in 7 steps.
How do I know the ultrasonic theremin with real tone works?
Hand over the pitch sensor: Tone rises as the hand moves away. Hand over the volume sensor: Louder as it gets closer. Snap on: Notes land on scale steps.
No sound: what should I check?
Check BCLK, LRC and DIN and the amplifier power.
Pitch jumps: what should I check?
Check the echo divider and smooth more.
Clicks: what should I check?
Lower the smoothing rate or raise the buffer count.
Sketch does not compile: what should I check?
Use the ESP32 boards package 2.0.x.
