In this project, we will build a small theremin-style musical instrument using the Kypruino board, an HC-SR04 ultrasonic sensor, and a potentiometer. The instrument plays sound through the Kypruino’s on-board buzzer, allowing the user to control pitch by moving a hand in front of the sensor and adjust a vibrato effect using the potentiometer.
This guide is written so that beginners can follow along. You do not need advanced electronics experience, but you should be comfortable connecting simple modules to a microcontroller, uploading an Arduino sketch, and assembling a basic 3D-printed enclosure.
What the project does
This mini theremin turns hand movement into sound. Instead of pressing buttons, the player controls the note by changing the distance between their hand and the ultrasonic sensor.
- Pitch control: the ultrasonic sensor measures hand distance and maps it to musical notes
- Quantized notes: the project snaps the pitch to chromatic notes from C4 to C6, making it easier to play recognisable tones
- Vibrato control: the potentiometer adjusts the depth of a vibrato effect
- Sound output: the Kypruino’s built-in buzzer plays the selected note
- Compact design: the electronics fit inside a small spherical 3D-printed enclosure
The result is a simple and playful STEM project that combines sensing, sound generation, and enclosure design.
Components needed
For this build, you will need:
- 1 × Kypruino board
- 1 × HC-SR04 ultrasonic distance sensor
- 1 × Potentiometer
- Jumper wires
- USB-C cable for programming and power
- 3D-printed spherical enclosure
How the controls work
Ultrasonic sensor
The HC-SR04 ultrasonic sensor measures the distance between the device and the user’s hand. In this project, that distance is used to choose a note from a chromatic scale.
The code is configured to work in a distance range of approximately 5 cm to 50 cm. If the hand is outside this range, the instrument stops playing.
In the current version of the code, moving the hand farther away gives higher notes. If you want the opposite behaviour, this can be changed in the code.
Potentiometer
The potentiometer controls the depth of the vibrato effect. Vibrato is a small repeating variation in pitch that gives the sound a more expressive and musical feel.
At very low potentiometer values, the vibrato is disabled. As the potentiometer is turned further, the vibrato becomes stronger.
Built-in buzzer
The sound is produced by the on-board buzzer of the Kypruino. The code uses the Arduino tone() function to play the selected frequency.
Wiring the project
Connect the modules to the Kypruino as shown below.
HC-SR04 ultrasonic sensor
| HC-SR04 Pin | Connects to Kypruino |
|---|---|
| VCC | 5V |
| GND | GND |
| TRIG | D4 |
| ECHO | D5 |
Potentiometer
| Potentiometer Pin | Connects to Kypruino |
|---|---|
| S | A0 |
| V | 5V |
| G | GND |
Built-in buzzer
| Component | Kypruino Pin |
|---|---|
| On-board buzzer | D9 |
Important: The buzzer is already built into the Kypruino board, so no external speaker or buzzer module is needed for this version of the project.
Wiring overview showing how the potentiometer and ultrasonic sensor connect to the Kypruino.
Installing the Arduino libraries
This project does not require any additional external libraries. The sketch uses standard Arduino functions and the built-in math.h support.
As long as your Arduino IDE is already set up for the Kypruino board, you can upload the sketch directly.
Uploading the code
Connect the Kypruino to your computer using a USB-C cable. Open the Arduino IDE, select the correct board and port, then upload the theremin sketch.
The code already includes all of the main behaviour:
- distance measurement from the HC-SR04
- mapping distance to musical notes
- note stability filtering
- potentiometer-controlled vibrato
- sound generation through the on-board buzzer
If you want to change the playing direction, look for this line in the code:
const bool CLOSE_IS_HIGH = false;In the current version, this means farther hand gives higher notes. If you change it to:
const bool CLOSE_IS_HIGH = true;then closer hand will give higher notes instead.
You can also adjust the playable range by changing:
const float MIN_DISTANCE_CM = 5.0;
const float MAX_DISTANCE_CM = 50.0;How the sound logic works
1. Distance becomes pitch
The ultrasonic sensor reads the hand distance and converts it into a position within the allowed range. That position is then mapped onto a set of musical notes.
In this project, the notes form a chromatic scale from C4 to C6. This means the player gets discrete musical notes instead of a completely continuous pitch sweep.
2. Notes are stabilised
Ultrasonic readings can vary slightly from one moment to the next. To prevent the sound from jumping around too quickly, the code waits until the same newly detected note has been seen multiple times before changing to it.
This makes the instrument easier to control and more pleasant to play.
3. Potentiometer adds vibrato
The potentiometer does not change the main note directly. Instead, it adjusts how much the note oscillates up and down around its base value.
At low settings, there is no vibrato. At higher settings, the pitch moves more noticeably, creating a stronger effect.
4. Invalid range silences the instrument
If the user’s hand is too close, too far, or the sensor cannot measure a valid distance, the code stops the buzzer. This gives the instrument a clear playable zone.
Understanding the note range
The project uses the following note span:
C4 to C6This gives a wide enough range to make the instrument interesting, while still keeping it easy to test and demonstrate in a classroom or workshop setting.
Because the project uses chromatic quantisation, every valid hand position snaps to a nearby musical note. This makes it easier for beginners to hear clear pitch steps.
Assembling the spherical enclosure
Once the circuit is working on your desk, you can install the electronics into the 3D-printed spherical enclosure.
- Mount the ultrasonic sensor behind the two front openings so it can face outward
- Fit the potentiometer into its opening or slot so the control can be adjusted from outside
- Place the Kypruino board inside the enclosure using the internal supports
- Route the wires neatly so they do not block the sensor openings
- Close the enclosure securely once everything is fitted
Important: Test the circuit fully before final assembly. It is much easier to debug the sensor and potentiometer while the electronics are still accessible.
What students can learn
This project introduces several useful STEM concepts:
- Ultrasonic distance measurement
- Analog input reading with a potentiometer
- Mapping sensor values to sound output
- Frequency generation using the Arduino tone() function
- Vibrato as a modulation effect
- Signal smoothing and stability filtering
- Basic music technology concepts
- 3D design for electronics enclosures
- Interaction design using gesture-based input
It also shows an important engineering idea: raw sensor data often needs filtering and interpretation before it becomes useful.
Possible extensions
- Add a second potentiometer for note range
- Use a speaker module instead of the on-board buzzer for richer sound and more effects
- Store different sound profiles or scales in the code
- Create alternative enclosure designs with different shapes or colours
Final thoughts
This Kypruino mini theremin is a fun and compact project that combines electronics, sound, and 3D design into a single interactive build. With just an ultrasonic sensor, a potentiometer, and the Kypruino board, it creates a musical instrument that feels playful and surprisingly expressive.
The project is simple enough for beginners to follow, but it also introduces valuable ideas such as signal processing, note mapping, and modulation. It is a great example of how a few components and a thoughtful enclosure can turn a basic microcontroller project into something creative and memorable.