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

package/src/chips/xiao-ble.ts

@@ -1,70 +1,82 @@
-// ---------------------------------------------------------------------------
-// Seeed Studio XIAO nRF52840 — Zephyr board descriptor
-//
-// Board target: `xiao_ble` (mainline Zephyr, boards/seeed/xiao_ble).
-// The onboard user LED is active-low and exposed as the DT alias `led0`.
-// ---------------------------------------------------------------------------
-
-import type { ZephyrChipDescriptor } from './types.js';
-
-export const XIAO_BLE: ZephyrChipDescriptor = {
-  id: 'xiao_ble',
-  soc: 'nrf52840',
-  gpioController: 'gpio0',
-  gpio: {
-    dtSpecs: [
-      // Onboard RGB LEDs — active-low (GPIO_ACTIVE_LOW in xiao_ble_common.dtsi).
-      // Verified against the board's `aliases { led0 = &led0; led1 = &led1; led2 = &led2; }`.
-      { pin: 26, dtSpec: 'led0' },  // Red   (P0.26)
-      { pin: 30, dtSpec: 'led1' },  // Green (P0.30)
-      { pin: 6, dtSpec: 'led2' },   // Blue  (P0.06)
-    ],
-    // The XIAO nRF52840 has a user button on P0.04, but mainline Zephyr's
-    // xiao_ble board (verified against Zephyr 4.3.99) does NOT expose it as a
-    // DT `sw0` alias — there is no gpio-keys node in xiao_ble.dts. Emitting
-    // GPIO_DT_SPEC_GET(DT_ALIAS(sw0), gpios) therefore fails to compile
-    // ('DT_N_ALIAS_sw0_... was not declared'). Until a button node + alias is
-    // added (via an overlay or an upstream board update), interruptPins stays
-    // empty: attachInterrupt on this board lowers to the no-DT-spec comment
-    // fallback rather than a hard compile error.
-    interruptPins: [],
-  },
-  // The XIAO connector wiring (from seeed_xiao_connector.dtsi + xiao_ble-pinctrl.dtsi):
-  //   xiao_i2c     → i2c1  (SDA P0.04/D4, SCL P0.05/D5)
-  //   xiao_spi     → spi2  (SCK P1.13/D8, MOSI P1.15/D10, MISO P1.14/D9)
-  //   xiao_serial  → uart0 (TX P1.11/D6, RX P1.12/D7)
-  // The board DTS leaves i2c0/spi0/spi1 disabled (shared instances).
-  i2c: {
-    controllers: [{ nodeLabel: 'i2c1' }],
-  },
-  spi: {
-    controllers: [{ nodeLabel: 'spi2' }],
-  },
-  uart: {
-    controllers: [{ nodeLabel: 'uart0' }],
-  },
-  pwm: {
-    // pwm-led0 drives the board PWM LED (PWM_OUT0 on P0.17, inverted).
-    specs: [{ pin: 17, dtSpec: 'pwm-led0' }],
-  },
-  adc: {
-    // SAADC node is `adc`; no pre-declared channels. XIAO D0–D3 = AIN0–AIN3
-    // (P0.02/P0.03/P0.28/P0.29). Internal VREF ~0.6V with VDD/4 gain ⇒ 3000mV.
-    nodeLabel: 'adc',
-    resolution: 12,
-    vrefMv: 3000,
-    channels: [
-      { pin: 2, channel: 0 },   // P0.02 / D0 / AIN0
-      { pin: 3, channel: 1 },   // P0.03 / D1 / AIN1
-      { pin: 28, channel: 2 },  // P0.28 / D2 / AIN2
-      { pin: 29, channel: 3 },  // P0.29 / D3 / AIN3
-    ],
-  },
-  wdt: { nodeLabel: 'wdt0' },
-  // Hardware timer: nRF RTC1 is the free counter (RTC0 is kernel-owned by the
-  // softdevice/clock driver). The hwtimer lowering drives it as a Zephyr
-  // counter device (counter_start/stop + a top-value alarm for set_frequency).
-  // Verified against the nRF52840 SoC dtsi (rtc0/rtc1 nodes). The kernel uses
-  // RTC0 for the system tick; RTC1 is available for application use.
-  hwtimer: { controllers: [{ nodeLabel: 'rtc1' }] },
-};
+// ---------------------------------------------------------------------------
+// Seeed Studio XIAO nRF52840 — Zephyr board descriptor
+//
+// Board target: `xiao_ble` (mainline Zephyr, boards/seeed/xiao_ble).
+// The onboard user LED is active-low and exposed as the DT alias `led0`.
+// ---------------------------------------------------------------------------
+
+import type { ZephyrChipDescriptor } from './types.js';
+
+export const XIAO_BLE: ZephyrChipDescriptor = {
+  id: 'xiao_ble',
+  soc: 'nrf52840',
+  gpioController: 'gpio0',
+    // GPIO is split across two devicetree controllers: gpio0 (P0.00–P0.31)
+    // and gpio1 (P1.00–P1.15, HAL pins 32–47). Declaring the split makes the
+    // raw path emit the port-relative index against gpio1 (P1.11 = raw 11),
+    // which NRF_GPIO_PIN_MAP(1, 11) resolves to absolute pin 43 — the same
+    // physical pin the old single-controller form reached only by accident:
+    // gpio0 + global 43 also maps to 43 (MAP(0, 43) = 43), but that form
+    // trips the generic layer's port_pin_mask __ASSERT ("Unsupported pin",
+    // gpio0's mask covers 0–31) on any assert-enabled build.
+  gpioControllers: [
+    { nodelabel: 'gpio0', minPin: 0, maxPin: 31 },
+    { nodelabel: 'gpio1', minPin: 32, maxPin: 47 },
+  ],
+  gpio: {
+    dtSpecs: [
+      // Onboard RGB LEDs — active-low (GPIO_ACTIVE_LOW in xiao_ble_common.dtsi).
+      // Verified against the board's `aliases { led0 = &led0; led1 = &led1; led2 = &led2; }`.
+      { pin: 26, dtSpec: 'led0' },  // Red   (P0.26)
+      { pin: 30, dtSpec: 'led1' },  // Green (P0.30)
+      { pin: 6, dtSpec: 'led2' },   // Blue  (P0.06)
+    ],
+    // The XIAO nRF52840 has a user button on P0.04, but mainline Zephyr's
+    // xiao_ble board (verified against Zephyr 4.3.99) does NOT expose it as a
+    // DT `sw0` alias — there is no gpio-keys node in xiao_ble.dts. Emitting
+    // GPIO_DT_SPEC_GET(DT_ALIAS(sw0), gpios) therefore fails to compile
+    // ('DT_N_ALIAS_sw0_... was not declared'). Until a button node + alias is
+    // added (via an overlay or an upstream board update), interruptPins stays
+    // empty: attachInterrupt on this board lowers to the no-DT-spec comment
+    // fallback rather than a hard compile error.
+    interruptPins: [],
+  },
+  // The XIAO connector wiring (from seeed_xiao_connector.dtsi + xiao_ble-pinctrl.dtsi):
+  //   xiao_i2c     → i2c1  (SDA P0.04/D4, SCL P0.05/D5)
+  //   xiao_spi     → spi2  (SCK P1.13/D8, MOSI P1.15/D10, MISO P1.14/D9)
+  //   xiao_serial  → uart0 (TX P1.11/D6, RX P1.12/D7)
+  // The board DTS leaves i2c0/spi0/spi1 disabled (shared instances).
+  i2c: {
+    controllers: [{ nodeLabel: 'i2c1' }],
+  },
+  spi: {
+    controllers: [{ nodeLabel: 'spi2' }],
+  },
+  uart: {
+    controllers: [{ nodeLabel: 'uart0' }],
+  },
+  pwm: {
+    // pwm-led0 drives the board PWM LED (PWM_OUT0 on P0.17, inverted).
+    specs: [{ pin: 17, dtSpec: 'pwm-led0' }],
+  },
+  adc: {
+    // SAADC node is `adc`; no pre-declared channels. XIAO D0–D3 = AIN0–AIN3
+    // (P0.02/P0.03/P0.28/P0.29). Internal VREF ~0.6V with VDD/4 gain ⇒ 3000mV.
+    nodeLabel: 'adc',
+    resolution: 12,
+    vrefMv: 3000,
+    channels: [
+      { pin: 2, channel: 0 },   // P0.02 / D0 / AIN0
+      { pin: 3, channel: 1 },   // P0.03 / D1 / AIN1
+      { pin: 28, channel: 2 },  // P0.28 / D2 / AIN2
+      { pin: 29, channel: 3 },  // P0.29 / D3 / AIN3
+    ],
+  },
+  wdt: { nodeLabel: 'wdt0' },
+  // Hardware timer: nRF RTC1 is the free counter (RTC0 is kernel-owned by the
+  // softdevice/clock driver). The hwtimer lowering drives it as a Zephyr
+  // counter device (counter_start/stop + a top-value alarm for set_frequency).
+  // Verified against the nRF52840 SoC dtsi (rtc0/rtc1 nodes). The kernel uses
+  // RTC0 for the system tick; RTC1 is available for application use.
+  hwtimer: { controllers: [{ nodeLabel: 'rtc1' }] },
+};

