@typecad/framework-zephyr 1.0.0-alpha.11 → 1.0.0-alpha.13

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

@@ -15,7 +15,32 @@ export interface ZephyrDisplayProfile {
     readonly rotation?: number;
     /** DT alias for the backlight GPIO (set high at init), if any. */
     readonly backlight?: string;
+    /** Panel controller the direct-drive UI adapter targets. Selects the init
+     *  sequence + pixel wire format (ST7796S: 18-bit; ILI9341: 16-bit RGB565).
+     *  Required for rgb565 profiles; mono profiles use the direct-op GFX
+     *  runtime and ignore it. */
+    readonly controller?: ZephyrPanelController;
+    /** DT compatible string for the display@0 node. Defaults per controller
+     *  (see PANEL_CONTROLLER_DEFAULTS) — override only for a panel whose DT
+     *  binding differs from its controller family. */
+    readonly dtCompatible?: string;
+    /** SPI controller nodelabel the panel hangs off (and SPI touch, if any).
+     *  Default 'spi2' — the ESP32-S3 first general-purpose SPI controller. */
+    readonly busLabel?: string;
+    /** Nodelabel of the MIPI DBI bridge node carrying the dc/reset GPIOs.
+     *  Default 'mipi_dbi' (the overlay emits the bridge under that label). */
+    readonly bridgeLabel?: string;
 }
+/** Panel controllers the direct-drive UI adapter knows how to init. */
+export type ZephyrPanelController = 'st7796s' | 'ili9341';
+/** Per-controller DT + transport defaults, shared by the overlay generator
+ *  (DT node props) and the UI adapter (init sequence + wire format). */
+export declare const PANEL_CONTROLLER_DEFAULTS: Record<ZephyrPanelController, {
+    dtCompatible: string;
+}>;
+/** Resolve a profile's panel controller, inferring it from the driver id when
+ *  the profile doesn't declare one (the '<controller>-zephyr' naming scheme). */
+export declare function panelControllerFor(profile: Pick<ZephyrDisplayProfile, 'driver' | 'controller'>): ZephyrPanelController;
 /**
  * Built-in profile registry. Looked up by driver id. Add a profile here when a
  * new board's display node is wired into its devicetree.
@@ -23,3 +48,11 @@ export interface 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

@@ -6,6 +6,21 @@
 // pin wiring. The GFX runtime (gfx.ts) reads width/height/colorFormat from the
 // active profile to size its line buffer.
 // ---------------------------------------------------------------------------
+/** Per-controller DT + transport defaults, shared by the overlay generator
+ *  (DT node props) and the UI adapter (init sequence + wire format). */
+export const PANEL_CONTROLLER_DEFAULTS = {
+    st7796s: { dtCompatible: 'sitronix,st7796s' },
+    ili9341: { dtCompatible: 'ilitek,ili9341' },
+};
+/** Resolve a profile's panel controller, inferring it from the driver id when
+ *  the profile doesn't declare one (the '<controller>-zephyr' naming scheme). */
+export function panelControllerFor(profile) {
+    if (profile.controller)
+        return profile.controller;
+    if (profile.driver.startsWith('ili9341'))
+        return 'ili9341';
+    return 'st7796s';
+}
 /**
  * Built-in profile registry. Looked up by driver id. Add a profile here when a
  * new board's display node is wired into its devicetree.
@@ -17,6 +32,7 @@ export const ZEPHYR_DISPLAY_PROFILES = {
         width: 320,
         height: 240,
         colorFormat: 'rgb565',
+        controller: 'ili9341',
         rotation: 90,
         backlight: 'backlight',
     },
@@ -33,6 +49,7 @@ export const ZEPHYR_DISPLAY_PROFILES = {
         nativeWidth: 320,
         nativeHeight: 480,
         colorFormat: 'rgb565',
+        controller: 'st7796s',
         rotation: 1,
         backlight: 'backlight',
     },
@@ -52,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/touch-adapter.d.ts

@@ -1,9 +1,8 @@
 import type { TouchAdapterCodegen } from "@typecad/cuttlefish/api/shared";
 import type { TouchProfile } from "@typecad/cuttlefish/api/shared";
 /**
- * Generate the FT6336U touch adapter for Zephyr. Emits touch_init /
- * touch_isTouched / touch_readRaw — the three symbols the runtime's
- * ui_poll_touch body calls. Returns undefined for other libraries so the
- * strategy can decline.
+ * Generate a Zephyr touch adapter for the profile's library. Returns
+ * undefined for libraries this framework doesn't handle so the strategy can
+ * decline and cuttlefish surfaces a clear error.
  */
 export declare function zephyrTouchAdapter(touch: TouchProfile): TouchAdapterCodegen | undefined;

package/dist/display/touch-adapter.js

@@ -1,29 +1,132 @@
 // ---------------------------------------------------------------------------
-// Zephyr touch adapter for the Cuttlefish UI rendering pipeline.
+// Zephyr touch adapters for the Cuttlefish UI rendering pipeline.
 //
-// FT6336U capacitive touch controller over I2C, driven via Zephyr's
-// device-tree-bound I2C API (i2c_write_read_dt). This is the Zephyr analog of
-// the Arduino FT6336U adapter in framework-arduino (touch-adapters-codegen.ts)
-// and the stale native ESP32 reference (demo-display/.../main.cc).
+// Two controllers, both driven directly (polling, no in-tree driver):
+//   - FT6336U capacitive over I2C (i2c_write_read_dt)
+//   - XPT2046 resistive over SPI (spi_transceive_dt) — the Zephyr analog of
+//     Arduino's XPT2046_Touchscreen adapter. The DT node uses the in-tree
+//     xptek,xpt2046 binding; CONFIG_INPUT stays off, so the in-tree input
+//     driver does not build and this adapter owns the chip.
 //
-// The touch node is resolved via DEVICE_DT_GET(DT_NODELABEL(ft6336u)). The
-// board's devicetree must carry an `ft6336u` nodelabel with the I2C spec +
-// the `focaltech,ft6336u` (or compatible) binding so the device is ready.
+// The adapters emit touch_init / touch_isTouched / touch_readRaw — the three
+// symbols the runtime's ui_poll_touch body calls.
 //
 // EMIT BOUNDARY: emitted bytes land in user firmware. Covered by the TypeCAD
 // Runtime Exception (RUNTIME_EXCEPTION.md at the repo root).
 // ---------------------------------------------------------------------------
 /**
- * Generate the FT6336U touch adapter for Zephyr. Emits touch_init /
- * touch_isTouched / touch_readRaw — the three symbols the runtime's
- * ui_poll_touch body calls. Returns undefined for other libraries so the
- * strategy can decline.
+ * Generate a Zephyr touch adapter for the profile's library. Returns
+ * undefined for libraries this framework doesn't handle so the strategy can
+ * decline and cuttlefish surfaces a clear error.
  */
 export function zephyrTouchAdapter(touch) {
-    if (touch.library !== "FT6336U")
-        return undefined;
-    const addr = touch.i2cAddress ?? 0x38;
-    const addrHex = "0x" + addr.toString(16).toUpperCase();
+    if (touch.library === "XPT2046_Touchscreen")
+        return xpt2046Adapter(touch);
+    if (touch.library === "FT6336U")
+        return ft6336uAdapter(touch);
+    return undefined;
+}
+/** XPT2046 control bytes (12-bit differential mode, auto power-down). */
+const XPT2046_CMD_X = 0x90;
+const XPT2046_CMD_Y = 0xd0;
+const XPT2046_CMD_Z1 = 0xb0;
+const hex = (v) => `0x${v.toString(16).toUpperCase()}`;
+function xpt2046Adapter(touch) {
+    // Pen-detect Z1 threshold (raw 12-bit counts). Resistive panels need a few
+    // hundred counts above noise; the TouchProfile default (10) is far too low
+    // for raw Z1, so the adapter defaults to 400 (the Arduino XPT2046
+    // library's Z_THRESHOLD) unless the config sets one explicitly.
+    const zThreshold = touch.minPressure ?? 400;
+    return {
+        includes: [
+            `#include <zephyr/kernel.h>`,
+            `#include <zephyr/drivers/spi.h>`,
+            `#include <zephyr/drivers/gpio.h>`,
+        ],
+        declaration: [
+            `// Zephyr XPT2046 resistive touch — SPI device resolved via devicetree.`,
+            `// The overlay defines the 'xpt2046' nodelabel on the panel's SPI bus`,
+            `// (CS index 1) with the xptek,xpt2046 binding; the bus + CS + 2.5MHz`,
+            `// ceiling come from that node. Raw X/Y/Z1 values are reported — the`,
+            `// runtime applies the profile calibration + rotation.`,
+            `static const struct spi_dt_spec __tc_touch =`,
+            `    SPI_DT_SPEC_GET(DT_NODELABEL(xpt2046), SPI_OP_MODE_MASTER | SPI_WORD_SET(8), 0U);`,
+            `static int16_t __tc_touch_cached_x = 0;`,
+            `static int16_t __tc_touch_cached_y = 0;`,
+            `static int16_t __tc_touch_cached_z = 0;`,
+            `static uint8_t __tc_touch_cached_valid = 0;`,
+            `#if DT_NODE_HAS_PROP(DT_NODELABEL(xpt2046), int_gpios)`,
+            `static const struct gpio_dt_spec __tc_touch_irq = GPIO_DT_SPEC_GET(DT_NODELABEL(xpt2046), int_gpios);`,
+            `static uint8_t __tc_touch_irq_ready = 0;`,
+            `#endif`,
+        ].join("\n"),
+        functions: [
+            `// One XPT2046 conversion: clock out a control byte, read the 12-bit`,
+            `// result. The rx byte during the command phase is a dummy; the value is`,
+            `// MSB-aligned across the following 16 bits ((b1<<8 | b2) >> 3). The`,
+            `// control byte's PD bits are 00 (auto power-down between transactions),`,
+            `// so the bus stays shareable with the panel. Touch is polled every frame`,
+            `// from ui_poll_touch, so a failed transfer is non-fatal — returns 0 and`,
+            `// touch_isTouched() reports false.`,
+            `static uint16_t __tc_xpt_read(uint8_t cmd) {`,
+            `  if (!device_is_ready(__tc_touch.bus)) return 0U;`,
+            `  uint8_t __tx[3] = { cmd, 0U, 0U };`,
+            `  uint8_t __rx[3] = { 0U, 0U, 0U };`,
+            `  struct spi_buf __bt = { __tx, sizeof(__tx) };`,
+            `  struct spi_buf __br = { __rx, sizeof(__rx) };`,
+            `  struct spi_buf_set __st = { &__bt, 1 };`,
+            `  struct spi_buf_set __sr = { &__br, 1 };`,
+            `  if (spi_transceive_dt(&__tc_touch, &__st, &__sr) != 0) return 0U;`,
+            `  return static_cast<uint16_t>(((static_cast<uint16_t>(__rx[1]) << 8) | __rx[2]) >> 3);`,
+            `}`,
+            ``,
+            `static inline void touch_init() {`,
+            `  // The SPI bus + CS are configured by devicetree. Configure the pen IRQ`,
+            `  // input (active low) when the overlay wired it — the cheap detect path.`,
+            `#if DT_NODE_HAS_PROP(DT_NODELABEL(xpt2046), int_gpios)`,
+            `  if (device_is_ready(__tc_touch_irq.port)) {`,
+            `    gpio_pin_configure_dt(&__tc_touch_irq, GPIO_INPUT);`,
+            `    __tc_touch_irq_ready = 1U;`,
+            `  }`,
+            `#endif`,
+            `  (void)device_is_ready(__tc_touch.bus);`,
+            `}`,
+            ``,
+            `static inline bool touch_isTouched() {`,
+            `  __tc_touch_cached_valid = 0;`,
+            `  __tc_touch_cached_z = 0;`,
+            `#if DT_NODE_HAS_PROP(DT_NODELABEL(xpt2046), int_gpios)`,
+            `  if (__tc_touch_irq_ready != 0U) {`,
+            `    // PENIRQ asserts (active low) while the panel is pressed — no SPI`,
+            `    // traffic needed to answer the per-frame poll.`,
+            `    if (gpio_pin_get_dt(&__tc_touch_irq) <= 0) return false;`,
+            `  }`,
+            `#endif`,
+            `  // No IRQ (or it fired): confirm via Z1 pressure before reading coords.`,
+            `  uint16_t __z1 = __tc_xpt_read(${hex(XPT2046_CMD_Z1)});`,
+            `  if (__z1 <= ${zThreshold}) return false;`,
+            `  __tc_touch_cached_x = static_cast<int16_t>(__tc_xpt_read(${hex(XPT2046_CMD_X)}));`,
+            `  __tc_touch_cached_y = static_cast<int16_t>(__tc_xpt_read(${hex(XPT2046_CMD_Y)}));`,
+            `  __tc_touch_cached_z = static_cast<int16_t>(__z1);`,
+            `  __tc_touch_cached_valid = 1;`,
+            `  return true;`,
+            `}`,
+            ``,
+            `static inline void touch_readRaw(int16_t* x, int16_t* y, int16_t* z) {`,
+            `  // touch_isTouched() is polled each frame by ui_poll_touch; the cached`,
+            `  // values are fresh. If something calls readRaw before isTouched, probe now.`,
+            `  if (!__tc_touch_cached_valid) {`,
+            `    (void)touch_isTouched();`,
+            `  }`,
+            `  if (x) *x = __tc_touch_cached_x;`,
+            `  if (y) *y = __tc_touch_cached_y;`,
+            `  if (z) *z = __tc_touch_cached_z;`,
+            `  __tc_touch_cached_valid = 0;`,
+            `}`,
+        ].join("\n"),
+    };
+}
+function ft6336uAdapter(_touch) {
     return {
         includes: [
             `#include <zephyr/drivers/i2c.h>`,

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;
 /**