AMR Emulator

An advin.io service — spec-faithful emulators of autonomous mobile robot (AMR) interfaces: the vendor-neutral VDA 5050 standard, and the Mobile Industrial Robots (MiR) REST APIs.

VDA 5050 — emulated mobile robots for your master control

packages/vda5050-emulator emulates VDA 5050 mobile robots (MQTT + JSON) — protocol versions 2.0.0, 2.1.0 and 3.0.0, switchable — with an embedded MQTT 3.1.1 broker so evaluation needs zero infrastructure. Every message in and out is validated against the official JSON schemas, vendored with pinned provenance from the VDA5050 repository and re-checked against upstream weekly (vda5050-sync.yml).

uv run vda5050-emulator                  # embedded broker on :1883 + one 3.0.0 robot
uv run vda5050-emulator --spec 2.1.0     # speak VDA 5050 2.1.0 instead
uv run vda5050-emulator --broker 10.0.0.5  # join YOUR existing broker
uv run vda5050-emulator --robots 5 --time-scale 60

Point any master control (or mosquitto_sub) at the printed broker address: the robot publishes retained connection/factsheet, event-driven state and visualization, and consumes order/instantActions (plus zoneSet/responses on 3.0.0) with the full acceptance flow of the recommendation — base/horizon stitching, the complete rejection-error catalogue, action blocking types, zones with the request/response mechanism, hibernation, and a last-will CONNECTION_BROKEN. Chaos goes through the non-standard .../_emulator topic: emergency stop, field violation, localization loss, battery override, teleport, forced action failures, connection drops, time scaling.

from vda5050_emulator import AGVConfig, Broker, MasterControl, VirtualAGV

MiR — self-updating REST API emulator

Emulator of the Mobile Industrial Robots (MiR) robot REST API and the MiR Fleet Enterprise Integration API. Develop and test MiR integrations against a local, spec-faithful /api/v2.0.0 (robot) or /api/v1 (fleet) without owning either — across the newest four minor lines of every major software generation.

./Quickstart -t          # lint + unit + conformance + integration
./Quickstart -s          # serve the newest tracked robot version on :8080

curl -H "Authorization: Basic $(printf '%s:%s' distributor "$(printf distributor | shasum -a 256 | cut -d' ' -f1)" | base64)" \
  http://127.0.0.1:8080/api/v2.0.0/status

uv run amr-emulator --fleet-version 1.5.0   # a MiR Fleet with two embedded robots
curl -H 'x-api-key: distributor' http://127.0.0.1:8080/api/v1/robots

The fleet emulates MiR Fleet Enterprise — by driving robot emulators

amr_emulator.fleet embeds a configurable set of robot emulators and controls them the way a real MiR Fleet does: over the robots' own REST API (auth, validation, mission simulation — the full HTTP stack, via an in-process ASGI transport). A POST /api/v1/serial-order really enqueues missions on a robot's /mission_queue; order status is derived live from the robot's simulation, so the fleet view and the robot view can never disagree. X-AMR-Session composes: one session id gets an isolated fleet and isolated robots. Fleet specs are MiR's official OpenAPI 3 documents, served verbatim (no PDF conversion) — see the public Swagger UI for the canonical reference; the emulator links to it rather than rebuilding it.

How it stays current

1. scrape.yml runs weekly: logs into the MiR support portal, parses the REST API files listing (~500 PDFs, one per product per version), and applies the selection rule — for every major release line, the latest patch of each of its newest 4 minor lines (so both MiR software generations stay covered four API revisions deep).
2. MiR publishes the API definitions as PDFs only (swagger2markup + Asciidoctor renderings of their internal swagger doc). The scraper picks one robot PDF per selected version (MIR250 preferred; FLEET/HOOK are different APIs and excluded) and converts it back to Swagger 2.0 (amr_spec_scraper/pdf_convert.py).
3. The converter is gated by a correctness oracle: MiR published exactly one machine-readable spec ever (3.5.4 swagger.json, pinned in the registry). Every scrape run re-converts the 3.5.4 PDF and requires zero structural differences (operations, parameters, response schemas, definition property types) against that official document.
4. New or changed specs land in packages/amr-emulator/src/amr_emulator/specs/ + registry.json via an automated PR; ci.yml proves every tracked version against the full conformance + adversarial suite before it merges.
5. The fleet half of the same scrape needs no credentials: MiR publishes Fleet Enterprise as native OpenAPI 3 JSON at public URLs. Discovery probes forward from the tracked versions (new patches, minors, majors) and the same selection rule applies per major line.
6. release.yml builds one amr-emulator wheel per tracked MiR version as an attested workflow artifact. Nothing is published to PyPI — the product is the hosted endpoint; run locally from a checkout.

Secrets

• MIR_PORTAL_EMAIL / MIR_PORTAL_PASSWORD — portal credentials (free account); without them the scrape workflow no-ops with a notice.
• OPEN_ROUTER_API_KEY (optional) — adds an AI-generated "release impact" summary on top of the mechanical API changelog in scrape PRs (model: anthropic/claude-sonnet-5, override with AMR_SUMMARY_MODEL). Strictly best-effort: any failure falls back to the mechanical report.

Tracked versions

packages/amr-emulator/src/amr_emulator/specs/registry.json is the authoritative list (versions, hashes, provenance, source PDF URLs). New releases are picked up as the latest patch of each major's newest 4 minor lines; once tracked, a minor line is permanent — it keeps updating to its latest patch but is never dropped. Currently:

