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

package/dist/toolchain/scaffold.js

@@ -9,6 +9,7 @@
 import { writeFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { resolveKconfigFragments } from '../dt-config/kconfig.js';
+import { readCuttlefishLibrarySidecar } from '@typecad/cuttlefish/library-packages';
 /** Write a file only if the content differs from the existing file.
  *  Returns true when the file was written (content changed or file was new). */
 export function writeIfChanged(filePath, content) {
@@ -24,27 +25,61 @@ export function writeIfChanged(filePath, content) {
     writeFileSync(filePath, content);
     return true;
 }
+/**
+ * Names of the cuttlefish-emitted C/C++ sources under src/ (top level only,
+ * matching the old `src/*.cpp src/*.c` glob; sorted so the generated
+ * CMakeLists.txt is stable across readdir orderings). Empty when no sources
+ * exist yet (first prepare call).
+ */
+function listEmittedSources(srcDir) {
+    if (!existsSync(srcDir))
+        return [];
+    const names = readdirSync(srcDir).filter((name) => name.endsWith('.cpp') || name.endsWith('.c'));
+    names.sort();
+    return names;
+}
 /**
  * Concatenate all emitted source under src/ so the scaffold can detect which
  * peripherals the program actually uses. The cuttlefish lowering emits
  * well-known driver API tokens (adc_read, spi_transceive, bt_*, …), so scanning
- * the post-transpile source is an authoritative usage signal — and it keeps the
- * scaffold self-contained (no need to thread analysis through the toolchain
+ * the post-transpile source is an authoritative usage signal — and it keeps
+ * the scaffold self-contained (no need to thread analysis through the toolchain
  * contract). Returns '' when no sources exist yet (first prepare call).
  */
 function readEmittedSources(srcDir) {
-    if (!existsSync(srcDir))
-        return '';
     let out = '';
-    for (const name of readdirSync(srcDir)) {
-        if (name.endsWith('.cpp') || name.endsWith('.c')) {
-            try {
-                out += readFileSync(join(srcDir, name), 'utf8');
-            }
-            catch {
-                // ignore unreadable files
+    for (const name of listEmittedSources(srcDir)) {
+        try {
+            out += readFileSync(join(srcDir, name), 'utf8');
+        }
+        catch {
+            // ignore unreadable files
+        }
+    }
+    return out;
+}
+/**
+ * Append cuttlefish library packages' devicetree overlay fragments to the
+ * generated overlay. Library entries come from the transpiler's libraries.json
+ * sidecar (next to the emitted sources) and are already gated on the
+ * library's include token appearing in the emitted sources — no re-detection.
+ * Fragments merge after the framework overlay so library nodes (e.g.
+ * @typecad/zephyr-esp32s3-rgb's WS2812 node on I2S0) layer over it.
+ */
+export function appendLibraryOverlayFragments(overlay, projectRoot) {
+    let out = overlay;
+    for (const entry of readCuttlefishLibrarySidecar(join(projectRoot, 'src'))) {
+        if (!entry.overlay)
+            continue;
+        try {
+            const fragment = readFileSync(entry.overlay, 'utf8').trim();
+            if (fragment.length > 0) {
+                out += (out.endsWith('\n') ? '' : '\n') + '\n' + fragment + '\n';
             }
         }
+        catch {
+            // best-effort; a missing fragment surfaces as a DT error
+        }
     }
     return out;
 }
@@ -118,8 +153,13 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
     };
     let changed = false;
     // ── Root CMakeLists.txt ─────────────────────────────────────────────────
-    // The canonical Zephyr CMake application. GLOB src/*.cpp so future multi-
-    // file emits are picked up automatically; cuttlefish owns the file contents.
+    // The canonical Zephyr CMake application. The emitted source list is
+    // explicit (no file(GLOB CONFIGURE_DEPENDS ...)): CONFIGURE_DEPENDS puts a
+    // cmake.verify_globs step in the ninja graph that spawns CMake to re-check
+    // the glob on every build, and the scaffold already rewrites this file via
+    // writeIfChanged whenever the emitted file set changes — which flips
+    // configChanged and reconfigures with the new list baked in.
+    const sourceFiles = listEmittedSources(srcDir);
     const cmakeLists = [
         '# Auto-generated by @typecad/framework-zephyr from cuttlefish.config.ts.',
         'cmake_minimum_required(VERSION 3.20.0)',
@@ -128,12 +168,18 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
         '',
         'project(zephyr_app)',
         '',
-        '# Collect cuttlefish-emitted sources. CONFIGURE_DEPENDS makes CMake re-',
-        '# check the glob when the source set changes (e.g. the transpiler removes',
-        '# a stale entry), instead of linking a file list from the last configure.',
-        'file(GLOB app_sources CONFIGURE_DEPENDS src/*.cpp src/*.c)',
-        '',
-        'target_sources(app PRIVATE ${app_sources})',
+        ...(sourceFiles.length > 0
+            ? [
+                '# Cuttlefish-emitted sources. This list is regenerated whenever the',
+                '# emitted file set changes (the scaffold rewrites CMakeLists.txt).',
+                'target_sources(app PRIVATE',
+                ...sourceFiles.map((name) => `  src/${name}`),
+                ')',
+            ]
+            : [
+                '# No emitted sources yet — the scaffold regenerates this list on the',
+                '# next compile once src/ contains .cpp/.c files.',
+            ]),
         // When PSRAM is configured, define BOARD_HAS_PSRAM so the UI runtime's
         // PSRAM canvas allocator (ui_create_canvas_best) is compiled in.
         ...(psram ? ['', '# PSRAM enabled: activate the runtime PSRAM canvas paths.', 'target_compile_definitions(app PRIVATE BOARD_HAS_PSRAM)', ''] : ['']),
@@ -182,6 +228,25 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
             continue;
         prjConf.push(`${sym}=${val}`);
     }
+    // ── Cuttlefish library packages ─────────────────────────────────────────
+    // Libraries the program imports (recorded in the transpiler's libraries.json
+    // sidecar, next to the emitted sources) contribute their manifest's kconfig
+    // lines — e.g. @typecad/zephyr-esp32s3-rgb contributes CONFIG_LED_STRIP.
+    // Sidecar entries are already gated on the library's include token
+    // appearing in the emitted sources, so no re-detection here. User
+    // zephyr.kconfig overrides still win.
+    const libraryEntries = readCuttlefishLibrarySidecar(srcDir);
+    if (libraryEntries.length > 0) {
+        prjConf.push('', '# Library packages (cuttlefish.library.json contributions).');
+        for (const entry of libraryEntries) {
+            for (const line of entry.kconfig) {
+                const sym = line.split('=')[0];
+                if (userKconfig && sym !== undefined && userKconfig.hasOwnProperty(sym))
+                    continue;
+                prjConf.push(line);
+            }
+        }
+    }
     // Emit user-specified Kconfig from cuttlefish.config.ts zephyr.kconfig.
     // These override any matching auto-detected symbol (skipped above).
     if (userKconfig) {

package/dist/toolchain/west-discover.d.ts

@@ -9,8 +9,11 @@ export interface WestInstall {
     westExecutable?: string;
     /** Absolute path to a Python interpreter with west installed (mode 'module'). */
     pythonExecutable?: string;
-    /** Absolute path to the Zephyr SDK root (for $ZEPHYR_BASE), if found. */
+    /** Absolute path to the Zephyr workspace (for $ZEPHYR_BASE), if found. */
     zephyrBase?: string;
+    /** Absolute path to the Zephyr SDK install dir (hosttools/openocd lives
+     *  there), if found — used to put the SDK's openocd on the flash PATH. */
+    sdkInstallDir?: string;
     /** mode 'micromamba': path to the micromamba binary (for `micromamba run -n …`). */
     micromambaExe?: string;
     /** mode 'micromamba': the conda env name (default 'zephyr'). */

package/dist/toolchain/west-discover.js

@@ -172,12 +172,14 @@ export function discoverFromMicromamba(envName = process.env.TYPECAD_ZEPHYR_ENV
     // anything else in the cuttlefish process) can detect the Zephyr version
     // WITHOUT activation — micromamba run sets it only inside the west subprocess.
     const zb = readMicromambaEnvVar(envDir, 'TYPECAD_ZEPHYR_BASE');
+    const sdk = readMicromambaEnvVar(envDir, 'TYPECAD_ZEPHYR_SDK_INSTALL_DIR');
     return {
         mode: 'micromamba',
         micromambaExe: mm.exe,
         envName,
         mambaRootPrefix: mm.rootPrefix,
         zephyrBase: zb && isZephyrBase(zb) ? zb : undefined,
+        sdkInstallDir: sdk && existsSync(sdk) ? sdk : undefined,
         source: 'micromamba',
     };
 }

package/dist/toolchain/west-spawn.js

@@ -14,7 +14,8 @@
 // (find_package(Zephyr) needs it). west's prj.conf/CMakeLists are found via
 // the project dir regardless.
 // ---------------------------------------------------------------------------
-import { dirname } from 'node:path';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
 import { discoverWest } from './west-discover.js';
 /**
  * The Scripts/ (Windows) or bin/ (POSIX) directory of the venv the discovered
@@ -41,8 +42,19 @@ export function buildEnv(install) {
     if (install.zephyrBase && !env.ZEPHYR_BASE) {
         env.ZEPHYR_BASE = install.zephyrBase;
     }
-    const bin = venvBinDir(install);
-    if (bin) {
+    // SWD flashing (`zephyr.runner: 'openocd'`): west's openocd runner resolves
+    // a bare `openocd` from PATH. The Zephyr SDK ships it under
+    // hosttools/openocd/bin (the SDK's own setup.cmd puts that dir on PATH for
+    // activated terminals) — do the same for spawned west processes so ST-Link
+    // flashing works without activation. $ZEPHYR_SDK_INSTALL_DIR (set by an
+    // activated env) wins over the discovered install dir.
+    const sdkRoot = env.ZEPHYR_SDK_INSTALL_DIR || install.sdkInstallDir;
+    const openocdBin = sdkRoot ? join(sdkRoot, 'hosttools', 'openocd', 'bin') : undefined;
+    const prepend = [
+        openocdBin !== undefined && existsSync(openocdBin) ? openocdBin : undefined,
+        venvBinDir(install),
+    ].filter((d) => d !== undefined);
+    if (prepend.length > 0) {
         const sep = process.platform === 'win32' ? ';' : ':';
         // On Windows the PATH environment variable may be cased as `Path` (the
         // registry-native form, the only one populated when node is launched from
@@ -50,9 +62,9 @@ export function buildEnv(install) {
         // casing can leave the other stale/empty, which under PowerShell would drop
         // the user's real PATH (cmake, ninja, …) — breaking `west` configure. Read
         // whichever casing is populated and write that same casing back, preserving
-        // the full existing value with the venv dir prepended.
+        // the full existing value with the discovered dirs prepended.
         const existing = env.Path ?? env.PATH ?? '';
-        const updated = bin + sep + existing;
+        const updated = prepend.join(sep) + sep + existing;
         if (env.Path !== undefined || (env.PATH === undefined && process.platform === 'win32')) {
             env.Path = updated;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typecad/framework-zephyr",
-  "version": "1.0.0-alpha.12",
+  "version": "1.0.0-alpha.14",
   "description": "TypeCAD framework package for the Zephyr RTOS — west/CMake build, devicetree-driven GPIO",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,11 +38,11 @@
     "test:hw:mqtt": "cd ../../tests/hardware && npm exec -- cuttlefish-test mqtt-client.test.ts"
   },
   "dependencies": {
-    "@typecad/cuttlefish": "1.0.0-alpha.12"
+    "@typecad/cuttlefish": "1.0.0-alpha.14"
   },
   "devDependencies": {
-    "@typecad/expect": "1.0.0-alpha.12",
-    "@typecad/board-xiao-nrf52840": "1.0.0-alpha.12",
+    "@typecad/expect": "1.0.0-alpha.14",
+    "@typecad/board-xiao-nrf52840": "1.0.0-alpha.14",
     "typescript": "^5.7.3"
   },
   "license": "MIT",
@@ -75,7 +75,7 @@
     "zephyr"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22.11.0"
   },
   "author": "typecad0",
   "sideEffects": false

package/src/chips/controllers.ts

@@ -19,7 +19,7 @@
 //     collapse to a one-liner.
 // ---------------------------------------------------------------------------
 
-import type { ZephyrChipDescriptor } from './types.js';
+import type { ZephyrChipDescriptor, ZephyrGpioController } from './types.js';
 
 /**
  * Resolve the devicetree nodelabel of the GPIO controller that owns `pin`.
@@ -30,23 +30,53 @@ import type { ZephyrChipDescriptor } from './types.js';
  * for out-of-range pins (e.g. the manifest probe's synthetic pin 0).
  */
 export function controllerNodelabelForPin(chip: ZephyrChipDescriptor, pin: number): string {
+  const hit = controllerRangeForPin(chip, pin);
+  return hit ? hit.nodelabel : chip.gpioController;
+}
+
+/**
+ * The owning controller range for a HAL pin, if the chip declares a split.
+ */
+export function controllerRangeForPin(
+  chip: ZephyrChipDescriptor,
+  pin: number,
+): ZephyrGpioController | undefined {
   const ranges = chip.gpioControllers;
   if (ranges && ranges.length > 0) {
-    const hit = ranges.find((r) => pin >= r.minPin && pin <= r.maxPin);
-    if (hit) return hit.nodelabel;
+    return ranges.find((r) => pin >= r.minPin && pin <= r.maxPin);
   }
-  return chip.gpioController;
+  return undefined;
 }
 
 /**
- * Emit the C++ source for a runtime pin → GPIO-device dispatcher.
+ * The PORT-RELATIVE pin index for the raw gpio_pin_*_raw() API — the Zephyr
+ * raw calls address the index WITHIN the controller, not the global HAL pin
+ * number. For split SoCs each controller's `minPin` is its base (STM32:
+ * gpiob minPin 16, so PB12 = pin 28 → raw 12); single-controller SoCs have
+ * no offset. Emitting the global number against a port driver would address
+ * a nonexistent port bit (STM32 gpiob is 0–15) and fail at runtime.
+ */
+export function controllerRawPinForPin(chip: ZephyrChipDescriptor, pin: number): number {
+  const hit = controllerRangeForPin(chip, pin);
+  return pin - (hit?.minPin ?? 0);
+}
+
+/**
+ * Emit the C++ source for runtime pin → GPIO-device / port-relative-index
+ * dispatchers.
+ *
+ * Returns lines defining:
+ *  - `static inline const struct device* __tc_gpio_dev(uint32_t pin)` — the
+ *    owning controller's device, resolved via DEVICE_DT_GET(DT_NODELABEL(...))
+ *    at compile time (the macro is evaluated per branch, so it is always
+ *    statically valid); only `pin` is runtime.
+ *  - `static inline gpio_pin_t __tc_gpio_pin(uint32_t pin)` — the
+ *    port-relative index for gpio_pin_*_raw() (see controllerRawPinForPin).
+ *    The runtime shim paths (UI pin-watch, safety voters) take a runtime pin,
+ *    so they cannot bake the offset in at emit time.
  *
- * Returns lines defining `static inline const struct device* __tc_gpio_dev(uint32_t pin)`.
- * Each branch resolves its controller via `DEVICE_DT_GET(DT_NODELABEL(...))` at
- * compile time (the macro is evaluated per branch, so it is always statically
- * valid); only `pin` is runtime. For a single-controller SoC this collapses to
- * a one-liner returning that controller, so the existing XIAO nRF52840 behavior
- * is byte-for-byte unchanged.
+ * For a single-controller SoC both collapse to one-liners, so the existing
+ * XIAO nRF52840 behavior is byte-for-byte unchanged.
  */
 export function emitGpioDevDispatcher(chip: ZephyrChipDescriptor): string[] {
   const ranges = chip.gpioControllers;
@@ -56,19 +86,38 @@ export function emitGpioDevDispatcher(chip: ZephyrChipDescriptor): string[] {
       `    (void)pin;`,
       `    return DEVICE_DT_GET(DT_NODELABEL(${chip.gpioController}));`,
       '}',
+      'static inline gpio_pin_t __tc_gpio_pin(uint32_t pin) {',
+      `    return (gpio_pin_t)pin;`,
+      '}',
     ];
   }
   const lines: string[] = [
     'static inline const struct device* __tc_gpio_dev(uint32_t pin) {',
   ];
+  const pinLines: string[] = [
+    'static inline gpio_pin_t __tc_gpio_pin(uint32_t pin) {',
+  ];
   for (const r of ranges) {
     lines.push(
       `    if (pin >= ${r.minPin} && pin <= ${r.maxPin}) { return DEVICE_DT_GET(DT_NODELABEL(${r.nodelabel})); }`,
     );
+    if (r.minPin === 0) {
+      pinLines.push(
+        `    if (pin >= ${r.minPin} && pin <= ${r.maxPin}) { return (gpio_pin_t)pin; }`,
+      );
+    } else {
+      pinLines.push(
+        `    if (pin >= ${r.minPin} && pin <= ${r.maxPin}) { return (gpio_pin_t)(pin - ${r.minPin}); }`,
+      );
+    }
   }
   lines.push(
     `    return DEVICE_DT_GET(DT_NODELABEL(${chip.gpioController}));`,
     '}',
   );
-  return lines;
+  pinLines.push(
+    `    return (gpio_pin_t)pin;`,
+    '}',
+  );
+  return [...lines, ...pinLines];
 }

package/src/chips/resolve.ts

@@ -102,18 +102,36 @@ export function resolveChipFromBoard(
 
   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 dtSpec = m.get(`zephyr.pwm.specs.${i}.dtSpec`) as string | undefined;
+    const controller = m.get(`zephyr.pwm.specs.${i}.controller`) as string | undefined;
+    const channel = m.get(`zephyr.pwm.specs.${i}.channel`) as number | undefined;
+    const periodNs = m.get(`zephyr.pwm.specs.${i}.periodNs`) as number | undefined;
+    const polarity = m.get(`zephyr.pwm.specs.${i}.polarity`) as string | undefined;
+    // Board-shipped alias form (dtSpec) or synthesized form (controller +
+    // channel → overlay-generated alias) — at least one, else drop the entry.
+    if (pin == null || !(dtSpec || (controller && channel != null))) return null;
+    return {
+      pin,
+      ...(dtSpec ? { dtSpec } : {}),
+      ...(controller ? { controller } : {}),
+      ...(channel != null ? { channel } : {}),
+      ...(periodNs != null ? { periodNs } : {}),
+      ...(polarity ? { polarity } : {}),
+    };
   });
 
   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 adcGain = bc.get('zephyr.adc.gain') as string | undefined;
+  const adcReference = bc.get('zephyr.adc.reference') as string | 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 };
+    const pinctrl = m.get(`zephyr.adc.channels.${i}.pinctrl`) as string | undefined;
+    if (pin != null && channel != null) {
+      return { pin, channel, ...(pinctrl ? { pinctrl } : {}) };
+    }
     return null;
   });
 
@@ -138,7 +156,16 @@ export function resolveChipFromBoard(
     ...(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 } }
+      ? {
+          adc: {
+            nodeLabel: adcNodeLabel ?? 'adc',
+            resolution: adcResolution ?? 12,
+            vrefMv: adcVref ?? 3000,
+            channels: adcChannels,
+            ...(adcGain ? { gain: adcGain } : {}),
+            ...(adcReference ? { reference: adcReference } : {}),
+          },
+        }
       : {}),
     ...(wdtNodeLabel ? { wdt: { nodeLabel: wdtNodeLabel } } : {}),
     ...(wifiSupported ? { wifi: { supported: true as const } } : {}),

package/src/chips/types.ts

@@ -64,14 +64,37 @@ export interface ZephyrBusController {
 /**
  * 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;
 }
 
 /**
@@ -88,7 +111,7 @@ export interface ZephyrInterruptPin {
 }
 
 /**
- * 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))`
@@ -97,8 +120,16 @@ 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;
+  /**
+   * 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;
 }
 
 /**
@@ -134,11 +165,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). */
@@ -155,7 +193,7 @@ export interface ZephyrChipDescriptor {
   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. */
+  /** ADC: the ADC device node label + the pin→channel map. */
   readonly adc?: {
     readonly nodeLabel: string;
     readonly channels: readonly ZephyrAdcChannel[];
@@ -163,6 +201,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