Configuration - piggei/wled-usermod-buzzer GitHub Wiki

Open Config -> Usermods -> Buzzer.

The page exposes the established controls Enabled:, GPIO Pin:, Buzzer Type:, Trigger level:, Volume:, and Sound:, plus Night mode:. In standard builds the types are Active/Passive. When the optional v0.2.0 audio profile is compiled, Audio (I2S) appears as a third type. Volume is hidden only for Active; From: and To: are shown only while Night Mode is enabled.

WLED Buzzer Usermod configuration

The screenshot shows the standard active/passive build. Audio (I2S) is added to the same Buzzer Type dropdown only when the optional audio profile is compiled.

Enabled

Enables or disables the usermod. Disabling it stops playback and releases its hardware resources.

GPIO Pin

The GPIO connected to the buzzer interface.

The usermod requests the pin from WLED PinManager. If the pin cannot be allocated, the buzzer remains unavailable rather than silently sharing the pin.

Buzzer Type

Active

An active buzzer contains its own oscillator. The usermod can switch it on and off but cannot choose the acoustic pitch. Built-in sounds therefore reproduce rhythm only on active buzzers.

Passive

A passive buzzer is driven by ESP32 LEDC. The usermod controls both pitch and timing, so melodies reproduce their defined notes.

Audio (I2S)

Visible only when an audio profile is enabled at compile time. In v0.2.0 this backend uses embedded PCM samples for alarm, attention, connect, disconnect, error, fail, imperial_march, notification, star_wars, success, trumpet, victory, wakeup, warning, and yankee_doodle; beep, double_beep, and triple_beep remain synthesized tones. The initial profile targets the Waveshare ESP32-S3 RGB Matrix. Buzzer Type appears before GPIO Pin. When Audio (I2S) is selected, GPIO Pin and Trigger level are hidden because the board profile uses fixed pins. Volume is an integer 0-100 control and uses the ES8311 DAC volume register. See I2S audio backend.

Trigger level

Selects the electrical level that means "buzzer active":

  • High — active level is HIGH.
  • Low — active level is LOW.

The same setting is supported for active and passive configurations.

Volume

Visible for Passive and optional Audio backends.

For Passive, the 0-100 slider controls LEDC duty used for tone output. For Audio, it controls the ES8311 DAC output level; it does not change sample pitch or synthesized note frequency. Perceived acoustic loudness is not necessarily linear: piezo buzzers can be substantially louder around their resonant frequencies even when the configured duty is unchanged.

Night mode

When enabled, the buzzer is muted during the configured daily interval. The policy is applied centrally, so it affects GUI tests, Web/HTTP, WLED JSON, the C++ service and optional C bridge consumers such as iDotMatrix.

  • From: start of the quiet interval.
  • To: end of the quiet interval.

The time fields are hidden while Night Mode is disabled. Intervals crossing midnight are supported, for example 23:00 -> 07:00. Equal From and To values intentionally mean a full-day mute.

Night Mode uses WLED local time. If WLED has not acquired valid time yet, playback is not muted and diagnostics report that Night Mode is waiting for valid time. If a sound is already playing when the quiet interval begins, playback is stopped and does not resume automatically.

Sound test

The Sound dropdown is presented alphabetically and filtered by the selected backend. The original 15 sounds are common to Active, Passive and Audio. With bundled samples enabled, imperial_march, trumpet, and wakeup are additional Audio-only entries and appear only when Audio (I2S) is selected.

Select any available sound and press Play. Press Stop to terminate playback.

Save the configuration before testing hardware changes. The Play button tests the active saved hardware configuration.

Show API commands

Displays ready-to-use Web API examples for the current device and selected sound.