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

package/README.md

@@ -35,7 +35,19 @@ fix (`pip install west`, set `ZEPHYR_BASE`, or activate the venv).
   symbols for the lowered peripherals). Both are regenerated idempotently —
   only rewritten when their content changes, so Ninja's incremental build is
   preserved.
-- The MVP target is the **Seeed Studio XIAO nRF52840** (`xiao_ble` board).
+- Supported board targets: **Seeed Studio XIAO nRF52840** (`xiao_ble`),
+  **ESP32 DevKit** (`esp32_devkitc`), **ESP32-S3 DevKit** (`esp32s3_devkitc`),
+  **ESP32-C3 DevKitM** (`esp32c3_devkitm/esp32c3`), **ESP32-C6 DevKitC**
+  (`esp32c6_devkitc/esp32c6/hpcore` — the qualified form is required, the
+  board also ships an lpcore variant), **Raspberry Pi Pico** (`rpi_pico`),
+  **Pico 2** (`rpi_pico2/rp2350a/m33`), and **WeAct Black Pill V2.0**
+  (`blackpill_f411ce/stm32f411xe` — the first STM32 target; flashed over USB
+  via the ROM DFU bootloader). The rpi_pico, esp32c3, esp32c6, and blackpill
+  boards resolve their chip data from the board packages' `zephyr` field (see
+  `resolveChipFromBoard`) rather than the hardcoded chip registry; the
+  qualified Pico 2 target selects the Cortex-M33 cpucluster (Zephyr 4.3+
+  rejects the bare `rpi_pico2` because the board also ships a Hazard3 variant
+  with no default).
 
 ## Installation
 

package/dist/chips/controllers.d.ts

@@ -1,4 +1,4 @@
-import type { ZephyrChipDescriptor } from './types.js';
+import type { ZephyrChipDescriptor, ZephyrGpioController } from './types.js';
 /**
  * Resolve the devicetree nodelabel of the GPIO controller that owns `pin`.
  *
@@ -9,13 +9,33 @@ import type { ZephyrChipDescriptor } from './types.js';
  */
 export declare function controllerNodelabelForPin(chip: ZephyrChipDescriptor, pin: number): string;
 /**
- * Emit the C++ source for a runtime pin → GPIO-device dispatcher.
+ * The owning controller range for a HAL pin, if the chip declares a split.
+ */
+export declare function controllerRangeForPin(chip: ZephyrChipDescriptor, pin: number): ZephyrGpioController | undefined;
+/**
+ * The PORT-RELATIVE pin index for the raw gpio_pin_*_raw() API — the Zephyr
+ * raw calls address the index WITHIN the controller, not the global HAL pin
+ * number. For split SoCs each controller's `minPin` is its base (STM32:
+ * gpiob minPin 16, so PB12 = pin 28 → raw 12); single-controller SoCs have
+ * no offset. Emitting the global number against a port driver would address
+ * a nonexistent port bit (STM32 gpiob is 0–15) and fail at runtime.
+ */
+export declare function controllerRawPinForPin(chip: ZephyrChipDescriptor, pin: number): number;
+/**
+ * Emit the C++ source for runtime pin → GPIO-device / port-relative-index
+ * dispatchers.
+ *
+ * Returns lines defining:
+ *  - `static inline const struct device* __tc_gpio_dev(uint32_t pin)` — the
+ *    owning controller's device, resolved via DEVICE_DT_GET(DT_NODELABEL(...))
+ *    at compile time (the macro is evaluated per branch, so it is always
+ *    statically valid); only `pin` is runtime.
+ *  - `static inline gpio_pin_t __tc_gpio_pin(uint32_t pin)` — the
+ *    port-relative index for gpio_pin_*_raw() (see controllerRawPinForPin).
+ *    The runtime shim paths (UI pin-watch, safety voters) take a runtime pin,
+ *    so they cannot bake the offset in at emit time.
  *
- * Returns lines defining `static inline const struct device* __tc_gpio_dev(uint32_t pin)`.
- * Each branch resolves its controller via `DEVICE_DT_GET(DT_NODELABEL(...))` at
- * compile time (the macro is evaluated per branch, so it is always statically
- * valid); only `pin` is runtime. For a single-controller SoC this collapses to
- * a one-liner returning that controller, so the existing XIAO nRF52840 behavior
- * is byte-for-byte unchanged.
+ * For a single-controller SoC both collapse to one-liners, so the existing
+ * XIAO nRF52840 behavior is byte-for-byte unchanged.
  */
 export declare function emitGpioDevDispatcher(chip: ZephyrChipDescriptor): string[];

