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

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

@@ -0,0 +1,227 @@
+// ---------------------------------------------------------------------------
+// Custom board generation — an out-of-tree Zephyr board for an MCU-only target
+//
+// When a project targets an MCU package with no board package (`mcu:` set,
+// `board:` absent) there may be no Zephyr board for the user's hardware. The
+// chip descriptor's `customBoard` block (silicon facts from the MCU package:
+// SoC name, devicetree includes, default console mux, default clock plan) is
+// all a minimal HWMv2 board needs, so we generate one into the project:
+//
+//   boards/typecad/<name>/board.yml       — board + SoC declaration
+//   boards/typecad/<name>/<name>.dts      — includes, chosen, console, clocks
+//   boards/typecad/<name>/Kconfig.<name>  — BOARD_<NAME> symbol selecting the SoC
+//   boards/typecad/<name>/<name>_defconfig— baseline (GPIO + console) every
+//                                           in-tree board carries
+//
+// The app's CMakeLists.txt adds the project root to BOARD_ROOT (see
+// toolchain/scaffold.ts), so Zephyr discovers the board without touching the
+// checkout. Everything else (buses, ADC, PWM, USB) stays usage-driven: the
+// overlay generator keeps layering `boards/<name>.overlay` on top exactly as
+// it does for upstream boards.
+//
+// Verified against Zephyr 4.3/4.4 (HWMv2): a minimal board is exactly these
+// four files — Kconfig.<name> + CONFIG_GPIO=y are load-bearing (a board
+// without them fails with "ARCH not defined" / gpio link errors).
+// ---------------------------------------------------------------------------
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { writeIfChanged } from '../toolchain/scaffold.js';
+/** The vendor segment of the generated board path + board.yml. */
+const CUSTOM_BOARD_VENDOR = 'typecad';
+/**
+ * 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 function sanitizeBoardName(raw) {
+    const cleaned = raw
+        .toLowerCase()
+        .replace(/[^a-z0-9_]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+    return cleaned.length > 0 ? cleaned : 'custom_board';
+}
+/** Kconfig symbol fragment: `cb_f411` → `CB_F411`. */
+function kconfigFragment(name) {
+    return name.toUpperCase();
+}
+/**
+ * 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 function generateCustomBoard(projectRoot, chip, rawName) {
+    const cb = chip.customBoard;
+    if (!cb)
+        return null;
+    const name = sanitizeBoardName(rawName);
+    const soc = cb.socs[0];
+    if (!soc)
+        return null;
+    const dir = join(projectRoot, 'boards', CUSTOM_BOARD_VENDOR, name);
+    mkdirSync(dir, { recursive: true });
+    let changed = false;
+    // ── board.yml ────────────────────────────────────────────────────────────
+    changed =
+        writeIfChanged(join(dir, 'board.yml'), [
+            '# Auto-generated by @typecad/framework-zephyr from the MCU package',
+            '# silicon definition. Regenerated on every compile — edit the MCU',
+            '# package (or add a board package) instead of this file.',
+            'board:',
+            `  name: ${name}`,
+            `  full_name: Cuttlefish custom board (${chip.soc})`,
+            `  vendor: ${CUSTOM_BOARD_VENDOR}`,
+            '  socs:',
+            `    - name: ${soc}`,
+            '',
+        ].join('\n')) || changed;
+    // ── Kconfig.<name> — the board symbol selecting the SoC ─────────────────
+    // Load-bearing: without the BOARD_<NAME> symbol selecting SOC_<SOC>, Kconfig
+    // completes with no SoC and the build dies with "ARCH not defined".
+    changed =
+        writeIfChanged(join(dir, `Kconfig.${name}`), [
+            '# Auto-generated by @typecad/framework-zephyr. Do not edit.',
+            '',
+            `config BOARD_${kconfigFragment(name)}`,
+            `\tselect SOC_${kconfigFragment(soc)}`,
+            '',
+        ].join('\n')) || changed;
+    // ── <name>.dts — includes, chosen, console, clock plan ───────────────────
+    const lines = [
+        '// Auto-generated by @typecad/framework-zephyr from the MCU package',
+        '// silicon definition. Regenerated on every compile — edit the MCU',
+        '// package (or add a board package) instead of this file.',
+        '/dts-v1/;',
+        ...cb.dtsIncludes.map((inc) => `#include <${inc}>`),
+        '',
+        '/ {',
+        `	model = "Cuttlefish custom board (${chip.soc})";`,
+        `	compatible = "${CUSTOM_BOARD_VENDOR},${name.replace(/_/g, '-')}";`,
+        '',
+        '	chosen {',
+        `		zephyr,console = &${cb.console.nodeLabel};`,
+        '		zephyr,sram = &sram0;',
+        '		zephyr,flash = &flash0;',
+        '	};',
+        '};',
+        '',
+    ];
+    // The chip descriptor's DT-aliased GPIOs (sw0/led0 from the reference
+    // board data): the generated firmware addresses them via DT_ALIAS, so the
+    // custom board must define the nodes. Pins map through gpioControllers
+    // (port-block numbering: pin = minPin + port bit).
+    const controllerFor = (pin) => {
+        const c = chip.gpioControllers?.find((c) => pin >= c.minPin && pin <= c.maxPin);
+        if (c)
+            return { label: c.nodelabel, bit: pin - c.minPin };
+        return undefined;
+    };
+    const keys = chip.gpio.dtSpecs.filter((s) => s.dtSpec.startsWith('sw') || s.dtSpec.startsWith('button'));
+    const leds = chip.gpio.dtSpecs.filter((s) => s.dtSpec.startsWith('led'));
+    if (keys.length > 0 || leds.length > 0) {
+        lines.push('/ {');
+        if (leds.length > 0) {
+            lines.push('	leds {', '		compatible = "gpio-leds";');
+            for (const l of leds) {
+                const c = controllerFor(l.pin);
+                if (!c)
+                    continue;
+                lines.push(`		${l.dtSpec}_node: ${l.dtSpec.replace(/_/g, '-')} {`, `			gpios = <&${c.label} ${c.bit} GPIO_ACTIVE_LOW>;`, '		};');
+            }
+            lines.push('	};');
+        }
+        if (keys.length > 0) {
+            lines.push('	gpio_keys {', '		compatible = "gpio-keys";');
+            for (const k of keys) {
+                const c = controllerFor(k.pin);
+                if (!c)
+                    continue;
+                lines.push(`		${k.dtSpec}_node: ${k.dtSpec.replace(/_/g, '-')} {`, `			gpios = <&${c.label} ${c.bit} (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>;`, '		};');
+            }
+            lines.push('	};');
+            lines.push('	aliases {');
+            for (const k of keys)
+                lines.push(`		${k.dtSpec} = &${k.dtSpec}_node;`);
+            for (const l of leds)
+                lines.push(`		${l.dtSpec} = &${l.dtSpec}_node;`);
+            lines.push('	};');
+        }
+        lines.push('};', '');
+    }
+    lines.push(
+    // Console UART — the one controller the board enables unconditionally;
+    // every other bus is enabled by the usage-driven overlay.
+    `&${cb.console.nodeLabel} {`, `	pinctrl-0 = <&${cb.console.tx} &${cb.console.rx}>;`, '	pinctrl-names = "default";', '	status = "okay";', `	current-speed = <${cb.console.speed}>;`, '};', '');
+    // USB: alias the silicon node under the Zephyr convention the descriptor's
+    // usb.controller names (e.g. zephyr_udc0: &usbotg_fs), pre-enabled with its
+    // pinctrl — the st,stm32-otgfs binding requires pinctrl-0 on an enabled
+    // node, and the overlay's CDC composition only flips status/enables the
+    // stack (Kconfig-gated), never pins. Mirrors the blackpill board shape.
+    if (cb.usbNode && chip.usb) {
+        lines.push(`${chip.usb.controller}: &${cb.usbNode} {`, ...(cb.usbPinctrl && cb.usbPinctrl.length > 0
+            ? [
+                `	pinctrl-0 = <${cb.usbPinctrl.map((p) => `&${p}`).join(' ')}>;`,
+                '	pinctrl-names = "default";',
+            ]
+            : []), '	status = "okay";', '};', '');
+    }
+    // PWM: the overlay enables `&pwm<N>` and synthesizes pwm-leds consumers
+    // against it — but the pwm<N> LABEL only exists when a board DTS declares
+    // it (the SoC dtsi ships the timers' pwm child unlabeled), and the
+    // st,stm32-pwm binding requires pinctrl-0 on an enabled node. Emit the
+    // blackpill-shape block per controller whose specs all carry pinctrl
+    // tokens; controllers without full token coverage stay to board packages.
+    if (chip.pwm) {
+        const byController = new Map();
+        for (const s of chip.pwm.specs) {
+            if (!s.controller)
+                continue;
+            const timersMatch = s.controller.match(/^pwm(\d+)$/);
+            if (!timersMatch)
+                continue;
+            const entry = byController.get(s.controller) ?? { n: timersMatch[1], tokens: [], complete: true };
+            if (s.pinctrl) {
+                entry.tokens.push(s.pinctrl);
+            }
+            else {
+                entry.complete = false;
+            }
+            byController.set(s.controller, entry);
+        }
+        for (const [controller, entry] of byController) {
+            if (!entry.complete || entry.tokens.length === 0)
+                continue;
+            lines.push(`&timers${entry.n} {`, '	status = "okay";', '', `	${controller}: pwm {`, `		pinctrl-0 = <${entry.tokens.map((t) => `&${t}`).join(' ')}>;`, '		pinctrl-names = "default";', '		status = "okay";', '	};', '};', '');
+        }
+    }
+    // ADC: some SoC drivers require board-DTS properties on an enabled adc node
+    // (STM32 F4: st,adc-clock-source + st,adc-prescaler, or the binding rejects
+    // the node when the usage-driven overlay enables it). Pre-enable with the
+    // silicon-required props + a baseline pinctrl; the overlay rewrites
+    // pinctrl-0 to the channels the program actually reads.
+    if (cb.adcNode) {
+        const a = cb.adcNode;
+        lines.push(`&${a.nodeLabel} {`, `	pinctrl-0 = <&${a.pinctrl}>;`, '	pinctrl-names = "default";', `	st,adc-clock-source = "${a.clockSource}";`, `	st,adc-prescaler = <${a.prescaler}>;`, '	status = "okay";', '};', '');
+    }
+    // Clock plan — STM32 F4 shape today (the only family carrying a clocks
+    // block so far): HSE crystal, PLL, RCC prescalers. SoCs whose dtsi clocks
+    // work out of the box ship no clocks block and emit nothing here.
+    const clk = cb.clocks;
+    lines.push(`&clk_hse {`, `	clock-frequency = <DT_FREQ_M(${clk.hseMHz})>;`, '	status = "okay";', '};', '', '&pll {', `	div-m = <${clk.pll.divM}>;`, `	mul-n = <${clk.pll.mulN}>;`, `	div-p = <${clk.pll.divP}>;`, `	div-q = <${clk.pll.divQ}>;`, '	clocks = <&clk_hse>;', '	status = "okay";', '};', '', '&rcc {', '	clocks = <&pll>;', `	clock-frequency = <DT_FREQ_M(${clk.sysMHz})>;`, `	ahb-prescaler = <${clk.ahbPrescaler}>;`, `	apb1-prescaler = <${clk.apb1Prescaler}>;`, `	apb2-prescaler = <${clk.apb2Prescaler}>;`, '};', '');
+    changed = writeIfChanged(join(dir, `${name}.dts`), lines.join('\n')) || changed;
+    // ── <name>_defconfig — the baseline every in-tree board carries ──────────
+    // Load-bearing: without CONFIG_GPIO the STM32 pinctrl driver's gpio_ports
+    // table references devices that are never built (undefined __device_dts_ord
+    // at link). Console/serial match what the DTS enables.
+    changed =
+        writeIfChanged(join(dir, `${name}_defconfig`), [
+            '# Auto-generated by @typecad/framework-zephyr. Do not edit.',
+            '',
+            'CONFIG_GPIO=y',
+            'CONFIG_SERIAL=y',
+            'CONFIG_CONSOLE=y',
+            'CONFIG_UART_CONSOLE=y',
+            '',
+        ].join('\n')) || changed;
+    return { dir, name, changed };
+}

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

@@ -1,3 +1,18 @@
+/** A sensor part's catalog facts, as the exceptions helper consumes them. */
+interface SensorKconfigSource {
+    kconfig: readonly string[];
+}
+/**
+ * Apply the per-part Kconfig exceptions the generated catalog records, for
+ * exactly the parts the program constructs. Lines are CONFIG_<SYM>=<value>
+ * strings parsed into the map; a symbol the user set explicitly in
+ * zephyr.kconfig is left alone (scaffold.ts already skips user overrides for
+ * auto symbols, and Map.set idempotence covers the rest). The lookup is a
+ * parameter so tests can drive it with a synthetic catalog.
+ */
+export declare function applySensorKconfigExceptions(m: Map<string, string>, parts: readonly {
+    part: string;
+}[] | undefined, lookup?: Readonly<Record<string, SensorKconfigSource>>): void;
 export interface KconfigUsage {
     usesAdc?: boolean;
     usesPwm?: boolean;
@@ -7,24 +22,90 @@ export interface KconfigUsage {
     usesI2c?: boolean;
     usesSpi?: boolean;
     usesUart?: boolean;
+    /** USB CDC-ACM serial used (usb.* ops). Selects the "next" USB device
+     *  stack + CDC class; the class instances themselves are composed in the
+     *  DT overlay and auto-default on once the node exists (assigning the
+     *  class symbol keeps prj.conf explicit and survives DT-only probes). */
+    usesUsb?: boolean;
     usesWdt?: boolean;
     usesBle?: boolean;
     usesDisplay?: boolean;
-    usesPower?: boolean;
     usesWifi?: boolean;
     usesHttp?: boolean;
     usesMqtt?: boolean;
     usesPreferences?: boolean;
     usesRandom?: boolean;
+    /** A printf-family format specifier with a float conversion (%f, %.2f, %e,
+     *  …) appears in the emitted source — Zephyr's cbprintf only links float
+     *  conversions with FP_SUPPORT (which itself needs the COMPLETE impl). */
+    usesFloatFormat?: boolean;
+    /** DT-bound sensor parts used (sensor.* ops — the generic catalog). The
+     *  umbrella under which every driver sensor Kconfig lives (`if SENSOR`);
+     *  the per-driver symbols default on from their DT node presence. */
+    usesSensor?: boolean;
+    /** Distinct constructed sensors — only the overlay generator consumes this
+     *  (one DT child node per entry, on the given I2C controller index); prj.conf
+     *  ignores it. Same adcReadPins/pwmUsedPins pattern. */
+    sensorParts?: readonly {
+        part: string;
+        busIndex: number;
+        port: number;
+        busKind: 'i2c' | 'spi';
+        spiHz?: number;
+        spiMode?: number;
+        alertPin?: number;
+    }[];
+    /** Distinct thin SPI targets (hal/spi-target.ts) — one DT child node per
+     *  entry (no compatible — a raw spi_dt_spec peer), appended after sensor
+     *  CS entries in the controller's merged cs-gpios. */
+    spiTargets?: readonly {
+        busIndex: number;
+        cs: number;
+        hz?: number;
+        mode?: number;
+    }[];
     /** Touch controller referenced (UI touch adapter emits DT_NODELABEL(ft6336u)
      *  or DT_NODELABEL(xpt2046)). Selects the bus driver the node needs. */
     usesTouch?: boolean;
     /** Which touch controller the program uses — FT6336U rides I2C, XPT2046
      *  rides the display's SPI bus. Only meaningful with usesTouch. */
     touchController?: 'ft6336u' | 'xpt2046';
+    /** The emitted shim carries the STM32F4 DBGMCU keep-SWD-alive init
+     *  (__tc_stm32_dbgmcu token). Selects Zephyr's own "debugger attach in
+     *  stop/sleep" init (sets DBG_STOP via the LL headers); the shim's raw
+     *  register poke additionally covers DBG_SLEEP, which the Zephyr F4 path
+     *  does not set. */
+    usesStm32DebugSleep?: boolean;
     /** PSRAM type ('opi' | 'quad') when the target board has PSRAM. Emits the
      *  CONFIG_SPIRAM symbols so the ESP heap serves PSRAM for canvas allocations. */
     psram?: 'opi' | 'quad';
+    /** HAL pin numbers the program reads with adc.* — scanned from the emitted
+     *  `__tc_adc<N>_setup()` calls at compile time. Only the overlay generator
+     *  consumes this (to rewrite the ADC node's pinctrl-0 to the used channels
+     *  on SoCs that need pad muxing, e.g. STM32); prj.conf ignores it. */
+    adcReadPins?: readonly number[];
+    /** HAL pin numbers the program drives with dac.* — scanned from the
+     *  emitted lazy-setup guards (__tc_dact<pin>_done) at compile time. Only
+     *  the overlay generator consumes this (the DAC node's pinctrl-0 lists
+     *  the used channels); prj.conf ignores it. */
+    dacWritePins?: readonly number[];
+    /** HAL pin numbers the program drives with pwm.* — scanned from the
+     *  emitted `__tc_pwm_*` spec references at compile time. Only the overlay
+     *  generator consumes this (synthesized pwm-leds consumers + aliases are
+     *  emitted per used pin, so the DT carries no dead channels); prj.conf
+     *  ignores it. */
+    pwmUsedPins?: readonly number[];
+    /** Controller indexes per bus the program actually drives — scanned from
+     *  the emitted `__tc_<bus><N>_dev` state blocks at compile time. The
+     *  overlay enables only those controllers (an enabled-but-unused
+     *  controller claims its default pins — e.g. i2c0's GP4/GP5 on the Pico —
+     *  which a program using the OTHER controller may want as GPIO). Absent
+     *  (prepare-time overlays, driver-API-only users like the display
+     *  adapter) → every declared controller is enabled, preserving the old
+     *  behavior. prj.conf ignores these. */
+    i2cUsedInstances?: readonly number[];
+    spiUsedInstances?: readonly number[];
+    uartUsedInstances?: readonly number[];
 }
 /**
  * Resolve the Kconfig symbol→value map for a prj.conf. Returns a Map preserving
@@ -32,3 +113,4 @@ export interface KconfigUsage {
  * are always present; driver symbols are usage-gated.
  */
 export declare function resolveKconfigFragments(usage: KconfigUsage, debug: boolean): Map<string, string>;
+export {};

package/dist/dt-config/kconfig.js

@@ -1,12 +1,24 @@
-// ---------------------------------------------------------------------------
-// Kconfig fragment resolver — extracts the prj.conf symbol logic
-//
-// Previously inline in scaffold.ts as token-scanning of the emitted source.
-// Formalized here as a typed, unit-testable function keyed off a usage-analysis
-// object (the same ctx.analysis.usesX flags the strategy uses). scaffold.ts
-// calls this instead of inlining the scan, keeping prj.conf generation honest
-// and testable.
-// ---------------------------------------------------------------------------
+import { SENSOR_PART_INFO } from '@typecad/hal';
+/**
+ * Apply the per-part Kconfig exceptions the generated catalog records, for
+ * exactly the parts the program constructs. Lines are CONFIG_<SYM>=<value>
+ * strings parsed into the map; a symbol the user set explicitly in
+ * zephyr.kconfig is left alone (scaffold.ts already skips user overrides for
+ * auto symbols, and Map.set idempotence covers the rest). The lookup is a
+ * parameter so tests can drive it with a synthetic catalog.
+ */
+export function applySensorKconfigExceptions(m, parts, lookup = SENSOR_PART_INFO) {
+    if (!parts)
+        return;
+    for (const sp of parts) {
+        for (const line of lookup[sp.part]?.kconfig ?? []) {
+            const eq = line.indexOf('=');
+            if (eq <= 0)
+                continue;
+            m.set(line.slice(0, eq), line.slice(eq + 1));
+        }
+    }
+}
 /**
  * Resolve the Kconfig symbol→value map for a prj.conf. Returns a Map preserving
  * insertion order (callers join with '\n'). Core GPIO + C++ + workqueue symbols
@@ -21,6 +33,22 @@ export function resolveKconfigFragments(usage, debug) {
     m.set('CONFIG_CONSOLE', 'y');
     if (usage.usesAdc)
         m.set('CONFIG_ADC', 'y');
+    // Sensors: only the umbrella — each in-tree driver is `default y` on its
+    // DT_HAS_<COMPAT>_ENABLED, so the overlay's child node enables the driver.
+    if (usage.usesSensor)
+        m.set('CONFIG_SENSOR', 'y');
+    // The rare driver that is NOT DT-default-on: the catalog records its
+    // Kconfig lines (from the driver's own Kconfig) and they are applied for
+    // exactly the parts the program constructs. Empty for every in-tree part
+    // today — this path is insurance for the next exception.
+    applySensorKconfigExceptions(m, usage.sensorParts);
+    // Float formatting: cbprintf builds float conversions only under
+    // FP_SUPPORT, which depends on the COMPLETE implementation — without these,
+    // %f silently prints garbage instead of the value.
+    if (usage.usesFloatFormat) {
+        m.set('CONFIG_CBPRINTF_COMPLETE', 'y');
+        m.set('CONFIG_CBPRINTF_FP_SUPPORT', 'y');
+    }
     if (usage.usesPwm)
         m.set('CONFIG_PWM', 'y');
     if (usage.usesDac)
@@ -29,8 +57,37 @@ export function resolveKconfigFragments(usage, debug) {
         m.set('CONFIG_I2C', 'y');
     if (usage.usesSpi)
         m.set('CONFIG_SPI', 'y');
+    // USB CDC-ACM serial: the "next" USB device stack + the CDC-ACM class.
+    // Symbol names verified against Zephyr 4.3 (subsys/usb/device_next/Kconfig):
+    //   - USB_DEVICE_STACK_NEXT is the new stack (selects UDC_DRIVER);
+    //     USB_DEVICE_STACK is the LEGACY stack — deprecated in 4.3 (selects
+    //     DEPRECATED) and its assignment is what trips the build.
+    //   - USBD_CDC_ACM_CLASS is the class (note the USBD_ prefix — a bare
+    //     CDC_ACM_CLASS is an undefined symbol). It depends on SERIAL +
+    //     DT_HAS_ZEPHYR_CDC_ACM_UART_ENABLED (the overlay's cdc-acm-uart node)
+    //     and selects UART_INTERRUPT_DRIVEN/RING_BUFFER itself; assigning it
+    //     keeps prj.conf explicit.
+    //   - UART_LINE_CTRL gates the driver's line_ctrl_get — usb.connected()
+    //     polls DTR through it.
+    if (usage.usesUsb) {
+        m.set('CONFIG_USB_DEVICE_STACK_NEXT', 'y');
+        m.set('CONFIG_USBD_CDC_ACM_CLASS', 'y');
+        m.set('CONFIG_UART_LINE_CTRL', 'y');
+        m.set('CONFIG_SERIAL', 'y');
+        // The device presents a serial-number string descriptor sourced from
+        // hwinfo (the SoC's unique ID). Without it Windows keys the CDC devnode
+        // on the physical USB port: replugs reuse stale nodes and repeated flash
+        // cycles wedge them into permanent "access denied" opens. A serial makes
+        // the instance path identity-based — stable across ports, immune to the
+        // port-keyed ghost pool.
+        m.set('CONFIG_HWINFO', 'y');
+    }
     if (usage.usesWdt)
         m.set('CONFIG_WATCHDOG', 'y');
+    // STM32: keep the debugger attachable in sleep/stop (see the shim's
+    // DBGMCU init — this covers the Zephyr-side DBG_STOP bit via LL headers).
+    if (usage.usesStm32DebugSleep)
+        m.set('CONFIG_STM32_ENABLE_DEBUG_SLEEP_STOP', 'y');
     // Hardware timers via the counter driver.
     if (usage.usesHwtimer)
         m.set('CONFIG_COUNTER', 'y');
@@ -87,24 +144,19 @@ export function resolveKconfigFragments(usage, debug) {
             m.set('CONFIG_SPIRAM_MODE_QUAD', 'y');
         }
     }
-    // deep_sleep_pin wake needs PM + PM_DEVICE.
-    if (usage.usesPower) {
-        m.set('CONFIG_PM', 'y');
-        m.set('CONFIG_PM_DEVICE', 'y');
-    }
     if (usage.usesWifi) {
         // Master networking switch — every CONFIG_NET_* symbol depends on NETWORKING
         // (without it, Kconfig silently forces them all to n).
         m.set('CONFIG_NETWORKING', 'y');
         m.set('CONFIG_WIFI', 'y');
-        m.set('CONFIG_WIFI_ESP32', 'y'); // ESP32-specific driver (sole WiFi target)
+        m.set('CONFIG_WIFI_ESP32', 'y'); // family-wide ESP32 driver (esp32/s3/c3/c6)
         m.set('CONFIG_NET_L2_ETHERNET', 'y');
         m.set('CONFIG_NET_IPV4', 'y');
         m.set('CONFIG_NET_UDP', 'y'); // transitive dep of NET_DHCPV4
         m.set('CONFIG_NET_DHCPV4', 'y');
         // NOT CONFIG_NET_CONFIG_SETTINGS: that runs net_config_init() at boot which
         // BLOCKS up to NET_CONFIG_INIT_TIMEOUT (default 30s) waiting for the iface
-        // to come up — but our shim brings the iface up itself in setup() (connect),
+        // to come up — but our shim brings the iface up itself in main() (connect),
         // so net_config waits the full 30s, then the dual management of the same
         // iface crashes the driver. Our shim owns connectivity (net_mgmt connect/
         // disconnect + conn_mgr monitor for L4), exactly like the standalone Zephyr
@@ -189,13 +241,26 @@ export function resolveKconfigFragments(usage, debug) {
         // server's RSA cert (rsa:2048) and is widely offered; add more ciphersuites
         // here to broaden server compatibility.
         m.set('CONFIG_MBEDTLS_CIPHERSUITE_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256', 'y');
+        // Ciphersuites only *depend on* X509_CRT_PARSE_C (they don't select it) —
+        // without it sockets_tls.c compiles out mbedtls_x509_crt_parse and every
+        // pinned-CA handshake fails with EPERM at connect (the insecure path
+        // skips verification, so it works either way).
+        m.set('CONFIG_MBEDTLS_X509_CRT_PARSE_C', 'y');
+        // KNOWN LIMITATION on this Zephyr tree: pinned-CA (verified TLS) fails at
+        // connect — the tf-psa-crypto mbedTLS needs a wider symbol matrix
+        // (RSA public-key parse + PEM/DER glue) than the single-ciphersuite
+        // select pulls in, and forcing the extra symbols regresses the insecure
+        // path. insecure() HTTPS is fully verified; caCert() chain verification
+        // stays open until the upstream matrix is mapped.
         // Handshake/protocol buffers allocate from the mbedTLS heap; MBEDTLS_HEAP_SIZE
         // must hold ~2x MBEDTLS_SSL_MAX_CONTENT_LEN plus working state. 65000 fits on
         // the ESP32; mbedTLS requires the full libc and PEM (not DER) cert format.
         m.set('CONFIG_MBEDTLS_ENABLE_HEAP', 'y');
-        m.set('CONFIG_MBEDTLS_HEAP_SIZE', '65000');
+        // 2x SSL_MAX_CONTENT_LEN record buffers + CA-chain parse state +
+        // handshake working memory. 65000 fit insecure-mode handshakes but the
+        // pinned-CA path (verification state) overflowed → EPERM at connect.
+        m.set('CONFIG_MBEDTLS_HEAP_SIZE', '100000');
         m.set('CONFIG_MBEDTLS_SSL_MAX_CONTENT_LEN', '16384');
-        m.set('CONFIG_MBEDTLS_PEM_CERTIFICATE_FORMAT', 'y');
         m.set('CONFIG_PSA_CRYPTO', 'y');
         m.set('CONFIG_REQUIRES_FULL_LIBC', 'y');
         // The http client + TLS handshake are stack-hungry; mirror the wifi bumps
@@ -219,6 +284,12 @@ export function resolveKconfigFragments(usage, debug) {
         m.set('CONFIG_NET_SOCKETS', 'y');
         m.set('CONFIG_MQTT_LIB', 'y');
         m.set('CONFIG_MQTT_LIB_TLS', 'y');
+        // The shim getaddrinfo-resolves the broker host — without the DNS
+        // resolver linked, getaddrinfo fails numeric AND hostname lookups with
+        // EAI_FAIL even while plain HTTP (which selects DNS via its own block)
+        // works.
+        m.set('CONFIG_DNS_RESOLVER', 'y');
+        m.set('CONFIG_DNS_SERVER_IP_ADDRESSES', 'y');
         // NET_MAX_CONTEXTS / NET_MAX_CONN: same exhaustion risk as HTTP — sequential
         // connections linger after close. Give the broker session + headroom.
         m.set('CONFIG_NET_MAX_CONTEXTS', '16');
@@ -230,10 +301,23 @@ export function resolveKconfigFragments(usage, debug) {
         m.set('CONFIG_MBEDTLS', 'y');
         m.set('CONFIG_MBEDTLS_BUILTIN', 'y');
         m.set('CONFIG_MBEDTLS_CIPHERSUITE_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256', 'y');
+        // Ciphersuites only *depend on* X509_CRT_PARSE_C (they don't select it) —
+        // without it sockets_tls.c compiles out mbedtls_x509_crt_parse and every
+        // pinned-CA handshake fails with EPERM at connect (the insecure path
+        // skips verification, so it works either way).
+        m.set('CONFIG_MBEDTLS_X509_CRT_PARSE_C', 'y');
+        // KNOWN LIMITATION on this Zephyr tree: pinned-CA (verified TLS) fails at
+        // connect — the tf-psa-crypto mbedTLS needs a wider symbol matrix
+        // (RSA public-key parse + PEM/DER glue) than the single-ciphersuite
+        // select pulls in, and forcing the extra symbols regresses the insecure
+        // path. insecure() HTTPS is fully verified; caCert() chain verification
+        // stays open until the upstream matrix is mapped.
         m.set('CONFIG_MBEDTLS_ENABLE_HEAP', 'y');
-        m.set('CONFIG_MBEDTLS_HEAP_SIZE', '65000');
+        // 2x SSL_MAX_CONTENT_LEN record buffers + CA-chain parse state +
+        // handshake working memory. 65000 fit insecure-mode handshakes but the
+        // pinned-CA path (verification state) overflowed → EPERM at connect.
+        m.set('CONFIG_MBEDTLS_HEAP_SIZE', '100000');
         m.set('CONFIG_MBEDTLS_SSL_MAX_CONTENT_LEN', '16384');
-        m.set('CONFIG_MBEDTLS_PEM_CERTIFICATE_FORMAT', 'y');
         m.set('CONFIG_PSA_CRYPTO', 'y');
         m.set('CONFIG_REQUIRES_FULL_LIBC', 'y');
         m.set('CONFIG_NET_TX_STACK_SIZE', '2048');
@@ -271,19 +355,24 @@ export function resolveKconfigFragments(usage, debug) {
         m.set('CONFIG_FLASH_MAP', 'y');
         m.set('CONFIG_FILE_SYSTEM', 'y');
         m.set('CONFIG_FILE_SYSTEM_LITTLEFS', 'y');
+        // fs_mkfs (the lazy first-use format in the shim) is gated behind this —
+        // without it the mount path links fine but the format call is undefined.
+        m.set('CONFIG_FILE_SYSTEM_MKFS', 'y');
     }
     // usesUart: the board enables the console UART by default; the overlay (not
     // Kconfig) is where a UART node would be enabled, so no symbol here.
     // Random: <zephyr/random/random.h> sys_rand_get is backed by the random
-    // generator subsystem. CONFIG_RANDOM_GENERATOR is the umbrella that selects a
-    // working backend for the board (nRF52840 → hardware RNG via the entropy
-    // driver; QEMU/host → the test generator). CONFIG_ENTROPY_GENERATOR is its
-    // hard dependency on hardware targets. Both default on for most boards, but
-    // setting them explicitly keeps the symbol set honest and survives a board
-    // whose defconfig leaves them off.
+    // generator subsystem's RNG_GENERATOR_CHOICE. There is no umbrella symbol —
+    // CONFIG_RANDOM_GENERATOR is a phantom in 4.x (assigning an undefined symbol
+    // aborts the build). The choice defaults to the entropy-device generator
+    // when the board has a driver (ENTROPY_HAS_DRIVER: nRF52840, ESP32, …);
+    // RNG-less SoCs (STM32F411 has no hardware RNG) need
+    // CONFIG_TEST_RANDOM_GENERATOR to unlock the timer-clock fallback, which
+    // the choice then picks by default. Setting both keys gets the best
+    // available source per board.
     if (usage.usesRandom) {
         m.set('CONFIG_ENTROPY_GENERATOR', 'y');
-        m.set('CONFIG_RANDOM_GENERATOR', 'y');
+        m.set('CONFIG_TEST_RANDOM_GENERATOR', 'y');
     }
     // System workqueue — bumped for worker-offload AND timer callbacks. The
     // workqueue itself is unconditionally built (no CONFIG_SYSTEM_WORKQUEUE symbol