@typecad/framework-zephyr 1.0.0-alpha.13 → 1.0.0-alpha.15

package/README.md

@@ -24,74 +24,61 @@ 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.
+- HAL ops (`gpio.write`, `i2c.reg_read`, etc.) lower to native Zephyr driver
+  calls (`gpio_pin_set_dt`, `i2c_reg_read_byte`, 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).
+  C entry point. Top-level statements lower straight into `main()` (no
+  `setup()`/`loop()` pair); event-driven programs get their scheduler loop
+  appended inside `main()` by the driver machinery.
 - 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).
+- Board targets are not curated: **every board variant in the generated board
+  catalog** resolves the same way (`resolveChipFromBoard` over the catalog's
+  board data — there is no hardcoded chip registry or target list). The
+  catalog is machine-local, generated from your Zephyr tree by
+  `cuttlefish board sync` (and refreshed automatically by builds).
 
 ## Installation
 
 ```sh
-cuttlefish init   # select "Zephyr RTOS" for an nRF52840-family target
+cuttlefish create   # pick a board from the catalog; the Zephyr framework is the default
 ```
 
 Or in `cuttlefish.config.ts`:
 
 ```ts
 export default {
+  entry: './src/main.ts',
+  board: 'xiao_ble/nrf52840',
   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).
+what lowers. Fully lowered: **gpio, pwm, adc, dac** (pin-fact-gated),
+**i2c, spi, uart, interrupts, timing, wdt, counter, thread, shift, board
+constants**, **random** (xorshift32 PRNG seeded from the Zephyr entropy tap),
+**preferences (Store)**, **fs (File)**, **sensor**, **ble**, **snprintf**, and
+**wifi/http/mqtt** (ESP32-class radio targets only — nRF52840 has no WiFi).
+**Display** lowers via the generic `<zephyr/drivers/display.h>` GFX runtime.
+Declared unsupported on this target: **i2s, twai/CAN, ethernet, espnow,
+hardware crypto, pcnt, mcpwm**. USB CDC is board-gated: it lowers only on
+boards whose DTS enables the USB device controller.
 
 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`

package/dist/as-built.d.ts

@@ -0,0 +1,33 @@
+export interface AsBuiltRoute {
+    source: string;
+    channel: number;
+    port: string;
+    bit: number;
+    pinctrl: string;
+}
+export interface AsBuiltFacts {
+    adc: AsBuiltRoute[];
+    pwm: AsBuiltRoute[];
+    dac: AsBuiltRoute[];
+}
+/** The .cuttlefish/as-built.json shape (machine-authored facts file). */
+export interface AsBuiltFile {
+    version: 1;
+    board: string;
+    generatedAt: string;
+    routes: {
+        adcPins: AsBuiltRoute[];
+        pwmPins: AsBuiltRoute[];
+        dacPins: AsBuiltRoute[];
+    };
+}
+/**
+ * Parse a resolved zephyr.dts into raw pin routes. Labels are matched as
+ * whole tokens (`label:` or `label {`) — in dtc output every node carries
+ * its labels inline before the node name.
+ */
+export declare function parseZephyrDts(text: string): AsBuiltFacts;
+/** Parse + shape-validate .cuttlefish/as-built.json; errors name the file. */
+export declare function parseAsBuiltJson(text: string, source?: string): AsBuiltFile;
+/** Serialize the as-built snapshot (deterministic field order). */
+export declare function asBuiltJson(board: string, facts: AsBuiltFacts): string;

package/dist/as-built.js