package/dist/chips/controllers.js

@@ -27,23 +27,47 @@
  * for out-of-range pins (e.g. the manifest probe's synthetic pin 0).
  */
 export function controllerNodelabelForPin(chip, pin) {
+    const hit = controllerRangeForPin(chip, pin);
+    return hit ? hit.nodelabel : chip.gpioController;
+}
+/**
+ * The owning controller range for a HAL pin, if the chip declares a split.
+ */
+export function controllerRangeForPin(chip, pin) {
     const ranges = chip.gpioControllers;
     if (ranges && ranges.length > 0) {
-        const hit = ranges.find((r) => pin >= r.minPin && pin <= r.maxPin);
-        if (hit)
-            return hit.nodelabel;
+        return ranges.find((r) => pin >= r.minPin && pin <= r.maxPin);
     }
-    return chip.gpioController;
+    return undefined;
 }
 /**
- * Emit the C++ source for a runtime pin → GPIO-device dispatcher.
+ * The PORT-RELATIVE pin index for the raw gpio_pin_*_raw() API — the Zephyr
+ * raw calls address the index WITHIN the controller, not the global HAL pin
+ * number. For split SoCs each controller's `minPin` is its base (STM32:
+ * gpiob minPin 16, so PB12 = pin 28 → raw 12); single-controller SoCs have
+ * no offset. Emitting the global number against a port driver would address
+ * a nonexistent port bit (STM32 gpiob is 0–15) and fail at runtime.
+ */
+export function controllerRawPinForPin(chip, pin) {
+    const hit = controllerRangeForPin(chip, pin);
+    return pin - (hit?.minPin ?? 0);
+}
+/**
+ * Emit the C++ source for runtime pin → GPIO-device / port-relative-index
+ * dispatchers.
+ *
+ * Returns lines defining:
+ *  - `static inline const struct device* __tc_gpio_dev(uint32_t pin)` — the
+ *    owning controller's device, resolved via DEVICE_DT_GET(DT_NODELABEL(...))
+ *    at compile time (the macro is evaluated per branch, so it is always
+ *    statically valid); only `pin` is runtime.
+ *  - `static inline gpio_pin_t __tc_gpio_pin(uint32_t pin)` — the
+ *    port-relative index for gpio_pin_*_raw() (see controllerRawPinForPin).
+ *    The runtime shim paths (UI pin-watch, safety voters) take a runtime pin,
+ *    so they cannot bake the offset in at emit time.
  *
- * Returns lines defining `static inline const struct device* __tc_gpio_dev(uint32_t pin)`.
- * Each branch resolves its controller via `DEVICE_DT_GET(DT_NODELABEL(...))` at
- * compile time (the macro is evaluated per branch, so it is always statically
- * valid); only `pin` is runtime. For a single-controller SoC this collapses to
- * a one-liner returning that controller, so the existing XIAO nRF52840 behavior
- * is byte-for-byte unchanged.
+ * For a single-controller SoC both collapse to one-liners, so the existing
+ * XIAO nRF52840 behavior is byte-for-byte unchanged.
  */
 export function emitGpioDevDispatcher(chip) {
     const ranges = chip.gpioControllers;
@@ -53,14 +77,27 @@ export function emitGpioDevDispatcher(chip) {
             `    (void)pin;`,
             `    return DEVICE_DT_GET(DT_NODELABEL(${chip.gpioController}));`,
             '}',
+            'static inline gpio_pin_t __tc_gpio_pin(uint32_t pin) {',
+            `    return (gpio_pin_t)pin;`,
+            '}',
         ];
     }
     const lines = [
         'static inline const struct device* __tc_gpio_dev(uint32_t pin) {',
     ];
+    const pinLines = [
+        'static inline gpio_pin_t __tc_gpio_pin(uint32_t pin) {',
+    ];
     for (const r of ranges) {
         lines.push(`    if (pin >= ${r.minPin} && pin <= ${r.maxPin}) { return DEVICE_DT_GET(DT_NODELABEL(${r.nodelabel})); }`);
+        if (r.minPin === 0) {
+            pinLines.push(`    if (pin >= ${r.minPin} && pin <= ${r.maxPin}) { return (gpio_pin_t)pin; }`);
+        }
+        else {
+            pinLines.push(`    if (pin >= ${r.minPin} && pin <= ${r.maxPin}) { return (gpio_pin_t)(pin - ${r.minPin}); }`);
+        }
     }
     lines.push(`    return DEVICE_DT_GET(DT_NODELABEL(${chip.gpioController}));`, '}');
-    return lines;
+    pinLines.push(`    return (gpio_pin_t)pin;`, '}');
+    return [...lines, ...pinLines];
 }

