Installation

The project is designed as an out-of-tree WLED usermod. The source repository can live next to the WLED repository and be referenced by PlatformIO.

Repository:

https://github.com/piggei/wled-usermod-buzzer

Recommended directory layout

Example:

~/repo/
├── wled_17_dev/
└── wled-usermod-buzzer/

The release archives intentionally use the fixed root directory:

wled-usermod-buzzer/

so update/build scripts do not need version-specific paths.

PlatformIO integration

Add the usermod to the WLED build environment through custom_usermods, for example:

custom_usermods =
  ${env:esp32dev.custom_usermods}
  symlink:///absolute/path/to/wled-usermod-buzzer

When the repositories are adjacent, a relative path can also be used if it resolves correctly in your environment.

Compile WLED normally for the intended ESP32-family target.

First boot

After flashing the firmware:

1. Open Config -> Usermods.
2. Find Buzzer.
3. Enable it.
4. Select the GPIO.
5. Select Active or Passive.
6. Set the trigger level.
7. For a passive buzzer, set the volume.
8. Save the configuration.
9. Return to the page and use Sound / Play / Stop to test the hardware.

See Configuration for the meaning of each option.

Hardware notes

• v0.1.1 remains the stable active/passive baseline.
• v0.2.0 adds optional audio support only when explicitly enabled at compile time.
• Passive buzzers require a free LEDC resource in addition to the GPIO.
• GPIO and LEDC resources are allocated through WLED PinManager.
• If the engine mutex cannot be created, playback is disabled rather than using an unsafe asynchronous fallback.
• Do not configure a GPIO already owned by another WLED function or usermod.

Optional Waveshare I2S audio build

The v0.2.0 audio backend is intentionally excluded from normal builds. For the Waveshare ESP32-S3 RGB Matrix profile, add:

build_flags =
  ${env.build_flags}
  -D WLED_BUZZER_AUDIO_WAVESHARE_S3_MATRIX

This board-profile flag automatically enables the generic audio backend and the bundled PCM samples. Add -D WLED_BUZZER_DISABLE_AUDIO_SAMPLES if you want the I2S/ES8311 backend without the embedded sample data. Without the board-profile flag, no ES8311/I2S implementation or sample data is compiled into the firmware and the Buzzer Type list remains Active/Passive only.

See I2S audio backend before enabling the profile.