@@ -0,0 +1,188 @@
+// ---------------------------------------------------------------------------
+// as-built.ts — harvest pin routes from a build's resolved zephyr.dts
+//
+// The third fact source: after any successful `west build`, the fully
+// merged devicetree at <build>/zephyr/zephyr.dts contains the board's
+// pinctrl nodes with LABELS verbatim — the stable name grammar
+// (`adc1_in1_pa1`, `tim4_ch1_pb6`, `iomuxc_<pad>_adc1_in1`) — with the
+// vendor macro values already expanded away. Parsing names only needs ONE
+// grammar per shape, immune to vendor macro churn, and corrects a broken
+// catalog harvest per-pin before the next build (the walker's macro-value
+// grammars are the fragile half; this is the robust half).
+//
+// Scope is honest: only node-name families appear (STM32-style dtsi nodes
+// and the i.MX RT label grammar with its in-band pad join). Header-matrix
+// families (Kinetis/LPC/GD32 macro routing, ESP32/RP2 matrices) never
+// exist as DT nodes — the walker + family tables remain their source.
+// ----------------------------------------------------------------------------
+// STM32-style pinctrl dtsi labels (all spellings the walker knows):
+// adc1_in1_pa1 / adc_in0_pa0 / adc1_inp16_pa0, tim4_ch1_pb6,
+// dac1_out1_pa4. Labels appear verbatim in zephyr.dts
+// (`adc1_in0_pa0: adc1_in0_pa0 {`). The `inn` negative inputs stay out —
+// the thin HAL is single-ended. The F1 (AFIO) family uses `tim1_ch1_pwm_out_pa8`
+// and `dac_out1_pa4` — separate grammars.
+const ST_ADC = /^([a-z]*adc\d*_(?:in|inp)\d+_p([a-z])(\d+))$/;
+const ST_PWM = /^(tim(\d+)_ch(\d+)_p([a-z])(\d+))$/;
+const ST_PWM_F1 = /^(tim(\d+)_ch(\d+)_pwm_out_p([a-z])(\d+))$/;
+const ST_DAC = /^(dac(\d+)_out(\d+)_p([a-z])(\d+))$/;
+const ST_DAC_F1 = /^(dac_out(\d+)_p([a-z])(\d+))$/;
+// i.MX RT labels: iomuxc_<pad>_adc1_in1 / iomuxc_<pad>_flexpwm2_pwma3,
+// with the pad→GPIO join as sibling iomuxc_<pad>_gpio1_io12 labels. The NEW
+// RT parts (rt11xx/rt116x/rt118x) use `…_flexpwm1_pwm0_a` (pwm<K>_<a|b> →
+// A=0/B=1). Their ADC is the LPADC (`lpadc<N>`) and stays out — see
+// dts-reader.ts.
+const IMX_GPIO = /^iomuxc_([a-z0-9_]+)_gpio(\d+)_io(\d+)$/;
+const IMX_ADC = /^iomuxc_([a-z0-9_]+)_adc(\d+)_in(\d+)$/;
+const IMX_PWM = /^iomuxc_([a-z0-9_]+)_flexpwm(\d+)_pwm([ab])(\d+)$/;
+const IMX_PWM2 = /^iomuxc_([a-z0-9_]+)_flexpwm(\d+)_pwm(\d+)_([ab])$/;
+/**
+ * Parse a resolved zephyr.dts into raw pin routes. Labels are matched as
+ * whole tokens (`label:` or `label {`) — in dtc output every node carries
+ * its labels inline before the node name.
+ */
+export function parseZephyrDts(text) {
+    const facts = { adc: [], pwm: [], dac: [] };
+    const imxPadToGpio = new Map();
+    const seen = new Set();
+    // Every label occurrence: `label:` (label before node) — zephyr.dts
+    // renders `label: nodename {`, INDENTED with tabs. Whole-token labels.
+    for (const m of text.matchAll(/^\s*([a-z][a-z0-9_]*):\s/gm)) {
+        const label = m[1];
+        if (seen.has(label))
+            continue;
+        let g;
+        if ((g = label.match(ST_ADC))) {
+            seen.add(label);
+            // Source: the unit prefix from the name — `adc1_in1…` → adc1, the
+            // single-unit spelling `adc_in0…` → adc.
+            const unit = label.match(/^([a-z]+?\d*)_in/);
+            facts.adc.push({
+                source: unit ? unit[1] : 'adc',
+                channel: Number(label.match(/_(?:in|inp)(\d+)_/)[1]),
+                port: g[2].toUpperCase(),
+                bit: Number(g[3]),
+                pinctrl: label,
+            });
+        }
+        else if ((g = label.match(ST_PWM))) {
+            seen.add(label);
+            facts.pwm.push({
+                source: `tim${g[2]}`,
+                channel: Number(g[3]),
+                port: g[4].toUpperCase(),
+                bit: Number(g[5]),
+                pinctrl: label,
+            });
+        }
+        else if ((g = label.match(ST_PWM_F1))) {
+            seen.add(label);
+            facts.pwm.push({
+                source: `tim${g[2]}`,
+                channel: Number(g[3]),
+                port: g[4].toUpperCase(),
+                bit: Number(g[5]),
+                pinctrl: label,
+            });
+        }
+        else if ((g = label.match(ST_DAC))) {
+            seen.add(label);
+            facts.dac.push({
+                source: `dac${g[2]}`,
+                channel: Number(g[3]),
+                port: g[4].toUpperCase(),
+                bit: Number(g[5]),
+                pinctrl: label,
+            });
+        }
+        else if ((g = label.match(ST_DAC_F1))) {
+            seen.add(label);
+            facts.dac.push({
+                source: 'dac1',
+                channel: Number(g[2]),
+                port: g[3].toUpperCase(),
+                bit: Number(g[4]),
+                pinctrl: label,
+            });
+        }
+        else if ((g = label.match(IMX_GPIO))) {
+            seen.add(label);
+            if (!imxPadToGpio.has(g[1]))
+                imxPadToGpio.set(g[1], { port: g[2], bit: Number(g[3]) });
+        }
+    }
+    // i.MX routes resolve after the join map is complete.
+    for (const m of text.matchAll(/^\s*([a-z][a-z0-9_]*):\s/gm)) {
+        const label = m[1];
+        let g;
+        if ((g = label.match(IMX_ADC))) {
+            const gpio = imxPadToGpio.get(g[1]);
+            if (!gpio || seen.has(label))
+                continue;
+            seen.add(label);
+            facts.adc.push({
+                source: `adc${g[2]}`,
+                channel: Number(g[3]),
+                port: gpio.port,
+                bit: gpio.bit,
+                pinctrl: label,
+            });
+        }
+        else if ((g = label.match(IMX_PWM))) {
+            const gpio = imxPadToGpio.get(g[1]);
+            if (!gpio || seen.has(label))
+                continue;
+            seen.add(label);
+            facts.pwm.push({
+                source: `flexpwm${g[2]}_pwm${g[4]}`,
+                channel: g[3] === 'b' ? 1 : 0,
+                port: gpio.port,
+                bit: gpio.bit,
+                pinctrl: label,
+            });
+        }
+        else if ((g = label.match(IMX_PWM2))) {
+            const gpio = imxPadToGpio.get(g[1]);
+            if (!gpio || seen.has(label))
+                continue;
+            seen.add(label);
+            facts.pwm.push({
+                source: `flexpwm${g[2]}_pwm${g[3]}`,
+                channel: g[4] === 'b' ? 1 : 0,
+                port: gpio.port,
+                bit: gpio.bit,
+                pinctrl: label,
+            });
+        }
+    }
+    return facts;
+}
+/** Parse + shape-validate .cuttlefish/as-built.json; errors name the file. */
+export function parseAsBuiltJson(text, source = '.cuttlefish/as-built.json') {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`${source} is not valid JSON: ${err.message}`);
+    }
+    const file = parsed;
+    if (!file || typeof file !== 'object' || file.version !== 1 || typeof file.board !== 'string'
+        || !file.routes || !Array.isArray(file.routes.adcPins) || !Array.isArray(file.routes.pwmPins)) {
+        throw new Error(`${source} must carry version 1, a board target, and routes.{adcPins,pwmPins}.`);
+    }
+    return file;
+}
+/** Serialize the as-built snapshot (deterministic field order). */
+export function asBuiltJson(board, facts) {
+    const byPin = (a, b) => a.port.localeCompare(b.port) || a.bit - b.bit || a.channel - b.channel;
+    return JSON.stringify({
+        version: 1,
+        board,
+        generatedAt: new Date().toISOString(),
+        routes: {
+            adcPins: [...facts.adc].sort(byPin),
+            pwmPins: [...facts.pwm].sort(byPin),
+            dacPins: [...facts.dac].sort(byPin),
+        },
+    }, null, 1);
+}

