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

package/dist/wifi.js

@@ -1,151 +1,137 @@
-import { wifiConnect, wifiConnectStart, wifiDisconnect, wifiStatus, wifiIsConnected, wifiLocalIp, wifiRssi, wifiMac, wifiSetHostname, wifiSetStaticIp, wifiSetAutoReconnect, wifiSetPowerSave, wifiSetTxPower, wifiOnEvent, wifiApStart, wifiApStop, wifiApClientCount, wifiApIp, wifiApSetChannel, wifiApSetHidden, wifiApSetMaxClients, wifiScan, wifiScanStart, wifiScanCount, wifiScanSsid, wifiScanRssi, wifiScanEncryption, wifiScanChannel, wifiSaveCredentials, wifiConnectSaved, wifiClearCredentials, wifiWaitConnected, wifiWaitDisconnected, } from './emit.js';
+// ---------------------------------------------------------------------------
+// WiFi — the thin Zephyr-shaped station/AP wrappers
+//
+// The link policy is CONSTRUCTION facts: credentials, security, band/channel,
+// join timeout, power-save, and (optionally) static IPv4 all ride the join op
+// (the sensor discipline — every op carries its construction facts). Methods
+// lower 1:1 onto Zephyr's net_mgmt/wifi_mgmt surface:
+//
+//   join()    → wifi_connect_req_params from the facts + a bounded wait on
+//               the L4 connected flag (conn_mgr monitor raises it post-DHCP,
+//               or immediately when static IPv4 facts are configured).
+//               Returns boolean — no exceptions. Awaitable in async contexts
+//               (start + poll split, like Time.sleep).
+//   leave()   → NET_REQUEST_WIFI_DISCONNECT
+//   linked() / rssi() / ip() / mac() → iface-status + net_if queries
+//   onUp() / onDrop() → the L4 / IPv4-addr net_mgmt event callbacks
+//   scan()    → one blocking scan, results read through the Scan handle
+//               (fixed pool, no heap)
+//
+// WiFiAP carries the SoftAP facts (ssid/psk/channel) the same way:
+// start()/stop() map to NET_REQUEST_WIFI_AP_ENABLE/DISABLE.
+// ----------------------------------------------------------------------------
+import { wifiJoin, wifiConnectStart, wifiDisconnect, wifiIsConnected, wifiLocalIp, wifiRssi, wifiMac, wifiOnEvent, wifiScan, wifiScanCount, wifiScanSsid, wifiScanRssi, wifiScanEncryption, wifiScanChannel, wifiApStart, wifiApStop, } from './emit.js';
 import { callback } from './callback.js';
