Feature: Integrate Watchman for entity health monitoring

[mholzi]

Summary

Add support for the Watchman HACS integration to display entity health status in Dashview.

What is Watchman?

Watchman is a powerful HACS integration that checks all services and entities in Home Assistant and reports those that are:

• Missing
• Unavailable
• Not responding

This helps users proactively identify and fix problems before automations and dashboards stop working.

Proposed Feature

Display Watchman's entity health information in Dashview, potentially including:

• Admin Panel: Show a health summary with count of problematic entities
• Room View: Indicate when devices in a room have issues (e.g., unavailable sensors)
• Notification Badge: Alert users when Watchman detects problems

Use Cases

1. Proactive Maintenance: Users see at a glance if any devices need attention
2. Troubleshooting: Quickly identify which room has problematic devices
3. Battery Alerts: Watchman can detect sensors that went offline (often due to dead batteries)

Technical Notes

• Watchman creates sensors like sensor.watchman_missing_entities and sensor.watchman_unavailable_entities
• Entity lists are available as sensor attributes
• Integration is optional - Dashview should gracefully handle when Watchman is not installed

References

• Watchman GitHub
• HACS Page

[mholzi]

🔬 Deep Research: Watchman Integration for Dashview

Part 1: Watchman Deep Dive

1.1 How Watchman Works Internally

Watchman (v0.8.3, 603 ⭐, HACS Default) is a custom integration that scans YAML configuration files and cross-references entity/action references against the current HA state registry.

Architecture:

• Parser: Reads YAML files line-by-line using regex-based heuristics to detect entity and service/action references. Intentionally lightweight — no full config model or dependency graph.
• Coordinator (WatchmanCoordinator): Extends HA's DataUpdateCoordinator. Manages parsing, validation, and event subscriptions.
• Hub: Handles file scanning, SQLite-based caching (watchman.db), and mtime-based change detection.
• Event Subscriptions: Listens to state_changed, service_registered, service_removed, automation_reloaded, scene_reloaded, and call_service (for reload operations).
• Triage Logic: For each parsed entity reference, checks state against MONITORED_STATES = ["unavailable", "unknown", "missing", "disabled"]. Supports label-based and pattern-based ignoring.

Key Limitation: Watchman only reports entities/services referenced in YAML config files. It does NOT scan the entire entity registry for all unavailable entities.

1.2 Sensors Created

Watchman creates 8 sensors (all diagnostic category):

Sensor Entity ID	Type	Description
sensor.watchman_missing_entities	Measurement (items)	Count of missing/unavailable entities
sensor.watchman_missing_actions	Measurement (items)	Count of missing/unavailable actions
sensor.watchman_last_updated	Timestamp	Last time sensors were refreshed
sensor.watchman_status	Enum	Current status: waiting_for_ha, parsing, idle, safe_mode
sensor.watchman_parse_duration	Duration (seconds)	Time taken for last parse
sensor.watchman_last_parse	Timestamp	Last time config files were parsed
sensor.watchman_processed_files	Measurement	Number of files processed
sensor.watchman_ignored_files	Measurement	Number of files ignored

Note: Legacy users may still have sensor.watchman_missing_services instead of sensor.watchman_missing_actions.

1.3 Sensor Data Structure (Critical for Integration)

sensor.watchman_missing_entities:

• State: Integer count (e.g., 3)
• Attributes: { "entities": [...] } where each entity is:

{
  "id": "sensor.stats_pm25_10_median",
  "state": "unavail",
  "friendly_name": "PM2.5 Median",
  "occurrences": "customize.yaml:14"
}

Possible state values: "missing", "unavail", "unknown", "disabled"

sensor.watchman_missing_actions:

• State: Integer count (e.g., 1)
• Attributes: { "entities": [...] } (note: key is "entities" in read, "services" in write — appears to be a minor inconsistency in source) where each is:

{
  "id": "xiaomi_miio.vacuum_goto",
  "occurrences": "automations.yaml:599,605"
}

1.4 Update Frequency

• On HA Start: Sensors update on homeassistant_started event (with configurable startup delay)
• On Config Changes: Automatically re-parses when automations/scenes are reloaded or core config is reloaded
• On State Changes: Refreshes when any monitored entity's state changes to/from a monitored state (unavailable, unknown, missing, disabled)
• On Service Changes: Refreshes when tracked services are registered/removed
• Manual Trigger: watchman.report service with optional parse_config: true
• NO periodic polling: Does not poll on a timer — purely event-driven

1.5 Exposed Services & Adoption

Services:

