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

package/dist/lowering/timing.js

@@ -1,13 +1,9 @@
 // ---------------------------------------------------------------------------
 // Timing lowering — Zephyr kernel timing
 //
-// delay/millis/delay_microseconds/micros/free_heap lower directly. The four
-// timer ops (set_interval/set_timeout/clear_interval/clear_timeout) call the
-// timer_methods polyfill helpers (k_timer + k_work pool), declared as 'polyfill'
-// status in the manifest — the validator skips the resolver probe for these
-// (they legitimately return polyfill-helper calls, not direct lowering).
-// free_heap has no portable Zephyr query without CONFIG_SYS_HEAP_RUNTIME_STATS;
-// it returns 0 with a comment (honest limitation).
+// sleep/now/now_us/busy_wait_us lower directly to kernel calls. Periodic or
+// deferred work is NOT a timing op: it is a Thread (k_thread) or a Counter
+// (hardware timer), each with its own lowering.
 // ---------------------------------------------------------------------------
 /**
  * Resolve a HAL timing.* op to Zephyr C++.
@@ -16,46 +12,24 @@
 export function lowerTiming(op) {
     const o = op;
     switch (op.operation) {
-        case 'timing.delay': {
-            // Milliseconds — k_msleep is the blocking Zephyr call. Because
-            // isRtosTarget() returns true, the transpiler does not warn about
-            // blocking delays inside loop().
-            const ms = o.ms;
-            return { code: `k_msleep(${ms});` };
-        }
-        case 'timing.delay_microseconds': {
-            // k_busy_wait spins (does not yield); for cooperative μs delays.
+        case 'timing.sleep':
+            // Time.sleep — yielding ms sleep (k_msleep), delay()'s replacement.
+            return { code: `k_msleep(${o.ms});` };
+        case 'timing.now':
+            // Time.now — ms since boot as a double (k_uptime_get is int64_t ms).
+            return { expression: 'static_cast<double>(k_uptime_get())' };
+        case 'timing.now_us':
+            // Time.nowUs — µs since boot, uptime-derived for EVERY board: the
+            // cycle-counter form (k_cyc_to_us_floor64(k_cycle_get_64())) reads a
+            // constant on SoCs without a free-running 64-bit counter, so the one
+            // uniform expression that is monotonic and advancing everywhere is
+            // the kernel uptime scaled to µs. Resolution is therefore the uptime
+            // tick (millisecond), uniformly. A double holds µs exactly for ~285
+            // years.
+            return { expression: 'static_cast<double>(k_uptime_get() * 1000)' };
+        case 'timing.busy_wait_us':
+            // Time.busyWaitUs — spin, no yield; delayMicroseconds's honest name.
             return { code: `k_busy_wait(${o.us});` };
-        }
-        case 'timing.millis':
-            // k_uptime_get_32() returns int64_t milliseconds since boot. Cast to the
-            // Arduino-millis() return type (uint32_t) so overflow wraps identically.
-            return { expression: 'static_cast<uint32_t>(k_uptime_get_32())' };
-        case 'timing.micros': {
-            // Convert hardware cycles to microseconds. k_cycle_get_32 + the cycles/sec
-            // macro (note: sys_clock_hw_cycles_per_sec is a MACRO — needs parens).
-            return {
-                expression: '(uint32_t)(((uint64_t)k_cycle_get_32() * 1000000ULL) / sys_clock_hw_cycles_per_sec())',
-            };
-        }
-        case 'timing.free_heap':
-            // No portable free-heap query without CONFIG_SYS_HEAP_RUNTIME_STATS.
-            // Return 0 with a comment so callers don't get a link error.
-            return { expression: '(0 /* free_heap: enable CONFIG_SYS_HEAP_RUNTIME_STATS for real value */)' };
-        case 'timing.set_interval':
-            // Backed by the timer_methods polyfill (k_timer + k_work). The handler is
-            // the resolved C++ callback name; timeout is the repeat period (ms).
-            // NOTE: these ops are declared 'polyfill' in the manifest, so setInterval
-            // is rewritten to __tc_setInterval before reaching the lowering — these
-            // cases are a fallback/defense and use the real op fields (handler/timeout).
-            return { expression: `__tc_setInterval(${o.handler}, ${o.timeout})` };
-        case 'timing.set_timeout':
-            // One-shot: k_timer with K_FOREVER period.
-            return { expression: `__tc_setTimeout(${o.handler}, ${o.timeout})` };
-        case 'timing.clear_interval':
-            return { code: `__tc_clearInterval(${o.id});` };
-        case 'timing.clear_timeout':
-            return { code: `__tc_clearTimeout(${o.id});` };
         default:
             throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
                 `Open an issue or use rawCpp() to emit it manually.`);

