Skip to main content

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.

Fixed pin

Wired to GPIO12, LEDC with 10-bit resolution and 50% duty; pitch is set by frequency.

Frozen into the firmware

Just import beep — no files to copy onto the SD card.

Non-blocking

tone() returns immediately; a timer handles the silence, so your main loop is free.

Pin and hardware parameters​

ItemValue
PinGPIO12 (fixed, not configurable)
PWM controllerLEDC low-speed mode
Timer / channelLEDC_TIMER_1 / LEDC_CHANNEL_1
Duty resolution10-bit (0–1023), fixed at 512 (50%) while sounding
Default frequency after init2000 Hz
How auto-stop worksA 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_initialized flag 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)
ArgumentTypeDescription
freqintSound frequency in Hz; higher value means higher pitch
duration_msintDuration 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:

ScenarioActual behaviour
tone(f, d) and nothing elseFrequency f sounds until millisecond d, then the timer disables the PWM and it goes quiet
tone(f2, d2) while still soundingSwitches to f2 immediately and restarts the countdown from d2
stop() while still soundingGoes quiet at once; the scheduled timer remains and disables the output again when it expires
tone() after stop(), before the timer expiresSounds 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 stringRaises TypeError

Common pitfalls​

  1. freq is in Hz, not kHz. For 2kHz you must write 2000; the official light-painting app's click sound uses 7000, i.e. 7kHz.
  2. 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 a time.sleep_ms() between them.
  3. Use duration_ms for long tones instead of busy-waiting. tone() does not block, so let the main loop continue and leave the silence to the timer.
  4. 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.
  5. 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.
  6. 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​

SymptomCause / fix
No sound at allYou only called init(), which prepares the hardware without sounding → use tone()
No sound at allfreq was written in kHz (2 means 2 Hz, inaudible) → write 2000
No sound at allduration_ms is too small (e.g. 0) → use at least a few tens of milliseconds
TypeError raisedA float or a string was passed → both arguments must be integers
Sound never stopsduration_ms was far too long → silence it with beep.stop()
Only the last note is audibleConsecutive tone() calls had no gap, so each note replaced the previous one → add time.sleep_ms() between them
Wrong or unstable pitchFrequency is outside what LEDC can produce at this resolution → keep beeps in the 2000–8000 Hz range
Still sounding after the app exitsNo 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/.

Agent entry (coming soon)

The entry link will go here. Once it is live, one click takes you straight to describing the app you want.