@typecad/framework-zephyr 1.0.0-alpha.18 → 1.0.0-alpha.20

package/dist/dt-config/overlay.js

@@ -10,8 +10,74 @@
 // that brings external capabilities into a build. (Arduino does it by parsing
 // library headers into .d.ts; Zephyr does it by enabling DT nodes + Kconfig.)
 // ---------------------------------------------------------------------------
-import { PANEL_CONTROLLER_DEFAULTS, panelControllerFor } from '../display/profiles.js';
+import { controllerNodelabelForPin, controllerRawPinForPin } from '../chips/controllers.js';
+import { PANEL_CONTROLLER_DEFAULTS, panelControllerFor, transportFor, isDtCompatible } from '../display/profiles.js';
+import { readDisplayBinding } from '../display/bindings.js';
+import { isEinkDisplay } from '../display/profiles.js';
+/** Standard values for the mono-OLED family's default-free required props
+ *  (segment/page/display offsets, multiplex ratio, precharge period) — the
+ *  values upstream board overlays ship; tune per panel from here. */
+function monoPropFallback(prop, info, nativeHeight) {
+    if (prop === 'width' || prop === 'height' || prop === 'reg' || prop === 'compatible')
+        return undefined;
+    const def = info?.default;
+    if (def?.kind === 'int')
+        return `${prop} = <${def.value}>`;
+    if (prop === 'multiplex-ratio')
+        return `multiplex-ratio = <${nativeHeight - 1}>`;
+    if (prop === 'prechargep')
+        return 'prechargep = <0x22>';
+    if (prop === 'segment-offset' || prop === 'page-offset' || prop === 'display-offset')
+        return `${prop} = <0>`;
+    // SSD1327-class (Stage 3 gray): required by solomon,ssd1327_5-common.yaml
+    // with no binding default. Panel-tunable — these are the datasheet/common-
+    // module starting points (scanline artifacts: raise oscillator-freq toward
+    // 0x70; striping: add 0x40 to remap-value per the binding's bit table).
+    if (prop === 'oscillator-freq')
+        return 'oscillator-freq = <0x00>';
+    if (prop === 'start-line')
+        return 'start-line = <0>';
+    if (prop === 'remap-value')
+        return 'remap-value = <0x51>';
+    if (prop === 'phase-length')
+        return 'phase-length = <0x1f>';
+    return undefined;
+}
+/** Format one binding-required property with its harvested default. Binding
+ *  props that are deliberately default-free ("panel specific" — e.g. the
+ *  sitronix gamma arrays) fall back to the rig-validated tuning the curated
+ *  profiles ship, so the generated node is always DT-valid. */
+function emitBindingProp(lines, prop, info) {
+    const def = info?.default;
+    if (def?.kind === 'bytes' && def.value.length > 0) {
+        lines.push(`            ${prop} = [${def.value.map((b) => b.toString(16).padStart(2, '0')).join(' ')}];`);
+        return;
+    }
+    if (def?.kind === 'bool' && def.value) {
+        lines.push(`            ${prop};`);
+        return;
+    }
+    if (def?.kind === 'string') {
+        lines.push(`            ${prop} = "${def.value}";`);
+        return;
+    }
+    if (info?.type === 'uint8-array') {
+        // No binding default (panel-specific): emit the rig-validated gamma
+        // tuning the curated st7796 profile carries. Tune per panel from here.
+        lines.push(`            ${prop} = [f0 09 0b 06 04 2e 46 46 39 13 15 12 15 12];`);
+        return;
+    }
+    const v = def?.kind === 'int' ? def.value : 0;
+    lines.push(`            ${prop} = <${v}>;`);
+}
 import { SENSOR_PART_INFO } from '@typecad/hal';
+/** 1-Wire family codes (the high byte of the 64-bit ROM ID) for the parts
+ *  the catalog carries on the w1 bus — vendor silicon data, like the ESP32
+ *  DAC pin table. Unknown compatibles default to the DS18B20's 0x28. */
+const W1_FAMILY_CODES = {
+    'maxim,ds18b20': 0x28,
+    'maxim,ds18s20': 0x10,
+};
 /** Display panel CS default — shared by the display block and the SPI-sensor
  *  cs-gpios merge so both sites write the same entry. */
 const DEFAULT_DISPLAY_CS = 5;
@@ -128,6 +194,36 @@ export function generateOverlay(chip, usage, display, wiring, touch, diagnostics
         lines.push('};');
         lines.push('');
     }
