Is Passive Piezo RTTTL Music Buzzer Compatible with Home Assistant (ESPHome)?
Electrical Specifications
Always confirm pin assignments against the manufacturer datasheet before wiring.
Compatibility Overview
Piezoelectric buzzer module for playing Nokia RTTTL tunes alarm sound effects and status chimes in ESPHome.
Wiring Passive Piezo RTTTL Music Buzzer to ESP32
| Module pin | ESP32 | Note |
|---|---|---|
| VCC / + | 3V3 | Three-pin modules only. A bare two-pin piezo has no supply pin; it sits between the GPIO and GND. |
| I/O / S | GPIO25 | Any output-capable pin works — the ledc peripheral can be routed to all of them. |
| GND / − | GND |
Host pins are the ones the configuration on this page uses. Move a pin here and change it in the YAML — they are documented together so they cannot disagree.
Technical Specification Matrix
| Feature / Attribute | Specification / Status |
|---|---|
| Hardware Protocol | PWM GPIO / 3.3V |
| Bridge Required | NO |
| Border Router Needed | None |
| Hardware Capabilities & Peripherals | Ringtone Audio RTTTL Tone Frequency (Hz) Note: these entities come from the ESPHome configuration you flash — each one needs its matching component in that YAML before it appears. |
| Pairing Complexity | Plug-and-Play |
| Factory Reset Instruction | Hold BOOT button for 3s. |
Wire, Flash, Adopt, Check
Wire it up
Follow the wiring table above. The ESP32 pins there are the ones the configuration uses, so if you move one, change it in both places.
Flash the configuration
Create a new device in the ESPHome dashboard (the Home Assistant add-on) and paste the configuration below into it, or save it as emb_esp32_buzzer_esphome.yaml and run esphome run emb_esp32_buzzer_esphome.yaml. The first flash goes over USB. If it is not detected, hold BOOT button for 3s to put it in download mode. Every update after that is over the air.
Adopt it in Home Assistant
Settings → Devices & Services. A node on the same network shows up as a discovered ESPHome device within a minute of joining Wi-Fi; choose Configure and enter the API encryption key from your secrets.yaml. If discovery does not find it, add the ESPHome integration by hand with the node's IP address.
Check it works
Pressing Play Tone in Home Assistant plays two short beeps and the log names the song as it starts. Silence with the log line present is wiring or an active buzzer; no log line is the button not reaching the node.
ESPHome Configuration
Starting configuration for Passive Piezo RTTTL Music Buzzer on ESP32. Untested on hardware — verify wiring and pins against your own board.
# ESPHome configuration for Passive Piezo RTTTL Music Buzzer
# Host: ESP32. Pin numbers below are host-side defaults — any free
# GPIO will do, and you should change them to match your own wiring.
esphome:
name: emb_esp32_buzzer_esphome
friendly_name: "Passive Piezo RTTTL Music Buzzer"
esp32:
board: esp32dev
framework:
type: esp-idf
logger:
api:
encryption:
key: !secret api_encryption_key
ota:
- platform: esphome
password: !secret ota_password
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
output:
- platform: ledc
pin: GPIO25
id: buzzer_out
rtttl:
output: buzzer_out
# Volume, roughly: it scales the PWM duty. Piezos are quiet at any setting;
# a magnetic buzzer behind a transistor is where this makes a difference.
gain: 60%
button:
- platform: template
name: "Play Tone"
on_press:
then:
- rtttl.play: 'two_short:d=4,o=5,b=100:16e6,16e6'
Before you flash:
the !secret values come from your
secrets.yaml, and the GPIO numbers are host-side
defaults rather than properties of this part — change them to match how you actually wired it.
What Appears in Home Assistant
The template button in the config plays a two-beep RTTTL string. Copy it for each chime you want.
rtttl: itself exposes nothing. To play arbitrary tunes from Home Assistant, add an action under api: with a string variable; HA then offers it as esphome.<node>_play_rtttl.
Known Problems and Fixes
Passive, not active
RTTTL needs a passive buzzer: a bare piezo or magnetic element that sounds at whatever frequency it is driven. An active buzzer has its own oscillator and plays one fixed tone no matter what the PWM does. The test: put DC across it — an active buzzer sounds continuously, a passive one clicks once.
Piezos are quiet
gain: in the config scales the PWM duty and is as much volume as a bare piezo offers. For a chime that carries across a room use a magnetic buzzer behind an NPN transistor with a flyback diode, or a small speaker on a DFPlayer or I2S amplifier.
Do not pull much current from the pin
An ESP32 GPIO is comfortable at about 12mA and 40mA is the absolute limit. Piezos draw almost nothing; magnetic buzzers can draw more than that at resonance. Modules with a transistor on board (three pins, an onboard resistor) take that problem away.
ledc is ESP32-only
On an ESP8266 the output platform is esp8266_pwm; the rtttl block is the same.
Two buzzers
Each rtttl: component drives one output. Two buzzers means two output: entries and two rtttl: entries with their own ids, and rtttl.play targeting one by id. They cannot play different tunes from a single component.
Report a Pinout Error or Submit Tested Code Snippets
Found a pin mapping quirk or built a custom ESPHome YAML driver for Passive Piezo RTTTL Music Buzzer? Submit a pull request or report corrections to our index.
Hardware Correction Reporter (emb-esp32-buzzer-esphome)
Frequently Asked Questions
Does Passive Piezo RTTTL Music Buzzer work without an internet connection?
How is Passive Piezo RTTTL Music Buzzer powered and wired to the host board?
How does the host board reach Home Assistant (ESPHome)?
Alternatives
DFPlayer Mini MP3 Audio Player
Real audio files from a microSD card, through a speaker, for doorbells and announcements.
MAX98357A I2S 3.2W Class-D Amplifier
An I2S amplifier turns the node into a Home Assistant media player, so text-to-speech announcements land on it directly.