Is DFPlayer Mini MP3 Audio Player Compatible with Home Assistant (ESPHome)?
Electrical Specifications
Always confirm pin assignments against the manufacturer datasheet before wiring.
Compatibility Overview
Hardware MP3/WAV audio player module for custom smart home voice chimes doorbells and alarm announcements from MicroSD storage.
Wiring DFPlayer Mini MP3 Audio Player to ESP32
| Module pin | ESP32 | Note |
|---|---|---|
| VCC | 5V | Its own supply or a large capacitor on the rail: a loud track pulls enough current to brown out an ESP32 sharing the same USB port. |
| GND | GND | |
| RX | GPIO17 | Through a 1kΩ series resistor. The module is a 5V part, and the resistor is what stops the hiss on the speaker. |
| TX | GPIO16 | Host RX. Carries the module's replies; harmless if you leave it off, but then the log is silent. |
| SPK_1 / SPK_2 | speaker | Up to 3W, 4–8Ω, straight to the terminals. For a bigger amplifier use DAC_L and DAC_R as a line out. |
| BUSY | GPIO18 | Low while a track plays. The config reads it as the Playing sensor. |
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 | UART Serial / 3.3V |
| Bridge Required | NO |
| Border Router Needed | None |
| Hardware Capabilities & Peripherals | Audio Track Selection Playback State Volume Level Speaker Switch Note: these entities come from the ESPHome configuration you flash — each one needs its matching component in that YAML before it appears. |
| Pairing Complexity | Intermediate |
| 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_dfplayer_esphome.yaml and run esphome run emb_esp32_dfplayer_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
Press Play First Track: the first file plays and Playing turns on for its duration. Sound with Playing stuck off is the BUSY pin; a click and silence is the card; a module that resets the ESP32 when it plays is power.
ESPHome Configuration
Starting configuration for DFPlayer Mini MP3 Audio Player on ESP32. Untested on hardware — verify wiring and pins against your own board.
# ESPHome configuration for DFPlayer Mini MP3 Audio Player
# 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_dfplayer_esphome
friendly_name: "DFPlayer Mini MP3 Audio Player"
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
uart:
rx_pin: GPIO16
tx_pin: GPIO17
baud_rate: 9600
dfplayer:
on_finished_playback:
then:
logger.log: 'Playback finished'
button:
- platform: template
name: "Play First Track"
on_press:
then:
- dfplayer.play: 1
# The module pulls BUSY low while a track plays. ESPHome gets no other
# playback feedback from a DFPlayer, so this pin is the "is it playing"
# entity.
binary_sensor:
- platform: gpio
name: "Playing"
pin:
number: GPIO18
mode:
input: true
pullup: true
inverted: true
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
Plays file 0001.mp3. Copy the block per chime, or add an action under api: with a track variable so Home Assistant can pick the track.
From the BUSY pin. It is the only playback state ESPHome can see; dfplayer.play is fire-and-forget otherwise.
Known Problems and Fixes
Track numbers follow copy order, not file names
The module plays files in the order they were written to the card's FAT table. Name them 0001.mp3, 0002.mp3 and copy them one at a time in that order onto a freshly formatted card; drag a folder across and track 1 may be any of them. Folder mode (01/001.mp3 with dfplayer.play_folder) is the tidier way.
The card
FAT32, 32GB or under, files in the root or in numbered folders. MP3 and WAV. Slow or oddly formatted cards give a module that clicks and plays nothing.
Clones behave differently
The reference chip is the YX5200. Boards with an MH2024K or GD3200B behave differently: some ignore volume commands, some never report a finished track, some need the resistor on TX as well as RX. If commands work and feedback does not, that is why.
Power
Playing through the speaker pins at full volume draws several hundred milliamps in bursts. On a shared USB rail the ESP32 resets mid-chime. Separate 5V, or 1000µF across VCC and GND at the module.
Not a media player
ESPHome cannot stream to this module or tell you what track is on; the DFPlayer is a chime box. For text-to-speech and streaming, see the I2S amplifier page.
Report a Pinout Error or Submit Tested Code Snippets
Found a pin mapping quirk or built a custom ESPHome YAML driver for DFPlayer Mini MP3 Audio Player? Submit a pull request or report corrections to our index.