package/dist/async/timer-polyfill.js

@@ -59,7 +59,7 @@ static int32_t __tc_timer_add(void (*cb)(void), int32_t ms, bool repeat) {
             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 i + 1;  // 1-based id
         }
     }
     return 0;  // pool full

package/dist/boardgen.d.ts

@@ -0,0 +1,128 @@
+import type { BoardDataEntry } from '@typecad/cuttlefish/board-catalog';
+export interface GeneratedBoard {
+    readonly boardTs: string;
+    readonly boardJson: string;
+    /** The resolved board record (identifier/name/vendor) — for build notes. */
+    readonly board: BoardDataEntry;
+    /** Non-fatal notes from generation — user facts shadowing harvested
+     *  routes (the user won; the harvest said otherwise). */
+    readonly warnings?: readonly string[];
+}
+/** Look up a board variant by qualified target or bare board id. */
+export declare function findBoardData(target: string): BoardDataEntry | undefined;
+/** soc name from a qualified target ('board/soc/qual' → 'soc'). */
+export declare function socOfTarget(target: string): string;
+/**
+ * nRF SAADC AIN→P0-pad map per SoC — [channel, pad] pairs (see the synthesis
+ * block in buildModule for the verification trail). Undefined for SoCs
+ * without a verified map (including every /cpunet variant: the nRF5340
+ * network core declares no SAADC).
+ */
+export declare function nrfSaadcAinPads(soc: string, identifier: string): readonly [number, number][] | undefined;
+/**
+ * ESP32 DAC channel→GPIO pad map per SoC — [channel, pad] pairs, silicon-
+ * fixed (no pinctrl group; the DAC outputs through the RTC IO mux on a fixed
+ * pad). Only the original ESP32 and the ESP32-S2 carry the 8-bit DAC; the
+ * S3/C3/C6/H2 dropped it. Sourced from the HAL's dac_periph.c
+ * (`dac_channel_io_num[]`), like the nRF SAADC table is from the PS.
+ */
+export declare function esp32DacPins(soc: string): readonly [number, number][] | undefined;
+/**
+ * Parse a datasheet pin name into (controller nodelabel, controller-relative
+ * bit) per the soc's naming family — the inverse of the sweep naming:
+ *   nRF      P0.28 / P0_28 → gpio0.28
+ *   RP2040   GP25          → gpio0.25
+ *   ESP32    GPIO9         → gpio0.9 (GPIO32+ → gpio1.x)
+ *   letters  PA5 / PB6     → gpioa.5 / gpiob.6
+ *   flat     GPIO9 (non-esp32 socs, single flat controller) → gpio.9
+ */
+export declare function parsePinName(soc: string, name: string): {
+    controller: string;
+    pin: number;
+} | undefined;
+/**
+ * Build the board module contents from one board record. This is the one
+ * builder for every kind of board: catalog records (from the local overlay
+ * generated off the installed SDK's tree) and contract records (custom PCB
+ * specs) both route through here.
+ */
+/** One board's user-declared facts — the `boards['<target>']` section. */
+export interface UserBoardFacts {
+    adc?: {
+        /** DT nodelabel of the ADC device (default: the board's primary, or 'adc'). */
+        device?: string;
+        channels: {
+            pin: number;
+            channel: number;
+            pinctrl?: string;
+        }[];
+    };
+    pwm?: {
+        /** Static specs — pin→controller/channel. Suppresses the auto nRF matrix. */
+        specs: {
+            pin: number;
+            controller: string;
+            channel: number;
+            pinctrl?: string;
+        }[];
+    };
+    dac?: {
+        device: string;
+        channels: {
+            pin: number;
+            channel: number;
+            resolution?: number;
+        }[];
+    };
+}
+/** The whole cuttlefish.facts.json shape. */
+export interface UserFactsFile {
+    boards: Record<string, UserBoardFacts>;
+}
+/** Parse + shape-validate the facts file; a clear error names the file. */
+export declare function parseUserFactsJson(text: string, source?: string): UserFactsFile;
+/** The section matching a target — the same exact → lowercase → prefix
+ *  leniency findBoardData applies to catalog keys. */
+export declare function userFactsForTarget(file: UserFactsFile | undefined, target: string): UserBoardFacts | undefined;
+export declare function buildModule(entry: BoardDataEntry, userFacts?: UserBoardFacts, factsSuffix?: string, seedWarnings?: readonly string[]): GeneratedBoard;
+/**
+ * Generate the board module contents for a qualified Zephyr board target
+ * ('esp32s3_devkitc/esp32s3/procpu'). Bare SoC names are not targets —
+ * every board resolves through the catalog like any other.
+ */
+export declare function generateBoard(target: string, opts?: {
+    factsJson?: string;
+    asBuiltJson?: string;
+}): GeneratedBoard;
+/**
+ * Generate the board module for a CONTRACT board — a custom PCB with no
+ * Zephyr board record. The contract (exported from a TypeCAD project)
+ * supplies the wired pads by datasheet name and which bus families the PCB
+ * routes; the SoC's bus controller nodelabels come from the INSTALLED
+ * Zephyr tree's soc dtsi (the SDK is the source of truth — a contract build
+ * compiles against that tree).
+ *
+ * Returns a full board module (the transpiler's pin map + chip resolution
+ * read board.json). The caller layers the narrowed board.ts on top, so the
+ * firmware can only touch pads the PCB actually wired.
+ */
+export declare function generateBoardModuleFromContract(opts: {
+    soc: string;
+    zephyrBase: string;
+    /** Wired pad names in the soc's datasheet form (PA5, P0.28, GP25...). */
+    pinNames: readonly string[];
+    /** Functional names to export as aliases of a wired pad (TX → PA9). */
+    padAliases?: readonly {
+        exportName: string;
+        padName: string;
+    }[];
+    /** Which bus families the PCB routes. */
+    peripherals: {
+        i2c: boolean;
+        spi: boolean;
+        uart: boolean;
+    };
+}): {
+    boardTs: string;
+    boardJson: string;
+};