@typecad/framework-zephyr 1.0.0-alpha.8

package/src/chips/esp32.ts

@@ -0,0 +1,62 @@
+// ---------------------------------------------------------------------------
+// Espressif ESP32 (esp32_devkitc) — Zephyr board descriptor
+//
+// Board target: `esp32_devkitc` (mainline Zephyr,
+// boards/espressif/esp32_devkitc). Programmed over USB via the esptool runner
+// (see toolchain/index.ts), the same flash path as the ESP32-S3.
+//
+// GPIO is split across TWO devicetree controllers — `gpio0` (pins 0–31) and
+// `gpio1` (pins 32–39) — so this descriptor lists both in `gpioControllers`.
+// The lowering routes each HAL pin to its owning controller at runtime; see
+// chips/controllers.ts. (Same shape as the S3, but the ESP32's highest GPIO is
+// 39, not 48 — `gpio1` has ngpios=8, not 17.)
+//
+// Minimal-by-design: the only DT facts carried here are the ones a compile-time
+// DT macro cannot reach — the runtime pin→controller split, plus the `sw0`
+// alias for the BOOT button (used by the devicetree-spec GPIO path). Every other
+// DT fact (UART/I2C/SPI/`wdt` nodelabels) is resolved by Zephyr's own
+// devicetree via emitted DT_NODELABEL macros, not hand-copied here.
+//
+// Verified against the Zephyr board DTS:
+//   boards/espressif/esp32_devkitc/esp32_devkitc_procpu.dts
+//   aliases { sw0 = &button0; } → button_0: pin 0 on gpio0, active-low + pull-up
+//   &gpio0/&gpio1 { status = "okay" }   (esp32_devkitc_procpu.dts:64-70)
+//   &wifi { status = "okay" }            (esp32_devkitc_procpu.dts:143-145)
+// GPIO controller coverage:
+//   dts/xtensa/espressif/esp32/esp32_common.dtsi:314-337
+//   gpio0: ngpios = <32>  (pins 0–31)
+//   gpio1: ngpios = <8>   (pins 32–39)
+//
+// Note: GPIO 34–39 are input-only pads on ESP32 silicon (not modeled here —
+// the DT does not encode output restrictions per pin; an output config on those
+// pins fails at runtime against the raw controller, which is the expected
+// silicon-accurate behavior).
+// ---------------------------------------------------------------------------
+
+import type { ZephyrChipDescriptor } from './types.js';
+
+export const ESP32_DEVKITC: ZephyrChipDescriptor = {
+  id: 'esp32_devkitc',
+  soc: 'esp32',
+  gpioController: 'gpio0',
+  gpioControllers: [
+    { nodelabel: 'gpio0', minPin: 0, maxPin: 31 },
+    { nodelabel: 'gpio1', minPin: 32, maxPin: 39 },
+  ],
+  gpio: {
+    // The BOOT button (GPIO0) is the board's only DT-aliased GPIO. Listed so a
+    // program reading/interrupting pin 0 goes through the polarity-correct
+    // devicetree-spec path (GPIO_ACTIVE_LOW honored by the DT flags).
+    dtSpecs: [
+      { pin: 0, dtSpec: 'sw0' },  // BOOT button (GPIO0)
+    ],
+    interruptPins: [
+      { pin: 0, dtSpec: 'sw0' },  // BOOT button (GPIO0)
+    ],
+  },
+  // WiFi: the ESP32 has a 2.4GHz radio; conn_mgr + the esp32 wifi driver
+  // (CONFIG_WIFI_ESP32) provide connectivity. WIFI_ESP32 depends on !SMP, and
+  // the ESP32 is AMP (dual-image procpu/appcpu), not SMP, by default — so the
+  // dependency is satisfied. Omitted on radioless targets.
+  wifi: { supported: true },
+};

package/src/chips/esp32s3.ts

