@typecad/framework-zephyr 1.0.0-alpha.10

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@typecad/framework-zephyr",
+  "version": "1.0.0-alpha.10",
+  "description": "TypeCAD framework package for the Zephyr RTOS — west/CMake build, devicetree-driven GPIO",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./display": {
+      "types": "./dist/display/index.d.ts",
+      "default": "./dist/display/index.js"
+    },
+    "./framework.manifest": {
+      "types": "./dist/framework.manifest.d.ts",
+      "default": "./dist/framework.manifest.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run --root ../.. tests/packages/framework-zephyr/manifest.test.ts",
+    "test:coverage": "npm test && tsx ../../scripts/render-framework-coverage.ts",
+    "test:hw": "npm exec -- cuttlefish-test",
+    "test:hw:basics": "npm exec -- cuttlefish-test tests/01-basics.test.ts",
+    "test:hw:gpio": "npm exec -- cuttlefish-test tests/40-gpio.test.ts",
+    "test:hw:timers": "npm exec -- cuttlefish-test tests/42-timers.test.ts",
+    "test:http": "tsx ../../tests/hardware/start-server.ts",
+    "test:hw:http": "cd ../../tests/hardware && npm exec -- cuttlefish-test http-client.test.ts",
+    "test:mqtt": "tsx ../../tests/hardware/start-server.ts",
+    "test:hw:mqtt": "cd ../../tests/hardware && npm exec -- cuttlefish-test mqtt-client.test.ts"
+  },
+  "dependencies": {
+    "@typecad/cuttlefish": "1.0.0-alpha.10"
+  },
+  "devDependencies": {
+    "@typecad/expect": "1.0.0-alpha.10",
+    "@typecad/board-xiao-nrf52840": "1.0.0-alpha.10",
+    "typescript": "^5.7.3"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/justind000/typecode.git",
+    "directory": "packages/framework-zephyr"
+  },
+  "homepage": "https://github.com/justind000/typecode/tree/main/packages/framework-zephyr",
+  "bugs": {
+    "url": "https://github.com/justind000/typecode/issues"
+  },
+  "keywords": [
+    "ble",
+    "cpp",
+    "cuttlefish",
+    "embedded",
+    "firmware",
+    "framework",
+    "gpio",
+    "microcontroller",
+    "nordic",
+    "nrf52840",
+    "rtos",
+    "typecad",
+    "typescript",
+    "zephyr"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "typecad0",
+  "sideEffects": false
+}

package/src/async/timer-polyfill.ts

