houseplan-card/docs/VACUUM.md

Live robot vacuums on the plan — the spec (source of truth)

Status: approved by the owner 2026-07-31. Scope decisions final: all three Tier-A adapters in P1, the trail ships in P1, the marker's placed position IS the dock, and tap-to-clean is out — display only, no commands (owner: «не нужно вообще»).

Principle

The device marker «Пылесос» NEVER moves: it stands where the user placed it — that is the base/dock — with its normal badge, states and tap actions. While the robot cleans, a SECOND visual appears: a round puck (the vacuum icon in a circle), no badge plate, with a soft pulse, driving around the plan on live coordinates. Owner's exact wording: «Иконка движущегося пылесоса должна быть круглой, без подложки и с легкой пульсацией. Основное устройство "Пылесос" при этом остается всегда на своем месте (база)». The puck is not clickable UI chrome duplicating the device — a tap on it opens the same more-info as the base marker. When the robot docks, the puck drives home and dissolves into the base marker.

Data tiers (auto-detected, zero user input)

• Tier A — coordinates + own calibration data. vacuum_position {x,y,angle} (+ calibration_points, rooms, sometimes path): Xiaomi Cloud Map Extractor, dreame-vacuum (Tasshack), Valetudo camera (sca075). All three ship in P1.
• Tier B — bare coordinates. Roomba core (position {x,y,theta}), raw Valetudo MQTT, template sensors. Works after manual calibration. P3.
• Tier C — current room only. current_room / current_segment. The room being cleaned gets a soft fill pulse + a 🤖 badge in the room card; no puck. Segment→room matched by name, manual override in the dialog.
• Tier D — nothing. Today's behaviour; yellow badge on the base marker while cleaning per the «yellow = working right now» principle.

Tiers degrade gracefully: coords gone → room highlight; that gone too → just the base marker.

Coordinate binding

Affine transform (translate+rotate+scale+mirror), 6 numbers, least squares over ≥3 point pairs. Stored per robot map: marker.vacuum.calibration[map_id] — multi-floor robots get one matrix per map; an active map without a matrix falls back to Tier C.

• Path 1, auto-calibration by rooms (the default): Tier-A adapters expose the robot's room list with coordinates; our rooms carry HA area bindings. Match by name, take centroids of ≥3 matches, solve, show a live preview («робот сейчас здесь») — one click to confirm.
• Path 2, manual 3-point wizard (Tier B or when auto fails): pause the robot somewhere recognisable → drag the ghost puck to the true spot → next; three points in different corners, live preview, done.
• Residual over ~40 cm → warn and ask for a fourth point. Mirrored maps are covered by the affine automatically (negative determinant).

Puck behaviour

Appears when the robot leaves docked AND live coords flow; CSS interpolation ~1.2 s between updates; a data gap over 10 s teleports without animation (no gliding through walls on sparse cloud updates). Soft pulse always while visible (respects prefers-reduced-motion: the pulse freezes, position still animates). Size: same --icon-size system as devices, circle, transparent background, no badge plate. Stale coords (>60 s while «cleaning»): puck freezes and dims. On docked/idle-at-base the puck rides home and fades out. Hidden markers render neither base nor puck (general hidden rules). Works in the full card, static card and kiosk; in editors no puck — the base marker is edited as usual.

Trail (ships in P1)

• Integration path when available (Map Extractor) — transform and draw as-is, includes history from before the card was opened.
• Otherwise self-recorded: client-side ring buffer, ~600 points with Douglas-Peucker thinning, one SVG polyline.
• Style fixed, no options: cartography casing — a dark translucent halo under a light core. Neutral (pure black/white alphas) and readable over any room fill; blend modes were rejected: each has a blind luminance where the line vanishes, and mix-blend-mode is costly on old kiosk WebViews. Lifecycle: appears on cleaning start, lives until dock + 10 min, dissolves; docked → cleaning clears the old trail. Ephemeral, never stored.
• Marker option «Показывать след уборки», on by default where data exists.

Setup UX

A «Живая позиция» section in the device dialog, vacuum markers only: status line (which source was found / room-only / nothing), one button («Настроить автоматически» for Tier A, «Калибровка по трём точкам» for Tier B), three checkboxes (live position / trail / room highlight, all on), and for multi-map robots a per-map calibration status list. The source entity is discovered via the device registry — no YAML, no entity pickers.

Storage & validation

marker.vacuum: { live, trail, room_highlight, source, calibration: {[map_id]: [6 numbers]}, segment_map: {[segment]: room_id} } — all optional (old configs stay valid), matrices are 6 finite numbers, backend-validated. Calibration is server-side state shared by every screen, like the whole plan.

Cases covered explicitly

Two vacuums (independent markers, calibrations, pucks); one robot on two floors (maps ↔ spaces, the puck only renders in the space whose map is active); robot outside the plan (±4 canvas bounds allow it, trail clipped by viewport); integration restart changes map_id (rebind by room-list match, else ask to recalibrate); user redraws rooms (the matrix does not depend on rooms); demo stand gets a scripted synthetic robot as the showcase.

Out of scope

Commands of any kind (owner decision: display only) — no tap-to-clean, no zone sending. No-go zones, cleaned-area polygons, cleaning history, multi-robot collision avoidance — v2 candidates.

Phases

• P1: adapter framework + all three Tier-A adapters + auto-calibration by rooms + manual 3-point wizard + the puck + trail (both sources).
• P2: Tier C room highlight + the demo-stand scripted robot.
• P3: Tier B zoo (Roomba, raw Valetudo MQTT), Deebot, multi-map polish by feedback.