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

package/dist/dt-config/overlay.js

@@ -11,7 +11,18 @@
 // library headers into .d.ts; Zephyr does it by enabling DT nodes + Kconfig.)
 // ---------------------------------------------------------------------------
 import { PANEL_CONTROLLER_DEFAULTS, panelControllerFor } from '../display/profiles.js';
-export function generateOverlay(chip, usage, display, wiring, touch) {
+export function generateOverlay(chip, usage, display, wiring, touch, diagnostics = []) {
+    // An I2C touch controller with no explicit bus pins: the overlay enables
+    // i2c0 and instantiates the node, but nothing remuxes the controller to
+    // the wired SDA/SCL (the board's default I2C pins rarely match a
+    // breakout). Every I2C read then fails and touch silently does nothing —
+    // surface it at build time instead of leaving it to a multimeter.
+    if (touch && touch.controller !== 'xpt2046' && (touch.sda === undefined || touch.scl === undefined)) {
+        diagnostics.push({
+            severity: "warning",
+            message: `touch: I2C controller '${touch.controller}' has no sda/scl pins in cuttlefish.config.ts — the overlay enables the bus without a pin assignment, so the controller may never answer. Add touch.sda and touch.scl (the board's default I2C pins are rarely the wired ones).`,
+        });
+    }
     const lines = [
         '/* Auto-generated by @typecad/framework-zephyr from cuttlefish.config.ts. */',
         '/* Enables peripherals the program uses. West merges this over the board DT. */',
@@ -42,6 +53,24 @@ export function generateOverlay(chip, usage, display, wiring, touch) {
         for (const c of chip.uart.controllers)
             block(c.nodeLabel);
     }
+    // PWM: synthesized specs (controller + channel, no board-shipped alias) get
+    // a pwm-leds consumer node + tc-pwm<pin> alias here — the lowering addresses
+    // the channel as PWM_DT_SPEC_GET(DT_ALIAS(tc-pwm<pin>)), so the alias must
+    // exist in the merged DT. pwmDtAlias (lowering/pwm.ts) derives the same
+    // name from the pin; the two sides cannot drift. Filtered to the pins the
+    // program actually drives (pwmUsedPins) so the DT carries no dead channels;
+    // an undefined list (prepare-time overlay) emits all specs.
+    if (usage.usesPwm && chip.pwm) {
+        emitPwmNodes(lines, chip, usage.pwmUsedPins);
+    }
+    // ADC: enable the ADC device node, and on SoCs whose channels carry a
+    // pinctrl label (STM32: the pad stays in GPIO mode unless the ADC node's
+    // pinctrl-0 muxes it analog), rewrite pinctrl-0 to exactly the channels the
+    // program reads. DT assignment replaces the whole property — the board
+    // default (one pad) is deliberately dropped in favor of the used set.
+    if (usage.usesAdc && chip.adc) {
+        emitAdcNode(lines, chip, usage.adcReadPins);
+    }
     // DAC: enable the chip's DAC device node when the program uses dac.*. The
     // lowering references DEVICE_DT_GET(DT_NODELABEL(<dac.device>)).
     if (usage.usesDac && chip.dac) {
@@ -95,6 +124,73 @@ export function generateOverlay(chip, usage, display, wiring, touch) {
     }
     return lines.join('\n');
 }
+/**
+ * Emit the pwm-leds consumer node + aliases for synthesized PWM specs.
+ *
+ * A board DTS may enable a PWM controller (`pwm4`) without aliasing any
+ * channel — the STM32 pattern — while the lowering addresses channels via
+ * DT_ALIAS. Each synthesized spec gets a `pwm-leds` child whose `pwms` cell
+ * binds the controller+channel (+ period/polarity), and a `tc-pwm<pin>`
+ * alias pointing at it. Alias/label names are valid DT identifiers (lowercase
+ * alphanumerics + dash/underscore).
+ */
+function emitPwmNodes(lines, chip, usedPins) {
+    const synthesized = (chip.pwm?.specs ?? []).filter((s) => s.controller && s.channel != null && !s.dtSpec).filter((s) => !usedPins || usedPins.includes(s.pin));
+    if (synthesized.length === 0)
+        return;
+    // Enable each distinct PWM controller node (idempotent when already okay).
+    for (const controller of [...new Set(synthesized.map((s) => s.controller))]) {
+        lines.push(`&${controller} {`);
+        lines.push('    status = "okay";');
+        lines.push('};');
+        lines.push('');
+    }
+    lines.push('/ {');
+    lines.push('    tc_pwm_leds: tc-pwm-leds {');
+    lines.push('        compatible = "pwm-leds";');
+    for (const s of synthesized) {
+        // 20 ms / 50 Hz default — the servo convention; the duty scaling in the
+        // lowering normalizes 0-255 against whatever period is baked in.
+        const period = s.periodNs ?? 20_000_000;
+        const polarity = s.polarity ?? 'PWM_POLARITY_NORMAL';
+        lines.push(`        tc_pwm_${s.pin}: pwm-led-${s.pin} {`);
+        lines.push(`            pwms = <&${s.controller} ${s.channel} ${period} ${polarity}>;`);
+        lines.push('        };');
+    }
+    lines.push('    };');
+    lines.push('    aliases {');
+    for (const s of synthesized) {
+        lines.push(`        tc-pwm${s.pin} = &tc_pwm_${s.pin};`);
+    }
+    lines.push('    };');
+    lines.push('};');
+    lines.push('');
+}
+/**
+ * Emit the ADC device-node enable (+ optional pinctrl override). The pinctrl
+ * override applies only when the descriptor's channels carry pinctrl labels
+ * AND the caller knows which pins the program reads (compile-time regen scans
+ * the emitted `__tc_adc<N>_setup()` calls); the prepare-time overlay omits it
+ * and the compile regen rewrites the file before west runs.
+ */
+function emitAdcNode(lines, chip, readPins) {
+    const adc = chip.adc;
+    const labeled = adc.channels.filter((c) => c.pinctrl);
+    const used = labeled.filter((c) => !readPins || readPins.includes(c.pin));
+    if (labeled.length > 0 && used.length > 0) {
+        lines.push(`&${adc.nodeLabel} {`);
+        lines.push('    status = "okay";');
+        lines.push(`    pinctrl-0 = <${used.map((c) => `&${c.pinctrl}`).join(' ')}>;`);
+        lines.push('    pinctrl-names = "default";');
+        lines.push('};');
+        lines.push('');
+        return;
+    }
+    lines.push(`&${adc.nodeLabel} {`);
+    lines.push('    status = "okay";');
+    lines.push('};');
+    lines.push('');
+}
 /**
  * Emit a display DT node definition. The node is attached to the profile's SPI
  * controller (default spi2, the ESP32's first user SPI controller) via a MIPI
@@ -177,6 +273,13 @@ function emitDisplayNode(lines, display, wiring, spiTouchCs) {
     lines.push(`        ${display.dtLabel}: display@0 {`);
     lines.push(`            compatible = "${compatible}";`);
     lines.push('            reg = <0>;');
+    if (wiring?.tearingEffectPin !== undefined) {
+        const tePin = wiring.tearingEffectPin;
+        // Tearing-effect input on the display node: GPIO_DT_SPEC_GET(
+        // DT_NODELABEL(display0), te_gpios) in the adapter. Opt-in —
+        // most modules don't break the TE pad out.
+        lines.push(`            te-gpios = <&${gpioController(tePin)} ${tePin} GPIO_ACTIVE_HIGH>;`);
+    }
     lines.push(`            mipi-max-frequency = <${freq}>;`);
     lines.push('            mipi-mode = "MIPI_DBI_MODE_SPI_4WIRE";');
     // Required by the lcd-controller binding (Zephyr 4.x): 0 = RGB565,

package/dist/framework.manifest.d.ts

@@ -1,41 +1,31 @@
 declare const _default: {
-    hal: {
-        [x: string]: {
-            supported: boolean;
-            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
-            partialCoverage: boolean;
-            unsupportedReason?: string | undefined;
-        };
-        raw?: unknown;
-    } & {
-        [k: string]: {
-            supported: boolean;
-            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
-            partialCoverage: boolean;
-            unsupportedReason?: string | undefined;
-        };
-    };
-    packageName: string;
     schemaVersion: 1;
     frameworkId: string;
+    packageName: string;
     canonical: boolean;
     displayName: string;
     description: string;
     implementationMode: "from-scratch" | "extends-canonical" | "extends-other";
     entrypoint: {
-        sourceExtension: "cpp" | "ino" | "cc" | "h";
         entrypointFunctionName: string;
         requiresLoopFunction: boolean;
+        sourceExtension: "cpp" | "ino" | "cc" | "h";
         generateHeaderFile: boolean;
         overrideBaseName?: string | undefined;
         outputSubdirectory?: string | undefined;
         customBridgeShim?: string | undefined;
     };
     profile: {
+        targets: string[];
         forcedIncludes: string[];
         symbolAliases: Record<string, string>;
-        targets: string[];
     };
+    hal: Record<string, {
+        supported: boolean;
+        ops: Record<string, "unsupported" | "supported" | "polyfill" | "probe-inconclusive" | "stub">;
+        partialCoverage: boolean;
+        unsupportedReason?: string | undefined;
+    }>;
     polyfills: {
         emitted: {
             id: string;
@@ -59,20 +49,20 @@ declare const _default: {
         reexportedFrom?: string | undefined;
     };
     typeEmission: {
-        needsIostream: boolean;
+        normalizeCppType: boolean;
+        mathHeader: "<math.h>" | "none" | "<Arduino.h>";
         needsStdString: boolean;
         needsStdVector: boolean;
+        needsIostream: boolean;
         needsStdFunction: boolean;
-        mathHeader: "none" | "<math.h>" | "<Arduino.h>";
-        normalizeCppType: boolean;
         stdlibSupport: {
             hasVector: boolean;
             hasString: boolean;
             hasIostream: boolean;
             hasExceptions: boolean;
             hasRTTI: boolean;
-            recommendedArrayImpl: "std_vector" | "static_array";
-            recommendedStringImpl: "std_string" | "static_string";
+            recommendedArrayImpl: "static_array" | "std_vector";
+            recommendedStringImpl: "static_string" | "std_string";
         };
     };
     ambientTypes: string[];
@@ -80,12 +70,6 @@ declare const _default: {
         hardwareTestGroups: string[];
         halResolutionTests: string[];
     };
-    doctor?: {
-        available: boolean;
-    } | undefined;
-    licenses?: {
-        available: boolean;
-    } | undefined;
     basedOn?: string | undefined;
     inheritsStrategyId?: string | undefined;
     libraryResolution?: {
@@ -95,6 +79,12 @@ declare const _default: {
         tryGenerateLibDecl: boolean;
         reexportedFrom?: string | undefined;
     } | undefined;
+    doctor?: {
+        available: boolean;
+    } | undefined;
+    licenses?: {
+        available: boolean;
+    } | undefined;
     compat?: {
         zephyr?: string | undefined;
     } | undefined;

package/dist/framework.manifest.js

@@ -45,8 +45,16 @@ export default defineFrameworkManifest({
     profile: {
         // Informational list of supported board targets. The manifest validator
         // never iterates this; chipForTarget (src/chips/index.ts) is the real
-        // resolver. ESP32-S3 + plain ESP32 added alongside the nRF52840 MVP target.
-        targets: ['xiao_ble', 'esp32s3_devkitc', 'esp32_devkitc'],
+        // resolver. ESP32-S3 + plain ESP32 added alongside the nRF52840 MVP target;
+        // rpi_pico / rpi_pico2 / esp32c3 / esp32c6 / blackpill_f411ce resolve via
+        // the board packages' zephyr chip data (resolveChipFromBoard), not the
+        // hardcoded chip registry.
+        targets: [
+            'xiao_ble', 'esp32s3_devkitc', 'esp32_devkitc',
+            'rpi_pico', 'rpi_pico2/rp2350a/m33',
+            'esp32c3_devkitm/esp32c3', 'esp32c6_devkitc/esp32c6/hpcore',
+            'blackpill_f411ce/stm32f411xe',
+        ],
         forcedIncludes: ['<zephyr/kernel.h>', '<zephyr/drivers/gpio.h>', '<cstdint>'],
         symbolAliases: {},
     },
@@ -204,7 +212,8 @@ export default defineFrameworkManifest({
             },
         },
         // ── Partial: WiFi (STA connect + scan + config via conn_mgr/net_mgmt) ────
-        // ESP32-S3 only — profileDiagnostics flags wifi usage on radioless chips.
+        // ESP32 family only (esp32, esp32s3, esp32c3, esp32c6) — profileDiagnostics
+        // flags wifi usage on radioless chips (nRF52840, RP2040/RP2350).
         // AP mode, credential persistence, static IP, and event callbacks deferred.
         wifi: {
             supported: true,

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { ZephyrStrategy as FrameworkStrategy } from './strategy.js';
 export { ZephyrStrategy } from './strategy.js';
 export { Toolchain } from './toolchain/index.js';
+export { writeProjectDebugArtifacts } from './toolchain/debug-config.js';
 export { runDoctor as doctor } from './doctor.js';
 export { runLicensesPresenter as licenses } from './licenses.js';
 export { chipForTarget, setActiveChip, getActiveChip, XIAO_BLE, } from './chips/index.js';

package/dist/index.js

@@ -8,6 +8,11 @@
 export { ZephyrStrategy as FrameworkStrategy } from './strategy.js';
 export { ZephyrStrategy } from './strategy.js';
 export { Toolchain } from './toolchain/index.js';
+// Create-time starter debug artifacts. The `cuttlefish create` flow reads this
+// optional named export off the loaded framework module (same loader pattern
+// as doctor/licenses) and calls it for freshly scaffolded projects, so F5 in
+// VS Code works before the first build. No-ops for non-GDB targets.
+export { writeProjectDebugArtifacts } from './toolchain/debug-config.js';
 // `cuttlefish doctor` — verify the installed Zephyr is reachable + inside the
 // declared compat range, and preview board-target normalization. Re-exported
 // under the dispatcher-facing alias `doctor` so the loader picks it up as

package/dist/lowering/adc.d.ts

@@ -4,11 +4,14 @@ import type { ZephyrChipDescriptor } from '../chips/types.js';
 export declare function adcChannelForPin(chip: ZephyrChipDescriptor, pin: number): number;
 /**
  * Emit the per-channel ADC setup state. One block per channel in the chip
- * descriptor, each guarded by a `static bool __tc_adc<N>_ready` so the first
- * read configures it and subsequent reads skip. Called from shimLines when
- * the program uses ADC.
+ * descriptor that the PROGRAM ACTUALLY READS (`usedPins`) — an unread
+ * channel's `static` setup function would trip -Wunused-function in the
+ * single generated TU. When `usedPins` is omitted (probe paths with no
+ * program), every descriptor channel is emitted. Each block is guarded by a
+ * `static bool __tc_adc<N>_ready` so the first read configures it and
+ * subsequent reads skip. Called from shimLines when the program uses ADC.
  */
-export declare function adcInitLines(chip: ZephyrChipDescriptor): string[];
+export declare function adcInitLines(chip: ZephyrChipDescriptor, usedPins?: ReadonlySet<number>): string[];
 /**
  * Resolve a HAL adc.* op to Zephyr C++.
  * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.

package/dist/lowering/adc.js

@@ -18,19 +18,30 @@ export function adcChannelForPin(chip, pin) {
 }
 /**
  * Emit the per-channel ADC setup state. One block per channel in the chip
- * descriptor, each guarded by a `static bool __tc_adc<N>_ready` so the first
- * read configures it and subsequent reads skip. Called from shimLines when
- * the program uses ADC.
+ * descriptor that the PROGRAM ACTUALLY READS (`usedPins`) — an unread
+ * channel's `static` setup function would trip -Wunused-function in the
+ * single generated TU. When `usedPins` is omitted (probe paths with no
+ * program), every descriptor channel is emitted. Each block is guarded by a
+ * `static bool __tc_adc<N>_ready` so the first read configures it and
+ * subsequent reads skip. Called from shimLines when the program uses ADC.
  */
-export function adcInitLines(chip) {
+export function adcInitLines(chip, usedPins) {
     const dev = `DEVICE_DT_GET(DT_NODELABEL(${chip.adc?.nodeLabel ?? 'adc'}))`;
     const res = chip.adc?.resolution ?? 12;
     const vref = chip.adc?.vrefMv ?? 3000;
+    // Gain/reference are SoC-specific: the nRF SAADC scheme (gain 1/4 against
+    // the 0.6V internal ref, vref-mv 3000 = VDD) is the default; the STM32
+    // driver requires exactly ADC_GAIN_1 + ADC_REF_INTERNAL (Zephyr maps
+    // "internal" to the VREF+ pad) with vref-mv = VDDA. The descriptor carries
+    // the SoC's pair so the emitted channel setup validates in the driver.
+    const gain = chip.adc?.gain ?? 'ADC_GAIN_1_4';
+    const reference = chip.adc?.reference ?? 'ADC_REF_INTERNAL';
+    const channels = (chip.adc?.channels ?? []).filter((c) => !usedPins || usedPins.has(c.pin));
     const lines = ['// CUTTLEFISH_ADC_BEGIN'];
     lines.push(`static const struct device* __tc_adc_dev = ${dev};`);
-    for (const c of chip.adc?.channels ?? []) {
+    for (const c of channels) {
         const n = c.channel;
-        lines.push(`static bool __tc_adc${n}_ready = false;`, `static void __tc_adc${n}_setup(void) {`, `    if (__tc_adc${n}_ready) return;`, `    const struct adc_channel_cfg cfg = {`, `        .gain = ADC_GAIN_1_4,`, `        .reference = ADC_REF_INTERNAL,`, `        .acquisition_time = ADC_ACQ_TIME_DEFAULT,`, `        .channel_id = ${n},`, `        .differential = 0,`, `    };`, `    adc_channel_setup(__tc_adc_dev, &cfg);`, `    __tc_adc${n}_ready = true;`, `}`);
+        lines.push(`static bool __tc_adc${n}_ready = false;`, `static void __tc_adc${n}_setup(void) {`, `    if (__tc_adc${n}_ready) return;`, `    const struct adc_channel_cfg cfg = {`, `        .gain = ${gain},`, `        .reference = ${reference},`, `        .acquisition_time = ADC_ACQ_TIME_DEFAULT,`, `        .channel_id = ${n},`, `        .differential = 0,`, `    };`, `    adc_channel_setup(__tc_adc_dev, &cfg);`, `    __tc_adc${n}_ready = true;`, `}`);
     }
     lines.push(`#define __TC_ADC_VREF_MV ${vref}`);
     lines.push(`#define __TC_ADC_RESOLUTION ${res}`);
@@ -45,6 +56,8 @@ export function lowerAdc(op, chip) {
     const o = op;
     const res = chip.adc?.resolution ?? 12;
     const vref = chip.adc?.vrefMv ?? 3000;
+    const gain = chip.adc?.gain ?? 'ADC_GAIN_1_4';
+    const reference = chip.adc?.reference ?? 'ADC_REF_INTERNAL';
     switch (op.operation) {
         case 'adc.read': {
             const ch = adcChannelForPin(chip, o.pin);
@@ -55,10 +68,11 @@ export function lowerAdc(op, chip) {
         }
         case 'adc.read_voltage': {
             const ch = adcChannelForPin(chip, o.pin);
-            // Read raw, convert to millivolts via adc_raw_to_millivolts (gain 1/4,
-            // internal ref). Returns mV as int.
+            // Read raw, convert to millivolts via adc_raw_to_millivolts with the
+            // descriptor's gain (raw_to_millivolts divides out the gain the channel
+            // was set up with). Returns mV as int.
             return {
-                expression: `({ __tc_adc${ch}_setup(); int16_t __b = 0; struct adc_sequence __s = { .channels = BIT(${ch}), .buffer = &__b, .buffer_size = sizeof(__b), .resolution = ${res} }; adc_read(__tc_adc_dev, &__s); int32_t __v = __b; adc_raw_to_millivolts(${vref}, ADC_GAIN_1_4, ${res}, &__v); __v; })`,
+                expression: `({ __tc_adc${ch}_setup(); int16_t __b = 0; struct adc_sequence __s = { .channels = BIT(${ch}), .buffer = &__b, .buffer_size = sizeof(__b), .resolution = ${res} }; adc_read(__tc_adc_dev, &__s); int32_t __v = __b; adc_raw_to_millivolts(${vref}, ${gain}, ${res}, &__v); __v; })`,
             };
         }
         case 'adc.get_resolution':
@@ -66,9 +80,9 @@ export function lowerAdc(op, chip) {
         case 'adc.set_reference':
             // Zephyr configures the reference at channel-setup time; runtime switching
             // would require re-setup. Record the intent as a no-op statement.
-            return { code: `/* adc.set_reference(${o.reference}): configured at channel setup (ADC_REF_INTERNAL) */` };
+            return { code: `/* adc.set_reference(${o.reference}): configured at channel setup (${reference}) */` };
         case 'adc.get_reference':
-            return { expression: `0 /* DEFAULT (ADC_REF_INTERNAL) */` };
+            return { expression: `0 /* DEFAULT (${reference}) */` };
         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/gpio.js

@@ -14,7 +14,7 @@
 //     The manifest validator's probe (which sends {operation, pin:0} with no
 //     port) hits this path, so it must return a lowered result, not undefined.
 // ---------------------------------------------------------------------------
-import { controllerNodelabelForPin } from '../chips/controllers.js';
+import { controllerNodelabelForPin, controllerRawPinForPin } from '../chips/controllers.js';
 /** The C identifier emitted for a pin's gpio_dt_spec variable. */
 export function dtSpecVarName(dtSpec) {
     return `__tc_dt_${dtSpec}`;
@@ -99,23 +99,30 @@ function lowerGpioRaw(op, chip) {
     const o = op;
     const pin = o.pin;
     // Resolve the owning controller by pin range (ESP32-S3 splits GPIO across
-    // gpio0/gpio1). For single-controller SoCs this is just chip.gpioController.
+    // gpio0/gpio1; STM32 across gpioa/gpiob/gpioc). For single-controller SoCs
+    // this is just chip.gpioController. The raw API takes the PORT-RELATIVE
+    // index (STM32 gpiob is 0-15), not the global HAL pin number.
     const controller = `DEVICE_DT_GET(DT_NODELABEL(${controllerNodelabelForPin(chip, pin)}))`;
+    const rawPin = controllerRawPinForPin(chip, pin);
     switch (op.operation) {
         case 'gpio.set_mode': {
-            return { code: `gpio_pin_configure(${controller}, ${pin}, ${flagsForMode(o.mode)});` };
+            return { code: `gpio_pin_configure(${controller}, ${rawPin}, ${flagsForMode(o.mode)});` };
         }
         case 'gpio.write': {
             const v = o.value;
             const rhs = typeof v === 'string' ? `((${v}) ? 1 : 0)` : v ? 1 : 0;
-            return { code: `gpio_pin_set_raw(${controller}, ${pin}, ${rhs});` };
+            return { code: `gpio_pin_set_raw(${controller}, ${rawPin}, ${rhs});` };
         }
         case 'gpio.read':
-            return { expression: `gpio_pin_get_raw(${controller}, ${pin})` };
+            return { expression: `gpio_pin_get_raw(${controller}, ${rawPin})` };
         case 'gpio.toggle':
-            return {
-                code: `gpio_pin_set_raw(${controller}, ${pin}, !gpio_pin_get_raw(${controller}, ${pin}));`,
-            };
+            // Native atomic toggle — never read-modify-write. gpio_pin_get_raw on
+            // a direction-only output reads the input latch, which is undefined on
+            // SoCs that don't latch it. Zephyr's toggle API has no _raw variant —
+            // gpio_pin_toggle is the driver-level atomic toggle, and for pins
+            // configured without GPIO_ACTIVE_LOW the logical level equals the
+            // physical one, so it matches the get_raw/set_raw used elsewhere.
+            return { code: `gpio_pin_toggle(${controller}, ${rawPin});` };
         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/mqtt.js

@@ -290,7 +290,15 @@ export function mqttInitLines() {
         `    (void)k_thread_create(&__tc_mqtt.poll_thread, __tc_mqtt_stack,`,
         `                          K_THREAD_STACK_SIZEOF(__tc_mqtt_stack),`,
         `                          __tc_mqtt_poll_thread, nullptr, nullptr, nullptr,`,
-        `                          5, 0, K_NO_WAIT);`,
+        `                          5, 0, K_FOREVER);`,
+        `#ifdef CONFIG_SMP`,
+        `    // On SMP targets park the poll thread on the app core so the network`,
+        `    // stack never competes with the main/UI thread for core 0. k_thread_cpu_pin`,
+        `    // is SMP-only; the pin happens before k_thread_start (which is why the`,
+        `    // thread is created K_FOREVER). Compiles away on !SMP builds.`,
+        `    (void)k_thread_cpu_pin(&__tc_mqtt.poll_thread, 1);`,
+        `#endif`,
+        `    k_thread_start(&__tc_mqtt.poll_thread);`,
         `}`,
         ``,
         `static inline void __tc_mqtt_set_on_message(__tc_mqtt_msg_cb_t fn) {`,

package/dist/lowering/pulse.js

@@ -7,7 +7,7 @@
 // implementations (no hardware pulse capture on nRF for the HAL surface); they
 // are correct but not high-precision.
 // ---------------------------------------------------------------------------
-import { controllerNodelabelForPin } from '../chips/controllers.js';
+import { controllerNodelabelForPin, controllerRawPinForPin } from '../chips/controllers.js';
 /** `DEVICE_DT_GET(DT_NODELABEL(<owning-controller>))` for a HAL pin. */
 function devForPin(chip, pin) {
     return `DEVICE_DT_GET(DT_NODELABEL(${controllerNodelabelForPin(chip, pin)}))`;
@@ -23,9 +23,9 @@ export function lowerPulseOrShift(op, chip) {
             // for the start edge is bounded by the timeout; the measurement of the
             // pulse itself is intentionally unbounded (that IS the pulse length).
             // Returns -1 (0) if the start edge never arrives within the timeout.
-            const pin = o.pin;
+            const pin = controllerRawPinForPin(chip, o.pin);
             const want = o.value;
-            const dev = devForPin(chip, pin);
+            const dev = devForPin(chip, o.pin);
             const timeout = o.timeout ?? 1_000_000; // default 1s in us
             return {
                 expression: `({ int64_t __max = static_cast<int64_t>(${timeout} / 1000); int64_t __t0 = k_uptime_get(); bool __ok = true; while (gpio_pin_get_raw(${dev}, ${pin}) != ${want}) { if ((k_uptime_get() - __t0) > __max) { __ok = false; break; } } int32_t __ret = 0; if (__ok) { int64_t __start = k_uptime_get(); while (gpio_pin_get_raw(${dev}, ${pin}) == ${want}) { } __ret = static_cast<int32_t>((k_uptime_get() - __start) * 1000); } __ret; })`,
@@ -36,9 +36,9 @@ export function lowerPulseOrShift(op, chip) {
             // with NO timeout (the comment claimed "no overflow concern" but the
             // real risk was hanging the thread on a stuck pin). Apply the same
             // timeout-bounded start-edge wait as pulse.in (bug Q5).
-            const pin = o.pin;
+            const pin = controllerRawPinForPin(chip, o.pin);
             const want = o.value;
-            const dev = devForPin(chip, pin);
+            const dev = devForPin(chip, o.pin);
             const timeout = o.timeout ?? 3_000_000; // default 3s in us (long pulses)
             return {
                 expression: `({ int64_t __max = static_cast<int64_t>(${timeout} / 1000); int64_t __t0 = k_uptime_get(); bool __ok = true; while (gpio_pin_get_raw(${dev}, ${pin}) != ${want}) { if ((k_uptime_get() - __t0) > __max) { __ok = false; break; } } int32_t __ret = 0; if (__ok) { int64_t __start = k_uptime_get(); while (gpio_pin_get_raw(${dev}, ${pin}) == ${want}) { } __ret = static_cast<int32_t>((k_uptime_get() - __start) * 1000); } __ret; })`,
@@ -57,7 +57,7 @@ export function lowerPulseOrShift(op, chip) {
             const test = msbFirst ? '(__i >= 0)' : '(__i < 8)';
             const step = msbFirst ? '__i--' : '__i++';
             return {
-                code: `for (int __i = ${init}; ${test}; ${step}) { gpio_pin_set_raw(${dataDev}, ${dataPin}, (${o.value} >> __i) & 1); gpio_pin_set_raw(${clockDev}, ${clockPin}, 1); k_busy_wait(1); gpio_pin_set_raw(${clockDev}, ${clockPin}, 0); }`,
+                code: `for (int __i = ${init}; ${test}; ${step}) { gpio_pin_set_raw(${dataDev}, ${controllerRawPinForPin(chip, dataPin)}, (${o.value} >> __i) & 1); gpio_pin_set_raw(${clockDev}, ${controllerRawPinForPin(chip, clockPin)}, 1); k_busy_wait(1); gpio_pin_set_raw(${clockDev}, ${controllerRawPinForPin(chip, clockPin)}, 0); }`,
             };
         }
         case 'shift.in': {
@@ -72,7 +72,7 @@ export function lowerPulseOrShift(op, chip) {
             const step = msbFirst ? '__i--' : '__i++';
             const accum = msbFirst ? '__v = (__v << 1)' : '__v |= (bit << __i)';
             return {
-                expression: `({ uint8_t __v = 0; for (int __i = ${init}; ${test}; ${step}) { gpio_pin_set_raw(${clockDev}, ${clockPin}, 1); k_busy_wait(1); int bit = gpio_pin_get_raw(${dataDev}, ${dataPin}); gpio_pin_set_raw(${clockDev}, ${clockPin}, 0); ${accum}; } __v; })`,
+                expression: `({ uint8_t __v = 0; for (int __i = ${init}; ${test}; ${step}) { gpio_pin_set_raw(${clockDev}, ${controllerRawPinForPin(chip, clockPin)}, 1); k_busy_wait(1); int bit = gpio_pin_get_raw(${dataDev}, ${controllerRawPinForPin(chip, dataPin)}); gpio_pin_set_raw(${clockDev}, ${controllerRawPinForPin(chip, clockPin)}, 0); ${accum}; } __v; })`,
             };
         }
         default:

package/dist/lowering/pwm.d.ts

@@ -1,10 +1,28 @@
 import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
-import type { ZephyrChipDescriptor } from '../chips/types.js';
+import type { ZephyrChipDescriptor, ZephyrPwmSpec } from '../chips/types.js';
+/**
+ * The DT alias a PWM spec is addressed by. Board-shipped specs carry their
+ * alias in `dtSpec`; synthesized specs (controller + channel) get a
+ * `tc-pwm<pin>` alias that the overlay generator creates in
+ * <board>.overlay — both sides derive the name from the pin so they agree.
+ */
+export declare function pwmDtAlias(spec: ZephyrPwmSpec): string;
+/**
+ * The C macro token for a spec's alias. Zephyr's devicetree macros replace
+ * dashes in alias names with underscores (`pwm-led0` in DTS is
+ * DT_ALIAS(pwm_led0) in C) — the dashed spelling is a subtraction
+ * expression and fails to compile (caught by the blackpill E2E west build).
+ */
+export declare function pwmDtAliasToken(spec: ZephyrPwmSpec): string;
 /**
  * Emit the per-channel PWM spec declarations. One per spec in the chip
- * descriptor. Called from shimLines when the program uses PWM.
+ * descriptor that the PROGRAM ACTUALLY DRIVES (`usedPins`) — a spec for an
+ * untouched pin is unused code in the emitted TU (and would need a dead DT
+ * alias in the overlay). When `usedPins` is omitted (probe paths with no
+ * program), every spec is emitted. Called from shimLines when the program
+ * uses PWM.
  */
-export declare function pwmInitLines(chip: ZephyrChipDescriptor): string[];
+export declare function pwmInitLines(chip: ZephyrChipDescriptor, usedPins?: ReadonlySet<number>): string[];
 /**
  * Resolve a HAL pwm.* op to Zephyr C++.
  * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.

package/dist/lowering/pwm.js

@@ -6,22 +6,46 @@
 // `pwm_set_pulse_dt` / `pwm_set_dt`. Duty is scaled from the Arduino-style
 // 0–255 (or 0–1023) range to nanoseconds against the spec's period.
 // ---------------------------------------------------------------------------
+/**
+ * The DT alias a PWM spec is addressed by. Board-shipped specs carry their
+ * alias in `dtSpec`; synthesized specs (controller + channel) get a
+ * `tc-pwm<pin>` alias that the overlay generator creates in
+ * <board>.overlay — both sides derive the name from the pin so they agree.
+ */
+export function pwmDtAlias(spec) {
+    return spec.dtSpec ?? `tc-pwm${spec.pin}`;
+}
+/**
+ * The C macro token for a spec's alias. Zephyr's devicetree macros replace
+ * dashes in alias names with underscores (`pwm-led0` in DTS is
+ * DT_ALIAS(pwm_led0) in C) — the dashed spelling is a subtraction
+ * expression and fails to compile (caught by the blackpill E2E west build).
+ */
+export function pwmDtAliasToken(spec) {
+    return pwmDtAlias(spec).replace(/-/g, '_');
+}
 /** Look up a PWM spec by HAL pin number. */
 function findPwmSpec(chip, pin) {
     return chip.pwm?.specs.find((s) => s.pin === pin);
 }
 /** The C variable name emitted for a PWM channel's spec. */
 function pwmVarName(spec) {
-    return `__tc_pwm_${spec.dtSpec.replace(/-/g, '_')}`;
+    return `__tc_pwm_${pwmDtAliasToken(spec)}`;
 }
 /**
  * Emit the per-channel PWM spec declarations. One per spec in the chip
- * descriptor. Called from shimLines when the program uses PWM.
+ * descriptor that the PROGRAM ACTUALLY DRIVES (`usedPins`) — a spec for an
+ * untouched pin is unused code in the emitted TU (and would need a dead DT
+ * alias in the overlay). When `usedPins` is omitted (probe paths with no
+ * program), every spec is emitted. Called from shimLines when the program
+ * uses PWM.
  */
-export function pwmInitLines(chip) {
+export function pwmInitLines(chip, usedPins) {
     const lines = ['// CUTTLEFISH_PWM_BEGIN'];
     for (const spec of chip.pwm?.specs ?? []) {
-        lines.push(`static const struct pwm_dt_spec ${pwmVarName(spec)} = PWM_DT_SPEC_GET(DT_ALIAS(${spec.dtSpec}));`);
+        if (usedPins && !usedPins.has(spec.pin))
+            continue;
+        lines.push(`static const struct pwm_dt_spec ${pwmVarName(spec)} = PWM_DT_SPEC_GET(DT_ALIAS(${pwmDtAliasToken(spec)}));`);
     }
     lines.push('// CUTTLEFISH_PWM_END');
     return lines;

package/dist/lowering/spi.js

@@ -12,7 +12,7 @@
 // DEVICE_DT_GET(DT_NODELABEL(spi2)) and call spi_transceive directly.
 // ---------------------------------------------------------------------------
 import { parseControllerIndex } from './util.js';
-import { controllerNodelabelForPin } from '../chips/controllers.js';
+import { controllerNodelabelForPin, controllerRawPinForPin } from '../chips/controllers.js';
 /** The C variable prefix for a controller's state. */
 function prefix(idx) {
     return `__tc_spi${idx}`;
@@ -103,7 +103,7 @@ export function lowerSpi(op, chip) {
             const val = op.operation === 'spi.cs_low' ? 0 : 1;
             const gpioController = controllerNodelabelForPin(chip, o.pin);
             return {
-                code: `gpio_pin_set_raw(DEVICE_DT_GET(DT_NODELABEL(${gpioController})), ${o.pin}, ${val});`,
+                code: `gpio_pin_set_raw(DEVICE_DT_GET(DT_NODELABEL(${gpioController})), ${controllerRawPinForPin(chip, o.pin)}, ${val});`,
             };
         }
         default:

package/dist/lowering/tone.js

@@ -11,6 +11,7 @@
 // matching the synchronous Arduino tone() semantics. For non-blocking tone,
 // a workqueue would be needed (deferred).
 // ---------------------------------------------------------------------------
+import { pwmDtAliasToken } from './pwm.js';
 /**
  * Resolve a HAL tone.* op to Zephyr C++ via PWM.
  * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
@@ -26,7 +27,7 @@ export function lowerTone(op, chip) {
             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);`;
@@ -40,7 +41,7 @@ export function lowerTone(op, chip) {
             const spec = chip.pwm?.specs[0];
             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: