@typecad/hal 1.0.0-alpha.6 → 1.0.0-alpha.7

package/src/rmt.ts

@@ -0,0 +1,125 @@
+// ---------------------------------------------------------------------------
+// @typecad/hal — RMT (Remote Control Transceiver) ergonomic API
+// ---------------------------------------------------------------------------
+// Exposes RMT via a RmtChannel class, mirroring the I2CBus/I2CDevice pattern.
+// The transpiler only resolves semantic calls made inside class-method bodies
+// (free top-level calls emit verbatim), so every peripheral exposes its API
+// through a class whose methods call the positional semantic primitives in
+// emit.ts. The resolver collapses object literals, so HALOpIR fields must be
+// scalars; these methods destructure `opts` at the call site before forwarding.
+//
+// Channel identity is the GPIO pin (like pwm.ts's LEDC channel-per-pin model).
+
+import type { Pin } from './gpio.js';
+import {
+  rmtTxInit,
+  rmtRxInit,
+  rmtTxWriteBytes,
+  rmtTxWriteSymbols,
+  rmtTxWaitDone,
+  rmtTxDeinit,
+  rmtRxOnReceived,
+  rmtRxStart,
+  rmtRxStop,
+  rmtRxRead,
+  rmtRxDeinit,
+} from './emit.js';
+
+/** Pin identifier accepted by RmtChannel: a Pin object, raw GPIO number, or port name. */
+type RmtPin = Pin | number | string;
+
+/**
+ * RMT transceiver channel bound to a GPIO pin. One channel per pin; TX and RX
+ * are independent roles on the same channel object.
+ *
+ * ```ts
+ * const led = new RmtChannel(LED);
+ * led.txInit({ resolutionHz: 10_000_000, bit0: [4, 9], bit1: [9, 4] });
+ * led.txWriteBytes([0, 16, 0]);
+ * led.txWaitDone();
+ * ```
+ */
+export class RmtChannel {
+  private _pin: RmtPin;
+
+  constructor(pin: RmtPin) {
+    this._pin = pin;
+  }
+
+  // ── TX ─────────────────────────────────────────────────────────────────────
+  /** Initialize the channel for TX. Idempotent per pin. Bit timings are fixed
+   *  at init — ESP-IDF bakes them into the bytes-encoder and exposes no public
+   *  mutation API. Tick units are 1/resolutionHz seconds.
+   *
+   *  Args are positional scalars (not an opts object) because the transpiler's
+   *  method-body renderer folds scalar params but not property accesses on an
+   *  object param (opts.resolutionHz would render as a collapsed object + dead
+   *  property access). Mirrors how I2CBus.begin(address) takes a scalar. */
+  txInit(
+    resolutionHz: number,
+    bit0Hi: number, bit0Lo: number,
+    bit1Hi: number, bit1Lo: number,
+    msbFirst: boolean = false,
+    queueDepth: number = 4,
+  ): void {
+    rmtTxInit(
+      this._pin,
+      resolutionHz,
+      bit0Hi, bit0Lo,
+      bit1Hi, bit1Lo,
+      msbFirst,
+      queueDepth,
+    );
+  }
+
+  /** Write bytes via the channel's bytes-encoder (timings fixed at txInit). */
+  txWriteBytes(bytes: number[] | Uint8Array): void {
+    rmtTxWriteBytes(this._pin, bytes);
+  }
+
+  /** Write raw RMT symbols — arbitrary [hiTicks, loTicks] pairs. */
+  txWriteSymbols(symbols: [number, number][]): void {
+    rmtTxWriteSymbols(this._pin, symbols);
+  }
+
+  /** Block until the queued TX completes. */
+  txWaitDone(timeoutMs?: number): void {
+    rmtTxWaitDone(this._pin, timeoutMs);
+  }
+
+  /** Tear down the TX channel and release its slot. */
+  txDeinit(): void {
+    rmtTxDeinit(this._pin);
+  }
+
+  // ── RX ─────────────────────────────────────────────────────────────────────
+  /** Initialize the channel for RX. Idempotent per pin. */
+  rxInit(resolutionHz: number): void {
+    rmtRxInit(this._pin, resolutionHz);
+  }
+
+  /** Register a callback-by-name invoked when an RX burst completes. */
+  rxOnReceived(handler: string): void {
+    rmtRxOnReceived(this._pin, handler);
+  }
+
+  /** Start receiving. */
+  rxStart(): void {
+    rmtRxStart(this._pin);
+  }
+
+  /** Stop receiving. */
+  rxStop(): void {
+    rmtRxStop(this._pin);
+  }
+
+  /** Blocking read — returns flattened symbols [d0,l0,d1,l1,…] in ticks. */
+  rxRead(maxCount: number): number[] {
+    return rmtRxRead(this._pin, maxCount);
+  }
+
+  /** Tear down the RX channel and release its slot. */
+  rxDeinit(): void {
+    rmtRxDeinit(this._pin);
+  }
+}

package/src/wifi.ts

@@ -0,0 +1,225 @@
+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';
+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 {
+    wifiDisconnect();
+  }
+
+  isConnected(): boolean {
+    return wifiIsConnected();
+  }
+
+  status(): WiFiStatus {
+    return wifiStatus() as WiFiStatus;
+  }
+
+  localIP(): string {
+    return wifiLocalIp();
+  }
+
+  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;
+  }
+
+  autoReconnect(enabled: boolean): this {
+    wifiSetAutoReconnect(enabled);
+    return this;
+  }
+
+  powerSave(mode: "default" | "none"): this {
+    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: number): this {
+    wifiSetTxPower(dbm);
+    return this;
+  }
+
+  saveCredentials(ssid: string, password: string): void {
+    wifiSaveCredentials(ssid, password);
+  }
+
+  connectSaved(timeoutMs: number = 15000): boolean {
+    return wifiConnectSaved(timeoutMs);
+  }
+
+  clearCredentials(): void {
+    wifiClearCredentials();
+  }
+
+  onConnect(handler: () => void): void {
+    wifiOnEvent("connect", callback(handler));
+  }
+
+  onDisconnect(handler: () => void): void {
+    wifiOnEvent("disconnect", callback(handler));
+  }
+
+  onGotIP(handler: () => void): void {
+    wifiOnEvent("got_ip", callback(handler));
+  }
+
+  startAP(ssid: string, password?: string): boolean {
+    return wifiApStart(ssid, password);
+  }
+
+  apChannel(ch: number): this {
+    wifiApSetChannel(ch);
+    return this;
+  }
+
+  apHidden(hidden: boolean): this {
+    wifiApSetHidden(hidden);
+    return this;
+  }
+
+  apMaxClients(n: number): this {
+    wifiApSetMaxClients(n);
+    return this;
+  }
+
+  stopAP(): 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();