Family	Versions	Source
VDA 5050	3.0.0, 2.1.0, 2.0.0	Official JSON schemas, vendored from VDA5050/VDA5050 (provenance in vda5050_emulator/schemas/registry.json)
Robot REST API 3.x	3.8.1, 3.7.2, 3.6.7, 3.5.6	Converted from the official MiR250 REST API PDFs
Robot REST API 3.x	3.5.4 (pinned)	Official swagger.json — the converter's oracle
Robot REST API 2.x	2.14.7, 2.13.5.4, 2.12.0.4, 2.10.5.8	Converted from the official MiR250 REST API PDFs
Fleet Integration API	1.5.0, 1.4.2, 1.3.1	Official OpenAPI 3 JSON, served verbatim (public URLs)

What the emulator does

• Serves every operation in the loaded spec under /api/v2.0.0 (289 operations across 159 paths in 3.8.1), with responses that validate against the spec's response schemas. Deterministic: same requests, same answers.
• Stateful where it matters: /status (PUT merges), /mission_queue (POST enqueues Pending entries with monotonic ids, DELETE clears), /registers (200 PLC registers, read/write), generic CRUD with create/read/update/delete semantics everywhere else. /metrics speaks OpenMetrics.
• MiR-style auth: Authorization: Basic BASE64(user:SHA-256(password)), default account distributor/distributor like a factory robot. Override with --username/--password or disable with --no-auth.
• Made for hardening: /_emulator/faults injects emergency stop, error, localization loss, critical battery, and blocked-path states (session- isolated; holding faults freeze the mission simulation); /_emulator/battery sets the battery level and runs charging curves toward a target; on a fleet, /_emulator/robots/{robot-id}/{faults|battery} proxies both surfaces to an embedded robot so orders can be chaos-tested in flight; /_emulator/clock runs simulated time Nx wall speed (process-wide) so missions and charging keep realistic durations and timestamps while tests wait seconds, not minutes (--time-scale at startup); X-AMR-Latency delays any response for timeout testing; X-AMR-Mission-Duration gives one queue entry its own runtime (real routes are not uniform); /_emulator/diff?from=&to= on the dispatcher reports structural API changes between tracked versions.
• Middleware-ready: serves its own API definition at /swagger.json (Swagger 2.0, verbatim) and /openapi.json (OpenAPI 3.0, converted and round-trip-validated) so SDK generators and contract-testing tools can point straight at it; --cors for browser dashboards; --export openapi3 to dump the definition; Dockerfile + compose.yaml for CI service stacks (docker compose up → MiR 3.8.1 on :8080 and 2.14.7 on :8081).

from amr_emulator import create_app, supported_versions

app = create_app("3.8.1")  # ASGI app: run under uvicorn, or hit with httpx/TestClient

Layout

• packages/vda5050-emulator/ — VDA 5050 mobile-robot emulator (asyncio; embedded MQTT 3.1.1 broker, virtual AGV core, fleet-control test client). Bundles the official schemas for every tracked protocol version.
• packages/amr-vda5050-adapter/ — VDA 5050 robot-side adapter for MiR: drive a MiR robot (real or emulated) from any VDA 5050 master control. Validated live: Isaac Mission Dispatch → adapter → amr-emulator.
• packages/arcl-emulator/ — Omron ARCL (LD/HD AMR) emulator: line-based TCP protocol per the public I617-E-02 reference manual, with the fleet queuing loop, docking/charging and fault injection.
• packages/amr-emulator/ — the emulator library (Starlette; spec-driven routes + behavior overlays). Bundles all tracked spec files.
• packages/amr-spec-scraper/ — portal login, listing parser, selection rule, registry updater.
• tests/ — cross-version conformance, adversarial/negative-path, and real-TCP integration suites, parametrized over every tracked version.
• scripts/build_versioned.py — stamps and builds one wheel per MiR version.

Hardening

Test harness: every tracked version runs the conformance suite (every operation answered with a declared status, every GET body validated against its response schema), an adversarial suite (auth bypass, injection, traversal, oversized payloads, concurrency races), and a deterministic hypothesis fuzz suite whose invariant is no input produces a 5xx or a non-JSON error — plus real-TCP integration tests and an offline test of the full scraper state machine (pinning, dropping, broken-file fallback). CI gates coverage at 82% offline; the PDF converter's full-document path is gated live by the 3.5.4 oracle on every scrape.

Supply chain: SHA-pinned actions, permissions: {} + least-privilege jobs, locked installs everywhere, Dependabot (uv + actions), CodeQL, PR dependency review, and build-provenance attestations on release wheels. Details and hard limits: SECURITY.md.

Self-improvement loop: the weekly scrape opens PRs whose body is an API changelog (added/removed/changed operations and definitions), re-validates the converter against the pinned oracle first, survives individually broken portal files by falling back to the last good spec of that major, and files a scraper-attention issue whenever anything needed human eyes — a new major, a new file format, or a PDF shape the converter can't parse cleanly.

Dependencies (why each exists)

Runtime: starlette + uvicorn (ASGI routing/serving), jsonschema (request/response validation against the spec), pyyaml (YAML specs), httpx (scraper HTTP + test client), pdfplumber (scraper only: the portal publishes PDFs, and its ruled-table extraction is what makes the PDF→swagger conversion reliable). Dev: pytest, hypothesis (property tests on the input-handling paths), ruff, ty.

License

MIT — use it freely, commercially or not; the only ask is that the copyright notice stays with the code. If this emulator saves you robot time, a mention is appreciated.