@protoboardai/ext-zephyr 0.0.0-stage → 0.2.0

package/lib/dts.ts

@@ -0,0 +1,166 @@
+/**
+ * A structural devicetree check for the generated files, used when `dtc` is
+ * not available (and by `check` always): after the C preprocessor would have
+ * run, a devicetree source is nodes and properties. This checks what a
+ * generator can get wrong: balanced nodes, every property and node closed
+ * with `;`, values that are cells, strings, byte strings or references,
+ * labels defined once, and every `&label` defined in the files or by the SoC.
+ * Macros inside cells (`NRF_PSEL(…)`, `GPIO_ACTIVE_LOW`) are not expanded.
+ */
+export interface DtsProblem {
+  file: string;
+  line: number;
+  message: string;
+}
+
+interface Token {
+  t: string;
+  line: number;
+}
+
+function tokenize(text: string, file: string, problems: DtsProblem[]): Token[] {
+  const tokens: Token[] = [];
+  let line = 1;
+  let i = 0;
+  const s = text;
+  while (i < s.length) {
+    const ch = s[i];
+    if (ch === "\n") {
+      line++;
+      i++;
+    } else if (/\s/.test(ch)) i++;
+    else if (s.startsWith("/*", i)) {
+      const end = s.indexOf("*/", i + 2);
+      if (end < 0) {
+        problems.push({ file, line, message: "unterminated /* comment" });
+        break;
+      }
+      line += s.slice(i, end).split("\n").length - 1;
+      i = end + 2;
+    } else if (s.startsWith("//", i) || (ch === "#" && /^#(include|define|undef|if|ifdef|ifndef|endif|else)\b/.test(s.slice(i)))) {
+      while (i < s.length && s[i] !== "\n") i++;
+    } else if (ch === '"') {
+      let j = i + 1;
+      while (j < s.length && s[j] !== '"' && s[j] !== "\n") j += s[j] === "\\" ? 2 : 1;
+      if (s[j] !== '"') problems.push({ file, line, message: "unterminated string" });
+      tokens.push({ t: s.slice(i, j + 1), line });
+      i = j + 1;
+    } else if (ch === "<" || ch === "[") {
+      const close = ch === "<" ? ">" : "]";
+      let depth = 0;
+      let j = i;
+      for (; j < s.length; j++) {
+        if (s[j] === "(") depth++;
+        else if (s[j] === ")") depth--;
+        else if (s[j] === close && depth === 0) break;
+        else if (s[j] === "\n") line++;
+      }
+      if (j >= s.length) problems.push({ file, line, message: `unterminated ${ch}…${close}` });
+      tokens.push({ t: s.slice(i, j + 1), line });
+      i = j + 1;
+    } else if ("{};=,".includes(ch)) {
+      tokens.push({ t: ch, line });
+      i++;
+    } else {
+      // a comma between word characters belongs to the name (zephyr,code; nordic,nrf-twim)
+      let j = i;
+      while (j < s.length && (!/[\s{};=,"<[]/.test(s[j]) || (s[j] === "," && j > i && /[\w#-]/.test(s[j + 1] ?? "")))) j++;
+      if (j === i) j++;
+      tokens.push({ t: s.slice(i, j), line });
+      i = j;
+    }
+  }
+  return tokens;
+}
+
+const NAME = /^[A-Za-z0-9,._+#?@-]+$/;
+const LABEL = /^[A-Za-z_][A-Za-z0-9_]*:$/;
+const REF = /^&[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** Check devicetree sources (name → text). `known` are labels the included SoC devicetree defines. */
+export function checkDts(files: Record<string, string>, known: string[] = []): DtsProblem[] {
+  const problems: DtsProblem[] = [];
+  const labels = new Map<string, string>();
+  const refs: { label: string; file: string; line: number }[] = [];
+  for (const [file, text] of Object.entries(files)) {
+    const tokens = tokenize(text, file, problems);
+    let depth = 0;
+    let i = 0;
+    const at = (k: number) => tokens[k]?.t;
+    const err = (k: number, message: string) => problems.push({ file, line: tokens[Math.min(k, tokens.length - 1)]?.line ?? 1, message });
+    while (i < tokens.length) {
+      // "/dts-v1/;"
+      if (at(i) === "/dts-v1/" && at(i + 1) === ";") {
+        i += 2;
+        continue;
+      }
+      if (at(i) === "}") {
+        if (at(i + 1) !== ";") err(i, "node not closed with };");
+        depth--;
+        if (depth < 0) {
+          err(i, "} without an open node");
+          depth = 0;
+        }
+        i += 2;
+        continue;
+      }
+      // labels before a node
+      while (LABEL.test(at(i) ?? "")) {
+        const l = at(i)!.slice(0, -1);
+        if (labels.has(l)) err(i, `label ${l} is defined twice (first in ${labels.get(l)})`);
+        labels.set(l, file);
+        i++;
+      }
+      const name = at(i);
+      if (name === undefined) break;
+      if (at(i + 1) === "{") {
+        if (REF.test(name)) {
+          if (depth !== 0) err(i, `${name} { … } is only allowed at the top level`);
+          refs.push({ label: name.slice(1), file, line: tokens[i].line });
+        } else if (name !== "/" && !NAME.test(name)) err(i, `bad node name ${name}`);
+        depth++;
+        i += 2;
+        continue;
+      }
+      if (depth === 0) {
+        err(i, `unexpected ${name} outside a node`);
+        i++;
+        continue;
+      }
+      if (!NAME.test(name)) err(i, `bad property name ${name}`);
+      if (at(i + 1) === ";") {
+        i += 2;
+        continue;
+      }
+      if (at(i + 1) !== "=") {
+        err(i, `property ${name} needs = or ;`);
+        i++;
+        continue;
+      }
+      // value list: cells, strings, byte strings, references, separated by commas
+      let j = i + 2;
+      for (;;) {
+        const v = at(j);
+        if (v === undefined) {
+          err(j, `property ${name} is not closed with ;`);
+          break;
+        }
+        if (/^<.*>$/s.test(v)) for (const m of v.matchAll(/&([A-Za-z_][A-Za-z0-9_]*)/g)) refs.push({ label: m[1], file, line: tokens[j].line });
+        else if (REF.test(v)) refs.push({ label: v.slice(1), file, line: tokens[j].line });
+        else if (!/^".*"$/s.test(v) && !/^\[.*\]$/s.test(v)) err(j, `property ${name}: ${v} is not a cell list, string, byte string or reference`);
+        j++;
+        if (at(j) === ",") {
+          j++;
+          continue;
+        }
+        if (at(j) !== ";") err(j, `property ${name} is not closed with ;`);
+        break;
+      }
+      i = j + 1;
+    }
+    if (depth !== 0) problems.push({ file, line: tokens[tokens.length - 1]?.line ?? 1, message: `${depth} node(s) not closed` });
+  }
+  const knownSet = new Set([...known, ...labels.keys()]);
+  for (const r of refs) if (!knownSet.has(r.label)) problems.push({ file: r.file, line: r.line, message: `&${r.label} is not defined by these files or the SoC devicetree` });
+  return problems;
+}

package/lib/pins.ts

@@ -0,0 +1,20 @@
+/** Pins named in generated Zephyr files: `NRF_PSEL(<fn>, <port>, <pin>)` and `<&gpio<port> <pin> …>`. */
+import type { ModuleDef } from "@deltarobotics/uhd";
+import type { PinRef } from "@protoboardai/core";
+import { leafAt } from "./soc.ts";
+
+export function readZephyrPins(files: Record<string, string>, controller: ModuleDef): PinRef[] {
+  const refs: PinRef[] = [];
+  for (const [file, text] of Object.entries(files)) {
+    if (!/\.(dts|dtsi|overlay)$/.test(file)) continue;
+    text.split("\n").forEach((line, i) => {
+      const code = line.replace(/\/\*.*?\*\//g, "");
+      for (const m of code.matchAll(/NRF_PSEL\(\s*\w+\s*,\s*(\d+)\s*,\s*(\d+)\s*\)|&gpio(\d+)\s+(\d+)\b/g)) {
+        const port = Number(m[1] ?? m[3]);
+        const pin = Number(m[2] ?? m[4]);
+        refs.push({ file, line: i + 1, ref: `P${port}.${String(pin).padStart(2, "0")}`, pin: leafAt(controller, port, pin)?.id });
+      }
+    });
+  }
+  return refs;
+}

package/lib/soc.ts

@@ -0,0 +1,89 @@
+/**
+ * nRF52840 facts the Zephyr provider needs, checked against Zephyr v4.2.0
+ * (dts/arm/nordic/nrf52840.dtsi, boards/nordic/nrf52840dongle,
+ * drivers/clock_control/Kconfig.nrf). This is the provider's own table,
+ * like a PCB tool's land patterns: it is never written into a part.
+ *
+ * A part is matched to an SoC entry by its stated SoC fact
+ * (`domains[electrical].metadata.soc`), which is a UHD fact about the part.
+ */
+import type { InterfaceDef, ModuleDef } from "@deltarobotics/uhd";
+
+export const ZEPHYR_VERSION = "4.2.0";
+
+export interface ZephyrSoc {
+  /** board.yml `socs[].name`. */
+  name: string;
+  /** Kconfig symbol the board selects (the package variant). */
+  kconfig: string;
+  /** SoC devicetree include. */
+  dtsi: string;
+  /** How the part states it: matched against its SoC fact. */
+  match: RegExp;
+  /** Package the Kconfig symbol stands for, matched against the same fact. */
+  packageMatch: RegExp;
+  /** Bus instances in the order the provider uses them. */
+  i2c: string[];
+  spi: string[];
+  uart: string[];
+  /** Instances that share one peripheral id and cannot both be enabled. */
+  sharesId: Record<string, string>;
+  /** Highest SPI clock per instance (Hz). */
+  spiMaxHz: Record<string, number>;
+  /** Labels the SoC devicetree defines (for the structural check of the generated files). */
+  labels: string[];
+}
+
+export const NRF52840: ZephyrSoc = {
+  name: "nrf52840",
+  kconfig: "SOC_NRF52840_QIAA",
+  dtsi: "nordic/nrf52840_qiaa.dtsi",
+  match: /nRF52840/i,
+  packageMatch: /aQFN-?73/i,
+  // TWIM0/SPIM0 and TWIM1/SPIM1 share peripheral ids (nrf52840.dtsi: i2c0 and spi0 both at 0x40003000)
+  i2c: ["i2c0", "i2c1"],
+  spi: ["spi3", "spi2", "spi1", "spi0"],
+  uart: ["uart0", "uart1"],
+  sharesId: { i2c0: "spi0", spi0: "i2c0", i2c1: "spi1", spi1: "i2c1" },
+  // SPIM3 runs at 32 MHz, SPIM0-2 at 8 MHz (nRF52840 PS §6.25)
+  spiMaxHz: { spi3: 32_000_000, spi2: 8_000_000, spi1: 8_000_000, spi0: 8_000_000 },
+  labels: [
+    "acl", "adc", "bt_hci_controller", "ccm", "clock", "comp", "cpu0", "cryptocell", "ecb", "egu0", "egu1", "egu2", "egu3", "egu4", "egu5",
+    "ficr", "flash0", "flash_controller", "gpio0", "gpio1", "gpiote", "gpiote0", "gpregret1", "gpregret2", "hfxo", "i2c0", "i2c1", "i2s0",
+    "ieee802154", "itm", "mwu", "nfct", "nvic", "pdm0", "pinctrl", "power", "ppi", "pwm0", "pwm1", "pwm2", "pwm3", "qdec", "qspi", "radio",
+    "reg0", "reg1", "rng", "rtc0", "rtc1", "rtc2", "spi0", "spi1", "spi2", "spi3", "sram0", "systick", "temp", "timer0", "timer1", "timer2",
+    "timer3", "timer4", "uart0", "uart1", "uicr", "usbd", "wdt", "wdt0",
+  ],
+};
+
+const SOCS = [NRF52840];
+
+/** The part's stated SoC fact, if it has one. */
+export function socFact(def: ModuleDef): string | undefined {
+  for (const d of def.domains ?? []) {
+    const soc = (d as { metadata?: Record<string, unknown> }).metadata?.soc;
+    if (typeof soc === "string") return soc;
+  }
+  return undefined;
+}
+
+export function socOf(def: ModuleDef): ZephyrSoc | undefined {
+  const fact = socFact(def);
+  return fact ? SOCS.find((s) => s.match.test(fact)) : undefined;
+}
+
+/** "P0.13" or "P0.00/XL1" → port 0, pin 13. */
+export function portPin(leaf: InterfaceDef | undefined): { port: number; pin: number } | undefined {
+  const m = /^P(\d)\.(\d{1,2})\b/.exec(leaf?.name ?? "");
+  return m ? { port: Number(m[1]), pin: Number(m[2]) } : undefined;
+}
+
+export const pinLabel = (pp: { port: number; pin: number }) => `P${pp.port}.${String(pp.pin).padStart(2, "0")}`;
+
+/** The controller leaf named P<port>.<pin>, if the module has it. */
+export function leafAt(def: ModuleDef, port: number, pin: number): InterfaceDef | undefined {
+  return def.interfaces.find((i) => {
+    const pp = portPin(i);
+    return pp?.port === port && pp.pin === pin;
+  });
+}

package/ops/firmware.ts

@@ -0,0 +1,36 @@
+/**
+ * The firmware capability for Zephyr on nRF52840 modules: the shared
+ * operations from @protoboardai/core with this provider's design, pin reader
+ * and rules (a devicetree structural check of what it generates).
+ */
+import type { CapabilityOperationFn } from "@protoboardai/core";
+import { firmwareOperations, previewFirmware, type FirmwareProviderSpec } from "@protoboardai/core";
+import { designZephyr } from "../lib/design.ts";
+import { checkDts } from "../lib/dts.ts";
+import { readZephyrPins } from "../lib/pins.ts";
+import { NRF52840, ZEPHYR_VERSION, socOf } from "../lib/soc.ts";
+
+export const SPEC: FirmwareProviderSpec = {
+  provider: "@protoboardai/ext-zephyr",
+  framework: "zephyr",
+  frameworkVersion: ZEPHYR_VERSION,
+  design: (fw, board, controller, ctx) => {
+    const d = designZephyr(fw, board, controller, ctx);
+    // the generated devicetree must be well formed, whatever the board
+    const dts = Object.fromEntries(d.files.filter((f) => /\.dtsi?$/.test(f.path)).map((f) => [f.path, f.lines.map((l) => l.text).join("\n")]));
+    for (const p of checkDts(dts, (socOf(controller) ?? NRF52840).labels)) {
+      d.findings.push({ code: "FW_DTS_SYNTAX", severity: "error", message: `${p.file}:${p.line}: ${p.message} (provider defect)` });
+    }
+    return d;
+  },
+  readPins: readZephyrPins,
+  // any nRF52840 GPIO wakes the chip from System OFF through its SENSE level (PS §6.9)
+  rules: () => ({ sleepName: "System OFF", i2cAddressRequired: true }),
+};
+
+const ops = firmwareOperations(SPEC);
+export const generate: CapabilityOperationFn = ops.generate;
+export const exportOutputs: CapabilityOperationFn = ops.exportOutputs;
+export const extract: CapabilityOperationFn = ops.extract;
+export const check: CapabilityOperationFn = ops.check;
+export { previewFirmware };

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@protoboardai/ext-zephyr",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Protoboard firmware provider: Zephyr board definitions (devicetree, pinctrl, Kconfig) for nRF52840 modules, from UHD boards",
+  "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-zephyr"
+  },
+  "type": "module",
+  "files": [
+    "protoboard-extension.json",
+    "ops",
+    "lib",
+    "skills",
+    "evals",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@protoboardai/core": "^0.2.0",
+    "@deltarobotics/uhd": ">=0.3.0"
+  }
+}

package/protoboard-extension.json

@@ -0,0 +1,40 @@
+{
+  "schema": "protoboard.extension/v0",
+  "id": "@protoboardai/ext-zephyr",
+  "version": "0.2.0",
+  "description": "firmware provider: Zephyr board definitions for nRF52840 modules (devicetree with pinctrl, buses, devices, buttons, display; Kconfig), every setting citing the UHD facts it comes from.",
+  "compatibility": {
+    "protoboard": "^0.2.0",
+    "uhd": ">=0.3.0"
+  },
+  "skills": [
+    {
+      "id": "firmware-config-zephyr",
+      "summary": "SOP: configure Zephyr for a UHD board with an nRF52840 module (firmware capability): config, generate, check, export, build hand-off; every setting cited",
+      "path": "skills/firmware-config-zephyr/SKILL.md"
+    }
+  ],
+  "capabilities": [
+    {
+      "id": "firmware",
+      "summary": "Zephyr 4.2 board definition (board.yml, Kconfig, defconfig, devicetree, pinctrl) and a Kconfig fragment for an nRF52840 board",
+      "native": "zephyr",
+      "operations": {
+        "generate": { "entry": "./ops/firmware.ts#generate", "summary": "Read the board into a firmware map, apply the rules, write the board definition and firmware.conf under zephyr/ with the line index" },
+        "export": { "entry": "./ops/firmware.ts#exportOutputs", "summary": "Copy the generated files to out/config/ and write out/firmware.manifest.json (refuses files edited since generate)" },
+        "extract": { "entry": "./ops/firmware.ts#extract", "summary": "Artifact references and the pins the devicetree names" },
+        "check": { "entry": "./ops/firmware.ts#check", "summary": "Pin table, single use, bus functions, I2C addresses, strapping, wake sources, devicetree structure, and drift between the files and the board" }
+      },
+      "constraints": {
+        "controller": { "description": "instance path of the controller, when the board has more than one microcontroller" },
+        "board_name": { "description": "Zephyr board name (default: the module id with _ for -)" },
+        "vendor": { "description": "board vendor folder and compatible prefix (default protoboard)" },
+        "console": { "description": "UART bus id or UART device instance for zephyr,console" },
+        "i2c_frequency_hz": { "description": "I2C bus clock: 100000 or 400000 (default: the fastest every device allows)" },
+        "uart_baud": { "description": "{ <instance>: baud } for UART devices that state no baud_rate" },
+        "wake": { "description": "[<button or device instance | net>] inputs that wake the chip from System OFF (written as zephyr,user wakeup-gpios)" },
+        "properties": { "description": "{ <instance>: { <devicetree property>: value } } for what a driver binding requires and the model does not state" }
+      }
+    }
+  ]
+}

package/skills/firmware-config-zephyr/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: firmware-config-zephyr
+description: Configure Zephyr for a UHD board whose controller is an nRF52840 module, with the @protoboardai/ext-zephyr firmware provider. Writes a board definition (devicetree, pinctrl, Kconfig) and a Kconfig fragment from the board's nets and part facts, every setting citing its facts, and fixes what firmware:check finds (pins, buses, addresses, wake sources, drift). Use after the board's circuit is modelled, whenever its nets change, and before the release's firmware configuration is frozen.
+---
+
+# Firmware configuration: Zephyr (nRF52840)
+
+Standard operating procedure (release-package-and-evals.md §4). The
+configuration is a view of the model: which pin is SDA is a net, a sensor's
+address is a part fact. Nothing is typed from memory or edited by hand.
+Reference: the package README.
+
+## Purpose
+
+Produce a Zephyr 4.2 board definition for one custom board and the standard
+firmware outputs (`out/config/`, `out/firmware.manifest.json`) that the
+release packages. Use it when a board module's controller is an nRF52840
+module (the part's SoC fact says nRF52840), after its nets are modelled, and
+again whenever they change.
+
+## Inputs
+
+- The board module: `src/boards/<module>/<module>.uhd.ts`, with every
+  peripheral pin the firmware drives or reads on a net that reaches a
+  controller pin (`netLinks`). Peripherals with a bus state it as a composite
+  (`i2c`, `spi`, `uart`) with `i2c_address` and `clock_freq`.
+- The parts: the controller module and each peripheral, from
+  `parts/catalog` or `parts/local`, with pin tables and facts.
+- What the model cannot state, decided with the person who owns the
+  firmware: which inputs wake the device, and any property a driver binding
+  requires (the DRV2605's `actuator-mode`, from the actuator chosen).
+
+## Steps
+
+### 1. Write the config
+
+Next to the board:
+
+```ts
+// src/boards/<module>/firmware.config.ts
+import { defineCapabilityConfig } from "@protoboardai/core";
+export default defineCapabilityConfig({
+  provider: "@protoboardai/ext-zephyr",
+  constraints: { board_name: "<board>", wake: ["sw1"], properties: { u5: { "actuator-mode": "LRA" } } },
+});
+```
+
+Then `npx protoboard capabilities`: the board is listed under `firmware`
+with `✓` and the provider.
+
+### 2. Check before generating
+
+`npx protoboard check`. Read every
+`ext:@protoboardai/ext-zephyr/firmware:check` finding; errors stop
+generate. `FW_NOT_GENERATED` (info) is expected now.
+
+### 3. Generate
+
+`npx protoboard run firmware:generate --module <module>`.
+The summary names the files, the number of cited settings, buses and
+GPIOs, and the warnings. Read the warnings (`--format json | jq .data`):
+each names a device without a Zephyr driver or a gap to close.
+
+### 4. Read the board devicetree
+
+In
+`src/boards/<module>/zephyr/boards/<vendor>/<board>/<board>.dts` and the
+pinctrl file. Compare each comment with the schematic intent: the pin,
+the net, the address, the polarity.
+
+### 5. Export
+
+`npx protoboard run firmware:export --module <module>`, then
+`npx protoboard check` again: `protoboard/standard-outputs` and the
+provider's check both clean.
+
+### 6. Hand off
+
+The build command in the README (`BOARD_ROOT`,
+`EXTRA_CONF_FILE`), the warnings, and the bench items in "Verification".
+
+## Decision points
+
+| Question | Rule |
+| --- | --- |
+| A part has no Zephyr driver (warning) | Leave the generated node (address, label); the application drives it. Do not invent a compatible, and do not edit the installed provider package. If Zephyr has a driver for it, report the missing mapping (part id, compatible, binding file at the pinned release) to the provider's maintainers; meanwhile bind the driver in the application's own overlay (`app.overlay`: `&<label> { compatible = "..."; };`), which the generated files do not touch. |
+| A binding needs a property the model lacks (`FW_PROPERTY_MISSING`) | If it is a fact of the part, add it to the part with its source (part authoring, repair mode). If it is a design choice, put it in `constraints.properties` with a comment saying why. |
+| Which pins should a new bus use | Full-drive pads for I2C, SPI, UART (the module's usage note lists them); low-frequency pads only for buttons and status lines. Change the board's nets, never the generated file. |
+| No crystal on XL1/XL2 (warning) | Acceptable for a prototype (RC oscillator); add the crystal to the board if timing accuracy or sleep current matters. |
+| Two devices share an address | Move one to a second bus (a second set of nets) or choose a part variant with another address. |
+| Something must differ from the generated files | Put it in the application's `prj.conf` or overlay. Never edit `zephyr/`. |
+
+## Outputs
+
+- `src/boards/<module>/zephyr/`: the board definition, `firmware.conf`,
+  `protoboard.lines.json` (native, provider-owned).
+- `src/boards/<module>/out/config/` and `out/firmware.manifest.json`:
+  standard outputs, the only files the release and other tools read.
+- The operation records in `operations/` (commit them with the outputs).
+
+## Verification
+
+- `npx protoboard check`: no error from `protoboard/standard-outputs` or the
+  firmware check; `FW_NATIVE_STALE` absent (the files match the model).
+- `out/firmware.manifest.json`: every file listed, each setting line with at
+  least one cite (`net:`, `pin:`, `part:`, `constraint:`).
+- First build: `west build -b <board> <app> -- -DBOARD_ROOT=… -DEXTRA_CONF_FILE=…`
+  compiles. A devicetree or Kconfig error there is a provider defect: record
+  it with the Zephyr version.
+- On the bench (the release's test plan): an I2C scan finds the addresses in
+  the devicetree; each button, interrupt and display line works; the device
+  wakes from System OFF on each wake source. Record results with
+  **test-and-measure**.
+
+## Failure handling
+
+| Diagnostic | Meaning | Action |
+| --- | --- | --- |
+| `FW_NO_CONTROLLER`, `FW_CONTROLLER_AMBIGUOUS` | No microcontroller, or several | Fix the controller part's category, or set `constraints.controller`. |
+| `FW_SOC_UNSUPPORTED` | The controller's SoC fact is not an nRF52840 | Use the provider for that SoC (ESP32-C3: `@protoboardai/ext-esp-idf`), or fix the part's SoC fact. |
+| `FW_BUS_PROTOCOL` | A bus signal on a pad without that function (a low-frequency pad) | Move the net to a full-drive pad. |
+| `FW_PIN_REUSED`, `FW_BUS_CROSSED` | One pin with two jobs; a peripheral's SDA/SCL swapped, or two SPI devices sharing SCK but not MOSI | Fix the nets. (Devices that agree on the lines they share are one bus.) |
+| `FW_SPI_CS_MISSING` | A device on a shared SPI bus with no chip select | Wire its CS to a controller GPIO. |
+| `FW_I2C_ADDRESS_UNKNOWN` | An I2C part states no address; a devicetree node needs `reg` | Fix the part (`i2c_address` on its I2C interface) through the parts library. |
+| `FW_BUTTON_CODES` (warning) | More than 36 buttons: the extra ones get no `zephyr,code` | Set their key codes in the application overlay. |
+| `FW_BUS_INCOMPLETE` | A peripheral's bus line reaches no controller pin | Add the missing pin to its net. |
+| `FW_I2C_ADDRESS_CONFLICT` | Two devices at one address on one bus | Second bus or another part variant. |
+| `FW_BUS_INSTANCES` | More buses than the nRF52840 has (i2c0/spi0 and i2c1/spi1 share hardware) | Share a bus. |
+| `FW_BUS_SPEED` | A clock the TWIM or a device cannot run | Use 100 or 400 kHz, at most the slowest device's limit. |
+| `FW_WAKE_UNKNOWN` | A wake source that is no input of the board | Name a button, or a device whose interrupt reaches the controller. |
+| `FW_NATIVE_EDITED` | Someone edited `zephyr/` | Regenerate; move the change to the application's files. |
+| `FW_NATIVE_STALE`, `FW_PIN_DRIFT` | The board changed since generate | Regenerate and export. |
+| `FW_PIN_UNKNOWN` | A file names a pin the module does not have | Regenerate; if it persists, it is a provider defect. |
+| `FW_DTS_SYNTAX`, `FW_LINE_UNCITED` | Provider defect | Report it with the board; do not work around it in the output. |