@typecad/framework-zephyr 1.0.0-alpha.16 → 1.0.0-alpha.19

package/dist/doctor.js

@@ -1,7 +1,7 @@
 // ---------------------------------------------------------------------------
 // @typecad/framework-zephyr — Zephyr environment doctor
 //
-// `cuttlefish doctor` (Zephyr framework) — verify west (the Zephyr build tool)
+// `typecad-hal 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. Follows the same contract
@@ -11,7 +11,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import * as ui from '@typecad/cuttlefish/utils/ui';
-import { loadCuttlefishConfig } from '@typecad/cuttlefish/config-loader';
+import { loadTypecadConfig } from '@typecad/cuttlefish/config-loader';
 import { checkZephyrEnv } from './toolchain/env-check.js';
 import { PINNED_ZEPHYR_MANIFEST_REV, PINNED_ZEPHYR_SDK_VERSION, sdkFingerprint } from '@typecad/cuttlefish/board-catalog';
 import { resolveChipFromBoard } from './chips/resolve.js';
@@ -23,7 +23,7 @@ import { resolveChipFromBoard } from './chips/resolve.js';
 export function runDoctor() {
     ui.printHeader();
     ui.printStep('Checking Zephyr environment...');
-    const config = loadCuttlefishConfig(process.cwd());
+    const config = loadTypecadConfig(process.cwd());
     const buildTarget = config?.buildTarget;
     const result = checkZephyrEnv(buildTarget);
     const c = result.check;
@@ -69,7 +69,7 @@ export function runDoctor() {
         }
     }
     else {
-        ui.printInfo('(no buildTarget in cuttlefish.config.ts — skipping board check)');
+        ui.printInfo('(no buildTarget in typecad-hal.config.ts — skipping board check)');
     }
     // Probe methods — from the board package's table, via the board constants
     // the transpile persists (candidates cover the standard out-dir layouts).

package/dist/dt-config/custom-board.js

