The libraries under libs/ are independent Python packages in the uv workspace, Apache-2.0 except mowdeck-control-mammotion (GPL-3.0, ADR 0011). Services depend on them with { workspace = true } sources. Each library has its own README with the full reference; this page is the overview.

No I/O, only pydantic. Everything is versioned under mowdeck_contracts.v1:

• envelopes: CommandEnvelope (command id, expiry, priority), CommandResult, EventEnvelope[Payload].
• mower: MowerState telemetry (observed_at is the time of the mower's report, heartbeat_at and connected the gateway's link, set by the Device-Gateway only, ADR 0040; its position_source says where the position comes from: rtk, gnss without an RTK fix, dock for the charging station while docked, unknown) and the commands StartMow, PauseMow, ResumeMow, ReturnToDock, EmergencyStop, SetBladeHeight, SetSpeed, ManualDrive.
• capabilities: MowerCapabilities (native patterns, manual drive, blades while driving, custom paths, camera access, RTK sources, blade height range, minimum and maximum speed, connection kinds).
• maps: MowerMap with areas, no-go zones, obstacles, paths and dock in local metres plus a GeoReference for WGS84.
• fleet: MowerRegistration (mower, account, name, connection kind and options), MowerListRequest / MowerListReply for fleet.mowers.list, MowerConnectionEvent for mower.connected and mower.disconnected.
• commands: Fleet's command API, CommandRequest, CommandAccepted, CommandView with CommandState, BulkCommandAccepted with one BulkCommandItem per visible mower.
• notifications: NotificationSent (payload of notifications.sent), NotificationKind, NotificationSeverity and WebPushPayload, the JSON a service worker receives (ADR 0022).
• principal: Principal mirrors the claims of the Identity access token.
• module: ModuleDescriptor, served by every service at /.well-known/mowdeck-module.
• problem: RFC 9457 ProblemDetails.
• spot: SpotMowPlan (segments as encoded polylines, SHA-256 plan_hash, optional native job) for StartMow.spot_plan and SpotMow.plan, encode_polyline / decode_polyline (ADR 0030); SpotRunStatus (MowerState.spot_run) and MAX_SPOT_MOW_SPEED_MPS for spot runs driven by MowDeck (ADR 0039).
• calibration: DriveCalibration (stored as link options), DriveCalibrationStatus (MowerState.drive_calibration), DriveSpeedSetting (MowerCapabilities.drive_speed_setting) for the drive calibration and the vendor's speed setting for manual driving (ADR 0042).
• positions: PositionTrackRequest / PositionTrackReply for the track query tracks.positions.query (Telemetry).
• subjects: command_subject(id), telemetry_subject(id), event_subject(domain, name), wildcards, the request subject FLEET_MOWERS_LIST and the streams COMMANDS, TELEMETRY, EVENTS.

from uuid import uuid4
from mowdeck_contracts.v1 import CommandEnvelope, EmergencyStop, PrincipalKind, PrincipalRef
from mowdeck_contracts.v1.subjects import command_subject

stop = CommandEnvelope.create(
    mower_id=uuid4(),
    account_id=uuid4(),
    issued_by=PrincipalRef(subject=uuid4(), kind=PrincipalKind.USER),
    command=EmergencyStop(),
)
assert stop.priority == "emergency"
subject = command_subject(stop.mower_id)  # "command.mower.<id>"

After changing a model, regenerate the committed JSON Schemas (a test fails otherwise):

uv run python -m mowdeck_contracts.schemas libs/mowdeck-contracts/schemas

The envelope, subject and versioning rules are recorded in ADR 0009.

Mowing patterns as plug-ins and the route validation chain, pure computation on Shapely (no network, no database). A pattern is a class with key, name, settings_schema() and compute(area, mower, settings), registered through the entry point group mowdeck.patterns; plan() computes a chain and runs the validation chain (inside the area minus the safety margin, no blades on through zones or holes, blades off on transfers, turning radius):

from mowdeck_patterns import Area, MowerSpec, plan, preview

area = Area.of(
    [(0, 0), (12, 0), (12, 8), (0, 8)], no_go_zones=[[(9, 5.5), (12, 5.5), (12, 8), (9, 8)]]
)
result = plan(area, MowerSpec(cutting_width_m=0.4), [("edge_only", {"laps": 2}), "diagonal"])
spot = result.to_spot_plan()  # StartMow(spot_plan=spot)

Built-in patterns, coverage and gaps, turn styles at lane ends (TurnOptions, shape_turns, ADR 0043) and how to add a pattern: libs/mowdeck-patterns/README.md. The Planner service (services/planner) serves it over HTTP (ADR 0030).

A service is one create_app call:

from fastapi import APIRouter
from mowdeck_contracts.v1 import ModuleDescriptor, PermissionDef
from mowdeck_service_kit import CurrentAccountId, ServiceSettings, create_app, run

router = APIRouter()


@router.get("/whoami")
async def whoami(account_id: CurrentAccountId) -> dict[str, str]:
    return {"account_id": str(account_id)}


settings = ServiceSettings.from_env()  # MOWDECK_* variables, *_FILE secrets
descriptor = ModuleDescriptor(
    name=settings.service_name,
    version="0.1.0",
    permissions=[PermissionDef(key="mower.view", description="View mowers")],
)
app = create_app(settings, descriptor, routers=[router])
run(app, settings)

What every service gets from it:

Tests use mowdeck_service_kit.testing: make_test_app, make_principal, StaticPrincipalResolver and lifespan_client. Every endpoint that touches account data needs a cross-tenant test; the kit README shows the pattern.