• watchman.report — Generate and optionally send a Watchman report
  • Parameters: parse_config, action (notification service), data, chunk_size, create_file

Adoption Stats:

• ⭐ 603 GitHub stars, 30 forks, 54 open issues
• HACS Default repository (high visibility)
• 5+ YouTube reviews from major HA channels (Everything Smart Home, mostlychris, Smart Home Australia, Smart Home Makers)
• Active community forum thread with ongoing discussion
• Estimated thousands of active installations (HACS Default + YouTube exposure)

---

Part 2: Current Dashview Architecture Review

2.1 Where Watchman Data Would Fit

Based on thorough codebase analysis, Dashview has several natural integration points:

Integration Point	Current Analog	Watchman Fit
Info Text Row (Status Bar)	Water leaks, smoke, motion, battery low, door/window/garage open	⭐ Best fit — same pattern as existing health alerts
Admin Status Tab	House info toggles, garbage, train, media, notifications	Good fit for configuration
Room Popup Chips	Motion, smoke, windows status chips	Possible for per-room breakdown
Activity Indicators	Lights, motion, smoke per floor	Could show health per floor

2.2 Admin Panel Structure

The admin panel has 7 sub-tabs:

1. Setup — Wizard, onboarding
2. Entities — Entity/label mapping configuration
3. Layout — Room config, floor cards, scene buttons, info text toggles
4. Weather — Weather entity configuration
5. Status — House info toggles, garbage card, train departures, media playlists, climate notifications
6. Scenes — Scene button configuration
7. Users — User management

Recommended placement: Status tab → new "Entity Health" section, OR a dedicated "Health" tab if scope grows.

2.3 How Dashview Currently Handles Unavailable Entities

Dashview silently filters out unavailable entities rather than alerting:

• Temperature/humidity sensors: filter(s => s.state !== 'unavailable' && s.state !== 'unknown') — silently excluded from readings
• Lights: Skip entities with state unavailable/unknown from toggle counts
• Appliances: Show "Nicht verfügbar" text with isUnavailable: true flag but no aggregate alert
• Charts: Filter out unavailable data points from history
• Entity stats: Counts unavailable entities in _getEntityStats() but doesn't surface it to UI

Gap: There is no proactive "your home has X broken devices" indicator. Users only discover issues when they notice a missing reading or failed automation.

---

Part 3: UI/UX Research

3.1 How Other Dashboards Handle Entity Health

Mushroom Cards (6.8k ⭐):

• Shows per-entity "unavailable" state with a muted/grayed-out card appearance
• No aggregate health view — each card independently shows its state
• Template badge can be used to create custom health indicators

Bubble Card:

• Similar per-entity approach — unavailable entities show a disabled state
• Pop-up cards can be configured to show grouped health status manually

Dwains Dashboard:

• Auto-discovers entities and rooms
• Shows device counts per room but no built-in health monitoring
• Users typically add Watchman as a separate Lovelace card

HA Core (2024.8+):

• Native badges system can show entity state
• Built-in "Problem" entity category shows some health info in Settings
• No dashboard-level aggregate health indicator

3.2 How Consumer Smart Home Apps Handle Unresponsive Devices

Apple Home:

• Shows "Not Responding" in red text directly on the accessory tile
• Status bar shows "X accessories not responding" as a banner
• Progressive disclosure: tap banner → see list of affected devices
• Per-room indicators: room shows warning icon if any device unresponsive

Google Home:

• Shows "Offline" badge on device cards
• "X devices offline" notification in the app
• Device health section under Settings → Devices
• No per-room aggregate

Samsung SmartThings:

• "Disconnected" status with warning icon on device card
• "Device Health" feature shows connectivity status
• Alert notification for newly disconnected devices
• History of connection status changes

Common Patterns Across All:

1. Badge/count on overview — "X devices need attention"
2. Per-device visual state — Grayed/muted/red indicator on individual devices
3. Detail drill-down — Tap to see list of affected devices
4. Progressive disclosure — Summary → List → Device Detail

3.3 Progressive Disclosure Patterns

Ideal 3-level hierarchy for Dashview:

1. L1: Status Bar Badge — "🛡️ 3 entities need attention" in info text row
2. L2: Health Popup — Expandable list showing entity name, state, and location
3. L3: Entity Detail — Click through to HA's More Info dialog for the entity

3.4 Mobile-First Considerations

• Touch targets: Minimum 44×44px for health items
• Scrollable lists: Watchman can report 50+ entities — needs virtualization or pagination for large lists
• Compact chips: Room-level indicators should use the existing chip component pattern
• Dismissable alerts: Already implemented for info text alerts — reuse for Watchman alerts
• Performance: Watchman sensor attributes can be large — debounce/cache reads

