Epic: Floorplan-anchored RF topology and radio intensity overlay

[DarinShapiro]

Summary

This epic introduces high-fidelity spatial awareness to Thread diagnostics. By integrating with \ha-floorplan\ for physical anchors and falling back to authored area adjacency, we enable a rich RF intensity / trouble-spot overlay that helps operators understand the physical health of their mesh network.

Why

Standard graph views lack physical context, making it difficult to identify why certain links are weak (e.g., concrete walls, distance). Spatial mapping transforms abstract metrics into actionable environmental insights.

Dependencies & Context

• Prerequisites: Graph area filter does not populate with real Home Assistant areas #80 (Sub-graph/grouping logic) and Graph: Support logical grouping by Area for mesh visualization #85 (Link quality metrics stability).
• Complementary: Graph UX: show node/link metadata on hover #92 (Graph UX refinements).

Phased Delivery Plan

1. Data Foundation: Implement the spatial model and persistence (Spatial model: persist floorplan anchors, floors, areas, and authored adjacency #93).
2. Layout Definition: Integrate floorplan anchors (Integrate ha-floorplan as a spatial anchor source for Thread topology #94) and build graph-based authoring for manual fallback (Graph authoring: define floor layout and area adjacency fallback #95).
3. Intelligence Engine: Develop spatial inference (Spatial inference engine: refine relative node placement from anchors and radio metrics #96) and RF stress scoring (Backend RF intensity and physical trouble-spot scoring #97).
4. UI/UX Layer: Ship the floorplan overlay view (Floorplan UI: topology overlays and radio intensity layer #98) and explainable diagnostic cues (Spatial diagnostics UX: confidence, conflicts, and remediation cues #99).
5. Verified Stability: Finalize validation fixtures and accuracy metrics (Validation pack: replay fixtures and acceptance metrics for spatial diagnostics #100).

Checklist

• Spatial model: persist floorplan anchors, floors, areas, and authored adjacency #93 Spatial model: persist floorplan anchors, floors, areas, and authored adjacency
• Integrate ha-floorplan as a spatial anchor source for Thread topology #94 Integrate ha-floorplan as a spatial anchor source for Thread topology
• Graph authoring: define floor layout and area adjacency fallback #95 Graph authoring: define floor layout and area adjacency fallback
• Spatial inference engine: refine relative node placement from anchors and radio metrics #96 Spatial inference engine: refine relative node placement from anchors and radio metrics
• Backend RF intensity and physical trouble-spot scoring #97 Backend RF intensity and physical trouble-spot scoring
• Floorplan UI: topology overlays and radio intensity layer #98 Floorplan UI: topology overlays and radio intensity layer
• Spatial diagnostics UX: confidence, conflicts, and remediation cues #99 Spatial diagnostics UX: confidence, conflicts, and remediation cues
• Validation pack: replay fixtures and acceptance metrics for spatial diagnostics #100 Validation pack: replay fixtures and acceptance metrics for spatial diagnostics

Non-Goals

• Claiming centimeter-level physical accuracy from RF metrics alone.
• Requiring a floorplan addon; basic diagnostics must work with manual area adjacency.

Acceptance Criteria

• Operator can view Thread topology overlaid on a physical floorplan (or area grid).
• A heatmap layer identifies areas of high RF stress or weak coverage.
• The system explains why a node is placed in a specific area based on combined RF and spatial evidence.

[DarinShapiro]

Requirement: Ground diagnostic insights in spatial and radio evidence. Explanation should correlate link degradation with physical barriers (e.g., walls) and recommend strategic router placement (e.g., adding a router between a weak endpoint and the OTBR) to optimize routing paths for nearby devices.

[DarinShapiro]

Note: The epic should explicitly consider whether an internal graph database is warranted, given the graph-like querying needs across both Thread topology and spatial/floorplan data. This can remain an internal implementation detail. Evaluation criteria should include query complexity, traversal-heavy workloads, persistence needs, and whether an in-memory/internal graph layer is sufficient first.

[DarinShapiro]

The epic should explicitly handle multiple floors, as residential and commercial environments commonly span several levels. Computing and estimating signal behavior between devices on different floors must be treated as a requirement, incorporating floors into both the spatial model and RF scoring/problem-detection logic.