Buzzer

Interfaces for buzzers. More...

Topics
	Buzzer Driver Backend API

Files
file	buzzer.h
	Main header file for buzzer driver API.

Macros
#define	BUZZER_FREQ_REST   0U
	Special frequency value representing silence.
#define	BUZZER_VOLUME_MAX   100U
	Maximum volume level, range is 0 to BUZZER_VOLUME_MAX.
#define	BUZZER_DURATION_FOREVER   UINT32_MAX
	Special duration meaning "play until explicitly stopped".

Functions
static int	buzzer_tone (const struct device *dev, uint32_t freq_hz, uint32_t duration_ms)
	Play a single tone at freq_hz for duration_ms.
static int	buzzer_set_volume (const struct device *dev, uint8_t percent)
	Set the buzzer volume.
static int	buzzer_beep (const struct device *dev, uint32_t duration_ms)
	Play the buzzer's default tone for duration_ms.
static int	buzzer_stop (const struct device *dev)
	Stop any tone currently being played.

Detailed Description

Interfaces for buzzers.

Since

4.5

Version

0.1.0

Audio output abstraction for simple buzzers and similar single-tone sound sources.

Buzzer API calls do not wait for the requested tone duration: a duration describes how long the hardware should keep emitting a tone, not how long the calling thread should sleep.

Macro Definition Documentation

BUZZER_DURATION_FOREVER

#define BUZZER_DURATION_FOREVER   UINT32_MAX

#include <zephyr/drivers/buzzer.h>

Special duration meaning "play until explicitly stopped".

Use this as the duration_ms argument to buzzer_tone() or buzzer_beep() when the tone should not be silenced automatically. The caller must invoke buzzer_stop() or start another tone to end it.

BUZZER_FREQ_REST

#define BUZZER_FREQ_REST   0U

#include <zephyr/drivers/buzzer.h>

Special frequency value representing silence.

BUZZER_VOLUME_MAX

#define BUZZER_VOLUME_MAX   100U

#include <zephyr/drivers/buzzer.h>

Maximum volume level, range is 0 to BUZZER_VOLUME_MAX.

Function Documentation

buzzer_beep()

int buzzer_beep ( const struct device * dev, uint32_t duration_ms )

inlinestatic

#include <zephyr/drivers/buzzer.h>

Play the buzzer's default tone for duration_ms.

The call returns after the hardware has been configured; it does not wait for duration_ms to elapse. For PWM-driven passive piezos, the default tone is derived from the period cell of the device's pwms devicetree property. For GPIO-driven active buzzers, the hardware oscillator determines the actual pitch.

Parameters

dev	Buzzer device.
duration_ms	How long the buzzer should keep emitting the tone. Use BUZZER_DURATION_FOREVER to play until an explicit buzzer_stop() or another tone-emitting call.

Return values

0	Tone scheduled successfully.
-errno	Negative errno code on failure.

buzzer_set_volume()

int buzzer_set_volume ( const struct device * dev, uint8_t percent )

inlinestatic

#include <zephyr/drivers/buzzer.h>

Set the buzzer volume.

Volume is expressed as a percentage between 0 and BUZZER_VOLUME_MAX, where 0 is silent and BUZZER_VOLUME_MAX is the loudest level the hardware can produce. The volume control affects subsequent tones until changed. Setting the volume to 0 also silences the buzzer immediately.

Backends without programmatic volume control map any non-zero value to their single audible level and zero to silent.

Parameters

dev	Buzzer device.
percent	Desired volume, 0 to BUZZER_VOLUME_MAX inclusive.

Return values

0	Volume updated successfully.
-EINVAL	percent is out of range.
-errno	Negative errno code on failure.

buzzer_stop()

int buzzer_stop ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/buzzer.h>

Stop any tone currently being played.

Idempotent: calling stop() on an already-silent buzzer is a no-op.

Parameters

dev	Buzzer device.

Return values

0	Buzzer stopped.
-errno	Negative errno code on failure.

buzzer_tone()

int buzzer_tone ( const struct device * dev, uint32_t freq_hz, uint32_t duration_ms )

inlinestatic

#include <zephyr/drivers/buzzer.h>

Play a single tone at freq_hz for duration_ms.

The call returns after the hardware has been configured; it does not wait for duration_ms to elapse. The buzzer keeps emitting the tone for duration_ms, after which the driver silences it automatically. Calling buzzer_tone() again while a previous tone is still playing pre-empts it.

Passing BUZZER_FREQ_REST silences the buzzer immediately.

Backends that cannot honor a requested frequency exactly play their nearest supported tone or, if the request is for silence, stop.

Parameters

dev	Buzzer device.
freq_hz	Tone frequency in Hz.
duration_ms	How long the buzzer should keep emitting the tone. Use BUZZER_DURATION_FOREVER to play until an explicit buzzer_stop() or another tone-emitting call.

Return values

0	Tone scheduled successfully.
-errno	Negative errno code on failure.