Register optimized ESPHome serial proxy transport with serialx (#168817)

Author: puddly

homeassistant/components/esphome/__init__.py

@@ -8,18 +8,24 @@
 
 from homeassistant.components import zeroconf
 from homeassistant.components.bluetooth import async_remove_scanner
+from homeassistant.components.usb import (
+    SerialDevice,
+    USBDevice,
+    async_register_serial_port_scanner,
+)
 from homeassistant.const import (
     CONF_HOST,
     CONF_PASSWORD,
     CONF_PORT,
     __version__ as ha_version,
 )
-from homeassistant.core import HomeAssistant
+from homeassistant.core import HomeAssistant, callback
 from homeassistant.helpers import config_validation as cv
 from homeassistant.helpers.issue_registry import async_delete_issue
 from homeassistant.helpers.typing import ConfigType
+from homeassistant.util import slugify
 
-from . import assist_satellite, dashboard, ffmpeg_proxy
+from . import assist_satellite, dashboard, ffmpeg_proxy, serial_proxy
 from .const import CONF_BLUETOOTH_MAC_ADDRESS, CONF_NOISE_PSK, DOMAIN
 from .domain_data import DomainData
 from .encryption_key_storage import async_get_encryption_key_storage
@@ -34,12 +40,48 @@
 CLIENT_INFO = f"Home Assistant {ha_version}"
 
 
+@callback
+def _async_scan_serial_ports(
+    hass: HomeAssistant,
+) -> list[USBDevice | SerialDevice]:
+    """Return serial-proxy ports exposed by connected ESPHome devices."""
+    ports: list[USBDevice | SerialDevice] = []
+
+    for entry in hass.config_entries.async_loaded_entries(DOMAIN):
+        entry_data = entry.runtime_data
+        if not entry_data.available:
+            continue
+
+        device_info = entry_data.device_info
+        if device_info is None:
+            continue
+
+        ports.extend(
+            SerialDevice(
+                device=str(serial_proxy.build_url(entry.entry_id, proxy.name)),
+                serial_number=(
+                    device_info.mac_address.replace(":", "") + "-" + slugify(proxy.name)
+                ),
+                manufacturer=device_info.manufacturer,
+                description=f"{device_info.model} ({proxy.name})",
+            )
+            for proxy in device_info.serial_proxies
+        )
+
+    return ports
+
+
 async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
     """Set up the esphome component."""
     ffmpeg_proxy.async_setup(hass)
     await assist_satellite.async_setup(hass)
     await dashboard.async_setup(hass)
     async_setup_websocket_api(hass)
+
+    if "usb" in hass.config.components:
+        async_register_serial_port_scanner(hass, _async_scan_serial_ports)
+        serial_proxy.set_hass_loop(hass.loop)
+
     return True
 
 

homeassistant/components/esphome/manifest.json

@@ -1,7 +1,7 @@
 {
   "domain": "esphome",
   "name": "ESPHome",
-  "after_dependencies": ["hassio", "zeroconf", "tag"],
+  "after_dependencies": ["hassio", "tag", "usb", "zeroconf"],
   "codeowners": ["@jesserockz", "@kbx81", "@bdraco"],
   "config_flow": true,
   "dependencies": ["assist_pipeline", "bluetooth", "intent", "ffmpeg", "http"],

homeassistant/components/esphome/serial_proxy.py

@@ -0,0 +1,113 @@
+"""Home Assistant-aware ESPHome serial proxy URI handler for serialx."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import cast
+
+from aioesphomeapi import APIClient
+from serialx import register_uri_handler
+from serialx.platforms.serial_esphome import (
+    ESPHomeSerial,
+    ESPHomeSerialTransport,
+    InvalidSettingsError,
+)
+from yarl import URL
+
+from homeassistant.config_entries import ConfigEntryState
+from homeassistant.core import HomeAssistant, async_get_hass
+
+from .const import DOMAIN
+from .entry_data import ESPHomeConfigEntry
+
+SCHEME = "esphome-hass://"
+
+# This is required so that serialx can safely query Core for an instance of an
+# aioesphomeapi client. We cannot make any assumptions here, some packages run separate
+# asyncio event loops in dedicated threads.
+_HASS_LOOP: asyncio.AbstractEventLoop | None = None
+
+
+def set_hass_loop(loop: asyncio.AbstractEventLoop) -> None:
+    """Store a reference to the Core event loop."""
+    global _HASS_LOOP  # noqa: PLW0603  # pylint: disable=global-statement
+    _HASS_LOOP = loop
+
+
+def build_url(entry_id: str, port_name: str) -> URL:
+    """Build a canonical `esphome-hass://` URL."""
+    return URL.build(
+        scheme="esphome-hass",
+        host="esphome",
+        path=f"/{entry_id}",
+        query={"port_name": port_name},
+    )
+
+
+async def _resolve_client(entry_id: str) -> APIClient:
+    """Look up the `APIClient` for a specific config entry."""
+
+    # This function is async specifically so that we can get a reference to the Home
+    # Assistant Core instance from its own thread
+    hass: HomeAssistant = async_get_hass()
+    entry = cast(ESPHomeConfigEntry, hass.config_entries.async_get_entry(entry_id))
+
+    if entry is None or entry.domain != DOMAIN:
+        raise InvalidSettingsError(f"No ESPHome config entry with id {entry_id!r}")
+
+    if entry.state is not ConfigEntryState.LOADED:
+        raise InvalidSettingsError(f"ESPHome config entry {entry_id!r} is not loaded")
+
+    return entry.runtime_data.client
+
+
+class HassESPHomeSerial(ESPHomeSerial):
+    """ESPHomeSerial that resolves an HA config entry's APIClient from the URL."""
+
+    _api: APIClient | None
+    _path: str | None
+
+    async def _async_open(self) -> None:
+        """Resolve the HA config entry's APIClient, then open the proxy."""
+        if self._api is None and self._path is not None:
+            parsed = URL(str(self._path))
+
+            entry_id = parsed.path.lstrip("/")
+            if not entry_id:
+                raise InvalidSettingsError(
+                    f"No ESPHome config entry id in URL {self._path!r}"
+                )
+
+            if "port_name" not in parsed.query:
+                raise InvalidSettingsError("Port name is required")
+
+            self._port_name = parsed.query["port_name"]
+
+            hass_loop = _HASS_LOOP
+            if hass_loop is None:
+                raise InvalidSettingsError(
+                    "ESPHome integration has not registered its event loop"
+                )
+
+            # Fetch the `APIClient` from the Core via the appropriate event loop
+            self._api = await asyncio.wrap_future(
+                asyncio.run_coroutine_threadsafe(_resolve_client(entry_id), hass_loop)
+            )
+            self._client_loop = self._api._loop  # noqa: SLF001
+
+        await super()._async_open()
+
+
+class HassESPHomeSerialTransport(ESPHomeSerialTransport):
+    """Transport variant that constructs :class:`HassESPHomeSerial`."""
+
+    transport_name = "esphome-hass"
+    _serial_cls = HassESPHomeSerial
+
+
+register_uri_handler(
+    scheme=SCHEME,
+    unique_scheme=SCHEME,
+    sync_cls=HassESPHomeSerial,
+    async_transport_cls=HassESPHomeSerialTransport,
+)