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

package/dist/toolchain/bossac-touch.d.ts

@@ -0,0 +1,18 @@
+/** The descriptor subset this helper needs (see ZephyrChipDescriptor.usb.touchReset). */
+export interface TouchResetInfo {
+    readonly flagAddress: number;
+    readonly magic: number;
+    readonly bootloaderVid?: string;
+    readonly bootloaderPid?: string;
+}
+export interface TouchResetResult {
+    /** Bootloader port to flash (undefined = touch failed / timed out). */
+    readonly port?: string;
+    /** Human-readable outcome for the build log. */
+    readonly note: string;
+}
+/**
+ * Touch the app port at 1200 baud and wait for the bootloader to appear.
+ * Never throws — a failed touch degrades to "double-tap reset" guidance.
+ */
+export declare function bossacTouchReset(appPort: string, info: TouchResetInfo, timeoutMs?: number): TouchResetResult;

package/dist/toolchain/bossac-touch.js

@@ -0,0 +1,88 @@
+// ---------------------------------------------------------------------------
+// 1200-baud touch-to-reset for BOSSA-bootloader boards (host side)
+//
+// The device side lives in the emitted USB shim (lowering/usb.ts): when the
+// host sets the CDC baud rate to 1200, the firmware writes the bootloader's
+// stay-resident magic to RAM and reboots — the board lands in the BOSSA
+// bootloader without a button press. This module is the other half: open the
+// app's console port at 1200 baud to trigger that reboot, then wait for the
+// bootloader's own USB identity to appear and report its port so bossac can
+// be pointed at it.
+//
+// Runs as a spawned `node -e` helper (upload() is synchronous; serialport's
+// open/poll loop is async) with require() resolution rooted at THIS package,
+// so `serialport` resolves from the monorepo's hoisted node_modules. In a
+// published install without serialport available, the touch is skipped with
+// a note telling the user to double-tap reset — never a hard failure.
+// ---------------------------------------------------------------------------
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+// CommonJS so `node -e` can require() it without a package "type" lookup.
+// Keep the logic compact: open at 1200, close, poll for the bootloader
+// identity, print the port (or nothing) on stdout.
+const TOUCH_SCRIPT = `
+const SerialPort = require('serialport');
+const [appPort, wantVid, wantPid, timeoutMsStr] = process.argv.slice(1);
+const norm = (v) => (v || '').toLowerCase().replace(/^0x/, '');
+const timeoutMs = parseInt(timeoutMsStr, 10) || 15000;
+function die(msg) { console.log(JSON.stringify({ error: msg })); process.exit(0); }
+// The open call itself delivers the touch: serialport applies the 1200-baud
+// line coding as part of opening, and the firmware resets to the bootloader
+// MID-OPEN — so the open erroring ("File not found" on Windows as the device
+// vanishes) is the EXPECTED symptom of success, not a failure. Whatever the
+// open result, proceed to watching for the bootloader identity; only a
+// missing bootloader after the timeout is a real failure.
+async function watchForBootloader() {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 300));
+    try {
+      const list = await SerialPort.SerialPort.list();
+      const hit = list.find((p) =>
+        norm(p.vendorId) === norm(wantVid) && norm(p.productId) === norm(wantPid));
+      if (hit) { console.log(JSON.stringify({ port: hit.path })); process.exit(0); }
+    } catch { /* transient enumeration races while ports bounce */ }
+  }
+  die('timeout');
+}
+const port = new SerialPort.SerialPort({ path: appPort, baudRate: 1200, autoOpen: false });
+port.open((err) => {
+  if (err) { watchForBootloader(); return; }
+  // The 1200-baud line coding was applied BY the open; close immediately —
+  // the firmware's 250 ms pre-reboot delay covers the ordering, and holding
+  // the handle open across the device reset is what wedges usbser.
+  port.close(() => watchForBootloader());
+});
+`;
+/**
+ * Touch the app port at 1200 baud and wait for the bootloader to appear.
+ * Never throws — a failed touch degrades to "double-tap reset" guidance.
+ */
+export function bossacTouchReset(appPort, info, timeoutMs = 30_000) {
+    if (!info.bootloaderVid || !info.bootloaderPid) {
+        return { note: 'touch-reset: board declares no bootloader USB identity — skipping (double-tap reset to enter the bootloader)' };
+    }
+    const pkgDir = path.dirname(path.dirname(fileURLToPath(import.meta.url))); // .../src -> package root
+    let result;
+    try {
+        result = spawnSync(process.execPath, ['-e', TOUCH_SCRIPT, '--', appPort, info.bootloaderVid, info.bootloaderPid, String(timeoutMs)], { encoding: 'utf8', timeout: timeoutMs + 10_000, cwd: pkgDir });
+    }
+    catch {
+        return { note: 'touch-reset: helper failed to launch — double-tap reset to enter the bootloader' };
+    }
+    const stdout = (typeof result.stdout === 'string' ? result.stdout : '').trim();
+    const lastLine = stdout.split('\n').filter(Boolean).pop() ?? '';
+    try {
+        const parsed = JSON.parse(lastLine);
+        if (parsed.port) {
+            return { port: parsed.port, note: `touch-reset: bootloader on ${parsed.port}` };
+        }
+        return { note: 'touch-reset: bootloader did not re-appear in time — double-tap reset and retry' };
+    }
+    catch {
+        // serialport not resolvable (published install without it) or the helper
+        // crashed — degrade gracefully.
+        return { note: 'touch-reset: unavailable (serialport not installed?) — double-tap reset to enter the bootloader' };
+    }
+}