@@ -0,0 +1,107 @@
+// ---------------------------------------------------------------------------
+// Timer methods polyfill — Zephyr k_timer + k_work (heap-free)
+//
+// setInterval / setTimeout / clearInterval / clearTimeout backed by a fixed
+// pool of k_timer + k_work pairs. The timer's expiry function (ISR context)
+// submits a k_work item to the system workqueue; the work handler runs the
+// user callback in thread context. This split keeps the ISR cheap and lets the
+// callback run on a real thread (so it can do real work — but must not block,
+// since the system workqueue is shared).
+//
+// EMIT BOUNDARY: emitted bytes land in user firmware. Covered by the TypeCAD
+// Runtime Exception (RUNTIME_EXCEPTION.md at the repo root).
+// ---------------------------------------------------------------------------
+
+import type { RuntimePolyfillIR } from '@typecad/cuttlefish/api/shared';
+
+const MIN_TIMERS = 1;
+const MAX_TIMERS_CAP = 16;
+
+export interface TimerPolyfillIR extends RuntimePolyfillIR {
+  /** The clamped pool size the C++ was generated with. */
+  maxTimers: number;
+}
+
+/**
+ * Build the timer_methods polyfill IR. `requestedTimers` is sized from
+ * ctx.analysis.timerCallCount; it is clamped to [1, 16].
+ */
+export function buildTimerPolyfill(requestedTimers: number): TimerPolyfillIR {
+  const maxTimers = Math.min(MAX_TIMERS_CAP, Math.max(MIN_TIMERS, requestedTimers));
+
+  const helperStructs = [`
+// cuttlefish timer runtime — k_timer + k_work pool (heap-free).
+struct __tc_TimerSlot {
+    struct k_timer timer;
+    struct k_work work;
+    void (*callback)(void);
+    bool active;
+};
+
+static struct __tc_TimerSlot __tc_timer_slots[${maxTimers}];
+
+static void __tc_timer_work_handler(struct k_work* w) {
+    // Runs on the system workqueue thread (NOT ISR). Find the owning slot by
+    // address and invoke the callback. Must not block.
+    for (int32_t i = 0; i < ${maxTimers}; i++) {
+        if (&__tc_timer_slots[i].work == w) {
+            if (__tc_timer_slots[i].callback != nullptr) { __tc_timer_slots[i].callback(); }
+            return;
+        }
+    }
+}
+
+static void __tc_timer_expiry_fn(struct k_timer* t) {
+    // ISR context: submit the work item, do NOT run the callback here.
+    for (int32_t i = 0; i < ${maxTimers}; i++) {
+        if (&__tc_timer_slots[i].timer == t) {
+            (void)k_work_submit(&__tc_timer_slots[i].work);
+            return;
+        }
+    }
+}
+
+static int32_t __tc_timer_add(void (*cb)(void), int32_t ms, bool repeat) {
+    for (int32_t i = 0; i < ${maxTimers}; i++) {
+        if (!__tc_timer_slots[i].active) {
+            __tc_timer_slots[i].callback = cb;
+            __tc_timer_slots[i].active = true;
+            k_timer_init(&__tc_timer_slots[i].timer, __tc_timer_expiry_fn, nullptr);
+            k_work_init(&__tc_timer_slots[i].work, __tc_timer_work_handler);
+            k_timer_start(&__tc_timer_slots[i].timer, K_MSEC(ms), repeat ? K_MSEC(ms) : K_FOREVER);
+            return i + 1;  // 1-based id (Arduino parity)
+        }
+    }
+    return 0;  // pool full
+}
+
+static void __tc_timer_clear(int32_t id) {
+    if (id > 0 && id <= ${maxTimers}) {
+        int32_t i = id - 1;
+        k_timer_stop(&__tc_timer_slots[i].timer);
+        __tc_timer_slots[i].active = false;
+        __tc_timer_slots[i].callback = nullptr;
+    }
+}
+`];
+
+  const helperFunctions = [`
+int32_t __tc_setInterval(void (*cb)(), int32_t ms) { return __tc_timer_add(cb, ms, true); }
+int32_t __tc_setTimeout(void (*cb)(), int32_t ms) { return __tc_timer_add(cb, ms, false); }
+void __tc_clearInterval(int32_t id) { __tc_timer_clear(id); }
+void __tc_clearTimeout(int32_t id) { __tc_timer_clear(id); }
+`];
+
+  return {
+    kind: 'polyfill',
+    id: 'timer_methods',
+    domain: 'embedded',
+    requiredIncludes: [],
+    forwardDeclarations: [],
+    helperStructs,
+    helperFunctions,
+    shimMacros: [],
+    dependencies: [],
+    maxTimers,
+  };
+}

package/src/chips/controllers.ts

