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

package/src/watchdog.ts

@@ -0,0 +1,35 @@
+// ---------------------------------------------------------------------------
+// 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 {
+  private readonly _timeoutMs: number;
+
+  /** Construct with the timeout in milliseconds. */
+  constructor(timeoutMs: number) {
+    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(): void {
+    wdtSetup(this._timeoutMs);
+  }
+
+  /** Feed the watchdog (wdt_feed). */
+  feed(): void {
+    wdtFeed();
+  }
+
+  /** Disable (wdt_disable). Not all drivers support runtime disable. */
+  disable(): void {
+    wdtDisable();
+  }
+}

package/src/wifi.ts

@@ -1,221 +1,189 @@
+// ---------------------------------------------------------------------------
+// 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 {
-  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,
+  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 enum WiFiStatus {
-  Idle = 0,
-  Connecting = 1,
-  Connected = 2,
-  ConnectFailed = 3,
-  Disconnected = 4,
-}
-
-export enum WiFiEncryption {
-  Open = 0,
-  WEP = 1,
-  WPA = 2,
-  WPA2 = 3,
-  WPA3 = 4,
-  Enterprise = 5,
-}
-
-/**
- * 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 {
-  static readonly __instance_name = "WiFi";
-
-  /** Blocking at top level; cooperatively awaitable inside async functions. */
-  connect(ssid: string, password?: string, timeoutMs: number = 15000): Promise<boolean> {
-    wifiConnect(ssid, password, timeoutMs);
-    return Promise.resolve(false);
-  }
-
-  /** Fire-and-forget STA begin; poll status() / untilConnected(). */
-  connectAsync(ssid: string, password?: string): void {
-    wifiConnectStart(ssid, password);
-  }
-
-  untilConnected(timeoutMs: number = 15000): Promise<boolean> {
-    wifiWaitConnected(timeoutMs);
-    return Promise.resolve(false);
-  }
-
-  untilDisconnected(): Promise<void> {
-    wifiWaitDisconnected();
-    return Promise.resolve();
-  }
-
-  disconnect(): void {
+export 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: string;
+  private readonly _psk: string | undefined;
+  private readonly _security: number;
+  private readonly _channel: number;
+  private readonly _band: number;
+  private readonly _timeoutMs: number;
+  private readonly _ps: number;
+  private readonly _ipAddr: string | undefined;
+  private readonly _gateway: string | undefined;
+  private readonly _netmask: string | undefined;
+
+  /** 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 };
+  } = {}) {
+    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(): boolean {
+    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(): void {
+    wifiConnectStart(this._ssid, this._psk);
+  }
+
+  /** Leave the network (NET_REQUEST_WIFI_DISCONNECT). */
+  leave(): void {
     wifiDisconnect();
   }
 
-  isConnected(): boolean {
+  /** True once IP connectivity is up (the L4 flag — post-DHCP, or after
+   *  static IPv4 facts are applied). */
+  linked(): boolean {
     return wifiIsConnected();
   }
 
-  status(): WiFiStatus {
-    return wifiStatus() as WiFiStatus;
-  }
-
-  localIP(): string {
-    return wifiLocalIp();
-  }
-
+  /** Signal strength in dBm (iface-status query). */
   rssi(): number {
     return wifiRssi();
   }
 
-  macAddress(): string {
-    return wifiMac();
-  }
-
-  hostname(name: string): this {
-    wifiSetHostname(name);
-    return this;
-  }
-
-  staticIP(ip: string, gateway: string, subnet: string, dns?: string): this {
-    wifiSetStaticIp(ip, gateway, subnet, dns);
-    return this;
+  /** The interface's global IPv4 address as text ("0.0.0.0" when down). */
+  ip(): string {
+    return wifiLocalIp();
   }
 
-  autoReconnect(enabled: boolean): this {
-    wifiSetAutoReconnect(enabled);
-    return this;
+  /** The radio's BSSID packed into a number (iface-status query). */
+  mac(): number {
+    return wifiMac();
   }
 
-  powerSave(mode: "default" | "none"): this {
-    wifiSetPowerSave(mode);
-    return this;
+  /** Fires once DHCP (or static config) assigns an address. */
+  onUp(handler: () => void): void {
+    wifiOnEvent('connect', callback(handler));
   }
 
-  /** 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 {
-    wifiSetTxPower(dbm);
-    return this;
+  /** Fires on link loss (deferred off the net_mgmt event chain so the
+   *  callback may safely call join()). */
+  onDrop(handler: () => void): void {
+    wifiOnEvent('disconnect', callback(handler));
   }
 
-  saveCredentials(ssid: string, password: string): void {
-    wifiSaveCredentials(ssid, password);
+  /** One blocking scan; read the results through the returned handle.
+   *  Fixed pool of 16 — no heap. */
+  scan(): Scan {
+    wifiScan();
+    return new Scan();
   }
+}
 
-  connectSaved(timeoutMs: number = 15000): boolean {
-    return wifiConnectSaved(timeoutMs);
+/** Read-only view over the last scan's fixed result pool. */
+export class Scan {
+  /** Number of networks found. */
+  count(): number {
+    return wifiScanCount();
   }
 
-  clearCredentials(): void {
-    wifiClearCredentials();
+  /** Network name ("" when out of range). */
+  ssid(i: number): string {
+    return wifiScanSsid(i);
   }
 
-  onConnect(handler: () => void): void {
-    wifiOnEvent("connect", callback(handler));
+  /** Signal strength in dBm. */
+  rssi(i: number): number {
+    return wifiScanRssi(i);
   }
 
-  onDisconnect(handler: () => void): void {
-    wifiOnEvent("disconnect", callback(handler));
+  /** Security family as text: "open" / "wpa" / "wpa2" / "wpa3". */
+  security(i: number): string {
+    return wifiScanEncryption(i);
   }
 
-  startAP(ssid: string, password?: string): boolean {
-    return wifiApStart(ssid, password);
+  /** Channel number (0 when unknown). */
+  channel(i: number): number {
+    return wifiScanChannel(i);
   }
+}
 
-  apChannel(ch: number): this {
-    wifiApSetChannel(ch);
-    return this;
-  }
+/** SoftAP — the AP facts at construction, then start/stop. */
+export class WiFiAP {
+  private readonly _ssid: string;
+  private readonly _psk: string | undefined;
+  private readonly _channel: number;
 
-  apHidden(hidden: boolean): this {
-    wifiApSetHidden(hidden);
-    return this;
+  /** Construct an AP. `psk` omitted → open network. `channel` 0 = auto. */
+  constructor(ssid: string, opts: { psk?: string; channel?: number } = {}) {
+    this._ssid = ssid;
+    this._psk = opts.psk;
+    this._channel = opts.channel ?? 0;
   }
 
-  apMaxClients(n: number): this {
-    wifiApSetMaxClients(n);
-    return this;
+  /** Bring the interface up as an AP (NET_REQUEST_WIFI_AP_ENABLE). */
+  start(): void {
+    wifiApStart(this._ssid, this._psk, this._channel);
   }
 
-  stopAP(): void {
+  /** Tear the AP down (NET_REQUEST_WIFI_AP_DISABLE). */
+  stop(): void {
     wifiApStop();
   }
-
-  apClientCount(): number {
-    return wifiApClientCount();
-  }
-
-  apIP(): string {
-    return wifiApIp();
-  }
-
-  scan(): number {
-    return wifiScan();
-  }
-
-  scanAsync(): Promise<void> {
-    wifiScanStart();
-    return Promise.resolve();
-  }
-
-  scanCount(): number {
-    return wifiScanCount();
-  }
-
-  scanSSID(i: number): string {
-    return wifiScanSsid(i);
-  }
-
-  scanRSSI(i: number): number {
-    return wifiScanRssi(i);
-  }
-
-  scanEncryption(i: number): WiFiEncryption {
-    return wifiScanEncryption(i) as WiFiEncryption;
-  }
-
-  scanChannel(i: number): number {
-    return wifiScanChannel(i);
-  }
 }
-
-export const WiFi = new WiFiClass();

package/src/zephyr-tokens.generated.ts

@@ -0,0 +1,77 @@
+// ---------------------------------------------------------------------------
+// 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: readonly string[] = [
+  '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: readonly string[] = [
+  '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: readonly string[] = [
+  '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: readonly string[] = [
+  'INT_DISABLE',
+  'INT_EDGE_RISING',
+  'INT_EDGE_FALLING',
+  'INT_EDGE_BOTH',
+  'INT_LEVEL_LOW',
+  'INT_LEVEL_HIGH',
+];

package/src/adc.ts

@@ -1,30 +0,0 @@
-import { adcRead, adcSetReference, boardResolve } from './emit.js';
-
-export class ADCClass {
-  static readonly __instance_name = "ADC";
-  static readonly __default_fields = { _reference: "DEFAULT" };
-  _reference: string;
-
-  constructor() {
-    this._reference = "DEFAULT";
-  }
-
-  getAnalogResolution(): number {
-    return boardResolve("peripherals.adc.0.resolution");
-  }
-
-  setAnalogReference(ref: string): void {
-    this._reference = ref;
-    adcSetReference(ref);
-  }
-
-  getAnalogReference(): number {
-    return boardResolve("peripherals.adc.0.referenceVoltages." + this._reference);
-  }
-
-  read(pin: number): number {
-    return adcRead(pin);
-  }
-}
-
-export const ADC = new ADCClass();

package/src/capacitive.ts

@@ -1,31 +0,0 @@
-/**
- * CapacitiveClass — ESP32 on-chip capacitive touch pins.
- *
- * ESP32-family chips have dedicated capacitive-sensing GPIOs (10 on classic
- * ESP32, up to 14 on S3) that read touch/proximity without external
- * components — distinct from the I2C/SPI touch *display* controllers (FT6336U,
- * GT911, etc.). Lowered to capacitive.* HAL ops: ESP-IDF's touch_sensor driver.
- *
- * Pin numbers are the touch-pad-capable GPIOs (GPIO4, GPIO0, GPIO2, ... on
- * classic ESP32); the framework maps them to touch_channel indices.
- */
-export class CapacitiveClass {
-  static readonly __instance_name = "Capacitive";
-
-  /** Read the raw capacitive value of a touch pin. Higher = more capacitance
-   *  (touched). The raw scale is chip-dependent; use a threshold calibrated
-   *  against the untouched reading. */
-  read(pin: number): number {
-    return capacitiveRead(pin);
-  }
-
-  /** True when the pin's reading exceeds `threshold` (a convenience over read()). */
-  isTouched(pin: number, threshold: number): boolean {
-    return capacitiveRead(pin) > threshold;
-  }
-}
-
-export const Capacitive = new CapacitiveClass();
-
-// ── Semantic primitive (resolved to capacitive.* HAL op by the transpiler) ──
-export function capacitiveRead(pin: number): number { return 0; }

package/src/constants.ts

@@ -1,23 +0,0 @@
-// These constants are resolved from the board definition at compile time by the
-// transpiler. At runtime (tests, type-checking) they default to 0.
-export const INPUT: number = 0;
-export const OUTPUT: number = 0;
-export const INPUT_PULLUP: number = 0;
-export const INPUT_PULLDOWN: number = 0;
-export const OUTPUT_OPEN_DRAIN: number = 0;
-export const ANALOG: number = 0;
-export const HIGH: number = 0;
-export const LOW: number = 0;
-export const LED_BUILTIN: number = 0;
-export const LSBFIRST: number = 0;
-export const MSBFIRST: number = 0;
-export const WDTO_15MS: number = 0;
-export const WDTO_30MS: number = 0;
-export const WDTO_60MS: number = 0;
-export const WDTO_120MS: number = 0;
-export const WDTO_250MS: number = 0;
-export const WDTO_500MS: number = 0;
-export const WDTO_1S: number = 0;
-export const WDTO_2S: number = 0;
-export const WDTO_4S: number = 0;
-export const WDTO_8S: number = 0;

package/src/dac.ts

@@ -1,21 +0,0 @@
-import { dacWrite, boardResolve } from './emit.js';
-
-/**
- * DACClass provides access to true digital-to-analog converters.
- * 
- * Note: This is for true analog output (DAC), distinct from PWM-based
- * analog simulation provided by Pin.pwm().
- */
-export class DACClass {
-  static readonly __instance_name = "DAC";
-
-  write(pin: number, value: number): void {
-    dacWrite(pin, value);
-  }
-
-  getResolution(): number {
-    return boardResolve("peripherals.dac.0.resolution");
-  }
-}
-
-export const DAC = new DACClass();

package/src/eeprom.ts

@@ -1,26 +0,0 @@
-import { rawCpp } from './emit.js';
-import { include } from './include.js';
-
-export class EEPROMClass {
-  static readonly __instance_name = "EEPROM";
-  static readonly __includes = ["<EEPROM.h>"];
-  static readonly __default_fields = { _name: "EEPROM" };
-
-  private _name: string;
-  constructor(name: string) {
-    include("<EEPROM.h>");
-    this._name = name;
-  }
-
-  read(address: number): number { return 0; }
-  write(address: number, value: number): void { rawCpp(`${this._name}.write(${address}, ${value});`); }
-  update(address: number, value: number): void { rawCpp(`${this._name}.update(${address}, ${value});`); }
-  length(): number { return 0; }
-  get<T>(address: number, ref: T): T {
-    rawCpp(`${this._name}.get(${address}, ${ref});`);
-    return ref;
-  }
-  put<T>(address: number, value: T): void { rawCpp(`${this._name}.put(${address}, ${value});`); }
-}
-
-export const EEPROM = new EEPROMClass("EEPROM");

package/src/interrupts.ts

@@ -1,35 +0,0 @@
-// ---------------------------------------------------------------------------
-// @typecad/hal — Interrupt helpers
-// ---------------------------------------------------------------------------
-
-import { interruptAttach, interruptDetach } from './emit.js';
-import { callback } from './callback.js';
-import type { InterruptHandler, InterruptMode } from './types.js';
-
-/**
- * Globally disable interrupts.
- */
-export function noInterrupts(): void {}
-
-/**
- * Re-enable interrupts after `noInterrupts()`.
- */
-export function interrupts(): void {}
-
-/**
- * Attach an interrupt handler to a pin.
- */
-export function attachInterrupt(
-  pin: number,
-  handler: InterruptHandler,
-  mode: InterruptMode,
-): void {
-  interruptAttach(pin, callback(handler), mode);
-}
-
-/**
- * Detach a previously attached interrupt.
- */
-export function detachInterrupt(pin: number): void {
-  interruptDetach(pin);
-}