0.1.1: diagnostic sensor "Last successful update"

Per-device timestamp entity (entity_category=DIAGNOSTIC,
device_class=TIMESTAMP) showing when the coordinator last completed a
successful poll. Lets users distinguish "polling alive but DSO has no
fresh data" from "polling broken" without digging into logs.

Coordinator now stamps EacData.last_success_time at the end of every
successful refresh; the sensor reads it. One sensor per active service
point (= per device).

Bumps manifest.json version 0.1.0 → 0.1.1.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: SantaFox

custom_components/eac_cyprus/coordinator.py

@@ -3,7 +3,7 @@
 
 import logging
 from dataclasses import dataclass
-from datetime import datetime, timedelta, timezone
+from datetime import UTC, datetime, timedelta
 
 from homeassistant.config_entries import ConfigEntry
 from homeassistant.core import HomeAssistant
@@ -45,6 +45,7 @@ class EacData:
     """What the coordinator hands to entities."""
     user: UserDetails
     points: dict[str, ServicePointState]  # keyed by service-point id
+    last_success_time: datetime  # tz-aware UTC; surfaced via a diagnostic sensor
 
 
 class EacCoordinator(DataUpdateCoordinator[EacData]):
@@ -69,7 +70,7 @@ async def _async_update_data(self) -> EacData:
         except EacApiError as err:
             raise UpdateFailed(f"API error: {err}") from err
 
-        end = datetime.now(timezone.utc)
+        end = datetime.now(UTC)
         start = end - timedelta(days=HISTORY_DAYS)
 
         points: dict[str, ServicePointState] = {}
@@ -113,7 +114,7 @@ async def _async_update_data(self) -> EacData:
                 service_point=sp, active_meter=active_meter, channels=channels
             )
 
-        return EacData(user=user, points=points)
+        return EacData(user=user, points=points, last_success_time=datetime.now(UTC))
 
 
 def _latest_reading(channels: list[ChannelReadings], channel_id: str) -> Reading | None:

custom_components/eac_cyprus/manifest.json

@@ -9,5 +9,5 @@
   "iot_class": "cloud_polling",
   "issue_tracker": "https://github.com/SantaFox/ha-eac/issues",
   "requirements": ["eac-dso-portal==0.1.0"],
-  "version": "0.1.0"
+  "version": "0.1.1"
 }

custom_components/eac_cyprus/sensor.py

@@ -26,6 +26,7 @@
 )
 from homeassistant.core import HomeAssistant, callback
 from homeassistant.helpers.device_registry import DeviceInfo
+from homeassistant.helpers.entity import EntityCategory
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
 from homeassistant.helpers.update_coordinator import CoordinatorEntity
 