package/dist/toolchain/compat.d.ts

@@ -32,7 +32,7 @@ export declare function checkZephyrCompat(version: string | undefined): CompatRe
 /**
  * Normalize a board target for the installed Zephyr version. Rewrites a stale
  * bare id (esp32s3_devkitc) to the qualified form on Zephyr >=4.3; idempotent
- * if the target is already qualified. Older Zephyr, single-core boards
- * (xiao_ble), and unknown boards pass through unchanged.
+ * if the target is already qualified. Older Zephyr and unknown boards pass
+ * through unchanged.
  */
 export declare function resolveBoardTarget(boardTarget: string, version: string | undefined): string;

package/dist/toolchain/compat.js

@@ -74,7 +74,7 @@ export function detectZephyrVersion() {
     let base = process.env.ZEPHYR_BASE;
     if (!base) {
         // Fall back to the discovered west install's zephyrBase — covers the
-        // micromamba env from @typecad/zephyr-installer WITHOUT activation.
+        // micromamba env from the bundled Zephyr installer WITHOUT activation.
         // (micromamba run sets ZEPHYR_BASE only inside the west subprocess; this
         // makes the compat check work in the parent cuttlefish process too.)
         const install = discoverWest();
@@ -120,16 +120,21 @@ export function checkZephyrCompat(version) {
  * found". Map each known multi-core board id to its procpu (main app core)
  * qualified form. procpu is the core that runs application firmware; appcpu is
  * the secondary core (selected explicitly only when offloading to it).
+ * Single-SoC boards (xiao_ble, rpi_pico) still normalize their bare ids on
+ * 4.4, but Zephyr has signaled that bare-name normalization is going away —
+ * map them too so builds do not depend on it.
  */
 const QUALIFIED_TARGETS_GE_4_3 = {
     esp32_devkitc: 'esp32_devkitc/esp32/procpu',
     esp32s3_devkitc: 'esp32s3_devkitc/esp32s3/procpu',
+    xiao_ble: 'xiao_ble/nrf52840',
+    rpi_pico: 'rpi_pico/rp2040',
 };
 /**
  * Normalize a board target for the installed Zephyr version. Rewrites a stale
  * bare id (esp32s3_devkitc) to the qualified form on Zephyr >=4.3; idempotent
- * if the target is already qualified. Older Zephyr, single-core boards
- * (xiao_ble), and unknown boards pass through unchanged.
+ * if the target is already qualified. Older Zephyr and unknown boards pass
+ * through unchanged.
  */
 export function resolveBoardTarget(boardTarget, version) {
     const boardId = boardTarget.split('/')[0];

package/dist/toolchain/debug-config.d.ts

@@ -4,7 +4,7 @@ export interface DebugConfigOptions {
     /** Absolute path to the workspace root (the cuttlefish config dir — the folder VS Code has open). */
     workspaceRoot: string;
     /** The Zephyr app dir relative to the workspace root (e.g. 'src/out'). */
-    sketchRel: string;
+    appRel: string;
     /** The Zephyr board id (e.g. 'esp32s3_devkitc'). */
     target: string;
     /** Absolute path to the Zephyr build dir (<projectRoot>/build) — read for the SDK/GDB path. */
@@ -24,14 +24,16 @@ export interface DebugConfigOptions {
  * omits gdbPath and relies on Cortex-Debug's default resolution).
  */
 export declare function resolveGdbPath(buildDir: string, target: string): string | undefined;
-/** The esp32s3 xtensa GDB location inside a Zephyr SDK root (verified against
- *  zephyr-sdk-0.17.4). Returns a forward-slash absolute path or undefined. */
-export declare function gdbPathFromSdkRoot(sdkRoot: string): string | undefined;
+/** The GDB location inside a Zephyr SDK root, per target architecture:
+ *  ARM boards use the arm-zephyr-eabi toolchain (verified against
+ *  zephyr-sdk-0.17.4), Espressif the xtensa-espressif_esp32s3_zephyr-elf one.
+ *  Returns a forward-slash absolute path or undefined. */
+export declare function gdbPathFromSdkRoot(sdkRoot: string, target?: string): string | undefined;
 /**
  * Probe the well-known Zephyr SDK install locations, newest version first:
  *   1. $ZEPHYR_SDK_INSTALL_DIR (the var board.cmake reads)
  *   2. <MAMBA_ROOT_PREFIX | ~/micromamba>/zephyr-sdk/zephyr-sdk-<ver> — the
- *      @typecad/zephyr-installer layout
+ *      the bundled Zephyr installer layout
  *   3. ~/zephyr-sdk-<ver> — the standalone download layout
  *
  * Only roots that actually contain the esp32s3 GDB are useful to callers;
@@ -43,21 +45,24 @@ export declare function discoverZephyrSdkRoots(opts?: {
     env?: Record<string, string | undefined>;
 }): string[];
 /**
- * Resolve the Espressif OpenOCD binary path. The esp32s3 needs the Espressif
- * OpenOCD fork (openocd-esp32) — not the Zephyr SDK's openocd and not a
+ * Resolve the OpenOCD binary path. The esp32s3 needs the Espressif OpenOCD
+ * fork (openocd-esp32) — not the Zephyr SDK's openocd and not a
  * generic/GDB-stub build — because only it carries the Xtensa + esp_usb_jtag
- * support. It is NOT on PATH by default, so Cortex-Debug must be pointed at it
- * explicitly or it fails with `spawn openocd.exe ENOENT`.
+ * support. ARM targets prefer the Zephyr SDK's own openocd (it ships the
+ * interface/target cfgs boards reference); the Espressif fork is only
+ * consulted for esp32 targets.
  *
  * Discovery order:
- *   1. ESPRESSIF_TOOLCHAIN_PATH env (the var board.cmake reads) — if set, its
- *      openocd-esp32/bin/openocd.exe.
+ *   1. ESPRESSIF_TOOLCHAIN_PATH env (the var board.cmake reads) — esp32
+ *      targets; its openocd-esp32/bin/openocd.exe.
  *   2. The standard ESP-IDF install layout: ~/.espressif/tools/openocd-esp32/
- *      <version>/openocd-esp32/bin/openocd.exe. Pick the newest version dir.
+ *      <version>/openocd-esp32/bin/openocd.exe (esp32 targets; newest first).
+ *   3. A Zephyr SDK root (discoverZephyrSdkRoots) — its
+ *      tools/opt/openocd/bin/openocd(.exe), any target.
  * Returns undefined if not found (the launch.json then omits openOCDPath and
  * Cortex-Debug falls back to PATH / its openocdPath setting).
  */
-export declare function resolveOpenOcdPath(): string | undefined;
+export declare function resolveOpenOcdPath(target?: string): string | undefined;
 /**
  * Resolve where to write the VS Code debug artifacts and how to express paths
  * in them.
@@ -71,13 +76,13 @@ export declare function resolveOpenOcdPath(): string | undefined;
  * THAT as the workspace root. This makes F5 work when a user opens the project
  * folder directly, and keeps launch.json paths relative to it.
  *
- * Returns { workspaceRoot, sketchRel } where workspaceRoot is the cuttlefish
- * project root (the `.vscode/` target) and sketchRel is the Zephyr app dir
+ * Returns { workspaceRoot, appRel } where workspaceRoot is the cuttlefish
+ * project root (the `.vscode/` target) and appRel is the Zephyr app dir
  * (`projectRoot`) relative to it (e.g. 'src/out').
  */
 export declare function resolveDebugLocations(projectRoot: string): {
     workspaceRoot: string;
-    sketchRel: string;
+    appRel: string;
 };
 /**
  * Generate the GDB Python frame-filter that rewrites cuttlefish's hoisted
@@ -89,16 +94,6 @@ export declare function resolveDebugLocations(projectRoot: string): {
  * the filter is cuttlefish-internal (lambda hoisting is framework-agnostic).
  */
 export declare function generateGdbScript(sourceMapPath?: string): string | null;
-/**
- * Write all gdb-mode debug artifacts for the given target. Called from the
- * toolchain compile() after a successful build when debugMode === 'gdb'.
- *
- * Writes (all idempotent):
- *   <workspaceRoot>/.vscode/launch.json   (cortex-debug config)
- *   <workspaceRoot>/.vscode/tasks.json    (build + flash preLaunch task)
- *   <projectRoot>/.cuttlefish/openocd.cfg (OpenOCD cfg, adapter speed override)
- *   <projectRoot>/.cuttlefish/.cuttlefish-gdb.py  (lambda frame filter, conditional)
- */
 export declare function writeDebugConfig(o: DebugConfigOptions): void;
 /**
  * Create-time starter debug artifacts. Called by the cuttlefish `create` flow