@@ -69,7 +69,7 @@ export function generateCustomBoard(projectRoot, chip, rawName) {
             '# package (or add a board package) instead of this file.',
             'board:',
             `  name: ${name}`,
-            `  full_name: Cuttlefish custom board (${chip.soc})`,
+            `  full_name: TypeCAD custom board (${chip.soc})`,
             `  vendor: ${CUSTOM_BOARD_VENDOR}`,
             '  socs:',
             `    - name: ${soc}`,
@@ -95,7 +95,7 @@ export function generateCustomBoard(projectRoot, chip, rawName) {
         ...cb.dtsIncludes.map((inc) => `#include <${inc}>`),
         '',
         '/ {',
-        `	model = "Cuttlefish custom board (${chip.soc})";`,
+        `	model = "TypeCAD custom board (${chip.soc})";`,
         `	compatible = "${CUSTOM_BOARD_VENDOR},${name.replace(/_/g, '-')}";`,
         '',
         '	chosen {',

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

@@ -20,6 +20,12 @@ export interface KconfigUsage {
     usesFS?: boolean;
     usesHwtimer?: boolean;
     usesI2c?: boolean;
+    /** I2C target mode used (i2c.resp_* ops — the responder). Enables the
+     *  i2c_target API paths: driver implementations are gated on it (e.g.
+     *  STM32 compiles target support + selects interrupt mode only under
+     *  I2C_TARGET); controllers without target support still build and
+     *  return -ENOSYS at registration, which the shim prints loudly. */
+    usesI2cTarget?: boolean;
     usesSpi?: boolean;
     usesUart?: boolean;
     /** USB CDC-ACM serial used (usb.* ops). Selects the "next" USB device
@@ -30,6 +36,22 @@ export interface KconfigUsage {
     usesWdt?: boolean;
     usesBle?: boolean;
     usesDisplay?: boolean;
+    /** How the UI adapter reaches the panel. 'zephyr-display' binds the
+     *  in-tree drivers (CONFIG_MIPI_DBI_SPI on); 'direct-spi' (default)
+     *  force-disables them — the adapter drives the panel itself. */
+    displayTransport?: 'direct-spi' | 'zephyr-display';
+    /** Panel controller for the display Kconfig symbol when the transport
+     *  needs one explicitly. Synthesized (compatible-driven) profiles carry
+     *  none — their driver symbol auto-defaults on from the DT node
+     *  (`default y depends on DT_HAS_<COMPATIBLE>_ENABLED`), so no symbol
+     *  is assigned at all. */
+    displayController?: 'st7796s' | 'ili9341' | 'ssd16xx' | 'uc81xx';
+    /** Panel bus family from the binding harvest: i2c-family panels (mono
+     *  OLEDs) get I2C and no SPI/MIPI/DMA block at all. */
+    displayBus?: 'i2c' | 'spi';
+    /** Profile-required Kconfig fragments, appended verbatim (e.g. the SDL
+     *  panel's mono pixel-format choice on native_sim). */
+    displayKconfigExtra?: readonly string[];
     usesWifi?: boolean;
     usesHttp?: boolean;
     usesMqtt?: boolean;
@@ -43,6 +65,44 @@ export interface KconfigUsage {
      *  umbrella under which every driver sensor Kconfig lives (`if SENSOR`);
      *  the per-driver symbols default on from their DT node presence. */
     usesSensor?: boolean;
+    /** Addressable LED strip (strip.* ops → ws2812-spi child). */
+    usesStrip?: boolean;
+    /** Strips the program drives: SPI controller index → chain length.
+     *  Scanned from the emitted shim's buffer declarations. */
+    strips?: Array<{
+        index: number;
+        count: number;
+    }>;
+    /** USB HID keyboard/mouse (hid.* ops → zephyr,hid-device node). */
+    usesHid?: boolean;
+    /** Which HID protocol the program drives — picks the DT node's
+     *  protocol-code and the report descriptor. */
+    hidProtocol?: 'keyboard' | 'mouse';
+    /** GPIO key matrix (matrix.* ops → gpio-kbd-matrix node). */
+    usesMatrix?: boolean;
+    /** The matrix's construction pad lists (from the lowering marker). */
+    matrix?: {
+        rows: number[];
+        cols: number[];
+    };
+    /** Explicit power-state entry (power.* ops → sys_poweroff). */
+    usesPower?: boolean;
+    /** Wall-clock time (clock.* ops → rtc alias). */
+    usesClock?: boolean;
+    /** CAN bus (can.* ops → the harvested can@ controller). */
+    usesCan?: boolean;
+    /** I2S audio (i2s.* ops → the harvested i2s@ controller). */
+    usesI2s?: boolean;
+    /** CAN loopback constructed (CAN_MODE_LOOPBACK in the emission) — the
+     *  overlay routes both TWAI functions onto one pad (no transceiver). */
+    canLoopback?: boolean;
+    /** The counter the rtc shim wraps (label + optional timer parent for
+     *  the child-form ESP32 counters). Omitted when the board ships its own
+     *  rtc alias — the lowering uses the hardware node. */
+    clockShimCounter?: {
+        label: string;
+        parent?: string;
+    };
     /** Distinct constructed sensors — only the overlay generator consumes this
      *  (one DT child node per entry, on the given I2C controller index); prj.conf
      *  ignores it. Same adcReadPins/pwmUsedPins pattern. */
@@ -50,10 +110,11 @@ export interface KconfigUsage {
         part: string;
         busIndex: number;
         port: number;
-        busKind: 'i2c' | 'spi';
+        busKind: 'i2c' | 'spi' | 'w1';
         spiHz?: number;
         spiMode?: number;
         alertPin?: number;
+        resolution?: number;
     }[];
     /** Distinct thin SPI targets (hal/spi-target.ts) — one DT child node per
      *  entry (no compatible — a raw spi_dt_spec peer), appended after sensor

package/dist/dt-config/kconfig.js

@@ -37,6 +37,11 @@ export function resolveKconfigFragments(usage, debug) {
     // DT_HAS_<COMPAT>_ENABLED, so the overlay's child node enables the driver.
     if (usage.usesSensor)
         m.set('CONFIG_SENSOR', 'y');
+    // 1-Wire masters: the w1 core + the bit-banged GPIO driver (default-on
+    // via the synthesized node, but the core W1 menuconfig gates the
+    // drivers — set it explicitly so the menu default cannot hide it).
+    if ((usage.sensorParts ?? []).some((sp) => sp.busKind === 'w1'))
+        m.set('CONFIG_W1', 'y');
     // The rare driver that is NOT DT-default-on: the catalog records its
     // Kconfig lines (from the driver's own Kconfig) and they are applied for
     // exactly the parts the program constructs. Empty for every in-tree part
@@ -51,10 +56,48 @@ export function resolveKconfigFragments(usage, debug) {
     }
     if (usage.usesPwm)
         m.set('CONFIG_PWM', 'y');
+    if (usage.usesStrip)
+        m.set('CONFIG_LED_STRIP', 'y');
+    // HID rides the same "next" device stack as CDC — the class is selected by
+    // the zephyr,hid-device node the overlay synthesizes.
+    if (usage.usesHid) {
+        m.set('CONFIG_USB_DEVICE_STACK_NEXT', 'y');
+        m.set('CONFIG_USBD_HID_SUPPORT', 'y');
+    }
+    if (usage.usesMatrix) {
+        m.set('CONFIG_INPUT', 'y');
+        m.set('CONFIG_INPUT_GPIO_KBD_MATRIX', 'y');
+    }
+    // sys_poweroff() only exists when the kernel builds the poweroff service
+    // (the SoC hook compiles under this symbol — without it the link fails
+    // with an undefined reference).
+    if (usage.usesPower)
+        m.set('CONFIG_POWEROFF', 'y');
+    // The rtc subsystem; the counter shim driver defaults on when the
+    // synthesized zephyr,rtc-counter node exists. RTC_INIT_PRIORITY defaults
+    // to KERNEL_INIT_PRIORITY_DEVICE (=50) which is BELOW the counter driver
+    // (=60) — the shim asserts it inits after its parent counter, so raise
+    // it whenever the shim is in play.
+    if (usage.usesCan)
+        m.set('CONFIG_CAN', 'y');
+    // I2S needs the DMA umbrella + the ESP32 GDMA driver (the controller
+    // DMA-runs through the gdma node the overlay enables — the driver is
+    // default-y once the node is on, but the umbrella needs the explicit
+    // set because nothing else pulls it in).
+    if (usage.usesI2s) {
+        m.set('CONFIG_I2S', 'y');
+        m.set('CONFIG_DMA', 'y');
+    }
+    if (usage.usesClock) {
+        m.set('CONFIG_RTC', 'y');
+        m.set('CONFIG_RTC_INIT_PRIORITY', '70');
+    }
     if (usage.usesDac)
         m.set('CONFIG_DAC', 'y');
     if (usage.usesI2c)
         m.set('CONFIG_I2C', 'y');
+    if (usage.usesI2cTarget)
+        m.set('CONFIG_I2C_TARGET', 'y');
     if (usage.usesSpi)
         m.set('CONFIG_SPI', 'y');
     // USB CDC-ACM serial: the "next" USB device stack + the CDC-ACM class.
@@ -93,38 +136,92 @@ export function resolveKconfigFragments(usage, debug) {
         m.set('CONFIG_COUNTER', 'y');
     if (usage.usesDisplay) {
         m.set('CONFIG_DISPLAY', 'y');
-        m.set('CONFIG_SPI', 'y');
-        m.set('CONFIG_MIPI_DBI', 'y');
-        // Enable GDMA so the ESP32 SPI driver uses DMA for panel transfers instead
-        // of PIO through the 64-byte hardware FIFO. Without DMA a full 480x320 fill
-        // takes ~110ms (effectively ~4MHz); with DMA the same transfer runs at the
-        // 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 + 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.displayBus === 'i2c' || usage.displayKconfigExtra) {
+            // Self-describing panels — no SPI bridge, no DMA:
+            //  - i2c-family (mono OLEDs, ssd1306-class): an I2C child node; the
+            //    panel driver self-builds from it.
+            //  - board-provided panels (native_sim's sdl_dc): the board's own DTS
+            //    wires the display; the profile's extra fragments (e.g. the SDL
+            //    panel's mono pixel-format choice) land here verbatim.
+            if (usage.displayBus === 'i2c')
+                m.set('CONFIG_I2C', 'y');
+            for (const frag of usage.displayKconfigExtra ?? []) {
+                const eq = frag.indexOf('=');
+                if (eq > 0)
+                    m.set(frag.slice(0, eq).trim(), frag.slice(eq + 1).trim());
+            }
+        }
+        else {
+            m.set('CONFIG_SPI', 'y');
+            m.set('CONFIG_MIPI_DBI', 'y');
+            // Enable GDMA so the ESP32 SPI driver uses DMA for panel transfers instead
+            // of PIO through the 64-byte hardware FIFO. Without DMA a full 480x320 fill
+            // takes ~110ms (effectively ~4MHz); with DMA the same transfer runs at the
+            // 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');
+            if (usage.displayTransport === 'zephyr-display') {
+                // Native display-API transport: the mipi-dbi SPI bridge hosts the
+                // panel driver, which owns init/rotation/wire format. Controller-
+                // specific exceptions and the drop-in (compatible-driven) path:
+                //  - st7796s (registry profile): the stock bridge deasserts CS
+                //    between command and parameters (scrambles clone panels), so it
+                //    stays OFF — the adapter emits an app-local CS-holding host.
+                //  - ili9341 (registry profile): assign the prompted symbol explicitly
+                //    (survives DT-only probes; not the hidden ILI9XXX).
+                //  - synthesized profiles (no controller): assign NOTHING — panel
+                //    drivers are `default y depends on DT_HAS_<COMPATIBLE>_ENABLED`,
+                //    so the overlay's enabled node builds its own driver.
+                if (usage.displayController === 'st7796s') {
+                    m.set('CONFIG_MIPI_DBI_SPI', 'n');
+                    m.set('CONFIG_ST7796S', 'y');
+                }
+                else if (usage.displayController === 'ili9341') {
+                    m.set('CONFIG_MIPI_DBI_SPI', 'y');
+                    m.set('CONFIG_ILI9341', 'y');
+                }
+                else {
+                    m.set('CONFIG_MIPI_DBI_SPI', 'y');
+                }
+                // E-ink families (Stage 4): the panel driver under the mipi-dbi SPI
+                // bridge — ssd16xx/uc81xx own the flash-cycle refresh + BUSY wait.
+                if (usage.displayController === 'ssd16xx') {
+                    m.set('CONFIG_SSD16XX', 'y');
+                }
+                else if (usage.displayController === 'uc81xx') {
+                    m.set('CONFIG_UC81XX', 'y');
+                }
+            }
+            else {
+                // Direct-spi transport (default): the display adapter drives the panel
+                // directly via spi_write. Disable the MIPI DBI SPI bridge + in-tree panel
+                // drivers (ILI9341, ST7796S) — binding them 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".
+                m.set('CONFIG_MIPI_DBI_SPI', 'n');
+                m.set('CONFIG_ILI9341', 'n');
+                m.set('CONFIG_ST7796S', 'n');
+            }
+        }
     }
     if (usage.usesTouch) {
-        // 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') {
+            // XPT2046 rides the display's SPI bus — the raw adapter owns the chip
+            // (CONFIG_INPUT stays off: the in-tree driver's DT min/max scaling
+            // would double-apply the runtime calibration — see touch-adapter.ts).
             m.set('CONFIG_SPI', 'y');
         }
         else {
+            // FT6336U through the input subsystem: the in-tree focaltech driver
+            // owns the controller in polling mode (no int-gpios on the node — no
+            // GPIO IRQ is registered, sidestepping the ESP32 VECDESC_FL_SHARED
+            // crash the interrupt path hit). The adapter listens for its events.
+            m.set('CONFIG_INPUT', 'y');
+            m.set('CONFIG_INPUT_FT5336', 'y');
             m.set('CONFIG_I2C', 'y');
         }
     }
@@ -246,12 +343,16 @@ export function resolveKconfigFragments(usage, debug) {
         // pinned-CA handshake fails with EPERM at connect (the insecure path
         // skips verification, so it works either way).
         m.set('CONFIG_MBEDTLS_X509_CRT_PARSE_C', 'y');
-        // KNOWN LIMITATION on this Zephyr tree: pinned-CA (verified TLS) fails at
-        // connect — the tf-psa-crypto mbedTLS needs a wider symbol matrix
-        // (RSA public-key parse + PEM/DER glue) than the single-ciphersuite
-        // select pulls in, and forcing the extra symbols regresses the insecure
-        // path. insecure() HTTPS is fully verified; caCert() chain verification
-        // stays open until the upstream matrix is mapped.
+        // KNOWN LIMITATION on this Zephyr tree: pinned-CA (verified TLS) was
+        // observed failing at connect with EPERM — the tf-psa-crypto mbedTLS
+        // needs a wider symbol matrix (RSA public-key parse + PEM/DER glue)
+        // than the single-ciphersuite select pulls in, and forcing the extra
+        // symbols regressed the insecure path (two hardware cycles proved it
+        // upstream). CAVEAT: that diagnosis predates the 2026-09 fix of the
+        // request-fact reset ordering (every option — including caCert — was
+        // being wiped before each send, which alone reproduces connect
+        // failures); the matrix limitation needs a hardware re-run to confirm
+        // it still applies. insecure() HTTPS and no-CA https are unaffected.
         // Handshake/protocol buffers allocate from the mbedTLS heap; MBEDTLS_HEAP_SIZE
         // must hold ~2x MBEDTLS_SSL_MAX_CONTENT_LEN plus working state. 65000 fits on
         // the ESP32; mbedTLS requires the full libc and PEM (not DER) cert format.
@@ -306,12 +407,14 @@ export function resolveKconfigFragments(usage, debug) {
         // pinned-CA handshake fails with EPERM at connect (the insecure path
         // skips verification, so it works either way).
         m.set('CONFIG_MBEDTLS_X509_CRT_PARSE_C', 'y');
-        // KNOWN LIMITATION on this Zephyr tree: pinned-CA (verified TLS) fails at
-        // connect — the tf-psa-crypto mbedTLS needs a wider symbol matrix
-        // (RSA public-key parse + PEM/DER glue) than the single-ciphersuite
-        // select pulls in, and forcing the extra symbols regresses the insecure
-        // path. insecure() HTTPS is fully verified; caCert() chain verification
-        // stays open until the upstream matrix is mapped.
+        // KNOWN LIMITATION on this Zephyr tree: pinned-CA (verified TLS) was
+        // observed failing at connect with EPERM — the tf-psa-crypto mbedTLS
+        // needs a wider symbol matrix (RSA public-key parse + PEM/DER glue)
+        // than the single-ciphersuite select pulls in. CAVEAT: that diagnosis
+        // was made on the HTTPS path and predates the 2026-09 request-fact
+        // reset-ordering fix (options were wiped before every send, which
+        // alone reproduces connect failures); it is shared here because mqtts
+        // pins its CA through the same matrix — re-verify on hardware.
         m.set('CONFIG_MBEDTLS_ENABLE_HEAP', 'y');
         // 2x SSL_MAX_CONTENT_LEN record buffers + CA-chain parse state +
         // handshake working memory. 65000 fit insecure-mode handshakes but the

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

@@ -5,7 +5,7 @@ import type { KconfigUsage } from './kconfig.js';
  * Generate the overlay source for a board + usage. Returns the overlay text
  * (caller writes it to app/boards/<board>.overlay via writeIfChanged).
  */
-/** Display wiring from cuttlefish.config.ts (cs/dc/rst/spiFrequency/spiPins). */
+/** Display wiring from typecad-hal.config.ts (cs/dc/rst/spiFrequency/spiPins). */
 export interface DisplayWiring {
     cs?: number;
     dc?: number;
@@ -13,7 +13,20 @@ export interface DisplayWiring {
     /** 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;
+    /** E-ink BUSY GPIO from display.busyPin — emitted as busy-gpios on the
+     *  panel child (required by the ssd16xx/uc81xx bindings, active-high). */
+    busyPin?: number;
     spiFrequency?: number;
+    /** I2C address for i2c-family panels (mono OLEDs, ssd1306-class). */
+    address?: number;
+    /** I2C bus pins for i2c-family panels. When present, the overlay remuxes
+     *  the I2C controller's pinctrl to these pins — the board's default I2C
+     *  pins rarely match a breakout's wiring (same rationale as the SPI pins
+     *  below; the ESP32 pinctrl headers carry the named I2C0_*_GPIOn macros).
+     *  Shared bus: when touch wiring also remuxes, the last assignment wins —
+     *  wire both to the same pins. */
+    sda?: number;
+    scl?: 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
      *  wiring — e.g. demo-st's panel is on SCK=18/MOSI=23, not the devkitc
@@ -28,7 +41,7 @@ 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; cs for SPI
+/** Touch wiring from typecad-hal.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