Homey ESPHomeDriver

This module can be used to make the development of ESPHome apps for Homey easier.

It is essentially a map-tool from Homey-capabilities to ESPHome entities.

This module requires Homey Apps SDK v3.

Related Modules

• node-homey-zigbeedriver — Module for Zigbee drivers
• node-homey-zwavedriver — Module for Z-Wave drivers
• node-homey-rfdriver — Module for RF drivers
• node-homey-oauth2app — Module for OAuth2 apps

Installation

$ pip install homey-esphomedriver

Homey apps declare it next to aioesphomeapi in app.json / .homeycompose/app.json:

"pythonPackages": ["aioesphomeapi", "homey-esphomedriver"]

Also checkout [aioesphomeapi](https://github.com/esphome/aioesphomeapi) if you want to talk to the ESPHome Native API directly, without homey-esphomedriver.

$ pip install aioesphomeapi

Changelog

See CHANGELOG.md.

Requirements

This module requires Homey Apps SDK v3 (Python 3.14 runtime).

Usage

Your device should extend EspHomeDevice. This is the class you most likely want to extend from. Your driver should extend EspHomeDriver.

Product identity lives on the Homey driver like Zigbee productId: an esphome object in driver.compose.json. EspHomeDriver reads it from self.manifest. driver.py and device.py can re-export the stock classes when you do not need extra logic.

Driver compose

{
  "name": { "en": "AQ-1" },
  "class": "sensor",
  "$extends": ["esphome-defaults"],
  "esphome": {
    "clientInfo": "Homey EverythingSmart",
    "projects": ["EverythingSmart.AQ-1"],
    "hiddenEntities": ["status_led"],
    "deviceEntities": { "voc": "measure_tvoc" },
    "deviceClassOverrides": { "aq_1": "sensor" }
  }
}

Omit projects / projectPrefix to accept every project (io.esphome). If both are set, either match is enough.

A class-level brand_profile = BrandProfile(...) on the driver still overrides compose. Use that for after_map.

Driver

# drivers/aq-1/driver.py
from homey_esphomedriver import EspHomeDriver

homey_export = EspHomeDriver

Device

# drivers/aq-1/device.py
from homey_esphomedriver import EspHomeDevice

homey_export = EspHomeDevice

Lifecycle hooks

Core owns on_init and on_uninit on EspHomeDriver and EspHomeDevice. Subclass the hooks below instead — same pattern as homey-oauth2app's onOAuth2Init. Brand app.py exports Homey's App.

On a paired device, use self.client for the live EspHomeClient (may exist before the API handshake). Capability commands still require a READY session via _require_client() / available — including from on_esphome_connected.

Debug logging uses env.json DEBUG; there is no separate class flag.

# drivers/aq-1/device.py
from homey_esphomedriver import EspHomeClient, EspHomeDevice as BaseDevice


class EspHomeDevice(BaseDevice):
    async def on_esphome_init(self, client: EspHomeClient | None) -> None:
        await super().on_esphome_init(client)
        if client is not None:
            self.log(f"API session started for {client.host}")

    async def on_esphome_connected(self, client: EspHomeClient) -> None:
        await super().on_esphome_connected(client)
        self.log(f"Logged in to {client.host}")


homey_export = EspHomeDevice

Homey Compose files

Homey Compose runs before Python, so $extends / $template only see files already in the app. When homey-esphomedriver is listed in pythonPackages, Homey CLI copies this package's templates into .homeycompose/ during preprocess (homey app run, build, validate), before compose. That is what makes "$extends": ["esphome-defaults"] and pair "$template": "enter_key" resolve.

Until that CLI is released, or when the package is unpublished, run the same copy by hand:

$ esphome-homey sync

-p / --path selects an app directory other than the current one. sync leaves app.json, app.py, driver.compose.json, and existing driver code alone unless --force.

A brand app is a normal Homey Python app:

$ homey app create
$ homey app dependencies add aioesphomeapi homey-esphomedriver
$ homey app driver create

Then set $extends and the esphome block on each driver's driver.compose.json, add store images, and publish with Homey CLI.

Documentation

See ARCHITECTURE.md for what devices get from Homey and how a brand listing is an esphome compose block on top of this core.

• [esphome-homey](https://github.com/Doekse/esphome-homey) — generic Homey app (io.esphome; any ESPHome node)

License

MIT. See LICENSE.