ADR 0070 Virtual Zones

ADR 0070: Virtual zones for mowers without a vendor map

Status

Accepted (2026-10-30)

Context

Some mowers report a GPS position but share no map with MowDeck: Worx Landroid models with the GPS or RTK module, Husqvarna models with capabilities.position (both ADR 0066). Their owners see a dot on an empty grid. They want to know where in the garden the mower is ("Vorgarten", "hinter dem Haus"), how long it spends in each part, and to be told when it is somewhere unexpected. The vendor cannot be asked to mow a MowDeck polygon: these mowers follow their boundary wire or their own map; at most they offer numbered zones as starting points (Worx zone:<n>, ADR 0066 amendment: StartPlan of kind zone).

Forces:

• Provider neutral and capability driven (ADR 0066): no vendor names in the core, no dead UI.
• The map projection and the aerial photo exist already (ADR 0023, ADR 0054). Positions arrive on the telemetry stream every few seconds while mowing (heartbeats every 10 s), with very different accuracy: plain GNSS scatters by metres, an RTK fix by centimetres.
• Authorization follows the mower (ADR 0014): whoever sees the mower sees its data; whoever controls it changes it.
• The theft tracking mode (ADR 0058) showed that a few tables next to the position track belong in Telemetry rather than in a new service.

Decision

Telemetry owns the zones, their definitions as well as the derived "current zone" and the time per zone. The only consumer of a zone is the position stream, which Telemetry alone reads; it also holds what decides whether zones are offered (the map snapshot, the capabilities, the positions) and the aerial photo the zones are drawn on. Splitting definitions into Fleet would need a new event, a projection of every polygon in Telemetry and an eventually consistent window in which a freshly drawn zone is unknown to the evaluation, for no second consumer. Fleet keeps what commands need: a zone start goes through the existing StartMow.plan_ref, which Fleet already validates. Ports and adapters as in the rest of the service: application/zone_ports.py (ZoneStore, PresenceTx), adapters/db/zone_store.py (PostgreSQL), adapters/memory_zones.py (tests), pure geometry and rules in domain/zones.py, the use cases in application/zones.py, the routes in adapters/api/zone_routes.py.

Data model (migration 0013, additive): virtual_zones (id, account, mower, name up to 60 characters, ring as JSONB [[lat, lon], ...] open, area_m2, optional start_plan_ref, created and updated time, creator), zone_presence (one row per mower: current zone or none, since when, the last evaluated report and position, its fix, whether the mower mowed, until when time was counted) and zone_days (mower, zone, UTC day: seconds in the zone, of those mowing, entries; deleted with the zone by a foreign key). A mower removal deletes all three with the rest of the mower's rows.

Geometry. WGS84 rings; planar work happens in a local tangent plane around the ring's vertex mean (mowdeck_control.geo). A ring is accepted open or closed; corners closer than 5 cm are merged. Limits: 3 to 64 corners, no crossing or touching edges (an O(n²) segment test, at most 2016 pairs), 1 m² to 10 ha, at most 1 km wide, every corner within 1 km of the mower's map origin or last position (a zone belongs to the garden; this also keeps the aerial photo proxy from being stretched to arbitrary places), at most 32 zones per mower. Violations are 422 with a JSON pointer (#/ring, #/name, #/start_plan_ref). The web app checks the same limits while drawing (libs/mowdeck-ui/src/lib/map/virtual-zones.ts).

Evaluation. After ingestion has committed a state, Zones.observe evaluates it (a failure is logged and never fails the ingestion). Mowers without zones cost one indexed query. Prepared shapes (local ring and bounding box) are cached per zone revision; the point test is a bounding box check, ray casting and the distance to the border, so a mower with 32 zones of 64 corners costs a few thousand float operations per report. Evaluations of one mower are serialised by a transaction level advisory lock and the presence row (FOR UPDATE), so two replicas never count an interval twice; older reports are ignored.

Hysteresis. A mower on a border must not flap between zones because of GPS scatter. The band depends on the fix the report carries: 0.3 m with an RTK fix, 1 m with a float fix, 0.5 m for the dock pose, 3 m for plain GNSS or an unknown quality. The current zone holds the mower while the fix is inside it or less than the band outside it; another zone is entered only when the fix lies inside it by at least the band (or, when no zone holds the mower, inside at all). Of several candidates the smallest wins, so a bed drawn inside the lawn takes over once the mower is well inside it. To change, a fix must move a band beyond a border, and back a band beyond it the other way.

Time per zone. The interval between two reports (the later of heartbeat_at and observed_at) counts for the zone the mower was in, as mowing time when it mowed at the earlier report (raw.blade_on, else activity mowing), split at UTC midnight, unless the gap exceeds 10 minutes or the link was lost in between. Entering a zone counts one entry. Drawing, reshaping or deleting zones re-evaluates the last position at once without counting time, so the owner sees "the mower is in this zone" right after saving.

Availability is decided by data the server holds, not by the vendor. GET /mowers/{id}/zones answers availability: available when the mower's map snapshot has no areas and it reports positions (a current one, or one in the last 30 days); vendor_map when the vendor shares map areas; no_position otherwise. There is no capability flag for positions (a vendor module may or may not be fitted, e.g. Worx' GPS module), so observed positions are the honest signal. Drawing is refused with 409 zones-unavailable (code vendor_map, no_position, or limit) unless available; zones drawn earlier stay listed if that changes. The web app shows the zone entry points only when the server offers zones or zones exist: no dead buttons.