@@ -0,0 +1,74 @@
+// ---------------------------------------------------------------------------
+// GPIO controller resolution — pin → devicetree nodelabel
+//
+// Most SoCs expose a single GPIO controller, so a HAL pin maps to
+// `chip.gpioController` unconditionally. SoCs that split GPIO across multiple
+// devicetree nodes (ESP32-S3: `gpio0` 0–31, `gpio1` 32–48) list a range per
+// controller in `chip.gpioControllers`. These helpers route a HAL pin to the
+// owning controller.
+//
+// Two forms:
+//   - controllerNodelabelForPin(): used by the compile-time lowering paths
+//     (gpio/pulse/spi raw writes), where the pin number is a literal known at
+//     transpile time. Resolves to a single nodelabel so the emitted
+//     `DT_NODELABEL(<nodelabel>)` macro is statically valid.
+//   - emitGpioDevDispatcher(): used by paths that take a RUNTIME pin (the
+//     @typecad/safety __tc_gpio_read/__tc_gpio_write shims). Emits a tiny
+//     `__tc_gpio_dev(uint32_t pin)` that returns the owning `const struct
+//     device*`, so a single shim body handles any pin. Single-controller SoCs
+//     collapse to a one-liner.
+// ---------------------------------------------------------------------------
+
+import type { ZephyrChipDescriptor } from './types.js';
+
+/**
+ * Resolve the devicetree nodelabel of the GPIO controller that owns `pin`.
+ *
+ * For single-controller SoCs (no `gpioControllers`) this is always
+ * `chip.gpioController`. For multi-controller SoCs it finds the entry whose
+ * [minPin, maxPin] range contains `pin`, falling back to `chip.gpioController`
+ * for out-of-range pins (e.g. the manifest probe's synthetic pin 0).
+ */
+export function controllerNodelabelForPin(chip: ZephyrChipDescriptor, pin: number): string {
+  const ranges = chip.gpioControllers;
+  if (ranges && ranges.length > 0) {
+    const hit = ranges.find((r) => pin >= r.minPin && pin <= r.maxPin);
+    if (hit) return hit.nodelabel;
+  }
+  return chip.gpioController;
+}
+
+/**
+ * Emit the C++ source for a runtime pin → GPIO-device dispatcher.
+ *
+ * Returns lines defining `static inline const struct device* __tc_gpio_dev(uint32_t pin)`.
+ * Each branch resolves its controller via `DEVICE_DT_GET(DT_NODELABEL(...))` at
+ * compile time (the macro is evaluated per branch, so it is always statically
+ * valid); only `pin` is runtime. For a single-controller SoC this collapses to
+ * a one-liner returning that controller, so the existing XIAO nRF52840 behavior
+ * is byte-for-byte unchanged.
+ */
+export function emitGpioDevDispatcher(chip: ZephyrChipDescriptor): string[] {
+  const ranges = chip.gpioControllers;
+  if (!ranges || ranges.length === 0) {
+    return [
+      'static inline const struct device* __tc_gpio_dev(uint32_t pin) {',
+      `    (void)pin;`,
+      `    return DEVICE_DT_GET(DT_NODELABEL(${chip.gpioController}));`,
+      '}',
+    ];
+  }
+  const lines: string[] = [
+    'static inline const struct device* __tc_gpio_dev(uint32_t pin) {',
+  ];
+  for (const r of ranges) {
+    lines.push(
+      `    if (pin >= ${r.minPin} && pin <= ${r.maxPin}) { return DEVICE_DT_GET(DT_NODELABEL(${r.nodelabel})); }`,
+    );
+  }
+  lines.push(
+    `    return DEVICE_DT_GET(DT_NODELABEL(${chip.gpioController}));`,
+    '}',
+  );
+  return lines;
+}

package/src/chips/esp32.ts

