thrustlab 0.4.0__tar.gz → 0.5.0__tar.gz

{thrustlab-0.4.0 → thrustlab-0.5.0}/CHANGELOG.md

@@ -8,6 +8,29 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-08-31
+
+### Added
+
+- `client.fmu` can export a completed simulation as an FMI 3.0 co-simulation
+  FMU with per-rotor inputs and outputs, battery and thermal state, and a
+  validity envelope. Exports can be enqueued, checked with paced polling,
+  downloaded when ready, or canceled.
+- The new `thrustlab.sitl` module flies exported FMUs in ArduPilot SITL and
+  Betaflight SITL using a six-degree-of-freedom rigid body, per-rotor servo
+  mapping, and battery voltage, current, and airspeed feedback to the firmware.
+  The `thrustlab-sitl` console command launches the bridge.
+- The new `examples/fmu` gallery includes quadcopter and Y6 SITL missions, an
+  endurance study, and replay rendering.
+- Generated models now cover component datasheets and the `component_specs`
+  entitlement flag.
+
+### Changed
+
+- NumPy, PyYAML, and FMPy are now included in the core installation, so
+  `pip install thrustlab` provides everything needed for SITL. The `[sitl]`
+  extra remains available as an empty compatibility alias.
+
 ## [0.4.0] - 2026-08-27
 
 Contract refresh for the production `/v1/` API. This release adds the current

