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

package/dist/lowering/usb.js

@@ -0,0 +1,206 @@
+// ---------------------------------------------------------------------------
+// USB CDC-ACM serial lowering — Zephyr "next" USB device stack
+//
+// A CDC-ACM instance (cdc_acm_uart<N>, composed in the generated overlay as a
+// child of the UDC controller node) registers as a UART-class device, so the
+// lowering drives it with the plain uart_* API — the same per-byte poll_out
+// loops as lowering/uart.ts. The differences from a hardware UART:
+//   - usb.begin must start the device stack (usbdDeviceLines' one-shot
+//     __tc_usbd_start) before the port carries traffic;
+//   - "connected" is a real query (DTR line ctrl), not a constant;
+//   - baud is a line-coding hint — recorded, but CDC has no wire baud.
+//
+// If the chip descriptor declares no `usb`, every op throws with a clear
+// "board does not expose USB" message (the diagnostic contract the framework
+// manifest's board-gated support entry promises).
+// ---------------------------------------------------------------------------
+import { parseControllerIndex } from './util.js';
+import { renderWrite } from './uart.js';
+/** Render a HAL field: pass through (already rendered by the resolver). */
+function s(v) {
+    return String(v);
+}
+/** The C variable prefix for a CDC instance's state. */
+function prefix(idx) {
+    return `__tc_usb${idx}`;
+}
+/** Instance N resolves to the DT nodelabel the overlay generator emits. */
+function nodeLabel(idx) {
+    return `cdc_acm_uart${idx}`;
+}
+/**
+ * Emit the shared USB device context (USBD_DEVICE_DEFINE + string/config
+ * descriptors + configuration + class registration + usbd_enable). Emitted
+ * ONCE per program when the chip declares `usb` — the next stack has one
+ * device context on the UDC controller, regardless of how many CDC instances
+ * hang off it.
+ *
+ * VID/PID default to the Zephyr-project testing IDs (0x2fe3/0x0001); a board
+ * overrides via `zephyr.usb.vid`/`zephyr.usb.pid`. Full-speed only — the
+ * boards this framework targets (STM32 OTG_FS, nRF USBD) are FS controllers,
+ * and the HS path would need a second USBD_CONFIGURATION_DEFINE.
+ *
+ * Symbol/API shapes verified against Zephyr 4.3:
+ * subsys/usb/device_next/Kconfig, include/zephyr/usb/usbd.h, and
+ * samples/subsys/usb/common/sample_usbd_init.c.
+ */
+export function usbdDeviceLines(chip) {
+    if (!chip.usb)
+        return [];
+    const vid = chip.usb.vid ?? '0x2fe3';
+    const pid = chip.usb.pid ?? '0x0001';
+    // 1200-baud touch-to-reset (BOSSA-bootloader boards): a usbd message
+    // callback that reboots into the bootloader when the host sets the CDC
+    // baud rate to 1200. Zephyr's CDC-ACM class publishes
+    // USBD_MSG_CDC_ACM_LINE_CODING on every host SET_LINE_CODING (the message
+    // carries the CDC uart device; its line coding is readable via
+    // uart_cfg_get). The reboot writes the bootloader's stay-resident magic
+    // (Arduino SAMD scheme: the bootloader checks the last word of SRAM after
+    // reset) so the board waits in the bootloader instead of booting the app.
+    const touch = chip.usb.touchReset;
+    const touchLines = touch
+        ? [
+            `// 1200-baud touch-to-reset: reboot into the bootloader (flag 0x${touch.magic.toString(16)} @ 0x${touch.flagAddress.toString(16)}).`,
+            'static void __tc_usbd_msg_cb(struct usbd_context* ctx, const struct usbd_msg* msg) {',
+            '    (void)ctx;',
+            '    if (msg->type != USBD_MSG_CDC_ACM_LINE_CODING) { return; }',
+            '    struct uart_config __tc_cfg;',
+            '    if (uart_config_get(msg->dev, &__tc_cfg) == 0 && __tc_cfg.baudrate == 1200) {',
+            '        // Delay the reboot so the host touch (which applies 1200 as part',
+            '        // of opening the port) can close its handle first — resetting under',
+            '        // an open host handle can wedge the Windows usbser driver and block',
+            '        // re-enumeration until a physical replug.',
+            '        k_msleep(250);',
+            `        *(volatile uint32_t*)0x${touch.flagAddress.toString(16)} = 0x${touch.magic.toString(16)};`,
+            '        NVIC_SystemReset();',
+            '    }',
+            '}',
+        ]
+        : [];
+    const touchRegister = touch
+        ? ['    usbd_msg_register_cb(&__tc_usbd, __tc_usbd_msg_cb);']
+        : [];
+    return [
+        '// CUTTLEFISH_USBD_BEGIN',
+        'USBD_DEVICE_DEFINE(__tc_usbd,',
+        `    DEVICE_DT_GET(DT_NODELABEL(${chip.usb.controller})),`,
+        `    ${vid}, ${pid});`,
+        'USBD_DESC_LANG_DEFINE(__tc_usbd_lang);',
+        'USBD_DESC_MANUFACTURER_DEFINE(__tc_usbd_mfr, "typecad");',
+        'USBD_DESC_PRODUCT_DEFINE(__tc_usbd_product, "cuttlefish app");',
+        // Serial number from hwinfo: Windows keys USB devnodes without a serial
+        // on the physical port, so flash-cycle re-enumerations reuse stale
+        // port-keyed nodes (the "access denied" open wedge). Identity-based
+        // instance paths are stable across ports and never hit that pool.
+        'USBD_DESC_SERIAL_NUMBER_DEFINE(__tc_usbd_sn);',
+        'USBD_DESC_CONFIG_DEFINE(__tc_usbd_cfg_desc, "cuttlefish");',
+        'USBD_CONFIGURATION_DEFINE(__tc_usbd_cfg, 0, 250, &__tc_usbd_cfg_desc);',
+        'static bool __tc_usbd_started = false;',
+        ...touchLines,
+        'static void __tc_usbd_start(void) {',
+        '    if (__tc_usbd_started) { return; }',
+        '    __tc_usbd_started = true;',
+        '    int err = usbd_add_descriptor(&__tc_usbd, &__tc_usbd_lang);',
+        '    if (err != 0) { printk("cuttlefish usb: lang descriptor failed: %d\\n", err); return; }',
+        '    err = usbd_add_descriptor(&__tc_usbd, &__tc_usbd_sn);',
+        '    if (err != 0) { printk("cuttlefish usb: serial descriptor failed: %d\\n", err); return; }',
+        '    err = usbd_add_descriptor(&__tc_usbd, &__tc_usbd_mfr);',
+        '    if (err != 0) { printk("cuttlefish usb: manufacturer descriptor failed: %d\\n", err); return; }',
+        '    err = usbd_add_descriptor(&__tc_usbd, &__tc_usbd_product);',
+        '    if (err != 0) { printk("cuttlefish usb: product descriptor failed: %d\\n", err); return; }',
+        '    err = usbd_add_configuration(&__tc_usbd, USBD_SPEED_FS, &__tc_usbd_cfg);',
+        '    if (err != 0) { printk("cuttlefish usb: add configuration failed: %d\\n", err); return; }',
+        '    err = usbd_register_all_classes(&__tc_usbd, USBD_SPEED_FS, 1, NULL);',
+        '    if (err != 0) { printk("cuttlefish usb: register classes failed: %d\\n", err); return; }',
+        // Registered before usbd_init so no line-coding event can be missed.
+        ...touchRegister,
+        // usbd_init builds the descriptor tables from the registered
+        // configuration/classes and marks the context initialized — usbd_enable
+        // refuses with -EPERM ("not initialized") without it (sample_usbd_init.c
+        // calls it between setup and enable).
+        '    err = usbd_init(&__tc_usbd);',
+        '    if (err != 0) { printk("cuttlefish usb: init failed: %d\\n", err); return; }',
+        // Boards with VBUS detection start on the VBUS event in the Zephyr
+        // sample, via a message callback we do not register; enabling
+        // unconditionally (and reporting the error) is the sample's own path
+        // for boards without detection (STM32 OTG_FS).
+        '    err = usbd_enable(&__tc_usbd);',
+        '    if (err != 0) { printk("cuttlefish usb: enable failed: %d\\n", err); return; }',
+        '    printk("cuttlefish usb: device enabled\\n");',
+        '}',
+        '// CUTTLEFISH_USBD_END',
+    ];
+}
+/**
+ * Emit the per-instance CDC device + init helper. Called from shimLines when
+ * the program uses USB and the chip declares `usb`; must be paired with one
+ * usbdDeviceLines() block. The init starts the device stack (guarded) and
+ * applies the line coding.
+ */
+export function usbInitLines(chip, instanceIndex) {
+    if (!chip.usb)
+        return [];
+    const p = prefix(instanceIndex);
+    const dev = `${p}_dev`;
+    return [
+        '// CUTTLEFISH_USB_BEGIN',
+        `static const struct device* ${dev} = DEVICE_DT_GET(DT_NODELABEL(${nodeLabel(instanceIndex)}));`,
+        `static void ${p}_init(void) {`,
+        `    __tc_usbd_start();   // CDC line coding is the host's business`,
+        `}`,
+        '// CUTTLEFISH_USB_END',
+    ];
+}
+/** Throw the board-capability diagnostic. Centralized so every op reads identically. */
+function requireUsb(chip, op) {
+    if (!chip.usb) {
+        throw new Error(`framework-zephyr: \`${op}\` needs a USB device stack, but this board's chip data declares no \`zephyr.usb\` ` +
+            `(controller + cdcInstances). Boards whose Zephyr DTS has no enabled UDC controller node ` +
+            `(zephyr_udc0) cannot provide USB CDC serial.`);
+    }
+}
+/**
+ * Resolve a HAL usb.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ */
+export function lowerUsb(op, chip) {
+    requireUsb(chip, op.operation);
+    const o = op;
+    const idx = parseControllerIndex(o.port);
+    if (chip.usb && idx >= chip.usb.cdcInstances) {
+        throw new Error(`framework-zephyr: usb port "${o.port}" (instance ${idx}) is out of range — this board composes ` +
+            `${chip.usb.cdcInstances} CDC-ACM instance(s) (USB0..USB${chip.usb.cdcInstances - 1}).`);
+    }
+    const p = prefix(idx);
+    const dev = `${p}_dev`;
+    switch (op.operation) {
+        case 'usb.begin':
+            return { code: `${p}_init();` };
+        case 'usb.wait_ready': {
+            // Bounded DTR poll, sliced in the shim-side expression (no user-code
+            // busy loop). timeoutMs 0 = wait forever.
+            return { expression: `({ bool __ok = false; uint32_t __t = 0U; while (true) { uint32_t __dtr = 0U; if ((uart_line_ctrl_get(${dev}, UART_LINE_CTRL_DTR, &__dtr) == 0) && (__dtr != 0U)) { __ok = true; break; } if ((${s(o.timeoutMs ?? 0)}) != 0 && __t >= (uint32_t)(${s(o.timeoutMs ?? 0)})) { break; } k_msleep(10); __t += 10U; } __ok; })` };
+        }
+        case 'usb.end':
+            // CDC has no per-port disable short of tearing down the device stack
+            // (which would drop every other instance); make end observable but safe.
+            return { code: `(void)${dev};` };
+        case 'usb.print':
+            return { code: renderWrite(dev, o.value, false) };
+        case 'usb.println':
+            return { code: renderWrite(dev, o.value, true) };
+        case 'usb.read':
+            // Same poll semantics as uart.read: the byte or -1 if none available.
+            return { expression: `({ unsigned char __b = 0; (uart_poll_in(${dev}, &__b) == 0) ? (int)__b : -1; })` };
+        case 'usb.available':
+            // uart_poll_in reports only "one byte ready" and probing would drain it;
+            // same honest limitation as uart.available.
+            return { expression: '(0)' };
+        case 'usb.connected':
+            // DTR asserted = the host actually opened the port.
+            return { expression: `({ uint32_t __dtr = 0; (uart_line_ctrl_get(${dev}, UART_LINE_CTRL_DTR, &__dtr) == 0) && (__dtr != 0); })` };
+        default:
+            throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+                `Open an issue or use rawCpp() to emit it manually.`);
+    }
+}

