@protoboardai/ext-drone 0.0.0-stage → 0.2.0

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/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" },
+        ],
+      },
+    ],
+  };
+};

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@protoboardai/ext-drone",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Protoboard extension: multirotor flight-controller configuration from UHD",
+  "license": "Apache-2.0",
+  "author": "Delta Robotics, Inc.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Delta-Robotics-Inc/protoboard-stack.git",
+    "directory": "packages/ext-drone"
+  },
+  "type": "module",
+  "files": [
+    "protoboard-extension.json",
+    "ops",
+    "lib",
+    "skills",
+    "evals",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@protoboardai/core": "^0.2.0",
+    "@deltarobotics/uhd": ">=0.3.0",
+    "@protoboardai/ext-release": "^0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@protoboardai/ext-release": {
+      "optional": true
+    }
+  }
+}

package/protoboard-extension.json

@@ -0,0 +1,49 @@
+{
+  "schema": "protoboard.extension/v0",
+  "id": "@protoboardai/ext-drone",
+  "version": "0.2.0",
+  "description": "Multirotor domain pack: flight-controller configuration (Betaflight) generated from the UHD model.",
+  "compatibility": {
+    "protoboard": "^0.2.0",
+    "uhd": ">=0.3.0"
+  },
+  "skills": [
+    {
+      "id": "firmware-config",
+      "summary": "Derive a flight-controller configuration from UHD links and part facts, every line cited, every setting checked against pinned firmware sources",
+      "path": "skills/firmware-config/SKILL.md",
+      "verifiedBy": "firmware-verify"
+    },
+    {
+      "id": "firmware-verify",
+      "summary": "Bench-verify a generated FC configuration on hardware (props off) and record the result as measured test data",
+      "path": "skills/firmware-verify/SKILL.md"
+    }
+  ],
+  "operations": [
+    {
+      "id": "betaflight-cli",
+      "summary": "Generate a Betaflight CLI dump (serial ports, receiver, OSD/VTX, GPS, compass) from the model's links; every line cites its link or part fact",
+      "entry": "./ops/betaflight.ts#betaflightCliOp",
+      "effect": "export",
+      "inputs": {
+        "out": {
+          "description": "output file, project-relative",
+          "default": "firmware/betaflight/cli.txt"
+        }
+      }
+    },
+    {
+      "id": "package:work-order",
+      "summary": "Manufacturing Package: the flight-controller configuration (file and loading steps) in the root unit's work order; refuses a configuration that no longer matches the model",
+      "entry": "./ops/package.ts#workOrder",
+      "effect": "pure"
+    },
+    {
+      "id": "package:test-plan",
+      "summary": "Manufacturing Package: the props-off bench check of the flight controller in the root unit's test plan",
+      "entry": "./ops/package.ts#testPlan",
+      "effect": "pure"
+    }
+  ]
+}

