@typecad/hal 1.0.0-alpha.13 → 1.0.0-alpha.15

package/dist/types.js

@@ -1,12 +1,13 @@
 // ---------------------------------------------------------------------------
 // @typecad/hal — Public type definitions
 //
-// Transpiler-shim type surface: enums, type aliases, and the pin-group API
-// consumed by the HAL's transpiler-shim classes (Pin/OutputPin/InputPin,
-// I2CBus/SPIBus/SerialPort) and re-exported for downstream type-checking.
+// Transpiler-shim type surface: value aliases and the enums consumed by the
+// HAL's transpiler-shim classes (Pin, GPIO, I2CBus/SPIBus) and re-exported
+// for downstream type-checking.
 //
 // Runtime-contract interfaces (BasePin, II2CBus, ISPIBus, ISerialPort, the
-// status enums, capability guards, etc.) have been relocated to
+// status enums, capability guards, and the legacy Wire/SPI protocol-shape
+// types I2CAddress/SPIMode/SPIBitOrder/SPISettings) have been relocated to
 // @typecad/simulator/src/contracts.ts — they describe the runtime objects the
 // simulator implements, not the transpiler shims that live here.
 // ---------------------------------------------------------------------------
@@ -22,46 +23,3 @@ export var PinMode;
     PinMode["OUTPUT_OPEN_DRAIN"] = "OUTPUT_OPEN_DRAIN";
     PinMode["ANALOG"] = "ANALOG";
 })(PinMode || (PinMode = {}));
-// ---------------------------------------------------------------------------
-// Interrupt mode enum
-// ---------------------------------------------------------------------------
-export var InterruptMode;
-(function (InterruptMode) {
-    InterruptMode["RISING"] = "RISING";
-    InterruptMode["FALLING"] = "FALLING";
-    InterruptMode["CHANGE"] = "CHANGE";
-    InterruptMode["LOW"] = "LOW";
-    InterruptMode["HIGH"] = "HIGH";
-})(InterruptMode || (InterruptMode = {}));
-export function createPinGroup(pins) {
-    return {
-        name: 'PinGroup',
-        pins: Object.freeze(pins),
-        writePattern(pattern) {
-            for (let i = 0; i < this.pins.length; i++) {
-                const bit = (pattern >> i) & 1;
-                const pin = this.pins[i];
-                if ('write' in pin && typeof pin.write === 'function') {
-                    pin.write(bit === 1);
-                }
-            }
-        },
-        readPattern() {
-            let value = 0;
-            for (let i = 0; i < this.pins.length; i++) {
-                const pin = this.pins[i];
-                if ('isHigh' in pin && typeof pin.isHigh === 'function' && pin.isHigh()) {
-                    value |= (1 << i);
-                }
-            }
-            return value;
-        },
-        fill(value) {
-            for (const pin of this.pins) {
-                if ('write' in pin && typeof pin.write === 'function') {
-                    pin.write(value);
-                }
-            }
-        },
-    };
-}

package/dist/uart-port.d.ts

@@ -0,0 +1,26 @@
+import type { SerialValue } from './types.js';
+export declare class UART {
+    private readonly _port;
+    private readonly _baud;
+    private readonly _rxBufferBytes;
+    /** Construct a port handle. `port` is the UART instance (UART0, UART1, …);
+     *  `baud` applies once at first use (default 115200, 8N1);
+     *  `rxBufferBytes` sizes the receive ring (default 64). */
+    constructor(port: string, opts?: {
+        baud?: number;
+        rxBufferBytes?: number;
+    });
+    /** Write text, a number, or a boolean (uart_poll_out per byte). No newline
+     *  appended. Numbers format as decimal; booleans print as 1/0. */
+    write(data: SerialValue): void;
+    /** Write a value followed by a newline. */
+    writeLine(data: SerialValue): void;
+    /** Bytes waiting in the receive ring. Arms the RX interrupt on first
+     *  use (uart_irq_callback_user_data_set + uart_irq_rx_enable — the
+     *  callback drains the FIFO into the ring). */
+    available(): number;
+    /** The oldest received byte WITHOUT consuming it; -1 when empty. */
+    peek(): number;
+    /** Pop the oldest received byte; -1 when the ring is empty. */
+    read(): number;
+}

package/dist/uart-port.js

