@typecad/framework-zephyr 1.0.0-alpha.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 typecad0
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# @typecad/framework-zephyr
+
+TypeCAD framework package that lowers HAL operation IR to **native Zephyr RTOS
+driver API calls**. Generates a real Zephyr application (`main` + `src/main.cpp`
++ `CMakeLists.txt` + `prj.conf`), compiled through Zephyr's `west` / CMake /
+Ninja build system.
+
+GPIO is lowered through devicetree specs (`gpio_pin_*_dt`) so an active-low
+LED's polarity is honored by the DT flags, not by the generated code.
+
+## Requirements
+
+- Zephyr RTOS ≥ 3.x installed (the SDK + a west-enabled Python environment).
+- The framework auto-discovers `west` without requiring you to activate the
+  venv first. Discovery cascade (first usable wins):
+  1. `west` already on `PATH` (env already activated / global install).
+  2. `$ZEPHYR_BASE` sibling venv: `${ZEPHYR_BASE}/../.venv/<python> -m west`.
+  3. Well-known workspace layouts (`~/zephyrproject/.venv`,
+     `/opt/zephyrproject/.venv`, etc.).
+  4. System pythons (`python`, `python3`, `py`) via `-m west`.
+
+If none is found, the build errors with an actionable message pointing at the
+fix (`pip install west`, set `ZEPHYR_BASE`, or activate the venv).
+
+## How it works
+
+- HAL ops (`gpio.write`, `i2c.begin`, etc.) lower to native Zephyr driver calls
+  (`gpio_pin_set_dt`, `i2c_write`, etc.) — no Arduino API.
+- The generated `src/main.cpp` defines `int main(void)` — the standard Zephyr
+  C entry point. `main` runs the synthesizer-emitted `setup()` once, then loops
+  `loop()` forever, yielding to the scheduler with `k_msleep(1)` each iteration
+  (cheap cooperative yield — matches the `app_main` pattern in framework-esp32).
+- The framework emits a complete Zephyr application: root `CMakeLists.txt`
+  (`find_package(Zephyr)` + `file(GLOB src/*.cpp)`) and `prj.conf` (the Kconfig
+  symbols for the lowered peripherals). Both are regenerated idempotently —
+  only rewritten when their content changes, so Ninja's incremental build is
+  preserved.
+- The MVP target is the **Seeed Studio XIAO nRF52840** (`xiao_ble` board).
+
+## Installation
+
+```sh
+cuttlefish init   # select "Zephyr RTOS" for an nRF52840-family target
+```
+
+Or in `cuttlefish.config.ts`:
+
+```ts
+export default {
+  framework: '@typecad/framework-zephyr',
+  frameworkData: {
+    buildTarget: 'xiao_ble',
+  },
+  toolchain: { type: 'west' },
+};
+```
+
+## HAL coverage
+
+The manifest (`src/framework.manifest.ts`) is the honest, complete record of
+what lowers. Fully supported: **gpio, pwm, adc, i2c, spi, uart, wdt, ble,
+shift, board constants** (Board.definition.* / Pins.definition.* folding),
+**random** (xorshift32 PRNG seeded from the Zephyr entropy tap).
+Partial (some ops lower, some are deferred stubs): **timing, power,
+interrupts, tone, pulse**. Unsupported for this target: **wifi** (nRF52840 has
+no WiFi), **http** (no networking stack lowered), **display** (deferred),
+**dac** (no DAC on nRF52840).
+
+Run `npm test` (the manifest validator) to confirm the declared coverage matches
+the actual lowering behavior.
+
+## Hardware tests
+
+On-device tests live in `tests/`. Run them against real hardware:
+
+```sh
+npm run test:hw          # all groups
+npm run test:hw:gpio     # just GPIO
+npm run test:hw:timers   # just timing
+```
+
+Update `test.port` in `cuttlefish.config.ts` to your XIAO's serial device
+before running. The tests transpile → `west build` → flash → read results over
+the console.
+
+## Notes / limitations
+
+- **Minimal C++ libc.** Zephyr's default C++ support (`lib/cpp/minimal`) has no
+  `<vector>`, `<string>`, `<iostream>`, `<functional>`, exceptions, or RTTI.
+  `prj.conf` enables `CONFIG_NEWLIB_LIBC` for `std::string`/`std::vector`; array
+  literals still promote to the StaticArray wrapper, not `std::vector`.
+- **Timer ops unsupported.** `timing.set_interval`/`set_timeout`/`clear_*` need
+  a polyfill-backed async runtime this framework does not emit yet. A Zephyr
+  workqueue / `k_thread` backing is a follow-on.
+- **Debug mode.** `cuttlefish build --debug` routes through `printk` (always
+  available, no `CONFIG_CONSOLE` dependency) rather than `std::cout`, since the
+  minimal libc has no iostream. Breakpoints halt on console input (`ENTER`
+  continues, `s` skips).
+- **AUTOSAR compliance.** All emitted C++ uses `static_cast`/`reinterpret_cast`
+  (no C-style casts) so the shim bytes pass `--autosar=strict`.

package/dist/async/timer-polyfill.d.ts

@@ -0,0 +1,10 @@
+import type { RuntimePolyfillIR } from '@typecad/cuttlefish/api/shared';
+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 declare function buildTimerPolyfill(requestedTimers: number): TimerPolyfillIR;

package/dist/async/timer-polyfill.js