-/** Normalized WiFi link status (mapped from esp_wifi events by the runtime shim). */
-export var WiFiStatus;
-(function (WiFiStatus) {
-    WiFiStatus[WiFiStatus["Idle"] = 0] = "Idle";
-    WiFiStatus[WiFiStatus["Connecting"] = 1] = "Connecting";
-    WiFiStatus[WiFiStatus["Connected"] = 2] = "Connected";
-    WiFiStatus[WiFiStatus["ConnectFailed"] = 3] = "ConnectFailed";
-    WiFiStatus[WiFiStatus["Disconnected"] = 4] = "Disconnected";
-})(WiFiStatus || (WiFiStatus = {}));
-export var WiFiEncryption;
-(function (WiFiEncryption) {
-    WiFiEncryption[WiFiEncryption["Open"] = 0] = "Open";
-    WiFiEncryption[WiFiEncryption["WEP"] = 1] = "WEP";
-    WiFiEncryption[WiFiEncryption["WPA"] = 2] = "WPA";
-    WiFiEncryption[WiFiEncryption["WPA2"] = 3] = "WPA2";
-    WiFiEncryption[WiFiEncryption["WPA3"] = 4] = "WPA3";
-    WiFiEncryption[WiFiEncryption["Enterprise"] = 5] = "Enterprise";
-})(WiFiEncryption || (WiFiEncryption = {}));
-/**
- * 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 class WiFiClass {
-    /** Blocking at top level; cooperatively awaitable inside async functions. */
-    connect(ssid, password, timeoutMs = 15000) {
-        wifiConnect(ssid, password, timeoutMs);
-        return Promise.resolve(false);
-    }
-    /** Fire-and-forget STA begin; poll status() / untilConnected(). */
-    connectAsync(ssid, password) {
-        wifiConnectStart(ssid, password);
-    }
-    untilConnected(timeoutMs = 15000) {
-        wifiWaitConnected(timeoutMs);
-        return Promise.resolve(false);
-    }
-    untilDisconnected() {
-        wifiWaitDisconnected();
-        return Promise.resolve();
-    }
-    disconnect() {
+export class WiFi {
+    /** 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, opts = {}) {
+        this._ssid = ssid;
+        this._psk = opts.psk;
+        this._security = opts.security ?? (opts.psk !== undefined ? WiFi.WPA2 : WiFi.OPEN);
+        this._channel = opts.channel ?? 0;
+        this._band = opts.band ?? WiFi.BAND_2_4;
+        this._timeoutMs = opts.timeoutMs ?? 15000;
+        this._ps = opts.powerSave ?? 0;
+        this._ipAddr = opts.ipv4?.addr;
+        this._gateway = opts.ipv4?.gateway;
+        this._netmask = opts.ipv4?.netmask;
+    }
+    /** 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() {
+        return wifiJoin(this._ssid, this._psk, this._security, this._channel, this._band, this._timeoutMs, this._ps, this._ipAddr, this._gateway, this._netmask);
+    }
+    /** Fire-and-forget join — poll linked() or await in an async function. */
+    joinStart() {
+        wifiConnectStart(this._ssid, this._psk);
+    }
+    /** Leave the network (NET_REQUEST_WIFI_DISCONNECT). */
+    leave() {
         wifiDisconnect();
     }
-    isConnected() {
+    /** True once IP connectivity is up (the L4 flag — post-DHCP, or after
+     *  static IPv4 facts are applied). */
+    linked() {
         return wifiIsConnected();
     }
-    status() {
-        return wifiStatus();
-    }
-    localIP() {
-        return wifiLocalIp();
-    }
+    /** Signal strength in dBm (iface-status query). */
     rssi() {
         return wifiRssi();
     }
-    macAddress() {
-        return wifiMac();
-    }
-    hostname(name) {
-        wifiSetHostname(name);
-        return this;
-    }
-    staticIP(ip, gateway, subnet, dns) {
-        wifiSetStaticIp(ip, gateway, subnet, dns);
-        return this;
-    }
-    autoReconnect(enabled) {
-        wifiSetAutoReconnect(enabled);
-        return this;
-    }
-    powerSave(mode) {
-        wifiSetPowerSave(mode);
-        return this;
-    }
-    /** Cap TX power in dBm (roughly 2–20). Safe to call before connect() —
-     *  the value is applied after the radio starts. */
-    txPower(dbm) {
-        wifiSetTxPower(dbm);
-        return this;
-    }
-    saveCredentials(ssid, password) {
-        wifiSaveCredentials(ssid, password);
-    }
-    connectSaved(timeoutMs = 15000) {
-        return wifiConnectSaved(timeoutMs);
-    }
-    clearCredentials() {
-        wifiClearCredentials();
-    }
-    onConnect(handler) {
-        wifiOnEvent("connect", callback(handler));
-    }
-    onDisconnect(handler) {
-        wifiOnEvent("disconnect", callback(handler));
-    }
-    startAP(ssid, password) {
-        return wifiApStart(ssid, password);
-    }
-    apChannel(ch) {
-        wifiApSetChannel(ch);
-        return this;
-    }
-    apHidden(hidden) {
-        wifiApSetHidden(hidden);
-        return this;
-    }
-    apMaxClients(n) {
-        wifiApSetMaxClients(n);
-        return this;
+    /** The interface's global IPv4 address as text ("0.0.0.0" when down). */
+    ip() {
+        return wifiLocalIp();
     }
-    stopAP() {
-        wifiApStop();
+    /** The radio's BSSID packed into a number (iface-status query). */
+    mac() {
+        return wifiMac();
     }
-    apClientCount() {
-        return wifiApClientCount();
+    /** Fires once DHCP (or static config) assigns an address. */
+    onUp(handler) {
+        wifiOnEvent('connect', callback(handler));
     }
-    apIP() {
-        return wifiApIp();
+    /** Fires on link loss (deferred off the net_mgmt event chain so the
+     *  callback may safely call join()). */
+    onDrop(handler) {
+        wifiOnEvent('disconnect', callback(handler));
     }
+    /** One blocking scan; read the results through the returned handle.
+     *  Fixed pool of 16 — no heap. */
     scan() {
-        return wifiScan();
-    }
-    scanAsync() {
-        wifiScanStart();
-        return Promise.resolve();
+        wifiScan();
+        return new Scan();
     }
-    scanCount() {
+}
+/** Security tokens — lowered to Zephyr's wifi_security_type enum. */
+WiFi.OPEN = 0;
+WiFi.WPA2 = 1;
+WiFi.WPA3 = 2;
+WiFi.WPA2_WPA3 = 3;
+/** Band tokens. */
+WiFi.BAND_2_4 = 0;
+WiFi.BAND_5 = 1;
+/** Power-save token — pass PS_OFF to disable the radio's modem sleep. */
+WiFi.PS_OFF = 0;
+/** Read-only view over the last scan's fixed result pool. */
+export class Scan {
+    /** Number of networks found. */
+    count() {
         return wifiScanCount();
     }
-    scanSSID(i) {
+    /** Network name ("" when out of range). */
+    ssid(i) {
         return wifiScanSsid(i);
     }
-    scanRSSI(i) {
+    /** Signal strength in dBm. */
+    rssi(i) {
         return wifiScanRssi(i);
     }
-    scanEncryption(i) {
+    /** Security family as text: "open" / "wpa" / "wpa2" / "wpa3". */
+    security(i) {
         return wifiScanEncryption(i);
     }
-    scanChannel(i) {
+    /** Channel number (0 when unknown). */
+    channel(i) {
         return wifiScanChannel(i);
     }
 }
-WiFiClass.__instance_name = "WiFi";
-export const WiFi = new WiFiClass();
+/** SoftAP — the AP facts at construction, then start/stop. */
+export class WiFiAP {
+    /** Construct an AP. `psk` omitted → open network. `channel` 0 = auto. */
+    constructor(ssid, opts = {}) {
+        this._ssid = ssid;
+        this._psk = opts.psk;
+        this._channel = opts.channel ?? 0;
+    }
+    /** Bring the interface up as an AP (NET_REQUEST_WIFI_AP_ENABLE). */
+    start() {
+        wifiApStart(this._ssid, this._psk, this._channel);
+    }
+    /** Tear the AP down (NET_REQUEST_WIFI_AP_DISABLE). */
+    stop() {
+        wifiApStop();
+    }
+}

package/dist/zephyr-tokens.generated.d.ts

@@ -0,0 +1,8 @@
+/** enum adc_gain suffixes — ADC.GAIN_<name> ↔ ADC_GAIN_<name>. */
+export declare const ZEPHYR_ADC_GAINS: readonly string[];
+/** enum adc_reference suffixes — ADC.REF_<name> ↔ ADC_REF_<name>. */
+export declare const ZEPHYR_ADC_REFERENCES: readonly string[];
+/** GPIO config flag names — GPIO.<name> ↔ GPIO_<name>. */
+export declare const ZEPHYR_GPIO_FLAGS: readonly string[];
+/** GPIO interrupt configuration names — GPIO.INT_<name> ↔ GPIO_INT_<name>. */
+export declare const ZEPHYR_GPIO_INTS: readonly string[];

package/dist/zephyr-tokens.generated.js

@@ -0,0 +1,73 @@
+// ---------------------------------------------------------------------------
+// zephyr-tokens.generated.ts — the thin-HAL token name sets
+//
+// GENERATED FILE — do not edit by hand. Regenerate against the pinned
+// workspace with:
+//
+//   node scripts/gen-zephyr-hal-tokens.mjs <zephyr-base>
+//
+// Derived from Zephyr 4.4.2: enum adc_gain / enum adc_reference
+// (include/zephyr/drivers/adc.h), the GPIO config flags (drivers/gpio.h +
+// dt-bindings/gpio/gpio.h), and the GPIO_INT_* interrupt configurations
+// (drivers/gpio.h). 21 gains, 7 references,
+// 9 flags, 6 interrupt configs.
+//
+// The class statics stay hand-declared for editor typing; the token-sync
+// test asserts they match these sets. The lowerings build their
+// token→macro maps from these lists — names only; values never cross to C++.
+// ---------------------------------------------------------------------------
+/** enum adc_gain suffixes — ADC.GAIN_<name> ↔ ADC_GAIN_<name>. */
+export const ZEPHYR_ADC_GAINS = [
+    '1_6',
+    '1_5',
+    '1_4',
+    '2_7',
+    '1_3',
+    '2_5',
+    '1_2',
+    '2_3',
+    '4_5',
+    '1',
+    '2',
+    '3',
+    '4',
+    '6',
+    '8',
+    '12',
+    '16',
+    '24',
+    '32',
+    '64',
+    '128',
+];
+/** enum adc_reference suffixes — ADC.REF_<name> ↔ ADC_REF_<name>. */
+export const ZEPHYR_ADC_REFERENCES = [
+    'VDD_1',
+    'VDD_1_2',
+    'VDD_1_3',
+    'VDD_1_4',
+    'INTERNAL',
+    'EXTERNAL0',
+    'EXTERNAL1',
+];
+/** GPIO config flag names — GPIO.<name> ↔ GPIO_<name>. */
+export const ZEPHYR_GPIO_FLAGS = [
+    'INPUT',
+    'OUTPUT',
+    'OUTPUT_INIT_LOW',
+    'OUTPUT_INIT_HIGH',
+    'PULL_UP',
+    'PULL_DOWN',
+    'OPEN_DRAIN',
+    'OPEN_SOURCE',
+    'DISCONNECTED',
+];
+/** GPIO interrupt configuration names — GPIO.INT_<name> ↔ GPIO_INT_<name>. */
+export const ZEPHYR_GPIO_INTS = [
+    'INT_DISABLE',
+    'INT_EDGE_RISING',
+    'INT_EDGE_FALLING',
+    'INT_EDGE_BOTH',
+    'INT_LEVEL_LOW',
+    'INT_LEVEL_HIGH',
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typecad/hal",
-  "version": "1.0.0-alpha.13",
+  "version": "1.0.0-alpha.15",
   "description": "TypeCAD hardware abstraction layer — GPIO, I2C, SPI, UART as regular TypeScript",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,9 +12,10 @@
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "npm run build",
-    "test:hw": "npm exec -- cuttlefish-test",
-    "test:hw:basics": "npm exec -- cuttlefish-test tests/01-gpio.test.ts",
-    "test:hw:preferences": "npm exec -- cuttlefish-test tests/14-preferences.test.ts"
+    "test:hw": "npm exec -- cuttlefish-test --config boards/blackpill/cuttlefish.config.ts",
+    "test:hw:board": "npm exec -- cuttlefish-test",
+    "test:hw:wired": "npm exec -- cuttlefish-test --config boards/blackpill/cuttlefish.config.ts --include \"tests/wired/*.test.ts\"",
+    "test:hw:esp32s3": "npm exec -- cuttlefish-test --config boards/esp32s3/cuttlefish.config.ts"
   },
   "license": "MIT",
   "publishConfig": {
@@ -46,13 +47,11 @@
     "uart"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22.11.0"
   },
   "author": "typecad0",
   "devDependencies": {
-    "@typecad/expect": "1.0.0-alpha.13",
-    "@typecad/board-arduino-uno": "1.0.0-alpha.13",
-    "@typecad/mcu-atmega328p": "1.0.0-alpha.13"
+    "@typecad/expect": "1.0.0-alpha.15"
   },
   "sideEffects": false,
   "exports": {

package/src/adc-pin.ts

@@ -0,0 +1,89 @@
+// ---------------------------------------------------------------------------
+// ADC — the thin Zephyr-shaped analog input
+//
+// Construction IS the channel setup: gain and reference are constructor
+// options (exactly struct adc_channel_cfg), defaulting to the chip
+// descriptor's pair when omitted. read() returns raw counts at the chip's
+// resolution; readMillivolts() applies adc_raw_to_millivolts. There is no
+// setReference() — Zephyr applies the reference at channel-setup time, and
+// this surface doesn't promise otherwise.
+//
+// Gain/reference tokens are Zephyr's enum names under the ADC
+// namespace (ADC_GAIN_1_4 ↔ ADC.GAIN_1_4, ADC_REF_INTERNAL ↔
+// ADC.REF_INTERNAL); the lowering maps token names to macros.
+// ----------------------------------------------------------------------------
+
+import { adcReadRaw, adcReadMv } from './emit.js';
+import type { Pin } from './gpio.js';
+
+export class ADC {
+  // ── Gain tokens (enum adc_gain, verbatim — generated set, see the
+  //    token-sync test) ───────────────────────────────────────────────────
+  static readonly GAIN_1_6 = 0x01;
+  static readonly GAIN_1_5 = 0x02;
+  static readonly GAIN_1_4 = 0x03;
+  static readonly GAIN_2_7 = 0x04;
+  static readonly GAIN_1_3 = 0x05;
+  static readonly GAIN_2_5 = 0x06;
+  static readonly GAIN_1_2 = 0x07;
+  static readonly GAIN_2_3 = 0x08;
+  static readonly GAIN_4_5 = 0x09;
+  static readonly GAIN_1 = 0x0a;
+  static readonly GAIN_2 = 0x0b;
+  static readonly GAIN_3 = 0x0c;
+  static readonly GAIN_4 = 0x0d;
+  static readonly GAIN_6 = 0x0e;
+  static readonly GAIN_8 = 0x0f;
+  static readonly GAIN_12 = 0x10;
+  static readonly GAIN_16 = 0x11;
+  static readonly GAIN_24 = 0x12;
+  static readonly GAIN_32 = 0x13;
+  static readonly GAIN_64 = 0x14;
+  static readonly GAIN_128 = 0x15;
+
+  // ── Reference tokens (enum adc_reference, verbatim) ────────────────────
+  static readonly REF_VDD_1 = 0x100;
+  static readonly REF_VDD_1_2 = 0x101;
+  static readonly REF_VDD_1_3 = 0x102;
+  static readonly REF_VDD_1_4 = 0x103;
+  static readonly REF_INTERNAL = 0x104;
+  static readonly REF_EXTERNAL0 = 0x105;
+  static readonly REF_EXTERNAL1 = 0x106;
+
+  private readonly _pin: number;
+  private readonly _gain: number | string;
+  private readonly _reference: number | string;
+  // Routing overrides (the inline escape hatch): when the facts layer does
+  // not cover this pin, the construction carries the channel (and optional
+  // device label + pinctrl token) the lowering uses verbatim.
+  private readonly _channel: number;
+  private readonly _device: string;
+  private readonly _pinctrl: string;
+
+  /** Construct an analog input channel. Omitted gain/reference fall back to
+   *  the chip descriptor's pair (the values the platform's driver validates
+   *  against, e.g. STM32's ADC_GAIN_1 + ADC_REF_INTERNAL). */
+  constructor(
+    pin: number | Pin,
+    opts?: { gain?: number; reference?: number; channel?: number; device?: string; pinctrl?: string },
+  ) {
+    this._pin = typeof pin === 'number' ? pin : pin.number;
+    this._gain = opts?.gain ?? '';
+    this._reference = opts?.reference ?? '';
+    this._channel = opts?.channel ?? -1;
+    this._device = opts?.device ?? '';
+    this._pinctrl = opts?.pinctrl ?? '';
+  }
+
+  /** Read raw counts at the chip's resolution (adc_channel_setup on first
+   *  use with the construction gain/reference, then adc_read). */
+  read(): number {
+    return adcReadRaw(this._pin, this._gain, this._reference, this._channel, this._device, this._pinctrl);
+  }
+
+  /** Read millivolts (adc_raw_to_millivolts against the descriptor's
+   *  vref). Returns mV. */
+  readMillivolts(): number {
+    return adcReadMv(this._pin, this._gain, this._reference, this._channel, this._device, this._pinctrl);
+  }
+}

package/src/async.ts

@@ -4,7 +4,6 @@
 // Provides a platform-independent API for:
 //   - sleep(ms)      — non-blocking delay via Promise + microtask
 //   - yield()        — cooperative yield to other tasks
-//   - sleepUntil(condition) — await a condition (promise-based)
 //   - currentTask()  — return a description of the currently executing task
 //
 // Framework packages (Arduino, Native, etc.) provide the C++ runtime behind
@@ -19,10 +18,9 @@ export class AsyncClass {
 
   /**
    * Non-blocking sleep for `ms` milliseconds.
-   * Returns a Promise<void> that resolves after the given delay.
-   * The underlying C++ implementation uses the platform's timer/microtask
-   * mechanism (e.g. millis-based polling on Arduino, std::this_thread::sleep_for
-   * on native, or a FreeRTOS vTaskDelay in the future).
+   * Returns a Promise<void> that resolves after the given delay. The async
+   * runtime resolves it cooperatively (the static state machine on
+   * heap-less targets polls the clock in the scheduler loop).
    */
   sleep(ms: number): Promise<void> {
     rawCpp(`__cuttlefish_async_sleep(${ms});`);
@@ -38,17 +36,6 @@ export class AsyncClass {
     return Promise.resolve();
   }
 
-  /**
-   * Await a polling condition.
-   * Repeatedly checks `condition()` every `pollIntervalMs` milliseconds
-   * until it returns true, then resolves.
-   * The underlying implementation uses the platform's timer mechanism.
-   */
-  sleepUntil(condition: () => boolean, pollIntervalMs: number = 10): Promise<void> {
-    rawCpp(`__cuttlefish_async_sleep_until(${pollIntervalMs});`);
-    return Promise.resolve();
-  }
-
   /**
    * Return a human-readable description of the currently executing async task.
    * Useful for debugging / logging in cooperative multitasking environments.