Add eGauge integration

homeassistant/components/egauge/__init__.py

@@ -0,0 +1,42 @@
+"""Integration for eGauge energy monitors."""
+
+from __future__ import annotations
+
+from homeassistant.const import Platform
+from homeassistant.core import HomeAssistant
+from homeassistant.helpers import device_registry as dr
+
+from .const import DOMAIN, MANUFACTURER, MODEL
+from .coordinator import EgaugeConfigEntry, EgaugeDataCoordinator
+
+PLATFORMS = [Platform.SENSOR]
+
+
+async def async_setup_entry(hass: HomeAssistant, entry: EgaugeConfigEntry) -> bool:
+    """Set up eGauge from a config entry."""
+
+    coordinator = EgaugeDataCoordinator(hass, entry)
+    await coordinator.async_config_entry_first_refresh()
+
+    # Store coordinator in runtime_data
+    entry.runtime_data = coordinator
+
+    # Set up main device
+    device_registry = dr.async_get(hass)
+    device_registry.async_get_or_create(
+        config_entry_id=entry.entry_id,
+        identifiers={(DOMAIN, coordinator.serial_number)},
+        name=coordinator.hostname,
+        manufacturer=MANUFACTURER,
+        model=MODEL,
+        serial_number=coordinator.serial_number,
+    )
+
+    # Setup sensor platform
+    await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
+    return True
+
+
+async def async_unload_entry(hass: HomeAssistant, entry: EgaugeConfigEntry) -> bool:
+    """Unload eGauge config entry."""
+    return await hass.config_entries.async_unload_platforms(entry, PLATFORMS)

homeassistant/components/egauge/config_flow.py