@@ -0,0 +1,57 @@
+// ---------------------------------------------------------------------------
+// Espressif ESP32-S3 (esp32s3_devkitc) — Zephyr board descriptor
+//
+// Board target: `esp32s3_devkitc` (mainline Zephyr,
+// boards/espressif/esp32s3_devkitc). Programmed over USB via the esptool
+// runner (see toolchain/index.ts), unlike the J-Link/nrfjprog path used for
+// the XIAO nRF52840.
+//
+// GPIO is split across TWO devicetree controllers — `gpio0` (pins 0–31) and
+// `gpio1` (pins 32–48) — so this descriptor lists both in `gpioControllers`.
+// The lowering routes each HAL pin to its owning controller at runtime; see
+// chips/controllers.ts.
+//
+// Minimal-by-design: the only DT facts carried here are the ones a
+// compile-time DT macro cannot reach — the runtime pin→controller split, plus
+// the `sw0` alias for the BOOT button (used by the devicetree-spec GPIO path).
+// Every other DT fact (UART/I2C/SPI/`wdt` nodelabels) is resolved by Zephyr's
+// own devicetree via emitted DT_NODELABEL macros, not hand-copied here.
+//
+// Verified against the Zephyr board DTS:
+//   boards/espressif/esp32s3_devkitc/esp32s3_devkitc_procpu.dts
+//   aliases { sw0 = &button0; } → button_0: pin 0 on gpio0, active-low + pull-up
+//   (the DevKitC board DTS defines no led0 alias — the onboard RGB is a WS2812
+//   on GPIO38, not a plain GPIO LED, so it is intentionally NOT listed here.)
+// ---------------------------------------------------------------------------
+
+import type { ZephyrChipDescriptor } from './types.js';
+
+export const ESP32S3_DEVKITC: ZephyrChipDescriptor = {
+  id: 'esp32s3_devkitc',
+  soc: 'esp32s3',
+  gpioController: 'gpio0',
+  gpioControllers: [
+    { nodelabel: 'gpio0', minPin: 0, maxPin: 31 },
+    { nodelabel: 'gpio1', minPin: 32, maxPin: 48 },
+  ],
+  gpio: {
+    // The BOOT button (GPIO0) is the board's only DT-aliased GPIO. Listed so a
+    // program reading/interrupting pin 0 goes through the polarity-correct
+    // devicetree-spec path (GPIO_ACTIVE_LOW honored by the DT flags). Every
+    // other GPIO pin uses the raw-controller path against its owning controller.
+    dtSpecs: [
+      { pin: 0, dtSpec: 'sw0' },  // BOOT button (GPIO0)
+    ],
+    interruptPins: [
+      { pin: 0, dtSpec: 'sw0' },  // BOOT button (GPIO0)
+    ],
+  },
+  // UART/I2C/SPI/`wdt` are intentionally omitted: their devicetree nodelabels
+  // (uart0/uart1/uart2, i2c0/i2c1, spi2/spi3, wdt0) are resolved by Zephyr's
+  // devicetree at compile time and don't need to be carried as data here. ADC is
+  // omitted as well — added when a demo needs analog reads, with the verified
+  // ESP32-S3 ADC1/ADC2 pin→channel map.
+  // WiFi: the ESP32-S3 has a 2.4GHz radio; conn_mgr + the esp32 wifi driver
+  // (CONFIG_WIFI_ESP32) provide connectivity. Omitted on radioless targets.
+  wifi: { supported: true },
+};

package/src/chips/index.ts