@@ -0,0 +1,62 @@
+// ---------------------------------------------------------------------------
+// Espressif ESP32 (esp32_devkitc) — Zephyr board descriptor
+//
+// Board target: `esp32_devkitc` (mainline Zephyr,
+// boards/espressif/esp32_devkitc). Programmed over USB via the esptool runner
+// (see toolchain/index.ts), the same flash path as the ESP32-S3.
+//
+// GPIO is split across TWO devicetree controllers — `gpio0` (pins 0–31) and
+// `gpio1` (pins 32–39) — so this descriptor lists both in `gpioControllers`.
+// The lowering routes each HAL pin to its owning controller at runtime; see
+// chips/controllers.ts. (Same shape as the S3, but the ESP32's highest GPIO is
+// 39, not 48 — `gpio1` has ngpios=8, not 17.)
+//
+// Minimal-by-design: the only DT facts carried here are the ones a compile-time
+// DT macro cannot reach — the runtime pin→controller split, plus the `sw0`
+// alias for the BOOT button (used by the devicetree-spec GPIO path). Every other
+// DT fact (UART/I2C/SPI/`wdt` nodelabels) is resolved by Zephyr's own
+// devicetree via emitted DT_NODELABEL macros, not hand-copied here.
+//
+// Verified against the Zephyr board DTS:
+//   boards/espressif/esp32_devkitc/esp32_devkitc_procpu.dts
+//   aliases { sw0 = &button0; } → button_0: pin 0 on gpio0, active-low + pull-up
+//   &gpio0/&gpio1 { status = "okay" }   (esp32_devkitc_procpu.dts:64-70)
+//   &wifi { status = "okay" }            (esp32_devkitc_procpu.dts:143-145)
+// GPIO controller coverage:
+//   dts/xtensa/espressif/esp32/esp32_common.dtsi:314-337
+//   gpio0: ngpios = <32>  (pins 0–31)
+//   gpio1: ngpios = <8>   (pins 32–39)
+//
+// Note: GPIO 34–39 are input-only pads on ESP32 silicon (not modeled here —
+// the DT does not encode output restrictions per pin; an output config on those
+// pins fails at runtime against the raw controller, which is the expected
+// silicon-accurate behavior).
+// ---------------------------------------------------------------------------
+
+import type { ZephyrChipDescriptor } from './types.js';
+
+export const ESP32_DEVKITC: ZephyrChipDescriptor = {
+  id: 'esp32_devkitc',
+  soc: 'esp32',
+  gpioController: 'gpio0',
+  gpioControllers: [
+    { nodelabel: 'gpio0', minPin: 0, maxPin: 31 },
+    { nodelabel: 'gpio1', minPin: 32, maxPin: 39 },
+  ],
+  gpio: {
+    // The BOOT button (GPIO0) is the board's only DT-aliased GPIO. Listed so a
+    // program reading/interrupting pin 0 goes through the polarity-correct
+    // devicetree-spec path (GPIO_ACTIVE_LOW honored by the DT flags).
+    dtSpecs: [
+      { pin: 0, dtSpec: 'sw0' },  // BOOT button (GPIO0)
+    ],
+    interruptPins: [
+      { pin: 0, dtSpec: 'sw0' },  // BOOT button (GPIO0)
+    ],
+  },
+  // WiFi: the ESP32 has a 2.4GHz radio; conn_mgr + the esp32 wifi driver
+  // (CONFIG_WIFI_ESP32) provide connectivity. WIFI_ESP32 depends on !SMP, and
+  // the ESP32 is AMP (dual-image procpu/appcpu), not SMP, by default — so the
+  // dependency is satisfied. Omitted on radioless targets.
+  wifi: { supported: true },
+};

package/src/chips/esp32s3.ts