@@ -0,0 +1,77 @@
+"""Config flow to configure the eGauge integration."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from egauge_async.exceptions import EgaugeAuthenticationError, EgaugePermissionError
+from egauge_async.json.client import EgaugeJsonClient
+from httpx import ConnectError
+import voluptuous as vol
+
+from homeassistant.config_entries import ConfigFlow, ConfigFlowResult
+from homeassistant.const import (
+    CONF_HOST,
+    CONF_PASSWORD,
+    CONF_SSL,
+    CONF_USERNAME,
+    CONF_VERIFY_SSL,
+)
+from homeassistant.helpers.httpx_client import get_async_client
+
+from .const import DOMAIN, LOGGER
+
+STEP_USER_DATA_SCHEMA = vol.Schema(
+    {
+        vol.Required(CONF_HOST): str,
+        vol.Required(CONF_USERNAME): str,
+        vol.Required(CONF_PASSWORD): str,
+        vol.Required(CONF_SSL, default=True): bool,
+        vol.Required(CONF_VERIFY_SSL, default=False): bool,
+    }
+)
+
+
+class EgaugeFlowHandler(ConfigFlow, domain=DOMAIN):
+    """Handle an eGauge config flow."""
+
+    async def async_step_user(
+        self, user_input: dict[str, Any] | None = None
+    ) -> ConfigFlowResult:
+        """Handle a flow initiated by the user."""
+        errors: dict[str, str] = {}
+
+        if user_input is not None:
+            client = EgaugeJsonClient(
+                host=user_input[CONF_HOST],
+                username=user_input[CONF_USERNAME],
+                password=user_input[CONF_PASSWORD],
+                client=get_async_client(
+                    self.hass, verify_ssl=user_input[CONF_VERIFY_SSL]
+                ),
+                use_ssl=user_input[CONF_SSL],
+            )
+            try:
+                serial_number = await client.get_device_serial_number()
+                hostname = await client.get_hostname()
+            except EgaugeAuthenticationError:
+                errors["base"] = "invalid_auth"
+            except EgaugePermissionError:
+                errors["base"] = "missing_permission"
+            except ConnectError:
+                errors["base"] = "cannot_connect"
+            except Exception:  # noqa: BLE001
+                LOGGER.exception("Unexpected exception")
+                errors["base"] = "unknown"
+            else:
+                await self.async_set_unique_id(serial_number)
+                self._abort_if_unique_id_configured()
+                return self.async_create_entry(title=hostname, data=user_input)
+
+        return self.async_show_form(
+            step_id="user",
+            data_schema=self.add_suggested_values_to_schema(
+                STEP_USER_DATA_SCHEMA, user_input
+            ),
+            errors=errors,
+        )

homeassistant/components/egauge/const.py

@@ -0,0 +1,10 @@
+"""Constants for the eGauge integration."""
+
+import logging
+
+DOMAIN = "egauge"
+LOGGER = logging.getLogger(__package__)
+
+MANUFACTURER = "eGauge Systems"
+MODEL = "eGauge Energy Monitor"
+COORDINATOR_UPDATE_INTERVAL_SECONDS = 30

homeassistant/components/egauge/coordinator.py

@@ -0,0 +1,105 @@
+"""Data update coordinator for eGauge energy monitors."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import timedelta
+
+from egauge_async.exceptions import (
+    EgaugeAuthenticationError,
+    EgaugeException,
+    EgaugePermissionError,
+)
+from egauge_async.json.client import EgaugeJsonClient
+from egauge_async.json.models import RegisterInfo
+from httpx import ConnectError
+
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.const import (
+    CONF_HOST,
+    CONF_PASSWORD,
+    CONF_SSL,
+    CONF_USERNAME,
+    CONF_VERIFY_SSL,
+)
+from homeassistant.core import HomeAssistant
+from homeassistant.exceptions import ConfigEntryError
+from homeassistant.helpers.httpx_client import get_async_client
+from homeassistant.helpers.update_coordinator import DataUpdateCoordinator, UpdateFailed
+
+from .const import COORDINATOR_UPDATE_INTERVAL_SECONDS, DOMAIN, LOGGER
+
+type EgaugeConfigEntry = ConfigEntry[EgaugeDataCoordinator]
+
+
+@dataclass
+class EgaugeData:
+    """Data from eGauge device."""
+
+    measurements: dict[str, float]  # Instantaneous values (W, V, A, etc.)
+    counters: dict[str, float]  # Cumulative values (Ws)
+    register_info: dict[str, RegisterInfo]  # Metadata for all registers
+
+
+class EgaugeDataCoordinator(DataUpdateCoordinator[EgaugeData]):
+    """Class to manage fetching eGauge data."""
+
+    serial_number: str
+    hostname: str
+
+    def __init__(self, hass: HomeAssistant, config_entry: ConfigEntry) -> None:
+        """Initialize the coordinator."""
+        super().__init__(
+            hass,
+            logger=LOGGER,
+            name=DOMAIN,
+            update_interval=timedelta(seconds=COORDINATOR_UPDATE_INTERVAL_SECONDS),
+            config_entry=config_entry,
+        )
+        self.client = EgaugeJsonClient(
+            host=config_entry.data[CONF_HOST],
+            username=config_entry.data[CONF_USERNAME],
+            password=config_entry.data[CONF_PASSWORD],
+            client=get_async_client(
+                hass, verify_ssl=config_entry.data[CONF_VERIFY_SSL]
+            ),
+            use_ssl=config_entry.data[CONF_SSL],
+        )
+        # Populated in _async_setup
+        self._register_info: dict[str, RegisterInfo] = {}
+
+    async def _async_setup(self) -> None:
+        try:
+            self.serial_number = await self.client.get_device_serial_number()
+            self.hostname = await self.client.get_hostname()
+            self._register_info = await self.client.get_register_info()
+        except (
+            EgaugeAuthenticationError,
+            EgaugePermissionError,
+            EgaugeException,
+        ) as err:
+            # EgaugeAuthenticationError and EgaugePermissionError will raise ConfigEntryAuthFailed once reauth is implemented
+            raise ConfigEntryError from err
+        except ConnectError as err:
+            raise UpdateFailed(f"Error fetching device info: {err}") from err
+
+    async def _async_update_data(self) -> EgaugeData:
+        """Fetch data from eGauge device."""
+        try:
+            measurements = await self.client.get_current_measurements()
+            counters = await self.client.get_current_counters()
+        except (
+            EgaugeAuthenticationError,
+            EgaugePermissionError,
+            EgaugeException,
+        ) as err:
+            # will raise ConfigEntryAuthFailed once reauth is implemented
+            raise ConfigEntryError("Error fetching device info: {err}") from err
+        except ConnectError as err:
+            raise UpdateFailed(f"Error fetching device info: {err}") from err
+
+        return EgaugeData(
+            measurements=measurements,
+            counters=counters,
+            register_info=self._register_info,
+        )

