ADR 0071 Capability Matrix

ADR 0071: Capability matrix generated from the adapters

Status

Proposed (2026-10-30). Extends ADR 0066 (ProviderSpec gains an optional field) and builds on ADR 0012 (capabilities), ADR 0046 (settings as capabilities) and ADR 0067 (error lexicons).

Context

MowDeck shows exactly what a connected mower can do: every feature is gated by MowerCapabilities, by the settings the mower declares (ADR 0046) and by the options of its provider (ADR 0066). Nobody can see that before a mower is linked, though. Someone who wants to know whether MowDeck drives a LUBA 1 by joystick, whether a Landroid reports its position or whether an Automower can be started from MowDeck has to read adapter code or ADRs, and the tables in ADR 0066 and the root README are written by hand, so they age with every change.

Three things make a static table hard:

• Capabilities are a run-time value. MowerConnection.capabilities() depends on the exact model (Mammotion reads blade height and speed ranges from PyMammotion's model table once the mower names its sub model), the firmware (some settings, obstacle detection modes), add-on modules (Worx cutting height and GPS modules), the account setup (Worx zones) and the links that are up (reverse driving only over the Bluetooth bridge).
• "No" has two meanings. A mower can lack a feature because the mower or its vendor's API does not offer it (no Husqvarna API call drives a mower by joystick), or because MowDeck has not built it yet (the Husqvarna API sets a cutting height, as a level that MowDeck does not map yet). MowerCapabilities defaults everything to "not supported" and cannot tell the two apart.
• The core must not learn vendor names (test_vendor_isolation.py): whatever renders the table may only reach the adapters through their entry points.

Decision

Adapters declare capability profiles; a generator renders the matrix from them.

1. Contract (mowdeck_contracts.v1.capability_profiles, Apache-2.0, neutral): a CapabilityProfile describes one model family of a provider: family (id), name, models (models or device name prefixes), capabilities (a MowerCapabilities value), reports (the state the family fills, ProfileReport: position, map geometry, job progress, blade height, satellites, signal, error codes, lift detection, rain sensor, battery cycles, firmware version, base station), varies, not_offered, tested_on_hardware and notes (LocalizedText, English and German like every provider text). The keys are neutral words: ProfileFeature (derived from MowerCapabilities by profile_features(): transports, patterns, start options and plans, dock keeps job, blade height, spacing, speed, manual driving, reverse, blades while driving, drive speed setting, spot mowing, undock, custom paths, light, camera, RTK, firmware updates, base station updates, maintenance), ProfileReport and the setting keys of SETTING_KEYS. The model refuses unknown keys, a key that both varies and is not offered, and a key marked not offered that the capabilities declare.
2. Supported, varies, not offered, not yet. A key is supported when the profile's capabilities, reports or settings declare it; it varies when the adapter lists it in varies (depends on model, firmware, module, link or setup; supported or not on the representative); it is not offered when the adapter lists it in not_offered (the mower or its vendor's API does not have it, so MowDeck cannot); every other key is not yet supported by MowDeck. This is the minimal, provider-neutral way to tell "not by the vendor" from "not yet in MowDeck": one set of neutral keys per family, declared next to the code that knows the vendor, validated by the contract. MowerCapabilities itself stays unchanged: a running mower needs no reason for a "no".
3. Capabilities are computed, not written. Each adapter builds its profile with its own capability code for a representative mower of the family: Mammotion calls mapping.capabilities_of with a device of the family's first device type, a sub model from PyMammotion's model table and the arguments a dual connection passes while every link is up and every option is on (firmware newer than every gate); it checks settings, camera and light for every device type of the family and marks what only some of them have as varies. Worx computes capabilities_of for a fully equipped mower (every module, zones, edge cut, rain delay); Husqvarna for its single capability set. A change in the capability code changes the matrix.
4. Families are the adapter's choice. Mammotion declares six (LUBA 1, LUBA 2 AWD, LUBA 2 AWD X, LUBA mini and LUBA 3, Yuka, Yuka mini; the device types are PyMammotion's, a test keeps them disjoint and checks every device name prefix classifies into its family), Husqvarna and Worx one each (their APIs answer every model the same way; equipment differences are varies with notes). tested_on_hardware is per family (only the LUBA 2 AWD X) and may only be true when the provider's descriptor says so.
5. Where the profiles come from. ProviderSpec.capability_profiles: Callable[[], Sequence[CapabilityProfile]] | None (default None). It is a callable, so the spec stays importable without the vendor SDK. No new entry point group: profiles belong to a provider, and every adapter that reaches mowers through a vendor cloud already registers a spec. The simulator is no provider and has no profile.
6. The generator. tools/repo-checks/scripts/capability_matrix.py (uv run poe capability-matrix, check capability-matrix-check in the CI docs job, like api-reference-check) loads the specs with mowdeck_control.providers.installed_specs() (the mowdeck.cloud_providers entry points), reads each descriptor from the plugin on its fake cloud (no network), takes the error lexicon that serves the provider from ErrorLexiconRegistry (the mowdeck.error_lexicons entry points) and writes docs/reference/capabilities.md: a legend, an overview (families, connections, lexicon size, tested on hardware, on by default), then per provider its summary, warnings (ProviderDescriptor.warnings), the untested note, the families with their models, and one table per group (commands, connection, mowing jobs, driving, hardware and maintenance, state reported, device settings) with a column per family and shared or per-family notes. It imports no vendor package by name. The output is deterministic, so the check compares the committed page with a fresh rendering. It fails when a family is declared twice or claims hardware tests the provider does not.
7. Basic commands. Start, pause, resume, return to dock and the emergency stop are part of every MowerConnection (ADR 0012), so the matrix shows them as supported everywhere; how a vendor carries out the emergency stop (Husqvarna and Worx: an immediate pause) is a note of the family.

