@typecad/framework-zephyr 1.0.0-alpha.10

package/dist/display/index.js

@@ -0,0 +1,53 @@
+// ---------------------------------------------------------------------------
+// Zephyr display op resolver — maps DisplayHALOp → GFX runtime calls
+//
+// resolveZephyrDisplayOp is a pure function of (op, state): the strategy holds
+// a DisplayState (mirrors Arduino's _displayCtx) and passes it in. On
+// display.init the state is seeded with the active profile; subsequent ops
+// lower to the helpers in gfx.ts.
+//
+// Validator probes call fill_rect/draw_text/draw_rect/flush WITHOUT a prior
+// init, so when state is uninitialized we seed the DEFAULT profile and lower
+// anyway (the probe only checks code/expression is non-undefined).
+// ---------------------------------------------------------------------------
+import { DEFAULT_ZEPHYR_DISPLAY_PROFILE } from './profiles.js';
+// Re-export the UI display/touch adapters + profile registry so the strategy
+// 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';
+/** Fresh display state (used by the strategy per-build). */
+export function newDisplayState() {
+    return { initialized: false, profile: DEFAULT_ZEPHYR_DISPLAY_PROFILE };
+}
+/**
+ * Resolve a display.* op. Returns { code } for statement ops, undefined when
+ * the op is not recognized.
+ */
+export function resolveZephyrDisplayOp(op, state) {
+    const o = op;
+    // display.init seeds the state. The probe payload for init has no profile
+    // fields, so use the default profile.
+    if (op.operation === 'display.init') {
+        state.initialized = true;
+        return { code: 'display_init();' };
+    }
+    // For non-init ops: if not initialized (validator probe path), seed the
+    // default so the op still lowers.
+    if (!state.initialized) {
+        state.initialized = true;
+        state.profile = DEFAULT_ZEPHYR_DISPLAY_PROFILE;
+    }
+    switch (op.operation) {
+        case 'display.fill_rect':
+            return { code: `display_fill_rect(${o.x}, ${o.y}, ${o.w}, ${o.h}, ${o.color});` };
+        case 'display.draw_rect':
+            return { code: `display_draw_rect(${o.x}, ${o.y}, ${o.w}, ${o.h}, ${o.color});` };
+        case 'display.draw_text':
+            return { code: `display_draw_text(${o.x}, ${o.y}, "${o.text}", ${o.color});` };
+        case 'display.flush':
+            return { code: 'display_flush();' };
+        default:
+            return undefined;
+    }
+}

package/dist/display/profiles.d.ts

@@ -0,0 +1,25 @@
+export interface ZephyrDisplayProfile {
+    /** Driver id, matched against ctx.frameworkData.display / manifest drivers. */
+    readonly driver: string;
+    /** Devicetree nodelabel, e.g. 'display0'. Emitted as DT_NODELABEL(<dtLabel>). */
+    readonly dtLabel: string;
+    /** Effective (screen-space) dimensions after rotation. */
+    readonly width: number;
+    readonly height: number;
+    /** Native panel dimensions before rotation, when they differ from the
+     *  effective size (e.g. a 320x480 panel mounted landscape = 480x320). */
+    readonly nativeWidth?: number;
+    readonly nativeHeight?: number;
+    readonly colorFormat: 'rgb565' | 'mono';
+    /** Applied via display_set_orientation (0/90/180/270). */
+    readonly rotation?: number;
+    /** DT alias for the backlight GPIO (set high at init), if any. */
+    readonly backlight?: string;
+}
+/**
+ * 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.
+ */
+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;

package/dist/display/profiles.js

@@ -0,0 +1,41 @@
+// ---------------------------------------------------------------------------
+// Zephyr display profiles — DT-binding descriptors
+//
+// Analog of framework-arduino/src/displays/, but profiles describe a Zephyr
+// devicetree node (DT_NODELABEL) to resolve via DEVICE_DT_GET, not Adafruit
+// pin wiring. The GFX runtime (gfx.ts) reads width/height/colorFormat from the
+// active profile to size its line buffer.
+// ---------------------------------------------------------------------------
+/**
+ * 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.
+ */
+export const ZEPHYR_DISPLAY_PROFILES = {
+    'ili9341-zephyr': {
+        driver: 'ili9341-zephyr',
+        dtLabel: 'display0',
+        width: 320,
+        height: 240,
+        colorFormat: 'rgb565',
+        rotation: 90,
+        backlight: 'backlight',
+    },
+    'st7796-zephyr': {
+        // ST7796S SPI TFT, 320x480 RGB565 mounted landscape (effective 480x320).
+        // Same DT nodelabel convention as the ILI9341 — the board's devicetree
+        // carries the `display0` node bound to the ST7796 driver; the overlay
+        // enables it via status="okay". Effective dims match the Arduino
+        // st7796-spi profile (480x320 landscape, rotation 1).
+        driver: 'st7796-zephyr',
+        dtLabel: 'display0',
+        width: 480,
+        height: 320,
+        nativeWidth: 320,
+        nativeHeight: 480,
+        colorFormat: 'rgb565',
+        rotation: 1,
+        backlight: 'backlight',
+    },
+};
+/** The default profile used when resolveDisplayOp is probed without a display.init. */
+export const DEFAULT_ZEPHYR_DISPLAY_PROFILE = ZEPHYR_DISPLAY_PROFILES['ili9341-zephyr'];

package/dist/display/touch-adapter.d.ts