@@ -0,0 +1,52 @@
+// ---------------------------------------------------------------------------
+// UART — the thin Zephyr-shaped serial port
+//
+// TX is poll-based (uart_poll_out — synchronous, fine for writes); RX is
+// INTERRUPT-backed: the first receive call arms the driver's IRQ callback,
+// which drains the FIFO into a construction-sized ring buffer. That makes
+// the honest versions of the calls the poll API couldn't support:
+//   available() — bytes waiting in the ring (the poll driver cannot report
+//                 this without draining the byte you want next)
+//   peek()      — the oldest byte WITHOUT consuming it
+//   read()      — pop the oldest byte, or -1 when the ring is empty
+//
+// Construction: `new UART('UART0', { baud: 9600, rxBufferBytes: 128 })` —
+// the ring size (default 64) is a construction fact that sizes the shim's
+// static buffer; bytes arriving with a full ring are dropped (the embedded
+// honest answer — no unbounded buffering).
+// ----------------------------------------------------------------------------
+import { uartPollWrite, uartRxAvailable, uartRxPeek, uartRxRead } from './emit.js';
+export class UART {
+    /** Construct a port handle. `port` is the UART instance (UART0, UART1, …);
+     *  `baud` applies once at first use (default 115200, 8N1);
+     *  `rxBufferBytes` sizes the receive ring (default 64). */
+    constructor(port, opts) {
+        this._port = port;
+        this._baud = opts?.baud ?? 115200;
+        this._rxBufferBytes = opts?.rxBufferBytes ?? 64;
+    }
+    /** Write text, a number, or a boolean (uart_poll_out per byte). No newline
+     *  appended. Numbers format as decimal; booleans print as 1/0. */
+    write(data) {
+        uartPollWrite(this._port, this._baud, data);
+    }
+    /** Write a value followed by a newline. */
+    writeLine(data) {
+        uartPollWrite(this._port, this._baud, data);
+        uartPollWrite(this._port, this._baud, "\n");
+    }
+    /** Bytes waiting in the receive ring. Arms the RX interrupt on first
+     *  use (uart_irq_callback_user_data_set + uart_irq_rx_enable — the
+     *  callback drains the FIFO into the ring). */
+    available() {
+        return uartRxAvailable(this._port, this._rxBufferBytes);
+    }
+    /** The oldest received byte WITHOUT consuming it; -1 when empty. */
+    peek() {
+        return uartRxPeek(this._port, this._rxBufferBytes);
+    }
+    /** Pop the oldest received byte; -1 when the ring is empty. */
+    read() {
+        return uartRxRead(this._port, this._rxBufferBytes);
+    }
+}

package/dist/uart.d.ts

@@ -1,21 +1,4 @@
 export declare class SerialPort {
-    static readonly __includes: string[];
     private _port;
     constructor(port: string);
-    begin(baud?: number): this;
-    end(): void;
-    print(value: any): void;
-    println(value: any): void;
-    printf(format: string, ...args: any[]): void;
-    write(data: any): void;
-    read(): number;
-    readLine(): string;
-    peek(): number;
-    available(): number;
-    flush(): void;
-    waitForConnection(timeout?: number): Promise<void>;
-    take(): this | null;
-    release(): void;
 }
-/** Map TypeCAD UART instance number to Arduino C++ object name. UART0→Serial, UART1→Serial1 */
-export declare function serialName(instance: number): string;

package/dist/uart.js

@@ -1,58 +1,15 @@
-import { uartBegin, uartEnd, uartPrint, uartPrintln, uartPrintf, uartWrite, uartRead, uartPeek, uartAvailable, uartFlush, rawCpp } from './emit.js';
+// ---------------------------------------------------------------------------
+// SerialPort — controller identity carrier (legacy UART API removed)
+//
+// The class carries ONLY the controller identity (the canonical controller
+// name: UART0, UART1, …). Generated board modules construct the singletons;
+// program-level serial is the thin `UART` (uart-port.ts — interrupt-drained
+// RX ring + poll TX, construction baud) or `USBConsole` (usb.ts) for the CDC
+// connector. The former print/printf/read/peek/available/waitForConnection
+// surface was removed with the legacy Arduino surface.
+// ----------------------------------------------------------------------------
 export class SerialPort {
     constructor(port) {
         this._port = port;
     }
-    begin(baud = 9600) {
-        uartBegin(this._port, baud);
-        return this;
-    }
-    end() {
-        uartEnd(this._port);
-    }
-    print(value) {
-        uartPrint(this._port, value);
-    }
-    println(value) {
-        uartPrintln(this._port, value);
-    }
-    printf(format, ...args) {
-        uartPrintf(this._port, format, args);
-    }
-    write(data) {
-        uartWrite(this._port, data);
-    }
-    read() {
-        return uartRead(this._port);
-    }
-    readLine() {
-        rawCpp(`return ${this._port}.readStringUntil('\\n');`);
-        return "";
-    }
-    peek() {
-        return uartPeek(this._port);
-    }
-    available() {
-        return uartAvailable(this._port);
-    }
-    flush() {
-        uartFlush(this._port);
-    }
-    waitForConnection(timeout) {
-        rawCpp(`while (!${this._port}) { delay(10); }`);
-        return Promise.resolve();
-    }
-    take() {
-        // Basic implementation for single-threaded Arduino; 
-        // real locking would be framework-specific.
-        return this;
-    }
-    release() {
-        // No-op for standard Arduino.
-    }
-}
-SerialPort.__includes = ["<Arduino.h>"];
-/** Map TypeCAD UART instance number to Arduino C++ object name. UART0→Serial, UART1→Serial1 */
-export function serialName(instance) {
-    return instance === 0 ? "Serial" : `Serial${instance}`;
 }

