feat: server telemetry, update entity, sync-clock controls

- Server device exposing CPU/RAM/GPU/temperature/battery sensors via /api/v1/system/performance, plus last-restart timestamp (cached with jitter threshold so the recorder doesn't see poll wobble) and version. - Update entity backed by /api/v1/system/update — installs via /apply, hides the install button when the server reports can_auto_update=false. - Sync-clock entities: reset button, speed number, running switch, and the event listener now refreshes on entity_changed events too. - Bump manifest to 0.4.0.
2026-04-27 01:35:42 +03:00
parent e8f2b5e528
commit a666d9eb9c
12 changed files with 1080 additions and 23 deletions
@@ -2,6 +2,7 @@

 from __future__ import annotations

+from datetime import datetime
 import logging
 from typing import Any

@@ -11,7 +12,14 @@ from homeassistant.components.sensor import (
    SensorStateClass,
 )
 from homeassistant.config_entries import ConfigEntry
+from homeassistant.const import (
+    PERCENTAGE,
+    UnitOfInformation,
+    UnitOfTemperature,
+    UnitOfTime,
+)
 from homeassistant.core import HomeAssistant
+from homeassistant.helpers.entity import EntityCategory
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
 from homeassistant.helpers.update_coordinator import CoordinatorEntity

@@ -47,9 +55,55 @@ async def async_setup_entry(
            if info.get("target_type") == TARGET_TYPE_HA_LIGHT:
                entities.append(HALightMappedLightsSensor(coordinator, target_id, entry.entry_id))

+    if coordinator.data:
+        for clock in coordinator.data.get("sync_clocks", []):
+            entities.append(SyncClockElapsedSensor(coordinator, clock["id"], entry.entry_id))
+
+    entities.extend(_build_server_sensors(coordinator, entry.entry_id))
+
    async_add_entities(entities)


+def _build_server_sensors(
+    coordinator: LedGrabCoordinator,
+    entry_id: str,
+) -> list[SensorEntity]:
+    """Build the server-level telemetry sensors.
+
+    GPU/CPU-temp/battery sensors are only registered when the first refresh
+    actually carries those readings — we don't want phantom unavailable
+    entities on hardware that doesn't support a metric. A reload picks up
+    metrics that come online later (e.g. user installs LibreHardwareMonitor).
+    """
+    system = (coordinator.data or {}).get("system") or {}
+    perf = system.get("performance") or {}
+    health = system.get("health")
+
+    sensors: list[SensorEntity] = [
+        ServerCpuPercentSensor(coordinator, entry_id),
+        ServerRamPercentSensor(coordinator, entry_id),
+        ServerAppCpuPercentSensor(coordinator, entry_id),
+        ServerAppRamSensor(coordinator, entry_id),
+        ServerVersionSensor(coordinator, entry_id),
+    ]
+
+    if health is not None:
+        # Only meaningful when /health actually responded on first refresh.
+        sensors.append(ServerLastRestartSensor(coordinator, entry_id))
+
+    if perf.get("gpu") is not None:
+        sensors.append(ServerGpuUtilizationSensor(coordinator, entry_id))
+        sensors.append(ServerGpuTemperatureSensor(coordinator, entry_id))
+
+    if perf.get("cpu_temp_c") is not None:
+        sensors.append(ServerCpuTemperatureSensor(coordinator, entry_id))
+
+    if perf.get("battery_percent") is not None:
+        sensors.append(ServerBatterySensor(coordinator, entry_id))
+
+    return sensors
+
+
 class LedGrabFPSSensor(CoordinatorEntity, SensorEntity):
    """FPS sensor for a LED Screen Controller target."""

@@ -160,6 +214,60 @@ class LedGrabStatusSensor(CoordinatorEntity, SensorEntity):
        return self.coordinator.data.get("targets", {}).get(self._target_id)


+class SyncClockElapsedSensor(CoordinatorEntity, SensorEntity):
+    """Elapsed seconds since the sync clock last reset.
+
+    Disabled by default — the value advances on every coordinator poll
+    (~3s) while the clock is running, which would write a recorder row
+    each refresh. Power users can enable it explicitly.
+    """
+
+    _attr_has_entity_name = True
+    _attr_state_class = SensorStateClass.MEASUREMENT
+    _attr_device_class = SensorDeviceClass.DURATION
+    _attr_native_unit_of_measurement = UnitOfTime.SECONDS
+    _attr_icon = "mdi:timer-outline"
+    _attr_entity_category = EntityCategory.DIAGNOSTIC
+    _attr_entity_registry_enabled_default = False
+    _attr_suggested_display_precision = 1
+
+    def __init__(
+        self,
+        coordinator: LedGrabCoordinator,
+        clock_id: str,
+        entry_id: str,
+    ) -> None:
+        super().__init__(coordinator)
+        self._clock_id = clock_id
+        self._entry_id = entry_id
+        self._attr_unique_id = f"{clock_id}_elapsed"
+        self._attr_translation_key = "sync_clock_elapsed"
+
+    @property
+    def device_info(self) -> dict[str, Any]:
+        return {"identifiers": {(DOMAIN, self._clock_id)}}
+
+    @property
+    def native_value(self) -> float | None:
+        clock = self._get_clock()
+        if not clock:
+            return None
+        elapsed = clock.get("elapsed_time")
+        return float(elapsed) if elapsed is not None else None
+
+    @property
+    def available(self) -> bool:
+        return self._get_clock() is not None
+
+    def _get_clock(self) -> dict[str, Any] | None:
+        if not self.coordinator.data:
+            return None
+        for clock in self.coordinator.data.get("sync_clocks", []):
+            if clock.get("id") == self._clock_id:
+                return clock
+        return None
+
+
 class HALightMappedLightsSensor(CoordinatorEntity, SensorEntity):
    """Sensor showing the number of mapped HA lights for an HA Light target."""

@@ -223,3 +331,274 @@ class HALightMappedLightsSensor(CoordinatorEntity, SensorEntity):
        if not self.coordinator.data:
            return None
        return self.coordinator.data.get("targets", {}).get(self._target_id)
+
+
+# ─────────────────────────── Server-level sensors ───────────────────────────
+
+
+class _ServerSensorBase(CoordinatorEntity, SensorEntity):
+    """Shared plumbing for sensors attached to the synthetic Server device."""
+
+    _attr_has_entity_name = True
+    _attr_entity_category = EntityCategory.DIAGNOSTIC
+
+    def __init__(
+        self,
+        coordinator: LedGrabCoordinator,
+        entry_id: str,
+        unique_suffix: str,
+        translation_key: str,
+    ) -> None:
+        super().__init__(coordinator)
+        self._entry_id = entry_id
+        self._attr_unique_id = f"{entry_id}_server_{unique_suffix}"
+        self._attr_translation_key = translation_key
+
+    @property
+    def device_info(self) -> dict[str, Any]:
+        return {"identifiers": {(DOMAIN, f"{self._entry_id}_server")}}
+
+    def _perf(self) -> dict[str, Any] | None:
+        if not self.coordinator.data:
+            return None
+        system = self.coordinator.data.get("system") or {}
+        return system.get("performance")
+
+    @property
+    def available(self) -> bool:
+        # Performance metrics are missing whenever /api/v1/system/performance
+        # fails — surface that as unavailable instead of stale numbers.
+        return self._perf() is not None
+
+
+class ServerCpuPercentSensor(_ServerSensorBase):
+    """System-wide CPU usage on the led-grab server."""
+
+    _attr_state_class = SensorStateClass.MEASUREMENT
+    _attr_native_unit_of_measurement = PERCENTAGE
+    _attr_icon = "mdi:cpu-64-bit"
+    _attr_suggested_display_precision = 1
+
+    def __init__(self, coordinator: LedGrabCoordinator, entry_id: str) -> None:
+        super().__init__(coordinator, entry_id, "cpu_percent", "server_cpu_percent")
+
+    @property
+    def native_value(self) -> float | None:
+        perf = self._perf()
+        return None if perf is None else perf.get("cpu_percent")
+
+    @property
+    def extra_state_attributes(self) -> dict[str, Any]:
+        perf = self._perf() or {}
+        return {"cpu_name": perf.get("cpu_name")}
+
+
+class ServerRamPercentSensor(_ServerSensorBase):
+    """System-wide RAM usage on the led-grab server."""
+
+    _attr_state_class = SensorStateClass.MEASUREMENT
+    _attr_native_unit_of_measurement = PERCENTAGE
+    _attr_icon = "mdi:memory"
+    _attr_suggested_display_precision = 1
+
+    def __init__(self, coordinator: LedGrabCoordinator, entry_id: str) -> None:
+        super().__init__(coordinator, entry_id, "ram_percent", "server_ram_percent")
+
+    @property
+    def native_value(self) -> float | None:
+        perf = self._perf()
+        return None if perf is None else perf.get("ram_percent")
+
+    @property
+    def extra_state_attributes(self) -> dict[str, Any]:
+        perf = self._perf() or {}
+        return {
+            "used_mb": perf.get("ram_used_mb"),
+            "total_mb": perf.get("ram_total_mb"),
+        }
+
+
+class ServerAppCpuPercentSensor(_ServerSensorBase):
+    """CPU usage of the led-grab process itself."""
+
+    _attr_state_class = SensorStateClass.MEASUREMENT
+    _attr_native_unit_of_measurement = PERCENTAGE
+    _attr_icon = "mdi:application-cog"
+    _attr_suggested_display_precision = 1
+    _attr_entity_registry_enabled_default = False
+
+    def __init__(self, coordinator: LedGrabCoordinator, entry_id: str) -> None:
+        super().__init__(coordinator, entry_id, "app_cpu_percent", "server_app_cpu_percent")
+
+    @property
+    def native_value(self) -> float | None:
+        perf = self._perf()
+        return None if perf is None else perf.get("app_cpu_percent")
+
+
+class ServerAppRamSensor(_ServerSensorBase):
+    """Resident memory of the led-grab process."""
+
+    _attr_state_class = SensorStateClass.MEASUREMENT
+    _attr_device_class = SensorDeviceClass.DATA_SIZE
+    _attr_native_unit_of_measurement = UnitOfInformation.MEGABYTES
+    _attr_icon = "mdi:memory"
+    _attr_suggested_display_precision = 1
+    _attr_entity_registry_enabled_default = False
+
+    def __init__(self, coordinator: LedGrabCoordinator, entry_id: str) -> None:
+        super().__init__(coordinator, entry_id, "app_ram_mb", "server_app_ram")
+
+    @property
+    def native_value(self) -> float | None:
+        perf = self._perf()
+        return None if perf is None else perf.get("app_ram_mb")
+
+
+class ServerGpuUtilizationSensor(_ServerSensorBase):
+    """GPU utilization (NVML)."""
+
+    _attr_state_class = SensorStateClass.MEASUREMENT
+    _attr_native_unit_of_measurement = PERCENTAGE
+    _attr_icon = "mdi:expansion-card"
+    _attr_suggested_display_precision = 1
+
+    def __init__(self, coordinator: LedGrabCoordinator, entry_id: str) -> None:
+        super().__init__(coordinator, entry_id, "gpu_utilization", "server_gpu_utilization")
+
+    @property
+    def native_value(self) -> float | None:
+        perf = self._perf()
+        if perf is None:
+            return None
+        gpu = perf.get("gpu") or {}
+        return gpu.get("utilization")
+
+    @property
+    def extra_state_attributes(self) -> dict[str, Any]:
+        perf = self._perf() or {}
+        gpu = perf.get("gpu") or {}
+        return {
+            "name": gpu.get("name"),
+            "memory_used_mb": gpu.get("memory_used_mb"),
+            "memory_total_mb": gpu.get("memory_total_mb"),
+            "app_memory_mb": gpu.get("app_memory_mb"),
+        }
+
+    @property
+    def available(self) -> bool:
+        perf = self._perf()
+        return perf is not None and perf.get("gpu") is not None
+
+
+class ServerGpuTemperatureSensor(_ServerSensorBase):
+    """GPU temperature (NVML)."""
+
+    _attr_state_class = SensorStateClass.MEASUREMENT
+    _attr_device_class = SensorDeviceClass.TEMPERATURE
+    _attr_native_unit_of_measurement = UnitOfTemperature.CELSIUS
+    _attr_suggested_display_precision = 0
+
+    def __init__(self, coordinator: LedGrabCoordinator, entry_id: str) -> None:
+        super().__init__(coordinator, entry_id, "gpu_temp", "server_gpu_temp")
+
+    @property
+    def native_value(self) -> float | None:
+        perf = self._perf()
+        if perf is None:
+            return None
+        gpu = perf.get("gpu") or {}
+        return gpu.get("temperature_c")
+
+    @property
+    def available(self) -> bool:
+        perf = self._perf()
+        return perf is not None and (perf.get("gpu") or {}).get("temperature_c") is not None
+
+
+class ServerCpuTemperatureSensor(_ServerSensorBase):
+    """Hottest CPU/SoC thermal-zone reading.
+
+    Only registered when the first refresh actually reports a temperature —
+    Windows needs LibreHardwareMonitor / OpenHardwareMonitor publishing WMI
+    sensors, otherwise the field stays null.
+    """
+
+    _attr_state_class = SensorStateClass.MEASUREMENT
+    _attr_device_class = SensorDeviceClass.TEMPERATURE
+    _attr_native_unit_of_measurement = UnitOfTemperature.CELSIUS
+    _attr_suggested_display_precision = 0
+
+    def __init__(self, coordinator: LedGrabCoordinator, entry_id: str) -> None:
+        super().__init__(coordinator, entry_id, "cpu_temp", "server_cpu_temp")
+
+    @property
+    def native_value(self) -> float | None:
+        perf = self._perf()
+        return None if perf is None else perf.get("cpu_temp_c")
+
+
+class ServerBatterySensor(_ServerSensorBase):
+    """Battery charge level (laptops / portable hosts)."""
+
+    _attr_state_class = SensorStateClass.MEASUREMENT
+    _attr_device_class = SensorDeviceClass.BATTERY
+    _attr_native_unit_of_measurement = PERCENTAGE
+    _attr_suggested_display_precision = 0
+
+    def __init__(self, coordinator: LedGrabCoordinator, entry_id: str) -> None:
+        super().__init__(coordinator, entry_id, "battery", "server_battery")
+
+    @property
+    def native_value(self) -> float | None:
+        perf = self._perf()
+        return None if perf is None else perf.get("battery_percent")
+
+    @property
+    def extra_state_attributes(self) -> dict[str, Any]:
+        perf = self._perf() or {}
+        return {"temperature_c": perf.get("battery_temp_c")}
+
+
+class ServerLastRestartSensor(_ServerSensorBase):
+    """Timestamp of the last server start.
+
+    Derived from ``/health.uptime_seconds``; the coordinator caches the
+    computed boot time and only refreshes it when the candidate moves more
+    than a few seconds, so the recorder doesn't get poll-jitter writes.
+    """
+
+    _attr_device_class = SensorDeviceClass.TIMESTAMP
+    _attr_icon = "mdi:restart"
+
+    def __init__(self, coordinator: LedGrabCoordinator, entry_id: str) -> None:
+        super().__init__(coordinator, entry_id, "last_restart", "server_last_restart")
+
+    @property
+    def native_value(self) -> datetime | None:
+        if not self.coordinator.data:
+            return None
+        system = self.coordinator.data.get("system") or {}
+        return system.get("boot_time")
+
+    @property
+    def available(self) -> bool:
+        return self.native_value is not None
+
+
+class ServerVersionSensor(_ServerSensorBase):
+    """Reported led-grab server version."""
+
+    _attr_icon = "mdi:tag-outline"
+
+    def __init__(self, coordinator: LedGrabCoordinator, entry_id: str) -> None:
+        super().__init__(coordinator, entry_id, "version", "server_version")
+
+    @property
+    def native_value(self) -> str | None:
+        version = self.coordinator.server_version
+        return version if version and version != "unknown" else None
+
+    @property
+    def available(self) -> bool:
+        return self.native_value is not None