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

package/dist/toolchain/index.js

@@ -19,19 +19,79 @@
 // ---------------------------------------------------------------------------
 import { spawnSync } from 'node:child_process';
 import { basename, dirname, join } from 'node:path';
-import { readdirSync, readFileSync, mkdirSync, rmSync } from 'node:fs';
+import { readdirSync, readFileSync, mkdirSync, rmSync, existsSync } from 'node:fs';
 import { parseCompileErrors } from '@typecad/cuttlefish/api/shared';
-import { scaffoldZephyrProject, writeIfChanged } from './scaffold.js';
+import { scaffoldZephyrProject, writeIfChanged, appendLibraryOverlayFragments } from './scaffold.js';
 import { westSpawn, buildEnv } from './west-spawn.js';
 import { discoverWest } from './west-discover.js';
 import { writeDebugConfig, resolveDebugLocations } from './debug-config.js';
 import { ZephyrStrategy } from '../strategy.js';
 import { generateOverlay } from '../dt-config/overlay.js';
 import { chipForTarget } from '../chips/index.js';
+import { resolveChipFromBoard } from '../chips/resolve.js';
+import { pwmDtAliasToken } from '../lowering/pwm.js';
 import { detectZephyrVersion, checkZephyrCompat, resolveBoardTarget } from './compat.js';
 import { DEFAULT_ZEPHYR_DISPLAY_PROFILE } from '../display/profiles.js';
 /** Default board target — the framework's MVP canonical board. */
 const DEFAULT_BOARD = 'xiao_ble';
