houseplan-card/docs/RADAR.md

Presence radars

Stage 1 of #485 projects current Home Assistant radar observations onto one House Plan room. It is intentionally a visualization and setup feature: House Plan does not identify people, record tracks, configure hardware zones or create derived Home Assistant entities at this stage.

What appears on the plan

• Cartesian or polar coordinates become small live target dots.
• A distance-only source becomes an arc or full range circle. It is not presented as an exact person position.
• Known zone states may be presented as occupied/clear state; unknown geometry is never invented.
• Presence-only sources report presence and health but do not fabricate a dot.
• Coordinates, arcs and known zone geometry are clipped to the selected room's real polygon, including concave rooms. A missing room is an error and never falls back to another room or to its bounding box.

The layer is pointer-transparent. Small verified jumps may transition smoothly; large jumps, source gaps, slot changes, calibration changes and non-convex room contours never animate through an unverified path. Reduced-motion mode disables target motion. The diagnostic trail is limited to eight seconds and exists only inside the current browser session.

Supported input profiles

Profile	Required source data	Result
ESPHome LD2450	One to three exact X/Y sensor pairs, millimetres	Target dots; x=0,y=0 together means an absent target, while one zero axis is a valid coordinate
Cartesian	One to eight exact X/Y pairs, explicit unit, axis order and directions	Target dots
Polar	One to eight exact distance/angle pairs, explicit length/angle units and angle convention	Target dots
Distance only	One or two exact distances, explicit unit and known/entered direction/FOV	Honest range arcs
Zone states	Exact occupancy/count entities	Read-only states; outlines only when geometry is actually known
Presence only	Exact binary presence entity	Presence and health without a position

An optional global availability entity and per-target/range presence gates may make absence explicit. Numeric zero remains data unless the selected adapter defines an exact pair rule such as LD2450's (0,0). Empty strings, unknown, unavailable, NaN and infinity are never converted to zero.

Configure a radar

1. Add or open the real device marker in the Device editor.
2. For a recognized radar, open Presence on the plan. For custom hardware, use Additional actions → This is a presence radar.
3. Enable the radar, choose the room and verify every exact source. For generic profiles, specify units and coordinate conventions explicitly.
4. Use Check live data before calibration. Correct unavailable, stale, partial or contradictory values in Home Assistant or the source mapping.
5. Enter the physical mounting point, heading, range and field of view manually, or use Configure on plan. The latter records the mount and a point straight ahead. Coordinate profiles then measure two separated reference positions.
6. Optionally check a third position. Its error is diagnostic and does not alter the solved transform.
7. Apply the setup, then use the ordinary marker Save. Until that final Save, Cancel, Escape, page hide or a config revision conflict discards the draft.

The physical mount is not the decorative icon position. Moving the icon later does not move or recalibrate the radar. Changing the radar source/profile, coordinate convention, room or physical installation invalidates an accepted calibration; display-only switches do not.

Use a desktop browser for calibration. Touch View/kiosk remains fully supported, but precise editor setup on touch is best effort.

Health meanings

Status	Meaning
Current data received	Complete, fresh source data was normalized
No targets detected	An explicit absence was reported
Some coordinate data is out of date	One or more paired values exceeded the freshness/skew contract
Presence reported; current position unavailable	Presence is true but no honest current coordinate is available
Sensor data unavailable	A required source or availability gate is unavailable
Installation needs setup	Sources exist but physical mapping is incomplete
Sources report conflicting values	Fresh sources contradict each other, for example a zero target count with current target coordinates

Coordinate/range reports have short server leases and disappear when they are not refreshed. Reopening a tab, reconnecting or changing a source/calibration starts a new ordering epoch; an old frame cannot resurrect a target.

Privacy, permissions and storage

House Plan subscribes only to the exact configured entity IDs. Read delivery is filtered through the current Home Assistant user's entity permissions; setup requires House Plan write permission. Payload sizes, subscriptions and update rates are bounded.

Saved configuration contains source entity IDs, selected room, physical mount, orientation, units and calibration — not observations. Raw source values, measurement samples, live targets, trails and health frames are runtime memory only. They do not enter plan export/import, support diagnostics, uploaded files, browser storage or Home Assistant history through House Plan. Home Assistant and the source integration may independently keep their normal entity history.

Virtualized plan imports intentionally drop hardware-specific radar bindings. Unknown future radar versions remain preserved but inert until supported.

Implementation map

• Persistence: marker.radar is saved only by the ordinary revisioned config transaction. radar_validation.py validates only a changed known version; untouched future versions stay inert. settings.radar.show_live is a display preference and never authorizes discovery, recording or hardware writes.
• Backend: one RadarCoordinator (radar.py) per integration entry owns exact HA source listeners, report-time freshness, independent-pair skew, source/calibration epochs, projection, real-room clipping and bounded public frames; it reconciles on config revision and closes all listeners/timers on unload. The explicit profile/source-role inventory (occupancy_entity, count_entity, availability_entity; Cartesian x_entity/y_entity; polar distance_entity/angle_entity; range/zone entity_id; slot/range presence_entity) is the single authority for live listeners, setup listeners and per-entity read ACLs; unknown future fields never become sources by naming convention. Only the backend interprets raw HA states.
• Eager View: radar-model.ts (frame validation/ordering/leasing), radar-live.ts (one active-space subscription and lifecycle), radar-render.ts (pointer-transparent SVG below ordinary device markers). Range segments arrive already clipped; an empty list is authoritative and never falls back to an unclipped arc. Transition eligibility is a server fact: only a current same-slot step of at most 100 cm in a convex room may animate.
• Lazy editor: radar-editor.ts (recognition/draft round-trip), editors/radar-section.ts (marker dialog), radar-setup.ts (session-only on-plan wizard). A two-reference result changes only the open draft; the ordinary marker Save is the only write.

Troubleshooting

• The section is absent: only positively recognized hardware or an already saved radar gets the main section. Use the manual action for a custom real device. Virtual markers cannot own a radar binding.
• The source list is incomplete: ensure the entity is enabled and readable by the current Home Assistant user. Manual mapping can use exact entities from different devices.
• Targets are missing: inspect health first. Verify units, axis signs, room, mount and heading. For LD2450, do not treat x=0 or y=0 alone as absence.
• A target stops at the room boundary: this is the intended safety clip.
• Calibration is noisy: repeat with one stationary person, separated references and no second reported target.

The normative engineering contract is docs/specs/485-radar-presence-stage1.md.