{thrustlab-0.4.0 → thrustlab-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.5
+Metadata-Version: 2.4
 Name: thrustlab
-Version: 0.4.0
+Version: 0.5.0
 Summary: Official Python SDK for the ThrustLab API
 Project-URL: Homepage, https://thrustlab.com
 Project-URL: Documentation, https://thrustlab.com/docs
@@ -20,14 +20,18 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Requires-Dist: attrs>=23.0
+Requires-Dist: fmpy>=0.3.31
 Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: numpy>=1.24
 Requires-Dist: pydantic<3.0,>=2.7
 Requires-Dist: python-dateutil>=2.8
+Requires-Dist: pyyaml>=6.0
 Provides-Extra: dev
 Requires-Dist: openapi-python-client==0.28.4; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: respx>=0.21; extra == 'dev'
+Provides-Extra: sitl
 Description-Content-Type: text/markdown
 
 # thrustlab — official Python SDK for the ThrustLab API

thrustlab-0.5.0/examples/fmu/ardupilot_sitl/README.md

@@ -0,0 +1,80 @@
+# ArduPilot SITL — fly your exported powertrain
+
+Fly a real ArduPilot mission where the vehicle physics is YOUR ThrustLab
+powertrain: per-rotor thrust and torque, true rotor spin-up, battery sag and
+state of charge — all from the `.fmu` you exported.
+
+## What you need
+
+- An exported FMU (`examples/fmu/export_and_download.py`, or the dashboard's
+  Share menu → Export powertrain).
+- `pip install thrustlab` — the SDK ships the JSON-backend physics bridge
+  (`thrustlab.sitl`).
+- An ArduPilot SITL build (`./waf copter`), any recent Copter.
+- `pip install pymavlink matplotlib numpy` for the mission script and plots.
+
+## Run it (three terminals)
+
+1. The bridge listens first, with your FMU and a vehicle layout. The rpm log
+   goes into `mission_out/` so the plot step finds every recording in one
+   place (create the directory first — the bridge won't):
+
+   ```sh
+   mkdir -p mission_out
+   python -m thrustlab.sitl \
+     --fmu my-powertrain.fmu --vehicle quad_x.yaml \
+     --rpm-log mission_out/mission_rpm_log.csv
+   ```
+
+   `quad_x.yaml` maps servo outputs to rotors (positions, spin directions,
+   mass). Start from the annotated `../quad_5inch_x.yaml` and edit mass
+   and geometry to your airframe.
+
+2. ArduPilot with the JSON model — run from your ArduPilot checkout, and
+   point at this example directory's `fmu.parm` by absolute path:
+
+   ```sh
+   ./build/sitl/bin/arducopter --model JSON:127.0.0.1 \
+     --defaults Tools/autotest/default_params/copter.parm,/path/to/examples/fmu/ardupilot_sitl/fmu.parm -I0
+   ```
+
+   `fmu.parm` needs at least `BATT_MONITOR 4` (the bridge feeds pack voltage
+   and current back into the firmware's battery monitor).
+
+3. The mission:
+
+   ```sh
+   python fly_mission.py --out-dir ./mission_out
+   ```
+
+   It uploads a multi-leg AUTO mission (takeoff, 13 m/s dash, climb, loiter
+   turns, fast descent, RTL), flies it, and records MAVLink telemetry beside
+   the bridge's per-rotor log.
+
+## The plots
+
+```sh
+python plot_mission.py ./mission_out ./mission_out/plots
+```
+
+Three figures from the recorded flight: the mission track colored by
+electrical power, the powertrain time series (per-rotor speed, bus voltage
+and current, power and state of charge), and the loiter-exit close-up where
+the mixer splits the four rotors.
+
+The same recording also renders as an animated replay — the track draws
+itself colored by power while live panels play the powertrain through the
+mission:
+
+```sh
+python render_mission_video.py ./mission_out ./mission_out/video
+```
+
+Frames land in `video/frames/`; with ffmpeg on PATH the mp4 is encoded
+automatically, otherwise the exact encode command is printed.
+
+Per-rotor RPM never crosses the ArduPilot JSON protocol — the protocol has no
+RPM lane — so the bridge logs it to `mission_out/mission_rpm_log.csv` for
+reconciliation against flight logs. If you changed the vehicle mass in
+`quad_x.yaml`, set `WEIGHT_N` at the top of `plot_mission.py` to match — it
+aligns the two recordings' clocks on the takeoff event.

thrustlab-0.5.0/examples/fmu/ardupilot_sitl/fly_mission.py

@@ -0,0 +1,225 @@
+"""Fly a multi-leg AUTO mission against a running ArduPilot SITL whose physics
+is your exported ThrustLab FMU (via thrustlab.sitl), recording MAVLink
+telemetry for the plot script.
+
+Usage: python fly_mission.py [--connect tcp:127.0.0.1:5760] [--out-dir .]
+
+Writes <out-dir>/mission_telemetry.csv and <out-dir>/mission_events.csv; the
+per-rotor truth (rpm, thrust, bus V/I, SOC) is the bridge's own --rpm-log CSV.
+"""
+import argparse
+import csv
+import math
+import sys
+import time
+from pathlib import Path
+
+from pymavlink import mavutil
+
+M_PER_DEG_LAT = 111320.0
+WALL_CAP_S = 900.0
+
+
+def build_mission(home_lat, home_lon, speed_scale=1.0):
+    frame = mavutil.mavlink.MAV_FRAME_GLOBAL_RELATIVE_ALT_INT
+    mav = mavutil.mavlink
+    items = []
+
+    def spd(m_s):
+        return max(2.0, m_s * speed_scale)
+
+    def add(cmd, p1=0, p2=0, p3=0, p4=0, dn=0.0, de=0.0, alt=0.0):
+        lat = home_lat + dn / M_PER_DEG_LAT
+        lon = home_lon + de / (M_PER_DEG_LAT * math.cos(math.radians(home_lat)))
+        items.append((len(items), frame, cmd, p1, p2, p3, p4,
+                      int(lat * 1e7), int(lon * 1e7), float(alt)))
+
+    add(mav.MAV_CMD_NAV_WAYPOINT)                                   # home slot
+    add(mav.MAV_CMD_NAV_TAKEOFF, alt=10.0)
+    add(mav.MAV_CMD_DO_CHANGE_SPEED, p1=1, p2=spd(13.0))
+    add(mav.MAV_CMD_NAV_WAYPOINT, dn=220.0, de=0.0, alt=15.0)       # fast dash
+    add(mav.MAV_CMD_DO_CHANGE_SPEED, p1=1, p2=spd(6.0))
+    add(mav.MAV_CMD_NAV_WAYPOINT, dn=220.0, de=140.0, alt=32.0)     # slow climb
+    add(mav.MAV_CMD_NAV_LOITER_TURNS, p1=2, p3=25.0, dn=220.0, de=140.0, alt=32.0)
+    add(mav.MAV_CMD_DO_CHANGE_SPEED, p1=1, p2=spd(14.0))
+    add(mav.MAV_CMD_NAV_WAYPOINT, dn=60.0, de=60.0, alt=14.0)       # fast descent
+    add(mav.MAV_CMD_DO_CHANGE_SPEED, p1=1, p2=spd(5.0))
+    add(mav.MAV_CMD_NAV_WAYPOINT, dn=25.0, de=0.0, alt=8.0)         # slow approach
+    add(mav.MAV_CMD_NAV_RETURN_TO_LAUNCH)
+    return items
+
+
+def upload_mission(m, items):
+    m.mav.mission_clear_all_send(m.target_system, m.target_component)
+    m.recv_match(type="MISSION_ACK", blocking=True, timeout=5)
+    m.mav.mission_count_send(m.target_system, m.target_component, len(items))
+    t0 = time.time()
+    while time.time() - t0 < 60:
+        msg = m.recv_match(
+            type=["MISSION_REQUEST", "MISSION_REQUEST_INT", "MISSION_ACK"],
+            blocking=True, timeout=10,
+        )
+        if msg is None:
+            raise RuntimeError("mission upload stalled")
+        if msg.get_type() == "MISSION_ACK":
+            if msg.type == mavutil.mavlink.MAV_MISSION_ACCEPTED:
+                print(f"mission accepted ({len(items)} items)", flush=True)
+                return
+            raise RuntimeError(f"mission rejected: ack type {msg.type}")
+        s, frame, cmd, p1, p2, p3, p4, lat, lon, alt = items[msg.seq]
+        m.mav.mission_item_int_send(
+            m.target_system, m.target_component, s, frame, cmd,
+            1 if s == 0 else 0, 1, p1, p2, p3, p4, lat, lon, alt,
+        )
+    raise RuntimeError("mission upload timed out")
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--connect", default="tcp:127.0.0.1:5760")
+    ap.add_argument("--out-dir", type=Path, default=Path("."))
+    ap.add_argument("--speed-scale", type=float, default=1.0,
+                    help="scale every mission leg speed (floor 2 m/s). A coax "
+                         "export's edgewise envelope is tighter than a solo "
+                         "rotor's; ~0.3 keeps a Y6 inside it.")
+    args = ap.parse_args()
+    args.out_dir.mkdir(parents=True, exist_ok=True)
+
+    m = mavutil.mavlink_connection(args.connect, source_system=250)
+    m.wait_heartbeat(timeout=120)
+    print(f"heartbeat from sys {m.target_system}", flush=True)
+
+    # Let the EKF settle; keep the streams coming at 10 Hz.
+    t0 = time.time()
+    while time.time() - t0 < 40:
+        m.mav.request_data_stream_send(
+            m.target_system, m.target_component,
+            mavutil.mavlink.MAV_DATA_STREAM_ALL, 10, 1,
+        )
+        st = m.recv_match(type="STATUSTEXT", blocking=False)
+        if st:
+            print("statustext:", st.text, flush=True)
+        time.sleep(0.5)
+
+    # Home = where the vehicle sits now.
+    gpi = m.recv_match(type="GLOBAL_POSITION_INT", blocking=True, timeout=10)
+    home_lat, home_lon = gpi.lat / 1e7, gpi.lon / 1e7
+    upload_mission(m, build_mission(home_lat, home_lon, args.speed_scale))
+
+    m.set_mode("GUIDED")
+    # GUIDED refuses to arm until the EKF is actually fusing GPS, and how
+    # long that takes in SIM time depends on the machine (a heavy FMU lowers
+    # the effective speedup). Retry instead of racing, and surface every
+    # refusal text instead of hanging in motors_armed_wait().
+    arm_deadline = time.time() + 300
+    armed = False
+    while not armed:
+        if time.time() > arm_deadline:
+            raise RuntimeError("arming timed out — see the refusal texts above")
+        m.arducopter_arm()
+        drain_until = time.time() + 5.0
+        while time.time() < drain_until:
+            msg = m.recv_match(type=["HEARTBEAT", "STATUSTEXT"],
+                               blocking=True, timeout=1)
+            if msg is None:
+                continue
+            if msg.get_type() == "STATUSTEXT":
+                print("statustext:", msg.text, flush=True)
+            elif (msg.get_srcSystem() == m.target_system
+                  and msg.base_mode
+                  & mavutil.mavlink.MAV_MODE_FLAG_SAFETY_ARMED):
+                armed = True
+                break
+    print("armed", flush=True)
+    m.set_mode("AUTO")
+    for _ in range(10):
+        m.mav.command_long_send(
+            m.target_system, m.target_component,
+            mavutil.mavlink.MAV_CMD_MISSION_START, 0, 0, 0, 0, 0, 0, 0, 0,
+        )
+        ack = m.recv_match(type="COMMAND_ACK", blocking=True, timeout=3)
+        if ack and ack.command == mavutil.mavlink.MAV_CMD_MISSION_START:
+            if ack.result == mavutil.mavlink.MAV_RESULT_ACCEPTED:
+                break
+        time.sleep(1)
+
+    tele = open(args.out_dir / "mission_telemetry.csv", "w", newline="")
+    tw = csv.writer(tele)
+    tw.writerow(["t_s", "lat", "lon", "alt_rel_m", "vn_m_s", "ve_m_s", "vd_m_s",
+                 "groundspeed_m_s", "climb_m_s", "throttle_pct",
+                 "roll_deg", "pitch_deg", "yaw_deg",
+                 "voltage_V", "current_A", "battery_pct", "mode"])
+    ev = open(args.out_dir / "mission_events.csv", "w", newline="")
+    ew = csv.writer(ev)
+    ew.writerow(["t_s", "kind", "detail"])
+
+    last = {"vfr": None, "att": None, "sys": None, "mode": None, "gpi": None}
+    armed, was_flying, rows = True, False, 0
+    wall0 = time.time()
+
+    def now_s():
+        return last["gpi"].time_boot_ms / 1000.0 if last["gpi"] else 0.0
+
+    while time.time() - wall0 < WALL_CAP_S:
+        msg = m.recv_match(blocking=True, timeout=10)
+        if msg is None:
+            continue
+        t = msg.get_type()
+        if t == "VFR_HUD":
+            last["vfr"] = msg
+        elif t == "ATTITUDE":
+            last["att"] = msg
+        elif t == "SYS_STATUS":
+            last["sys"] = msg
+        elif t == "HEARTBEAT":
+            mode = mavutil.mode_string_v10(msg)
+            if mode != last["mode"]:
+                ew.writerow([f"{now_s():.2f}", "mode", mode])
+                print(f"mode -> {mode}", flush=True)
+                last["mode"] = mode
+            armed = bool(msg.base_mode & mavutil.mavlink.MAV_MODE_FLAG_SAFETY_ARMED)
+            if was_flying and not armed:
+                print("disarmed after flight — mission complete", flush=True)
+                break
+        elif t == "MISSION_ITEM_REACHED":
+            ew.writerow([f"{now_s():.2f}", "wp", msg.seq])
+            print(f"reached wp {msg.seq}", flush=True)
+        elif t == "STATUSTEXT":
+            ew.writerow([f"{now_s():.2f}", "text", msg.text])
+        elif t == "GLOBAL_POSITION_INT":
+            last["gpi"] = msg
+            if msg.relative_alt / 1000.0 > 2.0:
+                was_flying = True
+            vfr, att, s = last["vfr"], last["att"], last["sys"]
+            tw.writerow([
+                f"{msg.time_boot_ms / 1000.0:.2f}", msg.lat / 1e7, msg.lon / 1e7,
+                f"{msg.relative_alt / 1000.0:.2f}",
+                f"{msg.vx / 100.0:.2f}", f"{msg.vy / 100.0:.2f}", f"{msg.vz / 100.0:.2f}",
+                f"{vfr.groundspeed:.2f}" if vfr else "",
+                f"{vfr.climb:.2f}" if vfr else "",
+                vfr.throttle if vfr else "",
+                f"{math.degrees(att.roll):.1f}" if att else "",
+                f"{math.degrees(att.pitch):.1f}" if att else "",
+                f"{math.degrees(att.yaw):.1f}" if att else "",
+                f"{s.voltage_battery / 1000.0:.3f}" if s else "",
+                f"{s.current_battery / 100.0:.2f}" if s else "",
+                s.battery_remaining if s else "",
+                last["mode"] or "",
+            ])
+            rows += 1
+
+    tele.close()
+    ev.close()
+    print(f"telemetry rows: {rows}", flush=True)
+    if not was_flying:
+        print("FAIL: never left the ground", flush=True)
+        return 2
+    if armed:
+        print("FAIL: still armed at wall cap", flush=True)
+        return 1
+    print("MISSION COMPLETE", flush=True)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

thrustlab-0.5.0/examples/fmu/ardupilot_sitl/fmu.parm

@@ -0,0 +1,6 @@
+# Parameters the FMU bridge flight needs on top of copter.parm.
+FRAME_CLASS 1
+FRAME_TYPE 1
+# The bridge feeds pack voltage/current back over the JSON protocol; monitor
+# type 4 (analog V+I) is how the firmware reads them.
+BATT_MONITOR 4

thrustlab-0.5.0/examples/fmu/ardupilot_sitl/plot_mission.py

@@ -0,0 +1,267 @@
+"""Render a recorded FMU mission into flight-report PNGs.
+
+Reads the bridge's per-rotor CSV (FMU truth: rpm, thrust, bus V/I, SOC) and
+the mission telemetry/events CSVs written by fly_mission.py, aligns the two
+clocks on the takeoff event, and renders three figures:
+
+  fmu_mission_track.png       top-down track colored by electrical power + altitude band
+  fmu_mission_timeseries.png  the powertrain story over time (rpm, V/I, power, SOC)
+  fmu_mission_loiter.png      loiter close-up: per-rotor rpm split vs roll
+
+Usage: python plot_mission.py <data_dir> <out_dir>
+<data_dir> holds mission_rpm_log.csv (from the bridge's --rpm-log),
+mission_telemetry.csv and mission_events.csv (from fly_mission.py).
+"""
+import csv
+import math
+import sys
+from pathlib import Path
+
+import matplotlib
+
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+import numpy as np
+
+# Gruvbox Soft (dark) — frontend/src/app/gruvbox-soft.css
+BG = "#111111"
+SURFACE = "#1b1b1b"
+TEXT = "#f5efe2"
+MUTED = "#bdb0a0"
+AXIS = "#d4be98"
+GRID = (1.0, 1.0, 1.0, 0.10)
+ORANGE = "#e78a4e"
+BLUE = "#7daea3"
+GREEN = "#a9b665"
+PURPLE = "#d3869b"
+AQUA = "#89b482"
+YELLOW = "#d8a657"
+RED = "#ea6962"
+ROTORS = [ORANGE, BLUE, GREEN, PURPLE]
+
+# Your vehicle's weight in newtons (mass_kg * 9.81) — used only to detect
+# takeoff in the bridge log for clock alignment between the two recordings.
+WEIGHT_N = 11.77
+M_PER_DEG_LAT = 111320.0
+
+
+def style():
+    plt.rcParams.update(
+        {
+            "figure.facecolor": BG,
+            "axes.facecolor": BG,
+            "savefig.facecolor": BG,
+            "text.color": TEXT,
+            "axes.edgecolor": AXIS,
+            "axes.labelcolor": MUTED,
+            "xtick.color": MUTED,
+            "ytick.color": MUTED,
+            "axes.grid": True,
+            "grid.color": GRID,
+            "grid.linewidth": 0.8,
+            "font.family": "DejaVu Sans",
+            "axes.titlesize": 11,
+            "axes.titlecolor": TEXT,
+            "axes.spines.top": False,
+            "axes.spines.right": False,
+            "legend.frameon": False,
+            "legend.labelcolor": MUTED,
+        }
+    )
+
+
+def read_csv(path):
+    with open(path, newline="") as f:
+        rows = list(csv.DictReader(f))
+    return rows
+
+
+def col(rows, name, default=np.nan):
+    out = np.empty(len(rows))
+    for i, r in enumerate(rows):
+        v = r.get(name, "")
+        out[i] = float(v) if v not in ("", None) else default
+    return out
+
+
+def main():
+    data = Path(sys.argv[1])
+    out = Path(sys.argv[2])
+    out.mkdir(parents=True, exist_ok=True)
+    style()
+
+    b = read_csv(data / "mission_rpm_log.csv")
+    t_rows = read_csv(data / "mission_telemetry.csv")
+    events = read_csv(data / "mission_events.csv")
+
+    n_rotors = sum(1 for k in b[0] if k.startswith("rpm_"))
+    bt = col(b, "timestamp_s")
+    thrust = sum(col(b, f"thrust_N_{i}") for i in range(n_rotors))
+    rpm = [col(b, f"rpm_{i}") for i in range(n_rotors)]
+    vbus = col(b, "voltage_bus_V")
+    ibus = col(b, "current_bus_A")
+    soc = col(b, "battery_soc")
+    power = vbus * ibus
+
+    tt = col(t_rows, "t_s")
+    alt = col(t_rows, "alt_rel_m")
+    gs = col(t_rows, "groundspeed_m_s")
+    lat = col(t_rows, "lat")
+    lon = col(t_rows, "lon")
+    roll = col(t_rows, "roll_deg")
+
+    # ---- clock alignment: takeoff (bridge thrust > weight) vs (alt > 1 m) ----
+    b_take = bt[np.argmax(thrust > 1.05 * WEIGHT_N)]
+    t_take = tt[np.argmax(alt > 1.0)]
+    bt = bt + (t_take - b_take)
+    print(f"clock offset applied: {t_take - b_take:+.2f} s")
+
+    # Smooth the 400 Hz bridge channels ONCE, globally, before any windowing —
+    # smoothing inside a window leaves edge artifacts at its boundaries.
+    def smooth(x, w=9):
+        return np.convolve(x, np.ones(w) / w, mode="same")
+
+    rpm_s = [smooth(r) for r in rpm]
+    vbus_s = smooth(vbus)
+    ibus_s = smooth(ibus)
+    power_s = smooth(power)
+    soc_s = smooth(soc)
+
+    # Flight window: a little pre-takeoff ramp, ending at the telemetry end;
+    # spool-up and post-kill frames (bus collapsed / negative current) are cut.
+    t0, t1 = t_take - 4.0, tt[-1]
+    bm = (bt >= t0) & (bt <= t1) & (vbus > 20.0)
+    tm = (tt >= t0) & (tt <= t1)
+
+    def dec(x, k=20):
+        return x[bm][::k]
+
+    bt_d = bt[bm][::20]
+    modes = [(float(e["t_s"]), e["detail"]) for e in events if e["kind"] == "mode"]
+    wps = [(float(e["t_s"]), int(e["detail"])) for e in events if e["kind"] == "wp"]
+
+    def mode_lines(ax, label_y=None):
+        for ts, name in modes:
+            if ts < t0 or ts > t1 or name in ("GUIDED",):
+                continue
+            ax.axvline(ts, color=MUTED, lw=0.7, alpha=0.5, ls=(0, (4, 3)))
+            if label_y is not None:
+                ax.annotate(
+                    name, (ts, label_y), color=MUTED, fontsize=7.5,
+                    xytext=(3, 0), textcoords="offset points",
+                )
+
+    # ================= Figure 1: track + altitude =================
+    east = (lon - lon[0]) * M_PER_DEG_LAT * math.cos(math.radians(lat[0]))
+    north = (lat - lat[0]) * M_PER_DEG_LAT
+    p_at_t = np.interp(tt, bt[bm], power_s[bm])
+
+    fig = plt.figure(figsize=(8.0, 9.0))
+    gs_ = fig.add_gridspec(2, 1, height_ratios=[2.4, 1.0], hspace=0.28)
+    ax = fig.add_subplot(gs_[0])
+    sc = ax.scatter(east[tm], north[tm], c=np.clip(p_at_t[tm], 0, None), s=7, cmap="plasma", lw=0)
+    ax.plot(0, 0, marker="^", ms=9, color=TEXT)
+    ax.annotate("launch", (0, 0), xytext=(8, -4), textcoords="offset points",
+                color=MUTED, fontsize=8)
+    ax.set_aspect("equal", adjustable="datalim")
+    ax.set_xlabel("east (m)")
+    ax.set_ylabel("north (m)")
+    ax.set_title("Mission track — colored by electrical power")
+    cb = fig.colorbar(sc, ax=ax, pad=0.02, fraction=0.04)
+    cb.set_label("power (W)", color=MUTED)
+    cb.ax.yaxis.set_tick_params(color=MUTED)
+    plt.setp(cb.ax.get_yticklabels(), color=MUTED)
+    cb.outline.set_edgecolor(AXIS)
+
+    ax2 = fig.add_subplot(gs_[1])
+    ax2.fill_between(tt[tm], 0, alt[tm], color=BLUE, alpha=0.25, lw=0)
+    ax2.plot(tt[tm], alt[tm], color=BLUE, lw=1.6)
+    mode_lines(ax2, label_y=max(alt[tm]) * 0.86)
+    ax2.set_xlabel("mission time (s)")
+    ax2.set_ylabel("altitude (m)")
+    fig.suptitle(
+        "ThrustLab FMU · ArduPilot SITL — the exported powertrain flying a real mission",
+        color=TEXT, fontsize=12.5, y=0.985,
+    )
+    fig.savefig(out / "fmu_mission_track.png", dpi=180, bbox_inches="tight")
+    plt.close(fig)
+
+    # ================= Figure 2: powertrain time series =================
+    fig, axes = plt.subplots(4, 1, figsize=(9.6, 9.4), sharex=True)
+    fig.subplots_adjust(hspace=0.16)
+
+    a = axes[0]
+    a.plot(tt[tm], alt[tm], color=BLUE, lw=1.5, label="altitude (m)")
+    a.set_ylabel("altitude (m)")
+    ag = a.twinx()
+    ag.plot(tt[tm], gs[tm], color=MUTED, lw=1.1, alpha=0.8, label="groundspeed (m/s)")
+    ag.set_ylabel("groundspeed (m/s)", color=MUTED)
+    ag.grid(False)
+    ag.spines["right"].set_visible(True)
+    mode_lines(a, label_y=max(alt[tm]) * 0.9)
+    a.set_title("Flight profile")
+
+    a = axes[1]
+    for i in range(n_rotors):
+        a.plot(bt_d, dec(rpm_s[i]), color=ROTORS[i % len(ROTORS)], lw=1.1, label=f"rotor {i}")
+    a.set_ylabel("rotor speed (rpm)")
+    a.legend(ncol=4, fontsize=8, loc="lower right")
+    a.set_title("Per-rotor speed — FMU state, integrated from torque imbalance")
+
+    a = axes[2]
+    a.plot(bt_d, dec(vbus_s), color=YELLOW, lw=1.4, label="bus voltage (V)")
+    a.set_ylabel("bus voltage (V)", color=YELLOW)
+    ai = a.twinx()
+    ai.plot(bt_d, dec(ibus_s), color=RED, lw=1.1, alpha=0.9, label="bus current (A)")
+    ai.set_ylabel("bus current (A)", color=RED)
+    ai.grid(False)
+    ai.spines["right"].set_visible(True)
+    a.set_title("Battery under load — sag and recovery from the pack surface")
+
+    a = axes[3]
+    a.plot(bt_d, dec(power_s), color=ORANGE, lw=1.3, label="electrical power (W)")
+    a.set_ylabel("power (W)", color=ORANGE)
+    asoc = a.twinx()
+    asoc.plot(bt_d, dec(soc_s) * 100.0, color=AQUA, lw=1.4)
+    asoc.set_ylabel("state of charge (%)", color=AQUA)
+    asoc.grid(False)
+    asoc.spines["right"].set_visible(True)
+    a.set_xlabel("mission time (s)")
+    a.set_title("Energy — power draw and state of charge")
+
+    fig.suptitle(
+        "ThrustLab FMU outputs over one mission — every line is the exported model",
+        color=TEXT, fontsize=12.5, y=0.945,
+    )
+    fig.savefig(out / "fmu_mission_timeseries.png", dpi=180, bbox_inches="tight")
+    plt.close(fig)
+
+    # ================= Figure 3: loiter close-up =================
+    lo_wp = [ts for ts, seq in wps if seq == 5]
+    lo_end = [ts for ts, seq in wps if seq == 7]
+    w1 = (lo_end[0] + 12.0) if lo_end else t0 + (t1 - t0) * 0.75
+    w0 = max(lo_wp[0] - 2.0, w1 - 75.0) if lo_wp else w1 - 75.0
+    bw = (bt >= w0) & (bt <= w1) & (vbus > 20.0)
+    tw = (tt >= w0) & (tt <= w1)
+
+    fig, axes = plt.subplots(2, 1, figsize=(9.6, 5.6), sharex=True)
+    fig.subplots_adjust(hspace=0.14)
+    a = axes[0]
+    for i in range(n_rotors):
+        a.plot(bt[bw][::8], rpm_s[i][bw][::8],
+               color=ROTORS[i % len(ROTORS)], lw=1.2, label=f"rotor {i}")
+    a.set_ylabel("rotor speed (rpm)")
+    a.legend(ncol=4, fontsize=8, loc="upper right")
+    a.set_title("Loiter and exit — the mixer splits the rotors, the FMU answers per rotor")
+    a2 = axes[1]
+    a2.plot(tt[tw], roll[tw], color=PURPLE, lw=1.3)
+    a2.set_ylabel("roll (deg)")
+    a2.set_xlabel("mission time (s)")
+    fig.savefig(out / "fmu_mission_loiter.png", dpi=180, bbox_inches="tight")
+    plt.close(fig)
+
+    print(f"wrote 3 figures to {out}")
+
+
+if __name__ == "__main__":
+    main()