+/**
+ * Resolve the chip for a build the same way the strategy does at emit time —
+ * from the board constants the transpile persisted next to the emitted
+ * source (`board-constants.json`), falling back to the hardcoded registry.
+ * Board-package chips (rpi_pico, esp32c3/c6, blackpill) exist only in their
+ * board packages; the registry fallback would silently resolve them to the
+ * XIAO default and the overlay generator would emit wrong controller labels
+ * (e.g. `&uart0` on an STM32, whose node is `usart1`).
+ */
+function chipForBuild(projectRoot, board) {
+    try {
+        // The transpile writes the constants into the emit outDir, which is
+        // <projectRoot>/src for the standard layout (basename 'src' collapsed by
+        // projectRootFromOptions); check both locations.
+        const bcPath = [join(projectRoot, 'src', 'board-constants.json'), join(projectRoot, 'board-constants.json')]
+            .find(p => existsSync(p));
+        if (bcPath) {
+            const raw = JSON.parse(readFileSync(bcPath, 'utf8'));
+            const fromBoard = resolveChipFromBoard(new Map(Object.entries(raw)));
+            if (fromBoard)
+                return fromBoard;
+        }
+    }
+    catch { /* fall back to the registry below */ }
+    return chipForTarget(board);
+}
+/**
+ * HAL pins the emitted sources read via adc.* — scanned from the emitted
+ * `__tc_adc<N>_setup()` call sites (N = channel index, mapped back to the HAL
+ * pin via the chip descriptor). Feeds the overlay's ADC pinctrl rewrite: on
+ * SoCs that mux ADC pads via pinctrl (STM32), only the read channels are
+ * switched to analog mode.
+ */
+function scanAdcReadPins(src, chip) {
+    const pins = [];
+    // Match CALL SITES only (`__tc_adc<N>_setup()` with empty parens) — the
+    // setup definitions emitted by adcInitLines have a `(void)` parameter list
+    // and would otherwise mark every descriptor channel as used.
+    for (const m of src.matchAll(/__tc_adc(\d+)_setup\(\)/g)) {
+        const ch = Number(m[1]);
+        const c = chip.adc?.channels.find((x) => x.channel === ch);
+        if (c && !pins.includes(c.pin))
+            pins.push(c.pin);
+    }
+    return pins;
+}
+/**
+ * HAL pins the emitted sources drive with pwm.* — the emitted source
+ * references each used spec as `__tc_pwm_<alias token>` (pwmVarName in
+ * lowering/pwm.ts), and the lowering only emits specs for driven pins, so
+ * var-presence is the authoritative signal. Feeds the overlay's per-pin
+ * pwm-leds gating (no dead DT channels).
+ */
+function scanPwmUsedPins(src, chip) {
+    return (chip.pwm?.specs ?? [])
+        .filter((s) => src.includes(`__tc_pwm_${pwmDtAliasToken(s)}`))
+        .map((s) => s.pin);
+}
 function targetFromOptions(o) {
     // The cuttlefish CLI populates ToolchainOptions.buildTarget from
     // config.frameworkData.buildTarget. Accept frameworkData.target as an alias.
@@ -77,7 +137,7 @@ const FLASH_TIMEOUT_MS = 120_000;
  * Exported (pure) so the runner-selection contract is unit-testable without
  * spawning west.
  */
-export function buildFlashArgs(buildDir, board, userRunner, port) {
+export function buildFlashArgs(buildDir, board, userRunner, port, runnerArgs) {
     const args = ['flash', '-d', buildDir];
     if (userRunner) {
         args.push('--runner', userRunner);
@@ -85,6 +145,11 @@ export function buildFlashArgs(buildDir, board, userRunner, port) {
     if (port && board.startsWith('esp32')) {
         args.push('--esp-device', port);
     }
+    // Extra runner-specific flags, appended verbatim (west's runner parsers
+    // accept them after the runner is selected).
+    if (runnerArgs && runnerArgs.length > 0) {
+        args.push(...runnerArgs);
+    }
     return args;
 }
 /**
@@ -182,7 +247,7 @@ export const Toolchain = {
         // resolution is a pre-build artifact step.
         const projectRoot = basename(outputDir) === 'src' ? dirname(outputDir) : outputDir;
         const board = DEFAULT_BOARD;
-        const chip = chipForTarget(board);
+        const chip = chipForBuild(projectRoot, board);
         // Scan the emitted source for usage tokens (same authoritative signal the
         // scaffold uses). entryPoint is the path to main.cpp; its dir is src/.
         const srcDir = dirname(entryPoint);
@@ -216,6 +281,10 @@ export const Toolchain = {
             usesI2c: uses('i2c_'),
             usesSpi: uses('spi_'),
             usesUart: uses('uart_'),
+            usesPwm: uses('pwm_'),
+            usesAdc: uses('adc_'),
+            adcReadPins: scanAdcReadPins(src, chip),
+            pwmUsedPins: scanPwmUsedPins(src, chip),
             usesDisplay,
             usesTouch: usesTouch || usesXpt,
             touchController: usesXpt ? 'xpt2046' : 'ft6336u',
@@ -253,7 +322,7 @@ export const Toolchain = {
         // the <default>.overlay it wrote does not match `west build -b <board>`.
         // Zephyr auto-detects boards/<board>.overlay under APPLICATION_CONFIG_DIR.
         try {
-            const chip = chipForTarget(board);
+            const chip = chipForBuild(projectRoot, board);
             const srcDir = join(projectRoot, 'src');
             let src = '';
             try {
@@ -343,6 +412,10 @@ export const Toolchain = {
                 usesI2c: uses('i2c_'),
                 usesSpi: uses('spi_'),
                 usesUart: uses('uart_'),
+                usesPwm: uses('pwm_'),
+                usesAdc: uses('adc_'),
+                adcReadPins: scanAdcReadPins(src, chip),
+                pwmUsedPins: scanPwmUsedPins(src, chip),
                 usesDisplay,
                 usesTouch: uses('ft6336u') || uses('touch_') || usesXpt,
                 touchController: usesXpt ? 'xpt2046' : 'ft6336u',
@@ -356,9 +429,10 @@ export const Toolchain = {
             // Write the board-specific overlay (the one west loads). Zephyr looks for
             // boards/<board_id>.overlay under APPLICATION_CONFIG_DIR — use the bare
             // board id (before any hardware-qualifier suffix, e.g. 'esp32_devkitc'
-            // not the full 'esp32_devkitc/esp32/procpu' target string).
+            // not the full 'esp32_devkitc/esp32/procpu' target string). Library
+            // packages' overlay fragments are appended by the scaffold helper.
             const boardId = board.split('/')[0];
-            writeIfChanged(join(overlayDir, `${boardId}.overlay`), overlay);
+            writeIfChanged(join(overlayDir, `${boardId}.overlay`), appendLibraryOverlayFragments(overlay, projectRoot));
         }
         catch { /* best-effort overlay regen; the build surfaces DT errors */ }
         // Use a stable build dir so incremental builds reuse the Ninja graph.
@@ -465,7 +539,8 @@ export const Toolchain = {
         const board = targetFromOptions(o);
         const zc = o.zephyrConfig;
         const runner = zc?.runner;
-        const args = buildFlashArgs(buildDir, board, runner, o.port);
+        const runnerArgs = zc?.runnerArgs;
+        const args = buildFlashArgs(buildDir, board, runner, o.port, runnerArgs);
         const inv = westSpawn(args, {
             cwd: projectRoot,
             encoding: 'utf-8',

package/dist/toolchain/scaffold.d.ts

@@ -1,6 +1,15 @@
 /** 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 declare function writeIfChanged(filePath: string, content: string): boolean;
+/**
+ * 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 declare function appendLibraryOverlayFragments(overlay: string, projectRoot: string): string;
 /**
  * Emit the Zephyr application skeleton around the generated src/main.cpp.
  *

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) {
@@ -57,6 +58,31 @@ function readEmittedSources(srcDir) {
     }
     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;
+}
 /**
  * Emit the Zephyr application skeleton around the generated src/main.cpp.
  *
@@ -202,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.13",
+  "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.13"
+    "@typecad/cuttlefish": "1.0.0-alpha.14"
   },
   "devDependencies": {
-    "@typecad/expect": "1.0.0-alpha.13",
-    "@typecad/board-xiao-nrf52840": "1.0.0-alpha.13",
+    "@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