Skip to content

Home

Jump to bottom
piggei edited this page Oct 3, 2026 · 10 revisions

WLED Buzzer Usermod is a standalone sound service for WLED on ESP32-family targets. It supports active and passive buzzers, built-in melodies and notification sounds, direct Web/HTTP control, WLED JSON commands, and a small C++ service API that other usermods can call.

Current documentation baseline: v0.2.0 Previous stable release: v0.1.1. v0.2.0 adds an optional compile-time I2S/ES8311 audio backend while preserving the qualified active/passive behavior.

WLED Buzzer Usermod configuration

What it provides

  • Active buzzer output using static GPIO levels.
  • Passive buzzer output using ESP32 LEDC tones.
  • Configurable High/Low trigger level.
  • Passive-buzzer volume slider.
  • Fully non-blocking playback engine.
  • 2 ms esp_timer scheduler with mutex-protected WLED-loop fallback if the timer cannot run.
  • GPIO and LEDC allocation through WLED PinManager.
  • 15 common built-in sounds selected by stable string IDs, shown alphabetically and filtered by backend capability.
  • Three additional Audio-only PCM sounds (imperial_march, trumpet, wakeup) when bundled samples are enabled; they remain absent from Active/Passive-only firmware and menus.
  • Play/Stop test controls in Config -> Usermods -> Buzzer.
  • HTTP/Webhook, WLED JSON, and internal C++ APIs.
  • One-shot, finite-repeat, and infinite-loop playback.
  • Runtime playback and timing diagnostics.
  • Configurable Night Mode with a daily quiet interval.
  • Complete optional weak-link C bridge for independent consumer usermods.
  • Optional compile-time I2S audio backend for supported boards.
  • Initial Waveshare ESP32-S3 RGB Matrix / ES8311 profile with zero firmware overhead when audio support is not compiled.
  • Optional embedded PCM samples for selected Audio (I2S) sounds, with automatic tone fallback for the remaining sound IDs.

Start here

Design principle

The usermod owns buzzer hardware, playback timing and sound definitions. Other components should request a logical sound such as alarm, notification or victory rather than driving a GPIO or LEDC channel themselves.

This separation allows display, gesture, sensor and automation usermods to use sound without duplicating buzzer hardware code.

The v0.2.0 stable release includes a hardware-qualified shared-clock and real-time streaming path on the Waveshare profile: AudioReactive remains I2S0 clock master/RX while Buzzer uses I2S1 as TX slave on the same BCLK/LRCK bus. The qualified 8x256 TX buffering keeps speaker audio and AudioReactive effects smooth, and the expanded sound catalog is included in v0.2.0.

Shared-I2S clock sensing

The hardware-qualified clock-routing path enables BCLK/LRCK input sensing without removing the I2S0 master output routes and verifies physical LRCK activity before starting I2S1 slave TX. See Shared I2S + AudioReactive for details.

This is intentionally a Buzzer-side change only. AudioReactive/I2S0 remains the owner of RX and of the physical MCLK/BCLK/LRCK outputs.

WLED Buzzer Usermod · Documentation v0.2.0 · https://github.com/piggei/wled-usermod-buzzer

WLED Buzzer Usermod

Clone this wiki locally