@@ -0,0 +1,54 @@
+// ---------------------------------------------------------------------------
+// Chip descriptor registry — maps Zephyr board target → ZephyrChipDescriptor
+//
+// Mirrors framework-esp32/src/chips/index.ts: a module-level activeChip,
+// setActiveChip/getActiveChip, and chipForTarget resolving from
+// frameworkData.buildTarget. The strategy calls setActiveChip during profile
+// resolution so the lowering reads a single cached descriptor.
+// ---------------------------------------------------------------------------
+
+import type { ZephyrChipDescriptor } from './types.js';
+import { XIAO_BLE } from './xiao-ble.js';
+import { ESP32S3_DEVKITC } from './esp32s3.js';
+import { ESP32_DEVKITC } from './esp32.js';
+
+export { XIAO_BLE, ESP32S3_DEVKITC, ESP32_DEVKITC };
+export type { ZephyrChipDescriptor, ZephyrGpioDtSpec } from './types.js';
+
+/**
+ * Default chip used when no buildTarget is supplied. The XIAO nRF52840 is the
+ * canonical MVP target; subsequent board additions extend the switch below.
+ */
+const DEFAULT_CHIP: ZephyrChipDescriptor = XIAO_BLE;
+
+let activeChip: ZephyrChipDescriptor = DEFAULT_CHIP;
+
+export function setActiveChip(d: ZephyrChipDescriptor): void {
+  activeChip = d;
+}
+
+export function getActiveChip(): ZephyrChipDescriptor {
+  return activeChip;
+}
+
+/**
+ * Resolve a chip descriptor from the Zephyr board target string
+ * (frameworkData.buildTarget / frameworkData.target). Accepts the bare board
+ * id ('xiao_ble', 'esp32s3_devkitc', 'esp32_devkitc') or a board/qualifier
+ * path ('esp32s3_devkitc/esp32s3/procpu', 'esp32_devkitc/esp32/procpu').
+ */
+export function chipForTarget(target?: string): ZephyrChipDescriptor {
+  const t = (target ?? '').trim().toLowerCase();
+  const boardId = t.split('/')[0];
+  switch (boardId) {
+    case 'xiao_ble':
+      return XIAO_BLE;
+    case 'esp32s3_devkitc':
+      return ESP32S3_DEVKITC;
+    case 'esp32_devkitc':
+      return ESP32_DEVKITC;
+    case '':
+    default:
+      return DEFAULT_CHIP;
+  }
+}

package/src/chips/resolve.ts

