@typecad/framework-zephyr 1.0.0-alpha.10 → 1.0.0-alpha.12

package/dist/toolchain/env-check.js

@@ -0,0 +1,190 @@
+// ---------------------------------------------------------------------------
+// Zephyr environment check — the shared detection behind `cuttlefish doctor`.
+//
+// Mirrors @typecad/arduino-cli's checkArduinoEnv(): gather the impure
+// environment facts once (west presence + version, Zephyr version, board
+// existence), then reduce them to a structured result the doctor (and, later,
+// the build/test gates) can present uniformly. The check is side-effect-free
+// and never throws — it never installs or mutates anything.
+//
+// Two parity checks vs. framework-arduino's doctor:
+//  1. west (the Zephyr build tool) is discoverable + responsive — the direct
+//     analog of "arduino-cli is installed". discoverWest() already confirms
+//     responsiveness via `west --version`; we additionally capture the version
+//     string to report it.
+//  2. the configured board target exists in the Zephyr checkout
+//     ($ZEPHYR_BASE/boards/) — the analog of "the required core is installed".
+//
+// The existing compat-range check (compat.ts) is folded in as a third check so
+// the doctor reports everything through one entry point.
+// ---------------------------------------------------------------------------
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { discoverWest, resetWestDiscoveryCache } from './west-discover.js';
+import { westSpawn } from './west-spawn.js';
+import { detectZephyrVersion, checkZephyrCompat, resolveBoardTarget, } from './compat.js';
+// ---- west probe (impure; isolated + cached + overridable) ------------------
+let cachedProbe;
+/** Clear the west-probe cache (for tests). Also resets discovery cache. */
+export function resetWestProbeCacheForTest() {
+    cachedProbe = undefined;
+    resetWestDiscoveryCache();
+}
+/**
+ * Gather west facts: discover a usable install, then run `west --version`
+ * through it to capture the version. Memoized for the process lifetime (west
+ * installs don't move). Never throws — returns westFound:false on any failure.
+ */
+export function probeWestEnv() {
+    if (cachedProbe)
+        return cachedProbe;
+    const install = discoverWest();
+    const envBase = process.env.ZEPHYR_BASE || undefined;
+    if (!install) {
+        const data = {
+            westFound: false,
+            westVersion: undefined,
+            source: undefined,
+            zephyrBase: envBase,
+        };
+        cachedProbe = data;
+        return data;
+    }
+    // Run `west --version` through the discovered install to capture the version.
+    // discoverWest() already confirmed responsiveness, so a parse failure here is
+    // not "unresponsive" — it just means we couldn't read a version token.
+    let westVersion;
+    try {
+        const inv = westSpawn(['--version'], {
+            encoding: 'utf8',
+            timeout: 15_000,
+            windowsHide: true,
+        });
+        const r = spawnSync(inv.command, inv.args, inv.options);
+        if (r.status === 0) {
+            // inv.options is a generic SpawnSyncOptions (no encoding literal), so
+            // coerce stdout to a string before matching.
+            const out = typeof r.stdout === 'string' ? r.stdout : '';
+            const m = out.match(/v?(\d+\.\d+\.\d+)/);
+            westVersion = m ? m[1] : undefined;
+        }
+    }
+    catch {
+        // westSpawn throws only when discovery fails — but discovery already
+        // succeeded (install is non-null). Defensive: treat as no version read.
+        westVersion = undefined;
+    }
+    const data = {
+        westFound: true,
+        westVersion,
+        source: install.source,
+        zephyrBase: envBase ?? install.zephyrBase,
+    };
+    cachedProbe = data;
+    return data;
+}
+// ---- board existence (pure-ish fs probe) -----------------------------------
+/**
+ * Does `boardId` exist as a board directory in the Zephyr checkout? Checks the
+ * HWMv2 vendor layout used by Zephyr 4.x: $ZEPHYR_BASE/boards/<vendor>/<boardId>.
+ * Returns true/false when determinable; undefined when the base is unknown or
+ * the boards/ tree can't be read (so callers never fail on an inconclusive
+ * lookup — they just skip the board check).
+ */
+export function boardExistsInCheckout(boardId, zephyrBase) {
+    if (!zephyrBase)
+        return undefined;
+    const boards = join(zephyrBase, 'boards');
+    try {
+        const entries = readdirSync(boards, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory() && existsSync(join(boards, entry.name, boardId))) {
+                return true;
+            }
+        }
+        return false;
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---- main entry point -------------------------------------------------------
+/**
+ * Verify the environment can build for `buildTarget`. Cheap and
+ * side-effect-free: discovers west, reads the Zephyr version, checks the compat
+ * range, and — when a target is configured — verifies the board exists in the
+ * checkout. Reports what (if anything) is wrong.
+ *
+ * - If `buildTarget` is undefined/empty, the board check is skipped (not a
+ *   failure), mirroring Arduino's no-FQBN path.
+ * - Never installs anything. Never mutates the user environment.
+ * - Never throws — always returns a result. Callers decide how to react.
+ *
+ * `options` is for-test only (injects fake probe data / board lookup).
+ */
+export function checkZephyrEnv(buildTarget, options) {
+    const probe = options?.fakeWestProbe ?? probeWestEnv();
+    const boardLookup = options?.fakeBoardExists ?? boardExistsInCheckout;
+    const zephyrVersion = detectZephyrVersion();
+    const compat = checkZephyrCompat(zephyrVersion);
+    const resolvedBoardTarget = buildTarget ? resolveBoardTarget(buildTarget, zephyrVersion) : undefined;
+    const boardId = resolvedBoardTarget ? resolvedBoardTarget.split('/')[0] : undefined;
+    const boardTargetSupported = boardId !== undefined ? boardLookup(boardId, probe.zephyrBase) : undefined;
+    const check = {
+        westFound: probe.westFound,
+        westVersion: probe.westVersion,
+        westSource: probe.source,
+        zephyrBase: probe.zephyrBase,
+        zephyrVersion,
+        compatRange: compat.range,
+        compatStatus: compat.status,
+        buildTarget,
+        resolvedBoardTarget,
+        boardTargetSupported,
+    };
+    // 1. west (the build tool) missing entirely — nothing else can run.
+    if (!probe.westFound) {
+        return {
+            ok: false,
+            reason: 'west-not-found',
+            check,
+            messages: [
+                "west (the Zephyr build tool) was not found.",
+                "  Run the typeCAD Zephyr installer, activate an existing Zephyr venv,",
+                "  set ZEPHYR_BASE to a Zephyr SDK root, or `pip install west`.",
+            ],
+            fixCommand: undefined,
+        };
+    }
+    // 2. west healthy but the Zephyr RTOS is outside the supported range.
+    if (compat.status === 'out-of-range') {
+        return {
+            ok: false,
+            reason: 'zephyr-out-of-range',
+            check,
+            messages: [
+                `Zephyr ${zephyrVersion} is outside the supported range (${compat.range}) for @typecad/framework-zephyr.`,
+                "  Set ZEPHYR_BASE to a compatible Zephyr checkout, or install one via '@typecad/zephyr-installer'.",
+            ],
+            fixCommand: undefined,
+        };
+    }
+    // 3. west + version OK — only check the board when a target is configured and
+    // the lookup was able to answer. A missing/absent target is not a board
+    // problem; an inconclusive lookup (no base) is reported as a skip, not a fail.
+    if (buildTarget && boardTargetSupported === false) {
+        return {
+            ok: false,
+            reason: 'board-not-supported',
+            check,
+            messages: [
+                `Board target '${resolvedBoardTarget}' was not found in this Zephyr checkout` +
+                    (probe.zephyrBase ? ` (${join(probe.zephyrBase, 'boards')}).` : '.'),
+                "  Check the board id, or run `west boards` to list boards in this checkout.",
+            ],
+            fixCommand: 'west boards',
+        };
+    }
+    return { ok: true, check };
+}

package/dist/toolchain/index.js

@@ -185,12 +185,17 @@ export const Toolchain = {
         // for either driver. Thread a non-default profile here only if a future
         // board carries a display node under a different nodelabel.
         const displayProfile = usesDisplay ? DEFAULT_ZEPHYR_DISPLAY_PROFILE : undefined;
+        // Touch controller kind comes from which DT nodelabel the emitted adapter
+        // references (FT6336U on I2C, XPT2046 on the display's SPI bus).
+        const usesTouch = uses('ft6336u') || uses('touch_');
+        const usesXpt = uses('xpt2046');
         const overlay = generateOverlay(chip, {
             usesI2c: uses('i2c_'),
             usesSpi: uses('spi_'),
             usesUart: uses('uart_'),
             usesDisplay,
-            usesTouch: uses('ft6336u') || uses('touch_'),
+            usesTouch: usesTouch || usesXpt,
+            touchController: usesXpt ? 'xpt2046' : 'ft6336u',
         }, displayProfile);
         const overlayDir = join(projectRoot, 'boards');
         mkdirSync(overlayDir, { recursive: true });
@@ -274,23 +279,48 @@ export const Toolchain = {
                     backlightPin: typeof dispCfg.backlightPin === 'number' ? dispCfg.backlightPin : undefined,
                 }
                 : undefined;
-            // Extract touch pin wiring (irq/resetPin/sda/scl) from the config
-            // display.touch section so the DT overlay wires the I2C bus + touch node.
+            // Extract touch pin wiring from the config display.touch section so the
+            // DT overlay wires the bus + touch node. I2C (FT6336U) carries
+            // irq/resetPin/sda/scl; SPI (XPT2046) carries irq/cs + the calibration
+            // range the xptek,xpt2046 binding requires.
             const touchCfg = dispCfg?.touch;
-            const touchWiring = touchCfg
+            const isXpt = touchCfg?.library === 'XPT2046_Touchscreen';
+            const touchCal = touchCfg?.calibration;
+            const num = (v) => (typeof v === 'number' ? v : undefined);
+            let touchWiring = touchCfg
                 ? {
-                    irq: typeof touchCfg.irq === 'number' ? touchCfg.irq : undefined,
-                    resetPin: typeof touchCfg.resetPin === 'number' ? touchCfg.resetPin : undefined,
-                    sda: typeof touchCfg.sda === 'number' ? touchCfg.sda : undefined,
-                    scl: typeof touchCfg.scl === 'number' ? touchCfg.scl : undefined,
+                    controller: isXpt ? 'xpt2046' : 'ft6336u',
+                    irq: num(touchCfg.irq),
+                    resetPin: num(touchCfg.resetPin),
+                    sda: num(touchCfg.sda),
+                    scl: num(touchCfg.scl),
+                    cs: num(touchCfg.cs),
+                    calibration: touchCal
+                        ? {
+                            xMin: num(touchCal.xMin) ?? 0,
+                            xMax: num(touchCal.xMax) ?? 4095,
+                            yMin: num(touchCal.yMin) ?? 0,
+                            yMax: num(touchCal.yMax) ?? 4095,
+                        }
+                        : undefined,
+                    minPressure: num(touchCfg.minPressure),
                 }
                 : undefined;
+            // Touch controller kind for Kconfig (bus driver selection) and the DT
+            // node shape: from the config when available, else from the DT nodelabel
+            // the emitted adapter references. Forced onto touchWiring so a source
+            // scan match without a config section still emits the right node.
+            const usesXpt = isXpt || uses('xpt2046');
+            if (usesXpt) {
+                touchWiring = { controller: 'xpt2046', ...(touchWiring ?? {}) };
+            }
             const overlay = generateOverlay(chip, {
                 usesI2c: uses('i2c_'),
                 usesSpi: uses('spi_'),
                 usesUart: uses('uart_'),
                 usesDisplay,
-                usesTouch: uses('ft6336u') || uses('touch_'),
+                usesTouch: uses('ft6336u') || uses('touch_') || usesXpt,
+                touchController: usesXpt ? 'xpt2046' : 'ft6336u',
                 psram: o.psram,
             }, displayProfile, wiring, touchWiring);
             const overlayDir = join(projectRoot, 'boards');

package/dist/toolchain/scaffold.js

@@ -85,6 +85,9 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
     const usage = {
         usesAdc: uses('adc_'),
         usesPwm: uses('pwm_'),
+        usesDac: uses('dac_') || uses('__tc_dac'),
+        usesFS: uses('__tc_fs'),
+        usesHwtimer: uses('counter_') || uses('__tc_hw'),
         usesI2c: uses('i2c_'),
         usesSpi: uses('spi_'),
         usesUart: uses('uart_'),
@@ -125,8 +128,10 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
         '',
         'project(zephyr_app)',
         '',
-        '# Collect cuttlefish-emitted sources.',
-        'file(GLOB app_sources src/*.cpp src/*.c)',
+        '# Collect cuttlefish-emitted sources. CONFIGURE_DEPENDS makes CMake re-',
+        '# check the glob when the source set changes (e.g. the transpiler removes',
+        '# a stale entry), instead of linking a file list from the last configure.',
+        'file(GLOB app_sources CONFIGURE_DEPENDS src/*.cpp src/*.c)',
         '',
         'target_sources(app PRIVATE ${app_sources})',
         // When PSRAM is configured, define BOARD_HAS_PSRAM so the UI runtime's

package/dist/toolchain/west-discover.d.ts

@@ -4,15 +4,21 @@
  * `pythonExecutable -m west`.
  */
 export interface WestInstall {
-    mode: 'launcher' | 'module';
+    mode: 'launcher' | 'module' | 'micromamba';
     /** Absolute path to a `west` launcher (mode 'launcher') or undefined. */
     westExecutable?: string;
     /** Absolute path to a Python interpreter with west installed (mode 'module'). */
     pythonExecutable?: string;
     /** Absolute path to the Zephyr SDK root (for $ZEPHYR_BASE), if found. */
     zephyrBase?: string;
+    /** mode 'micromamba': path to the micromamba binary (for `micromamba run -n …`). */
+    micromambaExe?: string;
+    /** mode 'micromamba': the conda env name (default 'zephyr'). */
+    envName?: string;
+    /** mode 'micromamba': MAMBA_ROOT_PREFIX, injected so micromamba finds its envs. */
+    mambaRootPrefix?: string;
     /** Which discovery strategy found this install. */
-    source: 'path' | 'zephyr-base-venv' | 'well-known' | 'system-python';
+    source: 'path' | 'zephyr-base-venv' | 'well-known' | 'system-python' | 'micromamba';
 }
 /** True if `dir` looks like a Zephyr SDK root: has CMakeLists.txt and the
  *  kernel header. */
@@ -21,6 +27,7 @@ export declare function discoverFromPath(): WestInstall | null;
 /** The canonical Zephyr workspace layout puts the venv beside the SDK:
  *  <workspace>/{.venv, zephyr}. So ${ZEPHYR_BASE}/../.venv is the venv. */
 export declare function discoverFromZephyrBase(): WestInstall | null;
+export declare function discoverFromMicromamba(envName?: string): WestInstall | null;
 /** Candidate Zephyr workspace directories. Each may contain both `.venv/`
  *  and `zephyr/` (the SDK). Exported for test injection. */
 export declare function wellKnownWorkspaces(): string[];
@@ -34,7 +41,8 @@ export declare function resetWestDiscoveryCache(): void;
  * Try each discovery strategy in order. The first usable install wins.
  * Result is memoized for the process lifetime (west installs don't move).
  *
- * Order: PATH → $ZEPHYR_BASE venv → well-known workspaces → system pythons.
+ * Order: PATH → $ZEPHYR_BASE venv → micromamba env → well-known workspaces →
+ * system pythons.
  * Returns null when no usable west install is found.
  */
 export declare function discoverWest(): WestInstall | null;

package/dist/toolchain/west-discover.js

@@ -10,14 +10,16 @@
 // Discovery cascade (first usable wins):
 //   1. `west` already on PATH (env already activated / global install).
 //   2. $ZEPHYR_BASE venv: ${ZEPHYR_BASE}/../.venv/<python> -m west.
-//   3. Well-known workspace layouts: ~/zephyrproject/.venv, /opt/zephyrproject/.
+//   3. micromamba env from @typecad/zephyr-installer (invoked via `micromamba run`,
+//      so cuttlefish builds work with NO manual activation).
+//   4. Well-known workspace layouts: ~/zephyrproject/.venv, /opt/zephyrproject/.
 //      venv, etc.
-//   4. System pythons (`python`, `python3`, `py`) via `-m west`.
+//   5. System pythons (`python`, `python3`, `py`) via `-m west`.
 //
 // Leaner than the ESP-IDF equivalent: west needs no env sourcing (no 15s
 // export.sh) — only the right interpreter + ZEPHYR_BASE.
 // ---------------------------------------------------------------------------
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
@@ -65,9 +67,12 @@ export function isZephyrBase(dir) {
 }
 // ── Strategy 1: `west` on PATH ──────────────────────────────────────────────
 export function discoverFromPath() {
+    // shell only on Windows (where.exe resolution through cmd) — an args array
+    // with shell: true triggers Node's DEP0190 deprecation warning on Linux/
+    // macOS, where `which` is a plain executable that needs no shell.
     const which = spawnSync(IS_WIN ? 'where' : 'which', ['west'], {
         encoding: 'utf8',
-        shell: true,
+        shell: IS_WIN,
         windowsHide: true,
     });
     if (which.status !== 0)
@@ -106,7 +111,77 @@ export function discoverFromZephyrBase() {
         source: 'zephyr-base-venv',
     };
 }
-// ── Strategy 3: well-known workspace layouts ───────────────────────────────
+// ── Strategy 3: micromamba env (the @typecad/zephyr-installer install) ─────
+// Locate the micromamba binary + root prefix. The installer downloads
+// micromamba to $MAMBA_ROOT_PREFIX/bin (POSIX) or Library/bin (Windows); the
+// root defaults to ~/micromamba. Returns null if the binary isn't present
+// (the installer hasn't run on this machine).
+function findMicromamba() {
+    const root = process.env.MAMBA_ROOT_PREFIX || join(homedir(), 'micromamba');
+    const exe = IS_WIN
+        ? join(root, 'Library', 'bin', 'micromamba.exe')
+        : join(root, 'bin', 'micromamba');
+    return existsSync(exe) ? { exe, rootPrefix: root } : null;
+}
+/**
+ * The micromamba env created by `@typecad/zephyr-installer`. The env's west
+ * lives at envs/<name>/bin/west (POSIX) or Scripts/west.exe (Windows). Found
+ * installs are invoked via `micromamba run -n <name> west …` (see
+ * west-spawn.ts), which sets up the env's full PATH (cmake/ninja/dtc) AND runs
+ * the activation hook (ZEPHYR_BASE / ZEPHYR_SDK_INSTALL_DIR) — so cuttlefish
+ * builds work with NO manual `micromamba activate`. This is what makes a fresh
+ * `cuttlefish build` succeed in any project without the user activating.
+ *
+ * Env name defaults to "zephyr"; override via TYPECAD_ZEPHYR_ENV. File-check
+ * based (no spawn) so it's cheap to run on every cuttlefish invocation.
+ */
+/** Read a TYPECAD_ZEPHYR_* value from the installer-written env-vars file in
+ *  a micromamba env. Handles .sh (export VAR="val"), .bat (set "VAR=val"),
+ *  and .ps1 ($env:VAR = "val"). Returns undefined if absent/unreadable. */
+function readMicromambaEnvVar(envDir, varName) {
+    const candidates = IS_WIN
+        ? [join(envDir, 'etc', 'conda', 'env-vars.ps1'), join(envDir, 'etc', 'conda', 'env-vars.bat')]
+        : [join(envDir, 'etc', 'conda', 'env-vars.sh')];
+    for (const f of candidates) {
+        if (!existsSync(f))
+            continue;
+        try {
+            const text = readFileSync(f, 'utf8');
+            // .sh/.ps1: VAR = "value" (quoted value after =).
+            let m = text.match(new RegExp(`${varName}\\s*=\\s*"([^"]+)"`));
+            if (m)
+                return m[1];
+            // .bat: set "VAR=value" (value after VAR= inside quotes).
+            m = text.match(new RegExp(`${varName}=([^"\\r\\n]+)"`));
+            if (m)
+                return m[1].trim();
+        }
+        catch { /* ignore unreadable */ }
+    }
+    return undefined;
+}
+export function discoverFromMicromamba(envName = process.env.TYPECAD_ZEPHYR_ENV || 'zephyr') {
+    const mm = findMicromamba();
+    if (!mm)
+        return null;
+    const envDir = join(mm.rootPrefix, 'envs', envName);
+    const westExe = join(envDir, IS_WIN ? 'Scripts' : 'bin', IS_WIN ? 'west.exe' : 'west');
+    if (!existsSync(envDir) || !existsSync(westExe))
+        return null;
+    // Read ZEPHYR_BASE from the installer's env-vars so the compat check (and
+    // anything else in the cuttlefish process) can detect the Zephyr version
+    // WITHOUT activation — micromamba run sets it only inside the west subprocess.
+    const zb = readMicromambaEnvVar(envDir, 'TYPECAD_ZEPHYR_BASE');
+    return {
+        mode: 'micromamba',
+        micromambaExe: mm.exe,
+        envName,
+        mambaRootPrefix: mm.rootPrefix,
+        zephyrBase: zb && isZephyrBase(zb) ? zb : undefined,
+        source: 'micromamba',
+    };
+}
+// ── Strategy 4: well-known workspace layouts ───────────────────────────────
 /** Candidate Zephyr workspace directories. Each may contain both `.venv/`
  *  and `zephyr/` (the SDK). Exported for test injection. */
 export function wellKnownWorkspaces() {
@@ -143,7 +218,7 @@ export function discoverFromWellKnown(workspaces = wellKnownWorkspaces()) {
     }
     return null;
 }
-// ── Strategy 4: system pythons via `-m west` ────────────────────────────────
+// ── Strategy 5: system pythons via `-m west` ────────────────────────────────
 /** Candidate system Python interpreters to probe with `-m west`. */
 export function systemPythons() {
     if (IS_WIN)
@@ -173,7 +248,8 @@ export function resetWestDiscoveryCache() {
  * Try each discovery strategy in order. The first usable install wins.
  * Result is memoized for the process lifetime (west installs don't move).
  *
- * Order: PATH → $ZEPHYR_BASE venv → well-known workspaces → system pythons.
+ * Order: PATH → $ZEPHYR_BASE venv → micromamba env → well-known workspaces →
+ * system pythons.
  * Returns null when no usable west install is found.
  */
 export function discoverWest() {
@@ -182,6 +258,7 @@ export function discoverWest() {
     const strategies = [
         discoverFromPath,
         discoverFromZephyrBase,
+        discoverFromMicromamba,
         discoverFromWellKnown,
         discoverFromSystemPython,
     ];

package/dist/toolchain/west-spawn.js

@@ -98,6 +98,21 @@ export function westSpawn(westArgs, baseOptions) {
     // Strip `shell` if present — we pass absolute paths / known commands, and
     // an explicit shell changes arg-quoting semantics on Windows.
     const { shell: _drop, ...optsWithoutShell } = baseOptions;
+    if (install.mode === 'micromamba' && install.micromambaExe) {
+        // `micromamba run -n <env> west …` sets up the env's full PATH
+        // (cmake/ninja/dtc) and runs the activation hook (ZEPHYR_BASE /
+        // ZEPHYR_SDK_INSTALL_DIR), so cuttlefish builds work WITHOUT the user
+        // activating the env. Inject MAMBA_ROOT_PREFIX so micromamba finds envs.
+        const mmEnv = { ...env };
+        if (install.mambaRootPrefix)
+            mmEnv.MAMBA_ROOT_PREFIX = install.mambaRootPrefix;
+        return {
+            command: install.micromambaExe,
+            args: ['run', '-n', install.envName ?? 'zephyr', 'west', ...westArgs],
+            options: { ...optsWithoutShell, env: mmEnv },
+            install,
+        };
+    }
     if (install.mode === 'launcher' && install.westExecutable) {
         return {
             command: install.westExecutable,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typecad/framework-zephyr",
-  "version": "1.0.0-alpha.10",
+  "version": "1.0.0-alpha.12",
   "description": "TypeCAD framework package for the Zephyr RTOS — west/CMake build, devicetree-driven GPIO",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,11 +38,11 @@
     "test:hw:mqtt": "cd ../../tests/hardware && npm exec -- cuttlefish-test mqtt-client.test.ts"
   },
   "dependencies": {
-    "@typecad/cuttlefish": "1.0.0-alpha.10"
+    "@typecad/cuttlefish": "1.0.0-alpha.12"
   },
   "devDependencies": {
-    "@typecad/expect": "1.0.0-alpha.10",
-    "@typecad/board-xiao-nrf52840": "1.0.0-alpha.10",
+    "@typecad/expect": "1.0.0-alpha.12",
+    "@typecad/board-xiao-nrf52840": "1.0.0-alpha.12",
     "typescript": "^5.7.3"
   },
   "license": "MIT",

package/src/chips/esp32.ts

@@ -59,4 +59,16 @@ export const ESP32_DEVKITC: ZephyrChipDescriptor = {
   // the ESP32 is AMP (dual-image procpu/appcpu), not SMP, by default — so the
   // dependency is satisfied. Omitted on radioless targets.
   wifi: { supported: true },
+  // DAC: the ESP32 has two 8-bit DAC channels on GPIO25 (channel 1) and GPIO26
+  // (channel 2). The Zephyr esp32 DAC driver (drivers/dac/dac_esp32.c) exposes
+  // them via the `dac0` node; the lowering emits dac_channel_setup +
+  // dac_write_value against DEVICE_DT_GET(DT_NODELABEL(dac0)). The overlay
+  // enables the node when the program uses dac.*. ESP32-S3 has no DAC.
+  dac: {
+    device: 'dac0',
+    channels: [
+      { pin: 25, channel: 1, resolution: 8 },
+      { pin: 26, channel: 2, resolution: 8 },
+    ],
+  },
 };

package/src/chips/types.ts

@@ -101,6 +101,19 @@ export interface ZephyrAdcChannel {
   readonly channel: number;
 }
 
+/**
+ * A DAC channel: which DAC output a given HAL pin maps to. The lowering emits
+ * `dac_channel_setup` + `dac_write_value` against the DAC device node.
+ */
+export interface ZephyrDacChannel {
+  /** GPIO number (matches the HAL op `pin` field). */
+  readonly pin: number;
+  /** DAC channel index (ESP32: GPIO25 → 1, GPIO26 → 2). */
+  readonly channel: number;
+  /** DAC resolution in bits (ESP32 DAC is 8-bit). */
+  readonly resolution: number;
+}
+
 /**
  * Pure-data descriptor for a Zephyr board + its SoC's peripheral layout.
  */
@@ -151,8 +164,24 @@ export interface ZephyrChipDescriptor {
     /** ADC resolution in bits. */
     readonly resolution: number;
   };
+  /**
+   * DAC: the DAC device node label + the pin→channel map. Present only on chips
+   * with a DAC (ESP32 has 2 channels on GPIO25/26; ESP32-S3 and nRF52840 have
+   * none). Read by profileDiagnostics to flag dac.* usage on chips without it.
+   */
+  readonly dac?: {
+    readonly device: string;
+    readonly channels: readonly ZephyrDacChannel[];
+  };
   /** Watchdog node label, e.g. 'wdt0'. */
   readonly wdt?: { readonly nodeLabel: string };
+  /**
+   * Hardware timers exposed as Zephyr counter devices. `instance` (the HAL
+   * hwtimer.* op's instance index) maps to `controllers[instance].nodeLabel`.
+   * Omit on chips whose counter nodes are kernel-owned or unavailable; the
+   * lowering then lowers to a comment and profileDiagnostics flags usage.
+   */
+  readonly hwtimer?: { readonly controllers: readonly ZephyrBusController[] };
   /**
    * WiFi capability marker. Present only on chips with a WiFi radio (ESP32-S3).
    * Read by profileDiagnostics to flag wifi.* usage on chips without a radio.

package/src/chips/xiao-ble.ts

@@ -61,4 +61,10 @@ export const XIAO_BLE: ZephyrChipDescriptor = {
     ],
   },
   wdt: { nodeLabel: 'wdt0' },
+  // Hardware timer: nRF RTC1 is the free counter (RTC0 is kernel-owned by the
+  // softdevice/clock driver). The hwtimer lowering drives it as a Zephyr
+  // counter device (counter_start/stop + a top-value alarm for set_frequency).
+  // Verified against the nRF52840 SoC dtsi (rtc0/rtc1 nodes). The kernel uses
+  // RTC0 for the system tick; RTC1 is available for application use.
+  hwtimer: { controllers: [{ nodeLabel: 'rtc1' }] },
 };