@protoboardai/ext-drone 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,13 @@
+Protoboard Stack: @protoboardai/ext-drone
+Copyright 2026 Delta Robotics, Inc.
+
+This product includes software developed at Delta Robotics, Inc.
+(https://deltaroboticsinc.com).
+
+Licensed under the Apache License, Version 2.0 (the "License").
+See the LICENSE file in this package for full terms.
+
+"Protoboard", the Protoboard logo and the "0" mark are trademarks of
+Delta Robotics, Inc. The License grants no rights to them (section 6);
+see TRADEMARKS.md in the Protoboard Stack repository
+(https://github.com/Delta-Robotics-Inc/protoboard-stack).

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @protoboardai/ext-drone
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Flight-controller configuration for multirotor drones.
+
+Part of [Protoboard](https://github.com/Delta-Robotics-Inc/protoboard-stack), which designs hardware with your AI agent. A project lists this extension in its `protoboard.config.ts`; the Protoboard templates add it where it fits. You rarely install it by hand: the [command line](https://www.npmjs.com/package/@protoboardai/cli) and the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=deltarobotics.vscode-protoboard) bring it with them.
+
+- [Installation guide](https://github.com/Delta-Robotics-Inc/protoboard-stack/blob/main/docs/guides/installation.md)
+- [Source](https://github.com/Delta-Robotics-Inc/protoboard-stack/tree/main/packages/ext-drone)
+- [Report an issue](https://github.com/Delta-Robotics-Inc/protoboard-stack/issues)
+
+Apache 2.0. Protoboard is a trademark of Delta Robotics, Inc.

package/evals/gps-moved-to-uart3/case.json

@@ -0,0 +1,32 @@
+{
+  "schema": "protoboard.eval-case/v0",
+  "title": "Update the flight-controller configuration after the GPS moved to UART3",
+  "skills": ["firmware-config"],
+  "tags": ["firmware"],
+  "fixture": {
+    "from": "../../../../examples/quadcopter-5in",
+    "exclude": ["docs"],
+    "steps": [
+      {
+        "note": "the model change: the GNSS lead's UART wires are soldered to the UART3 pads (the configuration still says UART1)",
+        "replace": { "file": "src/quadcopter.uhd.ts", "find": "p2: \"fc:uart1_tx\", p3: \"fc:uart1_rx\"", "with": "p2: \"fc:uart3_tx\", p3: \"fc:uart3_rx\"", "count": 1 }
+      }
+    ]
+  },
+  "instruction": "We re-soldered the GPS lead to the flight controller's UART3 pads, and the model (src/quadcopter.uhd.ts) already says so. Bring the flight controller's Betaflight configuration in firmware/ up to date with the model, and tell me which serial port lines changed.",
+  "tools": { "read": true, "edit": true, "commands": ["npx protoboard *"] },
+  "budget": { "turns": 15, "seconds": 600, "usd": 2 },
+  "graders": [
+    { "id": "check-clean", "kind": "check", "maxErrors": 0 },
+    { "id": "gps-on-uart3", "kind": "text", "file": "firmware/betaflight/cli.txt", "matches": ["serial UART3 2 115200", "set gps_provider = UBLOX"], "notMatches": ["serial UART1 2 "] },
+    { "id": "rest-unchanged", "kind": "text", "file": "firmware/betaflight/cli.txt", "matches": ["serial UART2 64 115200 57600 0 115200", "serial UART5 131073 ", "set motor_pwm_protocol = DSHOT600"] },
+    { "id": "reference-generated", "kind": "operation", "run": ["betaflight-cli", "--input", "out=firmware/betaflight/regenerated.txt"], "status": "succeeded", "weight": 0, "description": "the generator's output for the model, as the reference for the next grader" },
+    { "id": "matches-generator", "kind": "digest", "file": "firmware/betaflight/cli.txt", "sameAs": "firmware/betaflight/regenerated.txt", "description": "cli.txt is exactly what the generator makes from the model: regenerated, not patched by hand" },
+    { "id": "answer", "kind": "text", "matches": ["UART3", "UART1"] },
+    { "id": "model-untouched", "kind": "digest", "file": "src/quadcopter.uhd.ts", "changed": false }
+  ],
+  "solution": [
+    { "protoboard": ["run", "betaflight-cli"], "expect": { "status": "succeeded" } },
+    { "say": "Regenerated firmware/betaflight/cli.txt from the model (run betaflight-cli): the GPS serial line moved from `serial UART1 2 …` to `serial UART3 2 115200 115200 0 115200`; UART1 is now unused. The receiver (UART2) and DJI MSP (UART5) lines are unchanged." }
+  ]
+}

package/lib/betaflight.ts

@@ -0,0 +1,244 @@
+/**
+ * Betaflight configuration for the 5-inch quadcopter, derived from its UHD
+ * links and part facts (PB-792). CLI syntax and values follow
+ * ../skills/firmware-config/references/betaflight-reference.md (verified
+ * against Betaflight 4.5.5, 2025.12.5
+ * and 2026.6.2 sources). Output targets Betaflight >= 2025.12.1, which the
+ * M9N-5883's QMC5883P compass requires.
+ *
+ * Every line is emitted with a comment naming the link or part fact it
+ * comes from. Nothing here is flight-tested: verify on hardware.
+ */
+import type { InterfaceDef, ModuleDef, TraitDef } from "@deltarobotics/uhd";
+import { systemLinks, type LinkResult, type ModuleLookup, type ResolvedEndpoint } from "@deltarobotics/uhd";
+import { resolveSpins } from "@deltarobotics/uhd";
+import type { SpinDirection } from "@deltarobotics/uhd";
+
+/** serialPortFunction_e values (betaflight-reference.md §1). */
+const FUNCTION = { MSP: 1, GPS: 2, RX_SERIAL: 64, VTX_MSP: 131072 } as const;
+
+interface Line {
+  text: string;
+  why: string;
+}
+
+const traitsOf = (x: { traits?: TraitDef[] }) => x.traits ?? [];
+
+/** All trait params of a module and its interfaces, flattened. */
+function facts(def: ModuleDef): Record<string, unknown>[] {
+  return [def, ...def.interfaces].flatMap(traitsOf).map((t) => (t.params ?? {}) as Record<string, unknown>);
+}
+
+function textOf(def: ModuleDef): string {
+  return JSON.stringify(facts(def));
+}
+
+const hasProtocol = (iface: InterfaceDef, type: string) => iface.protocols.some((p) => p.type === type);
+
+function kindOf(end: ResolvedEndpoint): "receiver" | "gnss" | "dji" | "other" {
+  const words = `${end.owner.name} ${(end.owner.tags ?? []).join(" ")} ${(end.owner.categories ?? []).join(" ")}`.toLowerCase();
+  if (hasProtocol(end.iface, "crsf")) return "receiver";
+  if (/gnss|gps/.test(words)) return "gnss";
+  if (/dji|air unit/.test(words)) return "dji";
+  return "other";
+}
+
+/** "uart5" → 5, from the flight controller's interface id. */
+const uartNumber = (iface: InterfaceDef) => Number(/^uart(\d+)$/.exec(iface.id)?.[1]);
+
+function isFlightController(def: ModuleDef): boolean {
+  return /flight controller/i.test(def.name) || (def.categories ?? []).some((c) => /flight/i.test(c));
+}
+
+function param(iface: InterfaceDef, id: string) {
+  return iface.parameters?.find((p) => p.id === id);
+}
+
+export interface BetaflightConfig {
+  target?: string;
+  minFirmware: string;
+  buildOptions: string[];
+  lines: Line[];
+  warnings: string[];
+}
+
+export function betaflightConfig(system: ModuleDef, lookup: ModuleLookup): BetaflightConfig {
+  const links = systemLinks(system, lookup); // stored + derived through cables (PB-805)
+  const lines: Line[] = [];
+  const warnings: string[] = [];
+  const features = new Set<string>();
+  const buildOptions = new Set<string>(["DSHOT"]);
+  let minFirmware = "4.5.5";
+
+  const fcEnd = (r: LinkResult): [ResolvedEndpoint, ResolvedEndpoint] | undefined => {
+    if (r.protocol === "connector") return undefined; // positions, not functions: the derived links carry them
+    if (isFlightController(r.a.owner)) return [r.a, r.b];
+    if (isFlightController(r.b.owner)) return [r.b, r.a];
+    return undefined;
+  };
+
+  // --- target -------------------------------------------------------------
+  const fcDef = links.map(fcEnd).find(Boolean)?.[0].owner;
+  const target = fcDef ? /\b(MATEK[A-Z0-9]+|[A-Z0-9]{6,}(?=\b[^"]*target))/.exec(textOf(fcDef) + fcDef.description)?.[1] : undefined;
+
+  // --- serial ports ---------------------------------------------------------
+  for (const r of links) {
+    const ends = fcEnd(r);
+    if (!ends || r.protocol !== "uart") continue;
+    const [fc, other] = ends;
+    const n = uartNumber(fc.iface);
+    if (!Number.isFinite(n)) continue;
+    const kind = kindOf(other);
+    const why = `link ${r.link.id}: ${fc.path} ↔ ${other.path}`;
+    if (kind === "receiver") {
+      lines.push({ text: `serial UART${n} ${FUNCTION.RX_SERIAL} 115200 57600 0 115200`, why: `${why} (CRSF receiver → RX_SERIAL)` });
+      lines.push({ text: "set serialrx_provider = CRSF", why: `${other.path} speaks crsf` });
+      features.add("TELEMETRY");
+      buildOptions.add("SERIALRX_CRSF");
+    } else if (kind === "gnss") {
+      lines.push({ text: `serial UART${n} ${FUNCTION.GPS} 115200 115200 0 115200`, why: `${why} (GNSS → GPS)` });
+      lines.push({ text: "set gps_provider = UBLOX", why: `${other.owner.name}: u-blox receiver` });
+      lines.push({ text: "set gps_auto_config = ON", why: "auto-config sets the module's baud/protocol from its default" });
+      features.add("GPS");
+      buildOptions.add("GPS");
+    } else if (kind === "dji") {
+      lines.push({ text: `serial UART${n} ${FUNCTION.MSP + FUNCTION.VTX_MSP} 115200 57600 0 115200`, why: `${why} (DJI MSP DisplayPort → MSP + VTX_MSP)` });
+      lines.push({ text: "set osd_displayport_device = MSP", why: "DJI O4 OSD via MSP DisplayPort (onboard analog OSD chip must not win on AUTO)" });
+      lines.push({ text: "set vcd_video_system = HD", why: "HD digital video system" });
+      features.add("OSD");
+      buildOptions.add("OSD_HD");
+    } else {
+      warnings.push(`${why}: no Betaflight serial function derived for ${other.owner.name}`);
+    }
+  }
+
+  // Every other hardware UART the flight controller has is reset to no
+  // function, so a pasted configuration is complete: a port the model no
+  // longer uses (the GPS moved from UART1 to UART3) does not keep its old
+  // function from the board's saved settings. The baud fields are the
+  // per-port defaults (betaflight-reference.md §1).
+  const used = new Set(lines.map((l) => Number(/^serial UART(\d+) /.exec(l.text)?.[1])).filter(Number.isFinite));
+  for (const n of (fcDef?.interfaces ?? []).map(uartNumber).filter(Number.isFinite).sort((a, b) => a - b)) {
+    if (used.has(n)) continue;
+    lines.push({ text: `serial UART${n} 0 115200 57600 0 115200`, why: `${fcDef!.id}: UART${n} has no link in the model, reset to no function` });
+  }
+
+  // --- motors ---------------------------------------------------------------
+  const phaseLinks = links.filter((r) => r.protocol === "bldc_3phase");
+  const escDef = phaseLinks[0] && (param(phaseLinks[0].a.iface, "max_current") ? phaseLinks[0].a.owner : phaseLinks[0].b.owner);
+  const fcRates = fcDef?.interfaces.find((i) => i.capabilities?.includes("esc_signal"))?.parameters?.find((p) => p.id === "esc_signal_rate");
+  const escRates = escDef?.interfaces.find((i) => i.capabilities?.includes("esc_signal"))?.parameters?.find((p) => p.id === "esc_signal_rate");
+  const maxRate = (p?: { value?: number; range?: [number, number] }) => p?.range?.[1] ?? p?.value;
+  const rate = Math.min(maxRate(fcRates) ?? 0, maxRate(escRates) ?? 0);
+  if (rate >= 150) {
+    const protocol = rate >= 600 ? "DSHOT600" : rate >= 300 ? "DSHOT300" : "DSHOT150";
+    lines.push({ text: `set motor_pwm_protocol = ${protocol}`, why: `highest DShot rate both ${fcDef?.id} and ${escDef?.id} state (${rate} kbit/s)` });
+  } else {
+    warnings.push("no common DShot rate between the FC motor outputs and the ESC inputs");
+  }
+  const bidir = (def?: ModuleDef) => Boolean(def?.interfaces.some((i) => i.capabilities?.includes("dshot_bidirectional")));
+  if (bidir(fcDef) && bidir(escDef)) {
+    lines.push({ text: "set dshot_bidir = ON", why: `both ${fcDef?.id} and ${escDef?.id} state bidirectional DShot (source: DolphinRC review blog only — verify)` });
+  }
+  const motorEnd = phaseLinks[0] && (param(phaseLinks[0].a.iface, "max_current") ? phaseLinks[0].b : phaseLinks[0].a);
+  const config = motorEnd && /(\d+)N(\d+)P/.exec(textOf(motorEnd.owner));
+  if (config) {
+    lines.push({ text: `set motor_poles = ${config[2]}`, why: `${motorEnd.owner.id}: ${config[0]} stator (${config[2]} magnet poles)` });
+  }
+
+  // Quad-X motor order check (betaflight-reference.md §3)
+  const expected: Record<number, string> = { 1: "rr", 2: "fr", 3: "rl", 4: "fl" };
+  for (const r of phaseLinks) {
+    const escSide = param(r.a.iface, "max_current") ? r.a : r.b;
+    const armSide = escSide === r.a ? r.b : r.a;
+    const n = Number(/(\d+)$/.exec(escSide.iface.id)?.[1]);
+    const corner = /arm_(\w\w)/.exec(armSide.path)?.[1];
+    if (expected[n] && corner && expected[n] !== corner) {
+      warnings.push(`motor ${n} is wired to arm_${corner}; Betaflight Quad-X expects arm_${expected[n]} (remap with the resource command or rewire)`);
+    }
+  }
+
+  // Motor direction (betaflight-reference.md §3a): Quad-X "props in" is
+  // M1 CW, M2 CCW, M3 CCW, M4 CW from above with yaw_motors_reversed OFF
+  // (the default); "props out" is every motor reversed with it ON.
+  const propsIn: Record<number, SpinDirection> = { 1: "cw", 2: "ccw", 3: "ccw", 4: "cw" };
+  const spins = resolveSpins(system, lookup);
+  const motorSpin = new Map<number, SpinDirection | undefined>();
+  for (const r of phaseLinks) {
+    const escSide = param(r.a.iface, "max_current") ? r.a : r.b;
+    const armSide = escSide === r.a ? r.b : r.a;
+    const n = Number(/(\d+)$/.exec(escSide.iface.id)?.[1]);
+    const armPath = armSide.path.split(":")[0];
+    const motor = [...spins.values()].find((x) => x.path.startsWith(`${armPath}/`) && x.def.id === armSide.owner.id) ?? spins.get(armPath);
+    motorSpin.set(n, motor?.spin);
+  }
+  const known = [...motorSpin.entries()].filter(([n, sp]) => propsIn[n] && sp);
+  if (known.length && known.length === motorSpin.size) {
+    const inward = known.every(([n, sp]) => propsIn[n] === sp);
+    const outward = known.every(([n, sp]) => propsIn[n] !== sp);
+    const list = known.sort(([a], [b]) => a - b).map(([n, sp]) => `M${n} ${sp!.toUpperCase()}`).join(", ");
+    if (inward) lines.push({ text: "set yaw_motors_reversed = OFF", why: `motor spins in the model (${list}) are Quad-X "props in", the default` });
+    else if (outward) lines.push({ text: "set yaw_motors_reversed = ON", why: `motor spins in the model (${list}) are Quad-X "props out"` });
+    else warnings.push(`motor spins (${list}) are neither Quad-X props-in nor props-out: diagonal motors must turn the same way`);
+  } else if (phaseLinks.length) {
+    warnings.push("no spin direction on some motors: set ChildModuleRef.spin so the prop direction can be derived");
+  }
+
+  // --- current meter ----------------------------------------------------------
+  const scale = escDef && /scale[^0-9]{0,12}(\d{2,4})/i.exec(textOf(escDef));
+  if (scale) {
+    lines.push({ text: "set current_meter = ADC", why: `${escDef?.id}: analog current sensor on the FC connector` });
+    lines.push({ text: `set ibata_scale = ${scale[1]}`, why: `${escDef?.id}: manufacturer current scale` });
+    lines.push({ text: "set ibata_offset = 0", why: `${escDef?.id}: manufacturer current offset` });
+  }
+
+  // --- compass -----------------------------------------------------------------
+  const compass = links.find((r) => r.protocol === "i2c" && fcEnd(r));
+  if (compass) {
+    const [, other] = fcEnd(compass)!;
+    const address = param(other.iface, "i2c_address")?.value;
+    lines.push({ text: "set mag_hardware = AUTO", why: `link ${compass.link.id}: compass at 0x${address?.toString(16).toUpperCase()} on ${compass.a.path}` });
+    buildOptions.add("MAG");
+    if (address === 0x2c) {
+      minFirmware = "2025.12.1";
+      warnings.push(`${other.owner.id}: QMC5883P compass (0x2C) is detected only by Betaflight >= 2025.12.1`);
+    }
+    const align = /CW\s?(\d+)°?\s*Flip/i.exec(textOf(other.owner));
+    if (align) {
+      lines.push({ text: `set align_mag = CW${align[1]}FLIP`, why: `${other.owner.id}: manufacturer alignment for arrow-forward mounting — confirm in the Sensors tab` });
+    }
+  }
+
+  // --- features ------------------------------------------------------------------
+  const featureLines = [...features].map((f) => ({ text: `feature ${f}`, why: "required by the serial functions above" }));
+  return {
+    target,
+    minFirmware,
+    buildOptions: [...buildOptions].sort(),
+    lines: [
+      ...lines
+        .filter((l) => l.text.startsWith("serial"))
+        .sort((a, b) => Number(/UART(\d+)/.exec(a.text)?.[1]) - Number(/UART(\d+)/.exec(b.text)?.[1])),
+      ...featureLines,
+      ...lines.filter((l) => !l.text.startsWith("serial")),
+    ],
+    warnings,
+  };
+}
+
+export function betaflightCli(system: ModuleDef, cfg: BetaflightConfig): string {
+  const width = Math.max(...cfg.lines.map((l) => l.text.length)) + 2;
+  return [
+    `# Betaflight configuration — ${system.name}`,
+    `# Generated from the UHD model by @protoboardai/ext-drone (protoboard run betaflight-cli). Do not edit by hand.`,
+    `# Target: ${cfg.target ?? "unknown"} · firmware >= ${cfg.minFirmware} · cloud build options: ${cfg.buildOptions.join(", ")}`,
+    `# Syntax and values verified against @protoboardai/ext-drone skills/firmware-config/references/betaflight-reference.md.`,
+    `# NOT FLIGHT-TESTED. Verify motor order, directions and compass alignment on the bench before flight.`,
+    `# Every hardware UART is set below (unused ports reset to function 0), so pasting this file needs no prior reset.`,
+    ...cfg.warnings.map((w) => `# WARNING: ${w}`),
+    "",
+    ...cfg.lines.map((l) => `${l.text.padEnd(width)}# ${l.why}`),
+    "save",
+    "",
+  ].join("\n");
+}

package/ops/betaflight.ts

@@ -0,0 +1,16 @@
+import type { OperationFn } from "@protoboardai/core";
+import { betaflightCli, betaflightConfig } from "../lib/betaflight.ts";
+
+/** Betaflight CLI from the resolved system; warnings are returned as data for the agent to act on. */
+export const betaflightCliOp: OperationFn = (ctx) => {
+  const { rootDef, lookup } = ctx.project;
+  if (!rootDef) return { status: "failed", summary: "project has no root system" };
+  const cfg = betaflightConfig(rootDef, lookup);
+  const out = ctx.inputs.out ?? "firmware/betaflight/cli.txt";
+  ctx.writeOutput(out, betaflightCli(rootDef, cfg), `Betaflight CLI (min firmware ${cfg.minFirmware})`);
+  return {
+    status: "succeeded",
+    summary: `${cfg.lines.length} CLI lines for ${cfg.target ?? "unknown target"}, firmware ≥ ${cfg.minFirmware}${cfg.warnings.length ? `, ${cfg.warnings.length} warning(s)` : ""}`,
+    data: { target: cfg.target, minFirmware: cfg.minFirmware, buildOptions: cfg.buildOptions, warnings: cfg.warnings },
+  };
+};

package/ops/package.ts

@@ -0,0 +1,92 @@
+/**
+ * Contributions to the Manufacturing Package (@protoboardai/ext-release section
+ * contract): the flight-controller configuration, in the root unit's work
+ * order (it depends on the whole system's wiring, so it is loaded at final
+ * assembly, once everything is connected) and its bench check in the root
+ * unit's test plan. Flashing and loading are contributed as "configure"
+ * operations: the release numbers them after the assembly steps, inside the
+ * bench test and before the propellers go on.
+ *
+ * The configuration file is the one `protoboard run betaflight-cli` wrote.
+ * It is regenerated here in memory and compared: a file that no longer
+ * matches the model stops the release.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { listOperationRecords, type Project } from "@protoboardai/core";
+import type { SectionContribution, SectionFn } from "@protoboardai/ext-release";
+import { betaflightCli, betaflightConfig } from "../lib/betaflight.ts";
+
+const DEFAULT_OUT = "firmware/betaflight/cli.txt";
+
+/** The configuration file: where the last betaflight-cli run wrote it. */
+function cliFile(p: Project): string {
+  const rec = listOperationRecords(p).filter((r) => r.record.operation === "betaflight-cli" && r.record.status === "succeeded").pop();
+  return rec?.record.outputs[0]?.path ?? DEFAULT_OUT;
+}
+
+function configuration(p: Project) {
+  if (!p.rootDef) return undefined;
+  const cfg = betaflightConfig(p.rootDef, p.lookup);
+  if (!cfg.target && !cfg.lines.length) return undefined; // no flight controller in this system
+  return { cfg, text: betaflightCli(p.rootDef, cfg), file: cliFile(p) };
+}
+
+export const workOrder: SectionFn = ({ project: p, unit }) => {
+  if (unit?.kind !== "root") return undefined;
+  const c = configuration(p);
+  if (!c) return undefined;
+  const abs = join(p.root, c.file);
+  const rerun = "run `protoboard run betaflight-cli` and commit the result";
+  if (!existsSync(abs)) return { title: "Flight controller configuration", blocks: [], diagnostics: [{ code: "DRONE_CLI_MISSING", severity: "error", message: `${c.file} does not exist; ${rerun}` }] };
+  if (readFileSync(abs, "utf8") !== c.text) return { title: "Flight controller configuration", blocks: [], diagnostics: [{ code: "DRONE_CLI_STALE", severity: "error", message: `${c.file} no longer matches the model; ${rerun}` }] };
+  const out: SectionContribution = {
+    title: "Flight controller configuration",
+    order: 60,
+    blocks: [
+      { kind: "paragraph", text: "Load the configuration once the receiver, video transmitter and GNSS are connected, before the propellers go on: the operations above flash the firmware and load this file after the power-up checks and before the rest of the bench test. Every line of the file cites the link or part fact it comes from." },
+      {
+        kind: "keyvalues",
+        rows: [
+          { label: "Firmware", value: `Betaflight ${c.cfg.minFirmware} or later` },
+          { label: "Target", value: c.cfg.target ?? "unknown" },
+          { label: "Build options", value: c.cfg.buildOptions.join(", ") },
+          { label: "File", value: "files/firmware/betaflight-cli.txt", note: `${c.cfg.lines.length} settings, from ${c.file}` },
+        ],
+      },
+      ...c.cfg.warnings.map((w) => ({ kind: "note" as const, level: "caution" as const, text: w })),
+    ],
+    operations: [
+      { stage: "configure", title: "Flash the flight controller", actions: [`Propellers off. Flash Betaflight ${c.cfg.minFirmware} or later for ${c.cfg.target ?? "the flight controller's target"} with the cloud build options ${c.cfg.buildOptions.join(", ")}.`], tools: ["Betaflight Configurator", "USB-C cable"], inspect: "the configurator connects and shows the target", test: "the configurator connects and shows the target" },
+      { stage: "configure", title: "Load the flight controller configuration", actions: ["Open the CLI tab, paste files/firmware/betaflight-cli.txt and press Enter; the board saves and reboots."], tools: ["Betaflight Configurator", "USB-C cable"], inspect: "the CLI echoes no error lines", test: "the flight controller bench check (test plan)" },
+    ],
+    files: [{ path: "files/firmware/betaflight-cli.txt", from: c.file, role: "firmware-config", description: "Betaflight CLI configuration" }],
+  };
+  return out;
+};
+
+export const testPlan: SectionFn = ({ project: p, unit }) => {
+  if (unit?.kind !== "root" || !configuration(p)) return undefined;
+  return {
+    title: "Flight controller bench check",
+    order: 60,
+    blocks: [
+      { kind: "paragraph", text: "After bring-up and the configuration, before the propellers go on: props off, powered through a current-limited supply or a smoke stopper. The configuration is generated from the model and has not been flight-tested." },
+      {
+        kind: "table",
+        columns: [
+          { key: "check", label: "Check" },
+          { key: "how", label: "How" },
+          { key: "pass", label: "Pass" },
+        ],
+        rows: [
+          { check: "Motor order and direction", how: "Motors tab, spin each motor at low throttle", pass: "M1–M4 at the positions and directions of the model's Quad-X layout" },
+          { check: "Receiver", how: "Receiver tab with the transmitter bound", pass: "all channels follow the sticks" },
+          { check: "Video and OSD", how: "goggles on, power cycle", pass: "image and OSD elements shown" },
+          { check: "GNSS and compass", how: "outdoors, Sensors and GPS tabs", pass: "satellite fix; heading follows the frame's nose" },
+          { check: "Current sensor", how: "compare the OSD current with the supply's", pass: "within the supply's resolution at idle" },
+        ],
+      },
+    ],
+  };
+};