---

Part 4: Proposed UI Patterns

Option A: Admin-Only Health Tab

Description: New "Health" sub-tab in admin panel showing full Watchman report with entity list, states, and file locations.

Mockup:

┌─ Admin ─────────────────────────────────┐
│ [Setup][Entities][Layout][Weather]       │
│ [Status][Scenes][Users][🛡️ Health]      │
│                                          │
│ 🛡️ Entity Health (Watchman)             │
│ ─────────────────────────               │
│ ⚠️ 3 missing entities • 1 missing action│
│ Last checked: 2 min ago                  │
│                                          │
│ ┌──────────────────────────────────┐    │
│ │ 🔴 sensor.stats_pm25 (unavail)  │    │
│ │    customize.yaml:14             │    │
│ │ 🔴 sensor.xiaomi_miio (unavail) │    │
│ │    automations.yaml:231,1348     │    │
│ │ 🔴 vacuum.roborock_s5 (unavail) │    │
│ │    automations.yaml:589,603      │    │
│ └──────────────────────────────────┘    │
│                                          │
│ [🔄 Refresh Report]                     │
└──────────────────────────────────────────┘

Pros	Full detail, doesn't clutter main view, natural admin action, can show file locations
Cons	Admin-only = most users won't see it, no proactive alerting, hidden 2 levels deep
Complexity	🟢 Low — new tab + sensor read

Option B: Status Bar Badge (Info Text Row)

Description: Add Watchman health status to the existing info text row, following the same pattern as water leak, battery, motion, etc.

Mockup:

┌─────────────────────────────────────────────┐
│ 💡 2 Lichter an. 🪟 Wohnzimmer offen.     │
│ 🛡️ 3 Entitäten brauchen Aufmerksamkeit.   │
│                          [×]                │
└─────────────────────────────────────────────┘

Clicking the badge opens a health popup with the entity list.

Pros	Visible to all users, consistent with existing patterns, proactive, non-intrusive
Cons	Limited space for detail, may feel noisy if Watchman reports many false positives
Complexity	🟢 Low — add getWatchmanStatus() to status-service.js, render in info text row

Option C: Room-Level Indicators

Description: Show a warning chip in room cards/popups when Watchman-reported entities belong to that room.

Mockup (Room Card):

┌──────────────────┐
│ Wohnzimmer  ⚠️   │
│ 21°C • 45%       │
│ 1 device offline  │
└──────────────────┘

Mockup (Room Popup Chip):

[🔥 Motion 2m] [🪟 Closed] [⚠️ 1 offline]

