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

package/dist/chips/types.d.ts

@@ -43,18 +43,122 @@ export interface ZephyrGpioController {
 export interface ZephyrBusController {
     /** Devicetree nodelabel, e.g. 'i2c1', 'spi2', 'uart0'. */
     readonly nodeLabel: string;
+    /**
+     * Counter child form only: the labeled TIMER PARENT's nodelabel (ESP32
+     * timer0-3). The counter device is an unlabeled `counter {}` child; the
+     * nodeLabel above is a label the generated overlay defines on that child,
+     * and this field tells the overlay which parent to attach it to.
+     */
+    readonly counterParent?: string;
+    /**
+     * Synthesized pinctrl group, for controllers whose board DT ships no
+     * default group (e.g. uart1 on rpi_pico/rpi_pico2 — the mainline board DT
+     * only pins uart0). When present, the overlay generator emits the group
+     * under `&pinctrl` and wires `pinctrl-0`/`pinctrl-names` onto the
+     * controller when enabling it. RP2xxx pinmux is fully muxable per pad, so
+     * the group is pure data: which pads carry the signals.
+     */
+    readonly pinctrl?: {
+        /** Pinmux header to #include (token definitions). */
+        readonly include: string;
+        /** Output-signal pinmux tokens (emitted as group1). */
+        readonly pinmux: readonly string[];
+        /** Input-signal pinmux tokens (emitted as group2 with input-enable). */
+        readonly inputPinmux?: readonly string[];
+        /**
+         * `#define` lines emitted (ifndef-guarded) BEFORE the include — for
+         * upstream header bugs where a token's macro body references an
+         * undefined helper (e.g. RP2_PINCTRL_GPIO_FUNC_UART_ALT in Zephyr's
+         * rp2350 pinctrl headers, unreferenced by mainline so never noticed).
+         */
+        readonly defines?: readonly string[];
+    };
+    /**
+     * Reference an EXISTING pinctrl group (defined in the board's pinctrl
+     * dtsi but not attached to the node) instead of synthesizing one — e.g.
+     * uart1_default on esp32s3_devkitc. The overlay wires
+     * `pinctrl-0 = <&<group>>` when enabling the controller.
+     */
+    readonly pinctrlRef?: string;
+    /**
+     * Raw devicetree property lines emitted inside the enable block — for
+     * bindings with required properties the board DTS only sets on its own
+     * wired-up nodes (e.g. `current-speed` on the Picos' PL011 UARTs).
+     */
+    readonly props?: readonly string[];
 }
 /**
  * A PWM channel described as a devicetree spec.
  *
- * Emitted as `struct pwm_dt_spec __tc_pwm<N> = PWM_DT_SPEC_GET(DT_ALIAS(<dtSpec>))`.
- * `pwm_set_pulse_dt(&__tc_pwm<N>, pulse_ns)` honors the spec's period/polarity.
+ * Two forms, mutually exclusive:
+ * - **Board-shipped alias:** `dtSpec` names a DT alias the board's own DTS
+ *   already defines (e.g. the XIAO's `pwm-led0`). Emitted as
+ *   `PWM_DT_SPEC_GET(DT_ALIAS(<dtSpec>))`.
+ * - **Synthesized** (controller + channel): the board DTS enables a PWM
+ *   controller node (e.g. `pwm4`) but defines no alias for it. The overlay
+ *   generator synthesizes a `pwm-leds` consumer node + a `tc-pwm<pin>` alias
+ *   in `<board>.overlay`; the lowering emits
+ *   `PWM_DT_SPEC_GET(DT_ALIAS(tc-pwm<pin>))`. Both sides derive the alias
+ *   name from the pin, so they always agree.
+ *
+ * `pwm_set_pulse_dt(&spec, pulse_ns)` honors the spec's period/polarity.
  */
 export interface ZephyrPwmSpec {
     /** GPIO number (matches the HAL op `pin` field). */
     readonly pin: number;
-    /** Devicetree alias, e.g. 'pwm-led0'. */
-    readonly dtSpec: string;
+    /** Board-shipped DT alias, e.g. 'pwm-led0'. Omit when using the
+     *  synthesized form (controller + channel). */
+    readonly dtSpec?: string;
+    /** Synthesized form: PWM controller DT nodelabel, e.g. 'pwm4' (the STM32
+     *  timer's pwm child node). The overlay's pwm-leds node consumes it. */
+    readonly controller?: string;
+    /** Synthesized form: channel index within the controller (1-based timer
+     *  channel, matching the `pwms` binding's channel cell). */
+    readonly channel?: number;
+    /** Synthesized form: period in nanoseconds, baked into the DT spec. The
+     *  lowering scales duty against `spec.period`. Default 20 000 000 (20 ms /
+     *  50 Hz — the servo convention; harmless for LED dimming). */
+    readonly periodNs?: number;
+    /** Synthesized form: PWM polarity flag. Default PWM_POLARITY_NORMAL. */
+    readonly polarity?: string;
+    /**
+     * SoC pinctrl dtsi token muxing this channel's pin to the timer (e.g.
+     * 'tim4_ch1_pb6' on STM32). Required on custom boards — the st,stm32-pwm
+     * binding demands pinctrl-0 on an enabled node and only a board DTS (or
+     * the custom-board generator, fed by this token) can provide it. Also
+     * gates the generated board's `pwmN: pwm { }` label declaration: the
+     * overlay references `&<controller>`, a label that otherwise exists only
+     * when a board DTS defines it.
+     */
+    readonly pinctrl?: string;
+}
+/**
+ * A "PWM matrix" controller: any listed pin can carry any channel, routed by
+ * the SoC's GPIO matrix rather than a fixed timer-channel↔pad map.
+ *
+ * ESP32 LEDC is the shape (espressif,esp32-ledc): 8 channels, each routable
+ * to (almost) any pad via a pinctrl pinmux token (`LEDC_CH<ch>_GPIO<pin>`).
+ * A static `specs` list cannot express this — two arbitrary pins would
+ * collide on a statically assigned channel — so the channel assignment is
+ * made at build time: the pins the program actually drives are assigned
+ * channels 0..N-1 (ascending pin order, capped at `channelCount`), and the
+ * overlay generator emits the pinctrl group + per-channel child nodes the
+ * espressif,esp32-ledc binding requires. The emitted C++ is channel-blind:
+ * it addresses each pin via the same `DT_ALIAS(tc-pwm<pin>)` the synthesized
+ * static form uses, so the two paths share the lowering.
+ */
+export interface ZephyrPwmMatrix {
+    /** PWM controller DT nodelabel, e.g. 'ledc0'. */
+    readonly controller: string;
+    /** Channels the controller exposes (ESP32-S3 LEDC: 8). */
+    readonly channelCount: number;
+    /**
+     * HAL pins usable as PWM outputs. This is the safety filter as much as the
+     * capability list — on the ESP32-S3 it excludes the boot-strap pin, the
+     * USB D+/D− pads, the flash/PSRAM pins (GPIO 26–32), the octal-PSRAM pins
+     * (GPIO 33–37), and the console UART pads (GPIO 43/44).
+     */
+    readonly pins: readonly number[];
 }
 /**
  * A GPIO pin usable as an interrupt source.
@@ -69,7 +173,7 @@ export interface ZephyrInterruptPin {
     readonly dtSpec: string;
 }
 /**
- * An ADC channel: which SAADC input a given HAL pin maps to.
+ * An ADC channel: which ADC input a given HAL pin maps to.
  *
  * The XIAO nRF52840 has no pre-declared ADC channel nodes in devicetree, so the
  * lowering emits `adc_channel_setup` against `DEVICE_DT_GET(DT_NODELABEL(adc))`
@@ -78,8 +182,24 @@ export interface ZephyrInterruptPin {
 export interface ZephyrAdcChannel {
     /** GPIO number (matches the HAL op `pin` field). */
     readonly pin: number;
-    /** SAADC channel index (AIN0–AIN7). */
+    /** ADC channel index (nRF SAADC AIN0–AIN7; STM32 ADC1_IN0–IN9). */
     readonly channel: number;
+    /**
+     * ADC device node label that OWNS this channel when the SoC has more than
+     * one ADC controller (STM32 adc1/adc2, ESP32 units), e.g. 'adc2'. Omitted
+     * for channels on the descriptor's primary controller (`adc.nodeLabel`) —
+     * a single-controller manifest is unchanged. Channel indices are unique
+     * only WITHIN a controller; the pair (controller, channel) is the key.
+     */
+    readonly controller?: string;
+    /**
+     * Pinctrl node label that muxes this pin to analog mode, e.g.
+     * 'adc1_in0_pa0' (STM32). When present, the overlay generator rewrites the
+     * ADC node's pinctrl-0 to the channels the program actually reads — SoCs
+     * like STM32 leave the pad in GPIO mode otherwise and reads float.
+     * Omit on SoCs whose ADC needs no pad muxing (nRF SAADC, RP2040).
+     */
+    readonly pinctrl?: string;
 }
 /**
  * A DAC channel: which DAC output a given HAL pin maps to. The lowering emits
@@ -92,6 +212,8 @@ export interface ZephyrDacChannel {
     readonly channel: number;
     /** DAC resolution in bits (ESP32 DAC is 8-bit). */
     readonly resolution: number;