Integration tests against a real NATS server run when MOWDECK_TEST_NATS_URL is set:

docker run -d --name mowdeck-test-nats -p 4222:4222 public.ecr.aws/docker/library/nats:2.15.0-alpine -js
MOWDECK_TEST_NATS_URL=nats://127.0.0.1:4222 uv run pytest libs/mowdeck-service-kit
docker rm -f mowdeck-test-nats

Mower control without the platform, usable from scripts and other projects. Depends only on mowdeck-contracts; never imports PyMammotion (that adapter lives in the GPL-3.0 package mowdeck-control-mammotion, see ADR 0011). The design is recorded in ADR 0012.

flowchart LR
    gw["Device-Gateway / script"] -->|CommandEnvelope| ctl["MowerController"]
    ctl -->|CommandResult, MowerState| gw
    ctl --> conn{{"MowerConnection"}}
    conn --> sim["SimulatedMower"]
    conn --> mam["mowdeck-control-mammotion (GPL-3.0)"]

from mowdeck_control import MowerController, SimulatedMower

mower = SimulatedMower()
async with MowerController(mower, mower_id=mower.mower_id, on_state=publish) as controller:
    result = await controller.handle(envelope)  # CommandEnvelope -> CommandResult

Try it from the command line:

uv run python -m mowdeck_control.demo --seconds 3 --interval 0.5 --time-scale 60

The library README covers the safety rules in detail, the simulator hooks and the checklist for writing a new adapter.

The real adapter for Mammotion mowers, GPL-3.0-only because it imports PyMammotion (ADR 0011); transports, manual drive, secrets and pins are decided in ADR 0019. It registers two connection kinds through the entry point group mowdeck.connections, so the Device-Gateway uses them without code changes:

Only port.py imports pymammotion; everything else uses the small MammotionPort protocol, and the tests use FakeMammotionPort, built from the real PyMammotion data classes. Pins: pymammotion==0.10.9 exactly plus packaging; the esphome extra pins aioesphomeapi, bleak-esphome, habluetooth and bluetooth-adapters to PyMammotion's lock file.

from mowdeck_contracts.v1 import ConnectionKind
from mowdeck_control import ConnectionConfig, MowerController, create_connection

connection = create_connection(
    ConnectionKind.CLOUD,
    ConnectionConfig(
        mower_id=mower_id,
        account_id=account_id,
        options={
            "account": "[email protected]",
            "credential_ref": "env:MAMMOTION_PASSWORD",
            "device_name": "Luba-VP...",
        },
    ),
)
async with MowerController(connection, mower_id=mower_id) as controller:
    result = await controller.handle(envelope)

While a drive session is open the refresh loop keeps the report window open and polls for an undebounced report whenever none arrived for a second, so spot runs (ADR 0039) get a pose about once a second.

The owner script libs/mowdeck-control-mammotion/scripts/try_real_mower.py runs the adapter against the real mower (or --dry-run against the fake), including --turn-check and --spot-dry-run for spot mowing; see "Testing with a real mower" in libs/mowdeck-control-mammotion/README.md.

Services ask one question: may this subject do this on that object. The model is infra/openfga/model.fga; its design and the reasons are in ADR 0014 and the design document.

from mowdeck_authz import OpenFgaAuthorizer, Relation, mower, principal_subject

authz = OpenFgaAuthorizer.from_env(registry=app.state.metrics_registry)  # MOWDECK_OPENFGA_*
allowed = await authz.check(principal_subject(principal), Relation.CAN_CONTROL, mower(mower_id))

from mowdeck_authz import Relation
from mowdeck_authz.fastapi import install_authz, path_object, require_or_not_found

CanControl = Annotated[
    Principal, Depends(require_or_not_found(Relation.CAN_CONTROL, path_object("mower", "mower_id")))
]
install_authz(app, authz)  # also makes the kit's require_permission() ask OpenFGA

Integration tests against a real OpenFGA run when MOWDECK_TEST_OPENFGA_URL is set:

docker run -d --name mowdeck-test-openfga -p 18080:8080 ghcr.io/openfga/openfga:v1.22.0 run   --datastore-engine memory --authn-method preshared --authn-preshared-keys test-key
MOWDECK_TEST_OPENFGA_URL=http://127.0.0.1:18080 MOWDECK_TEST_OPENFGA_TOKEN=test-key   uv run pytest libs/mowdeck-authz
docker rm -f mowdeck-test-openfga

Model tests: uv run poe fga-test. After editing model.fga, regenerate the packaged JSON with uv run poe fga-json.

Every service verifies Identity's access tokens locally; nothing calls Identity per request (ADR 0015).

from mowdeck_auth import principal_resolver_from_env

app = create_app(
    settings, DESCRIPTOR, routers=[router], principal_resolver=principal_resolver_from_env()
)

Settings: MOWDECK_AUTH_JWKS_URL (Compose: http://identity:8000/.well-known/jwks.json), MOWDECK_AUTH_ISSUER, MOWDECK_AUTH_AUDIENCE, MOWDECK_AUTH_LEEWAY_SECONDS, MOWDECK_AUTH_JWKS_CACHE_SECONDS, MOWDECK_AUTH_JWKS_REFRESH_COOLDOWN_SECONDS. Full reference: libs/mowdeck-auth/README.md.

Mirrored from docs/dev/libraries.md at commit 6a87264c6123f07c8474e153053525dc1816feb7. Edit the file in the repository, not this wiki page.