package/skills/firmware-config/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: firmware-config
+description: Derive a controller's firmware configuration from a UHD system's links and part facts — Betaflight CLI for flight controllers today (protoboard run betaflight-cli; the same method for INAV, ArduPilot or PX4), and the firmware capability's pin and peripheral configuration for microcontroller boards as it lands — with every line citing the link or fact it comes from and every setting checked against the firmware's own source at a pinned version. Use when a system has a controller and its wiring is modelled, when wiring changes, or when moving firmware versions; follow with firmware-verify on the bench.
+---
+
+# Firmware configuration from the model
+
+```
+UHD links + part facts ──► reference doc (settings verified in firmware source, pinned) ──► generator
+                                                                                              │
+          firmware/<fw>/cli.txt  (every line: "# link <id>: …" or "# <part>: <fact>")  ◄──────┘
+                                                                                              │
+                                                              firmware-verify (bench) ◄────────┘
+```
+
+The configuration is a *view* of the model: which UART the receiver is wired
+to is a link, the current-sensor scale is an ESC fact, the compass address is
+a GNSS fact. Nothing is typed from memory, and nothing is claimed flight-ready.
+
+## Purpose
+
+Produce the controller configuration a unit is flashed with, derived from the
+model so it cannot disagree with the wiring silently. Use it when a system
+has a flight controller or a microcontroller board and its wiring is
+modelled, whenever wiring changes, and when moving firmware versions. In
+**build-a-project** it is stage 9, after the checks are clean; the
+configuration goes into the Manufacturing Package's `files/` and its
+UNVERIFIED items into the test plan. **firmware-verify** follows on the
+bench, performed by a person.
+
+## Inputs
+
+| Input | Where | From |
+| --- | --- | --- |
+| The links to the controller (UARTs, I2C, motor outputs) | the root system and sub-assemblies, `npx protoboard inspect <fc instance>` | **system-compose**, **harness-author** |
+| Part facts (firmware target, sensor scale, I2C address, motor poles, DShot rates) | the parts' definitions and evidence | **uhd-part-author**, the catalog |
+| The firmware reference, source-pinned | `references/betaflight-reference.md` (this skill) | step 2 |
+| A board's nets and pin assignment (microcontroller boards) | `src/boards/<module>/<module>.uhd.ts` | **circuit-board** |
+
+## Steps
+
+### 1. Generate (Betaflight)
+
+```bash
+npx protoboard run betaflight-cli                              # → firmware/betaflight/cli.txt + operation record
+npx protoboard run betaflight-cli --format json                # data: target, minFirmware, buildOptions, warnings
+```
+
+Look at `data.warnings`: each is something the model could not decide (an
+unknown peer on a UART, a motor-order mismatch, a target claimed only by
+compatibility) and goes on the **firmware-verify** list.
+
+Implementation: `@protoboardai/ext-drone` `lib/betaflight.ts`; reference:
+[betaflight-reference.md](references/betaflight-reference.md) (every setting
+checked against Betaflight 4.5.5, 2025.12.5 and 2026.6.2 sources, commits
+pinned, UNVERIFIED items marked). Read the reference's gotchas before trusting
+any output.
+
+What the configuration is derived from:
+
+| Setting family | Model input | Rule |
+| --- | --- | --- |
+| Target | FC part facts (target name in traits/description, e.g. `MATEKF405TE`) | The FC must state its firmware target with a source; if it only claims compatibility (DolphinRC → MATEKF405TE), that is UNVERIFIED and goes to the bench list. |
+| Serial ports | every `uart` link with the FC on one end: FC interface id `uartN` → port N; the other end's protocol/kind → function | CRSF receiver → `RX_SERIAL` (64) + `feature TELEMETRY`; u-blox GNSS → `GPS` (2) + provider; DJI air unit → `MSP + VTX_MSP` (131073) + HD OSD settings. An unknown peer is a warning, never a guess. |
+| Motor protocol | FC motor outputs' and ESC inputs' `esc_signal_rate` | highest DShot rate both state; bidirectional only if both state the capability (cite it). |
+| Unused UARTs | every `uartN` interface of the FC with no link | `serial UARTn 0 115200 57600 0 115200` (function 0, per-port default bauds), so a pasted file is complete: a port the model stopped using (the GPS moved from UART1 to UART3) is cleared, not left with its old function. |
+| Motor poles | motor stator/magnet config fact (`12N14P`) | magnet poles. |
+| Motor order | `bldc_3phase` links: ESC channel n → arm | compare with the firmware's mixer order (Quad-X: M1 rear-right, M2 front-right, M3 rear-left, M4 front-left); mismatch → warning (remap or rewire). |
+| Current meter | ESC current-sensor fact (scale, offset) | `current_meter = ADC`, `ibata_scale`, `ibata_offset` from the ESC's manufacturer values. |
+| Compass | `i2c` link to the FC; the peer's `i2c_address` and alignment fact | driver per address (0x2C QMC5883P needs ≥ 2025.12.1 → `minFirmware`), `align_mag` from the maker's mounting statement. |
+| Build options | whatever the lines above need | e.g. `GPS`, `MAG`, `OSD_HD`, `SERIALRX_CRSF`, `DSHOT` for a cloud build. |
+
+Each emitted line carries its reason: `serial UART2 64 … # link rx_crsf: stack:uart2 ↔ receiver:crsf (CRSF receiver → RX_SERIAL)`.
+
+### 2. Add or change a rule
+
+1. **Verify the setting first** in the firmware source at a pinned tag: the
+   CLI parser, the setting's table, value ranges, defaults, the target's
+   `config.h`. Add a section to the reference with `file#Lx-Ly` links, the
+   commit, and a **Δ** note for version differences. What cannot be checked in
+   source is marked **UNVERIFIED** and becomes a firmware-verify item.
+2. **Find the model input.** If the fact is not in the model (a pad label, a
+   scale factor), add it to the part with its source (**uhd-part-author**,
+   repair mode) instead of hard-coding it in the generator.
+3. **Emit with a reason** naming the link id or `<part id>: <fact>`, and a
+   warning when the model cannot decide.
+4. Regenerate, diff `firmware/<fw>/cli.txt`, commit output and operation
+   record together.
+
+### 3. Another firmware
+
+Same pattern, new files in `@protoboardai/ext-drone`: `lib/<fw>.ts` (pure:
+model → lines with reasons + warnings), `ops/<fw>.ts` (writes
+`firmware/<fw>/…`), an operation in the manifest, and
+`skills/firmware-config/references/<fw>-reference.md` written *before* the
+generator, with the same verification standard (source-pinned, UNVERIFIED
+marked, version deltas). Parameter names and serial-function values differ per
+firmware; the link → function mapping in step 1 does not.
+
+### 4. Microcontroller boards (the firmware capability, planned)
+
+Custom boards with a microcontroller (Zephyr devicetree overlays and Kconfig
+for nRF52840, ESP-IDF pin headers and sdkconfig for ESP32-C3) get their
+starting configuration from a `firmware` capability provider, being built
+now. It follows the capability pattern, so expect:
+
+```bash
+npx protoboard run firmware:generate --module <board>    # planned
+npx protoboard run firmware:check --module <board>       # planned: pins exist and are assigned once, peripherals match buses, strapping pins respected, I2C addresses match parts
+```
+
+Until it is in your CLI (`npx protoboard capabilities` lists `firmware`),
+write the board's pin and peripheral assignment as a table from the board
+module's nets (each row citing its net and part fact) in the board's notes,
+and list the configuration as an open item for the release.
+
+### 5. What the output does not establish
+
+A generated configuration is consistent with the model and the checked
+firmware sources. It does not prove the pads are labelled as the target
+expects, that motor directions are right, that the compass alignment matches
+the physical mounting, or that bidirectional DShot works on this ESC. Those
+are bench checks: **firmware-verify**. The CLI header says NOT FLIGHT-TESTED
+until they pass and are recorded.
+
+## Decision points
+
+| Decision | Rule |
+| --- | --- |
+| The model cannot decide a setting | Emit a warning, never a guess; it goes on the bench list. |
+| A fact is missing from the model | Add it to the part with its source (**uhd-part-author**), not to the generator. |
+| A setting not checkable in source | Mark it **UNVERIFIED** in the reference; it becomes a **firmware-verify** item. |
+| Firmware version | The lowest version every emitted line needs (`minFirmware`), recorded in the header and the release manifest. |
+| Motor order mismatch | Remap in firmware or rewire; decide and record it in `docs/decisions.md`. |
+
+## Outputs
+
+| Output | Where |
+| --- | --- |
+| Betaflight configuration (generated; never edit) | `firmware/betaflight/cli.txt` |
+| Operation record | `operations/` |
+| Reference, source-pinned | `references/<fw>-reference.md` in this skill |
+| Board pin and peripheral configuration | `firmware/<fw>/` from the firmware capability (planned) |
+
+## Verification
+
+```bash
+npx protoboard run betaflight-cli --format json      # succeeded; data.warnings reviewed, each on the bench list
+git diff --stat firmware/                            # only the changes the model change explains
+```
+
+Every line of `cli.txt` carries a `# link …` or `# <part>: …` reason. Then
+**firmware-verify** on the bench.
+
+## Failure handling
+
+| Code or symptom | Means | Do |
+| --- | --- | --- |
+| `run betaflight-cli` fails: "project has no root system" | `protoboard.config.ts` names no loadable root | Fix `root` (`PB_ROOT_NOT_FOUND`) |
+| Summary says "unknown target" | The FC part states no firmware target | Add the target to the FC part with its source; until then a bench item |
+| Warning: "no Betaflight serial function derived" | A UART link to something the generator has no rule for | Add the rule (step 2) or set it on the bench and record it |
+| Warning: "no common DShot rate" | FC outputs and ESC inputs state no shared rate | Add the rates from the datasheets, or choose compatible parts |
+| Warning: no spin, or spins not Quad-X | `spin` missing on the arms, or diagonal motors disagree | Set `ChildModuleRef.spin` once per arm (**system-compose**) |
+| Warning: motor order differs from the mixer | ESC channels and arms disagree | Remap or rewire; record the decision |
+| `UHD_LINK_STATE` on a link to the FC | The wiring the configuration would encode is wrong | Fix the system first (**system-compose**) |
+| `UHD_INTERFACE_REUSE` on an FC UART | Two devices on one UART | Fix the wiring; the generator cannot assign one port twice |
+| `UHD_BUS_ADDRESS` on the FC's I2C | Two devices share an address | Fix the system |
+| `run firmware:generate` not available | The firmware capability has not landed | Step 4's interim table and an open item |
+
+Every other code: **system-compose** [diagnostic codes](../system-compose/references/diagnostic-codes.md).
+
+## Hard rules
+
+1. Every emitted line cites the link or part fact it comes from.
+2. Never hand-edit a generated configuration; change the model or the
+   generator and regenerate.
+3. Nothing generated is flight-ready until **firmware-verify** passes on the
+   recorded firmware version and unit.