package/dist/usb.d.ts

@@ -0,0 +1,26 @@
+import type { SerialValue } from './types.js';
+export declare class USBConsole {
+    private readonly _port;
+    /** Construct the console for a CDC instance ('USB0' = instance 0). */
+    constructor(port?: string);
+    /** Start the USB device stack and bring the CDC port up. Idempotent. */
+    open(): void;
+    /** Stop using the port. Observable no-op on Zephyr — the device stack is
+     *  shared by every CDC instance and is not torn down per-port. */
+    close(): void;
+    /** Write text, a number, or a boolean. Numbers format as decimal;
+     *  booleans print as 1/0. */
+    write(value: SerialValue): void;
+    /** Write a value followed by a newline. */
+    writeLine(value: SerialValue): void;
+    /** True when the host has the port open (DTR asserted). Output written
+     *  before this is true is silently dropped by most hosts. */
+    linked(): boolean;
+    /** Block until the host opens the port, polling in the shim (no user-code
+     *  busy loop). `timeoutMs` 0 = wait forever. Returns true once linked. */
+    waitLinked(timeoutMs?: number): boolean;
+    /** Read one byte, or -1 when no byte is ready (non-blocking). */
+    read(): number;
+    /** Bytes ready to read (the CDC poll path reports 0/1 — see the lowering). */
+    available(): number;
+}

package/dist/usb.js

@@ -0,0 +1,66 @@
+// ---------------------------------------------------------------------------
+// USBConsole — the thin CDC-ACM console
+//
+// A serial pipe over the board's USB connector (Communication Device Class,
+// Abstract Control Model). The construction fact is the port identity
+// ('USB0' — the CDC instance index the devicetree overlay composes); the
+// verbs map 1:1 onto Zephyr's CDC device stack:
+//
+//   open()            → start the USB device stack (idempotent; CDC has no
+//                       wire baud — line coding is the host's business)
+//   close()           → observable no-op (tearing down the shared device
+//                       stack would drop every other CDC instance)
+//   write(v)          → one typed write (text | number | boolean — the
+//   writeLine(v)        __tc_print contract, not print(any))
+//   linked()          → the host has the port open (DTR asserted); output
+//                       written before this is silently dropped by hosts
+//   waitLinked(ms)    → ONE op: bounded DTR poll in the shim (k_msleep
+//                       slices), boolean, no user-code busy loop. 0 = forever.
+//   read()/available()→ poll RX (the byte or -1 / a ready count)
+//
+// Unlike a hardware UART, output before the host opens the port is lost —
+// gate on linked()/waitLinked() when early output matters.
+// ----------------------------------------------------------------------------
+import { usbBegin, usbEnd, usbPrint, usbPrintln, usbRead, usbAvailable, usbConnected, usbWaitReady, } from './emit.js';
+export class USBConsole {
+    /** Construct the console for a CDC instance ('USB0' = instance 0). */
+    constructor(port = 'USB0') {
+        this._port = port;
+    }
+    /** Start the USB device stack and bring the CDC port up. Idempotent. */
+    open() {
+        usbBegin(this._port);
+    }
+    /** Stop using the port. Observable no-op on Zephyr — the device stack is
+     *  shared by every CDC instance and is not torn down per-port. */
+    close() {
+        usbEnd(this._port);
+    }
+    /** Write text, a number, or a boolean. Numbers format as decimal;
+     *  booleans print as 1/0. */
+    write(value) {
+        usbPrint(this._port, value);
+    }
+    /** Write a value followed by a newline. */
+    writeLine(value) {
+        usbPrintln(this._port, value);
+    }
+    /** True when the host has the port open (DTR asserted). Output written
+     *  before this is true is silently dropped by most hosts. */
+    linked() {
+        return usbConnected(this._port);
+    }
+    /** Block until the host opens the port, polling in the shim (no user-code
+     *  busy loop). `timeoutMs` 0 = wait forever. Returns true once linked. */
+    waitLinked(timeoutMs = 0) {
+        return usbWaitReady(this._port, timeoutMs);
+    }
+    /** Read one byte, or -1 when no byte is ready (non-blocking). */
+    read() {
+        return usbRead(this._port);
+    }
+    /** Bytes ready to read (the CDC poll path reports 0/1 — see the lowering). */
+    available() {
+        return usbAvailable(this._port);
+    }
+}