+    /** Pinctrl node name routing the channel to its pad (STM32 harvest). */
+    readonly pinctrl?: string;
 }
 /**
  * Pure-data descriptor for a Zephyr board + its SoC's peripheral layout.
@@ -101,6 +223,33 @@ export interface ZephyrChipDescriptor {
     readonly id: string;
     /** SoC family, e.g. 'nrf52840'. */
     readonly soc: string;
+    /**
+     * How confident the framework is in this descriptor's facts.
+     * - 'validated' — the soc is part of the hardware-tested set; every field
+     *   was verified against the pinned Zephyr tree and real hardware.
+     * - 'derived' — reconstructed from data (board/MCU packages, DTS reading)
+     *   but never hardware-verified; capability errors may be less precise.
+     */
+    readonly tier?: 'validated' | 'derived';
+    /**
+     * Datasheet pin-naming convention — how a controller/pin pair becomes the
+     * schematic-facing name the generated board module exports (the
+     * `Pin.fromPort()` identity). One of:
+     * - 'esp32-gpio'   — flat numbering, `GPION` (esp32, esp32s3, esp32c*)
+     * - 'stm32-port'   — one controller per port, `P<port><bit>` (PA5, PB12)
+     * - 'nrf-port'     — P0.28 / P1.11 style (`P<port>.<bit>`)
+     * - 'rp-gpio'      — `GP<n>` flat numbering
+     * - 'samd-port'    — PA/PB ports like stm32-port
+     * Absent on tier-3 socs with no known convention (the generated board
+     * exposes only connector/alias pins + LED/BUTTON).
+     */
+    readonly pinNaming?: 'esp32-gpio' | 'stm32-port' | 'nrf-port' | 'rp-gpio' | 'samd-port';
+    /**
+     * Pins that exist in the controller ranges but must NOT be exported as
+     * usable GPIOs — strapping pads, flash/PSRAM, USB D+/-. The generated
+     * board module's pin list subtracts these.
+     */
+    readonly excludedPins?: readonly number[];
     /**
      * Default GPIO controller nodelabel for the raw-pin fallback. Pins not in
      * `gpio.dtSpecs` are addressed via
@@ -113,11 +262,18 @@ export interface ZephyrChipDescriptor {
     readonly gpioController: string;
     /**
      * Per-range GPIO controllers for SoCs that split GPIO across multiple
-     * devicetree nodes (ESP32-S3: `gpio0` 0–31, `gpio1` 32–48). When present, the
-     * lowering routes a HAL pin to its owning controller at runtime via the
-     * emitted `__tc_gpio_dev(pin)` dispatcher; `gpioController` is the fallback.
-     * Omit on single-controller SoCs (nRF52840, RP2040, …) — every pin is on the
-     * one controller described by `gpioController`.
+     * devicetree nodes (ESP32-S3: `gpio0` 0–31, `gpio1` 32–48; STM32: one
+     * controller per port — `gpioa` 0–15, `gpiob` 16–31, `gpioc` 32–47).
+     * When present, the lowering routes a HAL pin to its owning controller at
+     * runtime via the emitted `__tc_gpio_dev(pin)` dispatcher; `gpioController`
+     * is the fallback. Omit on single-controller SoCs (RP2040, …) — every pin
+     * is on the one controller described by `gpioController`.
+     *
+     * NUMBERING RULE (load-bearing): `minPin` must equal the controller's port
+     * base so the port-relative raw index is `pin - minPin` (STM32 PB12 = pin
+     * 28 → raw 12 — the Zephyr raw API addresses the index WITHIN the
+     * controller). Number pins by port blocks and never contiguously across
+     * unbonded pins.
      */
     readonly gpioControllers?: readonly ZephyrGpioController[];
     /** GPIO pins with devicetree specs (LEDs, buttons, board-defined pins). */