+    // One w1-gpio master + sensor child per constructed 1-Wire sensor. The
+    // master bit-bangs the data pin (open-drain, internal pull-up enabled —
+    // the binding recommends an external 4.7 kΩ, the internal one is weak);
+    // the child's family-code comes from the vendor table below (part of the
+    // 64-bit ROM ID), resolution from the construction opts. The nodelabels
+    // match lowering/sensor.ts sensorNames — the tc-pwm discipline.
+    for (const sp of sensorParts.filter((s) => s.busKind === 'w1')) {
+        const info = SENSOR_PART_INFO[sp.part.replace(/^SENSOR\./, '')];
+        const family = W1_FAMILY_CODES[info?.compatible ?? ''] ?? 0x28;
+        if (!info)
+            continue; // the lowering already threw on unknown parts
+        const pinCtrl = controllerNodelabelForPin(chip, sp.port);
+        const pinBit = controllerRawPinForPin(chip, sp.port);
+        const nodeName = info.compatible.split(',')[1] ?? sp.part;
+        const stem = `${sp.part.replace(/^SENSOR\./, '')}_w1_p${sp.port}`;
+        lines.push('/ {');
+        lines.push(`    tc_w1_p${sp.port}: tc-w1-p${sp.port} {`);
+        lines.push('        compatible = "zephyr,w1-gpio";');
+        lines.push(`        gpios = <&${pinCtrl} ${pinBit} (GPIO_OPEN_DRAIN | GPIO_PULL_UP)>;`);
+        lines.push('        status = "okay";');
+        lines.push(`        tc_${stem}: ${nodeName} {`);
+        lines.push(`            compatible = "${info.compatible}";`);
+        lines.push(`            family-code = <0x${family.toString(16)}>;`);
+        lines.push(`            resolution = <${sp.resolution}>;`);
+        lines.push('            status = "okay";');
+        lines.push('        };');
+        lines.push('    };');
+        lines.push('};');
+        lines.push('');
+    }
     if (usage.usesSpi && chip.spi) {
         for (const [i, c] of chip.spi.controllers.entries()) {
             if (usage.spiUsedInstances && !usage.spiUsedInstances.includes(i))
@@ -226,6 +322,178 @@ export function generateOverlay(chip, usage, display, wiring, touch, diagnostics
             }
         }
     }