package/dist/watchdog.d.ts

@@ -0,0 +1,12 @@
+export declare class Watchdog {
+    private readonly _timeoutMs;
+    /** Construct with the timeout in milliseconds. */
+    constructor(timeoutMs: number);
+    /** Arm the watchdog (wdt_install_timeout + wdt_setup). Full CPU reset on
+     *  expiry. Call feed() at least once per timeout window afterwards. */
+    enable(): void;
+    /** Feed the watchdog (wdt_feed). */
+    feed(): void;
+    /** Disable (wdt_disable). Not all drivers support runtime disable. */
+    disable(): void;
+}

package/dist/watchdog.js

@@ -0,0 +1,28 @@
+// ---------------------------------------------------------------------------
+// Watchdog — the thin Zephyr-shaped watchdog
+//
+// The timeout is a CONSTRUCTION fact in milliseconds (Zephyr's own unit for
+// wdt_timeout_cfg.window.max). enable() arms (wdt_install_timeout +
+// wdt_setup, reset-CPU-core flag); feed() keeps it alive (wdt_feed) —
+// Zephyr's verbs, no WDTO_* presets, no string parsing.
+// ----------------------------------------------------------------------------
+import { wdtSetup, wdtFeed, wdtDisable } from './emit.js';
+export class Watchdog {
+    /** Construct with the timeout in milliseconds. */
+    constructor(timeoutMs) {
+        this._timeoutMs = timeoutMs;
+    }
+    /** Arm the watchdog (wdt_install_timeout + wdt_setup). Full CPU reset on
+     *  expiry. Call feed() at least once per timeout window afterwards. */
+    enable() {
+        wdtSetup(this._timeoutMs);
+    }
+    /** Feed the watchdog (wdt_feed). */
+    feed() {
+        wdtFeed();
+    }
+    /** Disable (wdt_disable). Not all drivers support runtime disable. */
+    disable() {
+        wdtDisable();
+    }
+}

package/dist/wifi.d.ts