package/dist/lowering/wdt.d.ts

@@ -9,7 +9,7 @@ export declare function wdtInitLines(chip: ZephyrChipDescriptor): string[];
  * Resolve a HAL wdt.* op to Zephyr C++.
  * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
  */
-export declare function lowerWdt(op: HALOpIR): {
+export declare function lowerWdt(op: HALOpIR, chip: ZephyrChipDescriptor): {
     code?: string;
     expression?: string;
 };

package/dist/lowering/wdt.js

@@ -10,12 +10,15 @@
 // constant or a number; we parse to ms in the lowering.
 // ---------------------------------------------------------------------------
 /** Parse a HAL wdt timeout ("250ms", WDTO_2S, or a bare number) to ms.
- *  Tolerates undefined (the manifest validator's probe sends a minimal op). */
+ *  Tolerates undefined (the manifest validator's probe sends a minimal op)
+ *  and quote-wrapped strings (resolveSemanticArg can hand the literal's
+ *  quoted source text through). */
 function timeoutToMs(timeout) {
     if (typeof timeout === 'number')
         return timeout;
     if (!timeout)
         return 1000; // default 1s when absent (e.g. the validator probe)
+    timeout = timeout.replace(/^['"]|['"]$/g, '');
     // Arduino WDTO_* constants.
     const wdto = {
         WDTO_15MS: 15, WDTO_30MS: 30, WDTO_60MS: 60, WDTO_120MS: 120,
@@ -51,13 +54,20 @@ export function wdtInitLines(chip) {
  * Resolve a HAL wdt.* op to Zephyr C++.
  * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
  */
-export function lowerWdt(op) {
+export function lowerWdt(op, chip) {
     const o = op;
+    // No watchdog node on this target (e.g. SAM D21 — Zephyr's samd21 dtsi
+    // exposes none). Comment + (in profileDiagnostics) a clear error, mirroring
+    // the hwtimer unavailable pattern. Without this the wdt_* calls reference
+    // the shim vars that wdtInitLines (gated on chip.wdt) never emitted.
+    if (!chip.wdt) {
+        return { code: `/* ${op.operation}: no watchdog device on ${chip.id} */` };
+    }
     switch (op.operation) {
-        case 'wdt.enable': {
-            const ms = timeoutToMs(o.timeout);
-            // Install a timeout then set up the watchdog. Both are idempotent via
-            // the static flags. WDT_FLAG_RESET_CPU_CORE = full reset on timeout.
+        case 'wdt.setup': {
+            // Same install+setup sequence as wdt.enable, but the timeout is a
+            // plain ms number from construction — no WDTO_*/string parsing.
+            const ms = Number(o.timeoutMs ?? 1000);
             return {
                 code: [
                     `if (!__tc_wdt_setup_done) {`,
@@ -69,7 +79,7 @@ export function lowerWdt(op) {
                 ].join(' '),
             };
         }
-        case 'wdt.reset':
+        case 'wdt.feed':
             return { code: `if (__tc_wdt_channel >= 0) { wdt_feed(__tc_wdt_dev, __tc_wdt_channel); }` };
         case 'wdt.disable':
             return { code: `wdt_disable(__tc_wdt_dev); __tc_wdt_setup_done = false;` };

package/dist/lowering/wifi.d.ts

@@ -5,8 +5,9 @@ import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
  *
  * State is driven by two net_mgmt event handlers:
  *  - L4 connectivity (NET_EVENT_L4_CONNECTED/DISCONNECTED) → connected flag.
- *    This reflects IP connectivity (post-DHCP), not just the WiFi link — the
- *    events are raised by conn_mgr's monitoring layer (conn_mgr_monitor.c).
+ *    This reflects IP connectivity (post-DHCP, or right after static IPv4
+ *    facts are applied) — the events are raised by conn_mgr's monitoring
+ *    layer (conn_mgr_monitor.c).
  *  - WiFi scan (NET_EVENT_WIFI_SCAN_RESULT/SCAN_DONE) → scan_results pool.
  */
 export declare function wifiInitLines(): string[];

package/dist/lowering/wifi.js

@@ -1,7 +1,7 @@
 // ---------------------------------------------------------------------------
-// WiFi lowering — net_mgmt (connect/scan/radio) + conn_mgr monitor (L4 events)
+// WiFi lowering — net_mgmt (join/scan/radio) + conn_mgr monitor (L4 events)
 //
-// Hybrid: the WiFi connect/disconnect/scan/radio-query requests go directly
+// Hybrid: the WiFi join/disconnect/scan/radio-query requests go directly
 // through net_mgmt + wifi_mgmt.h (NET_REQUEST_WIFI_CONNECT/DISCONNECT/SCAN/...),
 // taking the iface admin-up with net_if_up first. IP-level connectivity is
 // still signaled by conn_mgr's monitoring layer (conn_mgr_monitor.c raises
@@ -23,8 +23,9 @@ function s(v) {
  *
  * State is driven by two net_mgmt event handlers:
  *  - L4 connectivity (NET_EVENT_L4_CONNECTED/DISCONNECTED) → connected flag.
- *    This reflects IP connectivity (post-DHCP), not just the WiFi link — the
- *    events are raised by conn_mgr's monitoring layer (conn_mgr_monitor.c).
+ *    This reflects IP connectivity (post-DHCP, or right after static IPv4
+ *    facts are applied) — the events are raised by conn_mgr's monitoring
+ *    layer (conn_mgr_monitor.c).
  *  - WiFi scan (NET_EVENT_WIFI_SCAN_RESULT/SCAN_DONE) → scan_results pool.
  */
 export function wifiInitLines() {
@@ -35,12 +36,12 @@ export function wifiInitLines() {
         `// ── core (always needed when wifi.* is used) ────────────────────────────`,
         `// CUTTLEFISH_WIFI_CORE_BEGIN`,
         `// WiFi event callback signature (wifi.on_event). One slot per supported`,
-        `// event — a second registration overwrites the first (matches framework-esp32).`,
+        `// event — a second registration overwrites the first.`,
         `typedef void (*__tc_wifi_cb_t)(void);`,
         ``,
         `// WiFi state. connected reflects IP connectivity (L4), not just link —`,
-        `// connect takes the iface admin-up (net_if_up) and conn_mgr_monitor raises`,
-        `// the L4 event once DHCP completes. is_connected polls this flag.`,
+        `// join takes the iface admin-up (net_if_up) and conn_mgr_monitor raises`,
+        `// the L4 event once DHCP completes (or the static-IPv4 facts are applied).`,
         `static struct {`,
         `    bool inited;              // net_mgmt handlers registered + iface resolved`,
         `    bool connected;           // set by NET_EVENT_L4_CONNECTED/DISCONNECTED`,
@@ -71,15 +72,15 @@ export function wifiInitLines() {
         `        __tc_wifi.connected = true;`,
         `    } else if (mgmt_event == NET_EVENT_L4_DISCONNECTED) {`,
         `        __tc_wifi.connected = false;`,
-        `        // Defer on_disconnect via k_work_submit so the user callback (which`,
-        `        // typically calls connectAsync) runs outside the net_mgmt event`,
-        `        // chain. Calling NET_REQUEST_WIFI_CONNECT from within the disconnect`,
+        `        // Defer on_drop via k_work_submit so the user callback (which`,
+        `        // typically re-joins) runs outside the net_mgmt event chain.`,
+        `        // Calling NET_REQUEST_WIFI_CONNECT from within the disconnect`,
         `        // callback causes re-entrancy that prevents re-association.`,
         `        if (__tc_wifi.on_disconnect != nullptr) {`,
         `            (void)k_work_submit(&__tc_wifi.disconnect_work);`,
         `        }`,
         `    } else if (mgmt_event == NET_EVENT_IPV4_ADDR_ADD) {`,
-        `        // DHCP assigned an IPv4 address — the true "got IP" signal. Fires`,
+        `        // An IPv4 address was assigned — the true "got IP" signal. Fires`,
         `        // after NET_EVENT_L4_CONNECTED on a successful DHCP join.`,
         `        if (__tc_wifi.on_connect != nullptr) __tc_wifi.on_connect();`,
         `    } else if (mgmt_event == NET_EVENT_WIFI_SCAN_RESULT) {`,
@@ -129,8 +130,8 @@ export function wifiInitLines() {
         `// duration. Each wait slice sleeps 20ms and, in the entry TU of a UI build`,
         `// (the only TU carrying the ui_tick definition), pumps one frame so`,
         `// animations and touch stay live during the wait. Constraint: do NOT call`,
-        `// blocking wifi waits from inside UI event handlers — that re-enters`,
-        `// ui_tick mid-tick; use wifi.connect_start + wifi.is_connected there.`,
+        `// join() from inside UI event handlers — that re-enters ui_tick mid-tick;`,
+        `// use joinStart() + linked() there.`,
         `#ifdef CUTTLEFISH_ENTRY_UI_TU`,
         `static void ui_tick(uint16_t deltaMs);   // defined by the UI runtime header`,
         `#endif`,
@@ -147,17 +148,20 @@ export function wifiInitLines() {
         `}`,
         `// CUTTLEFISH_WIFI_CORE_END`,
         ``,
-        `// ── connect / disconnect (net_mgmt — conn_mgr monitor supplies L4 events) ─`,
+        `// ── join / leave (net_mgmt — conn_mgr monitor supplies L4 events) ────────`,
         `// CUTTLEFISH_WIFI_CONNECT_BEGIN`,
         `// SSID/PSK are staged into static buffers (wifi_connect_req_params.ssid/psk`,
         `// are const uint8_t* — they point at caller-owned storage that must outlive`,
         `// the request), then net_if_up takes the iface admin-up and NET_REQUEST_WIFI_CONNECT`,
-        `// is issued. conn_mgr_monitor raises the L4 event once DHCP completes.`,
+        `// is issued with the station's construction facts (security/band/channel).`,
+        `// conn_mgr_monitor raises the L4 event once DHCP completes.`,
         `static struct wifi_connect_req_params __tc_wifi_conn_params;`,
         `static uint8_t __tc_wifi_ssid_buf[33];    // SSID ≤32 + slack`,
         `static uint8_t __tc_wifi_psk_buf[64];     // PSK ≤63 + slack`,
         ``,
-        `static void __tc_wifi_stage_creds(const char* ssid, const char* password) {`,
+        `static void __tc_wifi_stage_creds(const char* ssid, const char* password,`,
+        `                                  enum wifi_security_type security, int32_t channel,`,
+        `                                  enum wifi_frequency_bands band) {`,
         `    __tc_wifi_ensure_init();`,
         `    if (__tc_wifi.iface == nullptr) return;`,
         `    uint32_t ssid_len = strlen(ssid);`,
@@ -174,15 +178,16 @@ export function wifiInitLines() {
         `    } else {`,
         `        __tc_wifi_conn_params.psk_length = 0U;`,
         `    }`,
-        `    __tc_wifi_conn_params.security = WIFI_SECURITY_TYPE_PSK;`,
-        `    __tc_wifi_conn_params.channel = WIFI_CHANNEL_ANY;`,
-        `    __tc_wifi_conn_params.band = WIFI_FREQ_BAND_2_4_GHZ;`,
-        `    // Stage the connection request (wifi_connect). The L4 handler sets`,
-        `    // \`connected\` once DHCP completes.`,
+        `    __tc_wifi_conn_params.security = security;`,
+        `    __tc_wifi_conn_params.channel = (channel > 0) ? static_cast<uint8_t>(channel) : WIFI_CHANNEL_ANY;`,
+        `    __tc_wifi_conn_params.band = band;`,
         `    (void)net_mgmt(NET_REQUEST_WIFI_CONNECT, __tc_wifi.iface,`,
         `                   &__tc_wifi_conn_params, sizeof(__tc_wifi_conn_params));`,
         `}`,
         ``,
+        `// joinStart(): stage the association without waiting — poll linked() or`,
+        `// await join() in an async function (the async machinery splits it into`,
+        `// this + the is_connected poll).`,
         `static void __tc_wifi_connect_start(const char* ssid, const char* password) {`,
         `    __tc_wifi_ensure_init();`,
         `    if (__tc_wifi.iface == nullptr) {`,
@@ -190,21 +195,58 @@ export function wifiInitLines() {
         `        return;`,
         `    }`,
         `    net_if_up(__tc_wifi.iface);`,
-        `    __tc_wifi_stage_creds(ssid, password);`,
+        `    __tc_wifi_stage_creds(ssid, password, WIFI_SECURITY_TYPE_PSK, 0, WIFI_FREQ_BAND_2_4_GHZ);`,
         `    __tc_wifi.connected = false;`,
         `    printk("tc-wifi: connecting to %s\\n", ssid);`,
         `}`,
         ``,
-        `// CUTTLEFISH_WIFI_CONNECT_BLOCKING_BEGIN`,
-        `static void __tc_wifi_connect(const char* ssid, const char* password, int32_t timeout_ms) {`,
-        `    __tc_wifi_connect_start(ssid, password);`,
-        `    // Block until the L4 handler signals connectivity or the deadline passes.`,
-        `    // 20ms slices let __tc_wifi_wait_slice pump the UI between polls.`,
+        `// join(): the thin station verb — associate from the construction facts,`,
+        `// apply the optional static-IPv4 / power-save facts, then bounded-wait for`,
+        `// IP connectivity. Returns whether the link came up (boolean, no exceptions).`,
+        `static bool __tc_wifi_join(const char* ssid, const char* psk,`,
+        `                           enum wifi_security_type security, int32_t channel,`,
+        `                           enum wifi_frequency_bands band, int32_t timeout_ms,`,
+        `                           bool ps_off, const char* ip_addr, const char* gateway,`,
+        `                           const char* netmask) {`,
+        `    __tc_wifi_ensure_init();`,
+        `    if (__tc_wifi.iface == nullptr) {`,
+        `        printk("tc-wifi: no WiFi iface found\\n");`,
+        `        return false;`,
+        `    }`,
+        `    net_if_up(__tc_wifi.iface);`,
+        `    __tc_wifi_stage_creds(ssid, psk, security, channel, band);`,
+        `    __tc_wifi.connected = false;`,
+        `    if (ip_addr != nullptr && gateway != nullptr && netmask != nullptr) {`,
+        `        // Static IPv4 facts: stop DHCP, configure the address manually. The`,
+        `        // addr-add raises the events conn_mgr_monitor listens for, so`,
+        `        // \`connected\` flips without a lease.`,
+        `        net_dhcpv4_stop(__tc_wifi.iface);`,
+        `        struct in_addr addr = { 0 }, gw = { 0 }, mask = { 0 };`,
+        `        if (net_addr_pton(AF_INET, ip_addr, &addr) == 0`,
+        `            && net_addr_pton(AF_INET, netmask, &mask) == 0`,
+        `            && net_addr_pton(AF_INET, gateway, &gw) == 0) {`,
+        `            (void)net_if_ipv4_addr_add(__tc_wifi.iface, &addr, NET_ADDR_MANUAL, 0);`,
+        `            // set_netmask() is __deprecated on Zephyr >= 4.3 — the`,
+        `            // by-addr form carries the prefix it belongs to.`,
+        `            (void)net_if_ipv4_set_netmask_by_addr(__tc_wifi.iface, &addr, &mask);`,
+        `            (void)net_if_ipv4_set_gw(__tc_wifi.iface, &gw);`,
+        `        } else {`,
+        `            printk("tc-wifi: bad static ipv4 facts, falling back to DHCP\\n");`,
+        `            net_dhcpv4_start(__tc_wifi.iface);`,
+        `        }`,
+        `    }`,
+        `    if (ps_off) {`,
+        `        // WiFi.PS_OFF — disable the radio's modem sleep (wifi_ps_params).`,
+        `        struct wifi_ps_params ps = {};   // value-init: first member is an enum`,
+        `        ps.enabled = WIFI_PS_DISABLED;`,
+        `        (void)net_mgmt(NET_REQUEST_WIFI_PS_CONFIG, __tc_wifi.iface, &ps, sizeof(ps));`,
+        `    }`,
+        `    printk("tc-wifi: joining %s\\n", ssid);`,
         `    int32_t waited = 0;`,
         `    while (!__tc_wifi.connected && waited < timeout_ms) { __tc_wifi_wait_slice(20); waited += 20; }`,
-        `    printk("tc-wifi: connect %s after %dms\\n", __tc_wifi.connected ? "ok" : "timeout", waited);`,
+        `    printk("tc-wifi: join %s after %dms\\n", __tc_wifi.connected ? "ok" : "timeout", waited);`,
+        `    return __tc_wifi.connected;`,
         `}`,
-        `// CUTTLEFISH_WIFI_CONNECT_BLOCKING_END`,
         ``,
         `static void __tc_wifi_disconnect(void) {`,
         `    __tc_wifi_ensure_init();`,
@@ -217,10 +259,6 @@ export function wifiInitLines() {
         ``,
         `// ── status / radio queries ───────────────────────────────────────────────`,
         `// CUTTLEFISH_WIFI_QUERY_BEGIN`,
-        `static int32_t __tc_wifi_status(void) {`,
-        `    return __tc_wifi.connected ? 3 : 0;   // 3=Connected in the HAL status enum`,
-        `}`,
-        ``,
         `static const char* __tc_wifi_local_ip(void) {`,
         `    __tc_wifi_ensure_init();`,
         `    if (__tc_wifi.iface == nullptr || !__tc_wifi.connected) return "0.0.0.0";`,
@@ -247,7 +285,7 @@ export function wifiInitLines() {
         `    struct wifi_iface_status status = { 0 };`,
         `    (void)net_mgmt(NET_REQUEST_WIFI_IFACE_STATUS, __tc_wifi.iface,`,
         `                   &status, sizeof(status));`,
-        `    // Pack the 6 MAC bytes (status.bssid) into a uint64 (HAL returns a number).`,
+        `    // Pack the 6 MAC bytes (status.bssid) into a uint64 (the HAL returns a number).`,
         `    uint64_t m = 0;`,
         `    for (int32_t b = 0; b < 6; b++) { m = (m << 8) | static_cast<uint64_t>(status.bssid[b]); }`,
         `    return m;`,
@@ -291,61 +329,12 @@ export function wifiInitLines() {
         `}`,
         `// CUTTLEFISH_WIFI_SCAN_END`,
         ``,
-        `// ── config ───────────────────────────────────────────────────────────────`,
-        `// CUTTLEFISH_WIFI_CONFIG_BEGIN`,
-        `// NOTE: wifi.set_tx_power is intentionally NOT lowered here. The Zephyr esp32`,
-        `// WiFi driver owns esp_wifi_start/esp_wifi_connect, and calling`,
-        `// esp_wifi_set_max_tx_power from this shim fights the driver for control of`,
-        `// the radio (brownout). The compile-time PHY ceiling (ESP_PHY_MAX_WIFI_TX_POWER`,
-        `// in ESP-IDF's components/esp_phy/Kconfig) is NOT sourced into Zephyr's Kconfig`,
-        `// tree, so it cannot be lowered via prj.conf either (zephyr#45580). TX power`,
-        `// stays at its default until a Zephyr-native surface exists.`,
-        `static void __tc_wifi_set_hostname(const char* name) {`,
-        `    // Best-effort: Zephyr has no net_if_set_hostname; the system hostname`,
-        `    // comes from the hostname subsystem (net_hostname.h) + CONFIG_NET_HOSTNAME.`,
-        `    // The interface name is set via net_if_set_name, which is not the same as`,
-        `    // a DHCP hostname. No-op until the hostname subsystem is wired.`,
-        `    (void)name;`,
-        `    (void)__tc_wifi;`,
-        `}`,
-        ``,
-        `// ── power save (NET_REQUEST_WIFI_PS_CONFIG) ─────────────────────────────`,
-        `// wifi.set_power_save: HAL modes are "default" (enabled) / "none" (disabled).`,
-        `// The Zephyr esp32 driver implements esp32_wifi_set_power_save, so this is a`,
-        `// real net_mgmt request — not a no-op like set_hostname above.`,
-        `static void __tc_wifi_set_power_save(const char* mode) {`,
-        `    __tc_wifi_ensure_init();`,
-        `    if (__tc_wifi.iface == nullptr) return;`,
-        `    struct wifi_ps_params ps = { 0 };`,
-        `    ps.type = WIFI_PS_PARAM_TYPE_ENABLED;`,
-        `    // HAL mode "default" → power save on; "none" → off. (The full HAL surface`,
-        `    // only exposes those two; deeper ps_mode/wakeup tuning isn't exposed.)`,
-        `    bool on = (mode != nullptr && strcmp(mode, "none") != 0);`,
-        `    ps.enabled = on ? WIFI_PS_ENABLED : WIFI_PS_DISABLED;`,
-        `    (void)net_mgmt(NET_REQUEST_WIFI_PS_CONFIG, __tc_wifi.iface,`,
-        `                   &ps, sizeof(ps));`,
-        `}`,
-        ``,
-        `// ── waits (block on the L4 connectivity flag) ───────────────────────────`,
-        `// wifi.wait_connected / wait_disconnected: poll __tc_wifi.connected (set by`,
-        `// the L4 net_mgmt handler) with a deadline. Same blocking pattern as`,
-        `// __tc_wifi_connect.`,
-        `static void __tc_wifi_wait_connected(int32_t timeout_ms) {`,
-        `    __tc_wifi_ensure_init();`,
-        `    int32_t waited = 0;`,
-        `    while (!__tc_wifi.connected && waited < timeout_ms) { __tc_wifi_wait_slice(20); waited += 20; }`,
-        `}`,
-        `static void __tc_wifi_wait_disconnected(void) {`,
-        `    __tc_wifi_ensure_init();`,
-        `    // No timeout in the HAL surface — block until the L4 handler clears the flag.`,
-        `    while (__tc_wifi.connected) { __tc_wifi_wait_slice(20); }`,
-        `}`,
-        ``,
         `// ── AP mode (NET_REQUEST_WIFI_AP_ENABLE / DISABLE) ──────────────────────`,
-        `// wifi.ap_start / ap_stop: bring the iface up as an AP. The esp32 driver's`,
-        `// ap_enable takes the same struct as connect (ssid/psk/channel/security).`,
-        `// hidden/maxClients/channel-after-start have no driver hook (see manifest) —`,
-        `// only ssid/password/channel at start are honored.`,
+        `// CUTTLEFISH_WIFI_CONFIG_BEGIN`,
+        `// WiFiAP.start()/stop(): bring the iface up as an AP. The esp32 driver's`,
+        `// ap_enable takes the same struct as join (ssid/psk/channel/security).`,
+        `// hidden/maxClients have no driver hook — the thin WiFiAP facts carry only`,
+        `// what the driver honors.`,
         `static struct wifi_connect_req_params __tc_wifi_ap_params;`,
         `static uint8_t __tc_wifi_ap_ssid_buf[33];`,
         `static uint8_t __tc_wifi_ap_psk_buf[64];`,
@@ -396,15 +385,21 @@ export function wifiInitLines() {
 export function lowerWifi(op) {
     const o = op;
     switch (op.operation) {
-        // ── Connection ──
-        case 'wifi.connect':
-            return { code: `__tc_wifi_connect(${s(o.ssid)}, ${s(o.password ?? 'nullptr')}, ${s(o.timeoutMs ?? 15000)});` };
+        // ── Station ──
+        case 'wifi.join': {
+            // Token → Zephyr enum mapping (WiFi.OPEN/WPA2/WPA3/WPA2_WPA3).
+            const sec = Number(o.security ?? 1);
+            const secEnum = sec === 0 ? 'WIFI_SECURITY_TYPE_NONE'
+                : sec === 2 ? 'WIFI_SECURITY_TYPE_SAE'
+                    : sec === 3 ? 'WIFI_SECURITY_TYPE_PSK_SAE'
+                        : 'WIFI_SECURITY_TYPE_PSK';
+            const bandEnum = Number(o.band ?? 0) === 1 ? 'WIFI_FREQ_BAND_5_GHZ' : 'WIFI_FREQ_BAND_2_4_GHZ';
+            return { expression: `__tc_wifi_join(${s(o.ssid)}, ${o.psk != null ? s(o.psk) : 'nullptr'}, ${secEnum}, ${s(o.channel ?? 0)}, ${bandEnum}, ${s(o.timeoutMs ?? 15000)}, ${Number(o.ps ?? 0) !== 0 ? 'true' : 'false'}, ${o.ipAddr != null ? s(o.ipAddr) : 'nullptr'}, ${o.gateway != null ? s(o.gateway) : 'nullptr'}, ${o.netmask != null ? s(o.netmask) : 'nullptr'})` };
+        }
         case 'wifi.connect_start':
-            return { code: `__tc_wifi_connect_start(${s(o.ssid)}, ${s(o.password ?? 'nullptr')});` };
+            return { code: `__tc_wifi_connect_start(${s(o.ssid)}, ${o.password != null ? s(o.password) : 'nullptr'});` };
         case 'wifi.disconnect':
             return { code: `__tc_wifi_disconnect();` };
-        case 'wifi.status':
-            return { expression: `__tc_wifi_status()` };
         case 'wifi.is_connected':
             return { expression: `(__tc_wifi.connected)` };
         case 'wifi.local_ip':
@@ -416,6 +411,8 @@ export function lowerWifi(op) {
         // ── Scan ──
         case 'wifi.scan':
             return { code: `__tc_wifi_scan_blocking();` };
+        // Async split of wifi.scan (synthesized by the async tier's netWaitInfo —
+        // no TS-facing method maps here). Kick without waiting; poll scan_done.
         case 'wifi.scan_start':
             return { code: `__tc_wifi_scan_start();` };
         case 'wifi.scan_done':
@@ -432,14 +429,9 @@ export function lowerWifi(op) {
                         : '__tc_wifi_scan_channel';
             return { expression: `${helper}(${s(o.index ?? 0)})` };
         }
-        // ── Config ──
-        case 'wifi.set_hostname':
-            return { code: `__tc_wifi_set_hostname(${s(o.name)});` };
-        case 'wifi.set_power_save':
-            // HAL modes are "default" (on) / "none" (off) — see the shim's note.
-            return { code: `__tc_wifi_set_power_save(${s(o.mode)});` };
+        // ── Events ──
         case 'wifi.on_event': {
-            // Event callbacks (wifi.on_event). 'disconnect' and 'connect' are supported.
+            // 'disconnect' and 'connect' are the supported events.
             if (o.event === 'disconnect') {
                 return { code: `__tc_wifi.on_disconnect = ${s(o.handler)};` };
             }
@@ -448,11 +440,6 @@ export function lowerWifi(op) {
             }
             return undefined;
         }
-        // ── Waits (block on the L4 connectivity flag) ──
-        case 'wifi.wait_connected':
-            return { code: `__tc_wifi_wait_connected(${s(o.timeoutMs ?? 15000)});` };
-        case 'wifi.wait_disconnected':
-            return { code: `__tc_wifi_wait_disconnected();` };
         // ── AP mode (esp32 driver: ap_enable/ap_disable wired; only ssid/psk/channel
         //    honored — hidden/maxClients have no driver hook). ──
         case 'wifi.ap_start':
@@ -460,11 +447,10 @@ export function lowerWifi(op) {
         case 'wifi.ap_stop':
             return { code: `__tc_wifi_ap_stop();` };
         default:
-            // Out of scope (genuinely not lowered): ap_client_count/ap_ip/ap_set_*,
-            // credentials (save/connect_saved/clear), set_static_ip, set_auto_reconnect,
-            // set_tx_power. Each has no driver/Kconfig hook on Zephyr — see the manifest's
-            // per-op reasons. Return undefined so the resolver falls back and the
-            // 'unsupported' declaration is honest (the validator probes these).
+            // Out of scope (genuinely not lowered): each remaining wifi.* kind has no
+            // driver/Kconfig hook on Zephyr — see the manifest's per-op reasons.
+            // Return undefined so the resolver falls back and the 'unsupported'
+            // declaration is honest (the validator probes these).
             return undefined;
     }
 }