Home

A320 Systems Twin — Wiki

A headless digital twin of the A320's aircraft systems — no MSFS, no X-Plane — built on FlyByWire's open-source Rust systems code, operable from a terminal by a human or over MCP by an LLM agent.

The real interaction between an A320's systems — electrical, hydraulic, pneumatic, fuel, APU, pressurization, and the warning logic that raises ECAM cautions — lives in FlyByWire's Rust crates and does not need a flight simulator at runtime. This project compiles those crates natively, wraps them in a persistent tick loop, and exposes one control/observe API through two frontends:

• a CLI for a human to operate the aircraft from the terminal — flip switches, read buses, advance time, inject failures;
• an MCP server for an LLM to fly the closed loop: observe (ECAM + state) → reason (QRH) → act → advance → observe again.

The end goal is a reproducible environment for failure detection and management following real procedures (ECAM/QRH), designed as an LLM-agent benchmark. The research contribution is not the aircraft model (that is FlyByWire's) — it is the evaluable environment, the failure-scenario suite, and the procedure-compliance scoring.

Status: Phases 0–4 shipped (core, CLI, MCP, hydraulics/APU/fuel/engine-start). Phase 5 (the benchmark) is in progress. See Roadmap.

---

Where to go

Get started

• Installation — prerequisites, the pinned FlyByWire submodule, and the layered install (bindings → CLI / MCP / bench).
• Quickstart — take the aircraft from cold & dark to a powered network in the REPL.

Operate the aircraft

• CLI-Reference — every REPL command (set / get / run / watch / fail / ecam …).
• MCP-Server — the LLM's window: tools, start states, the two profiles, the agent loop.
• Controls-and-Variables — the curated control catalog vs raw LVARs, and reading state.
• Failures-and-ECAM — injecting failures and how read_ecam works without an FWC.

Benchmark (research)

• Benchmark-Overview — what Phase 5 is, and the run → record → score pipeline.
• Scenarios — the scenario YAML format, ground truth, and the shipped scenarios.
• Scoring — the procedure-compliance metric: component vector, derived scalar, safety gate.
• Running-the-Benchmark — the a320-bench commands and providers.

Reference

• Architecture — one core, two frontends; what's reused vs built; the API contract.
• Design-Decisions — an English index into the project's decision log (ADR).
• Roadmap — the phases and their status.

---

For contributors

The authoritative design notes live in the repo, in Spanish: docs/decisiones.md (ADR), docs/lecciones.md (lessons learned), and the phase notes (docs/fase*.md). Project conventions are in CLAUDE.md. This wiki summarizes and links them rather than duplicating them.

License

GPLv3, inherited from the FlyByWire crates this project vendors and links against. All aircraft systems modeling credit goes to the FlyByWire team. The vendored tree is pinned to commit 13bce4b — benchmark reproducibility depends on it. See Design-Decisions.