Buzzer (beep)
beep is the buzzer module built into the Beetle S1 firmware. It uses ESP32 hardware PWM (LEDC) to generate a square wave, so one line of code produces a tone of a given frequency for a given duration and then goes quiet automatically.
Wired to GPIO12, LEDC with 10-bit resolution and 50% duty; pitch is set by frequency.
Just import beep — no files to copy onto the SD card.
tone() returns immediately; a timer handles the silence, so your main loop is free.
Pin and hardware parameters
| Item | Value |
|---|---|
| Pin | GPIO12 (fixed, not configurable) |
| PWM controller | LEDC low-speed mode |
| Timer / channel | LEDC_TIMER_1 / LEDC_CHANNEL_1 |
| Duty resolution | 10-bit (0–1023), fixed at 512 (50%) while sounding |
| Default frequency after init | 2000 Hz |
| How auto-stop works | A one-shot esp_timer disables the PWM when it expires |
The buzzer is a single-tone source: only one frequency can sound at a time. Chords or multiple simultaneous tracks are impossible in hardware — split them into short notes played one after another.
Quick start
import beep
beep.tone(2000, 300) # 2000Hz for 300 milliseconds, then silence
What you'll see (and hear): the buzzer gives one short beep and stops after roughly 0.3 seconds. The code does not block — tone() sets the frequency and the timer and returns, so the rest of your program keeps running.
You do not need to call beep.init() manually: tone() initializes the module itself if needed.
API reference
Initialise beep.init()
beep.init()
No arguments, no return value. It configures the LEDC timer and channel, puts the pin in the silent state, and creates the esp_timer used for auto-stop.
- May be called repeatedly: an internal
beep_initializedflag makes it return immediately when already initialised. - Usually unnecessary:
tone()initialises automatically. Call it explicitly only when you want the hardware ready before the first sound.
Play a tone beep.tone()
beep.tone(freq, duration_ms)
| Argument | Type | Description |
|---|---|---|
freq | int | Sound frequency in Hz; higher value means higher pitch |
duration_ms | int | Duration in milliseconds, after which the buzzer goes quiet |
No return value. The behaviours you must know:
- Non-blocking: it only sets the PWM frequency, duty and timer, then returns. Your main loop is not occupied.
- Initialises automatically when needed, so
init()is optional. - Repeated calls replace, they do not queue: calling
tone()while a sound is playing switches to the new frequency at once and restarts the countdown. The previous tone never finishes. - Duty is fixed at 50% (
512 / 1024) while sounding, so the timbre is a plain square wave with no volume control. - Both arguments must be integers (floats or strings raise
TypeError). The frequency is not validated — an invalid value raises no error, it simply stays silent or sounds wrong.
Stop beep.stop()
beep.stop()
Disables the PWM output immediately, regardless of whether the timer is still counting down. No arguments, no return value; calling it before initialisation is a safe no-op.
Note that it only silences the buzzer and does not cancel an already scheduled auto-stop timer. Since that timer merely disables the output again when it expires, this has no side effect.
Release beep.deinit()
beep.deinit()
Stops the PWM, deletes the esp_timer, and clears the initialised flag. No arguments, no return value.
Calling tone() afterwards re-initialises the module automatically, so you do not need beep.init() after deinit().
Timing and behaviour
The duration passed to tone() means "auto-silence", not "block and wait". Here is what actually happens in each combination:
| Scenario | Actual behaviour |
|---|---|
tone(f, d) and nothing else | Frequency f sounds until millisecond d, then the timer disables the PWM and it goes quiet |
tone(f2, d2) while still sounding | Switches to f2 immediately and restarts the countdown from d2 |
stop() while still sounding | Goes quiet at once; the scheduled timer remains and disables the output again when it expires |
tone() after stop(), before the timer expires | Sounds normally; the timer is reset, so the new tone is not cut short |
tone() after deinit() | Re-initialises automatically and sounds normally |
| Passing a float or a string | Raises TypeError |
Common pitfalls
freqis in Hz, not kHz. For 2kHz you must write2000; the official light-painting app's click sound uses7000, i.e. 7kHz.- You must add gaps yourself when playing a melody. Because
tone()replaces,tone(523, 200); tone(659, 200)only ever produces the second note. Put atime.sleep_ms()between them. - Use
duration_msfor long tones instead of busy-waiting.tone()does not block, so let the main loop continue and leave the silence to the timer. - Keep the frequency within the hardware and hearing range. With 10-bit resolution the LEDC output tops out around 78 kHz (80 MHz ÷ 1024), and very low frequencies are inaudible. 2000–8000 Hz is the useful range for beeps.
- There is only one buzzer system-wide. The module keeps module-level global state, so if another part of your code is sounding and you call
deinit(), you silence it too. - Do not play a whole melody inside a button callback. Callbacks run in the scheduler context, and sleeping through a melody stalls it. Emit single short beeps in callbacks and move long sequences to the main loop or a thread.
More recipes
Button click sound
Short operations such as beeping are safe inside a callback. The official light-painting app uses beep.tone(7000, 50) — 7000Hz for 50 milliseconds:
import beep
from button import Button
buttons = Button()
def beep_click():
beep.tone(7000, 50)
buttons.register_callback('up', 'short', beep_click)
buttons.register_callback('down', 'short', beep_click)
buttons.register_callback('center', 'short', beep_click)
Play a melody
tone() does not block, so as long as you add a gap between notes you can play a sequence:
import beep
import time
# C major scale starting from middle C (Hz)
NOTES = [262, 294, 330, 349, 392, 440, 494]
def play(notes, duration=200, gap=30):
for f in notes:
beep.tone(f, duration)
time.sleep_ms(duration + gap) # the gap is required, or each note replaces the last
play([262, 330, 392, 523]) # do mi so high-do
play(list(reversed(NOTES))) # and back down the scale
Cutting a sound short
import beep
import time
beep.tone(1000, 5000) # about to sound for 5 seconds
time.sleep_ms(300)
beep.stop() # silence it 300ms in instead of waiting
Warning and error sounds
import beep
import time
def warn():
beep.tone(2000, 300) # the launcher uses exactly these values before auto-sleep
def error():
for _ in range(3):
beep.tone(800, 150)
time.sleep_ms(200)
Complete example
Beetle S1 apps live on the SD card under /sd/apps/<app-directory>/, with boot.py as the entry point. The launcher releases its own buttons before entering an app, so an app can safely create its own Button (again, only one).
Drop the following into /sd/apps/my-beep-app/boot.py: a three-note startup chirp, up / down short presses to audition different frequencies, a click feedback on a centre short press, and a centre long press to quit.
from button import Button
import beep
import time
TONES = [1000, 2000, 4000, 7000] # frequencies to audition (Hz)
index = 0
running = True
buttons = Button()
def on_up():
global index
index = (index - 1) % len(TONES)
beep.tone(TONES[index], 300)
def on_down():
global index
index = (index + 1) % len(TONES)
beep.tone(TONES[index], 300)
def on_center_short():
beep.tone(7000, 50) # click feedback
def on_center_long():
global running
running = False
buttons.register_callback('up', 'short', on_up)
buttons.register_callback('down', 'short', on_down)
buttons.register_callback('center', 'short', on_center_short)
buttons.register_callback('center', 'long', on_center_long)
# Startup chirp: three rising notes with a gap between them
for f in (1000, 2000, 4000):
beep.tone(f, 120)
time.sleep_ms(180)
while running:
time.sleep(0.1) # light-effect rendering and other work goes here
beep.stop() # silence before leaving, to avoid a trailing note
beep.deinit()
buttons.deinit()
Related modules: USB Serial Control (CDC) · Button Control (button) · LED Control (WS2812) · Display (ST7789)
Troubleshooting
| Symptom | Cause / fix |
|---|---|
| No sound at all | You only called init(), which prepares the hardware without sounding → use tone() |
| No sound at all | freq was written in kHz (2 means 2 Hz, inaudible) → write 2000 |
| No sound at all | duration_ms is too small (e.g. 0) → use at least a few tens of milliseconds |
TypeError raised | A float or a string was passed → both arguments must be integers |
| Sound never stops | duration_ms was far too long → silence it with beep.stop() |
| Only the last note is audible | Consecutive tone() calls had no gap, so each note replaced the previous one → add time.sleep_ms() between them |
| Wrong or unstable pitch | Frequency is outside what LEDC can produce at this resolution → keep beeps in the 2000–8000 Hz range |
| Still sounding after the app exits | No silence before exit → call stop() or deinit() before leaving |
AI usage (coming soon)
Soon you will not have to work out frequencies or insert gaps by hand: describe the sound you want in plain language and the Agent will follow the API in this page to generate a complete program that runs on the Beetle S1.
For example, just tell it:
Beep once when the menu selection changes, play three low beeps when an action fails, and play a short rising chirp on startup.
It will combine beep and Button into a working program and place it on the SD card under /sd/apps/.
The entry link will go here. Once it is live, one click takes you straight to describing the app you want.