@@ -0,0 +1,146 @@
+// ---------------------------------------------------------------------------
+// Derive ZephyrChipDescriptor from board/MCU package constants
+//
+// The board constants resolver extracts flat dot-path scalars from the board
+// and MCU definition files. This utility reconstructs the structured
+// ZephyrChipDescriptor from those flat keys, merging SoC-level defaults
+// (from the MCU package's zephyr field) with board-level overrides (from the
+// board package's zephyr field).
+//
+// When a board package carries Zephyr config, this path replaces the
+// hardcoded chip descriptor registry. When it doesn't (legacy), chipForTarget
+// still works as the fallback.
+// ---------------------------------------------------------------------------
+
+import type { BoardConstants } from '@typecad/cuttlefish/api/shared';
+import type {
+  ZephyrChipDescriptor,
+  ZephyrGpioDtSpec,
+  ZephyrGpioController,
+  ZephyrBusController,
+  ZephyrPwmSpec,
+  ZephyrInterruptPin,
+  ZephyrAdcChannel,
+} from './types.js';
+
+/** Collect an indexed array of objects reconstructed from flat dot-path keys. */
+function collectIndexed<T>(
+  bc: BoardConstants,
+  prefix: string,
+  build: (bc: BoardConstants, index: number) => T | null,
+): T[] {
+  const result: T[] = [];
+  for (let i = 0; i < 256; i++) {
+    const checkKey = `${prefix}.${i}`;
+    let hasAny = false;
+    for (const [k] of bc) {
+      if (k.startsWith(checkKey)) { hasAny = true; break; }
+    }
+    if (!hasAny) break;
+    const item = build(bc, i);
+    if (item) result.push(item);
+  }
+  return result;
+}
+
+function collectBusControllers(
+  bc: BoardConstants,
+  prefix: string,
+): ZephyrBusController[] {
+  return collectIndexed<ZephyrBusController>(bc, prefix, (m, i) => {
+    const nodeLabel = m.get(`${prefix}.${i}.nodeLabel`) as string;
+    return nodeLabel ? { nodeLabel } : null;
+  });
+}
+
+/**
+ * Try to derive a ZephyrChipDescriptor from board/MCU package constants.
+ *
+ * Returns null when no zephyr info is available in the board constants
+ * (the caller should fall back to the hardcoded chipForTarget registry).
+ */
+export function resolveChipFromBoard(
+  bc: BoardConstants | undefined,
+): ZephyrChipDescriptor | null {
+  if (!bc) return null;
+
+  const boardTarget = bc.get('build.frameworks.zephyr') as string | undefined;
+  if (!boardTarget) return null;
+
+  const zGpioController = bc.get('zephyr.gpioController') as string | undefined;
+  const soc = (bc.get('mcu.id') as string) ?? '';
+
+  // ── Build mutable sub-objects, then construct the final descriptor ──────
+
+  const gc = collectIndexed<ZephyrGpioController>(bc, 'zephyr.gpioControllers', (m, i) => {
+    const nodelabel = m.get(`zephyr.gpioControllers.${i}.nodelabel`) as string;
+    const minPin = m.get(`zephyr.gpioControllers.${i}.minPin`) as number;
+    const maxPin = m.get(`zephyr.gpioControllers.${i}.maxPin`) as number;
+    if (nodelabel != null && minPin != null && maxPin != null) {
+      return { nodelabel, minPin, maxPin };
+    }
+    return null;
+  });
+
+  const dtSpecs = collectIndexed<ZephyrGpioDtSpec>(bc, 'zephyr.gpio.dtSpecs', (m, i) => {
+    const pin = m.get(`zephyr.gpio.dtSpecs.${i}.pin`) as number;
+    const dtSpec = m.get(`zephyr.gpio.dtSpecs.${i}.dtSpec`) as string;
+    if (pin != null && dtSpec) return { pin, dtSpec };
+    return null;
+  });
+
+  const intPins = collectIndexed<ZephyrInterruptPin>(bc, 'zephyr.gpio.interruptPins', (m, i) => {
+    const pin = m.get(`zephyr.gpio.interruptPins.${i}.pin`) as number;
+    const dtSpec = m.get(`zephyr.gpio.interruptPins.${i}.dtSpec`) as string;
+    if (pin != null && dtSpec) return { pin, dtSpec };
+    return null;
+  });
+
+  const i2cControllers = collectBusControllers(bc, 'zephyr.i2c.controllers');
+  const spiControllers = collectBusControllers(bc, 'zephyr.spi.controllers');
+  const uartControllers = collectBusControllers(bc, 'zephyr.uart.controllers');
+
+  const pwmSpecs = collectIndexed<ZephyrPwmSpec>(bc, 'zephyr.pwm.specs', (m, i) => {
+    const pin = m.get(`zephyr.pwm.specs.${i}.pin`) as number;
+    const dtSpec = m.get(`zephyr.pwm.specs.${i}.dtSpec`) as string;
+    if (pin != null && dtSpec) return { pin, dtSpec };
+    return null;
+  });
+
+  const adcNodeLabel = bc.get('zephyr.adc.nodeLabel') as string | undefined;
+  const adcResolution = bc.get('zephyr.adc.resolution') as number | undefined;
+  const adcVref = bc.get('zephyr.adc.vrefMv') as number | undefined;
+  const adcChannels = collectIndexed<ZephyrAdcChannel>(bc, 'zephyr.adc.channels', (m, i) => {
+    const pin = m.get(`zephyr.adc.channels.${i}.pin`) as number;
+    const channel = m.get(`zephyr.adc.channels.${i}.channel`) as number;
+    if (pin != null && channel != null) return { pin, channel };
+    return null;
+  });
+
+  const wdtNodeLabel = bc.get('zephyr.wdt.nodeLabel') as string | undefined;
+  const wifiSupported = bc.get('zephyr.wifi.supported') as boolean | undefined;
+
+  // ── Construct the final readonly descriptor ─────────────────────────────
+
+  const gpio: ZephyrChipDescriptor['gpio'] = {
+    dtSpecs,
+    ...(intPins.length > 0 ? { interruptPins: intPins } : {}),
+  };
+
+  return {
+    id: boardTarget,
+    soc,
+    gpioController: zGpioController ?? 'gpio0',
+    ...(gc.length > 0 ? { gpioControllers: gc } : {}),
+    gpio,
+    ...(i2cControllers.length > 0 ? { i2c: { controllers: i2cControllers } } : {}),
+    ...(spiControllers.length > 0 ? { spi: { controllers: spiControllers } } : {}),
+    ...(uartControllers.length > 0 ? { uart: { controllers: uartControllers } } : {}),
+    ...(pwmSpecs.length > 0 ? { pwm: { specs: pwmSpecs } } : {}),
+    ...(adcNodeLabel || adcResolution != null || adcVref != null || adcChannels.length > 0
+      ? { adc: { nodeLabel: adcNodeLabel ?? 'adc', resolution: adcResolution ?? 12, vrefMv: adcVref ?? 3000, channels: adcChannels } }
+      : {}),
+    ...(wdtNodeLabel ? { wdt: { nodeLabel: wdtNodeLabel } } : {}),
+    ...(wifiSupported ? { wifi: { supported: true as const } } : {}),
+  };
+}

