v0.4.0: mock agent, SMART FAILED fix, attention reasons entity, dynamic icons, NVMe sensor coverage

Author: DAB-LABS

README.md

@@ -273,6 +273,7 @@ Binaries output to `agent/build/`.
 | Doc | Description |
 |-----|-------------|
 | [Attention Severity Logic](docs/attention-severity-logic.md) | State machine, classification rules, notification lifecycle |
+| [Trigger → Entity Map](docs/attention-trigger-entity-map.md) | Every attention trigger mapped to its sensor entity and icon |
 | [Early Warning Attributes](docs/early-warning-attributes.md) | Which SMART attributes predict failure and why |
 | [Attribute Name Variants](docs/smart-attribute-name-variants.md) | Manufacturer-specific `smartctl` name mapping research |
 | [Mock Agent](docs/mock-agent.md) | Testing tool — fake agent with controllable drives |
@@ -284,6 +285,7 @@ Binaries output to `agent/build/`.
 - [ ] Integration icons for HA integrations page
 - [ ] MQTT agent mode
 - [ ] Custom Lovelace card
+- [ ] Temperature-based attention triggers (absolute threshold + trend over time)
 - [ ] Configurable alert thresholds via options flow
 - [ ] SAS/SCSI drive support
 

custom_components/smart_sniffer/attention.py

@@ -127,6 +127,13 @@ def evaluate_attention(
     critical_reasons: list[str] = []
     warning_reasons:  list[str] = []
 
+    # ------------------------------------------------------------------
+    # SMART overall status (applies to all protocols)
+    # ------------------------------------------------------------------
+    status = smart_data.get("smart_status", {})
+    if isinstance(status, dict) and status.get("passed") is False:
+        critical_reasons.append("SMART overall status: FAILED")
+
     # ------------------------------------------------------------------
     # NVMe evaluation
     # ------------------------------------------------------------------

custom_components/smart_sniffer/coordinator.py

@@ -109,9 +109,10 @@ def __init__(self, hass: HomeAssistant, entry: ConfigEntry) -> None:
             update_interval=timedelta(seconds=interval),
         )
 
-        # Track the last known attention state per drive for transition detection.
-        # None = drive not yet seen (first poll baseline).
+        # Track the last known attention state and reasons per drive for
+        # transition detection. None = drive not yet seen (first poll baseline).
         self._prev_state: dict[str, str | None] = {}
+        self._prev_reasons: dict[str, list[str]] = {}
 
     @property
     def _base_url(self) -> str:
@@ -177,10 +178,14 @@ async def _handle_attention_notifications(
                     drive_id, state,
                 )
                 self._prev_state[drive_id] = state
+                self._prev_reasons[drive_id] = reasons
                 continue
 
-            if state == prev:
-                continue  # No change.
+            prev_reasons = self._prev_reasons.get(drive_id, [])
+            reasons_changed = sorted(reasons) != sorted(prev_reasons)
+
+            if state == prev and not reasons_changed:
+                continue  # No change in state or reasons.
 
             notif_id = _notif_id(drive_id)
 
@@ -203,8 +208,10 @@ async def _handle_attention_notifications(
                           notification_id=notif_id)
 
             elif state in (STATE_MAYBE, STATE_YES):
-                # Attention needed — fire or escalate/de-escalate.
-                if prev == STATE_NO:
+                # Attention needed — fire, escalate/de-escalate, or refresh reasons.
+                if state == prev and reasons_changed:
+                    action = "reasons updated"
+                elif prev == STATE_NO:
                     action = "now requires attention"
                 elif prev == STATE_MAYBE and state == STATE_YES:
                     action = "ESCALATED to critical"
@@ -224,10 +231,12 @@ async def _handle_attention_notifications(
                           notification_id=notif_id)
 
             self._prev_state[drive_id] = state
+            self._prev_reasons[drive_id] = reasons
 
         # Clean up state for drives that disappeared (e.g., USB unplugged).
         removed = set(self._prev_state.keys()) - current_drive_ids
         for drive_id in removed:
             _LOGGER.debug("SMART Sniffer: %s no longer present, cleaning up", drive_id)
             del self._prev_state[drive_id]
+            self._prev_reasons.pop(drive_id, None)
             pn_dismiss(self.hass, _notif_id(drive_id))

custom_components/smart_sniffer/sensor.py

@@ -54,6 +54,8 @@
 })
 
 NVME_ONLY_KEYS: frozenset[str] = frozenset({
+    "critical_warning",
+    "media_errors",
     "available_spare",
     "available_spare_threshold",
 })
@@ -157,6 +159,20 @@
     ),
 
     # --- NVMe only ---
