thrustlab 0.3.2__tar.gz → 0.5.0__tar.gz

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

@@ -8,6 +8,129 @@ 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
+multi-rotor, battery-topology, geometry, entitlement, and native Rust solver
+response models. It also removes generated models for an endpoint that is not
+part of the public API.
+
+### Breaking
+
+- Paid accounts now represent unlimited monthly simulation usage explicitly:
+  `CreditBalanceResource.total` and `CreditUsageEventResource.balance_after`
+  may be `None`, and `CreditBalanceResource.unlimited` states whether the
+  account has no monthly usage allowance. Concurrency and HTTP rate limits are
+  still enforced separately.
+- Removed `PreviewRequest` and `GeometryPreviewResponse`. The corresponding
+  `/v1/geometry/preview` operation was not a public live endpoint; use
+  `client.geometry.generate(...)` or `client.geometry.analyze(...)` instead.
+- The generated sweep-point payload is now typed as `SweepPointInputs` with a
+  nested `SweepPointComponentSelection`, replacing the unstructured
+  `SweepPointResourceInputs` model.
+- Generated dynamic schedule enum names now include the nullable-union suffix:
+  `SegmentGroupCommandInThrottleRampType0` and
+  `SegmentGroupCommandInTiltRampType0` replace their unsuffixed counterparts.
+
+### Added
+
+- Single-point, sweep, and dynamic requests accept an ordered `rotors` list.
+  Each rotor can carry its rotation sense and coaxial stack/position metadata;
+  legacy grouped inputs remain accepted for compatibility. Rotor-group counts
+  now support up to 40 rotors.
+- Structured `PackTopologyIn` battery definitions with series, parallel, and
+  leaf nodes. Simulation and dynamic resources return the stored topology.
+- Simulation, sweep, and dynamic resources expose `solver_engine`; dynamic
+  resources also expose `snapshot_version`.
+- Dynamic rotor groups expose the full ESC contract: type, timing, PWM
+  frequency, resistance, motor-wire resistance, and synchronous rectification.
+- Geometry design/generation accepts explicit radial station arrays, hub ratio,
+  airfoil layout, and one to 16 blades. Analysis responses expose validation
+  envelope status/limiting factor and `Ct_raw`, `Cp_raw`, `thrust_raw`,
+  `torque_raw`, and `power_raw`.
+- Entitlements expose `max_concurrent_runs` and `fmi_export`. User resources
+  expose first/last name and required-tier gate metadata.
+
+### Changed
+
+- The published contract and generated models now identify native Rust solver
+  results via the `solver_engine` response field (`prom-rs/0.2.1` in this
+  release).
+- Hobbyist and Pro usage is unlimited. `max_concurrent_runs` communicates the
+  account-wide queue width (one for Hobbyist and five for Pro); request rate
+  limiting remains independent of simulation concurrency.
+- **Physical inputs that were silently accepted out of range are now rejected
+  with a `422` naming the field.** The intervals below were already enforced one
+  layer inside the API, but they were absent from the request schema — so a
+  request carrying one of these values either returned an unhelpful `500` or, for
+  the pinned motor temperatures, was accepted and run. Nothing in range changes:
+  every previously-valid request is still valid and returns the same numbers.
+
+  | Field | Accepted range |
+  | --- | --- |
+  | `density_kg_m3` (simulation, sweep, dynamic, dynamic estimate) | `0 < x <= 2.0` kg/m³ |
+  | `airspeed_m_s` (simulation, sweep) | `0 – 100` m/s |
+  | `airspeed_target` (dynamic schedule segment and CSV row) | `0 – 100` m/s |
+  | `throttle_pct` (rotor group) | `0 – 100` % |
+  | `esc_resistance_mohm`, `esc_motor_wire_resistance_mohm` (rotor group) | `0 – 10000` mΩ |
+  | `battery_esc_wire_resistance_mohm` (simulation, sweep) | `0 – 10000` mΩ |
+  | `motor_t_w`, `motor_t_mag` (rotor group) | `-60 – 250` °C |
+
+  The motor-temperature pins are the ones worth checking in existing code: they
+  are **degrees Celsius**, and a value in kelvin (e.g. `293.15`) used to be
+  accepted and quietly changed the winding resistance and torque constant. It is
+  now a `422`.
+
+  Every one of these bounds also appears in the OpenAPI spec now, so a
+  spec-generated client can see them.
+
+- **`esc_type` now defaults to `six_step` instead of `foc`** on `RotorGroupIn`
+  and `SweepRotorGroupIn` (ESC-7). This is a BEHAVIOUR change for any caller that
+  omits the field: `esc_type` selects the commutation convention — K_volt
+  (1/sqrt(3) vs sqrt(3)/pi), copper and iron multipliers, the six-step advance
+  physics, and the throttle→duty map. Measured on a 400 kV / 14-pole / 50 mOhm
+  motor at 22.2 V: RPM −4.56% at full throttle (−2.56% at 75%, −2.84% at 50%,
+  −3.71% at 25%), thrust −8.91% at full throttle to −5.06% at 75%.
+
+  Why: the API defaulted to `foc` while the web app has always sent `six_step`,
+  so the same powertrain returned different numbers depending on which surface
+  submitted it. Six-step is the researched default — catalog Kv is measured under
+  trapezoidal drive and real hobby ESCs are 120° block commutation — so aligning
+  the API to it makes the two agree without moving the web app.
+
+  **To keep the previous behaviour, send `esc_type="foc"` explicitly.** Stored
+  simulations are unaffected: the column default changed with no backfill, so a
+  run recorded as FOC still re-runs as FOC.
+
+### Fixed
+
+- The source archive now uses an explicit public-package manifest, excluding
+  monorepo-only release tooling while retaining the SDK, tests, examples,
+  changelog, and legal files.
+
 ## [0.3.2] - 2026-07-16
 
 Bug-fix release: a docs-vs-code audit found several SDK surfaces that

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thrustlab
-Version: 0.3.2
+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.21; 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.3.2 → thrustlab-0.5.0}/examples/dynamic/run_and_poll.py

@@ -19,9 +19,11 @@ client = Client()  # reads $THRUSTLAB_API_KEY from the environment
 project = client.projects.create(name="sdk dynamic example")
 
 # Resolve by name, or paste explicit IDs: motor_id = "comp_motor_xxx"
-motor = client.components.find(name="Spektrum Avian 4260 800Kv")
+motor = client.components.find(name="BadAss 2826-820Kv")
 prop = client.components.find(name="10.5x4.5")
-battery = client.components.find(name="Liperior 5000mAh 4S 35C")
+battery = client.components.find(
+    name="Liperior 5000mAh 4S 35C 14.8V Lipo Battery With XT90 Plug"
+)
 
 dyn = client.dynamic_simulations.create(
     project_id=project["id"],

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