Vendors with maps (decided: not offered). A mower with vendor areas already has zones, and they are what it can actually be sent to; a second, independent zone system on top would contradict them (two names for one lawn, two "current zones"). The follow-up is to derive the current vendor area from the same evaluator instead.

Vendor zone starts as an optional, provider declared mapping. A zone may name one of the mower's start plans of kind zone (StartPlan, declared by the connection in MowerCapabilities.start_plans; ADR 0066). Telemetry accepts only a reference the stored capabilities declare (422 otherwise) and offers the list as zone_plans. The zone page then shows "Hier starten", which sends the existing start_mow {plan_ref} through Fleet, the controller and the connection, which validate it as before. No new capability is needed, no adapter changes, and nothing claims MowDeck can send a mower into a polygon; without declared zone plans there is no link field.

API (all under /api/v1/telemetry): GET /mowers/{id}/zones (zones, presence with zone id, name and since, zone_plans, the map anchor, the limits), POST /mowers/{id}/zones, PATCH /mowers/{id}/zones/{zone_id} (name, ring, start_plan_ref, unlink_start_plan), DELETE /mowers/{id}/zones/{zone_id} and GET /mowers/{id}/zones/stats?days=1..92 (seconds, mowing seconds, entries, per UTC day).

Authorization needs no model change: reading needs can_view on the mower, drawing, changing, deleting and linking need can_control (as renaming a map area); a foreign mower is 404, a visible one without the right 403. Every query also filters by the token's account.

Aerial photo. The tile proxy of ADR 0054 serves the box of the map plus margin, grown by the corners of the zones, so a zone at the edge of the garden still lies on the photo. The box can only grow within 1 km of the garden (the corner limit above).

Web. /mowers/{id}/zones: the mower map (the vendor's snapshot when it has a geographic reference, else an empty map anchored where the server says) with the zones as dashed "surveyor's tape" outlines and name tags, the current zone filled in the mowing colour, the mower and an aerial photo toggle when offered. "Zone zeichnen" switches to drawing: each tap on the map sets a corner, a bar on the map shows the count, the reason a drawing cannot be saved yet (edges cross, too small, ...), "Ecke zurück", "Abbrechen" and "Fertig"; a sheet asks for the name and, when the mower declares zone starts, the link. The side panel says where the mower is now and since when, and lists the zones with their area, a bar of the time in each over the last seven days, mowing time and entries, "Hier starten" for linked zones and "Bearbeiten" (rename, relink, redraw the shape, delete). The mower page shows a "Zonen" button in its top bar and a chip with the current zone next to the presence; a mower without a vendor map gets "Zone zeichnen" in its empty map. German and English texts; phone first (map on top, panel below; side by side from 900 px). MowerMap (libs/mowdeck-ui) draws zones, the current and the selected zone and a draft; the pure layer model is unit tested.

Events: none yet. Nothing consumes zone changes today; the "left all zones" hint and zone history in notifications need a contract (event.zones.presence) and a consumer in Notifications, listed as follow-up rather than published without a reader.

Consequences

• Owners of GPS mowers without a vendor map get a meaningful map: named zones, where the mower is, and how long it spends where. MowDeck never pretends to command a mower into a polygon; the one way to start "there" is the vendor's own zone start, declared by its connection.
• One more query per stored state (zones of the mower), and for mowers with zones a short transaction per report. The cost is bounded by the zone and corner limits.
• The current zone is as good as the positions: with plain GNSS the 3 m band delays changes by a few metres; a zone smaller than the scatter will be entered rarely. Time counts only while the mower reports; long silences (over 10 minutes) and link losses count nothing.
• Time per zone is kept per UTC day without a retention limit (one small row per zone and day), like the health day totals; it is deleted with the zone or the mower.
• Follow-up (not in this change): the event.zones.presence contract and Notifications kinds ("left all zones", unexpected zone), coverage per zone (the coverage heatmap clipped to a zone), the current vendor area for mowers with vendor maps, zone history on the health page, zones in the fleet map, and editing single corners by dragging (today a shape is redrawn).

---

Mirrored from docs/adr/0070-virtual-zones.md at commit 0031f1857a87c89bad7356661ca60578f18fedaf. Edit the file in the repository, not this wiki page.