package/dist/chips/resolve.js

@@ -81,18 +81,35 @@ export function resolveChipFromBoard(bc) {
     const pwmSpecs = collectIndexed(bc, 'zephyr.pwm.specs', (m, i) => {
         const pin = m.get(`zephyr.pwm.specs.${i}.pin`);
         const dtSpec = m.get(`zephyr.pwm.specs.${i}.dtSpec`);
-        if (pin != null && dtSpec)
-            return { pin, dtSpec };
-        return null;
+        const controller = m.get(`zephyr.pwm.specs.${i}.controller`);
+        const channel = m.get(`zephyr.pwm.specs.${i}.channel`);
+        const periodNs = m.get(`zephyr.pwm.specs.${i}.periodNs`);
+        const polarity = m.get(`zephyr.pwm.specs.${i}.polarity`);
+        // Board-shipped alias form (dtSpec) or synthesized form (controller +
+        // channel → overlay-generated alias) — at least one, else drop the entry.
+        if (pin == null || !(dtSpec || (controller && channel != null)))
+            return null;
+        return {
+            pin,
+            ...(dtSpec ? { dtSpec } : {}),
+            ...(controller ? { controller } : {}),
+            ...(channel != null ? { channel } : {}),
+            ...(periodNs != null ? { periodNs } : {}),
+            ...(polarity ? { polarity } : {}),
+        };
     });
     const adcNodeLabel = bc.get('zephyr.adc.nodeLabel');
     const adcResolution = bc.get('zephyr.adc.resolution');
     const adcVref = bc.get('zephyr.adc.vrefMv');
+    const adcGain = bc.get('zephyr.adc.gain');
+    const adcReference = bc.get('zephyr.adc.reference');
     const adcChannels = collectIndexed(bc, 'zephyr.adc.channels', (m, i) => {
         const pin = m.get(`zephyr.adc.channels.${i}.pin`);
         const channel = m.get(`zephyr.adc.channels.${i}.channel`);
-        if (pin != null && channel != null)
-            return { pin, channel };
+        const pinctrl = m.get(`zephyr.adc.channels.${i}.pinctrl`);
+        if (pin != null && channel != null) {
+            return { pin, channel, ...(pinctrl ? { pinctrl } : {}) };
+        }
         return null;
     });
     const wdtNodeLabel = bc.get('zephyr.wdt.nodeLabel');
@@ -113,7 +130,16 @@ export function resolveChipFromBoard(bc) {
         ...(uartControllers.length > 0 ? { uart: { controllers: uartControllers } } : {}),
         ...(pwmSpecs.length > 0 ? { pwm: { specs: pwmSpecs } } : {}),
         ...(adcNodeLabel || adcResolution != null || adcVref != null || adcChannels.length > 0
-            ? { adc: { nodeLabel: adcNodeLabel ?? 'adc', resolution: adcResolution ?? 12, vrefMv: adcVref ?? 3000, channels: adcChannels } }
+            ? {
+                adc: {
+                    nodeLabel: adcNodeLabel ?? 'adc',
+                    resolution: adcResolution ?? 12,
+                    vrefMv: adcVref ?? 3000,
+                    channels: adcChannels,
+                    ...(adcGain ? { gain: adcGain } : {}),
+                    ...(adcReference ? { reference: adcReference } : {}),
+                },
+            }
             : {}),
         ...(wdtNodeLabel ? { wdt: { nodeLabel: wdtNodeLabel } } : {}),
         ...(wifiSupported ? { wifi: { supported: true } } : {}),

package/dist/chips/types.d.ts

@@ -47,14 +47,37 @@ export interface ZephyrBusController {
 /**
  * A PWM channel described as a devicetree spec.
  *
- * Emitted as `struct pwm_dt_spec __tc_pwm<N> = PWM_DT_SPEC_GET(DT_ALIAS(<dtSpec>))`.
- * `pwm_set_pulse_dt(&__tc_pwm<N>, pulse_ns)` honors the spec's period/polarity.
+ * Two forms, mutually exclusive:
+ * - **Board-shipped alias:** `dtSpec` names a DT alias the board's own DTS
+ *   already defines (e.g. the XIAO's `pwm-led0`). Emitted as
+ *   `PWM_DT_SPEC_GET(DT_ALIAS(<dtSpec>))`.
+ * - **Synthesized** (controller + channel): the board DTS enables a PWM
+ *   controller node (e.g. `pwm4`) but defines no alias for it. The overlay
+ *   generator synthesizes a `pwm-leds` consumer node + a `tc-pwm<pin>` alias
+ *   in `<board>.overlay`; the lowering emits
+ *   `PWM_DT_SPEC_GET(DT_ALIAS(tc-pwm<pin>))`. Both sides derive the alias
+ *   name from the pin, so they always agree.
+ *
+ * `pwm_set_pulse_dt(&spec, pulse_ns)` honors the spec's period/polarity.
  */
 export interface ZephyrPwmSpec {
     /** GPIO number (matches the HAL op `pin` field). */
     readonly pin: number;
-    /** Devicetree alias, e.g. 'pwm-led0'. */
-    readonly dtSpec: string;
+    /** Board-shipped DT alias, e.g. 'pwm-led0'. Omit when using the
+     *  synthesized form (controller + channel). */
+    readonly dtSpec?: string;
+    /** Synthesized form: PWM controller DT nodelabel, e.g. 'pwm4' (the STM32
+     *  timer's pwm child node). The overlay's pwm-leds node consumes it. */
+    readonly controller?: string;
+    /** Synthesized form: channel index within the controller (1-based timer
+     *  channel, matching the `pwms` binding's channel cell). */
+    readonly channel?: number;
+    /** Synthesized form: period in nanoseconds, baked into the DT spec. The
+     *  lowering scales duty against `spec.period`. Default 20 000 000 (20 ms /
+     *  50 Hz — the servo convention; harmless for LED dimming). */
+    readonly periodNs?: number;
+    /** Synthesized form: PWM polarity flag. Default PWM_POLARITY_NORMAL. */
+    readonly polarity?: string;
 }
 /**
  * A GPIO pin usable as an interrupt source.
@@ -69,7 +92,7 @@ export interface ZephyrInterruptPin {
     readonly dtSpec: string;
 }
 /**
- * An ADC channel: which SAADC input a given HAL pin maps to.
+ * An ADC channel: which ADC input a given HAL pin maps to.
  *
  * The XIAO nRF52840 has no pre-declared ADC channel nodes in devicetree, so the
  * lowering emits `adc_channel_setup` against `DEVICE_DT_GET(DT_NODELABEL(adc))`
@@ -78,8 +101,16 @@ export interface ZephyrInterruptPin {
 export interface ZephyrAdcChannel {
     /** GPIO number (matches the HAL op `pin` field). */
     readonly pin: number;
-    /** SAADC channel index (AIN0–AIN7). */
+    /** ADC channel index (nRF SAADC AIN0–AIN7; STM32 ADC1_IN0–IN9). */
     readonly channel: number;
+    /**
+     * Pinctrl node label that muxes this pin to analog mode, e.g.
+     * 'adc1_in0_pa0' (STM32). When present, the overlay generator rewrites the
+     * ADC node's pinctrl-0 to the channels the program actually reads — SoCs
+     * like STM32 leave the pad in GPIO mode otherwise and reads float.
+     * Omit on SoCs whose ADC needs no pad muxing (nRF SAADC, RP2040).
+     */
+    readonly pinctrl?: string;
 }
 /**
  * A DAC channel: which DAC output a given HAL pin maps to. The lowering emits
@@ -113,11 +144,18 @@ export interface ZephyrChipDescriptor {
     readonly gpioController: string;
     /**
      * Per-range GPIO controllers for SoCs that split GPIO across multiple
-     * devicetree nodes (ESP32-S3: `gpio0` 0–31, `gpio1` 32–48). When present, the
-     * lowering routes a HAL pin to its owning controller at runtime via the
-     * emitted `__tc_gpio_dev(pin)` dispatcher; `gpioController` is the fallback.
-     * Omit on single-controller SoCs (nRF52840, RP2040, …) — every pin is on the
-     * one controller described by `gpioController`.
+     * devicetree nodes (ESP32-S3: `gpio0` 0–31, `gpio1` 32–48; STM32: one
+     * controller per port — `gpioa` 0–15, `gpiob` 16–31, `gpioc` 32–47).
+     * When present, the lowering routes a HAL pin to its owning controller at
+     * runtime via the emitted `__tc_gpio_dev(pin)` dispatcher; `gpioController`
+     * is the fallback. Omit on single-controller SoCs (RP2040, …) — every pin
+     * is on the one controller described by `gpioController`.
+     *
+     * NUMBERING RULE (load-bearing): `minPin` must equal the controller's port
+     * base so the port-relative raw index is `pin - minPin` (STM32 PB12 = pin
+     * 28 → raw 12 — the Zephyr raw API addresses the index WITHIN the
+     * controller). Number pins by port blocks and never contiguously across
+     * unbonded pins.
      */
     readonly gpioControllers?: readonly ZephyrGpioController[];
     /** GPIO pins with devicetree specs (LEDs, buttons, board-defined pins). */
@@ -142,7 +180,7 @@ export interface ZephyrChipDescriptor {
     readonly pwm?: {
         readonly specs: readonly ZephyrPwmSpec[];
     };
-    /** ADC: the SAADC node label + the pin→channel map. */
+    /** ADC: the ADC device node label + the pin→channel map. */
     readonly adc?: {
         readonly nodeLabel: string;
         readonly channels: readonly ZephyrAdcChannel[];
@@ -150,6 +188,19 @@ export interface ZephyrChipDescriptor {
         readonly vrefMv: number;
         /** ADC resolution in bits. */
         readonly resolution: number;
+        /**
+         * Zephyr `enum adc_gain` macro for the channel setup, e.g.
+         * 'ADC_GAIN_1_4' (nRF SAADC default) or 'ADC_GAIN_1' (STM32 driver
+         * requires exactly this). Defaults to 'ADC_GAIN_1_4'.
+         */
+        readonly gain?: string;
+        /**
+         * Zephyr `enum adc_reference` macro, e.g. 'ADC_REF_INTERNAL'. Defaults to
+         * 'ADC_REF_INTERNAL' — on nRF that is the 0.6 V internal ref measured
+         * through the gain divider; the STM32 driver ALSO requires
+         * ADC_REF_INTERNAL (Zephyr maps it to the VREF+ pad) with vrefMv = VDDA.
+         */
+        readonly reference?: string;
     };
     /**
      * DAC: the DAC device node label + the pin→channel map. Present only on chips

package/dist/chips/xiao-ble.js

@@ -8,6 +8,18 @@ export const XIAO_BLE = {
     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).

package/dist/display/index.d.ts

@@ -2,7 +2,7 @@ import type { DisplayHALOp } from '@typecad/cuttlefish/api/shared';
 import { type ZephyrDisplayProfile } from './profiles.js';
 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 {
     initialized: boolean;

package/dist/display/index.js

@@ -15,7 +15,7 @@ import { DEFAULT_ZEPHYR_DISPLAY_PROFILE } from './profiles.js';
 // 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';
 /** Fresh display state (used by the strategy per-build). */
 export function newDisplayState() {
     return { initialized: false, profile: DEFAULT_ZEPHYR_DISPLAY_PROFILE };

package/dist/display/profiles.d.ts

@@ -48,3 +48,11 @@ export declare function panelControllerFor(profile: Pick<ZephyrDisplayProfile, '
 export declare const ZEPHYR_DISPLAY_PROFILES: Record<string, ZephyrDisplayProfile>;
 /** The default profile used when resolveDisplayOp is probed without a display.init. */
 export declare const DEFAULT_ZEPHYR_DISPLAY_PROFILE: ZephyrDisplayProfile;
+/**
+ * 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 declare const BUILT_IN_PROFILES: Record<string, import('@typecad/cuttlefish/api/shared').DisplayProfile>;

package/dist/display/profiles.js

@@ -69,3 +69,22 @@ export const ZEPHYR_DISPLAY_PROFILES = {
 };
 /** The default profile used when resolveDisplayOp is probed without a display.init. */
 export const DEFAULT_ZEPHYR_DISPLAY_PROFILE = 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 = 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/dist/display/ui-adapter.d.ts

@@ -10,6 +10,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 declare function zephyrUiDisplayAdapter(profile: ZephyrDisplayProfile, readback?: ZephyrDisplayReadbackOptions): DisplayAdapterCode;
 /**

package/dist/display/ui-adapter.js

@@ -55,6 +55,9 @@ export function zephyrUiDisplayAdapter(profile, readback = {}) {
     // 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}) ---`,
         `// Native CuttlefishGFX path: do NOT #define CuttlefishCanvas16 so the`,
@@ -118,6 +121,22 @@ export function zephyrUiDisplayAdapter(profile, readback = {}) {
         `// 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.`,
@@ -134,6 +153,17 @@ export function zephyrUiDisplayAdapter(profile, readback = {}) {
     // 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`
         : '';
@@ -452,6 +482,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;
@@ -551,8 +594,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);
@@ -699,5 +744,6 @@ export const zephyrDisplayAdapterGenerator = (display) => {
     return zephyrUiDisplayAdapter(profile, {
         scanlineSync: display.scanlineSync,
         miso: display.spiPins?.miso,
+        tearingEffectPin: display.tearingEffectPin,
     });
 };

package/dist/dt-config/kconfig.d.ts

@@ -25,6 +25,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[];
 }
 /**
  * Resolve the Kconfig symbol→value map for a prj.conf. Returns a Map preserving

package/dist/dt-config/kconfig.js

@@ -97,7 +97,7 @@ export function resolveKconfigFragments(usage, debug) {
         // (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/dist/dt-config/overlay.d.ts

@@ -10,6 +10,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
@@ -49,4 +52,8 @@ export interface TouchWiring {
      *  panels need a few hundred 12-bit counts; default 400. */
     minPressure?: number;
 }
-export declare function generateOverlay(chip: ZephyrChipDescriptor, usage: KconfigUsage, display: ZephyrDisplayProfile | undefined, wiring?: DisplayWiring, touch?: TouchWiring): string;
+export interface OverlayDiagnostic {
+    severity: "warning" | "error";
+    message: string;
+}
+export declare function generateOverlay(chip: ZephyrChipDescriptor, usage: KconfigUsage, display: ZephyrDisplayProfile | undefined, wiring?: DisplayWiring, touch?: TouchWiring, diagnostics?: OverlayDiagnostic[]): string;