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

package/dist/doctor.js

@@ -1,48 +1,75 @@
 // ---------------------------------------------------------------------------
 // @typecad/framework-zephyr — Zephyr environment doctor
 //
-// `cuttlefish doctor` (Zephyr framework) — verify the installed Zephyr RTOS is
-// reachable and inside the framework's declared compat range, and preview how
-// the configured board target resolves for that version. Exits 0 if the
-// environment is OK, non-zero otherwise. Mirrors framework-arduino's doctor
-// shape (dispatched via the framework's `doctor` export).
+// `cuttlefish doctor` (Zephyr framework) — verify west (the Zephyr build tool)
+// is installed + responsive, the Zephyr RTOS is inside the framework's declared
+// compat range, and the configured board target exists in the checkout. Exits 0
+// if the environment is OK, non-zero otherwise. Mirrors framework-arduino's
+// doctor shape (dispatched via the framework's `doctor` export) and reuses
+// checkZephyrEnv so the detection logic can be shared with the build/test gates.
 // ---------------------------------------------------------------------------
 import * as ui from '@typecad/cuttlefish/utils/ui';
 import { loadCuttlefishConfig } from '@typecad/cuttlefish/config-loader';
-import { detectZephyrVersion, checkZephyrCompat, resolveBoardTarget } from './toolchain/compat.js';
+import { checkZephyrEnv } from './toolchain/env-check.js';
 /**
- * Verify the installed Zephyr is reachable + inside the supported range, and
- * preview board-target normalization for the configured target. Sets
- * process.exitCode = 1 on an out-of-range Zephyr.
+ * Verify west is installed + responsive, the Zephyr RTOS is inside the supported
+ * range, and the configured board target exists in the checkout. Sets
+ * process.exitCode = 1 on failure. Thin presenter over checkZephyrEnv.
  */
 export function runDoctor() {
     ui.printHeader();
     ui.printStep('Checking Zephyr environment...');
-    const base = process.env.ZEPHYR_BASE;
-    const version = detectZephyrVersion();
-    const result = checkZephyrCompat(version);
-    ui.printInfo(`ZEPHYR_BASE ..... ${base ?? '(not set)'}`);
-    ui.printInfo(`Zephyr version .. ${version ?? 'unknown (could not read ZEPHYR_BASE/VERSION)'}`);
-    ui.printInfo(`Supported range . ${result.range ?? '(none declared)'}`);
-    if (result.status === 'out-of-range') {
-        ui.printError(`Zephyr ${version} is OUTSIDE the supported range (${result.range}).`);
-        ui.printInfo("Set ZEPHYR_BASE to a compatible Zephyr checkout, or install one via '@typecad/zephyr-installer'.");
-        process.exitCode = 1;
-        return;
-    }
-    if (result.status === 'undetectable') {
+    const config = loadCuttlefishConfig(process.cwd());
+    const buildTarget = config?.buildTarget;
+    const result = checkZephyrEnv(buildTarget);
+    const c = result.check;
+    // west (the Zephyr build tool) — the analog of arduino-cli presence.
+    if (c.westFound) {
+        const ver = c.westVersion ?? 'found';
+        const src = c.westSource ? `  (${c.westSource})` : '';
+        ui.printInfo(`west ............. ${ver}  ✓${src}`);
+    }
+    else {
+        ui.printError('west ............. NOT FOUND');
+    }
+    // Zephyr RTOS version + declared compat range.
+    ui.printInfo(`ZEPHYR_BASE ...... ${c.zephyrBase ?? '(not set)'}`);
+    ui.printInfo(`Zephyr version .. ${c.zephyrVersion ?? 'unknown (could not read ZEPHYR_BASE/VERSION)'}`);
+    ui.printInfo(`Supported range . ${c.compatRange ?? '(none declared)'}`);
+    if (c.compatStatus === 'out-of-range') {
+        ui.printError(`Zephyr ${c.zephyrVersion} is OUTSIDE the supported range (${c.compatRange}).`);
+    }
+    else if (c.compatStatus === 'undetectable') {
         ui.printWarning('Could not detect the Zephyr version (is ZEPHYR_BASE set?) — compat check skipped.');
     }
     else {
         ui.printInfo('Zephyr compat ... OK');
     }
-    // Preview how the configured board target resolves for this Zephyr version
-    // (e.g. a stale bare id would be qualified at build time). The loader extracts
-    // frameworkData.buildTarget to a top-level field.
-    const config = loadCuttlefishConfig(process.cwd());
-    const buildTarget = config?.buildTarget;
+    // Board target — the analog of the Arduino core presence check.
     if (buildTarget) {
-        const resolved = resolveBoardTarget(buildTarget, version);
-        ui.printInfo(`Board target .... ${buildTarget}${resolved === buildTarget ? '' : ` → ${resolved}`}`);
+        const resolved = c.resolvedBoardTarget ?? buildTarget;
+        const arrow = resolved === buildTarget ? '' : ` → ${resolved}`;
+        if (c.boardTargetSupported === false) {
+            ui.printError(`Board target .... ${buildTarget}${arrow}  NOT found in this Zephyr checkout`);
+            ui.printInfo('  → check the board id, or run: west boards');
+        }
+        else if (c.boardTargetSupported === undefined) {
+            ui.printInfo(`Board target .... ${buildTarget}${arrow}`);
+            ui.printInfo('(could not verify board presence — no ZEPHYR_BASE boards/ tree found)');
+        }
+        else {
+            ui.printInfo(`Board target .... ${buildTarget}${arrow}`);
+        }
+    }
+    else {
+        ui.printInfo('(no buildTarget in cuttlefish.config.ts — skipping board check)');
+    }
+    // Exit code — mirrors framework-arduino's doctor.
+    if (result.ok) {
+        ui.printSuccess('Environment OK');
+        return; // exitCode stays unset => 0
     }
+    for (const line of result.messages)
+        ui.printInfo(line);
+    process.exitCode = 1;
 }

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

@@ -1,6 +1,9 @@
 export interface KconfigUsage {
     usesAdc?: boolean;
     usesPwm?: boolean;
+    usesDac?: boolean;
+    usesFS?: boolean;
+    usesHwtimer?: boolean;
     usesI2c?: boolean;
     usesSpi?: boolean;
     usesUart?: boolean;
@@ -13,8 +16,12 @@ export interface KconfigUsage {
     usesMqtt?: boolean;
     usesPreferences?: boolean;
     usesRandom?: boolean;
-    /** Touch controller referenced (UI touch adapter emits DT_NODELABEL(ft6336u)). */
+    /** Touch controller referenced (UI touch adapter emits DT_NODELABEL(ft6336u)
+     *  or DT_NODELABEL(xpt2046)). Selects the bus driver the node needs. */
     usesTouch?: boolean;
+    /** Which touch controller the program uses — FT6336U rides I2C, XPT2046
+     *  rides the display's SPI bus. Only meaningful with usesTouch. */
+    touchController?: 'ft6336u' | 'xpt2046';
     /** 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';

package/dist/dt-config/kconfig.js

@@ -23,12 +23,17 @@ export function resolveKconfigFragments(usage, debug) {
         m.set('CONFIG_ADC', 'y');
     if (usage.usesPwm)
         m.set('CONFIG_PWM', 'y');
+    if (usage.usesDac)
+        m.set('CONFIG_DAC', 'y');
     if (usage.usesI2c)
         m.set('CONFIG_I2C', 'y');
     if (usage.usesSpi)
         m.set('CONFIG_SPI', 'y');
     if (usage.usesWdt)
         m.set('CONFIG_WATCHDOG', 'y');
+    // Hardware timers via the counter driver.
+    if (usage.usesHwtimer)
+        m.set('CONFIG_COUNTER', 'y');
     if (usage.usesDisplay) {
         m.set('CONFIG_DISPLAY', 'y');
         m.set('CONFIG_SPI', 'y');
@@ -39,15 +44,32 @@ export function resolveKconfigFragments(usage, debug) {
         // configured SPI clock (~80MHz) and drops into the low tens of ms. The
         // display overlay pairs this with dma-enabled + dmas on the spi2 node.
         m.set('CONFIG_DMA', 'y');
-        // Disable the MIPI DBI SPI bridge + ST7796S drivers. The display adapter
-        // drives the panel directly via spi_write. Binding these drivers would
-        // allocate a tearing-effect GPIO interrupt that conflicts with the SPI/I2C
-        // driver interrupts — the VECDESC_FL_SHARED assertion crashes on touch.
+        // Disable the MIPI DBI SPI bridge + in-tree panel drivers (ILI9341,
+        // ST7796S). The display adapter drives the panel directly via spi_write.
+        // Binding these drivers would allocate a tearing-effect GPIO interrupt
+        // that conflicts with the SPI/I2C driver interrupts — the
+        // VECDESC_FL_SHARED assertion crashes on touch. ILI9341 matters as much
+        // as the bridge: the driver auto-defaults on from the overlay's
+        // ilitek,ili9341 node and references the (disabled) mipi-dbi-spi
+        // controller's device struct, failing at link time with
+        // "undefined reference to __device_dts_ord_N". (Assign the prompted
+        // ILI9341, not the hidden ILI9XXX — promptless symbols reject prj.conf
+        // assignments.)
         m.set('CONFIG_MIPI_DBI_SPI', 'n');
+        m.set('CONFIG_ILI9341', 'n');
         m.set('CONFIG_ST7796S', 'n');
     }
     if (usage.usesTouch) {
-        m.set('CONFIG_I2C', 'y'); // FT6336U touch on I2C
+        // FT6336U touch is on I2C; the XPT2046 shares the display's SPI bus.
+        // CONFIG_INPUT stays off either way: the adapters drive the controllers
+        // directly, and enabling it would build the in-tree input drivers
+        // (ft5336 / xpt2046) against nodes these adapters already own.
+        if (usage.touchController === 'xpt2046') {
+            m.set('CONFIG_SPI', 'y');
+        }
+        else {
+            m.set('CONFIG_I2C', 'y');
+        }
     }
     // PSRAM: enable the ESP SPIRAM driver + route malloc/heap to external RAM so
     // large canvas allocations (scroll viewports, lists) can use PSRAM instead of
@@ -237,6 +259,19 @@ export function resolveKconfigFragments(usage, debug) {
         m.set('CONFIG_SETTINGS', 'y');
         m.set('CONFIG_SETTINGS_ZMS', 'y');
     }
+    // Filesystem: littlefs on the storage partition. CONFIG_FILE_SYSTEM_LITTLEFS
+    // selects the littlefs backend but NOT FLASH/FLASH_MAP (the partition lookup
+    // needs them), so all three are set explicitly — same shape as the
+    // preferences/ZMS block. The overlay points the storage_partition at the FS
+    // (see dt-config/overlay.ts). NOTE: a program using BOTH fs.* and
+    // preferences.* shares the one storage_partition between littlefs and ZMS —
+    // dedicate separate partitions if both are needed (the manifest flags this).
+    if (usage.usesFS) {
+        m.set('CONFIG_FLASH', 'y');
+        m.set('CONFIG_FLASH_MAP', 'y');
+        m.set('CONFIG_FILE_SYSTEM', 'y');
+        m.set('CONFIG_FILE_SYSTEM_LITTLEFS', 'y');
+    }
     // usesUart: the board enables the console UART by default; the overlay (not
     // Kconfig) is where a UART node would be enabled, so no symbol here.
     // Random: <zephyr/random/random.h> sys_rand_get is backed by the random

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

@@ -25,11 +25,28 @@ export interface DisplayWiring {
      *  backlight init is guarded by `DT_HAS_ALIAS` and compiles away. */
     backlightPin?: number;
 }
-/** Touch wiring from cuttlefish.config.ts (irq/resetPin/sda/scl). */
+/** Touch wiring from cuttlefish.config.ts (irq/resetPin/sda/scl; cs for SPI
+ *  resistive controllers, calibration for the XPT2046 DT binding). */
 export interface TouchWiring {
+    /** Touch controller kind — selects the DT node shape (FT6336U node on I2C0
+     *  vs XPT2046 node on the display's SPI bus). Default 'ft6336u'. */
+    controller?: 'ft6336u' | 'xpt2046';
     irq?: number;
     resetPin?: number;
     sda?: number;
     scl?: number;
+    /** XPT2046 only: SPI CS pin (second cs-gpios entry on the panel's bus). */
+    cs?: number;
+    /** XPT2046 only: raw ADC calibration — feeds the binding's min-x/max-x/
+     *  min-y/max-y (required props). Defaults span the full 12-bit range. */
+    calibration?: {
+        xMin: number;
+        xMax: number;
+        yMin: number;
+        yMax: number;
+    };
+    /** XPT2046 only: pen-detect Z1 threshold (binding's z-threshold). Resistive
+     *  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;

package/dist/dt-config/overlay.js

@@ -10,6 +10,7 @@
 // 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';
 export function generateOverlay(chip, usage, display, wiring, touch) {
     const lines = [
         '/* Auto-generated by @typecad/framework-zephyr from cuttlefish.config.ts. */',
@@ -41,6 +42,11 @@ export function generateOverlay(chip, usage, display, wiring, touch) {
         for (const c of chip.uart.controllers)
             block(c.nodeLabel);
     }
+    // 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) {
+        block(chip.dac.device);
+    }
     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 }`
@@ -48,14 +54,18 @@ export function generateOverlay(chip, usage, display, wiring, touch) {
         // controller with the panel's compatible string + dimensions. The pin
         // wiring (cs/dc/rst) uses ESP32 GPIO defaults from the demo config; a
         // real board overlay would carry its own binding.
-        emitDisplayNode(lines, display, wiring);
+        // An XPT2046 on the same bus needs its CS as the second cs-gpios entry,
+        // so thread it into the display block (DT assignment replaces the whole
+        // property — both entries must be written together).
+        emitDisplayNode(lines, display, wiring, touch?.controller === 'xpt2046' ? (touch?.cs ?? DEFAULT_XPT2046_CS) : undefined);
     }
-    // FT6336U touch on I2C — defined when the program uses touch (the UI touch
-    // adapter references DT_NODELABEL(ft6336u)). Same rationale: the bare devkit
-    // has no such node. Gated on usesTouch (not usesI2c/chip.i2c) so it emits
-    // even when the chip descriptor doesn't declare I2C controllers (ESP32).
+    // Touch — FT6336U capacitive on I2C (references DT_NODELABEL(ft6336u)) or
+    // XPT2046 resistive on the display's SPI bus (references
+    // DT_NODELABEL(xpt2046)). Same rationale as the display node: the bare
+    // devkit has no such node. Gated on usesTouch (not usesI2c/chip.i2c) so it
+    // emits even when the chip descriptor doesn't declare bus controllers.
     if (usage.usesTouch) {
-        emitTouchNode(lines, touch);
+        emitTouchNode(lines, touch, display);
     }
     // Preferences (ZMS settings backend): point the settings subsystem at the
     // board's storage_partition. The backend looks for /chosen
@@ -86,11 +96,21 @@ export function generateOverlay(chip, usage, display, wiring, touch) {
     return lines.join('\n');
 }
 /**
- * Emit a display DT node definition. The node is attached to spi2 (the ESP32's
- * first user SPI controller) via a MIPI DBI SPI bridge. Pin wiring comes from
- * the display config (cs/dc/rst); defaults match the demo-st wiring if absent.
+ * 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
+ * DBI SPI bridge. Pin wiring comes from the display config (cs/dc/rst);
+ * defaults match the demo-st wiring if absent. The compatible string + node
+ * props come from the profile's panel controller (st7796s carries the required
+ * pgc/ngc gamma + madctl; ili9341's binding defaults everything else).
+ *
+ * spiTouchCs: when an XPT2046 SPI touch controller shares the bus, its CS is
+ * appended as the second cs-gpios entry (the touch node uses reg = <1>) — DT
+ * property assignment replaces, so both entries must be written together.
  */
-function emitDisplayNode(lines, display, wiring) {
+function emitDisplayNode(lines, display, wiring, spiTouchCs) {
+    const bus = display.busLabel ?? 'spi2';
+    const controller = panelControllerFor(display);
+    const compatible = display.dtCompatible ?? PANEL_CONTROLLER_DEFAULTS[controller].dtCompatible;
     const dc = wiring?.dc ?? 17;
     const rst = wiring?.rst ?? 16;
     const cs = wiring?.cs ?? 5;
@@ -111,7 +131,9 @@ function emitDisplayNode(lines, display, wiring) {
     // macros are used instead of the named SPIM2_*_GPIOxx tokens because the
     // bindings header omits GPIOs 22-25 from those lists.
     if (sck !== undefined && mosi !== undefined) {
-        lines.push('&spim2_default {');
+        // 'spi2' → pinctrl group 'spim2_default' (ESP32 SPI-master naming).
+        const pinctrlGroup = bus.replace(/^spi(\d)$/, 'spim$1') + '_default';
+        lines.push(`&${pinctrlGroup} {`);
         lines.push('    group1 {');
         lines.push(`        pinmux = <ESP32_PINMUX(${miso ?? 19}, ESP_FSPIQ_IN, ESP_NOSIG)>,`);
         lines.push(`                 <ESP32_PINMUX(${sck}, ESP_NOSIG, ESP_FSPICLK_OUT)>,`);
@@ -128,9 +150,9 @@ function emitDisplayNode(lines, display, wiring) {
     lines.push('    status = "okay";');
     lines.push('};');
     lines.push('');
-    lines.push('&spi2 {');
+    lines.push(`&${bus} {`);
     lines.push('    status = "okay";');
-    lines.push(`    cs-gpios = <&${gpioController(cs)} ${cs} GPIO_ACTIVE_LOW>;`);
+    lines.push(`    cs-gpios = <&${gpioController(cs)} ${cs} GPIO_ACTIVE_LOW>${spiTouchCs !== undefined ? `, <&${gpioController(spiTouchCs)} ${spiTouchCs} GPIO_ACTIVE_LOW>` : ''};`);
     // Enable GDMA for the SPI2 host. The ESP32 SPI driver uses DMA only when
     // dma-enabled is set AND dmas wires tx/rx channels to the GDMA controller;
     // without it, transfers run PIO through the 64-byte FIFO (~4MHz effective at
@@ -146,25 +168,37 @@ function emitDisplayNode(lines, display, wiring) {
     lines.push('/ {');
     lines.push('    mipi_dbi: mipi-dbi {');
     lines.push('        compatible = "zephyr,mipi-dbi-spi";');
-    lines.push('        spi-dev = <&spi2>;');
+    lines.push(`        spi-dev = <&${bus}>;`);
     lines.push(`        dc-gpios = <&${gpioController(dc)} ${dc} GPIO_ACTIVE_HIGH>;`);
     lines.push(`        reset-gpios = <&${gpioController(rst)} ${rst} GPIO_ACTIVE_LOW>;`);
     lines.push('        write-only;');
     lines.push('        #address-cells = <1>;');
     lines.push('        #size-cells = <0>;');
     lines.push(`        ${display.dtLabel}: display@0 {`);
-    lines.push('            compatible = "sitronix,st7796s";');
+    lines.push(`            compatible = "${compatible}";`);
     lines.push('            reg = <0>;');
     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>;');
     lines.push(`            width = <${nativeW}>;`);
     lines.push(`            height = <${nativeH}>;`);
-    // MADCTL: rotation 1 (landscape, MV=1) + BGR bit, matching the adapter's
-    // direct-drive init (0x28). The DT copy keeps the stock driver's init
-    // consistent if it is ever exercised.
-    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];');
+    if (controller === 'st7796s') {
+        // MADCTL: rotation 1 (landscape, MV=1) + BGR bit, matching the adapter's
+        // direct-drive init (0x28). The DT copy keeps the stock driver's init
+        // consistent if it is ever exercised.
+        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];');
+    }
+    else {
+        // 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}>;`);
+    }
     lines.push('        };');
     lines.push('    };');
     lines.push('};');
@@ -190,13 +224,33 @@ function emitDisplayNode(lines, display, wiring) {
         lines.push('');
     }
 }
+/** Default XPT2046 CS/IRQ pins (ESP32-S3 GPIOs clear of the demo-st display
+ *  wiring: 5/17/16/15 and the remuxed SPI pins). Config values override. */
+const DEFAULT_XPT2046_CS = 6;
+const DEFAULT_XPT2046_IRQ = 7;
 /**
- * Emit an FT6336U touch DT node on the first I2C controller. The node address
- * is the FT6336U default (0x38). The UI touch adapter references
- * DT_NODELABEL(ft6336u). Pin wiring (irq/resetPin/sda/scl) comes from the
- * touch config; defaults match the demo-st wiring if absent.
+ * Emit the touch DT node for the configured controller.
+ *
+ * FT6336U (capacitive, I2C): node on i2c0 at the FT6336U default address
+ * (0x38); the C++ touch adapter reads it via i2c_write_read_dt.
+ *
+ * XPT2046 (resistive, SPI): node on the display's SPI bus as CS index 1. The
+ * in-tree xptek,xpt2046 binding (drivers/input) is register-matched for the
+ * raw SPI access — CONFIG_INPUT stays off, so the in-tree input driver does
+ * not build and the adapter owns the chip (same pattern as FT6336U reusing
+ * the ft5336 binding). The binding requires int-gpios, touchscreen-size-*,
+ * and min/max calibration props, so defaults are filled for anything the
+ * config omits.
  */
-function emitTouchNode(lines, touch) {
+function emitTouchNode(lines, touch, display) {
+    if (touch?.controller === 'xpt2046') {
+        emitXpt2046Node(lines, touch, display);
+        return;
+    }
+    emitFt6336uNode(lines, touch);
+}
+/** FT6336U capacitive touch node on the first I2C controller. */
+function emitFt6336uNode(lines, touch) {
     const irq = touch?.irq ?? 15;
     const resetPin = touch?.resetPin;
     const sda = touch?.sda;
@@ -244,3 +298,47 @@ function emitTouchNode(lines, touch) {
     lines.push('};');
     lines.push('');
 }
+/** XPT2046 resistive touch node on the display's SPI bus (CS index 1). */
+function emitXpt2046Node(lines, touch, display) {
+    const bus = display?.busLabel ?? 'spi2';
+    const cs = touch.cs ?? DEFAULT_XPT2046_CS;
+    const irq = touch.irq ?? DEFAULT_XPT2046_IRQ;
+    const cal = touch.calibration;
+    // ESP32-S3 GPIOs 0-31 are on gpio0, 32-48 on gpio1.
+    const gpioController = (pin) => pin <= 31 ? 'gpio0' : 'gpio1';
+    const zThreshold = touch.minPressure ?? 400;
+    // touchscreen-size-* describe the panel the touch layer sits on (the display
+    // profile's effective size); a touch-only build falls back to the 12-bit
+    // full-scale range so the binding's required props still resolve.
+    const sizeX = display?.width ?? cal?.xMax ?? 320;
+    const sizeY = display?.height ?? cal?.yMax ?? 240;
+    // The display block already wrote cs-gpios with both entries (its CS at
+    // index 0, the touch CS at index 1). When there is no display block, enable
+    // the bus here with the touch CS as the only entry.
+    if (!display) {
+        lines.push(`&${bus} {`);
+        lines.push('    status = "okay";');
+        lines.push(`    cs-gpios = <&${gpioController(cs)} ${cs} GPIO_ACTIVE_LOW>;`);
+        lines.push('};');
+        lines.push('');
+    }
+    lines.push(`&${bus} {`);
+    lines.push('    xpt2046: xpt2046@1 {');
+    lines.push('        compatible = "xptek,xpt2046";');
+    lines.push('        reg = <1>;');
+    // The XPT2046 datasheet max SPI clock is 2.5MHz — the panel bus may run at
+    // 80MHz, but this node's spi-max-frequency gates only its own transactions
+    // (the adapter's SPI_DT_SPEC picks it up).
+    lines.push('        spi-max-frequency = <2500000>;');
+    lines.push(`        int-gpios = <&${gpioController(irq)} ${irq} GPIO_ACTIVE_LOW>;`);
+    lines.push(`        touchscreen-size-x = <${sizeX}>;`);
+    lines.push(`        touchscreen-size-y = <${sizeY}>;`);
+    lines.push(`        min-x = <${cal?.xMin ?? 0}>;`);
+    lines.push(`        max-x = <${cal?.xMax ?? 4095}>;`);
+    lines.push(`        min-y = <${cal?.yMin ?? 0}>;`);
+    lines.push(`        max-y = <${cal?.yMax ?? 4095}>;`);
+    lines.push(`        z-threshold = <${zThreshold}>;`);
+    lines.push('    };');
+    lines.push('};');
+    lines.push('');
+}

package/dist/framework.manifest.d.ts

@@ -1,40 +1,40 @@
 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: "ino" | "cc" | "cpp" | "h";
         generateHeaderFile: boolean;
         overrideBaseName?: string | undefined;
         outputSubdirectory?: string | undefined;
         customBridgeShim?: string | undefined;
     };
     profile: {
-        targets: string[];
         forcedIncludes: string[];
         symbolAliases: Record<string, string>;
-    };
-    hal: {
-        [x: string]: {
-            supported: boolean;
-            ops: Record<string, "supported" | "stub" | "unsupported" | "probe-inconclusive" | "polyfill">;
-            partialCoverage: boolean;
-            unsupportedReason?: string | undefined;
-        };
-        raw?: unknown;
-    } & {
-        [k: string]: {
-            supported: boolean;
-            ops: Record<string, "supported" | "stub" | "unsupported" | "probe-inconclusive" | "polyfill">;
-            partialCoverage: boolean;
-            unsupportedReason?: string | undefined;
-        };
+        targets: string[];
     };
     polyfills: {
         emitted: {
@@ -54,16 +54,17 @@ declare const _default: {
             compile: boolean;
             upload: boolean;
             monitor: boolean;
+            debug?: boolean | undefined;
         };
         reexportedFrom?: string | undefined;
     };
     typeEmission: {
-        normalizeCppType: boolean;
-        mathHeader: "none" | "<math.h>" | "<Arduino.h>";
+        needsIostream: boolean;
         needsStdString: boolean;
         needsStdVector: boolean;
-        needsIostream: boolean;
         needsStdFunction: boolean;
+        mathHeader: "none" | "<math.h>" | "<Arduino.h>";
+        normalizeCppType: boolean;
         stdlibSupport: {
             hasVector: boolean;
             hasString: boolean;
@@ -79,6 +80,12 @@ declare const _default: {
         hardwareTestGroups: string[];
         halResolutionTests: string[];
     };
+    doctor?: {
+        available: boolean;
+    } | undefined;
+    licenses?: {
+        available: boolean;
+    } | undefined;
     basedOn?: string | undefined;
     inheritsStrategyId?: string | undefined;
     libraryResolution?: {
@@ -88,12 +95,6 @@ declare const _default: {
         tryGenerateLibDecl: boolean;
         reexportedFrom?: string | undefined;
     } | undefined;
-    doctor?: {
-        available: boolean;
-    } | undefined;
-    licenses?: {
-        available: boolean;
-    } | undefined;
     compat?: {
         zephyr?: string | undefined;
     } | undefined;