ESPHome - Connect your ESPHome devices to Homey
Hi everyone, as I promised: the ESPHome app is here. This is the central topic for questions and discussion around the ESPHome App. Please use this topic to ask questions, report issues and share your experiences with your ESPHome devices.
Homey talks to your devices locally over ESPHome’s Native API. There is no cloud in between. Discovery uses mDNS; if that doesn’t find the node you can add it by IP, and new devices can get their Wi-Fi credentials via Bluetooth (Improv).
You’ll notice the GitHub repo has surprisingly little code. That’s because this app uses the new homey-esphomedriver package, which contains the connection, pairing and capability-mapping logic. That package in turn uses aioesphomeapi, maintained by the ESPHome team.
I created that package for one simple reason: more and more brands are shipping off-the-shelf ESPHome devices, like our good partners Apollo Automation and Everything Smart Technology for example. I want to make it easier for those brands to get up and running with Homey and become Works with Homey partners. With this package they only have to manage drivers for their products; the backend is already taken care of. That should also give a more consistent experience across ESPHome brands and devices.
If you pair a device that already has its own Homey app, Homey will point you towards that app instead.
Useful links
Requirements
- Homey Pro (2023) or newer, Homey Pro mini or Homey Self-Hosted Server
- Homey firmware 13.0.0 or newer
- An ESPHome device with the Native API enabled (
api:in YAML) - The ESPHome device and Homey on the same network
A typical YAML snippet:
api:
encryption:
key: "YOUR_BASE64_ENCRYPTION_KEY"
The encryption key is the one from api → encryption → key. You’ll be asked for it during pairing (or repair) when the device requires it.
Adding a device
In Homey, as usual, go to Add device → ESPHome. You can:
- Pick a discovered device → nodes advertising over mDNS (
_esphomelib._tcp) show up automatically - Add by IP… → enter hostname or IP (port
6053by default) - Set up via Bluetooth… → using BLE Improv you can give the device Wi-Fi credentials, after which it appears like any other ESPHome node
If the connection later breaks (new IP, new encryption key) you can use the device repair to change any of these values.
Supported entities
Entities are mapped automatically to Homey capabilities (and to Flows / Insights). Currently that includes:
Light, Switch, Sensor, Binary sensor, Cover, Climate, Fan, Lock, Button, Number, Select, Text sensor, Media player, Valve, Siren, Event, Alarm panel and Water heater.
If Homey has no matching system capability, a generic esphome_* capability is added instead.
Reporting an issue
Please include:
- Homey model + firmware version
- App version
- ESPHome firmware version
- How you added the device (discovered / IP / Bluetooth)
- The relevant part of the device YAML
- Diagnostic report from the app (
More→Apps→ESPHome→⚙→Create Diagnostics Report)
GitHub issues are preferred for bugs: Doekse/esphome-homey/issues. This topic is great for “does this work for device X?” and general feedback.
FAQ
Are all ESPHome devices supported?
They should be. Any ESPHome node with a Native API (api:) and supported entities can be added out of the box. If pairing fails with “no supported entities”, the node may only expose types we don’t map yet, post the YAML here and we’ll have a look.
How can I map the entities of my ESPHome device?
You don’t map them by hand. Entities are matched automatically to the corresponding Homey capability. If no system capability exists, a generic capability (esphome_boolean, esphome_number, esphome_select, esphome_string) is added instead.
Where can I find the diagnostic and configuration entities?
To avoid flooding a device with capabilities, diagnostic and configuration entities are hidden by default (Wi-Fi signal, uptime, calibration numbers, restart buttons, and anything marked entity_category: diagnostic / config in ESPHome). Enable them under the device’s Advanced settings:
- Show diagnostic capabilities
- Show configuration capabilities
My device gets the wrong Device Class
The app does a best-effort guess from the entities on the device. You can override it under the device’s Advanced settings → Device class. Auto keeps the detected class.
Can I set up a new ESPHome device with this app?
Yes. When adding a device, choose Set up via Bluetooth…. That starts BLE Improv so you can send Wi-Fi credentials. Homey needs to be close to the device, and the firmware must have Improv enabled. This sets up Wi-Fi only, it does not flash firmware.
The app asks for an encryption key
That’s the Native API Noise key from your YAML (api → encryption → key). If you later rotate the key, repair the device. If the device has no encryption it will skip that step.
My device isn’t discovered
Check that Homey and the device are on the same LAN/VLAN (mDNS has to get through), that api: is enabled, and that the node is online. If discovery still fails, use Add by IP…. A DHCP reservation or static IP makes this more reliable.
Does this replace the (older) community ESPHome apps?
This will become the official integration, not a continuation of the community apps. You can run them side by side if wanted. Thank you to everyone who kept ESPHome usable on Homey until now!
I have a branded ESPHome device. Should I use this app?
We always suggest using the manufacturers own Homey App. This generic app accepts any ESPHome node, and when a brand ships its own Homey App pairing that product here will suggest the dedicated app.
Does this App work on Homey Cloud
No. The app is local-only. ESPHome’s BLE Bluetooth Proxy is also not used; Homey talks to each node over the Native API on your LAN.
Does this App work on Homey (2016-2019)
Unfortunately, no. The ESPHome app for Homey relies on the aioesphomeapi package, which is Python-based rather than Java- or TypeScript-based. The older-generation Homey Pro does not currently support this runtime.
