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

package/src/doctor.ts

@@ -1,56 +1,77 @@
-// ---------------------------------------------------------------------------
-// @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).
-// ---------------------------------------------------------------------------
-
-import * as ui from '@typecad/cuttlefish/utils/ui';
-import { loadCuttlefishConfig } from '@typecad/cuttlefish/config-loader';
-import { detectZephyrVersion, checkZephyrCompat, resolveBoardTarget } from './toolchain/compat.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.
- */
-export function runDoctor(): void {
-  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') {
-    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;
-  if (buildTarget) {
-    const resolved = resolveBoardTarget(buildTarget, version);
-    ui.printInfo(`Board target .... ${buildTarget}${resolved === buildTarget ? '' : ` → ${resolved}`}`);
-  }
-}
+// ---------------------------------------------------------------------------
+// @typecad/framework-zephyr — Zephyr environment doctor
+//
+// `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 { checkZephyrEnv } from './toolchain/env-check.js';
+
+/**
+ * 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(): void {
+  ui.printHeader();
+  ui.printStep('Checking Zephyr environment...');
+
+  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');
+  }
+
+  // Board target — the analog of the Arduino core presence check.
+  if (buildTarget) {
+    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/src/dt-config/kconfig.ts

@@ -11,6 +11,9 @@
 export interface KconfigUsage {
   usesAdc?: boolean;
   usesPwm?: boolean;
+  usesDac?: boolean;
+  usesFS?: boolean;
+  usesHwtimer?: boolean;
   usesI2c?: boolean;
   usesSpi?: boolean;
   usesUart?: boolean;
@@ -23,8 +26,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';
@@ -49,9 +56,12 @@ export function resolveKconfigFragments(
 
   if (usage.usesAdc) 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');
@@ -62,15 +72,31 @@ export function resolveKconfigFragments(
     // 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
@@ -257,6 +283,19 @@ export function resolveKconfigFragments(
     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/src/dt-config/overlay.ts

@@ -13,6 +13,7 @@
 
 import type { ZephyrChipDescriptor } from '../chips/types.js';
 import type { ZephyrDisplayProfile } from '../display/profiles.js';
+import { PANEL_CONTROLLER_DEFAULTS, panelControllerFor } from '../display/profiles.js';
 import type { KconfigUsage } from './kconfig.js';
 
 /**
@@ -40,12 +41,24 @@ export interface DisplayWiring {
   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 function generateOverlay(
@@ -84,6 +97,11 @@ export function generateOverlay(
   if (usage.usesUart && chip.uart) {
     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 }`
@@ -91,14 +109,23 @@ export function generateOverlay(
     // 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
@@ -133,11 +160,26 @@ export function generateOverlay(
 }
 
 /**
- * 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: string[], display: ZephyrDisplayProfile, wiring?: DisplayWiring): void {
+function emitDisplayNode(
+  lines: string[],
+  display: ZephyrDisplayProfile,
+  wiring?: DisplayWiring,
+  spiTouchCs?: number,
+): void {
+  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;
@@ -158,7 +200,9 @@ function emitDisplayNode(lines: string[], display: ZephyrDisplayProfile, 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)>,`);
@@ -175,9 +219,9 @@ function emitDisplayNode(lines: string[], display: ZephyrDisplayProfile, 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
@@ -193,25 +237,36 @@ function emitDisplayNode(lines: string[], display: ZephyrDisplayProfile, 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";');
+            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('};');
@@ -238,13 +293,39 @@ function emitDisplayNode(lines: string[], display: ZephyrDisplayProfile, wiring?
   }
 }
 
+/** 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: string[], touch?: TouchWiring): void {
+function emitTouchNode(
+  lines: string[],
+  touch: TouchWiring | undefined,
+  display: ZephyrDisplayProfile | undefined,
+): void {
+  if (touch?.controller === 'xpt2046') {
+    emitXpt2046Node(lines, touch, display);
+    return;
+  }
+  emitFt6336uNode(lines, touch);
+}
+
+/** FT6336U capacitive touch node on the first I2C controller. */
+function emitFt6336uNode(lines: string[], touch?: TouchWiring): void {
   const irq = touch?.irq ?? 15;
   const resetPin = touch?.resetPin;
   const sda = touch?.sda;
@@ -291,3 +372,52 @@ function emitTouchNode(lines: string[], touch?: TouchWiring): void {
   lines.push('};');
   lines.push('');
 }
+
+/** XPT2046 resistive touch node on the display's SPI bus (CS index 1). */
+function emitXpt2046Node(
+  lines: string[],
+  touch: TouchWiring,
+  display: ZephyrDisplayProfile | undefined,
+): void {
+  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: number) => 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/src/framework.manifest.ts

@@ -113,9 +113,13 @@ export default defineFrameworkManifest({
       },
     },
     dac: {
-      supported: false,
-      unsupportedReason: 'No DAC lowering implemented in the framework (not applicable on nRF52840; ESP32 variants with DAC not yet wired).',
-      ops: { 'dac.write': 'unsupported' },
+      // ESP32 DAC (2× 8-bit channels on GPIO25/26) via the Zephyr DAC driver
+      // (dac_channel_setup + dac_write_value). nRF52840 / ESP32-S3 have no DAC;
+      // usage there lowers to a comment and profileDiagnostics flags it
+      // (zephyr-dac-pin-unavailable).
+      supported: true,
+      partialCoverage: true,
+      ops: { 'dac.write': 'supported' },
     },
     interrupts: {
       supported: true,
@@ -285,9 +289,14 @@ export default defineFrameworkManifest({
     },
     display: {
       supported: true,
-      partialCoverage: false,
-      unsupportedReason: undefined,
-      drivers: ['ili9341-zephyr', 'st7796-zephyr'],
+      partialCoverage: true,
+      // Partial: mono profiles (ssd1306-zephyr) drive display.* ops via the
+      // direct GFX runtime only — no CuttlefishGFX UI rendering path. The
+      // ILI9341 UI adapter shares the ST7796S direct-drive transport with a
+      // per-controller init table (16-bit RGB565 wire format); hardware-tuned
+      // on ST7796S only. E-ink panels are out of scope at this time.
+      unsupportedReason: 'Mono panels (ssd1306) are direct-op only (no UI rendering); ili9341 UI path is ported but not yet hardware-verified; e-ink is out of scope at this time.',
+      drivers: ['ili9341-zephyr', 'st7796-zephyr', 'ssd1306-zephyr'],
       colorFormat: 'rgb565',
       ops: {
         'display.init': 'supported',
@@ -370,10 +379,17 @@ export default defineFrameworkManifest({
       },
     },
     fs: {
-      supported: false,
-      unsupportedReason: 'No filesystem lowering on Zephyr (Zephyr has its own FS API; not wired).',
+      // littlefs on the board's storage_partition, via <zephyr/fs/fs.h>. The
+      // shim mounts at /lfs lazily (formats on first use) and the HAL paths are
+      // treated as paths within the filesystem. Requires CONFIG_FILE_SYSTEM +
+      // CONFIG_FILE_SYSTEM_LITTLEFS (emitted by the scaffold when fs.* is used)
+      // and the storage_partition node.
+      supported: true,
       partialCoverage: false,
-      ops: unsupportedOps('fs.'),
+      ops: {
+        'fs.begin': 'supported', 'fs.read_text': 'supported', 'fs.write_text': 'supported',
+        'fs.exists': 'supported', 'fs.remove': 'supported',
+      },
     },
     mdns: {
       supported: false,
@@ -410,10 +426,17 @@ export default defineFrameworkManifest({
       ops: { 'temp.read': 'unsupported' },
     },
     hwtimer: {
-      supported: false,
-      unsupportedReason: 'No hardware-timer lowering on Zephyr (timers are handled via the k_timer polyfill, not hwtimer.*).',
-      partialCoverage: false,
-      ops: unsupportedOps('hwtimer.'),
+      // Hardware timers via the Zephyr counter driver (<zephyr/drivers/counter.h>).
+      // set_frequency → top value (counter_freq/hz) + on_overflow callback;
+      // start arms both; stop halts. A chip declares its free counters
+      // (e.g. nRF RTC1; RTC0 is kernel-owned). This is distinct from the JS
+      // setInterval/setTimeout k_timer polyfill, which is unaffected.
+      supported: true,
+      partialCoverage: true,
+      ops: {
+        'hwtimer.set_frequency': 'supported', 'hwtimer.on_overflow': 'supported',
+        'hwtimer.start': 'supported', 'hwtimer.stop': 'supported',
+      },
     },
     capacitive: {
       // FT6336U capacitive touch is handled via the strategy-owned touch adapter
@@ -481,6 +504,9 @@ export default defineFrameworkManifest({
   polyfills: {
     emitted: [
       { id: 'cuttlefish_halt', domain: 'standard', notes: 'Mapped to a k_msleep halt loop (exceptions disabled)' },
+      { id: 'wiring_compat', domain: 'standard', notes: 'HIGH/LOW/digitalRead/etc. macros routing Wiring tokens (referenced unconditionally by the UI runtime header) to the __tc_gpio_* helpers' },
+      { id: 'string_methods', domain: 'embedded', notes: 'STL-free __tc_* string helpers (const char*, inline ASCII case conv, <cstring> only)' },
+      { id: 'static_array', domain: 'embedded', notes: 'STL-free __tc_StaticArray<T,N> wrapper for no-<vector> mutated/struct array literals' },
       { id: 'timer_methods', domain: 'embedded', notes: 'k_timer + k_work pool (system workqueue); callbacks run in thread context' },
       { id: 'async_runtime', domain: 'embedded', notes: 'Heap-free static Promise/microtask runtime (generateStaticAsyncRuntime), pumped in loop()' },
     ],
@@ -489,7 +515,7 @@ export default defineFrameworkManifest({
 
   toolchain: {
     backend: 'west',
-    operations: { prepare: true, compile: true, upload: true, monitor: true },
+    operations: { prepare: true, compile: true, upload: true, monitor: true, debug: true },
   },
 
   libraryResolution: {
@@ -537,9 +563,9 @@ export default defineFrameworkManifest({
     // pure string-snapshot tests (no hardware); they are the safety net that
     // catches regressions like silent pull-resistor / interrupt no-ops.
     halResolutionTests: [
-      'adc', 'ble', 'board', 'dac', 'gpio', 'http', 'i2c', 'interrupts', 'mqtt',
-      'power', 'preferences', 'pulse', 'pwm', 'random', 'spi', 'timing', 'tone',
-      'uart', 'wdt', 'worker',
+      'adc', 'ble', 'board', 'dac', 'fs', 'gpio', 'http', 'hwtimer', 'i2c',
+      'interrupts', 'mqtt', 'power', 'preferences', 'pulse', 'pwm', 'random',
+      'spi', 'timing', 'tone', 'uart', 'wdt', 'worker',
     ],
   },
 
@@ -555,4 +581,8 @@ export default defineFrameworkManifest({
   // `cuttlefish doctor` prints the detected Zephyr version + compat result and
   // previews how the configured board target resolves for that version.
   doctor: { available: true },
+
+  // `cuttlefish licenses` enumerates the Zephyr kernel + west manifest projects
+  // and resolves each one's SPDX license (mirrors framework-arduino).
+  licenses: { available: true },
 });

package/src/index.ts

@@ -16,6 +16,12 @@ export { Toolchain } from './toolchain/index.js';
 // mod.doctor (see framework-package.ts).
 export { runDoctor as doctor } from './doctor.js';
 
+// `cuttlefish licenses` — enumerate the Zephyr kernel + west manifest projects
+// and resolve each one's SPDX license. Re-exported under the dispatcher-facing
+// alias `licenses` so the loader picks it up as mod.licenses (see
+// framework-package.ts). Mirrors framework-arduino's presenter.
+export { runLicensesPresenter as licenses } from './licenses.js';
+
 // Chip descriptor registry (for downstream tooling / additional boards).
 export {
   chipForTarget,