@@ -0,0 +1,57 @@
+// ---------------------------------------------------------------------------
+// Espressif ESP32-S3 (esp32s3_devkitc) — Zephyr board descriptor
+//
+// Board target: `esp32s3_devkitc` (mainline Zephyr,
+// boards/espressif/esp32s3_devkitc). Programmed over USB via the esptool
+// runner (see toolchain/index.ts), unlike the J-Link/nrfjprog path used for
+// the XIAO nRF52840.
+//
+// GPIO is split across TWO devicetree controllers — `gpio0` (pins 0–31) and
+// `gpio1` (pins 32–48) — so this descriptor lists both in `gpioControllers`.
+// The lowering routes each HAL pin to its owning controller at runtime; see
+// chips/controllers.ts.
+//
+// Minimal-by-design: the only DT facts carried here are the ones a
+// compile-time DT macro cannot reach — the runtime pin→controller split, plus
+// the `sw0` alias for the BOOT button (used by the devicetree-spec GPIO path).
+// Every other DT fact (UART/I2C/SPI/`wdt` nodelabels) is resolved by Zephyr's
+// own devicetree via emitted DT_NODELABEL macros, not hand-copied here.
+//
+// Verified against the Zephyr board DTS:
+//   boards/espressif/esp32s3_devkitc/esp32s3_devkitc_procpu.dts
+//   aliases { sw0 = &button0; } → button_0: pin 0 on gpio0, active-low + pull-up
+//   (the DevKitC board DTS defines no led0 alias — the onboard RGB is a WS2812
+//   on GPIO38, not a plain GPIO LED, so it is intentionally NOT listed here.)
+// ---------------------------------------------------------------------------
+
+import type { ZephyrChipDescriptor } from './types.js';
+
+export const ESP32S3_DEVKITC: ZephyrChipDescriptor = {
+  id: 'esp32s3_devkitc',
+  soc: 'esp32s3',
+  gpioController: 'gpio0',
+  gpioControllers: [
+    { nodelabel: 'gpio0', minPin: 0, maxPin: 31 },
+    { nodelabel: 'gpio1', minPin: 32, maxPin: 48 },
+  ],
+  gpio: {
+    // The BOOT button (GPIO0) is the board's only DT-aliased GPIO. Listed so a
+    // program reading/interrupting pin 0 goes through the polarity-correct
+    // devicetree-spec path (GPIO_ACTIVE_LOW honored by the DT flags). Every
+    // other GPIO pin uses the raw-controller path against its owning controller.
+    dtSpecs: [
+      { pin: 0, dtSpec: 'sw0' },  // BOOT button (GPIO0)
+    ],
+    interruptPins: [
+      { pin: 0, dtSpec: 'sw0' },  // BOOT button (GPIO0)
+    ],
+  },
+  // UART/I2C/SPI/`wdt` are intentionally omitted: their devicetree nodelabels
+  // (uart0/uart1/uart2, i2c0/i2c1, spi2/spi3, wdt0) are resolved by Zephyr's
+  // devicetree at compile time and don't need to be carried as data here. ADC is
+  // omitted as well — added when a demo needs analog reads, with the verified
+  // ESP32-S3 ADC1/ADC2 pin→channel map.
+  // WiFi: the ESP32-S3 has a 2.4GHz radio; conn_mgr + the esp32 wifi driver
+  // (CONFIG_WIFI_ESP32) provide connectivity. Omitted on radioless targets.
+  wifi: { supported: true },
+};

package/src/chips/index.ts

@@ -0,0 +1,54 @@
+// ---------------------------------------------------------------------------
+// Chip descriptor registry — maps Zephyr board target → ZephyrChipDescriptor
+//
+// Mirrors framework-esp32/src/chips/index.ts: a module-level activeChip,
+// setActiveChip/getActiveChip, and chipForTarget resolving from
+// frameworkData.buildTarget. The strategy calls setActiveChip during profile
+// resolution so the lowering reads a single cached descriptor.
+// ---------------------------------------------------------------------------
+
+import type { ZephyrChipDescriptor } from './types.js';
+import { XIAO_BLE } from './xiao-ble.js';
+import { ESP32S3_DEVKITC } from './esp32s3.js';
+import { ESP32_DEVKITC } from './esp32.js';
+
+export { XIAO_BLE, ESP32S3_DEVKITC, ESP32_DEVKITC };
+export type { ZephyrChipDescriptor, ZephyrGpioDtSpec } from './types.js';
+
+/**
+ * Default chip used when no buildTarget is supplied. The XIAO nRF52840 is the
+ * canonical MVP target; subsequent board additions extend the switch below.
+ */
+const DEFAULT_CHIP: ZephyrChipDescriptor = XIAO_BLE;
+
+let activeChip: ZephyrChipDescriptor = DEFAULT_CHIP;
+
+export function setActiveChip(d: ZephyrChipDescriptor): void {
+  activeChip = d;
+}
+
+export function getActiveChip(): ZephyrChipDescriptor {
+  return activeChip;
+}
+
+/**
+ * Resolve a chip descriptor from the Zephyr board target string
+ * (frameworkData.buildTarget / frameworkData.target). Accepts the bare board
+ * id ('xiao_ble', 'esp32s3_devkitc', 'esp32_devkitc') or a board/qualifier
+ * path ('esp32s3_devkitc/esp32s3/procpu', 'esp32_devkitc/esp32/procpu').
+ */
+export function chipForTarget(target?: string): ZephyrChipDescriptor {
+  const t = (target ?? '').trim().toLowerCase();
+  const boardId = t.split('/')[0];
+  switch (boardId) {
+    case 'xiao_ble':
+      return XIAO_BLE;
+    case 'esp32s3_devkitc':
+      return ESP32S3_DEVKITC;
+    case 'esp32_devkitc':
+      return ESP32_DEVKITC;
+    case '':
+    default:
+      return DEFAULT_CHIP;
+  }
+}

