Cpp Integration - piggei/wled-usermod-buzzer GitHub Wiki

The public header WLEDBuzzerService.h lets another WLED usermod request sounds without knowing the buzzer GPIO, polarity, LEDC channel or playback scheduler.

Obtain the service

#include "WLEDBuzzerService.h"

WLEDBuzzerService* buzzer = WLEDBuzzerService::instance();
if (buzzer && buzzer->isReady()) {
  buzzer->play("notification");
}

Always handle a null pointer or a service that is not ready. The Buzzer Usermod may be absent, disabled, not configured, or unable to allocate its hardware resources.

Play a built-in sound

buzzer->play("victory");

Infinite loop

buzzer->play("alarm", true);

Stop later:

buzzer->stop();

Finite repeat

buzzer->playRepeat("alarm", 3);

The count is the total number of executions.

Beep and tone

buzzer->beep(150);
buzzer->beep(150, 2000);
buzzer->tone(1200, 200);

Query state

if (buzzer->isPlaying()) {
  const char* id = buzzer->currentSoundId();
}

Available query calls include:

buzzer->isReady();
buzzer->isPlaying();
buzzer->currentSoundId();

Integration rule

Consumer usermods should depend on the logical service, not on the hardware implementation. Do not directly drive the buzzer GPIO from a consumer when the Buzzer Usermod owns that pin.

This makes the consumer independent of active/passive selection, trigger polarity, volume, LEDC allocation and future scheduler changes.

Optional weak-link consumers

v0.1.1 exports a complete extern "C" bridge for consumers that must remain buildable when the Buzzer Usermod is not selected in custom_usermods. This avoids including WLEDBuzzerService.h from an optional consumer, which can cause PlatformIO Library Dependency Finder to auto-discover and compile a sibling Buzzer repository.

Exported symbols:

bool wledBuzzerServiceReady();
bool wledBuzzerServicePlaying();
bool wledBuzzerServicePlay(const char* soundId, bool loop);
bool wledBuzzerServicePlayRepeat(const char* soundId, uint16_t repeatCount);
bool wledBuzzerServiceBeep(uint16_t durationMs, uint16_t frequencyHz);
bool wledBuzzerServiceTone(uint16_t frequencyHz, uint16_t durationMs);
void wledBuzzerServiceStop();
const char* wledBuzzerServiceCurrentSoundId();

A consumer may declare these symbols with GCC __attribute__((weak)), check that the function pointers are non-null, and remain fully linkable when this Usermod is absent. The existing C++ singleton API remains available for consumers that intentionally make the Buzzer Usermod a hard build dependency.

This optional-consumer path has been validated with the real iDotMatrix Usermod integration. Playback requests return false while Night Mode is actively muting the buzzer; Ready still represents service/hardware readiness rather than the quiet-policy state.