Web app: not now. Showing the matrix in the web app (for example next to the provider choice of "link an account") would need the profiles on the bus and in Fleet's API: a field on CloudProvidersReply or a gateway.cloud.profiles subject, a Fleet schema with resolved texts, the OpenAPI export and generated types. That is more than a small change, so it is a follow-up; the profiles are a contract model already, so the data is ready to be served. Until then the documentation page is the one place.

Alternatives considered.

• A hand-written table (as in ADR 0066 and the README): ages with every change; rejected.
• A reason field per capability in MowerCapabilities: changes the run-time contract every client reads for a documentation need, and the vendor's limits are a property of the family, not of each connection; rejected.
• A new entry point group mowdeck.capability_profiles: also covers connection kinds without a provider, but the vendor boundary test and every adapter would gain a third declaration for data that belongs to the provider; not now.
• Grouping device types automatically by equal capabilities: exhaustive, but gives columns without meaningful names and splits families over firmware details; families stay curated, with varies for what differs inside one.

Consequences

• docs/reference/capabilities.md is generated and in the MkDocs navigation (and the wiki mirror); CI fails when it disagrees with the code. A new provider declares profiles (docs/dev/cloud-providers.md), and test_capability_matrix.py fails when an installed provider declares none.
• not_offered is a claim about the vendor; the adapters base theirs on the ADR 0066 research and their own docstrings. A wrong claim is fixed in the adapter, like a wrong capability.
• The first rendering already shows gaps: the Husqvarna connection reads plan references (schedule, duration, work_area) but declares no start_plans, so the web app offers no start for Husqvarna mowers (row "Start plans": not yet); Husqvarna headlight mode and cutting height level are not mapped yet.
• Follow-ups: serve the profiles to the web app (see above); a profile for connection kinds without a cloud provider if one appears; let the conformance kit (ADR 0069) check that a profile's capabilities equal what the connection declares for the representative mower.

---

Mirrored from docs/adr/0071-capability-matrix.md at commit 0031f1857a87c89bad7356661ca60578f18fedaf. Edit the file in the repository, not this wiki page.