package/dist/lowering/tone.js

@@ -11,6 +11,16 @@
 // matching the synchronous Arduino tone() semantics. For non-blocking tone,
 // a workqueue would be needed (deferred).
 // ---------------------------------------------------------------------------
+import { findPwmSpec, pwmDtAliasToken } from './pwm.js';
+/**
+ * The PWM spec a tone op drives: the op's own pin when it maps to a spec
+ * (matrix chips — ESP32 LEDC — resolve any driven pad), else the board's
+ * first spec (the aliased LED channel, e.g. pwm-led0 on the XIAO).
+ */
+function toneSpec(chip, pin) {
+    return (typeof pin === 'number' ? findPwmSpec(chip, pin) : undefined)
+        ?? chip.pwm?.specs[0];
+}
 /**
  * Resolve a HAL tone.* op to Zephyr C++ via PWM.
  * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
@@ -22,14 +32,17 @@ export function lowerTone(op, chip) {
             // period_ns = 1e9 / freq; pulse_ns = period / 2 (50% duty).
             // Build a fake pwm.write would need the spec var directly; emit the
             // pwm_set_dt call against the same spec var the PWM lowering uses.
-            const spec = chip.pwm?.specs[0];
+            const spec = toneSpec(chip, o.pin);
             if (!spec) {
                 return { code: `/* tone.play(${o.frequency}): no PWM spec in chip descriptor */` };
             }
-            const v = `__tc_pwm_${spec.dtSpec.replace(/-/g, '_')}`;
+            const v = `__tc_pwm_${pwmDtAliasToken(spec)}`;
             const freq = o.frequency;
             const duration = o.duration;
-            const setTone = `uint32_t __period = (${freq} > 0) ? (1000000000ULL / static_cast<uint64_t>(${freq})) : 0; pwm_set_dt(&${v}, __period, __period / 2);`;
+            // Braced: two tone ops in one statement-scope (e.g. tone(440).for(50)
+            // lowers tone.play + tone.play_for back-to-back) would otherwise
+            // redeclare __period.
+            const setTone = `{ uint32_t __period = (${freq} > 0) ? (1000000000ULL / static_cast<uint64_t>(${freq})) : 0; pwm_set_dt(&${v}, __period, __period / 2); }`;
             if (duration !== undefined) {
                 // Blocking tone for the requested duration, then stop.
                 return { code: `${setTone} k_msleep(${duration}); pwm_set_pulse_dt(&${v}, 0);` };
@@ -37,10 +50,10 @@ export function lowerTone(op, chip) {
             return { code: setTone };
         }
         case 'tone.stop': {
-            const spec = chip.pwm?.specs[0];
+            const spec = toneSpec(chip, o.pin);
             if (!spec)
                 return { code: `/* tone.stop: no PWM spec */` };
-            const v = `__tc_pwm_${spec.dtSpec.replace(/-/g, '_')}`;
+            const v = `__tc_pwm_${pwmDtAliasToken(spec)}`;
             return { code: `pwm_set_pulse_dt(&${v}, 0);` };
         }
         default:

package/dist/lowering/uart.d.ts

@@ -5,6 +5,12 @@ import type { ZephyrChipDescriptor } from '../chips/types.js';
  * when the program uses UART.
  */
 export declare function uartInitLines(chip: ZephyrChipDescriptor, controllerIndex: number): string[];
+/** Render a string/number/boolean value to a per-byte poll_out loop via the
+ *  __tc_dev_put overloads (the const char* overload streams a string; the
+ *  double overload formats a number with __tc_fmt_num_buf). The value passes
+ *  through verbatim — C++ overload resolution picks the right overload for a
+ *  string literal, a number literal, or a runtime variable of either type. */
+export declare function renderWrite(dev: string, value: string, newline: boolean): string;
 /**
  * Resolve a HAL uart.* op to Zephyr C++.
  * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
@@ -13,3 +19,10 @@ export declare function lowerUart(op: HALOpIR): {
     code?: string;
     expression?: string;
 };
+/** The per-port RX ring state: a construction-sized static buffer, free-running
+ *  head/tail counters (available = head - tail, no wrap ambiguity), and the
+ *  ISR that drains the FIFO. A byte arriving with a full ring is dropped —
+ *  the embedded-honest answer (no unbounded buffering). Emitted only for
+ *  ports whose uart.rx_* ops were emitted (collectUartRings), so an unused
+ *  ISR never trips -Wunused-function. */
+export declare function uartRingStateLines(index: number, ring: number): string[];

package/dist/lowering/uart.js

@@ -2,9 +2,8 @@
 // UART lowering — uart_poll_out / uart_poll_in per-byte
 //
 // Zephyr's UART API is byte-oriented (uart_poll_out / uart_poll_in). The HAL's
-// uart.print/println/write lower to per-byte poll_out loops. For console output
-// the strategy's transformConsoleCall routes to printk; these uart.* ops are
-// for a specific UART port (the XIAO exposes uart0 on D6/D7).
+// uart.print/println/write lower to per-byte poll_out loops; these uart.* ops
+// are for a specific UART port (the XIAO exposes uart0 on D6/D7).
 //
 // The device resolves at compile time via DEVICE_DT_GET(DT_NODELABEL(uart0)).
 // uart.begin configures the baud via uart_configure.
@@ -33,16 +32,14 @@ export function uartInitLines(chip, controllerIndex) {
         '// CUTTLEFISH_UART_END',
     ];
 }
-/** Render a string-literal or expression to a per-byte poll_out loop. */
-function renderWrite(dev, value, newline) {
-    // String literal → emit a char-array loop (known length). Otherwise fall back
-    // to a const char* cast with a strlen-guarded loop.
-    if (/^".*"$/.test(value)) {
-        const body = `for (size_t __i = 0; __i < sizeof(${value}) - 1; __i++) { uart_poll_out(${dev}, (${value})[__i]); }`;
-        return newline ? `${body} uart_poll_out(${dev}, '\\n');` : body;
-    }
-    const body = `for (const char* __s = (const char*)(${value}); *__s; __s++) { uart_poll_out(${dev}, *__s); }`;
-    return newline ? `${body} uart_poll_out(${dev}, '\\n');` : body;
+/** Render a string/number/boolean value to a per-byte poll_out loop via the
+ *  __tc_dev_put overloads (the const char* overload streams a string; the
+ *  double overload formats a number with __tc_fmt_num_buf). The value passes
+ *  through verbatim — C++ overload resolution picks the right overload for a
+ *  string literal, a number literal, or a runtime variable of either type. */
+export function renderWrite(dev, value, newline) {
+    const put = `__tc_dev_put(${dev}, ${value});`;
+    return newline ? `${put} uart_poll_out(${dev}, '\\n');` : put;
 }
 /**
  * Resolve a HAL uart.* op to Zephyr C++.
@@ -54,49 +51,73 @@ export function lowerUart(op) {
     const p = prefix(idx);
     const dev = `${p}_dev`;
     switch (op.operation) {
-        case 'uart.begin':
-            return { code: `${p}_init(static_cast<uint32_t>(${o.baud}));` };
-        case 'uart.end':
-            return { code: `(void)${dev};` };
-        case 'uart.print':
-            return { code: renderWrite(dev, o.value, false) };
-        case 'uart.println':
-            return { code: renderWrite(dev, o.value, true) };
-        case 'uart.write':
-            return { code: renderWrite(dev, o.data, false) };
-        case 'uart.printf': {
-            // snprintf into a buffer, then poll_out each byte.
-            const fmt = o.format;
-            const args = (o.args ?? []).join(', ');
-            const argList = args ? `, ${args}` : '';
+        case 'uart.poll_write': {
+            const pre = uartBaudGuard(p, o.baud);
+            return { code: `${pre} ${renderWrite(dev, o.data, false)}` };
+        }
+        // ── Thin UART RX (hal/uart-port.ts) — interrupt-drained ring ──────────
+        // The first receive call arms the driver IRQ (guarded); the ISR drains
+        // the FIFO into the construction-sized static ring (uartRingStateLines).
+        // available/peek/read are then pure ring arithmetic — the calls the poll
+        // API honestly could not support.
+        case 'uart.rx_arm':
+        case 'uart.rx_available':
+        case 'uart.rx_peek':
+        case 'uart.rx_read': {
+            const r = `__tc_uartrx${idx}`;
+            const arm = `{ static bool ${r}_armed = false; if (!${r}_armed) { uart_irq_callback_user_data_set(${dev}, ${r}_isr, NULL); uart_irq_rx_enable(${dev}); ${r}_armed = true; } }`;
+            if (op.operation === 'uart.rx_arm')
+                return { code: arm };
+            if (op.operation === 'uart.rx_available') {
+                return { expression: `({ ${arm} (${r}_head - ${r}_tail); })` };
+            }
+            if (op.operation === 'uart.rx_peek') {
+                return { expression: `({ ${arm} (${r}_tail < ${r}_head ? ${r}_buf[${r}_tail % ${o.ring}] : -1); })` };
+            }
             return {
-                code: `char __buf[128]; int __n = snprintk(__buf, sizeof(__buf), ${fmt}${argList}); for (int __i = 0; __i < __n; __i++) { uart_poll_out(${dev}, __buf[__i]); }`,
+                expression: `({ ${arm} (${r}_tail < ${r}_head ? ${r}_buf[(${r}_tail)++ % ${o.ring}] : -1); })`,
             };
         }
-        case 'uart.read':
-            // Non-blocking poll; returns the byte or -1 if none available.
-            return { expression: `({ unsigned char __b = 0; (uart_poll_in(${dev}, &__b) == 0) ? (int)__b : -1; })` };
-        case 'uart.peek':
-            // The poll API has no buffered-byte store, so there is no true peek.
-            // Return -1 (the Arduino "no data" sentinel) rather than blocking. This
-            // is an honest limitation of the byte-level poll driver; an interrupt- or
-            // DMA-backed UART driver would be needed for real peek semantics.
-            return { expression: '(-1)' };
-        case 'uart.available':
-            // The poll API reports only "at least one byte ready" via uart_poll_in's
-            // return code — it has no buffered-byte count, and probing with poll_in
-            // would DRAIN the very byte the caller next wants to read. So we cannot
-            // honestly report availability. Return 0 (Arduino's "no data" value)
-            // rather than the old truthy -1, so `if (uart.available())` loops don't
-            // spin forever on a false-positive. Callers should instead just call
-            // uart.read() directly (it returns -1 when no byte is ready). For true
-            // buffered availability, use an interrupt/DMA-backed UART driver.
-            return { expression: '(0)' };
-        case 'uart.flush':
-            // poll_out is synchronous (blocking until sent); flush is a no-op.
-            return { code: `(void)${dev};` };
         default:
             throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
                 `Open an issue or use rawCpp() to emit it manually.`);
     }
 }
+/** The thin-port baud preamble: apply the construction baud once via the
+ *  shim's `_init` helper (uart_configure). Guarded per controller. */
+function uartBaudGuard(p, baud) {
+    const n = typeof baud === 'number' ? baud : parseInt(String(baud ?? 0), 10);
+    if (!n || isNaN(n))
+        return '';
+    const done = `${p}_baud_done`;
+    return `{ static bool ${done} = false; if (!${done}) { ${p}_init(static_cast<uint32_t>(${n})); ${done} = true; } } `;
+}
+/** The per-port RX ring state: a construction-sized static buffer, free-running
+ *  head/tail counters (available = head - tail, no wrap ambiguity), and the
+ *  ISR that drains the FIFO. A byte arriving with a full ring is dropped —
+ *  the embedded-honest answer (no unbounded buffering). Emitted only for
+ *  ports whose uart.rx_* ops were emitted (collectUartRings), so an unused
+ *  ISR never trips -Wunused-function. */
+export function uartRingStateLines(index, ring) {
+    const r = `__tc_uartrx${index}`;
+    const dev = `__tc_uart${index}_dev`;
+    return [
+        '// CUTTLEFISH_UARTRX_BEGIN',
+        `static uint8_t ${r}_buf[${ring}];`,
+        `static volatile uint32_t ${r}_head = 0;`,
+        `static volatile uint32_t ${r}_tail = 0;`,
+        `static void ${r}_isr(const struct device* dev, void* user_data) {`,
+        `    (void)user_data;`,
+        `    uart_irq_update(dev);`,
+        `    while (uart_irq_rx_ready(dev)) {`,
+        `        uint8_t __c = 0;`,
+        `        (void)uart_fifo_read(dev, &__c, 1);`,
+        `        if ((${r}_head - ${r}_tail) < ${ring}) {`,
+        `            ${r}_buf[${r}_head % ${ring}] = __c;`,
+        `            ${r}_head++;`,
+        `        }`,
+        `    }`,
+        `}`,
+        '// CUTTLEFISH_UARTRX_END',
+    ];
+}

package/dist/lowering/usb.d.ts

@@ -0,0 +1,34 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+/**
+ * Emit the shared USB device context (USBD_DEVICE_DEFINE + string/config
+ * descriptors + configuration + class registration + usbd_enable). Emitted
+ * ONCE per program when the chip declares `usb` — the next stack has one
+ * device context on the UDC controller, regardless of how many CDC instances
+ * hang off it.
+ *
+ * VID/PID default to the Zephyr-project testing IDs (0x2fe3/0x0001); a board
+ * overrides via `zephyr.usb.vid`/`zephyr.usb.pid`. Full-speed only — the
+ * boards this framework targets (STM32 OTG_FS, nRF USBD) are FS controllers,
+ * and the HS path would need a second USBD_CONFIGURATION_DEFINE.
+ *
+ * Symbol/API shapes verified against Zephyr 4.3:
+ * subsys/usb/device_next/Kconfig, include/zephyr/usb/usbd.h, and
+ * samples/subsys/usb/common/sample_usbd_init.c.
+ */
+export declare function usbdDeviceLines(chip: ZephyrChipDescriptor): string[];
+/**
+ * Emit the per-instance CDC device + init helper. Called from shimLines when
+ * the program uses USB and the chip declares `usb`; must be paired with one
+ * usbdDeviceLines() block. The init starts the device stack (guarded) and
+ * applies the line coding.
+ */
+export declare function usbInitLines(chip: ZephyrChipDescriptor, instanceIndex: number): string[];
+/**
+ * Resolve a HAL usb.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ */
+export declare function lowerUsb(op: HALOpIR, chip: ZephyrChipDescriptor): {
+    code?: string;
+    expression?: string;
+};

package/dist/lowering/usb.js

@@ -0,0 +1,206 @@
+// ---------------------------------------------------------------------------
+// USB CDC-ACM serial lowering — Zephyr "next" USB device stack
+//
+// A CDC-ACM instance (cdc_acm_uart<N>, composed in the generated overlay as a
+// child of the UDC controller node) registers as a UART-class device, so the
+// lowering drives it with the plain uart_* API — the same per-byte poll_out
+// loops as lowering/uart.ts. The differences from a hardware UART:
+//   - usb.begin must start the device stack (usbdDeviceLines' one-shot
+//     __tc_usbd_start) before the port carries traffic;
+//   - "connected" is a real query (DTR line ctrl), not a constant;
+//   - baud is a line-coding hint — recorded, but CDC has no wire baud.
+//
+// If the chip descriptor declares no `usb`, every op throws with a clear
+// "board does not expose USB" message (the diagnostic contract the framework
+// manifest's board-gated support entry promises).
+// ---------------------------------------------------------------------------
+import { parseControllerIndex } from './util.js';
+import { renderWrite } from './uart.js';
+/** Render a HAL field: pass through (already rendered by the resolver). */
+function s(v) {
+    return String(v);
+}
+/** The C variable prefix for a CDC instance's state. */
+function prefix(idx) {
+    return `__tc_usb${idx}`;
+}
+/** Instance N resolves to the DT nodelabel the overlay generator emits. */
+function nodeLabel(idx) {
+    return `cdc_acm_uart${idx}`;
+}
+/**
+ * Emit the shared USB device context (USBD_DEVICE_DEFINE + string/config
+ * descriptors + configuration + class registration + usbd_enable). Emitted
+ * ONCE per program when the chip declares `usb` — the next stack has one
+ * device context on the UDC controller, regardless of how many CDC instances
+ * hang off it.
+ *
+ * VID/PID default to the Zephyr-project testing IDs (0x2fe3/0x0001); a board
+ * overrides via `zephyr.usb.vid`/`zephyr.usb.pid`. Full-speed only — the
+ * boards this framework targets (STM32 OTG_FS, nRF USBD) are FS controllers,
+ * and the HS path would need a second USBD_CONFIGURATION_DEFINE.
+ *
+ * Symbol/API shapes verified against Zephyr 4.3:
+ * subsys/usb/device_next/Kconfig, include/zephyr/usb/usbd.h, and
+ * samples/subsys/usb/common/sample_usbd_init.c.
+ */
+export function usbdDeviceLines(chip) {
+    if (!chip.usb)
+        return [];
+    const vid = chip.usb.vid ?? '0x2fe3';
+    const pid = chip.usb.pid ?? '0x0001';
+    // 1200-baud touch-to-reset (BOSSA-bootloader boards): a usbd message
+    // callback that reboots into the bootloader when the host sets the CDC
+    // baud rate to 1200. Zephyr's CDC-ACM class publishes
+    // USBD_MSG_CDC_ACM_LINE_CODING on every host SET_LINE_CODING (the message
+    // carries the CDC uart device; its line coding is readable via
+    // uart_cfg_get). The reboot writes the bootloader's stay-resident magic
+    // (Arduino SAMD scheme: the bootloader checks the last word of SRAM after
+    // reset) so the board waits in the bootloader instead of booting the app.
+    const touch = chip.usb.touchReset;
+    const touchLines = touch
+        ? [
+            `// 1200-baud touch-to-reset: reboot into the bootloader (flag 0x${touch.magic.toString(16)} @ 0x${touch.flagAddress.toString(16)}).`,
+            'static void __tc_usbd_msg_cb(struct usbd_context* ctx, const struct usbd_msg* msg) {',
+            '    (void)ctx;',
+            '    if (msg->type != USBD_MSG_CDC_ACM_LINE_CODING) { return; }',
+            '    struct uart_config __tc_cfg;',
+            '    if (uart_config_get(msg->dev, &__tc_cfg) == 0 && __tc_cfg.baudrate == 1200) {',
+            '        // Delay the reboot so the host touch (which applies 1200 as part',
+            '        // of opening the port) can close its handle first — resetting under',
+            '        // an open host handle can wedge the Windows usbser driver and block',
+            '        // re-enumeration until a physical replug.',
+            '        k_msleep(250);',
+            `        *(volatile uint32_t*)0x${touch.flagAddress.toString(16)} = 0x${touch.magic.toString(16)};`,
+            '        NVIC_SystemReset();',
+            '    }',
+            '}',
+        ]
+        : [];
+    const touchRegister = touch
+        ? ['    usbd_msg_register_cb(&__tc_usbd, __tc_usbd_msg_cb);']
+        : [];
+    return [
+        '// CUTTLEFISH_USBD_BEGIN',
+        'USBD_DEVICE_DEFINE(__tc_usbd,',
+        `    DEVICE_DT_GET(DT_NODELABEL(${chip.usb.controller})),`,
+        `    ${vid}, ${pid});`,
+        'USBD_DESC_LANG_DEFINE(__tc_usbd_lang);',
+        'USBD_DESC_MANUFACTURER_DEFINE(__tc_usbd_mfr, "typecad");',
+        'USBD_DESC_PRODUCT_DEFINE(__tc_usbd_product, "cuttlefish app");',
+        // Serial number from hwinfo: Windows keys USB devnodes without a serial
+        // on the physical port, so flash-cycle re-enumerations reuse stale
+        // port-keyed nodes (the "access denied" open wedge). Identity-based
+        // instance paths are stable across ports and never hit that pool.
+        'USBD_DESC_SERIAL_NUMBER_DEFINE(__tc_usbd_sn);',
+        'USBD_DESC_CONFIG_DEFINE(__tc_usbd_cfg_desc, "cuttlefish");',
+        'USBD_CONFIGURATION_DEFINE(__tc_usbd_cfg, 0, 250, &__tc_usbd_cfg_desc);',
+        'static bool __tc_usbd_started = false;',
+        ...touchLines,
+        'static void __tc_usbd_start(void) {',
+        '    if (__tc_usbd_started) { return; }',
+        '    __tc_usbd_started = true;',
+        '    int err = usbd_add_descriptor(&__tc_usbd, &__tc_usbd_lang);',
+        '    if (err != 0) { printk("cuttlefish usb: lang descriptor failed: %d\\n", err); return; }',
+        '    err = usbd_add_descriptor(&__tc_usbd, &__tc_usbd_sn);',
+        '    if (err != 0) { printk("cuttlefish usb: serial descriptor failed: %d\\n", err); return; }',
+        '    err = usbd_add_descriptor(&__tc_usbd, &__tc_usbd_mfr);',
+        '    if (err != 0) { printk("cuttlefish usb: manufacturer descriptor failed: %d\\n", err); return; }',
+        '    err = usbd_add_descriptor(&__tc_usbd, &__tc_usbd_product);',
+        '    if (err != 0) { printk("cuttlefish usb: product descriptor failed: %d\\n", err); return; }',
+        '    err = usbd_add_configuration(&__tc_usbd, USBD_SPEED_FS, &__tc_usbd_cfg);',
+        '    if (err != 0) { printk("cuttlefish usb: add configuration failed: %d\\n", err); return; }',
+        '    err = usbd_register_all_classes(&__tc_usbd, USBD_SPEED_FS, 1, NULL);',
+        '    if (err != 0) { printk("cuttlefish usb: register classes failed: %d\\n", err); return; }',
+        // Registered before usbd_init so no line-coding event can be missed.
+        ...touchRegister,
+        // usbd_init builds the descriptor tables from the registered
+        // configuration/classes and marks the context initialized — usbd_enable
+        // refuses with -EPERM ("not initialized") without it (sample_usbd_init.c
+        // calls it between setup and enable).
+        '    err = usbd_init(&__tc_usbd);',
+        '    if (err != 0) { printk("cuttlefish usb: init failed: %d\\n", err); return; }',
+        // Boards with VBUS detection start on the VBUS event in the Zephyr
+        // sample, via a message callback we do not register; enabling
+        // unconditionally (and reporting the error) is the sample's own path
+        // for boards without detection (STM32 OTG_FS).
+        '    err = usbd_enable(&__tc_usbd);',
+        '    if (err != 0) { printk("cuttlefish usb: enable failed: %d\\n", err); return; }',
+        '    printk("cuttlefish usb: device enabled\\n");',
+        '}',
+        '// CUTTLEFISH_USBD_END',
+    ];
+}
+/**
+ * Emit the per-instance CDC device + init helper. Called from shimLines when
+ * the program uses USB and the chip declares `usb`; must be paired with one
+ * usbdDeviceLines() block. The init starts the device stack (guarded) and
+ * applies the line coding.
+ */
+export function usbInitLines(chip, instanceIndex) {
+    if (!chip.usb)
+        return [];
+    const p = prefix(instanceIndex);
+    const dev = `${p}_dev`;
+    return [
+        '// CUTTLEFISH_USB_BEGIN',
+        `static const struct device* ${dev} = DEVICE_DT_GET(DT_NODELABEL(${nodeLabel(instanceIndex)}));`,
+        `static void ${p}_init(void) {`,
+        `    __tc_usbd_start();   // CDC line coding is the host's business`,
+        `}`,
+        '// CUTTLEFISH_USB_END',
+    ];
+}
+/** Throw the board-capability diagnostic. Centralized so every op reads identically. */
+function requireUsb(chip, op) {
+    if (!chip.usb) {
+        throw new Error(`framework-zephyr: \`${op}\` needs a USB device stack, but this board's chip data declares no \`zephyr.usb\` ` +
+            `(controller + cdcInstances). Boards whose Zephyr DTS has no enabled UDC controller node ` +
+            `(zephyr_udc0) cannot provide USB CDC serial.`);
+    }
+}
+/**
+ * Resolve a HAL usb.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ */
+export function lowerUsb(op, chip) {
+    requireUsb(chip, op.operation);
+    const o = op;
+    const idx = parseControllerIndex(o.port);
+    if (chip.usb && idx >= chip.usb.cdcInstances) {
+        throw new Error(`framework-zephyr: usb port "${o.port}" (instance ${idx}) is out of range — this board composes ` +
+            `${chip.usb.cdcInstances} CDC-ACM instance(s) (USB0..USB${chip.usb.cdcInstances - 1}).`);
+    }
+    const p = prefix(idx);
+    const dev = `${p}_dev`;
+    switch (op.operation) {
+        case 'usb.begin':
+            return { code: `${p}_init();` };
+        case 'usb.wait_ready': {
+            // Bounded DTR poll, sliced in the shim-side expression (no user-code
+            // busy loop). timeoutMs 0 = wait forever.
+            return { expression: `({ bool __ok = false; uint32_t __t = 0U; while (true) { uint32_t __dtr = 0U; if ((uart_line_ctrl_get(${dev}, UART_LINE_CTRL_DTR, &__dtr) == 0) && (__dtr != 0U)) { __ok = true; break; } if ((${s(o.timeoutMs ?? 0)}) != 0 && __t >= (uint32_t)(${s(o.timeoutMs ?? 0)})) { break; } k_msleep(10); __t += 10U; } __ok; })` };
+        }
+        case 'usb.end':
+            // CDC has no per-port disable short of tearing down the device stack
+            // (which would drop every other instance); make end observable but safe.
+            return { code: `(void)${dev};` };
+        case 'usb.print':
+            return { code: renderWrite(dev, o.value, false) };
+        case 'usb.println':
+            return { code: renderWrite(dev, o.value, true) };
+        case 'usb.read':
+            // Same poll semantics as uart.read: the byte or -1 if none available.
+            return { expression: `({ unsigned char __b = 0; (uart_poll_in(${dev}, &__b) == 0) ? (int)__b : -1; })` };
+        case 'usb.available':
+            // uart_poll_in reports only "one byte ready" and probing would drain it;
+            // same honest limitation as uart.available.
+            return { expression: '(0)' };
+        case 'usb.connected':
+            // DTR asserted = the host actually opened the port.
+            return { expression: `({ uint32_t __dtr = 0; (uart_line_ctrl_get(${dev}, UART_LINE_CTRL_DTR, &__dtr) == 0) && (__dtr != 0); })` };
+        default:
+            throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+                `Open an issue or use rawCpp() to emit it manually.`);
+    }
+}