package/src/chips/resolve.ts

@@ -0,0 +1,146 @@
+// ---------------------------------------------------------------------------
+// Derive ZephyrChipDescriptor from board/MCU package constants
+//
+// The board constants resolver extracts flat dot-path scalars from the board
+// and MCU definition files. This utility reconstructs the structured
+// ZephyrChipDescriptor from those flat keys, merging SoC-level defaults
+// (from the MCU package's zephyr field) with board-level overrides (from the
+// board package's zephyr field).
+//
+// When a board package carries Zephyr config, this path replaces the
+// hardcoded chip descriptor registry. When it doesn't (legacy), chipForTarget
+// still works as the fallback.
+// ---------------------------------------------------------------------------
+
+import type { BoardConstants } from '@typecad/cuttlefish/api/shared';
+import type {
+  ZephyrChipDescriptor,
+  ZephyrGpioDtSpec,
+  ZephyrGpioController,
+  ZephyrBusController,
+  ZephyrPwmSpec,
+  ZephyrInterruptPin,
+  ZephyrAdcChannel,
+} from './types.js';
+
+/** Collect an indexed array of objects reconstructed from flat dot-path keys. */
+function collectIndexed<T>(
+  bc: BoardConstants,
+  prefix: string,
+  build: (bc: BoardConstants, index: number) => T | null,
+): T[] {
+  const result: T[] = [];
+  for (let i = 0; i < 256; i++) {
+    const checkKey = `${prefix}.${i}`;
+    let hasAny = false;
+    for (const [k] of bc) {
+      if (k.startsWith(checkKey)) { hasAny = true; break; }
+    }
+    if (!hasAny) break;
+    const item = build(bc, i);
+    if (item) result.push(item);
+  }
+  return result;
+}
+
+function collectBusControllers(
+  bc: BoardConstants,
+  prefix: string,
+): ZephyrBusController[] {
+  return collectIndexed<ZephyrBusController>(bc, prefix, (m, i) => {
+    const nodeLabel = m.get(`${prefix}.${i}.nodeLabel`) as string;
+    return nodeLabel ? { nodeLabel } : null;
+  });
+}
+
+/**
+ * Try to derive a ZephyrChipDescriptor from board/MCU package constants.
+ *
+ * Returns null when no zephyr info is available in the board constants
+ * (the caller should fall back to the hardcoded chipForTarget registry).
+ */
+export function resolveChipFromBoard(
+  bc: BoardConstants | undefined,
+): ZephyrChipDescriptor | null {
+  if (!bc) return null;
+
+  const boardTarget = bc.get('build.frameworks.zephyr') as string | undefined;
+  if (!boardTarget) return null;
+
+  const zGpioController = bc.get('zephyr.gpioController') as string | undefined;
+  const soc = (bc.get('mcu.id') as string) ?? '';
+
+  // ── Build mutable sub-objects, then construct the final descriptor ──────
+
+  const gc = collectIndexed<ZephyrGpioController>(bc, 'zephyr.gpioControllers', (m, i) => {
+    const nodelabel = m.get(`zephyr.gpioControllers.${i}.nodelabel`) as string;
+    const minPin = m.get(`zephyr.gpioControllers.${i}.minPin`) as number;
+    const maxPin = m.get(`zephyr.gpioControllers.${i}.maxPin`) as number;
+    if (nodelabel != null && minPin != null && maxPin != null) {
+      return { nodelabel, minPin, maxPin };
+    }
+    return null;
+  });
+
+  const dtSpecs = collectIndexed<ZephyrGpioDtSpec>(bc, 'zephyr.gpio.dtSpecs', (m, i) => {
+    const pin = m.get(`zephyr.gpio.dtSpecs.${i}.pin`) as number;
+    const dtSpec = m.get(`zephyr.gpio.dtSpecs.${i}.dtSpec`) as string;
+    if (pin != null && dtSpec) return { pin, dtSpec };
+    return null;
+  });
+
+  const intPins = collectIndexed<ZephyrInterruptPin>(bc, 'zephyr.gpio.interruptPins', (m, i) => {
+    const pin = m.get(`zephyr.gpio.interruptPins.${i}.pin`) as number;
+    const dtSpec = m.get(`zephyr.gpio.interruptPins.${i}.dtSpec`) as string;
+    if (pin != null && dtSpec) return { pin, dtSpec };
+    return null;
+  });
+
+  const i2cControllers = collectBusControllers(bc, 'zephyr.i2c.controllers');
+  const spiControllers = collectBusControllers(bc, 'zephyr.spi.controllers');
+  const uartControllers = collectBusControllers(bc, 'zephyr.uart.controllers');
+
+  const pwmSpecs = collectIndexed<ZephyrPwmSpec>(bc, 'zephyr.pwm.specs', (m, i) => {
+    const pin = m.get(`zephyr.pwm.specs.${i}.pin`) as number;
+    const dtSpec = m.get(`zephyr.pwm.specs.${i}.dtSpec`) as string;
+    if (pin != null && dtSpec) return { pin, dtSpec };
+    return null;
+  });
+
+  const adcNodeLabel = bc.get('zephyr.adc.nodeLabel') as string | undefined;
+  const adcResolution = bc.get('zephyr.adc.resolution') as number | undefined;
+  const adcVref = bc.get('zephyr.adc.vrefMv') as number | undefined;
+  const adcChannels = collectIndexed<ZephyrAdcChannel>(bc, 'zephyr.adc.channels', (m, i) => {
+    const pin = m.get(`zephyr.adc.channels.${i}.pin`) as number;
+    const channel = m.get(`zephyr.adc.channels.${i}.channel`) as number;
+    if (pin != null && channel != null) return { pin, channel };
+    return null;
+  });
+
+  const wdtNodeLabel = bc.get('zephyr.wdt.nodeLabel') as string | undefined;
+  const wifiSupported = bc.get('zephyr.wifi.supported') as boolean | undefined;
+
+  // ── Construct the final readonly descriptor ─────────────────────────────
+
+  const gpio: ZephyrChipDescriptor['gpio'] = {
+    dtSpecs,
+    ...(intPins.length > 0 ? { interruptPins: intPins } : {}),
+  };
+
+  return {
+    id: boardTarget,
+    soc,
+    gpioController: zGpioController ?? 'gpio0',
+    ...(gc.length > 0 ? { gpioControllers: gc } : {}),
+    gpio,
+    ...(i2cControllers.length > 0 ? { i2c: { controllers: i2cControllers } } : {}),
+    ...(spiControllers.length > 0 ? { spi: { controllers: spiControllers } } : {}),
+    ...(uartControllers.length > 0 ? { uart: { controllers: uartControllers } } : {}),
+    ...(pwmSpecs.length > 0 ? { pwm: { specs: pwmSpecs } } : {}),
+    ...(adcNodeLabel || adcResolution != null || adcVref != null || adcChannels.length > 0
+      ? { adc: { nodeLabel: adcNodeLabel ?? 'adc', resolution: adcResolution ?? 12, vrefMv: adcVref ?? 3000, channels: adcChannels } }
+      : {}),
+    ...(wdtNodeLabel ? { wdt: { nodeLabel: wdtNodeLabel } } : {}),
+    ...(wifiSupported ? { wifi: { supported: true as const } } : {}),
+  };
+}