+    // LED strips: one ws2812-spi child per driven SPI controller. The frame
+    // tuning (6.4 MHz, one=0xf0 / zero=0xc0 — 625 ns bit halves) is the
+    // Zephyr led_strip sample's canonical SPI encoding; the color-mapping
+    // matches the WS2812's native GRB order (the driver reorders). The
+    // controller is enabled here too — a strip-only program emits no spi_*
+    // calls, so the bus enable cannot ride the generic SPI usage path.
+    // `line-idle-low` keeps MOSI low between frames, the WS2812 reset level.
+    if (usage.usesStrip && usage.strips && usage.strips.length > 0) {
+        lines.splice(2, 0, '#include <zephyr/dt-bindings/led/led.h>', '');
+        for (const s of usage.strips) {
+            const ctrl = chip.spi?.controllers[s.index];
+            if (!ctrl)
+                continue;
+            lines.push(`&${ctrl.nodeLabel} {`);
+            lines.push('    status = "okay";');
+            lines.push('    line-idle-low;');
+            lines.push(`    tc_strip${s.index}: ws2812@0 {`);
+            lines.push('        compatible = "worldsemi,ws2812-spi";');
+            lines.push('        reg = <0>;');
+            lines.push('        spi-max-frequency = <6400000>;');
+            lines.push(`        chain-length = <${s.count}>;`);
+            lines.push('        spi-cpha;');
+            lines.push('        spi-one-frame = <0xf0>;');
+            lines.push('        spi-zero-frame = <0xc0>;');
+            lines.push('        color-mapping = <LED_COLOR_ID_GREEN LED_COLOR_ID_RED LED_COLOR_ID_BLUE>;');
+            lines.push('    };');
+            lines.push('};');
+            lines.push('');
+        }
+    }
+    // I2S: enable the board's own i2s@ controllers — their pinctrl groups
+    // are board-authored (the devkitC wires i2s0_default/i2s1_default), so
+    // status is the only synthesis needed. The GDMA the ESP32 I2S driver
+    // DMA-runs through also ships disabled — enable it alongside.
+    // Full-duplex: the RX side's I_BCK/I_WS inputs must be routed in the
+    // GPIO matrix to the same pads the TX outputs drive (input-enable on
+    // the TX clock pads — the same-pad GPIO matrix trick the CAN loopback
+    // uses; the devkitC's i2s0 clock pads are WS=36, BCK=37).
+    if (usage.usesI2s && chip.i2s) {
+        lines.push('&dma {');
+        lines.push('    status = "okay";');
+        lines.push('};');
+        lines.push('');
+        for (const c of chip.i2s.controllers) {
+            const n = c.nodeLabel.replace(/[^0-9]/g, '') || '0';
+            lines.push(`&${c.nodeLabel} {`);
+            lines.push('    status = "okay";');
+            lines.push('};');
+            lines.push('');
+            lines.push('&pinctrl {');
+            lines.push('    tc_i2s_clock_loop: tc-i2s-clock-loop {');
+            lines.push('        group1 {');
+            lines.push(`            pinmux = <I2S${n}_I_BCK_GPIO37>,`);
+            lines.push(`                     <I2S${n}_I_WS_GPIO36>;`);
+            lines.push('        };');
+            lines.push('    };');
+            lines.push('};');
+            lines.push(`&${c.nodeLabel} {`);
+            lines.push(`    pinctrl-0 = <&${c.nodeLabel}_default>, <&tc_i2s_clock_loop>;`);
+            lines.push('    pinctrl-names = "default";');
+            lines.push('};');
+            lines.push('');
+        }
+    }
+    // CAN: enable the board's own can@ controller (the harvested node —
+    // boards that ship pinctrl groups keep them; the bitrate is the begin()
+    // default, overridden at runtime by can_set_bitrate). Classic CAN only.
+    // LOOPBACK: the SJA1000 self-test transmits on the TX pad and receives
+    // on the RX pad — with no transceiver the overlay routes BOTH TWAI
+    // functions onto the TX pad (the Zephyr test suite's own
+    // twai-enable.overlay shape: output-enable on the RX mux, input-enable
+    // on the TX mux, one shared pad).
+    if (usage.usesCan && chip.can) {
+        for (const c of chip.can.controllers) {
+            lines.push(`&${c.nodeLabel} {`);
+            lines.push('    status = "okay";');
+            lines.push('    bitrate = <500000>;');
+            lines.push('};');
+            lines.push('');
+            if (usage.canLoopback && c.txPad !== undefined) {
+                lines.push('&pinctrl {');
+                lines.push('    tc_can_loopback: tc-can-loopback {');
+                lines.push('        group1 {');
+                lines.push(`            pinmux = <TWAI_RX_GPIO${c.txPad}>;`);
+                lines.push('            output-enable;');
+                lines.push('        };');
+                lines.push('        group2 {');
+                lines.push(`            pinmux = <TWAI_TX_GPIO${c.txPad}>;`);
+                lines.push('            input-enable;');
+                lines.push('        };');
+                lines.push('    };');
+                lines.push('};');
+                lines.push(`&${c.nodeLabel} { pinctrl-0 = <&tc_can_loopback>; pinctrl-names = "default"; };`);
+                lines.push('');
+            }
+        }
+    }
+    // Wall-clock shim: a zephyr,rtc-counter child on the board's first free
+    // counter node + the `rtc` alias (Zephyr's own discovery convention —
+    // the api tests filter on dt_alias_exists("rtc")). The shim is a CHILD:
+    // the counter driver keeps the parent node, so Counter and Clock
+    // coexist. V1 always synthesizes the shim (uniform semantics, no driver
+    // conflicts); preferring a board's own hardware-calendar alias — and the
+    // backup-domain persistence it buys — is the follow-up.
+    if (usage.usesClock && usage.clockShimCounter) {
+        const c = usage.clockShimCounter;
+        if (c.parent) {
+            // Child-form counters (ESP32 timerN children): the shim's parent
+            // must be the counter DEVICE, so it nests INSIDE the counter child —
+            // DT_INST_PARENT in the shim driver resolves to the counter, not the
+            // timer (which carries no device of its own).
+            lines.push(`&${c.parent} {`);
+            lines.push('    status = "okay";');
+            lines.push(`    ${c.label}: counter {`);
+            lines.push('        status = "okay";');
+            lines.push('        tc_rtc: tc-rtc {');
+            lines.push('            compatible = "zephyr,rtc-counter";');
+            lines.push('        };');
+            lines.push('    };');
+            lines.push('};');
+        }
+        else {
+            lines.push(`&${c.label} {`);
+            lines.push('    tc_rtc: tc-rtc {');
+            lines.push('        compatible = "zephyr,rtc-counter";');
+            lines.push('    };');
+            lines.push('};');
+        }
+        lines.push('/ {');
+        lines.push('    aliases {');
+        lines.push('        rtc = &tc_rtc;');
+        lines.push('    };');
+        lines.push('};');
+        lines.push('');
+    }
+    // USB HID: one zephyr,hid-device interface per program (the v1 ceiling —
+    // Keyboard OR Mouse, not both). protocol-code stays "none": the boot
+    // subclass/protocol codes (keyboard/mouse) made Windows bind the
+    // collections but silently discard every input report on this stack,
+    // while "none" (pure report-protocol device, like Zephyr's own samples)
+    // delivers input normally. The report descriptor carries the real
+    // keyboard/mouse semantics either way.
+    if (usage.usesHid) {
+        lines.push('/ {');
+        lines.push('    tc_hid: tc-hid {');
+        lines.push('        compatible = "zephyr,hid-device";');
+        lines.push('        protocol-code = "none";');
+        lines.push('        in-report-size = <8>;');
+        lines.push('        in-polling-period-us = <1000>;');
+        lines.push('    };');
+        lines.push('};');
+        lines.push('');
+    }
+    // Key matrix: the gpio-kbd-matrix node from the construction pad lists.
+    // Rows are pull-up inputs (active-low); columns are driven one at a time.
+    // Pin → controller/bit via the same mapping the gpio lowering uses.
+    if (usage.usesMatrix && usage.matrix && usage.matrix.rows.length > 0) {
+        // Same mapping the gpio lowering uses — the canonical controller
+        // resolution (single-controller fallback included). The port-relative
+        // bit comes from controllerRawPinForPin (split-SoC offsets).
+        const gpioRef = (pin) => {
+            return `&${controllerNodelabelForPin(chip, pin)} ${controllerRawPinForPin(chip, pin)} (GPIO_PULL_UP | GPIO_ACTIVE_LOW)`;
+        };
+        lines.push('/ {');
+        lines.push('    tc_matrix: matrix {');
+        lines.push('        compatible = "gpio-kbd-matrix";');
+        lines.push(`        row-gpios = ${usage.matrix.rows.map((pin) => `<${gpioRef(pin)}>`).join(', ')};`);
+        lines.push(`        col-gpios = ${usage.matrix.cols.map((pin) => `<${gpioRef(pin)}>`).join(', ')};`);
+        lines.push('    };');
+        lines.push('};');
+        lines.push('');
+    }
     if (display) {
         // Emit a full display DT node definition. Boards like the ESP32 devkit
         // have no display node in their base DT, so a bare `&display0 { status }`
@@ -726,11 +994,87 @@ function emitAlert(lines, chip, alertPin, supported, indent) {
 function emitDisplayNode(lines, display, wiring, spiTouchCs) {
     const bus = display.busLabel ?? 'spi2';
     const controller = panelControllerFor(display);
-    const compatible = display.dtCompatible ?? PANEL_CONTROLLER_DEFAULTS[controller].dtCompatible;
+    // Board-provided displays (native_sim's built-in sdl_dc): the board's own
+    // devicetree wires the panel — nothing to emit here.
+    if (display.boardProvidesDisplay) {
+        return;
+    }
+    // I2C-family panels (mono OLEDs, ssd1306-class): a plain &i2cN child node —
+    // no mipi-dbi bridge, no SPI bus block, no DMA. Bus pins come from the
+    // touch wiring's remux (shared bus) or the board's default I2C pins.
+    if (readDisplayBinding(display.dtCompatible ?? (isDtCompatible(display.driver) ? display.driver : ''))?.busFamily === 'i2c') {
+        const addr = wiring?.address ?? 0x3c;
+        // Optional I2C pin remux — mirrors the touch path's remux (the board's
+        // default I2C pins rarely match a breakout's wiring). Named macros from
+        // the SoC pinctrl header; the group lives under &pinctrl and overrides
+        // i2c0's default group via pinctrl-0.
+        const sda = wiring?.sda;
+        const scl = wiring?.scl;
+        if (sda !== undefined && scl !== undefined) {
+            lines.push('&pinctrl {');
+            lines.push('    i2c0_display: i2c0_display {');
+            lines.push('        group1 {');
+            lines.push(`            pinmux = <I2C0_SDA_GPIO${sda}>, <I2C0_SCL_GPIO${scl}>;`);
+            lines.push('            bias-pull-up;');
+            lines.push('            drive-open-drain;');
+            lines.push('        };');
+            lines.push('    };');
+            lines.push('};');
+            lines.push('');
+        }
+        // Node name from the compatible's panel segment (ssd1306/ssd1309/sh1106);
+        // DT node names are labels, not compatibles — but matching the panel
+        // keeps the built zephyr.dts readable.
+        const panel = (display.dtCompatible ?? display.driver).split(',')[1] ?? 'ssd1306';
+        lines.push('&i2c0 {');
+        lines.push('    status = "okay";');
+        // Fast mode: the full-frame mono push is bandwidth-bound (a 128x64 frame
+        // is 1KB — ~25ms at the 100kHz default, ~7ms at 400kHz), so animations
+        // step without it. OLED modules and the esp32s3/nRF i2c controllers all
+        // handle 400kHz; declare it whenever we own the bus node generation.
+        lines.push('    clock-frequency = <400000>;');
+        if (sda !== undefined && scl !== undefined) {
+            lines.push('    pinctrl-0 = <&i2c0_display>;');
+            lines.push('    pinctrl-names = "default";');
+        }
+        lines.push(`    ${display.dtLabel}: ${panel}@${addr.toString(16)} {`);
+        lines.push(`        compatible = "${display.dtCompatible ?? display.driver}";`);
+        lines.push(`        reg = <0x${addr.toString(16)}>;`);
+        lines.push(`        width = <${display.nativeWidth ?? display.width}>;`);
+        lines.push(`        height = <${display.nativeHeight ?? display.height}>;`);
+        const binding = readDisplayBinding(display.dtCompatible ?? display.driver);
+        if (binding) {
+            for (const [prop, info] of binding.required) {
+                const v = monoPropFallback(prop, info, display.nativeHeight ?? display.height);
+                if (v !== undefined)
+                    lines.push(`        ${v};`);
+            }
+        }
+        lines.push('    };');
+        lines.push('};');
+        lines.push('');
+        return;
+    }
+    // Compatible resolution: explicit override → the registry controllers →
+    // the drop-in path (driver IS a compatible string) → a safe default.
+    // Drop-in drivers (DT-compatible shape) ARE the compatible — they win over
+    // the controller-default table (which only serves registry driver ids whose
+    // id isn't itself a compatible; the e-ink family entries exist for the
+    // Kconfig layer, not for node naming).
+    const compatible = display.dtCompatible
+        ?? (isDtCompatible(display.driver)
+            ? display.driver
+            : (controller !== undefined
+                ? PANEL_CONTROLLER_DEFAULTS[controller].dtCompatible
+                : PANEL_CONTROLLER_DEFAULTS.ili9341.dtCompatible));
     const dc = wiring?.dc ?? 17;
     const rst = wiring?.rst ?? 16;
     const cs = wiring?.cs ?? DEFAULT_DISPLAY_CS;
-    const freq = wiring?.spiFrequency ?? 80000000;
+    // E-ink SPI tops out far below TFTs (the reel board runs ssd1673 at 4MHz;
+    // the controllers' shift registers clock 4-10MHz). Cap the default for the
+    // e-ink families; explicit spiFrequency always wins.
+    const einkFamily = isEinkDisplay({ driver: display.driver, displayClass: display.displayClass });
+    const freq = wiring?.spiFrequency ?? (einkFamily ? 4000000 : 80000000);
     // DT node describes the NATIVE panel geometry; the effective (rotated)
     // dimensions live in the display profile.
     const nativeW = display.nativeWidth ?? display.width;
@@ -793,19 +1137,25 @@ function emitDisplayNode(lines, display, wiring, spiTouchCs) {
     lines.push(`        ${display.dtLabel}: display@0 {`);
     lines.push(`            compatible = "${compatible}";`);
     lines.push('            reg = <0>;');
-    if (wiring?.tearingEffectPin !== undefined) {
+    if (wiring?.tearingEffectPin !== undefined && transportFor(display) === 'direct-spi') {
         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.
+        // DT_NODELABEL(display0), te_gpios) in the direct-spi adapter.
+        // Opt-in — most modules don't break the TE pad out. NOT emitted
+        // on the zephyr-display transport: te-gpios makes the bound
+        // in-tree driver allocate the TE GPIO interrupt (the ESP32
+        // VECDESC_FL_SHARED conflict path) — the driver's TE handling
+        // needs re-verification before it can be wired there.
         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,
-    // matching upstream ILI9341 boards (esp_wrover_kit) and the C++
-    // runtime, which drives these SPI TFTs as RGB565.
-    lines.push('            pixel-format = <0>;');
+    if (wiring?.busyPin !== undefined) {
+        // E-ink BUSY line — required by the ssd16xx/uc81xx bindings
+        // (the drivers block on it through the flash cycle). Active
+        // level fixed per family: ssd16xx BUSY is active-high.
+        lines.push(`            busy-gpios = <&${gpioController(wiring.busyPin)} ${wiring.busyPin} GPIO_ACTIVE_HIGH>;`);
+    }
     lines.push(`            width = <${nativeW}>;`);
     lines.push(`            height = <${nativeH}>;`);
     if (controller === 'st7796s') {
@@ -815,12 +1165,72 @@ function emitDisplayNode(lines, display, wiring, spiTouchCs) {
         lines.push('            madctl = <0x28>;');
         lines.push('            pgc = [f0 09 0b 06 04 2e 46 46 39 13 15 12 15 12];');
         lines.push('            ngc = [f0 09 0b 06 04 2e 46 46 39 13 15 12 15 12];');
+        // rgb-is-inverted flips the format the driver REPORTS (565 <-> 565X).
+        // Zephyr RGB_565 is little-endian storage, but an 8-bit SPI panel clocks
+        // the LOW byte first — each pixel arrives byte-swapped, which mixes the
+        // green channel into red/blue (white text reads purple, dark backgrounds
+        // read green — verified on the rig). With the flag, the driver reports
+        // 565X and the adapter byte-swaps at pack time, restoring wire order.
+        // (The binding documents the prop for "buggy modules that display RGB as
+        // BGR" — same mechanism, byte order.)
+        lines.push('            rgb-is-inverted;');
     }
-    else {
+    else if (controller === 'ili9341') {
         // ILI9341: the ilitek,ili9341 binding carries defaults for every register
         // (gamma, power, porch) and expresses orientation via `rotation` (degrees)
         // instead of a raw MADCTL — no panel-specific props are required.
         lines.push(`            rotation = <${display.rotation ?? 0}>;`);
+        // pixel-format is REQUIRED by the lcd-controller binding the ilitek
+        // ili9xxx family includes: 0 = RGB565 (dt-bindings/display/panel.h),
+        // matching upstream ILI9341 boards (esp_wrover_kit) and the C++ runtime.
+        // The sitronix,st7796s binding does NOT declare pixel-format (its branch
+        // omits the property — emitting it there is a DTC error, caught the hard
+        // way once the overlay stopped carrying the wrong ilitek compatible).
+        lines.push('            pixel-format = <0>;');
+    }
+    else {
+        // Generic (drop-in) path: required properties come from the panel's own
+        // binding in the user's Zephyr tree — the harvest is the single source
+        // of truth, so the node is valid for ANY bound panel by construction.
+        // Geometry/frequency props above are already emitted; pixel-format is
+        // special (required by the lcd-controller family, value fixed to RGB565).
+        const binding = readDisplayBinding(compatible);
+        if (binding?.requiresPixelFormat) {
+            lines.push('            pixel-format = <0>;');
+        }
+        if (binding) {
+            for (const [prop, def] of binding.required) {
+                // Skip structural properties the generator emits itself.
+                if (prop === 'width' || prop === 'height' || prop === 'mipi-max-frequency'
+                    || prop === 'pixel-format' || prop === 'reg' || prop === 'compatible'
+                    || prop === 'status' || prop === 'mipi-mode'
+                    // phandle-array props are structural (GPIO routing) — the
+                    // generator emits them from config wiring (busy-gpios above),
+                    // never from a numeric fallback.
+                    || prop === 'busy-gpios' || prop === 'reset-gpios' || prop === 'dc-gpios') {
+                    continue;
+                }
+                emitBindingProp(lines, prop, def);
+            }
+            // Rotation on madctl-style panels (st7796s family): the binding ships
+            // a neutral portrait default and the driver writes MADCTL verbatim, so
+            // the config's rotation MUST reach the node or the UI's landscape
+            // writes fall outside the portrait address window — half the screen
+            // scrambled, half fine (verified on the rig). Table = ST77xx rotation
+            // bits with BGR set (the verified clone convention; an R/B-swapped
+            // panel flips to the config's channelSwapRb flag instead).
+            // Byte-order quirk flag (clone panels): flips the format the driver
+            // reports so the adapter byte-swaps at pack time. Only bindings that
+            // declare the prop accept it — the DTC rejects it elsewhere, honestly.
+            if (display.rgbInverted === true) {
+                lines.push('            rgb-is-inverted;');
+            }
+            if (binding.props.has('madctl') && display.rotation !== undefined) {
+                const MADCTL_ROTATION = [0x08, 0x28, 0x48, 0xE8];
+                const r = ((display.rotation % 4) + 4) % 4;
+                lines.push(`            madctl = <0x${MADCTL_ROTATION[r].toString(16)}>;`);
+            }
+        }
     }
     lines.push('        };');
     lines.push('    };');
@@ -909,11 +1319,16 @@ function emitFt6336uNode(lines, touch) {
     lines.push('    ft6336u: ft6336u@38 {');
     lines.push('        compatible = "focaltech,ft5336";');
     lines.push('        reg = <0x38>;');
-    // NOTE: int-gpios is intentionally omitted. The ft5336 Zephyr driver
-    // registers a GPIO interrupt on int-gpios, which triggers an assertion
-    // failure in the ESP32 interrupt controller (VECDESC_FL_SHARED conflict).
-    // The cuttlefish touch adapter polls touch_isTouched() via I2C every frame
-    // — it never uses the IRQ pin, so the interrupt registration is unnecessary.
+    // NOTE: int-gpios is intentionally omitted. The driver's interrupt mode
+    // registers a GPIO IRQ (the ESP32 VECDESC_FL_SHARED crash); with no
+    // int-gpios the in-tree driver falls back to polling mode
+    // (CONFIG_INPUT_FT5336_PERIOD, default 10ms) — no IRQ is registered and
+    // the touch adapter consumes the driver's input events.
+    // swapped-x-y: the driver reports pos(col, row) — the Y-register value
+    // first. The swap makes its ABS_X/ABS_Y events carry the controller's
+    // X/Y registers verbatim, which is the raw coordinate space the runtime's
+    // calibration + rotation math (ui_poll_touch) expects from touch_readRaw.
+    lines.push('        swapped-x-y;');
     if (resetPin !== undefined) {
         lines.push(`        reset-gpios = <&${gpioController(resetPin)} ${resetPin} GPIO_ACTIVE_LOW>;`);
     }

package/dist/framework.manifest.d.ts

@@ -9,7 +9,7 @@ declare const _default: {
     entrypoint: {
         entrypointFunctionName: string;
         requiresLoopFunction: boolean;
-        sourceExtension: "cpp" | "ino" | "cc" | "h";
+        sourceExtension: "h" | "cpp" | "ino" | "cc";
         generateHeaderFile: boolean;
         overrideBaseName?: string | undefined;
         outputSubdirectory?: string | undefined;
@@ -22,7 +22,7 @@ declare const _default: {
     };
     hal: Record<string, {
         supported: boolean;
-        ops: Record<string, "stub" | "polyfill" | "unsupported" | "supported" | "probe-inconclusive">;
+        ops: Record<string, "supported" | "unsupported" | "stub" | "polyfill" | "probe-inconclusive">;
         partialCoverage: boolean;
         unsupportedReason?: string | undefined;
     }>;
@@ -62,7 +62,7 @@ declare const _default: {
             hasExceptions: boolean;
             hasRTTI: boolean;
             recommendedArrayImpl: "static_array" | "std_vector";
-            recommendedStringImpl: "static_string" | "std_string";
+            recommendedStringImpl: "std_string" | "static_string";
         };
     };
     ambientTypes: string[];
@@ -85,6 +85,12 @@ declare const _default: {
     licenses?: {
         available: boolean;
     } | undefined;
+    sbom?: {
+        available: boolean;
+    } | undefined;
+    audit?: {
+        available: boolean;
+    } | undefined;
     compat?: {
         zephyr?: string | undefined;
     } | undefined;