@@ -1,67 +1,91 @@
-/** Normalized WiFi link status (mapped from esp_wifi events by the runtime shim). */
-export declare enum WiFiStatus {
-    Idle = 0,
-    Connecting = 1,
-    Connected = 2,
-    ConnectFailed = 3,
-    Disconnected = 4
+export declare class WiFi {
+    /** Security tokens — lowered to Zephyr's wifi_security_type enum. */
+    static readonly OPEN = 0;
+    static readonly WPA2 = 1;
+    static readonly WPA3 = 2;
+    static readonly WPA2_WPA3 = 3;
+    /** Band tokens. */
+    static readonly BAND_2_4 = 0;
+    static readonly BAND_5 = 1;
+    /** Power-save token — pass PS_OFF to disable the radio's modem sleep. */
+    static readonly PS_OFF = 0;
+    private readonly _ssid;
+    private readonly _psk;
+    private readonly _security;
+    private readonly _channel;
+    private readonly _band;
+    private readonly _timeoutMs;
+    private readonly _ps;
+    private readonly _ipAddr;
+    private readonly _gateway;
+    private readonly _netmask;
+    /** Construct a station link policy. `psk` omitted → open network;
+     *  `security` defaults WPA2 when a psk is present, OPEN otherwise;
+     *  `channel` 0/omitted = any. `ipv4` opts out of DHCP with static facts. */
+    constructor(ssid: string, opts?: {
+        psk?: string;
+        security?: number;
+        channel?: number;
+        band?: number;
+        timeoutMs?: number;
+        powerSave?: number;
+        ipv4?: {
+            addr: string;
+            gateway: string;
+            netmask: string;
+        };
+    });
+    /** Join the network. Blocks (bounded by timeoutMs, pumping a mounted UI's
+     *  tick between polls); returns true once IP connectivity is up, false on
+     *  timeout or missing radio. Idempotent-ish: re-joining re-associates. */
+    join(): boolean;
+    /** Fire-and-forget join — poll linked() or await in an async function. */
+    joinStart(): void;
+    /** Leave the network (NET_REQUEST_WIFI_DISCONNECT). */
+    leave(): void;
+    /** True once IP connectivity is up (the L4 flag — post-DHCP, or after
+     *  static IPv4 facts are applied). */
+    linked(): boolean;
+    /** Signal strength in dBm (iface-status query). */
+    rssi(): number;
+    /** The interface's global IPv4 address as text ("0.0.0.0" when down). */
+    ip(): string;
+    /** The radio's BSSID packed into a number (iface-status query). */
+    mac(): number;
+    /** Fires once DHCP (or static config) assigns an address. */
+    onUp(handler: () => void): void;
+    /** Fires on link loss (deferred off the net_mgmt event chain so the
+     *  callback may safely call join()). */
+    onDrop(handler: () => void): void;
+    /** One blocking scan; read the results through the returned handle.
+     *  Fixed pool of 16 — no heap. */
+    scan(): Scan;
 }
-export declare enum WiFiEncryption {
-    Open = 0,
-    WEP = 1,
-    WPA = 2,
-    WPA2 = 3,
-    WPA3 = 4,
-    Enterprise = 5
+/** Read-only view over the last scan's fixed result pool. */
+export declare class Scan {
+    /** Number of networks found. */
+    count(): number;
+    /** Network name ("" when out of range). */
+    ssid(i: number): string;
+    /** Signal strength in dBm. */
+    rssi(i: number): number;
+    /** Security family as text: "open" / "wpa" / "wpa2" / "wpa3". */
+    security(i: number): string;
+    /** Channel number (0 when unknown). */
+    channel(i: number): number;
 }
-/**
- * WiFi radio / link control, lowered to native ESP-IDF (`esp_wifi` /
- * `esp_netif` / `esp_event` / `nvs_flash`) by framework-esp32.
- *
- * No `include()` calls here — ESP-IDF headers are framework-owned and added
- * via forcedIncludes when the program uses wifi.* ops (the Preferences
- * lesson: HAL files must not carry platform headers). Frameworks without a
- * wifi lowering reject these ops with a diagnostic.
- */
-export declare class WiFiClass {
-    static readonly __instance_name = "WiFi";
-    /** Blocking at top level; cooperatively awaitable inside async functions. */
-    connect(ssid: string, password?: string, timeoutMs?: number): Promise<boolean>;
-    /** Fire-and-forget STA begin; poll status() / untilConnected(). */
-    connectAsync(ssid: string, password?: string): void;
-    untilConnected(timeoutMs?: number): Promise<boolean>;
-    untilDisconnected(): Promise<void>;
-    disconnect(): void;
-    isConnected(): boolean;
-    status(): WiFiStatus;
-    localIP(): string;
-    rssi(): number;
-    macAddress(): string;
-    hostname(name: string): this;
-    staticIP(ip: string, gateway: string, subnet: string, dns?: string): this;
-    autoReconnect(enabled: boolean): this;
-    powerSave(mode: "default" | "none"): this;
-    /** Cap TX power in dBm (roughly 2–20). Safe to call before connect() —
-     *  the value is applied after the radio starts. */
-    txPower(dbm: number): this;
-    saveCredentials(ssid: string, password: string): void;
-    connectSaved(timeoutMs?: number): boolean;
-    clearCredentials(): void;
-    onConnect(handler: () => void): void;
-    onDisconnect(handler: () => void): void;
-    startAP(ssid: string, password?: string): boolean;
-    apChannel(ch: number): this;
-    apHidden(hidden: boolean): this;
-    apMaxClients(n: number): this;
-    stopAP(): void;
-    apClientCount(): number;
-    apIP(): string;
-    scan(): number;
-    scanAsync(): Promise<void>;
-    scanCount(): number;
-    scanSSID(i: number): string;
-    scanRSSI(i: number): number;
-    scanEncryption(i: number): WiFiEncryption;
-    scanChannel(i: number): number;
+/** SoftAP — the AP facts at construction, then start/stop. */
+export declare class WiFiAP {
+    private readonly _ssid;
+    private readonly _psk;
+    private readonly _channel;
+    /** Construct an AP. `psk` omitted → open network. `channel` 0 = auto. */
+    constructor(ssid: string, opts?: {
+        psk?: string;
+        channel?: number;
+    });
+    /** Bring the interface up as an AP (NET_REQUEST_WIFI_AP_ENABLE). */
+    start(): void;
+    /** Tear the AP down (NET_REQUEST_WIFI_AP_DISABLE). */
+    stop(): void;
 }
-export declare const WiFi: WiFiClass;