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

package/dist/dt-config/kconfig.js

@@ -44,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

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

@@ -10,6 +10,9 @@ export interface DisplayWiring {
     cs?: number;
     dc?: number;
     rst?: number;
+    /** Tearing-effect (TE) GPIO from display.tearingEffectPin — emitted as
+     *  te-gpios on the display DT node. Opt-in; most boards don't wire TE. */
+    tearingEffectPin?: number;
     spiFrequency?: number;
     /** SPI bus pins. When present, the overlay remuxes the SPI controller's
      *  pinctrl to these pins (the board defaults rarely match a breakout's
@@ -25,11 +28,32 @@ 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 interface OverlayDiagnostic {
+    severity: "warning" | "error";
+    message: string;
 }
-export declare function generateOverlay(chip: ZephyrChipDescriptor, usage: KconfigUsage, display: ZephyrDisplayProfile | undefined, wiring?: DisplayWiring, touch?: TouchWiring): string;
+export declare function generateOverlay(chip: ZephyrChipDescriptor, usage: KconfigUsage, display: ZephyrDisplayProfile | undefined, wiring?: DisplayWiring, touch?: TouchWiring, diagnostics?: OverlayDiagnostic[]): string;

package/dist/dt-config/overlay.js

@@ -10,7 +10,19 @@
 // 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.)
 // ---------------------------------------------------------------------------
-export function generateOverlay(chip, usage, display, wiring, touch) {
+import { PANEL_CONTROLLER_DEFAULTS, panelControllerFor } from '../display/profiles.js';
+export function generateOverlay(chip, usage, display, wiring, touch, diagnostics = []) {
+    // An I2C touch controller with no explicit bus pins: the overlay enables
+    // i2c0 and instantiates the node, but nothing remuxes the controller to
+    // the wired SDA/SCL (the board's default I2C pins rarely match a
+    // breakout). Every I2C read then fails and touch silently does nothing —
+    // surface it at build time instead of leaving it to a multimeter.
+    if (touch && touch.controller !== 'xpt2046' && (touch.sda === undefined || touch.scl === undefined)) {
+        diagnostics.push({
+            severity: "warning",
+            message: `touch: I2C controller '${touch.controller}' has no sda/scl pins in cuttlefish.config.ts — the overlay enables the bus without a pin assignment, so the controller may never answer. Add touch.sda and touch.scl (the board's default I2C pins are rarely the wired ones).`,
+        });
+    }
     const lines = [
         '/* Auto-generated by @typecad/framework-zephyr from cuttlefish.config.ts. */',
         '/* Enables peripherals the program uses. West merges this over the board DT. */',
@@ -53,14 +65,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
@@ -91,11 +107,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;
@@ -116,7 +142,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)>,`);
@@ -133,9 +161,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
@@ -151,25 +179,44 @@ 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>;');
+    if (wiring?.tearingEffectPin !== undefined) {
+        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.
+        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>;');
     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('};');
@@ -195,13 +242,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;
@@ -249,3 +316,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;

package/dist/framework.manifest.js

@@ -280,8 +280,13 @@ export default defineFrameworkManifest({
         },
         display: {
             supported: true,
-            partialCoverage: false,
-            unsupportedReason: undefined,
+            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: {
@@ -484,6 +489,7 @@ 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' },
@@ -493,7 +499,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: {
         isFrameworkLibraryImport: false,

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { ZephyrStrategy as FrameworkStrategy } from './strategy.js';
 export { ZephyrStrategy } from './strategy.js';
 export { Toolchain } from './toolchain/index.js';
+export { writeProjectDebugArtifacts } from './toolchain/debug-config.js';
 export { runDoctor as doctor } from './doctor.js';
 export { runLicensesPresenter as licenses } from './licenses.js';
 export { chipForTarget, setActiveChip, getActiveChip, XIAO_BLE, } from './chips/index.js';

package/dist/index.js

@@ -8,6 +8,11 @@
 export { ZephyrStrategy as FrameworkStrategy } from './strategy.js';
 export { ZephyrStrategy } from './strategy.js';
 export { Toolchain } from './toolchain/index.js';
+// Create-time starter debug artifacts. The `cuttlefish create` flow reads this
+// optional named export off the loaded framework module (same loader pattern
+// as doctor/licenses) and calls it for freshly scaffolded projects, so F5 in
+// VS Code works before the first build. No-ops for non-GDB targets.
+export { writeProjectDebugArtifacts } from './toolchain/debug-config.js';
 // `cuttlefish doctor` — verify the installed Zephyr is reachable + inside the
 // declared compat range, and preview board-target normalization. Re-exported
 // under the dispatcher-facing alias `doctor` so the loader picks it up as

package/dist/lowering/ble.js

@@ -388,7 +388,9 @@ export function lowerBle(op) {
         case 'ble.on_read':
             // Store the typed read handler as void*; __tc_ble_attr_read casts it back
             // to the right signature based on the char's type field. reinterpret_cast
-            // (not a C-style cast) keeps this AUTOSAR-compliant under --autosar=strict.
+            // (not a C-style cast) avoids M5-0-7, but M5-0-10 still flags it — the
+            // whole type-erased table is covered by a knownPatterns deviation on
+            // that rule (see rules.ts, "BLE type-erased callback table").
             return { code: `__tc_ble.on_read[__tc_ble.current_char] = reinterpret_cast<void*>(${s(o.handler)});` };
         case 'ble.on_write':
             return { code: `__tc_ble.on_write[__tc_ble.current_char] = (${s(o.handler)});` };

package/dist/lowering/gpio.js

@@ -113,9 +113,13 @@ function lowerGpioRaw(op, chip) {
         case 'gpio.read':
             return { expression: `gpio_pin_get_raw(${controller}, ${pin})` };
         case 'gpio.toggle':
-            return {
-                code: `gpio_pin_set_raw(${controller}, ${pin}, !gpio_pin_get_raw(${controller}, ${pin}));`,
-            };
+            // Native atomic toggle — never read-modify-write. gpio_pin_get_raw on
+            // a direction-only output reads the input latch, which is undefined on
+            // SoCs that don't latch it. Zephyr's toggle API has no _raw variant —
+            // gpio_pin_toggle is the driver-level atomic toggle, and for pins
+            // configured without GPIO_ACTIVE_LOW the logical level equals the
+            // physical one, so it matches the get_raw/set_raw used elsewhere.
+            return { code: `gpio_pin_toggle(${controller}, ${pin});` };
         default:
             throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
                 `Open an issue or use rawCpp() to emit it manually.`);

package/dist/strategy.d.ts

@@ -32,6 +32,26 @@ export declare class ZephyrStrategy implements PlatformStrategy {
      * nodes whose resolved `raw` code references it.
      */
     private programUsesAsyncRuntime;
+    /** Pins referenced by gpio.* hal-ops in the program IR. lowerGpio routes a
+     *  pin to its devicetree spec by pin NUMBER, so the structured hal-op pins
+     *  are the authoritative signal for which __tc_dt_* specs are needed —
+     *  regardless of when the final call text is rendered. */
+    private collectGpioPinUsage;
+    /** Run `re` (global) against every raw string in the IR — raw expression
+     *  values plus raw hal-op codes — returning capture group 1 of each match
+     *  (the full match when the regex has no group). This is how references the
+     *  text scanners must see but that never appear as IR call nodes (e.g. a
+     *  rawCpp() escape hatch naming `__tc_dt_sw0` directly) are discovered. */
+    private collectRawMatches;
+    /** Whether the wiring-compat GPIO read surface (__tc_gpio_read definition,
+     *  __tc_gpio_dev dispatcher, and the wiring_compat polyfill's digitalRead /
+     *  HIGH / LOW macros) must be emitted. Consumers: user digitalRead() calls
+     *  (usesDigitalRead), the @typecad/safety voter (calls __tc_gpio_read
+     *  directly via lowered raw text), and the UI runtime header's
+     *  unconditional digitalRead() poll (entryHasUI — build-global, so every TU
+     *  in a UI build carries the macros). With no analysis present (capability
+     *  query), default to emitting — same convention as the uses() helper. */
+    private needsGpioReadShim;
     shimLines(program?: ProgramIR, ctx?: PlatformContext): string[];
     profileDiagnostics(program?: ProgramIR, ctx?: PlatformContext): Diagnostic[];
     /**
@@ -78,6 +98,10 @@ export declare class ZephyrStrategy implements PlatformStrategy {
     passthroughMacroNames(): ReadonlySet<string>;
     apiReservedEnumNames(): ReadonlySet<string>;
     apiReservedEnumGuard(): string;
+    isrUnsafeOperations(): Map<string, {
+        reason: string;
+        severity: 'warning' | 'info';
+    }>;
     ambientTypeDeclarations(): string[];
     needsIostream(): boolean;
     needsStdString(): boolean;