Pros	Contextual, helps identify WHERE problems are, fits room-centric design
Cons	Complex entity→area mapping needed (Watchman doesn't provide area info), visual noise, needs cross-referencing entity registry
Complexity	🔴 High — requires entity→device→area resolution for each Watchman entity

Option D: Dedicated Health Popup

Description: Accessible via a status bar badge or admin panel, shows a full-screen popup with categorized health information.

Mockup:

┌─ Entity Health ─────────────── [×] ─────┐
│                                          │
│ 🛡️ Watchman Report                      │
│ Last updated: 14:30                      │
│                                          │
│ ⚠️ Missing Entities (3)                 │
│ ┌──────────────────────────────────┐    │
│ │ 🔴 sensor.stats_pm25_10_median   │    │
│ │    State: unavailable             │    │
│ │    Used in: customize.yaml:14     │    │
│ ├──────────────────────────────────┤    │
│ │ 🔴 sensor.xiaomi_miio_sensor     │    │
│ │    State: unavailable             │    │
│ │    Used in: automations.yaml      │    │
│ ├──────────────────────────────────┤    │
│ │ 🔴 vacuum.roborock_s5max         │    │
│ │    State: unavailable             │    │
│ │    Used in: automations.yaml      │    │
│ └──────────────────────────────────┘    │
│                                          │
│ ⚠️ Missing Actions (1)                  │
│ ┌──────────────────────────────────┐    │
│ │ 🔴 xiaomi_miio.vacuum_goto       │    │
│ │    Used in: automations.yaml      │    │
│ └──────────────────────────────────┘    │
│                                          │
│ ✅ 213 entities OK • 37 actions OK      │
│                                          │
│ [🔄 Run Watchman Report]                │
└──────────────────────────────────────────┘

Pros	Full detail, good for debugging, can show file locations and entity states, clickable entities
Cons	Needs a trigger (badge/button), not always visible, separate from room context
Complexity	🟡 Medium — new popup component + sensor attribute parsing

Option E: Inline in Room Popup

Description: Show affected entities directly in the room popup as a new collapsible section.

Mockup:

┌─ Wohnzimmer ─────────────── [×] ────────┐
│ [🔥 Motion] [🪟 Closed] [⚠️ 1 Issue]   │
│                                          │
│ ⚡ Quick Actions                         │
│ [💡 Lights Off] [🪟 Covers Close]       │
│                                          │
│ ⚠️ Entity Issues ──────────── [▼]       │
│ ┌──────────────────────────────────┐    │
│ │ 🔴 sensor.xiaomi_miio (unavail)  │    │
│ └──────────────────────────────────┘    │
│                                          │
│ 🌡️ Climate                              │
│ ...                                      │
└──────────────────────────────────────────┘

Pros	Contextual to room, natural discovery, progressive disclosure via collapse
Cons	Same complexity as Option C (entity→area mapping), room popup already content-heavy, only shows room-specific issues
Complexity	🔴 High — entity→area mapping + new room popup section

Option F: Combination Approach (⭐ RECOMMENDED)

Description: Combine Options B + D + A for a 3-tier progressive disclosure:

1. Info Text Row Badge (always visible) → "🛡️ 3 entities need attention"
2. Health Popup (click badge) → Full categorized entity list with states and locations
3. Admin Health Section (in Status tab) → Configuration, manual refresh, advanced settings

Why this wins:

• Follows the proven Apple Home pattern (banner → detail → settings)
• Consistent with existing Dashview patterns (water leak, battery alerts use same flow)
• Low complexity for Phase 1 (badge only), scalable for future phases
• Admin section provides control without cluttering the main UI
• No entity→area mapping needed for Phase 1

Pros	Best of all worlds, progressive disclosure, consistent patterns, phased delivery
Cons	Most total work (but can be phased), needs 3 integration points
Complexity	Phase 1: 🟢 Low, Phase 2: 🟡 Medium, Phase 3: 🟢 Low

---

Part 5: Implementation Architecture

5.1 Proposed File Structure

services/
  watchman-service.js          # NEW: Watchman data access & status generation
  status-service.js            # MODIFIED: Add getWatchmanStatus() call

features/
  admin/
    status-tab.js              # MODIFIED: Add Entity Health section
  popups/
    health-popup.js            # NEW: Health detail popup (Phase 2)
    index.js                   # MODIFIED: Export health popup

stores/
  settings-store.js            # MODIFIED: Add watchman settings

constants/
  index.js                     # MODIFIED: Add watchman-related constants

5.2 watchman-service.js (Core Service)

/**
 * Watchman Service
 * Reads Watchman sensor data and provides health status information
 */

const WATCHMAN_ENTITIES = {
  missingEntities: 'sensor.watchman_missing_entities',
  missingActions: 'sensor.watchman_missing_actions',
  lastUpdated: 'sensor.watchman_last_updated',
  status: 'sensor.watchman_status',
};

/**
 * Check if Watchman integration is available
 */
export function isWatchmanAvailable(hass) {
  return !!hass?.states[WATCHMAN_ENTITIES.missingEntities];
}

/**
 * Get Watchman health summary
 */
export function getWatchmanSummary(hass) {
  if (!isWatchmanAvailable(hass)) return null;

  const missingEntities = hass.states[WATCHMAN_ENTITIES.missingEntities];
  const missingActions = hass.states[WATCHMAN_ENTITIES.missingActions];
  const lastUpdated = hass.states[WATCHMAN_ENTITIES.lastUpdated];
  const status = hass.states[WATCHMAN_ENTITIES.status];

  return {
    entityCount: parseInt(missingEntities?.state) || 0,
    actionCount: parseInt(missingActions?.state) || 0,
    totalIssues: (parseInt(missingEntities?.state) || 0) + (parseInt(missingActions?.state) || 0),
    entities: missingEntities?.attributes?.entities || [],
    actions: missingActions?.attributes?.entities || [],
    lastUpdated: lastUpdated?.state,
    status: status?.state,
  };
}

/**
 * Get Watchman status for info text row
 * Follows same pattern as getWaterLeakStatus, getBatteryLowStatus, etc.
 */
export function getWatchmanStatus(hass, infoTextConfig) {
  if (!hass || !infoTextConfig?.watchman?.enabled) return null;
  if (!isWatchmanAvailable(hass)) return null;

  const summary = getWatchmanSummary(hass);
  if (!summary || summary.totalIssues === 0) return null;

  return {
    state: 'warning',
    prefixText: '',
    badgeText: `🛡️ ${summary.totalIssues}`,
    emoji: '',
    suffixText: summary.totalIssues === 1
      ? t('status.watchman.singleIssue')
      : t('status.watchman.multipleIssues', { count: summary.totalIssues }),
    isWarning: summary.totalIssues > 0,
    clickAction: 'health',
    priority: 50,  // Below safety (water/smoke=100) but above info (motion/lights)
    alertId: `watchman:${summary.totalIssues}`,
  };
}

5.3 Data Flow

Watchman Integration (HACS)
    │
    ▼
sensor.watchman_missing_entities  ←── HA State Registry
sensor.watchman_missing_actions       (real-time updates via events)
    │
    ▼
watchman-service.js
    ├── isWatchmanAvailable()    → Graceful degradation
    ├── getWatchmanSummary()     → Parsed sensor data
    └── getWatchmanStatus()      → Status bar item
          │
          ▼
    ┌─────────────────┐
    │ status-service   │──→ Info Text Row (Badge)
    │ getAllStatusItems │     │
    └─────────────────┘     ▼
                        Health Popup (Phase 2)
                             │
                             ▼
                        Admin Status Tab (Phase 3)

5.4 Admin Configuration

Add to Status tab → new "Entity Health" section:

// In status-tab.js - new section
renderInfoTextToggle(panel, html, 'watchman',
  t('admin.infoTextToggles.watchman'),
  'mdi:shield-half-full',
  t('admin.infoTextToggles.watchmanDesc')
)

Settings to expose:

• Enable/disable Watchman health in status bar (toggle)
• Show missing entities (toggle, default: on)
• Show missing actions (toggle, default: on)
• Warning threshold — Only show badge if issues exceed N (default: 0)

5.5 Entity Auto-Detection vs Manual Config

Recommendation: Auto-detection with graceful degradation

• Auto-detect sensor.watchman_missing_entities — if it exists, Watchman is installed
• No manual entity configuration needed
• If Watchman is not installed, the feature simply doesn't appear (no toggle in admin, no badge)
• Show a "Watchman detected ✅" indicator in admin when available, with link to install instructions when not

5.6 Performance Impact Assessment

Concern	Risk	Mitigation
Sensor attribute size	🟡 Medium — entities array can be large	Cache parsed result, only re-parse on state change
Render frequency	🟢 Low — Watchman updates are event-driven, not polling	No additional polling needed
DOM updates	🟢 Low — single badge in info text row	Lit's efficient diffing handles this
Memory	🟢 Low — parsed summary is small	Store only summary, not raw attributes
Startup	🟢 Low — read existing sensor state	No additional API calls or file parsing

Total estimated performance impact: Negligible — reading 2-3 sensor states that are already in HA's state machine.

---

Implementation Estimate

Phase 1: Status Bar Badge (MVP) — ~4-6 hours

• Create watchman-service.js with isWatchmanAvailable(), getWatchmanSummary(), getWatchmanStatus()
• Add getWatchmanStatus to getAllStatusItems() in status-service.js
• Add watchman toggle to infoTextConfig in settings store
• Add admin toggle in Status tab
• Add i18n strings (DE + EN)
• Auto-detection: only show toggle when Watchman is installed
• Tests for watchman-service.js

Phase 2: Health Popup — ~6-8 hours

• Create health-popup.js with categorized entity/action lists
• Implement clickAction: 'health' handler in panel
• Click-through to HA More Info for individual entities
• Refresh button calling watchman.report service
• Responsive design for mobile
• Tests for popup rendering

Phase 3: Admin Health Section — ~3-4 hours

• Extended Status tab section with full report view
• Advanced settings (threshold, show/hide categories)
• "Install Watchman" prompt when not detected
• File location display (for advanced users)

Phase 4 (Future): Room-Level Indicators — ~8-12 hours

• Entity → Device → Area resolution for Watchman entities
• Room card warning indicator
• Room popup health chip
• Per-floor health aggregation

Total: ~21-30 hours across all phases
Recommended MVP (Phase 1): 4-6 hours

---

Key Design Decisions

1. Optional integration — Dashview must work perfectly without Watchman installed
2. Auto-detection — No manual sensor configuration; detect Watchman presence automatically
3. Consistent patterns — Use existing info text row, popup, and admin patterns
4. Progressive disclosure — Badge → Popup → Admin Detail (Apple Home pattern)
5. Priority ordering — Watchman alerts below safety (water/smoke) but above informational (motion/lights)
6. i18n from day one — All strings through translation system
7. No false positive noise — Respect Watchman's own ignore lists; add threshold option