Projects / Ultrasonic theremin with real tone

Ultrasonic theremin with real tone

Intermediate3 hGuided buildReviewed

Build it step by step

0 of 7 done
  1. ESP32

    Test the amplifier

    Play a fixed 440 Hz tone.

  2. ESP32VL53L0X61 cm

    Test the distance sensors

    Print both readings.

  3. ESP32VL53L0X61 cm

    Map distance to pitch

    Use the exponential curve.

  4. ESP32VL53L0X61 cm

    Map distance to volume

    Closer is louder.

  5. ESP32

    Smooth the changes

    Glide to avoid clicks.

  6. ESP32

    Add the snap button

    Quantise to a major scale.

  7. ESP32

    Mount it

    Fix the sensors on a board a hand-width apart.

In short

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

Tick what you already own. It saves to My Garage, so “Build with what I have” knows.

Wiring

FromToWhy
HC-SR04 VCC and GNDESP32 5V (VIN) and GNDSensor power
HC-SR04 TRIGESP32 GPIO5Trigger
HC-SR04 ECHO1 kΩ resistor to GPIO18, 4.7 kΩ from GPIO18 to GNDDivider brings 5 V down to about 4 V (better: 2 kΩ and 3.3 kΩ)
VL53L0X VIN and GNDESP32 3V3 and GNDSensor power
VL53L0X SDA and SCLESP32 GPIO21 and GPIO22I2C
MAX98357A VIN and GNDESP32 5V (VIN) and GNDAmplifier power
MAX98357A BCLKESP32 GPIO26I2S bit clock
MAX98357A LRCESP32 GPIO25I2S word select
MAX98357A DINESP32 GPIO27I2S data
SpeakerMAX98357A + and −Sound
ButtonESP32 GPIO4 and GNDSnap 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.

CheckExpected
Hand over the pitch sensorTone rises as the hand moves away
Hand over the volume sensorLouder as it gets closer
Snap onNotes land on scale steps
Hand removedSound 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 →

Ask Lark AI

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.