+    SensorEntityDescription(
+        key="critical_warning",
+        name="Critical Warning",
+        state_class=SensorStateClass.MEASUREMENT,
+        icon="mdi:alert-decagram",
+        entity_category=EntityCategory.DIAGNOSTIC,
+    ),
+    SensorEntityDescription(
+        key="media_errors",
+        name="Media Errors",
+        state_class=SensorStateClass.TOTAL_INCREASING,
+        icon="mdi:alert-decagram-outline",
+        entity_category=EntityCategory.DIAGNOSTIC,
+    ),
     SensorEntityDescription(
         key="available_spare",
         name="Available Spare",
@@ -211,6 +227,8 @@ def _extract_attribute(drive_data: dict[str, Any], key: str) -> Any | None:
             "power_cycle_count":            lambda: nvme_log.get("power_cycles"),
             "wear_leveling_count":          lambda: nvme_log.get("percentage_used"),
             "reported_uncorrectable_errors":lambda: nvme_log.get("media_errors"),
+            "critical_warning":             lambda: nvme_log.get("critical_warning"),
+            "media_errors":                 lambda: nvme_log.get("media_errors"),
             "available_spare":              lambda: nvme_log.get("available_spare"),
             "available_spare_threshold":    lambda: nvme_log.get("available_spare_threshold"),
         }
@@ -341,13 +359,44 @@ async def async_setup_entry(
             SmartSnifferAttentionSensor(coordinator, drive_id, drive_data)
         )
 
+        # --- Attention Reasons sensor (one per drive, always created) ---
+        entities.append(
+            SmartSnifferAttentionReasonsSensor(coordinator, drive_id, drive_data)
+        )
+
     async_add_entities(entities, update_before_add=False)
 
 
 # ---------------------------------------------------------------------------
 # SMART attribute sensor
 # ---------------------------------------------------------------------------
 
+# Sensor keys whose non-zero values trigger critical attention (YES).
+_CRITICAL_SENSOR_KEYS: frozenset[str] = frozenset({
+    "reallocated_sector_count",
+    "current_pending_sector_count",
+    "reported_uncorrectable_errors",
+    "critical_warning",
+    "media_errors",
+})
+
+# Sensor keys whose non-zero values trigger warning attention (MAYBE).
+_WARNING_SENSOR_KEYS: frozenset[str] = frozenset({
+    "reallocated_event_count",
+    "spin_retry_count",
+    "command_timeout",
+})
+
+# NVMe sensors with threshold-based triggers (not simple non-zero).
+# These are handled specially in the icon property.
+_NVME_SPARE_KEY = "available_spare"
+_NVME_WEAR_KEY = "wear_leveling_count"
+
+# Alert icons — used when a diagnostic sensor is actively triggering attention.
+_ALERT_ICON_CRITICAL = "mdi:alert-octagon"
+_ALERT_ICON_WARNING  = "mdi:alert-circle"
+
+
 class SmartSnifferSensor(CoordinatorEntity[SmartSnifferCoordinator], SensorEntity):
     """Representation of a single SMART attribute as a HA sensor."""
 
@@ -363,6 +412,7 @@ def __init__(
         super().__init__(coordinator)
         self.entity_description = description
         self._drive_id = drive_id
+        self._default_icon = description.icon
 
         model = drive_data.get("model", "Unknown Drive")
         serial = drive_data.get("serial", drive_id)
@@ -378,6 +428,40 @@ def __init__(
             "serial_number": serial,
         }
 
+    @property
+    def icon(self) -> str | None:
+        """Dynamic icon — switches to alert icon when this sensor triggers attention."""
+        key = self.entity_description.key
+        value = self.native_value
+
+        # Non-zero triggers (ATA + NVMe critical_warning/media_errors).
+        if value is not None and isinstance(value, (int, float)) and value > 0:
+            if key in _CRITICAL_SENSOR_KEYS:
+                return _ALERT_ICON_CRITICAL
+            if key in _WARNING_SENSOR_KEYS:
+                return _ALERT_ICON_WARNING
+
+        # NVMe available_spare — threshold-based (needs drive's own threshold).
+        if key == _NVME_SPARE_KEY and value is not None and isinstance(value, (int, float)):
+            # Get the threshold from the same drive's data.
+            drive_data = self.coordinator.data.get(self._drive_id, {})
+            threshold = _extract_attribute(drive_data, "available_spare_threshold")
+            if threshold is not None and value <= threshold:
+                return _ALERT_ICON_CRITICAL
+            if value < 20:
+                return _ALERT_ICON_WARNING
+
+        # NVMe percentage_used (mapped to wear_leveling_count) — ≥90% = warning.
+        if key == _NVME_WEAR_KEY and value is not None and isinstance(value, (int, float)):
+            if value >= 90:
+                return _ALERT_ICON_WARNING
+
+        # SMART Status — FAILED = critical.
+        if key == "smart_status" and value == "FAILED":
+            return _ALERT_ICON_CRITICAL
+
+        return self._default_icon
+
     @property
     def native_value(self) -> Any | None:
         drive_data = self.coordinator.data.get(self._drive_id)
@@ -475,6 +559,77 @@ def extra_state_attributes(self) -> dict[str, Any]:
         }
 
 