package/src/display/index.ts

@@ -18,7 +18,7 @@ import { DEFAULT_ZEPHYR_DISPLAY_PROFILE, type ZephyrDisplayProfile } from './pro
 // and consumers can reach them from the package barrel.
 export { zephyrUiDisplayAdapter, zephyrDisplayAdapterGenerator } from './ui-adapter.js';
 export { zephyrTouchAdapter } from './touch-adapter.js';
-export { ZEPHYR_DISPLAY_PROFILES, DEFAULT_ZEPHYR_DISPLAY_PROFILE } from './profiles.js';
+export { ZEPHYR_DISPLAY_PROFILES, DEFAULT_ZEPHYR_DISPLAY_PROFILE, BUILT_IN_PROFILES } from './profiles.js';
 export type { ZephyrDisplayProfile } from './profiles.js';
 
 export interface DisplayState {

package/src/display/profiles.ts

@@ -114,3 +114,26 @@ export const ZEPHYR_DISPLAY_PROFILES: Record<string, ZephyrDisplayProfile> = {
 /** The default profile used when resolveDisplayOp is probed without a display.init. */
 export const DEFAULT_ZEPHYR_DISPLAY_PROFILE: ZephyrDisplayProfile =
   ZEPHYR_DISPLAY_PROFILES['ili9341-zephyr'];
+
+/**
+ * The Zephyr profiles mapped to the shared DisplayProfile shape — the single
+ * mapping, so no consumer needs to know the DT-binding descriptor layout.
+ * The strategy's getProfileRegistry() and the preview's profile-registry
+ * loader both consume this (the same role `BUILT_IN_PROFILES` plays in
+ * framework-arduino's displays modules).
+ */
+export const BUILT_IN_PROFILES: Record<string, import('@typecad/cuttlefish/api/shared').DisplayProfile> =
+  Object.fromEntries(
+    Object.entries(ZEPHYR_DISPLAY_PROFILES).map(([name, p]) => [
+      name,
+      {
+        driver: p.driver,
+        width: p.width,
+        height: p.height,
+        nativeWidth: p.nativeWidth,
+        nativeHeight: p.nativeHeight,
+        colorFormat: p.colorFormat,
+        rotation: p.rotation ?? 1,
+      },
+    ]),
+  );

package/src/display/ui-adapter.ts

@@ -46,6 +46,10 @@ export interface ZephyrDisplayReadbackOptions {
   scanlineSync?: boolean;
   /** MISO/SDO GPIO; readback is disabled when it is not explicitly wired. */
   miso?: number;
+  /** Tearing-effect GPIO (panel TE output). When set, panel updates wait for
+   *  the TE frame pulse instead of GET_SCANLINE readback — no MISO required.
+   *  The overlay adds te-gpios to the display DT node from this. */
+  tearingEffectPin?: number;
 }
 
 export function zephyrUiDisplayAdapter(
@@ -74,6 +78,9 @@ export function zephyrUiDisplayAdapter(
   // react badly to GSCAN reads. Both an explicit opt-in and an explicit MISO
   // pin are required before emitting an active synchronization path.
   const scanlineSync = readback.scanlineSync === true && readback.miso !== undefined;
+  // TE (hardware tearing-effect) sync: strictly opt-in via a configured GPIO.
+  // Preferred over GET_SCANLINE when wired — no readback traffic, no MISO.
+  const tePin = typeof readback.tearingEffectPin === 'number' ? readback.tearingEffectPin : undefined;
 
   const includes = [
     `// --- Zephyr UI display adapter (${profile.driver}) ---`,
@@ -140,6 +147,22 @@ export function zephyrUiDisplayAdapter(
     `// controller-specific validation are required; otherwise the display stays`,
     `// on the existing retained/composited path with no extra SPI reads.`,
     `static const bool __tc_pnl_scanline_sync = ${scanlineSync ? 'true' : 'false'};`,
+    `// Tearing-effect (TE) hardware sync: the panel pulses its TE line once`,
+    `// per frame. When te-gpios is present on the display DT node, panel`,
+    `// updates arm on the TE edge — tear-free writes with no MISO readback.`,
+    `#if DT_NODE_HAS_PROP(DT_NODELABEL(${dtLabel}), te_gpios)`,
+    `#define __TC_TE_SYNC 1`,
+    `static const struct gpio_dt_spec __tc_te =`,
+    `    GPIO_DT_SPEC_GET(DT_NODELABEL(${dtLabel}), te_gpios);`,
+    `static struct gpio_callback __tc_te_cb;`,
+    `static volatile uint32_t __tc_te_count = 0;`,
+    `static void __tc_te_isr(const struct device* port, struct gpio_callback* cb, uint32_t pins) {`,
+    `    (void)port; (void)cb; (void)pins;`,
+    `    __tc_te_count++;`,
+    `}`,
+    `#else`,
+    `#define __TC_TE_SYNC 0`,
+    `#endif`,
     `// Stashed address window from the last setAddrWindow call. The runtime`,
     `// calls setAddrWindow + writePixels as a matched pair, so we stash the rect`,
     `// here and consume it in writePixels.`,
@@ -157,6 +180,18 @@ export function zephyrUiDisplayAdapter(
   // with DT_HAS_ALIAS (the safe primitive for an alias that may be absent —
   // DT_NODE_HAS_STATUS(DT_ALIAS(...)) is version-dependent when the alias is
   // missing and can fail the build).
+  // TE pin: input + rising-edge interrupt (the ST7796 TE pulse), then tell
+  // the controller to drive the line (TEON 0x35, mode 1 = vertical sync only).
+  const teInit = tePin !== undefined ? `#if __TC_TE_SYNC
+    if (device_is_ready(__tc_te.port)) {
+      gpio_pin_configure_dt(&__tc_te, GPIO_INPUT);
+      gpio_init_callback(&__tc_te_cb, __tc_te_isr, BIT(__tc_te.pin));
+      (void)gpio_add_callback(__tc_te.port, &__tc_te_cb);
+      (void)gpio_pin_interrupt_configure_dt(&__tc_te, GPIO_INT_EDGE_RISING);
+      __tc_pnl_cmd1(0x35, 0x01); // TEON: TE output = vsync pulse
+    }
+#endif` : '';
+
   const blInit = backlightAlias
     ? `#if DT_HAS_ALIAS(${backlightAlias})\n    const struct gpio_dt_spec __bl = GPIO_DT_SPEC_GET(DT_ALIAS(${backlightAlias}), gpios);\n    if (device_is_ready(__bl.port)) { gpio_pin_configure_dt(&__bl, GPIO_OUTPUT_ACTIVE); }\n#endif`
     : '';
@@ -479,6 +514,19 @@ static uint16_t __tc_pnl_read_scanline(void) {
 // have no safe post-rectangle interval, so they retain the normal single-burst
 // behavior; the caller's framebuffer still prevents intermediate software frames.
 static void __tc_pnl_wait_for_safe_rect(int16_t y, int16_t rh) {
+#if __TC_TE_SYNC
+  // TE variant: arm on the next frame pulse, then start the burst — the write
+  // chases the scan beam from the top of the rect. Bounded so a stuck TE line
+  // can never hang the UI loop.
+  if (rh < 8 || y < 0) return;
+  uint32_t __was = __tc_te_count;
+  uint32_t __deadline = k_uptime_get_32() + 25U;
+  while (__tc_te_count == __was) {
+    if (static_cast<int32_t>(k_uptime_get_32() - __deadline) >= 0) break;
+    k_msleep(0);
+  }
+  return;
+#endif
   if (!__tc_pnl_scanline_sync || rh < 8 || y < 0) return;
   int16_t __last = static_cast<int16_t>(y + rh - 1);
   if (__last >= static_cast<int16_t>(${h} - 2)) return;
@@ -578,8 +626,10 @@ const CuttlefishPanelOps __tc_display_ops = {
 CuttlefishGFX __tc_display(&__tc_display_ops, nullptr);
 ${initBlock}
 // ── display_init (called from setup) ────────────────────────────────────
+
 static inline void display_init() {
   printk("TC_DISPLAY: device ready\\n");
+${teInit}
 ${blInit}
   gpio_pin_configure_dt(&__tc_pnl_cs, GPIO_OUTPUT);
   gpio_pin_configure_dt(&__tc_pnl_dc, GPIO_OUTPUT);
@@ -726,5 +776,6 @@ export const zephyrDisplayAdapterGenerator: DisplayAdapterGenerator = (display)
   return zephyrUiDisplayAdapter(profile, {
     scanlineSync: display.scanlineSync,
     miso: display.spiPins?.miso,
+    tearingEffectPin: (display as { tearingEffectPin?: number }).tearingEffectPin,
   });
 };

package/src/dt-config/kconfig.ts

@@ -35,6 +35,17 @@ export interface KconfigUsage {
   /** PSRAM type ('opi' | 'quad') when the target board has PSRAM. Emits the
    *  CONFIG_SPIRAM symbols so the ESP heap serves PSRAM for canvas allocations. */
   psram?: 'opi' | 'quad';
+  /** HAL pin numbers the program reads with adc.* — scanned from the emitted
+   *  `__tc_adc<N>_setup()` calls at compile time. Only the overlay generator
+   *  consumes this (to rewrite the ADC node's pinctrl-0 to the used channels
+   *  on SoCs that need pad muxing, e.g. STM32); prj.conf ignores it. */
+  adcReadPins?: readonly number[];
+  /** HAL pin numbers the program drives with pwm.* — scanned from the
+   *  emitted `__tc_pwm_*` spec references at compile time. Only the overlay
+   *  generator consumes this (synthesized pwm-leds consumers + aliases are
+   *  emitted per used pin, so the DT carries no dead channels); prj.conf
+   *  ignores it. */
+  pwmUsedPins?: readonly number[];
 }
 
 /**
@@ -123,7 +134,7 @@ export function resolveKconfigFragments(
     // (without it, Kconfig silently forces them all to n).
     m.set('CONFIG_NETWORKING', 'y');
     m.set('CONFIG_WIFI', 'y');
-    m.set('CONFIG_WIFI_ESP32', 'y');            // ESP32-specific driver (sole WiFi target)
+    m.set('CONFIG_WIFI_ESP32', 'y');            // family-wide ESP32 driver (esp32/s3/c3/c6)
     m.set('CONFIG_NET_L2_ETHERNET', 'y');
     m.set('CONFIG_NET_IPV4', 'y');
     m.set('CONFIG_NET_UDP', 'y');               // transitive dep of NET_DHCPV4

package/src/dt-config/overlay.ts

@@ -25,6 +25,9 @@ export interface DisplayWiring {
   cs?: number;
   dc?: number;
   rst?: number;
+  /** Tearing-effect (TE) GPIO from display.tearingEffectPin — emitted as
+   *  te-gpios on the display DT node. Opt-in; most boards don't wire TE. */
+  tearingEffectPin?: number;
   spiFrequency?: number;
   /** SPI bus pins. When present, the overlay remuxes the SPI controller's
    *  pinctrl to these pins (the board defaults rarely match a breakout's
@@ -61,13 +64,30 @@ export interface TouchWiring {
   minPressure?: number;
 }
 
+export interface OverlayDiagnostic {
+  severity: "warning" | "error";
+  message: string;
+}
+
 export function generateOverlay(
   chip: ZephyrChipDescriptor,
   usage: KconfigUsage,
   display: ZephyrDisplayProfile | undefined,
   wiring?: DisplayWiring,
   touch?: TouchWiring,
+  diagnostics: OverlayDiagnostic[] = [],
 ): string {
+  // 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: string[] = [
     '/* Auto-generated by @typecad/framework-zephyr from cuttlefish.config.ts. */',
     '/* Enables peripherals the program uses. West merges this over the board DT. */',
@@ -97,6 +117,24 @@ export function generateOverlay(
   if (usage.usesUart && chip.uart) {
     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) {
@@ -159,6 +197,84 @@ export function generateOverlay(
   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: string[],
+  chip: ZephyrChipDescriptor,
+  usedPins?: readonly number[],
+): void {
+  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: string[],
+  chip: ZephyrChipDescriptor,
+  readPins?: readonly number[],
+): void {
+  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
@@ -246,6 +362,13 @@ function emitDisplayNode(
   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/src/framework.manifest.ts

@@ -50,8 +50,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: {},
   },
@@ -213,7 +221,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/src/index.ts

@@ -10,6 +10,12 @@ 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/src/lowering/adc.ts

@@ -23,25 +23,38 @@ export function adcChannelForPin(chip: ZephyrChipDescriptor, pin: number): numbe
 
 /**
  * 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: ZephyrChipDescriptor): string[] {
+export function adcInitLines(chip: ZephyrChipDescriptor, usedPins?: ReadonlySet<number>): string[] {
   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: string[] = ['// 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,`,
+      `        .gain = ${gain},`,
+      `        .reference = ${reference},`,
       `        .acquisition_time = ADC_ACQ_TIME_DEFAULT,`,
       `        .channel_id = ${n},`,
       `        .differential = 0,`,
@@ -68,6 +81,8 @@ export function lowerAdc(
   const o = op as any;
   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': {
@@ -79,10 +94,11 @@ export function lowerAdc(
     }
     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':
@@ -90,9 +106,9 @@ export function lowerAdc(
     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}\`. ` +