@@ -0,0 +1,9 @@
+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.
+ */
+export declare function zephyrTouchAdapter(touch: TouchProfile): TouchAdapterCodegen | undefined;

package/dist/display/touch-adapter.js

@@ -0,0 +1,95 @@
+// ---------------------------------------------------------------------------
+// Zephyr touch adapter 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).
+//
+// 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.
+//
+// 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.
+ */
+export function zephyrTouchAdapter(touch) {
+    if (touch.library !== "FT6336U")
+        return undefined;
+    const addr = touch.i2cAddress ?? 0x38;
+    const addrHex = "0x" + addr.toString(16).toUpperCase();
+    return {
+        includes: [
+            `#include <zephyr/drivers/i2c.h>`,
+        ],
+        declaration: [
+            `// Zephyr FT6336U touch — I2C device resolved via devicetree.`,
+            `// The board DT must define an 'ft6336u' nodelabel on an I2C bus.`,
+            `static const struct i2c_dt_spec __tc_touch = I2C_DT_SPEC_GET(DT_NODELABEL(ft6336u));`,
+            `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;`,
+        ].join("\n"),
+        functions: [
+            `// Read N bytes starting from a register address. Returns 1 on success.`,
+            `// Uses i2c_write_read_dt for a combined write-read transaction (register`,
+            `// address write, then repeated-start read). The FT6336U is polled every`,
+            `// frame from ui_poll_touch, so a failed read (stuck SDA, no controller) is`,
+            `// non-fatal — returns 0 and touch_isTreated() returns false.`,
+            `static inline uint8_t __tc_touch_read_block(uint8_t reg, uint8_t* buf, uint8_t len) {`,
+            `  if (!device_is_ready(__tc_touch.bus)) return 0U;`,
+            `  int rc = i2c_write_read_dt(&__tc_touch, &reg, 1U, buf, len);`,
+            `  return (rc == 0) ? 1U : 0U;`,
+            `}`,
+            ``,
+            `static inline void touch_init() {`,
+            `  // The I2C bus + device are configured by devicetree. The FT6336U needs a`,
+            `  // hardware reset (reset pin low → high) to enter normal mode after power-on.`,
+            `#if DT_NODE_HAS_STATUS(DT_NODELABEL(ft6336u), okay) && DT_NODE_HAS_PROP(DT_NODELABEL(ft6336u), reset_gpios)`,
+            `  static const struct gpio_dt_spec __tc_touch_rst = GPIO_DT_SPEC_GET(DT_NODELABEL(ft6336u), reset_gpios);`,
+            `  if (device_is_ready(__tc_touch_rst.port)) {`,
+            `    gpio_pin_configure_dt(&__tc_touch_rst, GPIO_OUTPUT_ACTIVE);    // assert reset (active=low)`,
+            `    k_msleep(10);`,
+            `    gpio_pin_set_dt(&__tc_touch_rst, 0);                            // release reset (inactive=high)`,
+            `    k_msleep(200);  // FT6336U needs ~50ms after reset before responding`,
+            `  }`,
+            `#endif`,
+            `  (void)device_is_ready(__tc_touch.bus);`,
+            `}`,
+            ``,
+            `static inline bool touch_isTouched() {`,
+            `  __tc_touch_cached_valid = 0;`,
+            `  __tc_touch_cached_z = 0;`,
+            `  // Read TD_STATUS (0x02) + P1_XH/XL/YH/YL — 5 bytes in one transaction.`,
+            `  uint8_t buf[5] = {0, 0, 0, 0, 0};`,
+            `  if (!__tc_touch_read_block(0x02, buf, 5U)) return false;`,
+            `  uint8_t count = buf[0] & 0x0F;`,
+            `  if (count == 0U) return false;`,
+            `  __tc_touch_cached_x = static_cast<int16_t>((static_cast<uint16_t>(buf[1] & 0x0F) << 8) | buf[2]);`,
+            `  __tc_touch_cached_y = static_cast<int16_t>((static_cast<uint16_t>(buf[3] & 0x0F) << 8) | buf[4]);`,
+            `  __tc_touch_cached_z = 255;`,
+            `  __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"),
+    };
+}

package/dist/display/ui-adapter.d.ts

@@ -0,0 +1,21 @@
+import type { DisplayAdapterCode, DisplayAdapterGenerator } from "@typecad/cuttlefish/api/shared";
+import type { ZephyrDisplayProfile } from "./profiles.js";
+/**
+ * Build the Zephyr UI display adapter for a profile. Emits the full
+ * display_ / display_target_ / display_canvas_ surface the UI runtime expects,
+ * driving the panel directly via SPI (CS held across command+data).
+ */
+export interface ZephyrDisplayReadbackOptions {
+    /** Enable the controller GET_SCANLINE dirty-rectangle experiment. */
+    scanlineSync?: boolean;
+    /** MISO/SDO GPIO; readback is disabled when it is not explicitly wired. */
+    miso?: number;
+}
+export declare function zephyrUiDisplayAdapter(profile: ZephyrDisplayProfile, readback?: ZephyrDisplayReadbackOptions): DisplayAdapterCode;
+/**
+ * Strategy-owned display adapter generator. Receives the resolved display and
+ * looks up the Zephyr DT-binding profile by driver id. Returns undefined for
+ * unknown drivers so resolveDisplayAdapter can decline and
+ * generateDisplayAdapter surfaces a clear error.
+ */
+export declare const zephyrDisplayAdapterGenerator: DisplayAdapterGenerator;