ESPuino Home Assistant Integration

---

Fully integrate your ESPuino RFID audio player into Home Assistant!
This custom integration lets you control ESPuino via MQTT and monitor its status directly from Home Assistant.

---

---

🔧 Features

• Media control (play, pause, next/previous track, volume)
• Display current track information via MQTT
• Control lock, sleep timer, and other functions
• UI integration via Config Flow
• Compatible with Home Assistant 2023.x+

---

📦 Requirements

• A running MQTT broker
• A properly configured ESPuino device with MQTT enabled
• Home Assistant with MQTT integration set up

---

🚀 Installation

Via HACS (recommended)

1. Open HACS → Integrations → Three-dot menu → Custom repositories
2. Add the repository: https://github.com/DexXxter007/ESPuino_HA_Integration
3. Category: Integration
4. After adding, search for ESPuino Integration in HACS and install it
5. Restart Home Assistant

Manual Installation

1. Download the ZIP archive
2. Extract it into:
   <config>/custom_components/espuino/
3. Restart Home Assistant

---

⚙️ Setup

After restarting Home Assistant:

1. Go to Settings → Devices & Services → Add Integration
2. Search for ESPuino Integration
3. Enter a Name manually (check your device-id in the webserver),
4. You're done – entities will be created automatically

📡 Required ESPuino MQTT Configuration

For this integration to work correctly, your have to configure mqtt in the webserver of the ESPuino (MQTT-Tab).

Note: By default there is no topic prefix — topics are in the form <device_id>/<state> for state updates and <device_id>/<command>/set for commands. If you prefer a prefixed structure you can set topic_prefix to something like home/media, which will result in home/media/<device_id>/<state> and home/media/<device_id>/<command>/set.

You can change the topic_prefix after installation from Home Assistant: go to Settings → Devices & Services → ESPuino → Configure and edit the Topic Prefix option. For example (default, no prefix):

// Commands:
ESPuino-AABBCCDDEEFF/sleep/set
ESPuino-AABBCCDDEEFF/rfid/set
// States:
ESPuino-AABBCCDDEEFF/sleep
ESPuino-AABBCCDDEEFF/rfid
ESPuino-AABBCCDDEEFF/track

For example (with topic_prefix = "home/media"):

// Commands:
home/media/ESPuino-AABBCCDDEEFF/sleep/set
home/media/ESPuino-AABBCCDDEEFF/rfid/set
// States:
home/media/ESPuino-AABBCCDDEEFF/sleep
home/media/ESPuino-AABBCCDDEEFF/rfid
home/media/ESPuino-AABBCCDDEEFF/track

---

## 🧪 Example Entities

Once set up, the following entities will be available:

- `media_player.espuino`
- `sensor.espuino_track`
- `switch.espuino_sleep`
- `button.espuino_play_next`
- `number.espuino_volume`

---

## 🛠️ Troubleshooting

- **Integration not found:** Make sure `custom_components/espuino` exists in your config folder
- **MQTT not working:** Check your MQTT topics and broker connection
- **HACS warning:** Ensure you're using a [tagged release](https://github.com/DexXxter007/ESPuino_HA_Integration/releases) (`v1.0.0`, etc.)

---

## 🗒️ Changelog

### v1.0.0
- Initial release with media player support and MQTT integration

---

## 👤 Credits

- [DexXxter007](https://github.com/DexXxter007) – Development
- [biologist79](https://github.com/biologist79/ESPuino) – ESPuino project (hardware & firmware)

---

## 🪪 License

MIT License – free to use, modify, and distribute.