homeassistant/components/egauge/entity.py

@@ -0,0 +1,35 @@
+"""Base entity for the eGauge integration."""
+
+from __future__ import annotations
+
+from homeassistant.helpers.device_registry import DeviceInfo
+from homeassistant.helpers.update_coordinator import CoordinatorEntity
+
+from .const import DOMAIN, MANUFACTURER, MODEL
+from .coordinator import EgaugeDataCoordinator
+
+
+class EgaugeEntity(CoordinatorEntity[EgaugeDataCoordinator]):
+    """Base entity for eGauge sensors."""
+
+    _attr_has_entity_name = True
+
+    def __init__(
+        self,
+        coordinator: EgaugeDataCoordinator,
+        register_name: str,
+    ) -> None:
+        """Initialize the eGauge entity."""
+        super().__init__(coordinator)
+
+        register_identifier = f"{coordinator.serial_number}_{register_name}"
+        register_name = f"{coordinator.hostname} {register_name}"
+
+        # Device info using coordinator's cached data
+        self._attr_device_info = DeviceInfo(
+            identifiers={(DOMAIN, register_identifier)},
+            name=register_name,
+            manufacturer=MANUFACTURER,
+            model=MODEL,
+            via_device=(DOMAIN, coordinator.serial_number),
+        )

homeassistant/components/egauge/manifest.json

@@ -0,0 +1,11 @@
+{
+  "domain": "egauge",
+  "name": "eGauge",
+  "codeowners": ["@neggert"],
+  "config_flow": true,
+  "documentation": "https://www.home-assistant.io/integrations/egauge",
+  "integration_type": "device",
+  "iot_class": "local_polling",
+  "quality_scale": "bronze",
+  "requirements": ["egauge-async==0.4.0"]
+}

homeassistant/components/egauge/quality_scale.yaml

@@ -0,0 +1,74 @@
+rules:
+  # Bronze
+  action-setup:
+    status: exempt
+    comment: Integration does not register custom actions
+  appropriate-polling: done
+  brands: done
+  common-modules: done
+  config-flow: done
+  config-flow-test-coverage: done
+  dependency-transparency: done
+  docs-actions:
+    status: exempt
+    comment: Integration does not register custom actions
+  docs-high-level-description: done
+  docs-installation-instructions: done
+  docs-removal-instructions: done
+  entity-event-setup:
+    status: exempt
+    comment: Integration does not subscribe to events
+  entity-unique-id: done
+  has-entity-name: done
+  runtime-data: done
+  test-before-configure: done
+  test-before-setup: done
+  unique-config-entry: done
+
+  # Silver
+  action-exceptions:
+    status: exempt
+    comment: Integration does not register actions
+  config-entry-unloading: done
+  docs-configuration-parameters:
+    status: exempt
+    comment: Integration does not expose configuration options
+  docs-installation-parameters: done
+  entity-unavailable: done
+  integration-owner: done
+  log-when-unavailable: done
+  parallel-updates: todo
+  reauthentication-flow: todo
+  test-coverage: done
+
+  # Gold
+  devices: done
+  diagnostics: todo
+  discovery: todo
+  discovery-update-info: todo
+  docs-data-update: done
+  docs-examples: todo
+  docs-known-limitations: done
+  docs-supported-devices: done
+  docs-supported-functions: done
+  docs-troubleshooting: done
+  docs-use-cases: todo
+  dynamic-devices: todo
+  entity-category: done
+  entity-device-class: done
+  entity-disabled-by-default:
+    status: exempt
+    comment: Integration only has essential entities
+  entity-translations: done
+  exception-translations: todo
+  icon-translations:
+    status: exempt
+    comment: Integration uses standard device class icons
+  reconfiguration-flow: todo
+  repair-issues: todo
+  stale-devices: todo
+
+  # Platinum
+  async-dependency: done
+  inject-websession: done
+  strict-typing: todo