package/skills/firmware-config/references/betaflight-reference.md

@@ -0,0 +1,258 @@
+# Betaflight CLI reference: 5" quad (DolphinRC F405 V3 / MATEKF405TE)
+
+Every item below was checked against the Betaflight source or the official docs. Nothing here comes from memory. Anything that could not be checked is marked **UNVERIFIED**.
+
+## 0. Versions checked
+
+| Source | Ref | Commit |
+|---|---|---|
+| Firmware (primary) | `betaflight/betaflight` tag **4.5.5**, the newest 4.5.x tag | `4adbd3ef7cb546947600e5f747bd5453c9573063` |
+| Firmware (delta check) | tag **2025.12.5** | `7348054f268f0058574719c134e9f149565bb8ea` |
+| Firmware (delta check) | tag **2026.6.2**, the newest stable release on 2026-09-26 | `e0b7bb01b17b21351057e9ead2d1ab39dd44fa16` |
+| Target config (4.5) | `betaflight/config` branch `4.5-config`, `configs/MATEKF405TE/config.h` | `7b1f01a25d8cb6379ebeeeca9f0e91c24925e907` |
+| Target config (master) | `betaflight/config` branch `master`, `configs/MTKS/MATEKF405TE/config.h` (the file has moved into a manufacturer folder) | `96910e90881573589b2a6c41f7392b7afad63973` |
+| Docs | `betaflight/betaflight.com` master | `0589eb3b938ca3b9782aae6eb91f323604b9a39c` |
+
+The `config.h` for MATEKF405TE is **byte-identical** on `4.5-config` and `master`. The `2025.12-config` branch points at the same commit as `4.5-config`.
+
+Note: 4.5.x is **no longer the current stable line**. 2025.12.x and 2026.6.x have both shipped since. Where they differ from 4.5.5, the difference is flagged with a **Δ** marker.
+
+Short link prefixes used below:
+- `BF` = `https://github.com/betaflight/betaflight/blob/4.5.5/`
+- `BF25` = `https://github.com/betaflight/betaflight/blob/2025.12.5/`
+- `BF26` = `https://github.com/betaflight/betaflight/blob/2026.6.2/`
+- `CFG` = `https://github.com/betaflight/config/blob/4.5-config/configs/MATEKF405TE/config.h`
+
+---
+
+## Final CLI block (4.5.5)
+
+```
+# ports: serial <identifier> <functionMask> <msp_baud> <gps_baud> <telem_baud> <blackbox_baud>
+serial 0 2 115200 115200 0 115200        # UART1 -> GPS (FUNCTION_GPS=2), GPS baud 115200
+serial 1 64 115200 57600 0 115200        # UART2 -> Serial RX (FUNCTION_RX_SERIAL=64) (already the target default)
+serial 4 131073 115200 57600 0 115200    # UART5 -> MSP(1) + VTX_MSP(131072) = MSP DisplayPort for DJI O4
+
+feature GPS
+feature TELEMETRY          # needed for CRSF/ELRS telemetry back to the TX
+feature OSD
+
+set serialrx_provider = CRSF
+set gps_provider = UBLOX
+set gps_auto_config = ON
+set osd_displayport_device = MSP
+set vcd_video_system = HD
+set motor_pwm_protocol = DSHOT600      # or DSHOT300
+set dshot_bidir = ON
+set motor_poles = 14
+set current_meter = ADC
+set ibata_scale = 150
+set ibata_offset = 0
+set mag_hardware = QMC5883             # AUTO also works; needs a MAG-enabled build (see section 4)
+set align_mag = CW270FLIP
+save
+```
+
+**Δ 2025.12.x / 2026.6.x:** the `serial` command takes a port *name* instead: `serial UART1 2 115200 115200 0 115200`, `serial UART2 64 ...`, `serial UART5 131073 ...`. The old numeric identifiers 0-19 are still accepted and are remapped as legacy values (see section 1). All the `set` lines are unchanged.
+
+---
+
+## 1. `serial` command, function bitmask, UART mapping
+
+### Syntax (4.5.5)
+
+`serial <identifier> <functionMask> <msp_baud> <gps_baud> <telemetry_baud> <blackbox_baud>`. All **6 arguments** are required.
+
+- Parser: `BF src/main/cli/cli.c#L1288-L1375`. Output format `"serial %d %d %ld %ld %ld %ld"` is at L1290. The command fails with an invalid-argument error when `validArgumentCount < 6` (L1361-L1364).
+- Baud limits the parser enforces (`cli.c#L1320-L1359`):
+  - MSP: 9600 to 1000000
+  - GPS: 9600 to **115200**
+  - Telemetry: `0` (= AUTO) or up to 115200
+  - Blackbox: 19200 to 2470000
+- Baud table: `baudRates[] = {0, 9600, 19200, 38400, 57600, 115200, 230400, 250000, 400000, 460800, 500000, 921600, 1000000, 1500000, 2000000, 2470000}` at `BF src/main/io/serial.c#L114-L115`. `0` is `BAUD_AUTO` (`src/main/io/serial.h#L60`).
+- Per-port defaults: MSP 115200, GPS 57600, telemetry AUTO, blackbox 115200 (`BF src/main/io/serial.c#L136-L142`).
+- Docs: https://betaflight.com/docs/wiki/guides/current/Serial ("The `serial` CLI command takes 6 arguments").
+
+### Unused ports
+
+`serial` changes only the port it names, and every other port keeps its saved
+function. A generated block is complete only when it also writes the ports it
+does not use: `serial UARTn 0 115200 57600 0 115200` (function 0 with the
+per-port default bauds above). ext-drone writes such a line for every hardware
+UART of the flight controller that the model does not link. This is safer than
+a `defaults nosave` preamble, which would also reset modes, rates and PIDs.
+
+### Function bitmask (`serialPortFunction_e`, `BF src/main/io/serial.h#L35-L54`)
+
+| Function | Value |
+|---|---|
+| FUNCTION_MSP | 1 (L37) |
+| FUNCTION_GPS | 2 (L38) |
+| FUNCTION_TELEMETRY_SMARTPORT | 32 (L42) |
+| FUNCTION_RX_SERIAL | 64 (L43) |
+| FUNCTION_BLACKBOX | 128 (L44) |
+| FUNCTION_VTX_MSP | 131072 (L53) |
+
+The values are identical in 2025.12.5 and 2026.6.2 (`serial.h` L37, L38, L43, L53).
+
+**TELEMETRY for ELRS:** there is **no CRSF telemetry function bit**. CRSF telemetry runs on the RX_SERIAL port itself:
+- `initCrsfTelemetry()` enables only if `crsfRxIsActive()` (`BF src/main/telemetry/crsf.c#L731-L739`).
+- It only runs when `FEATURE_TELEMETRY` is on (`BF src/main/fc/init.c#L976-L980`).
+
+So ELRS needs `64` on the RX port plus `feature TELEMETRY`, and no extra bit. The docs confirm: "CRSF, GHST and F.Port receivers cannot share their port with a telemetry slot — they carry telemetry over the receiver protocol itself" (Serial guide, "Validation and Recovery").
+
+### UART to identifier mapping (4.5.5)
+
+`serialPortIdentifier_e` (`BF src/main/io/serial.h#L81-L101`):
+- `SERIAL_PORT_USART1 = 0`, USART2 = 1, USART3 = 2, UART4 = 3, **UART5 = 4**, USART6 = 5
+- `SERIAL_PORT_USB_VCP = 20`, SOFTSERIAL1 = 30
+
+So in 4.5.5 **UART1 = 0, UART2 = 1, UART5 = 4**. These are fixed identifiers, not array positions. The `portConfigs[]` array puts VCP first (`serial.c#L69-L90`), but the CLI takes the identifier.
+
+**Δ 2025.12+:**
+- UART identifiers moved to 51+ (`SERIAL_PORT_USART1 = SERIAL_PORT_UART_FIRST = 51`, `BF25 src/main/io/serial.h#L97-L105`).
+- The CLI prints and accepts names (`"serial %s %d ..."`, `BF25 src/main/cli/cli.c#L1292`). Names come from `serialPortNames[]` (`"UART1"`, `"UART5"`, ..., `BF25 src/main/io/serial.c#L147-L170`).
+- Numeric 0-19 is still accepted: `identifier += SERIAL_PORT_UART1` for the legacy range 0..19 (`BF25 src/main/cli/cli.c#L1306-L1316`, `serial.h#L86-L87`). 2026.6.2 behaves the same (`BF26 src/main/cli/cli.c#L1414-L1509`).
+
+**Δ future 2026.12 (unreleased):** the docs say `serial` becomes read-only and ports are assigned with `rx_uart`, `gps_uart`, `msp_uart_N`, `vtx_uart` and similar settings (Serial guide, "Per-Feature Port Assignment"). This does not apply to 4.5.5, 2025.12 or 2026.6.
+
+### MATEKF405TE hardware UARTs
+
+- The MCU target enables `USE_UART1` through `USE_UART6` plus VCP and softserial (`BF src/main/target/STM32F405/target.h#L35-L50`).
+- The config defines pins for UART1 to UART6 (`CFG#L52-L63`):
+
+| UART | TX | RX |
+|---|---|---|
+| UART1 | PA9 | PA10 |
+| UART2 | PA2 | PA3 |
+| UART3 | PC10 | PC11 |
+| UART4 | PA0 | PA1 |
+| UART5 | PC12 | PD2 |
+| UART6 | PC6 | PC7 |
+
+- No special or remapped UART numbering. The only target serial default is `SERIALRX_UART SERIAL_PORT_USART2` (`CFG#L123`). That makes UART2 = RX_SERIAL by default through `pgResetFn_serialConfig` (`BF src/main/io/serial.c#L160-L165`).
+- **UNVERIFIED:** that the DolphinRC F405 V3 pads are labelled to match MATEK's UART numbering. Check the DolphinRC wiring diagram.
+
+---
+
+## 2. Settings
+
+### Serial RX (ELRS)
+- `set serialrx_provider = CRSF`. The setting is at `BF src/main/cli/settings.c#L769`, and the name comes from `src/main/fc/parameter_names.h#L45`.
+- Allowed values (`lookupTableSerialRX`, `settings.c#L239-L256`): `NONE, SPEK2048, SBUS, SUMD, SUMH, XB-B, XB-B-RJ01, IBUS, JETIEXBUS, CRSF, SRXL, CUSTOM, FPORT, SRXL2, GHST, SPEK1024`.
+- The default is already CRSF when the build includes `USE_SERIALRX_CRSF` (`BF src/main/pg/rx.c#L37-L40`, `L84`). Setting it explicitly is harmless.
+- `feature RX_SERIAL` is already the target default (`DEFAULT_RX_FEATURE FEATURE_RX_SERIAL`, `CFG#L124`, applied at `BF src/main/config/feature.c#L35`).
+
+### GPS (u-blox M10)
+- `feature GPS` (feature name list `BF src/main/cli/cli.c#L234-L237`). GPS init is gated on `FEATURE_GPS` (`BF src/main/fc/init.c#L762-L763`).
+- `set gps_provider = UBLOX`. Values are `NMEA, UBLOX, MSP` (`settings.c#L201-L203`, setting at `L1020`). UBLOX is the default (`BF src/main/pg/gps.c#L35`). **Δ** 2025.12 adds `VIRTUAL` (`BF25 settings.c#L254-L256`).
+- `gps_auto_config` defaults to ON (`pg/gps.c#L37`). With UBLOX and auto-config on, the FC probes baud rates with MON-VER and then commands the module to the port's configured GPS baud (`BF src/main/io/gps.c#L425-L452`, `#L1044-L1052`). M10 is recognised (`gps.c#L479`, `UBX_VERSION_M10`).
+- `gps_auto_baud` defaults to OFF (`pg/gps.c#L38`). In 4.5.5 it is referenced only by CLI GPS passthrough (`cli.c#L4813`), so you do not need to set it.
+- Optional settings:
+  - `gps_ublox_use_galileo` (ON/OFF, default OFF, `settings.c#L1028`)
+  - `gps_ublox_flight_model` (default `AIRBORNE_4G`; values `PORTABLE, STATIONARY, PEDESTRIAN, AUTOMOTIVE, AT_SEA, AIRBORNE_1G, AIRBORNE_2G, AIRBORNE_4G`, `settings.c#L209-L211`)
+  - `gps_update_rate_hz` (default 10)
+- GPS baud goes in the `serial` line's 4th field. The CLI accepts at most 115200.
+- **UNVERIFIED:** the Matek M10Q-5883 factory baud rate. It does not matter much because UBLOX auto-config probes for it.
+
+### MSP DisplayPort OSD (DJI O4)
+- **`displayport_msp_serial` does not exist in 4.5.5.** A grep of `src/main` finds no hits. The DisplayPort UART is chosen as the **first non-VCP port whose mask includes both `FUNCTION_MSP` and `FUNCTION_VTX_MSP`** (`BF src/main/config/config.c#L616-L630`). So the port setting is the `serial ... 131073 ...` line. The same logic is in 2025.12.5 (`config.c#L537`) and 2026.6.2 (`config.c#L576`).
+- `set osd_displayport_device = MSP`. Values are `NONE, AUTO, MAX7456, MSP, FRSKYOSD` (`settings.c#L491-L493`, setting at `L1514`). **Δ** 2026.6 adds `FBOSD`.
+- `set vcd_video_system = HD`. Values are `AUTO, PAL, NTSC, HD` (`settings.c#L392-L394`, setting at `L1570`). When `vcd_video_system == HD`, init forces the MSP device (`BF src/main/fc/init.c#L896-L900`) and uses the canvas size (`src/main/io/displayport_msp.c#L215-L217`).
+- **Why both settings matter on this board:** MATEKF405TE has an onboard MAX7456 (`USE_MAX7456`, `CFG#L34`). With `AUTO`, init falls through to the MAX7456 case before MSP (`init.c#L920-L937`).
+- Firmware defaults are already MSP and HD when `USE_OSD_HD` is built (`BF src/main/osd/osd.c#L415-L419`, `src/main/pg/vcd.c#L33-L37`), but set them explicitly anyway.
+- The 4.4 release notes give exactly these two lines: https://betaflight.com/docs/wiki/release/Betaflight-4-4-Release-Notes (section "2. HD OSD").
+- `displayport_msp_fonts` (`settings.c#L1588`) is **not required**.
+- HD canvas defaults to 53x20 and is renegotiated by the VTX (`osd.h#L89-L90`; 4.4 notes).
+- **UNVERIFIED (not in Betaflight sources):** DJI "Canvas mode" is a goggle/O4 menu option on the DJI side and needs no extra Betaflight setting beyond the above.
+
+### Motor protocol, bidirectional DShot, poles
+- `set motor_pwm_protocol = DSHOT600` (or `DSHOT300`). Values are `PWM, ONESHOT125, ONESHOT42, MULTISHOT, BRUSHED, DSHOT150, DSHOT300, DSHOT600, PROSHOT1000, DISABLED` (`settings.c#L302-L306`, setting at `L865`). The default is DSHOT600 (`BF src/main/pg/motor.c#L71`). **Δ** 2026.6 appends `DRONECAN`.
+- `set dshot_bidir = ON`. Values are OFF/ON (`settings.c#L856`). The default is OFF (`pg/motor.c#L47-L48`, `L118`).
+- `USE_DSHOT_TELEMETRY` is defined whenever `USE_DSHOT` is (`BF src/main/target/common_pre.h#L56-L60`). That block is outside the `CLOUD_BUILD` guard, so selecting DSHOT in a cloud build includes bidir.
+- `set motor_poles = 14`. The range is 4 to 255 (`settings.c#L868`), and the default is already 14 (`pg/motor.c#L107`).
+- **UNVERIFIED:** AM32 bidirectional DShot support on this particular ESC. Confirm in the Motors tab (RPM readout / 0% error) after setup.
+
+### Current and voltage meter
+- `set current_meter = ADC`. Values are `NONE, ADC, VIRTUAL, ESC, MSP` (`BF src/main/sensors/current.c#L45-L47`, setting at `settings.c#L902`). The target default is already ADC (`CFG#L108`).
+- `battery_meter` values are `NONE, ADC, ESC` (`src/main/sensors/voltage.c#L51-L53`). The target default is ADC (`CFG#L109`). `vbat_scale` target default is 210 (`CFG#L110`).
+- `set ibata_scale = 150`. The range is -16000 to 16000 (`settings.c#L924`). The target default is already 150 (`CFG#L111`).
+- `set ibata_offset = 0`. The range is -32000 to 32000 (`settings.c#L925`). The default is 0 (`BF src/main/sensors/current.c#L97-L105`).
+
+### Compass (QMC5883L on I2C1, 0x0D)
+- `set mag_hardware = QMC5883` (or `AUTO`). Values are `AUTO, NONE, HMC5883, AK8975, AK8963, QMC5883, LIS2MDL, LIS3MDL, MPU925X_AK8963, IST8310` (`BF src/main/cli/settings.c#L159-L161`, setting at `L731`). The docs recommend `AUTO` (https://betaflight.com/docs/wiki/guides/current/Magnetometer, "set mag_hardware = AUTO").
+- `set align_mag = CW270FLIP`. Values are `DEFAULT, CW0, CW90, CW180, CW270, CW0FLIP, CW90FLIP, CW180FLIP, CW270FLIP, CUSTOM` (`settings.c#L181-L192`, setting at `L723`). Enum value 8 is `CW270_DEG_FLIP` (`src/main/common/sensor_alignment.h#L39`). "Flip" means a 180 degree rotation about Y (Magnetometer doc). **UNVERIFIED:** that CW270FLIP is right for this mounting. It comes from the module vendor, so verify it in the Sensors tab.
+- Bus settings need **no change**:
+  - The target sets `MAG_I2C_INSTANCE I2CDEV_1` (`CFG#L105`).
+  - `pgResetFn_compassConfig` sets `mag_bustype = I2C`, `mag_i2c_device = I2C_DEV_TO_CFG(I2CDEV_1) = 1`, `mag_i2c_address = 0` (`BF src/main/sensors/compass.c#L125-L130`; `I2C_DEV_TO_CFG(x) = x+1`, `src/main/drivers/bus_i2c.h#L50`).
+  - Address 0 makes the QMC driver use `0x0D` (`src/main/drivers/compass/compass_qmc5883l.c#L43`, `#L148-L149`).
+  - If you set them explicitly: `set mag_bustype = I2C`, `set mag_i2c_device = 1`, `set mag_i2c_address = 13` (`settings.c#L727-L729`).
+- `USE_MAG` is **not** defined by the target config. `CFG` defines only `MAG_I2C_INSTANCE`. I2C1 (PB8 SCL / PB7 SDA, `CFG#L64-L65`) is the only I2C bus defined, and it is **shared with the onboard DPS310 baro** (`BARO_I2C_INSTANCE I2CDEV_1`, `CFG#L106-L107`). **UNVERIFIED:** which physical pads on the DolphinRC board expose I2C1.
+
+---
+
+## 3. Motor order (Quad-X) and motor resources
+
+`mixerQuadX[]` (`BF src/main/flight/mixer_init.c#L72-L77`). The row comments give the positions:
+
+| Motor | Position |
+|---|---|
+| Motor 1 | REAR_R (rear-right) |
+| Motor 2 | FRONT_R (front-right) |
+| Motor 3 | REAR_L (rear-left) |
+| Motor 4 | FRONT_L (front-left) |
+
+The order is identical in 2025.12.5 and 2026.6.2 (`mixer_init.c#L85-L88`). QUADX is the default mixer (`DEFAULT_MIXER MIXER_QUADX`, `BF src/main/target/common_defaults_post.h#L108`), so no `mixer` line is needed. The docs point to the same expected mapping (https://betaflight.com/docs/wiki/getting-started/troubleshooting, motor order section).
+
+Motor pin defaults (`CFG#L39-L46`):
+
+| Motor | Pin | Timer map (`CFG#L86-L94`) |
+|---|---|---|
+| M1 | PC9 | timer index 2 |
+| M2 | PC8 | timer index 2 |
+| M3 | PB15 | timer index 1 |
+| M4 | PA8 | timer index 1 |
+
+M5 to M8 are PB11, PB10, PB3 and PA15. The pins are loaded into `motorConfig->dev.ioTags[]` (`BF src/main/pg/motor.c#L81-L104`). **No `resource` changes are needed** unless the ESC harness order differs. In that case remap with `resource MOTOR n <pin>`, or use the Motors tab reorder (`motorOutputReordering`, `pg/motor.c#L109-L110`).
+
+### 3a. Motor spin direction (fetched 2026-09-26 from `master`)
+
+Quad-X default, viewed from above: **M1 rear-right CW, M2 front-right CCW, M3 rear-left CCW, M4 front-left CW** ("props in"). `set yaw_motors_reversed = ON` reverses every motor ("props out").
+
+- `yaw_motors_reversed` is an OFF/ON setting on `mixerConfig_t` (`BF src/main/cli/settings.c`, `{ "yaw_motors_reversed", VAR_INT8 | MASTER_VALUE | MODE_LOOKUP, .config.lookup = { TABLE_OFF_ON }, PG_MIXER_CONFIG, ... }`). The default comes from `#define YAW_MOTORS_REVERSED 0` (`BF src/main/flight/mixer_init.c#L50-L51`), and `configs/MATEKF405TE/config.h` does not override it. So the default is OFF.
+- `mixerQuadX[]` yaw column (`mixer_init.c#L84-L89`): REAR_R −1, FRONT_R +1, REAR_L +1, FRONT_L −1. In the same file, `mixerY4[]` labels its rows `// REAR_TOP CW` (yaw −1) and `// REAR_BOTTOM CCW` (yaw +1). With that sign convention, M1 and M4 turn CW and M2 and M3 turn CCW. Source file sha256 `0b080d762403ca067fc4c5728d9dd5651a68311bcc1407f2ade9a6cf278d8418`.
+- Docs, motors tab (https://github.com/betaflight/betaflight.com, `docs/wiki/app/motors-tab.md`): "The normal setting assumes your props will spin in towards the camera at the front of your quad "props in"".
+- Docs, reversed motor direction (`docs/wiki/guides/current/Reversed-motor-direction.md`): "Reversed motors would be spinning outwards (contrary to the standard inwards), that is the front left spins counterclockwise, front right clockwise". The default is the opposite: front-left CW, front-right CCW. Diagonal motors share a direction.
+- The setup guide's props-in/props-out diagram is `static/img/betaflight_props_in_out.png` in the same repo.
+
+The UHD model records direction as `ChildModuleRef.spin` on each arm instance. `betaflight.ts` emits `yaw_motors_reversed` from it, and the `prop_handedness` check compares it with the prop variant on each motor.
+
+---
+
+## 4. Target defaults, compatibility, gotchas
+
+| Item | Target default | Source |
+|---|---|---|
+| Serial RX on UART2 | Yes (`SERIALRX_UART SERIAL_PORT_USART2`, mask 64) | `CFG#L123`, `BF serial.c#L160-L165` |
+| RX feature | `FEATURE_RX_SERIAL` | `CFG#L124` |
+| serialrx_provider | Not set by target. The firmware default is CRSF if built in. | `BF pg/rx.c#L37-L40` |
+| Blackbox | `BLACKBOX_DEVICE_FLASH` (M25P16 on SPI2) | `CFG#L116`, `#L35-L36`, `#L118` |
+| Current/voltage source | ADC / ADC, scale 150 / 210 | `CFG#L108-L111` |
+| Gyro | ICM42688P, SPI1, `GYRO_1_ALIGN CW270_DEG_FLIP` (the gyro, not the mag) | `CFG#L29-L32`, `#L120-L121` |
+| Baro | DPS310 on I2C1 | `CFG#L33`, `#L106-L107` |
+| OSD chip | MAX7456 on SPI1 | `CFG#L34`, `#L117` |
+| GPS / MSP UART | None defined (no `GPS_UART` / `MSP_UART`) | `CFG` |
+
+Gotchas:
+
+1. **The compass needs a custom build with `MAG`.**
+   - `USE_MAG` is only auto-defined for builds *without* a board config (`#if !defined(USE_CONFIG)` inside `#if !defined(CLOUD_BUILD)`, `BF src/main/target/common_pre.h#L72-L77`).
+   - MATEKF405TE does not define it, so `mag_hardware` and the QMC driver are compiled out unless you select **"MAG"** under "Other Options" in the cloud build (`https://betaflight.com/docs/development/API/Cloud-Build-API`, "Other Options" list). For local builds use `-DUSE_MAG` (Magnetometer doc: "Betaflight's build system must include `Magnetometers`... or `-DUSE_MAG`").
+   - With `USE_MAG`, the QMC5883 driver is pulled in automatically (`BF src/main/target/common_post.h#L88-L101`).
+   - Also select `GPS`, `OSD_HD` (or both SD and HD), `SERIALRX_CRSF` and `DSHOT`. CRSF telemetry is included automatically (Cloud-Build-API note).
+2. **Onboard MAX7456.** Because of it, `osd_displayport_device = MSP` and `vcd_video_system = HD` must be set explicitly (section 2).
+3. **UART5 mask must be 131073, not 131072.** A port with VTX_MSP alone is not picked for DisplayPort (`config.c#L625`), and the docs say "MSP VTX is alone on a port — it has to share with MSP" (Serial guide).
+4. **Features.** `feature TELEMETRY` is required for ELRS telemetry (`init.c#L978`). `feature GPS` is required for GPS init (`init.c#L762`). `DEFAULT_FEATURES` is 0 (`BF src/main/config/feature.h#L25-L26`). FEATURE_OSD is auto-enabled only on an unconfigured board (`BF src/main/config/config.c#L484-L494`), so add `feature OSD` to be safe.
+5. **QMC5883P variant.** 4.5.5 supports only the QMC5883**L** (`compass_qmc5883l.c`, address 0x0D). 2025.12+ adds a QMC5883**P** driver at address 0x2C (`BF25 src/main/drivers/compass/compass_qmc5883.c#L82-L83`). The Magnetometer doc notes the L was "Discontinued in 2025 and replaced by the QMC5883P". If a newer M10Q-5883 ships with the P variant, 4.5.5 will not detect it. **UNVERIFIED:** which chip this unit carries. The user states 0x0D, which is the L variant.
+6. **Target file path.** The user-supplied path `configs/MATEKF405TE/config.h` is correct only on the `4.5-config` / `2025.12-config` branches. On `master` the file is at `configs/MTKS/MATEKF405TE/config.h`. Contents are identical.
+7. **DolphinRC F405 V3 → MATEKF405TE.** **UNVERIFIED** from Betaflight sources. DolphinRC is a registered manufacturer (`DOLP`, `Manufacturers.md#L44`), but its only config is `configs/DOLP/DOLPHINRC_F722`. There is no DolphinRC F405 config, so the pin compatibility is taken from the vendor's claim.

package/skills/firmware-verify/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: firmware-verify
+description: Verify a generated flight-controller configuration on the real hardware, props off — apply the CLI, diff the result, then check ports, receiver and telemetry, OSD, GPS, compass alignment, motor order and direction, bidirectional DShot and the current sensor, resolving every UNVERIFIED item in the firmware reference — and record the result as measured test data. Use after firmware-config, before any flight, and after any firmware or wiring change. Physical effects: a person performs or authorises each step.
+---
+
+# Firmware verify (bench)
+
+Everything here happens on a physical unit. An agent can prepare the
+checklist, read dumps and logs, and record results; a person connects the
+battery and spins motors. **Props off for every step.** First power through a
+current limiter (smoke stopper or bench supply at ~1 A).
+
+## Purpose
+
+Close the gap between a configuration that agrees with the model and one
+that works on the unit: pads, directions, alignment and sensor scales can
+only be confirmed on hardware. Use it after **firmware-config**, before any
+flight, and after any firmware or wiring change. In **build-a-project** it
+comes after the release (stage 11): the unit under test is built from a
+release, and the result is recorded against it. An agent prepares and
+records; a person performs or authorises every physical step.
+
+## Inputs
+
+| Input | Where | From |
+| --- | --- | --- |
+| The release and unit under test | release name and unit serial | **release** |
+| The generated configuration and its record | `firmware/<fw>/cli.txt`, `operations/` | **firmware-config** |
+| Firmware version and build options it asks for | the CLI header (`# Target … firmware >= … cloud build options …`) | **firmware-config** |
+| The UNVERIFIED list | `firmware-config/references/betaflight-reference.md` | **firmware-config** |
+| The generator's warnings | `npx protoboard run betaflight-cli --format json` → `data.warnings` | **firmware-config** |
+| A person at the bench | with the unit, a current-limited supply, a clamp meter, a multimeter | the operator |
+
+## Steps
+
+### 1. Prepare
+
+- The release/revision and unit serial under test (**release**).
+- `firmware/<fw>/cli.txt` and its operation record; the firmware version and
+  build options it asks for.
+- The UNVERIFIED list from the reference
+  ([betaflight-reference.md](../firmware-config/references/betaflight-reference.md))
+  and the generator's warnings:
+
+```bash
+npx protoboard run betaflight-cli --format json      # data.warnings; the run must not change cli.txt (git diff firmware/)
+```
+
+### 2. Flash and apply (a person does this)
+
+1. Flash the stated firmware with the stated build options (a missing `MAG`
+   option silently compiles the compass driver out).
+2. CLI: `diff all` → save as `firmware/<fw>/bench/<date>-before.txt`.
+3. Paste `cli.txt`; the FC reboots on `save`.
+4. `diff all` again → `…-after.txt`. Every generated line must appear (or be
+   the firmware default, which `diff` omits); any rejected line is a finding
+   against the reference.
+
+### 3. Checks (each: expected from the model, observed, pass/fail)
+
+| Check | Expected (model) | How |
+| --- | --- | --- |
+| Pads = UARTs | the link's UART is the pad you soldered | Ports tab lists the functions on the right UARTs; each peripheral works (below). Resolves "pads labelled as the target expects". |
+| Receiver | CRSF on the receiver link's UART | Receiver tab: sticks move the right channels; telemetry (RSSI, battery) reaches the radio. |
+| OSD | MSP DisplayPort on the air-unit link's UART | OSD elements visible in the goggles, HD canvas. |
+| GPS | GNSS on its UART, auto-config | Sats and fix in the GPS tab (outdoors); the module's baud was negotiated. |
+| Compass | detected at the model's I2C address; `align_mag` per the maker | Sensors tab shows MAG; rotate the craft: heading follows (N-E-S-W), no mirror. Resolves the alignment item. |
+| Motor order | Quad-X order from the phase links | Motors tab, props off: M1 rear-right, M2 front-right, M3 rear-left, M4 front-left spin. |
+| Motor direction | the spin the model states for each arm | Each motor's direction matches its prop's handedness; fix with the ESC tool (AM32) or `motor_direction` per the firmware, then record. |
+| Bidirectional DShot | both parts state it (weak source: say which) | Motors tab shows RPM with ~0 % error. Otherwise turn it off and record the finding against the part. |
+| Current sensor | the ESC's `ibata_scale` | Compare the FC's current with a clamp meter at 2–3 loads; adjust scale only with a recorded measurement. |
+| Voltage | `vbat_scale` default | FC voltage vs multimeter within 0.05 V/cell. |
+
+### 4. Record
+
+Write `docs/test-data/firmware-bench.json` (status `measured`; **test-and-measure**):
+conditions (release, unit, firmware version, build options, cli.txt sha256),
+columns `check`, `expected`, `observed`, `pass`, one row per check, raw files
+(`before`/`after` dumps, screenshots, Blackbox logs). Validate it:
+
+```bash
+npx tsx node_modules/@protoboardai/ext-hardware/skills/test-and-measure/scripts/test-data.ts docs/test-data/firmware-bench.json
+```
+
+Feed every failure back: a wrong pad mapping or alignment becomes a model fix
+(part fact or link), then regenerate the CLI — never a hand edit of
+`cli.txt`.
+
+## Decision points
+
+| Decision | Rule |
+| --- | --- |
+| Continue after a failed check | Stop before anything that spins or powers more: fix the model, regenerate, re-apply, re-check. |
+| A rejected CLI line | A finding against the reference; correct the reference (source-pinned) and the generator, not the dump. |
+| Adjust a scale | Only with a recorded measurement at two or more loads. |
+| The NOT FLIGHT-TESTED header | May be reconsidered only when every check passes, and only for the recorded firmware version and unit. |
+| Who acts | A person performs every physical step; an agent prepares, reads and records. |
+
+## Outputs
+
+| Output | Where |
+| --- | --- |
+| Before/after dumps | `firmware/<fw>/bench/<date>-before.txt`, `<date>-after.txt` |
+| The measured result | `docs/test-data/firmware-bench.json` |
+| Model fixes | the parts and links (through **uhd-part-author**, **system-compose**), then a regenerated `cli.txt` |
+
+## Verification
+
+`test-data.ts` passes on `firmware-bench.json`; every row of the checks table
+has an observed value and pass/fail; every UNVERIFIED item in the reference
+is resolved or still listed with the reason; the release and unit are named
+in the file's conditions.
+
+## Failure handling
+
+| Code or symptom | Means | Do |
+| --- | --- | --- |
+| A generated line rejected by the CLI | The reference is wrong for this version | Fix the reference and generator (**firmware-config** step 2) |
+| A peripheral works on another UART than the link says | Pads not labelled as the target expects, or the link is wrong | Fix the link or the FC part's pad facts; regenerate |
+| Heading mirrored or rotated | `align_mag` is wrong for the mounting | Fix the GNSS part's alignment fact from the maker; regenerate |
+| A motor in the wrong position or direction | Phase links or spins disagree with the mixer | Remap or rewire, record the decision; fix the model to match |
+| RPM telemetry errors | Bidirectional DShot does not work with this ESC firmware | Turn it off; record the finding against the part |
+| `test-data.ts` fails | The record is incomplete or has placeholders | Complete it; never commit a placeholder as measured |
+| `UHD_PROP_HANDEDNESS` | Spins not set or mismatched in the model | **system-compose**: set `spin` per arm |
+
+Every other code: **system-compose** [diagnostic codes](../system-compose/references/diagnostic-codes.md).

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.