@@ -138,11 +294,70 @@ export interface ZephyrChipDescriptor {
     readonly uart?: {
         readonly controllers: readonly ZephyrBusController[];
     };
+    /**
+     * USB device (CDC-ACM serial) capability. Zephyr "next" USB device stack:
+     * the UDC controller node (uniformly `zephyr_udc0` on every USB-capable
+     * board) plus `cdcInstances` CDC-ACM class child nodes, both composed in
+     * the generated overlay. The lowering addresses instance N as
+     * DT_NODELABEL(cdc_acm_uart<N>) — a UART-class device driven with the
+     * plain uart_* API. Boards without USB device support omit this field;
+     * usb.* HAL ops then fail with a clear "board does not expose USB" error.
+     */
+    readonly usb?: {
+        /** UDC controller nodelabel (convention: 'zephyr_udc0'). */
+        readonly controller: string;
+        /** How many CDC-ACM serial instances to compose (≥1). */
+        readonly cdcInstances: number;
+        /** USB vendor ID for the device descriptor ('0x2fe3' Zephyr-test default). */
+        readonly vid?: string;
+        /** USB product ID for the device descriptor ('0x0001' default). */
+        readonly pid?: string;
+        /**
+         * 1200-baud touch-to-reset (BOSSA-bootloader boards, e.g. SAM D21).
+         *
+         * Present = two things happen automatically:
+         * - Device side: the emitted USB shim registers a usbd message callback;
+         *   when the host sets the CDC baud rate to 1200, the shim writes the
+         *   bootloader's "stay resident" magic to the flag address and reboots —
+         *   the board lands in the bootloader with no button press.
+         * - Host side: the bossac upload path opens the app's console port at
+         *   1200 baud to trigger the above, waits for the bootloader's USB
+         *   identity, and points bossac at that port.
+         * Omit on boards without a cooperative bootloader (probe- or
+         * UF2-flashed boards don't need it).
+         */
+        readonly touchReset?: {
+            /** RAM address of the bootloader's stay-resident flag word
+             * (SAMD21G18A: 0x20007FFC — the last word of the 32 KB SRAM). */
+            readonly flagAddress: number;
+            /** Magic word the bootloader checks there (Arduino SAMD: 0x07738135). */
+            readonly magic: number;
+            /** Bootloader USB vendor id, hex string ('0x2341') — host-side watch. */
+            readonly bootloaderVid?: string;
+            /** Bootloader USB product id, hex string ('0x0057') — host-side watch. */
+            readonly bootloaderPid?: string;
+        };
+    };
     /** PWM channels with DT specs. */
     readonly pwm?: {
         readonly specs: readonly ZephyrPwmSpec[];
+        /**
+         * Matrix PWM capability (ESP32 LEDC) — channels assigned to the driven
+         * pins at build time instead of enumerated statically. `specs` may be
+         * empty when only the matrix is declared.
+         */
+        readonly matrix?: ZephyrPwmMatrix;
+        /**
+         * Timer input clock (Hz) for the synthesized specs' controllers — the
+         * number the 16-bit overflow check divides by (STM32: APB clock × the
+         * timer multiplier; blackpill TIM4 = 96 MHz). When set, the overlay
+         * generator derives an `st,prescaler` for the timers node so slow
+         * periods (servo 20 ms) fit the 16-bit ARR — without it pwm_stm32
+         * rejects the channel ("period cycles exceeds 16-bit timer limit").
+         */
+        readonly clockHz?: number;
     };
-    /** ADC: the SAADC node label + the pin→channel map. */
+    /** ADC: the ADC device node label + the pin→channel map. */
     readonly adc?: {
         readonly nodeLabel: string;
         readonly channels: readonly ZephyrAdcChannel[];
@@ -150,6 +365,19 @@ export interface ZephyrChipDescriptor {
         readonly vrefMv: number;
         /** ADC resolution in bits. */
         readonly resolution: number;
+        /**
+         * Zephyr `enum adc_gain` macro for the channel setup, e.g.
+         * 'ADC_GAIN_1_4' (nRF SAADC default) or 'ADC_GAIN_1' (STM32 driver
+         * requires exactly this). Defaults to 'ADC_GAIN_1_4'.
+         */
+        readonly gain?: string;
+        /**
+         * Zephyr `enum adc_reference` macro, e.g. 'ADC_REF_INTERNAL'. Defaults to
+         * 'ADC_REF_INTERNAL' — on nRF that is the 0.6 V internal ref measured
+         * through the gain divider; the STM32 driver ALSO requires
+         * ADC_REF_INTERNAL (Zephyr maps it to the VREF+ pad) with vrefMv = VDDA.
+         */
+        readonly reference?: string;
     };
     /**
      * DAC: the DAC device node label + the pin→channel map. Present only on chips
@@ -164,6 +392,25 @@ export interface ZephyrChipDescriptor {
     readonly wdt?: {
         readonly nodeLabel: string;
     };
+    /**
+     * Storage partition to synthesize when the board DTS ships none. Boards
+     * with an MCUboot-style partition map (most STM32s) define boot/slot
+     * partitions but no `storage_partition`, which the Preferences/FS backends
+     * (ZMS/littlefs) require. Present = "the overlay generator must declare
+     * this partition under &flash0"; boards whose DTS already carries one
+     * (ESP32 devkits) omit it — the overlay only adds the /chosen pointer.
+     * The region must cover ≥2 flash pages (ZMS minimum) and stay clear of
+     * the linked application image.
+     */
+    readonly storage?: {
+        /** Partition start offset in flash, page-aligned. */
+        readonly offset: number;
+        /** Partition size in bytes, a multiple of the flash page size. */
+        readonly size: number;
+        /** True when the board's own DTS already declares this partition — the
+         *  overlay must only point /chosen at it, never redeclare the node. */
+        readonly preexisting?: boolean;
+    };
     /**
      * Hardware timers exposed as Zephyr counter devices. `instance` (the HAL
      * hwtimer.* op's instance index) maps to `controllers[instance].nodeLabel`.
@@ -181,4 +428,127 @@ export interface ZephyrChipDescriptor {
     readonly wifi?: {
         readonly supported: true;
     };
+    /**
+     * Probe methods the board supports, in user-facing terms. Each entry maps a
+     * friendly id (`stlink`, `dfu`, `jlink`, …) to the west runner it drives
+     * plus any args the method always needs — the hardware quirks (e.g. openocd
+     * needing `reset_config none` when the SRST line is unwired) live here,
+     * verified with the board, instead of in user configs. One probe method
+     * serves BOTH flashing and debugging (the same attach session); entries
+     * that cannot debug (bootloaders) set `debug: false`. Users select one via
+     * `zephyr.probe` in cuttlefish.config.ts or `--probe` on the CLI;
+     * `zephyr.runner`/`runnerArgs` remain the raw escape hatch underneath.
+     */
+    readonly probeMethods?: readonly ZephyrProbeMethod[];
+    /**
+     * Silicon-level inputs for the custom-board generator — present when the
+     * chip was resolved from an MCU package's `zephyr` block (an MCU-only
+     * config with no board package). The generator emits an out-of-tree Zephyr
+     * board (`boards/typecad/<name>/` in the project) from exactly this data:
+     * SoC name, devicetree includes, the default console mux, and the default
+     * clock plan. Absent on board-resolved chips (their board already exists).
+     */
+    readonly customBoard?: ZephyrCustomBoardData;
+}
+/**
+ * Everything the custom-board generator needs from the silicon to emit a
+ * minimal, buildable out-of-tree board for a chip with no board package.
+ */
+export interface ZephyrCustomBoardData {
+    /** Zephyr SoC name(s) for board.yml + the Kconfig SOC_* selection. */
+    readonly socs: readonly string[];
+    /** Devicetree includes for the generated board DTS root (SoC + pinctrl). */
+    readonly dtsIncludes: readonly string[];
+    /** The default console the generated board enables. */
+    readonly console: {
+        /** Controller nodelabel, e.g. 'usart1'. */
+        readonly nodeLabel: string;
+        /** TX pinctrl token from the SoC's pinctrl dtsi, e.g. 'usart1_tx_pa9'. */
+        readonly tx: string;
+        /** RX pinctrl token, e.g. 'usart1_rx_pa10'. */
+        readonly rx: string;
+        /** Baud rate (the DT `current-speed`). */
+        readonly speed: number;
+    };
+    /**
+     * Default clock plan — the numbers the generated DTS writes into the SoC's
+     * clock nodes (HSE crystal frequency, PLL dividers, bus prescalers). A
+     * board package overrides with its own crystal/plan; a custom board uses
+     * this silicon default.
+     */
+    readonly clocks: {
+        /** HSE crystal frequency in MHz. */
+        readonly hseMHz: number;
+        /** PLL divider/multiplier plan. */
+        readonly pll: {
+            readonly divM: number;
+            readonly mulN: number;
+            readonly divP: number;
+            readonly divQ: number;
+        };
+        /** System clock frequency in MHz (the &rcc clock-frequency). */
+        readonly sysMHz: number;
+        readonly ahbPrescaler: number;
+        readonly apb1Prescaler: number;
+        readonly apb2Prescaler: number;
+    };
+    /**
+     * Silicon USB node to alias as `usb.controller` in the generated DTS
+     * (e.g. 'usbotg_fs' aliased as 'zephyr_udc0'). Omit when usb is absent.
+     */
+    readonly usbNode?: string;
+    /**
+     * Pinctrl tokens muxing the USB node's pins (e.g.
+     * 'usb_otg_fs_dm_pa11'/'usb_otg_fs_dp_pa12'). The st,stm32-otgfs binding
+     * requires pinctrl-0 on an enabled node, so the generated board pre-enables
+     * the USB node with exactly these (the blackpill shape). Omit when the
+     * SoC's USB needs no board-side muxing.
+     */
+    readonly usbPinctrl?: readonly string[];
+    /**
+     * ADC node the generated board must pre-enable with the SoC driver's
+     * required properties — e.g. the STM32 F4 binding rejects an enabled adc
+     * node without `st,adc-clock-source`/`st,adc-prescaler` (upstream boards
+     * set them in their DTS; a custom board has none, so the generator emits
+     * them from this data). The baseline pinctrl satisfies the binding's
+     * pinctrl-0 requirement; the usage-driven overlay rewrites it to the
+     * channels the program actually reads. Omit on SoCs whose ADC needs no
+     * board-side enabling.
+     */
+    readonly adcNode?: {
+        readonly nodeLabel: string;
+        /** The binding's clock-source property value (e.g. 'SYNC'). */
+        readonly clockSource: string;
+        /** The binding's prescaler property value (e.g. 2). */
+        readonly prescaler: number;
+        /** Baseline pinctrl token (e.g. 'adc1_in1_pa1'). */
+        readonly pinctrl: string;
+    };
+}
+/**
+ * A named way to attach a probe to a board — what the user picks, and what
+ * flashing/debugging lower to.
+ */
+export interface ZephyrProbeMethod {
+    /** User-facing id, stable per board (`stlink`, `dfu`, `jlink`, `uf2`, …). */
+    readonly id: string;
+    /** The west runner this method drives (flash and debug). */
+    readonly runner: string;
+    /** Args always passed with this method (before any user runnerArgs). */
+    readonly args?: readonly string[];
+    /** One-line human description for the wizard, doctor, and error messages. */
+    readonly description?: string;
+    /** Whether this method can debug (default true — SWD/JTAG probes can,
+     *  bootloaders cannot and set this false explicitly). */
+    readonly debug?: boolean;
+    /** cortex-debug: the wire protocol (default 'swd'; esp_usb_jtag is 'jtag'). */
+    readonly debugInterface?: 'swd' | 'jtag';
+    /** cortex-debug servertype=jlink: the J-Link device name (e.g. 'STM32F411CE'). */
+    readonly debugDevice?: string;
+    /** Raw OpenOCD cfg lines for the debug server config (e.g. 'reset_config
+     *  none') — the cfg-file form of the quirks `args` carry for west. */
+    readonly debugCfg?: readonly string[];
+    /** OpenOCD cfg `source [find …]` lines for the debug server (interface +
+     *  target configs). Omitted entries fall back to the framework default. */
+    readonly debugCfgSource?: readonly string[];
 }

package/dist/chips/xiao-ble.js

@@ -8,6 +8,18 @@ export const XIAO_BLE = {
     id: 'xiao_ble',
     soc: 'nrf52840',
     gpioController: 'gpio0',
+    // GPIO is split across two devicetree controllers: gpio0 (P0.00–P0.31)
+    // and gpio1 (P1.00–P1.15, HAL pins 32–47). Declaring the split makes the
+    // raw path emit the port-relative index against gpio1 (P1.11 = raw 11),
+    // which NRF_GPIO_PIN_MAP(1, 11) resolves to absolute pin 43 — the same
+    // physical pin the old single-controller form reached only by accident:
+    // gpio0 + global 43 also maps to 43 (MAP(0, 43) = 43), but that form
+    // trips the generic layer's port_pin_mask __ASSERT ("Unsupported pin",
+    // gpio0's mask covers 0–31) on any assert-enabled build.
+    gpioControllers: [
+        { nodelabel: 'gpio0', minPin: 0, maxPin: 31 },
+        { nodelabel: 'gpio1', minPin: 32, maxPin: 47 },
+    ],
     gpio: {
         dtSpecs: [
             // Onboard RGB LEDs — active-low (GPIO_ACTIVE_LOW in xiao_ble_common.dtsi).
@@ -40,6 +52,15 @@ export const XIAO_BLE = {
     uart: {
         controllers: [{ nodeLabel: 'uart0' }],
     },
+    // nRF52840 native USB device (USBD). The board DTS carries `zephyr_udc0`
+    // (the nRF USBD driver node); the overlay enables it + composes one CDC-ACM
+    // instance when a program uses USB0. (The console on this board is already
+    // USB-CDC via the board's own chosen cdc_acm_uart0 — this field exposes the
+    // same peripheral to usb.* HAL ops.)
+    usb: {
+        controller: 'zephyr_udc0',
+        cdcInstances: 1,
+    },
     pwm: {
         // pwm-led0 drives the board PWM LED (PWM_OUT0 on P0.17, inverted).
         specs: [{ pin: 17, dtSpec: 'pwm-led0' }],
@@ -64,4 +85,16 @@ export const XIAO_BLE = {
     // Verified against the nRF52840 SoC dtsi (rtc0/rtc1 nodes). The kernel uses
     // RTC0 for the system tick; RTC1 is available for application use.
     hwtimer: { controllers: [{ nodeLabel: 'rtc1' }] },
+    // Mirror of board-xiao-nrf52840's probeMethods (registry fallback parity —
+    // the board package's zephyr field wins when board constants are present).
+    probeMethods: [
+        { id: 'jlink', runner: 'jlink', description: 'J-Link probe (SWD)',
+            debug: true, debugInterface: 'swd', debugDevice: 'nRF52840_xxAA' },
+        { id: 'openocd', runner: 'openocd',
+            description: 'Any SWD probe openocd supports (CMSIS-DAP, cheap clones)',
+            debug: true, debugInterface: 'swd',
+            debugCfgSource: ['interface/stlink.cfg', 'target/nrf52.cfg'] },
+        { id: 'uf2', runner: 'uf2', description: 'Bootloader UF2 drag-and-drop: double-tap reset',
+            debug: false },
+    ],
 };

package/dist/display/profiles.js

@@ -40,7 +40,7 @@ export const ZEPHYR_DISPLAY_PROFILES = {
         // 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
+        // enables it via status="okay". Effective dims match the display
         // st7796-spi profile (480x320 landscape, rotation 1).
         driver: 'st7796-zephyr',
         dtLabel: 'display0',

package/dist/doctor.js

@@ -4,13 +4,17 @@
 // `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
+// if the environment is OK, non-zero otherwise. Follows the same contract
 // 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 { 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 { 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';
 /**
  * Verify west is installed + responsive, the Zephyr RTOS is inside the supported
  * range, and the configured board target exists in the checkout. Sets
@@ -23,7 +27,7 @@ export function runDoctor() {
     const buildTarget = config?.buildTarget;
     const result = checkZephyrEnv(buildTarget);
     const c = result.check;
-    // west (the Zephyr build tool) — the analog of arduino-cli presence.
+    // west (the Zephyr build tool) presence.
     if (c.westFound) {
         const ver = c.westVersion ?? 'found';
         const src = c.westSource ? `  (${c.westSource})` : '';
@@ -35,6 +39,9 @@ export function runDoctor() {
     // 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(`Workspace pin ... ${PINNED_ZEPHYR_MANIFEST_REV} (SDK ${PINNED_ZEPHYR_SDK_VERSION})`);
+    const fp = c.zephyrBase ? sdkFingerprint(c.zephyrBase) : undefined;
+    ui.printInfo(`SDK fingerprint . ${fp ?? '(no tree — run ' + 'npx --package @typecad/framework-zephyr zephyr-installer)'}`);
     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}).`);
@@ -45,7 +52,7 @@ export function runDoctor() {
     else {
         ui.printInfo('Zephyr compat ... OK');
     }
-    // Board target — the analog of the Arduino core presence check.
+    // Board target availability.
     if (buildTarget) {
         const resolved = c.resolvedBoardTarget ?? buildTarget;
         const arrow = resolved === buildTarget ? '' : ` → ${resolved}`;
@@ -64,7 +71,34 @@ export function runDoctor() {
     else {
         ui.printInfo('(no buildTarget in cuttlefish.config.ts — skipping board check)');
     }
-    // Exit code — mirrors framework-arduino's doctor.
+    // Probe methods — from the board package's table, via the board constants
+    // the transpile persists (candidates cover the standard out-dir layouts).
+    // The debug line lists the debug-capable subset (bootloaders can't debug).
+    if (buildTarget) {
+        const bcPath = [
+            join(process.cwd(), 'out', 'src', 'board-constants.json'),
+            join(process.cwd(), 'out', 'board-constants.json'),
+            join(process.cwd(), 'src', 'out', 'src', 'board-constants.json'),
+            join(process.cwd(), 'src', 'out', 'board-constants.json'),
+        ].find((p) => existsSync(p));
+        if (bcPath) {
+            try {
+                const raw = JSON.parse(readFileSync(bcPath, 'utf8'));
+                const chip = resolveChipFromBoard(new Map(Object.entries(raw)));
+                const methods = chip?.probeMethods ?? [];
+                if (methods.length > 0) {
+                    ui.printInfo(`Probe methods .... ${methods.map((m) => m.id).join(', ')}  (zephyr.probe / --probe)`);
+                    const debuggable = methods.filter((m) => m.debug !== false).map((m) => m.id);
+                    ui.printInfo(`Debug methods .... ${debuggable.join(', ') || '(none — an external probe is required)'}`);
+                }
+            }
+            catch { /* best-effort listing */ }
+        }
+        else {
+            ui.printInfo('Probe methods .... (build once to list them)');
+        }
+    }
+    // Exit code — 0 ok, non-zero otherwise.
     if (result.ok) {
         ui.printSuccess('Environment OK');
         return; // exitCode stays unset => 0

package/dist/dt-config/custom-board.d.ts

@@ -0,0 +1,23 @@
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+/**
+ * Sanitize a raw name into a legal Zephyr board name: lowercase, `[a-z0-9_]`
+ * (dashes/dots/spaces collapse to underscores, leading/trailing underscores
+ * trimmed). Board names become C identifiers in Kconfig symbols, so anything
+ * stricter would break `config BOARD_<NAME>`.
+ */
+export declare function sanitizeBoardName(raw: string): string;
+/** Generated-board file set, all under `<projectRoot>/boards/typecad/<name>/`. */
+export interface GeneratedCustomBoard {
+    /** Absolute directory of the generated board. */
+    dir: string;
+    /** The sanitized board name (the `west build -b` argument). */
+    name: string;
+    /** Whether any file changed (idempotent regeneration signal). */
+    changed: boolean;
+}
+/**
+ * Emit the custom board for a chip whose descriptor carries `customBoard`
+ * silicon data. No-op (returns null) when the chip has no generator inputs —
+ * board-resolved chips don't need one.
+ */
+export declare function generateCustomBoard(projectRoot: string, chip: ZephyrChipDescriptor, rawName: string): GeneratedCustomBoard | null;