Skip to content

attention-trigger-entity-map.md

Latest commit

 

History

History
102 lines (68 loc) · 4.92 KB

attention-trigger-entity-map.md

File metadata and controls

102 lines (68 loc) · 4.92 KB
Raw

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.