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

package/src/dt-config/custom-board.ts

@@ -0,0 +1,325 @@
+// ---------------------------------------------------------------------------
+// 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 type { ZephyrChipDescriptor } from '../chips/types.js';
+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: string): string {
+  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: string): string {
+  return name.toUpperCase();
+}
+
+/** Generated-board file set, all under `<projectRoot>/boards/typecad/<name>/`. */
+export interface GeneratedCustomBoard {
+  /** Absolute directory of the generated board. */
+  dir: string;
+  /** The sanitized board name (the `west build -b` argument). */
+  name: string;
+  /** Whether any file changed (idempotent regeneration signal). */
+  changed: boolean;
+}
+
+/**
+ * Emit the custom board for a chip whose descriptor carries `customBoard`
+ * silicon data. No-op (returns null) when the chip has no generator inputs —
+ * board-resolved chips don't need one.
+ */
+export function generateCustomBoard(
+  projectRoot: string,
+  chip: ZephyrChipDescriptor,
+  rawName: string,
+): GeneratedCustomBoard | null {
+  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: string[] = [
+    '// 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: number): { label: string; bit: number } | undefined => {
+    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<string, { n: string; tokens: string[]; complete: boolean }>();
+    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/src/dt-config/kconfig.ts

@@ -1,3 +1,33 @@
+import { SENSOR_PART_INFO } from '@typecad/hal';
+
+/** 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 function applySensorKconfigExceptions(
+  m: Map<string, string>,
+  parts: readonly { part: string }[] | undefined,
+  lookup: Readonly<Record<string, SensorKconfigSource>> = SENSOR_PART_INFO,
+): void {
+  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));
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Kconfig fragment resolver — extracts the prj.conf symbol logic
 //
@@ -17,21 +47,47 @@ 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';
@@ -40,12 +96,28 @@ export interface KconfigUsage {
    *  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[];
 }
 
 /**
@@ -66,11 +138,54 @@ export function resolveKconfigFragments(
   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) m.set('CONFIG_DAC', 'y');
   if (usage.usesI2c) 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');
   if (usage.usesDisplay) {
@@ -124,11 +239,6 @@ export function resolveKconfigFragments(
       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).
@@ -141,7 +251,7 @@ export function resolveKconfigFragments(
     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
@@ -226,13 +336,26 @@ export function resolveKconfigFragments(
     // 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
@@ -255,6 +378,12 @@ export function resolveKconfigFragments(
     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');
@@ -266,10 +395,23 @@ export function resolveKconfigFragments(
     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');
@@ -306,19 +448,24 @@ export function resolveKconfigFragments(
     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