@@ -122,25 +123,51 @@ async def async_setup_entry(
     """Create sensors for all currently-known channels and watch for new ones."""
     coordinator: EacCoordinator = hass.data[DOMAIN][entry.entry_id]
 
-    known: set[tuple[str, str]] = set()  # (service_point_id, channel_id)
+    known_channels: set[tuple[str, str]] = set()  # (service_point_id, channel_id)
+    known_diagnostic: set[str] = set()  # service_point_id
 
     @callback
     def _add_new_entities() -> None:
-        new_entities: list[EacChannelSensor] = []
+        new_entities: list[CoordinatorEntity[EacCoordinator]] = []
         for sp_state in coordinator.data.points.values():
             for ch_state in sp_state.channels.values():
                 key = (sp_state.service_point.id, ch_state.channel.id)
-                if key in known:
+                if key in known_channels:
                     continue
-                known.add(key)
-                new_entities.append(EacChannelSensor(coordinator, sp_state, ch_state.channel.id))
+                known_channels.add(key)
+                new_entities.append(
+                    EacChannelSensor(coordinator, sp_state, ch_state.channel.id)
+                )
+            # One diagnostic sensor per device (= per active service point that
+            # produced a meter config). Inactive points don't get a device, so
+            # they don't get one either.
+            if (
+                sp_state.active_meter is not None
+                and sp_state.service_point.id not in known_diagnostic
+            ):
+                known_diagnostic.add(sp_state.service_point.id)
+                new_entities.append(EacLastUpdateSensor(coordinator, sp_state))
         if new_entities:
             async_add_entities(new_entities)
 
     _add_new_entities()
     entry.async_on_unload(coordinator.async_add_listener(_add_new_entities))
 
 
+def _device_info_for(sp_state: ServicePointState) -> DeviceInfo:
+    meter = sp_state.active_meter
+    return DeviceInfo(
+        identifiers={(DOMAIN, sp_state.service_point.id)},
+        name=sp_state.service_point.address or f"EAC {sp_state.service_point.id}",
+        manufacturer=meter.manufacturer if meter else MANUFACTURER,
+        model=meter.model if meter else None,
+        serial_number=meter.serial_number if meter else sp_state.service_point.serial_number,
+        configuration_url=(
+            f"https://meterreading-dso.eac.com.cy/sp/{sp_state.service_point.id}"
+        ),
+    )
+
+
 class EacChannelSensor(CoordinatorEntity[EacCoordinator], SensorEntity):
     """One reading channel of one service point."""
 
@@ -160,15 +187,7 @@ def __init__(
         self.entity_description = _description_for(ch.uom, ch.type, ch.interval)
         self._attr_unique_id = f"{self._sp_id}_{self._channel_id}"
 
-        meter = sp_state.active_meter
-        self._attr_device_info = DeviceInfo(
-            identifiers={(DOMAIN, self._sp_id)},
-            name=sp_state.service_point.address or f"EAC {self._sp_id}",
-            manufacturer=meter.manufacturer if meter else MANUFACTURER,
-            model=meter.model if meter else None,
-            serial_number=meter.serial_number if meter else sp_state.service_point.serial_number,
-            configuration_url=f"https://meterreading-dso.eac.com.cy/sp/{self._sp_id}",
-        )
+        self._attr_device_info = _device_info_for(sp_state)
 
     @property
     def _ch_state(self):
@@ -219,3 +238,32 @@ def extra_state_attributes(self) -> dict[str, Any]:
 
 def _iso(dt: datetime | None) -> str | None:
     return dt.isoformat() if dt is not None else None
+
+
+class EacLastUpdateSensor(CoordinatorEntity[EacCoordinator], SensorEntity):
+    """Diagnostic timestamp showing when the coordinator last refreshed.
+
+    Lets users distinguish "polling is alive but the DSO has no fresh data"
+    from "polling is broken" without digging into logs. Reports the same
+    value across every device the integration owns — there is one polling
+    cycle for the whole config entry.
+    """
+
+    _attr_has_entity_name = True
+    _attr_entity_category = EntityCategory.DIAGNOSTIC
+    _attr_device_class = SensorDeviceClass.TIMESTAMP
+    _attr_name = "Last successful update"
+
+    def __init__(
+        self, coordinator: EacCoordinator, sp_state: ServicePointState
+    ) -> None:
+        super().__init__(coordinator)
+        self._sp_id = sp_state.service_point.id
+        self._attr_unique_id = f"{self._sp_id}_last_update"
+        self._attr_device_info = _device_info_for(sp_state)
+
+    @property
+    def native_value(self) -> datetime | None:
+        if self.coordinator.data is None:
+            return None
+        return self.coordinator.data.last_success_time

tests/test_coordinator.py

@@ -26,13 +26,19 @@ def _make_entry(hass: HomeAssistant) -> MockConfigEntry:
 async def test_coordinator_update_active_and_inactive_points(
     hass: HomeAssistant, mock_client
 ) -> None:
+    from datetime import UTC, datetime, timedelta
+
     entry = _make_entry(hass)
     coord = EacCoordinator(hass, mock_client, entry)
     data = await coord._async_update_data()
 
     assert data.user.name == "Test User"
     assert set(data.points) == {"111111111111", "222222222222"}
 
+    # last_success_time should be set to "now" on every successful refresh.
+    assert data.last_success_time.tzinfo is not None
+    assert datetime.now(UTC) - data.last_success_time < timedelta(seconds=10)
+
     active = data.points["111111111111"]
     assert active.active_meter is not None
     assert active.active_meter.serial_number == "NEW123"

tests/test_sensor.py

@@ -33,8 +33,9 @@ async def test_full_setup_creates_sensors(
     states = [
         s for s in hass.states.async_all() if s.entity_id.startswith("sensor.")
     ]
-    # One sensor per channel that returned data — 2 channels for the active SP.
-    assert len(states) == 2
+    # Two channel sensors + one diagnostic "Last successful update" for the
+    # single active service point.
+    assert len(states) == 3
 
     # Check the cumulative total sensor.
     total = next(s for s in states if "total_24h" in s.entity_id)
@@ -46,6 +47,24 @@ async def test_full_setup_creates_sensors(
     assert "last_cumulative_reading" in total.attributes
 
 
+async def test_last_update_diagnostic_sensor(
+    hass: HomeAssistant, patch_eac_client
+) -> None:
+    """Each active service point exposes a TIMESTAMP diagnostic entity."""
+    from datetime import datetime
+
+    await _setup_integration(hass, patch_eac_client)
+    state = next(
+        s
+        for s in hass.states.async_all()
+        if s.entity_id.startswith("sensor.") and "last_successful_update" in s.entity_id
+    )
+    assert state.attributes["device_class"] == SensorDeviceClass.TIMESTAMP
+    # The state is an ISO-8601 timestamp set by the coordinator on success.
+    parsed = datetime.fromisoformat(state.state)
+    assert parsed.tzinfo is not None
+
+
 async def test_30min_channel_is_power(
     hass: HomeAssistant, patch_eac_client
 ) -> None: