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

package/dist/toolchain/scaffold.d.ts

@@ -1,6 +1,15 @@
 /** Write a file only if the content differs from the existing file.
  *  Returns true when the file was written (content changed or file was new). */
 export declare function writeIfChanged(filePath: string, content: string): boolean;
+/**
+ * Append cuttlefish library packages' devicetree overlay fragments to the
+ * generated overlay. Library entries come from the transpiler's libraries.json
+ * sidecar (next to the emitted sources) and are already gated on the
+ * library's include token appearing in the emitted sources — no re-detection.
+ * Fragments merge after the framework overlay so library nodes (e.g.
+ * @typecad/zephyr-esp32s3-rgb's WS2812 node on I2S0) layer over it.
+ */
+export declare function appendLibraryOverlayFragments(overlay: string, projectRoot: string): string;
 /**
  * Emit the Zephyr application skeleton around the generated src/main.cpp.
  *

package/dist/toolchain/scaffold.js

@@ -9,6 +9,9 @@
 import { writeFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { resolveKconfigFragments } from '../dt-config/kconfig.js';
+import { scanSensorParts } from './index.js';
+import { readCuttlefishLibrarySidecar } from '@typecad/cuttlefish/library-packages';
+import { SENSOR_PART_INFO } from '@typecad/hal';
 /** Write a file only if the content differs from the existing file.
  *  Returns true when the file was written (content changed or file was new). */
 export function writeIfChanged(filePath, content) {
@@ -57,6 +60,31 @@ function readEmittedSources(srcDir) {
     }
     return out;
 }
+/**
+ * Append cuttlefish library packages' devicetree overlay fragments to the
+ * generated overlay. Library entries come from the transpiler's libraries.json
+ * sidecar (next to the emitted sources) and are already gated on the
+ * library's include token appearing in the emitted sources — no re-detection.
+ * Fragments merge after the framework overlay so library nodes (e.g.
+ * @typecad/zephyr-esp32s3-rgb's WS2812 node on I2S0) layer over it.
+ */
+export function appendLibraryOverlayFragments(overlay, projectRoot) {
+    let out = overlay;
+    for (const entry of readCuttlefishLibrarySidecar(join(projectRoot, 'src'))) {
+        if (!entry.overlay)
+            continue;
+        try {
+            const fragment = readFileSync(entry.overlay, 'utf8').trim();
+            if (fragment.length > 0) {
+                out += (out.endsWith('\n') ? '' : '\n') + '\n' + fragment + '\n';
+            }
+        }
+        catch {
+            // best-effort; a missing fragment surfaces as a DT error
+        }
+    }
+    return out;
+}
 /**
  * Emit the Zephyr application skeleton around the generated src/main.cpp.
  *
@@ -97,17 +125,28 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
         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_'),
+        // The __tc_<bus> alternative matches the shim's state block — a program
+        // that only calls begin() emits `(void)__tc_i2c1_dev;` (no driver API
+        // call yet), but the shim still declared DEVICE_DT_GET(DT_NODELABEL(...))
+        // so the overlay must enable the node or the device symbol is missing.
+        usesI2c: uses('i2c_') || uses('__tc_i2c'),
+        // DT-bound sensor parts: the __tc_sensor_* state references and the
+        // sensor_sample_fetch/sensor_channel_get calls both carry the token.
+        usesSensor: uses('sensor_') || uses('__tc_sensor'),
+        usesFloatFormat: /%[-0-9.]*[eEfFgG]/.test(src),
+        usesSpi: uses('spi_') || uses('__tc_spi'),
+        usesUart: uses('uart_') || uses('__tc_uart'),
+        // USB CDC serial: every usb.* lowering calls into the __tc_usb<N>_* shim
+        // (device + init helper emitted under usesUsb).
+        usesUsb: uses('__tc_usb'),
+        // STM32F4 DBGMCU keep-SWD-alive init present (emitted for stm32f4 socs).
+        usesStm32DebugSleep: uses('__tc_stm32_dbgmcu'),
         usesWdt: uses('wdt_'),
         usesBle: uses('bt_') || uses('bt_gatt') || uses('bt_le_'),
         usesDisplay: uses('display_write') || uses('display_init') || uses('display_fill_rect') || uses('__tc_display_dev') || uses('CuttlefishDisplayTarget'),
         usesTouch: uses('ft6336u') || uses('touch_'),
-        // Power tokens: k_sleep + pm_state_force / PM_STATE_* (what power.ts emits).
-        // The old `power_` token matched nothing the power HAL emits and collides
-        // with tx_power_dbm — removed.
-        usesPower: uses('pm_') || uses('k_sleep') || uses('PM_STATE_'),
+        // (The power HAL is removed; its former pm_/k_sleep token scan is gone —
+        // nothing here must match tx_power_dbm's `power` substring.)
         usesWifi: uses('wifi_') || uses('net_mgmt') || uses('conn_mgr'),
         // HTTP: the __tc_http_* shim + http_client_req + getaddrinfo. The '_'-anchored
         // 'http_' token matches __tc_http_* and http_client_req (the core HTTP lib
@@ -138,6 +177,12 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
         '# Auto-generated by @typecad/framework-zephyr from cuttlefish.config.ts.',
         'cmake_minimum_required(VERSION 3.20.0)',
         '',
+        '# The app is its own board root: MCU-only targets generate an out-of-tree',
+        '# custom board under boards/typecad/<name>/ that Zephyr must discover.',
+        '# Harmless when boards/ holds only .overlay files (BOARD_ROOT just needs',
+        '# the directory to exist).',
+        'list(APPEND BOARD_ROOT ${CMAKE_CURRENT_SOURCE_DIR})',
+        '',
         'find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})',
         '',
         'project(zephyr_app)',
@@ -202,6 +247,38 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
             continue;
         prjConf.push(`${sym}=${val}`);
     }
+    // ── Cuttlefish library packages ─────────────────────────────────────────
+    // Libraries the program imports (recorded in the transpiler's libraries.json
+    // sidecar, next to the emitted sources) contribute their manifest's kconfig
+    // lines — e.g. @typecad/zephyr-esp32s3-rgb contributes CONFIG_LED_STRIP.
+    // Sidecar entries are already gated on the library's include token
+    // appearing in the emitted sources, so no re-detection here. User
+    // zephyr.kconfig overrides still win.
+    const libraryEntries = readCuttlefishLibrarySidecar(srcDir);
+    if (libraryEntries.length > 0) {
+        prjConf.push('', '# Library packages (cuttlefish.library.json contributions).');
+        for (const entry of libraryEntries) {
+            for (const line of entry.kconfig) {
+                const sym = line.split('=')[0];
+                if (userKconfig && sym !== undefined && userKconfig.hasOwnProperty(sym))
+                    continue;
+                prjConf.push(line);
+            }
+        }
+    }
+    // Per-part Kconfig exceptions: catalog parts whose driver is NOT default-y
+    // on its DT node carry extra lines here (empty today — every in-tree sensor
+    // driver lights up from the node; the path exists so the first exception
+    // found by the generator has somewhere to go).
+    const sensorParts = scanSensorParts(src);
+    if (sensorParts.length > 0) {
+        const extra = [...new Set(sensorParts.flatMap((sp) => SENSOR_PART_INFO[sp.part]?.kconfig ?? []))];
+        if (extra.length > 0) {
+            prjConf.push('', '# Sensor part Kconfig (catalog exceptions).');
+            for (const line of extra)
+                prjConf.push(line);
+        }
+    }
     // Emit user-specified Kconfig from cuttlefish.config.ts zephyr.kconfig.
     // These override any matching auto-detected symbol (skipped above).
     if (userKconfig) {

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

@@ -9,8 +9,11 @@ export interface WestInstall {
     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. */
+    /** Absolute path to the Zephyr workspace (for $ZEPHYR_BASE), if found. */
     zephyrBase?: string;
+    /** Absolute path to the Zephyr SDK install dir (hosttools/openocd lives
+     *  there), if found — used to put the SDK's openocd on the flash PATH. */
+    sdkInstallDir?: string;
     /** mode 'micromamba': path to the micromamba binary (for `micromamba run -n …`). */
     micromambaExe?: string;
     /** mode 'micromamba': the conda env name (default 'zephyr'). */
@@ -27,6 +30,10 @@ 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;
+/** The installer-written ZEPHYR_BASE of the micromamba env, fs-only (no
+ *  spawn) — the cheap probe shared by board-catalog overlay discovery.
+ *  Undefined when the installer env or its env-vars file is absent. */
+export declare function micromambaZephyrBase(envName?: string): string | undefined;
 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. */

package/dist/toolchain/west-discover.js

@@ -42,13 +42,14 @@ function pythonRunsWest(exe) {
         return false;
     }
 }
-/** True if `cmd` runs `west --version` successfully. */
+/** True if `cmd` runs `west --version` successfully. `cmd` comes from
+ * `where`/`which` output — a venv launcher (west.exe) or script path, spawned
+ * without a shell like every other command in this module. */
 function westOnPath(cmd) {
     try {
         const r = spawnSync(cmd, ['--version'], {
             encoding: 'utf8',
             timeout: 15_000,
-            shell: IS_WIN,
             windowsHide: true,
         });
         return r.status === 0;
@@ -67,12 +68,11 @@ 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.
+    // No shell: `where`/`which` are plain executables Node resolves from PATH
+    // (where.exe is a real PE, not a cmd builtin), and an args array with a
+    // truthy shell triggers Node's DEP0190 deprecation warning.
     const which = spawnSync(IS_WIN ? 'where' : 'which', ['west'], {
         encoding: 'utf8',
-        shell: IS_WIN,
         windowsHide: true,
     });
     if (which.status !== 0)
@@ -160,6 +160,17 @@ function readMicromambaEnvVar(envDir, varName) {
     }
     return undefined;
 }
+/** The installer-written ZEPHYR_BASE of the micromamba env, fs-only (no
+ *  spawn) — the cheap probe shared by board-catalog overlay discovery.
+ *  Undefined when the installer env or its env-vars file is absent. */
+export function micromambaZephyrBase(envName = process.env.TYPECAD_ZEPHYR_ENV || 'zephyr') {
+    const mm = findMicromamba();
+    if (!mm)
+        return undefined;
+    const envDir = join(mm.rootPrefix, 'envs', envName);
+    const zb = readMicromambaEnvVar(envDir, 'TYPECAD_ZEPHYR_BASE');
+    return zb && isZephyrBase(zb) ? zb : undefined;
+}
 export function discoverFromMicromamba(envName = process.env.TYPECAD_ZEPHYR_ENV || 'zephyr') {
     const mm = findMicromamba();
     if (!mm)
@@ -172,12 +183,14 @@ export function discoverFromMicromamba(envName = process.env.TYPECAD_ZEPHYR_ENV
     // 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');
+    const sdk = readMicromambaEnvVar(envDir, 'TYPECAD_ZEPHYR_SDK_INSTALL_DIR');
     return {
         mode: 'micromamba',
         micromambaExe: mm.exe,
         envName,
         mambaRootPrefix: mm.rootPrefix,
         zephyrBase: zb && isZephyrBase(zb) ? zb : undefined,
+        sdkInstallDir: sdk && existsSync(sdk) ? sdk : undefined,
         source: 'micromamba',
     };
 }

package/dist/toolchain/west-spawn.js

@@ -14,7 +14,8 @@
 // (find_package(Zephyr) needs it). west's prj.conf/CMakeLists are found via
 // the project dir regardless.
 // ---------------------------------------------------------------------------
-import { dirname } from 'node:path';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
 import { discoverWest } from './west-discover.js';
 /**
  * The Scripts/ (Windows) or bin/ (POSIX) directory of the venv the discovered
@@ -41,8 +42,19 @@ export function buildEnv(install) {
     if (install.zephyrBase && !env.ZEPHYR_BASE) {
         env.ZEPHYR_BASE = install.zephyrBase;
     }
-    const bin = venvBinDir(install);
-    if (bin) {
+    // SWD flashing (`zephyr.runner: 'openocd'`): west's openocd runner resolves
+    // a bare `openocd` from PATH. The Zephyr SDK ships it under
+    // hosttools/openocd/bin (the SDK's own setup.cmd puts that dir on PATH for
+    // activated terminals) — do the same for spawned west processes so ST-Link
+    // flashing works without activation. $ZEPHYR_SDK_INSTALL_DIR (set by an
+    // activated env) wins over the discovered install dir.
+    const sdkRoot = env.ZEPHYR_SDK_INSTALL_DIR || install.sdkInstallDir;
+    const openocdBin = sdkRoot ? join(sdkRoot, 'hosttools', 'openocd', 'bin') : undefined;
+    const prepend = [
+        openocdBin !== undefined && existsSync(openocdBin) ? openocdBin : undefined,
+        venvBinDir(install),
+    ].filter((d) => d !== undefined);
+    if (prepend.length > 0) {
         const sep = process.platform === 'win32' ? ';' : ':';
         // On Windows the PATH environment variable may be cased as `Path` (the
         // registry-native form, the only one populated when node is launched from
@@ -50,9 +62,9 @@ export function buildEnv(install) {
         // casing can leave the other stale/empty, which under PowerShell would drop
         // the user's real PATH (cmake, ninja, …) — breaking `west` configure. Read
         // whichever casing is populated and write that same casing back, preserving
-        // the full existing value with the venv dir prepended.
+        // the full existing value with the discovered dirs prepended.
         const existing = env.Path ?? env.PATH ?? '';
-        const updated = bin + sep + existing;
+        const updated = prepend.join(sep) + sep + existing;
         if (env.Path !== undefined || (env.PATH === undefined && process.platform === 'win32')) {
             env.Path = updated;
         }