+# ---------------------------------------------------------------------------
+# Attention Reasons sensor (text: human-readable trigger summary)
+# ---------------------------------------------------------------------------
+
+class SmartSnifferAttentionReasonsSensor(
+    CoordinatorEntity[SmartSnifferCoordinator], SensorEntity
+):
+    """Text sensor showing human-readable reasons for the current attention state.
+
+    Provides an at-a-glance answer to "why does this drive need attention?"
+    directly on the device page, without needing to inspect entity attributes.
+
+    When attention is NO:          "No issues detected"
+    When attention is UNSUPPORTED: "No usable SMART data"
+    When attention is MAYBE/YES:   Semicolon-separated list of trigger reasons.
+    """
+
+    _attr_has_entity_name = True
+    _attr_name = "Attention Reasons"
+    _attr_icon = "mdi:text-box-search-outline"
+    _attr_entity_category = EntityCategory.DIAGNOSTIC
+
+    def __init__(
+        self,
+        coordinator: SmartSnifferCoordinator,
+        drive_id: str,
+        drive_data: dict[str, Any],
+    ) -> None:
+        super().__init__(coordinator)
+        self._drive_id = drive_id
+
+        model = drive_data.get("model", "Unknown Drive")
+        serial = drive_data.get("serial", drive_id)
+
+        self._attr_unique_id = (
+            f"{coordinator.config_entry.entry_id}_{drive_id}_attention_reasons"
+        )
+        self._attr_device_info = {
+            "identifiers": {(DOMAIN, drive_id)},
+            "name": f"{model} ({serial})",
+            "manufacturer": _guess_manufacturer(model),
+            "model": model,
+            "serial_number": serial,
+        }
+
+    @property
+    def native_value(self) -> str:
+        drive_data = self.coordinator.data.get(self._drive_id)
+        if drive_data is None:
+            return "Drive data unavailable"
+        state, _, reasons = evaluate_attention(drive_data)
+        if state == STATE_NO:
+            return "No issues detected"
+        if state == STATE_UNSUPPORTED:
+            return "No usable SMART data"
+        return "; ".join(reasons)
+
+    @property
+    def icon(self) -> str:
+        """Dynamic icon matching the attention state."""
+        drive_data = self.coordinator.data.get(self._drive_id)
+        if drive_data is None:
+            return "mdi:text-box-search-outline"
+        state, _, _ = evaluate_attention(drive_data)
+        if state == STATE_YES:
+            return "mdi:alert-octagon"
+        if state == STATE_MAYBE:
+            return "mdi:alert-circle-outline"
+        return "mdi:text-box-search-outline"
+
+
 # ---------------------------------------------------------------------------
 # Helpers
 # ---------------------------------------------------------------------------

docs/attention-trigger-entity-map.md