package/dist/lowering/wdt.d.ts

@@ -9,7 +9,7 @@ export declare function wdtInitLines(chip: ZephyrChipDescriptor): string[];
  * Resolve a HAL wdt.* op to Zephyr C++.
  * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
  */
-export declare function lowerWdt(op: HALOpIR): {
+export declare function lowerWdt(op: HALOpIR, chip: ZephyrChipDescriptor): {
     code?: string;
     expression?: string;
 };

package/dist/lowering/wdt.js

@@ -10,12 +10,15 @@
 // constant or a number; we parse to ms in the lowering.
 // ---------------------------------------------------------------------------
 /** Parse a HAL wdt timeout ("250ms", WDTO_2S, or a bare number) to ms.
- *  Tolerates undefined (the manifest validator's probe sends a minimal op). */
+ *  Tolerates undefined (the manifest validator's probe sends a minimal op)
+ *  and quote-wrapped strings (resolveSemanticArg can hand the literal's
+ *  quoted source text through). */
 function timeoutToMs(timeout) {
     if (typeof timeout === 'number')
         return timeout;
     if (!timeout)
         return 1000; // default 1s when absent (e.g. the validator probe)
+    timeout = timeout.replace(/^['"]|['"]$/g, '');
     // Arduino WDTO_* constants.
     const wdto = {
         WDTO_15MS: 15, WDTO_30MS: 30, WDTO_60MS: 60, WDTO_120MS: 120,
@@ -51,13 +54,20 @@ export function wdtInitLines(chip) {
  * Resolve a HAL wdt.* op to Zephyr C++.
  * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
  */
-export function lowerWdt(op) {
+export function lowerWdt(op, chip) {
     const o = op;
+    // No watchdog node on this target (e.g. SAM D21 — Zephyr's samd21 dtsi
+    // exposes none). Comment + (in profileDiagnostics) a clear error, mirroring
+    // the hwtimer unavailable pattern. Without this the wdt_* calls reference
+    // the shim vars that wdtInitLines (gated on chip.wdt) never emitted.
+    if (!chip.wdt) {
+        return { code: `/* ${op.operation}: no watchdog device on ${chip.id} */` };
+    }
     switch (op.operation) {
-        case 'wdt.enable': {
-            const ms = timeoutToMs(o.timeout);
-            // Install a timeout then set up the watchdog. Both are idempotent via
-            // the static flags. WDT_FLAG_RESET_CPU_CORE = full reset on timeout.
+        case 'wdt.setup': {
+            // Same install+setup sequence as wdt.enable, but the timeout is a
+            // plain ms number from construction — no WDTO_*/string parsing.
+            const ms = Number(o.timeoutMs ?? 1000);
             return {
                 code: [
                     `if (!__tc_wdt_setup_done) {`,
@@ -69,7 +79,7 @@ export function lowerWdt(op) {
                 ].join(' '),
             };
         }
-        case 'wdt.reset':
+        case 'wdt.feed':
             return { code: `if (__tc_wdt_channel >= 0) { wdt_feed(__tc_wdt_dev, __tc_wdt_channel); }` };
         case 'wdt.disable':
             return { code: `wdt_disable(__tc_wdt_dev); __tc_wdt_setup_done = false;` };

package/dist/lowering/wifi.d.ts

@@ -5,8 +5,9 @@ import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
  *
  * State is driven by two net_mgmt event handlers:
  *  - L4 connectivity (NET_EVENT_L4_CONNECTED/DISCONNECTED) → connected flag.
- *    This reflects IP connectivity (post-DHCP), not just the WiFi link — the
- *    events are raised by conn_mgr's monitoring layer (conn_mgr_monitor.c).
+ *    This reflects IP connectivity (post-DHCP, or right after static IPv4
+ *    facts are applied) — the events are raised by conn_mgr's monitoring
+ *    layer (conn_mgr_monitor.c).
  *  - WiFi scan (NET_EVENT_WIFI_SCAN_RESULT/SCAN_DONE) → scan_results pool.
  */
 export declare function wifiInitLines(): string[];