@@ -0,0 +1,95 @@
+// ---------------------------------------------------------------------------
+// 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).
+// ---------------------------------------------------------------------------
+const MIN_TIMERS = 1;
+const MAX_TIMERS_CAP = 16;
+/**
+ * Build the timer_methods polyfill IR. `requestedTimers` is sized from
+ * ctx.analysis.timerCallCount; it is clamped to [1, 16].
+ */
+export function buildTimerPolyfill(requestedTimers) {
+    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/dist/chips/controllers.d.ts

@@ -0,0 +1,21 @@
+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 declare function controllerNodelabelForPin(chip: ZephyrChipDescriptor, pin: number): string;
+/**
+ * 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 declare function emitGpioDevDispatcher(chip: ZephyrChipDescriptor): string[];

package/dist/chips/controllers.js

@@ -0,0 +1,66 @@
+// ---------------------------------------------------------------------------
+// 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.
+// ---------------------------------------------------------------------------
+/**
+ * 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, pin) {
+    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) {
+    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 = [
+        '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/dist/chips/esp32.d.ts

@@ -0,0 +1,2 @@
+import type { ZephyrChipDescriptor } from './types.js';
+export declare const ESP32_DEVKITC: ZephyrChipDescriptor;

package/dist/chips/esp32.js

@@ -0,0 +1,59 @@
+// ---------------------------------------------------------------------------
+// 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).
+// ---------------------------------------------------------------------------
+export const ESP32_DEVKITC = {
+    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/dist/chips/esp32s3.d.ts

@@ -0,0 +1,2 @@
+import type { ZephyrChipDescriptor } from './types.js';
+export declare const ESP32S3_DEVKITC: ZephyrChipDescriptor;

package/dist/chips/esp32s3.js

@@ -0,0 +1,54 @@
+// ---------------------------------------------------------------------------
+// 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.)
+// ---------------------------------------------------------------------------
+export const ESP32S3_DEVKITC = {
+    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/dist/chips/index.d.ts

@@ -0,0 +1,15 @@
+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';
+export declare function setActiveChip(d: ZephyrChipDescriptor): void;
+export declare function getActiveChip(): ZephyrChipDescriptor;
+/**
+ * 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 declare function chipForTarget(target?: string): ZephyrChipDescriptor;

package/dist/chips/index.js

@@ -0,0 +1,45 @@
+// ---------------------------------------------------------------------------
+// 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 { 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 };
+/**
+ * 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 = XIAO_BLE;
+let activeChip = DEFAULT_CHIP;
+export function setActiveChip(d) {
+    activeChip = d;
+}
+export function getActiveChip() {
+    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) {
+    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/dist/chips/resolve.d.ts

@@ -0,0 +1,9 @@
+import type { BoardConstants } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from './types.js';
+/**
+ * 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 declare function resolveChipFromBoard(bc: BoardConstants | undefined): ZephyrChipDescriptor | null;

package/dist/chips/resolve.js

@@ -0,0 +1,121 @@
+// ---------------------------------------------------------------------------
+// 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.
+// ---------------------------------------------------------------------------
+/** Collect an indexed array of objects reconstructed from flat dot-path keys. */
+function collectIndexed(bc, prefix, build) {
+    const result = [];
+    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, prefix) {
+    return collectIndexed(bc, prefix, (m, i) => {
+        const nodeLabel = m.get(`${prefix}.${i}.nodeLabel`);
+        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) {
+    if (!bc)
+        return null;
+    const boardTarget = bc.get('build.frameworks.zephyr');
+    if (!boardTarget)
+        return null;
+    const zGpioController = bc.get('zephyr.gpioController');
+    const soc = bc.get('mcu.id') ?? '';
+    // ── Build mutable sub-objects, then construct the final descriptor ──────
+    const gc = collectIndexed(bc, 'zephyr.gpioControllers', (m, i) => {
+        const nodelabel = m.get(`zephyr.gpioControllers.${i}.nodelabel`);
+        const minPin = m.get(`zephyr.gpioControllers.${i}.minPin`);
+        const maxPin = m.get(`zephyr.gpioControllers.${i}.maxPin`);
+        if (nodelabel != null && minPin != null && maxPin != null) {
+            return { nodelabel, minPin, maxPin };
+        }
+        return null;
+    });
+    const dtSpecs = collectIndexed(bc, 'zephyr.gpio.dtSpecs', (m, i) => {
+        const pin = m.get(`zephyr.gpio.dtSpecs.${i}.pin`);
+        const dtSpec = m.get(`zephyr.gpio.dtSpecs.${i}.dtSpec`);
+        if (pin != null && dtSpec)
+            return { pin, dtSpec };
+        return null;
+    });
+    const intPins = collectIndexed(bc, 'zephyr.gpio.interruptPins', (m, i) => {
+        const pin = m.get(`zephyr.gpio.interruptPins.${i}.pin`);
+        const dtSpec = m.get(`zephyr.gpio.interruptPins.${i}.dtSpec`);
+        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(bc, 'zephyr.pwm.specs', (m, i) => {
+        const pin = m.get(`zephyr.pwm.specs.${i}.pin`);
+        const dtSpec = m.get(`zephyr.pwm.specs.${i}.dtSpec`);
+        if (pin != null && dtSpec)
+            return { pin, dtSpec };
+        return null;
+    });
+    const adcNodeLabel = bc.get('zephyr.adc.nodeLabel');
+    const adcResolution = bc.get('zephyr.adc.resolution');
+    const adcVref = bc.get('zephyr.adc.vrefMv');
+    const adcChannels = collectIndexed(bc, 'zephyr.adc.channels', (m, i) => {
+        const pin = m.get(`zephyr.adc.channels.${i}.pin`);
+        const channel = m.get(`zephyr.adc.channels.${i}.channel`);
+        if (pin != null && channel != null)
+            return { pin, channel };
+        return null;
+    });
+    const wdtNodeLabel = bc.get('zephyr.wdt.nodeLabel');
+    const wifiSupported = bc.get('zephyr.wifi.supported');
+    // ── Construct the final readonly descriptor ─────────────────────────────
+    const 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 } } : {}),
+    };
+}