# \[APP\]\[Pro\] ESPHome - Connect your ESPHome devices to Homey

**URL:** <https://community.homey.app/t/app-pro-esphome-connect-your-esphome-devices-to-homey/158455>\
**Category:** Apps\
**Tags:** app, homey-pro, esphome\
**Created:** [August 18, 2026, 2:52pm UTC](https://community.homey.app/t/app-pro-esphome-connect-your-esphome-devices-to-homey/158455 "2026-08-18T14:52:25Z")\
**Posts on this page:** 18\
**Page:** 1

<div class="post-metadata">

**Author:** ![Doekse](https://sea1.discourse-cdn.com/flex025/user_avatar/community.homey.app/doekse/32/109415_2.png) [@Doekse](https://community.homey.app/u/Doekse)\
**Post date:** [August 18, 2026, 2:52pm UTC](https://community.homey.app/t/app-pro-esphome-connect-your-esphome-devices-to-homey/158455/1 "2026-08-18T14:52:25Z")

</div>

# 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](https://homey.app/a/io.esphome/test/). 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](https://github.com/Doekse/esphome-homey) has surprisingly little code. That’s because this app uses the new [`homey-esphomedriver`](https://github.com/Doekse/homey-esphomedriver) package, which contains the connection, pairing and capability-mapping logic. That package in turn uses [`aioesphomeapi`](https://github.com/esphome/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](https://apolloautomation.com/) and [Everything Smart Technology](https://everythingsmarthome.co.uk/) 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

- [Source on GitHub](https://github.com/Doekse/esphome-homey)
- [Issues](https://github.com/Doekse/esphome-homey/issues)
- [homey-esphomedriver](https://github.com/Doekse/homey-esphomedriver)
- [ESPHome Native API](https://esphome.io/components/api/)

* * *

## 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:

```yaml
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:

1. **Pick a discovered device** → nodes advertising over mDNS _(`_esphomelib._tcp`)_ show up automatically
2. **Add by IP…** → enter hostname or IP _(port `6053` by default)_
3. **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](https://github.com/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`](https://github.com/esphome/aioesphomeapi) package, which is Python-based rather than Java- or TypeScript-based. The older-generation Homey Pro does not currently support this runtime.

> **[ESPHome | Homey](https://homey.app/en-us/app/io.esphome/ESPHome/test/)**
>
> Connect your ESPHome devices to Homey

---

<div class="post-metadata">

**Author:** ![Doekse](https://sea1.discourse-cdn.com/flex025/user_avatar/community.homey.app/doekse/32/109415_2.png) [@Doekse](https://community.homey.app/u/Doekse)\
**Post date:** [August 18, 2026, 2:52pm UTC](https://community.homey.app/t/app-pro-esphome-connect-your-esphome-devices-to-homey/158455/2 "2026-08-18T14:52:43Z")

</div>

[Reserved]

---

<div class="post-metadata">

**Author:** ![Peter\_Kawa](https://sea1.discourse-cdn.com/flex025/user_avatar/community.homey.app/peter_kawa/32/173848_2.png) [@Peter\_Kawa](https://community.homey.app/u/Peter_Kawa)\
**Post date:** [August 19, 2026, 12:10pm UTC](https://community.homey.app/t/app-pro-esphome-connect-your-esphome-devices-to-homey/158455/3 "2026-08-19T12:10:05Z")

</div>

Nice to see the result of your efforts, Abe.

Hint for Early (Pro) 2016-2019 model owners:  
You can use the ESPHome Controller community app:  
[https://community.homey.app/t/app-pro-esphome-controller-app/150421?u=peter\_kawa](https://community.homey.app/t/app-pro-esphome-controller-app/150421)

But of course it also works on the Homey Pro 202x / Mini models

---

<div class="post-metadata">

**Author:** ![smarthomesven](https://sea1.discourse-cdn.com/flex025/user_avatar/community.homey.app/smarthomesven/32/79712_2.png) [@smarthomesven](https://community.homey.app/u/smarthomesven)\
**Post date:** [August 19, 2026, 4:48pm UTC](https://community.homey.app/t/app-pro-esphome-connect-your-esphome-devices-to-homey/158455/4 "2026-08-19T16:48:00Z")

</div>

> [@Doekse](#):
>
> more and more brands are shipping off-the-shelf ESPHome devices, like our good partners [Apollo Automation](https://apolloautomation.com/) and [Everything Smart Technology](https://everythingsmarthome.co.uk/) for example.

So this means the Apollo Automation and Everything Smart Technology apps will no longer be compatible on Homey Pro 2019 as well?

---

<div class="post-metadata">

**Author:** ![Doekse](https://sea1.discourse-cdn.com/flex025/user_avatar/community.homey.app/doekse/32/109415_2.png) [@Doekse](https://community.homey.app/u/Doekse)\
**Post date:** [August 19, 2026, 5:04pm UTC](https://community.homey.app/t/app-pro-esphome-connect-your-esphome-devices-to-homey/158455/5 "2026-08-19T17:04:53Z")

</div>

Definitely not! Those apps already exist and use their own Node-based codebases.

Of course, some apps may choose to switch to the shared codebase in the future, but that’s not for me to decide. That’s entirely up to the individual developers and brands. We simply provide the tool and make it available to them.

---

<div class="post-metadata">

**Author:** ![Nick\_Schiffman](https://sea1.discourse-cdn.com/flex025/user_avatar/community.homey.app/nick_schiffman/32/121524_2.png) [@Nick\_Schiffman](https://community.homey.app/u/Nick_Schiffman)\
**Post date:** [September 11, 2026, 12:43am UTC](https://community.homey.app/t/app-pro-esphome-connect-your-esphome-devices-to-homey/158455/6 "2026-09-11T00:43:54Z")

</div>

Seems like I cannot add a device on self-hosted is that expected?

restarting the app I get “uv\_pipe\_chmod EINVAL”

When going to add a device I don’t see the ESPHome app connection

 ![Screenshot 2026-09-10 at 8.42.50 PM](https://us1.discourse-cdn.com/flex025/uploads/athom/original/3X/5/2/529040edb51406e64be54cd8d253b226deb8c74b.png)

```auto
Error: uv_pipe_chmod EINVAL
    at Server.listen (node:net:2390:15)
    at AppLocal.createUnixDomainSocket (file:///app/packages/homey-local/lib/AppLocal.mts:1389:22)
    at async file:///app/packages/homey-local/lib/AppLocal.mts:1123:32
    at async AppLocal.executeStart (file:///app/packages/homey-local/lib/AppLocal.mts:1298:7)
    at async AppLocal.start (file:///app/packages/homey-local/lib/AppLocal.mts:982:7)

```

---

<div class="post-metadata">

**Author:** ![Peter\_Kawa](https://sea1.discourse-cdn.com/flex025/user_avatar/community.homey.app/peter_kawa/32/173848_2.png) [@Peter\_Kawa](https://community.homey.app/u/Peter_Kawa)\
**Post date:** [September 11, 2026, 10:18am UTC](https://community.homey.app/t/app-pro-esphome-connect-your-esphome-devices-to-homey/158455/7 "2026-09-11T10:18:37Z")

</div>

Hi Abe!

Just curious, compared with Insights and other apps, can you tell why ESPHome app uses a relatively “big” chunk of storage?

Is it because of the included driver package maybe?

> [@Doekse](#):
>
> the new [`homey-esphomedriver`](https://github.com/Doekse/homey-esphomedriver) package

 ![Screenshot_20260911_120935_Homey](https://us1.discourse-cdn.com/flex025/uploads/athom/original/3X/9/1/91aa8cd761e81e6374949b4b3190bbe3e9505e28.jpeg)

---

<div class="post-metadata">

**Author:** ![Doekse](https://sea1.discourse-cdn.com/flex025/user_avatar/community.homey.app/doekse/32/109415_2.png) [@Doekse](https://community.homey.app/u/Doekse)\
**Post date:** [September 11, 2026, 10:22am UTC](https://community.homey.app/t/app-pro-esphome-connect-your-esphome-devices-to-homey/158455/8 "2026-09-11T10:22:25Z")

</div>

Good question actually, I will dive into that. I haven’t done any optimalisations yet.

---

<div class="post-metadata">

**Author:** ![Doekse](https://sea1.discourse-cdn.com/flex025/user_avatar/community.homey.app/doekse/32/109415_2.png) [@Doekse](https://community.homey.app/u/Doekse)\
**Post date:** [September 11, 2026, 10:31am UTC](https://community.homey.app/t/app-pro-esphome-connect-your-esphome-devices-to-homey/158455/9 "2026-09-11T10:31:16Z")

</div>

You’ve most likely run into a bug with Self-Hosted Server, we’ll have a look at it.

---

<div class="post-metadata">

**Author:** ![Peter\_Kawa](https://sea1.discourse-cdn.com/flex025/user_avatar/community.homey.app/peter_kawa/32/173848_2.png) [@Peter\_Kawa](https://community.homey.app/u/Peter_Kawa)\
**Post date:** [September 11, 2026, 10:53am UTC](https://community.homey.app/t/app-pro-esphome-connect-your-esphome-devices-to-homey/158455/10 "2026-09-11T10:53:01Z")

</div>

Confirmed.

@Doekse  
The app crashes right after install on Homey SHS. It does find my ESPHome devices though, according to the log.

This seems to be the culprit:

```auto

Error: Could not mount /python : 32
    at file:///app/packages/homey-local/lib/AppLocal.mts:1115:25
⚠ The app has crashed.

```

Relevant log entries:

```auto
Homey [log][ManagerAppsLocal][AppLocal:io.esphome] Automatically restarting in 100 seconds...

Homey [log][ManagerAppsLocal][AppLocal:io.esphome] Automatically restarting...
Homey [log][ManagerAppsLocal][AppLocal:io.esphome] Starting...
Homey [log][ManagerAppsLocal][AppLocal:io.esphome] Session ID: io.esphome-0.4.2-827554ab
Homey [log][ManagerDiscoveryLocal][DiscoveryStrategyMDNSSDLocal:a151f718-ac07-42e8-9422-2de19069d558] Init mDNS-SD Strategy: _esphomelib._tcp
Homey [log][ManagerDiscoveryLocal][DiscoveryStrategyMDNSSDLocal:a151f718-ac07-42e8-9422-2de19069d558] Discovered new service with ID 4827e25ddc24 and address 192.168.x.x
Homey [log][ManagerDiscoveryLocal][DiscoveryStrategyMDNSSDLocal:a151f718-ac07-42e8-9422-2de19069d558] Discovered new service with ID 2cf4321e84ad and address 192.168.x.xx
Homey [log][ManagerDiscoveryLocal][DiscoveryStrategyMDNSSDLocal:a151f718-ac07-42e8-9422-2de19069d558] Discovered new service with ID c4d8d50aed27 and address 192.168.x.xx
Homey [log][ManagerDiscoveryLocal][DiscoveryStrategyMDNSSDLocal:a151f718-ac07-42e8-9422-2de19069d558] Discovered new service with ID 2cf4322f86a1 and address 192.168.x.xx
Homey [log][ManagerAppsLocal][AppLocal:io.esphome] Could not unmount /homey/user/apps/7111cb336072ea096123bb0843484a2e/python : 32
Homey [err][ManagerAppsLocal][AppLocal:io.esphome] Error Starting: Could not mount /python : 32
Homey [err][ManagerDiscoveryLocal] Error Broadcasting onDiscoveryResult: Could not mount /python : 32
Homey [err][ManagerDiscoveryLocal] Error Broadcasting onDiscoveryResult: Could not mount /python : 32
Homey [err][ManagerDiscoveryLocal] Error Broadcasting onDiscoveryResult: Could not mount /python : 32
Homey [err][ManagerDiscoveryLocal] Error Broadcasting onDiscoveryResult: Could not mount /python : 32
Homey [log][ManagerAppsLocal][AppLocal:io.esphome] Last 10 lines Stderr: 
Error: Could not mount /python : 32
    at file:///app/packages/homey-local/lib/AppLocal.mts:1115:25
    at process.processTicksAndRejections (node:internal/process/task_queues:104:5)
⚠ The app has crashed.

```

.

NB: Just FYI, the [ESPHome Controller app](https://community.homey.app/t/app-pro-esphome-controller-app/150421) works @ SHS

---

<div class="post-metadata">

**Author:** ![Peter\_Kawa](https://sea1.discourse-cdn.com/flex025/user_avatar/community.homey.app/peter_kawa/32/173848_2.png) [@Peter\_Kawa](https://community.homey.app/u/Peter_Kawa)\
**Post date:** [September 11, 2026, 11:00am UTC](https://community.homey.app/t/app-pro-esphome-connect-your-esphome-devices-to-homey/158455/11 "2026-09-11T11:00:18Z")

</div>

> [@Doekse](#):
>
> a but

A but, not a bug? 😜

---

<div class="post-metadata">

**Author:** ![Doekse](https://sea1.discourse-cdn.com/flex025/user_avatar/community.homey.app/doekse/32/109415_2.png) [@Doekse](https://community.homey.app/u/Doekse)\
**Post date:** [September 11, 2026, 11:06am UTC](https://community.homey.app/t/app-pro-esphome-connect-your-esphome-devices-to-homey/158455/12 "2026-09-11T11:06:14Z")

</div>

Doing 16 things at the same time, always works very well; bug\*\* 🫣

---

<div class="post-metadata">

**Author:** ![Doekse](https://sea1.discourse-cdn.com/flex025/user_avatar/community.homey.app/doekse/32/109415_2.png) [@Doekse](https://community.homey.app/u/Doekse)\
**Post date:** [September 11, 2026, 11:07am UTC](https://community.homey.app/t/app-pro-esphome-connect-your-esphome-devices-to-homey/158455/13 "2026-09-11T11:07:01Z")

</div>

Could you try restarting your Self-Hosted Server instance? It is missing a file in Homey OS, that should be created with a reboot.

Next to that, on what platform are you using Self-Hosted Server?

---

<div class="post-metadata">

**Author:** ![robertklep](https://sea1.discourse-cdn.com/flex025/user_avatar/community.homey.app/robertklep/32/160628_2.png) [@robertklep](https://community.homey.app/u/robertklep)\
**Post date:** [September 11, 2026, 11:09am UTC](https://community.homey.app/t/app-pro-esphome-connect-your-esphome-devices-to-homey/158455/14 "2026-09-11T11:09:40Z")

</div>

> [@Peter\_Kawa](#):
>
> This seems to be the culprit:
> 
> ```auto
> Error: Could not mount /python : 32
> at file:///app/packages/homey-local/lib/AppLocal.mts:1115:25
> ⚠ The app has crashed.
> 
> ```

Was reported some time ago already: [Python apps crash immediately on Proxmox 9.1.1 ("Could not mount /python : 32") – Amazon Echo app won't start](https://community.homey.app/t/python-apps-crash-immediately-on-proxmox-9-1-1-could-not-mount-python-32-amazon-echo-app-wont-start/157731)

---

<div class="post-metadata">

**Author:** ![Nick\_Schiffman](https://sea1.discourse-cdn.com/flex025/user_avatar/community.homey.app/nick_schiffman/32/121524_2.png) [@Nick\_Schiffman](https://community.homey.app/u/Nick_Schiffman)\
**Post date:** [September 11, 2026, 12:47pm UTC](https://community.homey.app/t/app-pro-esphome-connect-your-esphome-devices-to-homey/158455/15 "2026-09-11T12:47:59Z")

</div>

I did reboot, and got the same failure, also tried reinstalling.

Testing was done on Mac mini

---

<div class="post-metadata">

**Author:** ![Doekse](https://sea1.discourse-cdn.com/flex025/user_avatar/community.homey.app/doekse/32/109415_2.png) [@Doekse](https://community.homey.app/u/Doekse)\
**Post date:** [September 11, 2026, 12:54pm UTC](https://community.homey.app/t/app-pro-esphome-connect-your-esphome-devices-to-homey/158455/16 "2026-09-11T12:54:30Z")

</div>

Thanks for the info!

It seems there are currently some issues with running Python apps on Self-Hosted Server on macOS. We are working on it!

---

<div class="post-metadata">

**Author:** ![Doekse](https://sea1.discourse-cdn.com/flex025/user_avatar/community.homey.app/doekse/32/109415_2.png) [@Doekse](https://community.homey.app/u/Doekse)\
**Post date:** [September 15, 2026, 4:53pm UTC](https://community.homey.app/t/app-pro-esphome-connect-your-esphome-devices-to-homey/158455/17 "2026-09-15T16:53:17Z")

</div>

Looked into this one, and it turns out I just hadn’t cleaned up my local build properly. I still had a few old local builds of the shared driver hanging around 🫣

That should be fixed in v0.4.3!

---

<div class="post-metadata">

**Author:** ![Peter\_Kawa](https://sea1.discourse-cdn.com/flex025/user_avatar/community.homey.app/peter_kawa/32/173848_2.png) [@Peter\_Kawa](https://community.homey.app/u/Peter_Kawa)\
**Post date:** [September 15, 2026, 5:41pm UTC](https://community.homey.app/t/app-pro-esphome-connect-your-esphome-devices-to-homey/158455/18 "2026-09-15T17:41:02Z")

</div>

Ah, that explains 😉  
It’s below 100MB’s now 🤘

 ![Screenshot_20260915_193715_Homey](https://us1.discourse-cdn.com/flex025/uploads/athom/original/3X/c/6/c685b980e48d4f87fddd8b5ef7b2a0684b827a35.jpeg)