package/src/chips/types.ts

@@ -0,0 +1,163 @@
+// ---------------------------------------------------------------------------
+// Zephyr chip descriptor — pure-data model
+//
+// Mirrors the per-framework chip-descriptor pattern established by
+// framework-esp32 (Esp32ChipDescriptor) and framework-avr (AVRChipDescriptor):
+// the framework owns its own device-tree-derived descriptor, keyed off the
+// Zephyr board target string in frameworkData.buildTarget. The board/MCU
+// packages are deliberately NOT read at emit time (see the framework-package
+// data-flow split); this descriptor is the source the lowering reads.
+//
+// No behavior — the lowering code in src/lowering/*.ts reads getActiveChip()
+// to resolve pins to devicetree specs and raw-controller fallbacks.
+// ---------------------------------------------------------------------------
+
+/**
+ * A GPIO pin described as a devicetree spec.
+ *
+ * Zephyr addresses GPIO via `struct gpio_dt_spec` resolved from devicetree
+ * aliases/labels (e.g. DT_ALIAS(led0)). The dtSpec form is preferred because
+ * `gpio_pin_set_dt()` honors the node's polarity flags — so an active-low LED
+ * (logical 1 = LED on) is handled by the DT `GPIO_ACTIVE_LOW` flag, not by the
+ * generated C++.
+ */
+export interface ZephyrGpioDtSpec {
+  /** GPIO number — matches the HAL op `pin` field (P0.X → X, P1.X → 32+X). */
+  readonly pin: number;
+  /**
+   * Devicetree alias/nodelabel macro, e.g. `led0`, `sw0`, `led1`.
+   * Emitted as `GPIO_DT_SPEC_GET(DT_ALIAS(<dtSpec>), gpios)`.
+   */
+  readonly dtSpec: string;
+}
+
+/**
+ * A GPIO controller devicetree node, and the HAL pin-number range it owns.
+ *
+ * Most SoCs expose a single GPIO controller (nRF52840: `gpio0` owns every
+ * pin). SoCs that split GPIO across multiple devicetree nodes — e.g. the
+ * ESP32-S3 (`gpio0`: pins 0–31, `gpio1`: pins 32–48) — list one entry per
+ * controller so the lowering can route a HAL pin to the owning controller at
+ * runtime. Pin numbers match the HAL op `pin` field.
+ */
+export interface ZephyrGpioController {
+  /** Devicetree nodelabel, e.g. 'gpio0', 'gpio1'. */
+  readonly nodelabel: string;
+  /** First HAL pin number owned by this controller (inclusive). */
+  readonly minPin: number;
+  /** Last HAL pin number owned by this controller (inclusive). */
+  readonly maxPin: number;
+}
+
+/**
+ * A bus controller (I2C / SPI / UART) described by its devicetree nodelabel.
+ *
+ * Zephyr resolves the `const struct device*` at compile time via
+ * `DEVICE_DT_GET(DT_NODELABEL(<nodeLabel>))`, so unlike ESP-IDF there is no
+ * lazy handle resolution — the lowering emits the macro directly.
+ */
+export interface ZephyrBusController {
+  /** Devicetree nodelabel, e.g. 'i2c1', 'spi2', 'uart0'. */
+  readonly nodeLabel: 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.
+ */
+export interface ZephyrPwmSpec {
+  /** GPIO number (matches the HAL op `pin` field). */
+  readonly pin: number;
+  /** Devicetree alias, e.g. 'pwm-led0'. */
+  readonly dtSpec: string;
+}
+
+/**
+ * A GPIO pin usable as an interrupt source.
+ *
+ * Emitted as `struct gpio_dt_spec __tc_int<N> = GPIO_DT_SPEC_GET(DT_ALIAS(<dtSpec>), gpios)`
+ * + a `struct gpio_callback` registered via `gpio_add_callback`.
+ */
+export interface ZephyrInterruptPin {
+  /** GPIO number (matches the HAL op `pin` field). */
+  readonly pin: number;
+  /** Devicetree alias, e.g. 'sw0', or a nodelabel. */
+  readonly dtSpec: string;
+}
+
+/**
+ * An ADC channel: which SAADC 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))`
+ * using the `channel` index here (SAADC AIN0–AIN7).
+ */
+export interface ZephyrAdcChannel {
+  /** GPIO number (matches the HAL op `pin` field). */
+  readonly pin: number;
+  /** SAADC channel index (AIN0–AIN7). */
+  readonly channel: number;
+}
+
+/**
+ * Pure-data descriptor for a Zephyr board + its SoC's peripheral layout.
+ */
+export interface ZephyrChipDescriptor {
+  /** Zephyr board target (the `west build -b <id>` argument), e.g. 'xiao_ble'. */
+  readonly id: string;
+  /** SoC family, e.g. 'nrf52840'. */
+  readonly soc: string;
+  /**
+   * Default GPIO controller nodelabel for the raw-pin fallback. Pins not in
+   * `gpio.dtSpecs` are addressed via
+   * `DEVICE_DT_GET(DT_NODELABEL(<gpioController>))` + gpio_pin_*_raw().
+   *
+   * For SoCs that split GPIO across multiple devicetree nodes, `gpioControllers`
+   * overrides this per pin range; this field is then only the out-of-range
+   * fallback (so a single-controller board is unaffected by it).
+   */
+  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`.
+   */
+  readonly gpioControllers?: readonly ZephyrGpioController[];
+  /** GPIO pins with devicetree specs (LEDs, buttons, board-defined pins). */
+  readonly gpio: {
+    readonly dtSpecs: readonly ZephyrGpioDtSpec[];
+    /** Interrupt-capable pins with DT specs (buttons etc.). */
+    readonly interruptPins?: readonly ZephyrInterruptPin[];
+  };
+  /** I2C controllers (board-wired). Index 0 = the primary bus. */
+  readonly i2c?: { readonly controllers: readonly ZephyrBusController[] };
+  /** SPI controllers (board-wired). Index 0 = the primary bus. */
+  readonly spi?: { readonly controllers: readonly ZephyrBusController[] };
+  /** UART controllers (board-wired). Index 0 = the primary port. */
+  readonly uart?: { readonly controllers: readonly ZephyrBusController[] };
+  /** PWM channels with DT specs. */
+  readonly pwm?: { readonly specs: readonly ZephyrPwmSpec[] };
+  /** ADC: the SAADC node label + the pin→channel map. */
+  readonly adc?: {
+    readonly nodeLabel: string;
+    readonly channels: readonly ZephyrAdcChannel[];
+    /** Reference voltage in millivolts (nRF internal = 3000 for VDD/4 + gain 1/4… use 3000). */
+    readonly vrefMv: number;
+    /** ADC resolution in bits. */
+    readonly resolution: number;
+  };
+  /** Watchdog node label, e.g. 'wdt0'. */
+  readonly wdt?: { readonly nodeLabel: string };
+  /**
+   * WiFi capability marker. Present only on chips with a WiFi radio (ESP32-S3).
+   * Read by profileDiagnostics to flag wifi.* usage on chips without a radio.
+   * Omit on radioless chips (nRF52840) — its absence is the "no WiFi" signal.
+   */
+  readonly wifi?: { readonly supported: true };
+}
+

package/src/chips/xiao-ble.ts

@@ -0,0 +1,64 @@
+// ---------------------------------------------------------------------------
+// Seeed Studio XIAO nRF52840 — Zephyr board descriptor
+//
+// Board target: `xiao_ble` (mainline Zephyr, boards/seeed/xiao_ble).
+// The onboard user LED is active-low and exposed as the DT alias `led0`.
+// ---------------------------------------------------------------------------
+
+import type { ZephyrChipDescriptor } from './types.js';
+
+export const XIAO_BLE: ZephyrChipDescriptor = {
+  id: 'xiao_ble',
+  soc: 'nrf52840',
+  gpioController: 'gpio0',
+  gpio: {
+    dtSpecs: [
+      // Onboard RGB LEDs — active-low (GPIO_ACTIVE_LOW in xiao_ble_common.dtsi).
+      // Verified against the board's `aliases { led0 = &led0; led1 = &led1; led2 = &led2; }`.
+      { pin: 26, dtSpec: 'led0' },  // Red   (P0.26)
+      { pin: 30, dtSpec: 'led1' },  // Green (P0.30)
+      { pin: 6, dtSpec: 'led2' },   // Blue  (P0.06)
+    ],
+    // The XIAO nRF52840 has a user button on P0.04, but mainline Zephyr's
+    // xiao_ble board (verified against Zephyr 4.3.99) does NOT expose it as a
+    // DT `sw0` alias — there is no gpio-keys node in xiao_ble.dts. Emitting
+    // GPIO_DT_SPEC_GET(DT_ALIAS(sw0), gpios) therefore fails to compile
+    // ('DT_N_ALIAS_sw0_... was not declared'). Until a button node + alias is
+    // added (via an overlay or an upstream board update), interruptPins stays
+    // empty: attachInterrupt on this board lowers to the no-DT-spec comment
+    // fallback rather than a hard compile error.
+    interruptPins: [],
+  },
+  // The XIAO connector wiring (from seeed_xiao_connector.dtsi + xiao_ble-pinctrl.dtsi):
+  //   xiao_i2c     → i2c1  (SDA P0.04/D4, SCL P0.05/D5)
+  //   xiao_spi     → spi2  (SCK P1.13/D8, MOSI P1.15/D10, MISO P1.14/D9)
+  //   xiao_serial  → uart0 (TX P1.11/D6, RX P1.12/D7)
+  // The board DTS leaves i2c0/spi0/spi1 disabled (shared instances).
+  i2c: {
+    controllers: [{ nodeLabel: 'i2c1' }],
+  },
+  spi: {
+    controllers: [{ nodeLabel: 'spi2' }],
+  },
+  uart: {
+    controllers: [{ nodeLabel: 'uart0' }],
+  },
+  pwm: {
+    // pwm-led0 drives the board PWM LED (PWM_OUT0 on P0.17, inverted).
+    specs: [{ pin: 17, dtSpec: 'pwm-led0' }],
+  },
+  adc: {
+    // SAADC node is `adc`; no pre-declared channels. XIAO D0–D3 = AIN0–AIN3
+    // (P0.02/P0.03/P0.28/P0.29). Internal VREF ~0.6V with VDD/4 gain ⇒ 3000mV.
+    nodeLabel: 'adc',
+    resolution: 12,
+    vrefMv: 3000,
+    channels: [
+      { pin: 2, channel: 0 },   // P0.02 / D0 / AIN0
+      { pin: 3, channel: 1 },   // P0.03 / D1 / AIN1
+      { pin: 28, channel: 2 },  // P0.28 / D2 / AIN2
+      { pin: 29, channel: 3 },  // P0.29 / D3 / AIN3
+    ],
+  },
+  wdt: { nodeLabel: 'wdt0' },
+};