@@ -0,0 +1,102 @@
+# Attention Trigger → Entity Map
+
+Every attribute that can trigger an attention state change must have a visible sensor entity on the HA device page, with a dynamic icon that reflects whether it's currently contributing to the alert. This document maps each trigger to its entity and tracks coverage.
+
+Last updated: v0.3.1
+
+---
+
+## ATA / SATA Triggers
+
+### Critical (→ YES)
+
+| smartctl Attribute | Sensor Entity | Key | Dynamic Icon |
+|---|---|---|---|
+| `Reallocated_Sector_Ct` | Reallocated Sector Count | `reallocated_sector_count` | `mdi:alert-octagon` when > 0 |
+| `Current_Pending_Sector` / `Current_Pending_Sector_Ct` / `Total_Pending_Sectors` | Current Pending Sector Count | `current_pending_sector_count` | `mdi:alert-octagon` when > 0 |
+| `Offline_Uncorrectable` / `Reported_Uncorrect` / `Uncorrectable_Error_Cnt` / `Total_Offl_Uncorrectabl` | Reported Uncorrectable Errors | `reported_uncorrectable_errors` | `mdi:alert-octagon` when > 0 |
+
+### Warning (→ MAYBE)
+
+| smartctl Attribute | Sensor Entity | Key | Dynamic Icon |
+|---|---|---|---|
+| `Reallocated_Event_Count` | Reallocated Event Count | `reallocated_event_count` | `mdi:alert-circle` when > 0 |
+| `Spin_Retry_Count` | Spin Retry Count | `spin_retry_count` | `mdi:alert-circle` when > 0 |
+| `Command_Timeout` | Command Timeout | `command_timeout` | `mdi:alert-circle` when > 0 |
+
+---
+
+## NVMe Triggers
+
+### Critical (→ YES)
+
+| NVMe Health Log Field | Sensor Entity | Key | Dynamic Icon |
+|---|---|---|---|
+| `critical_warning` (bitmask ≠ 0) | Critical Warning | `critical_warning` | `mdi:alert-octagon` when ≠ 0 |
+| `media_errors` (≥ 1) | Media Errors | `media_errors` | `mdi:alert-octagon` when > 0 |
+| `available_spare` ≤ `available_spare_threshold` | Available Spare | `available_spare` | `mdi:alert-octagon` when ≤ threshold |
+
+### Warning (→ MAYBE)
+
+| NVMe Health Log Field | Sensor Entity | Key | Dynamic Icon |
+|---|---|---|---|
+| `available_spare` < 20% | Available Spare | `available_spare` | `mdi:alert-circle` when < 20 |
+| `percentage_used` ≥ 90% | Wear Leveling / Percentage Used | `wear_leveling_count` | `mdi:alert-circle` when ≥ 90 |
+
+---
+
+## Universal Triggers
+
+| Condition | Sensor Entity | Key | Dynamic Icon |
+|---|---|---|---|
+| `smart_status.passed` = false | SMART Status | `smart_status` | `mdi:alert-octagon` when "FAILED" |
+
+---
+
+## Summary Entities (per drive, always created)
+
+| Entity | Type | Description |
+|---|---|---|
+| **Attention Needed** | Enum sensor | Primary state: NO / MAYBE / YES / UNSUPPORTED. Icon changes per state. Attributes include `severity`, `reasons` list, and `issue_count`. |
+| **Attention Reasons** | Text sensor (diagnostic) | Human-readable semicolon-separated list of what's triggering the alert. Shows "No issues detected" when clean, "No usable SMART data" for UNSUPPORTED. Icon matches attention severity. |
+
+---
+
+## Icon Behavior
+
+All diagnostic sensors that participate in attention evaluation have dynamic icons:
+
+- **Normal state (value is 0 or within safe range):** Default icon from `SensorEntityDescription` (varies per sensor — thermometer, clock, harddisk, etc.).
+- **Warning trigger active (MAYBE):** Switches to `mdi:alert-circle` (filled circle with exclamation).
+- **Critical trigger active (YES):** Switches to `mdi:alert-octagon` (octagon stop sign with exclamation).
+
+Icons revert to default automatically when the triggering value returns to safe range.
+
+The Attention Needed sensor itself has state-based icons: `mdi:check-circle-outline` (NO), `mdi:alert-circle-outline` (MAYBE), `mdi:alert-octagon` (YES), `mdi:help-circle-outline` (UNSUPPORTED).
+
+---
+
+## Notification Behavior
+
+Persistent notifications are managed by the coordinator and fire on state or reason transitions:
+
+| Transition | Action |
+|---|---|
+| First poll | Silent baseline — no notification |
+| NO → MAYBE | Fire warning notification |
+| NO → YES | Fire critical notification |
+| MAYBE → YES | Update notification (escalate) |
+| YES → MAYBE | Update notification (de-escalate) |
+| YES/MAYBE → NO | Dismiss notification |
+| * → UNSUPPORTED | Fire informational notification (once) |
+| Same state, reasons changed | Update notification with new reason list |
+
+Notification IDs are stable per drive: `smart_sniffer_attention_{drive_id}`. Each notification lists all active trigger reasons as bullet points.
+
+---
+
+## Known Gaps (Future Work)
+
+- **Temperature triggers** — not yet implemented. Planned: absolute threshold (e.g., > 55°C → MAYBE) and trend-over-time detection (sustained rise over multiple polls). Requires historical storage in the coordinator.
+- **SAS/SCSI triggers** — `scsi_grown_defect_list` and SCSI error counters are not yet parsed. SAS drives currently show as UNSUPPORTED.
+- **NVMe `critical_warning` bitmask decoding** — currently treated as a single flag (≠ 0 → YES). Future: decode individual bits (spare below threshold, temperature exceeded, reliability degraded, read-only mode, volatile memory backup failed) into separate reasons.