@typecad/hal 0.1.0-alpha.2 → 1.0.0-alpha.11

package/dist/wifi.d.ts

@@ -0,0 +1,67 @@
+/** 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 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 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;
+}
+export declare const WiFi: WiFiClass;

package/dist/wifi.js

@@ -0,0 +1,151 @@
+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 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() {
+        wifiDisconnect();
+    }
+    isConnected() {
+        return wifiIsConnected();
+    }
+    status() {
+        return wifiStatus();
+    }
+    localIP() {
+        return wifiLocalIp();
+    }
+    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;
+    }
+    stopAP() {
+        wifiApStop();
+    }
+    apClientCount() {
+        return wifiApClientCount();
+    }
+    apIP() {
+        return wifiApIp();
+    }
+    scan() {
+        return wifiScan();
+    }
+    scanAsync() {
+        wifiScanStart();
+        return Promise.resolve();
+    }
+    scanCount() {
+        return wifiScanCount();
+    }
+    scanSSID(i) {
+        return wifiScanSsid(i);
+    }
+    scanRSSI(i) {
+        return wifiScanRssi(i);
+    }
+    scanEncryption(i) {
+        return wifiScanEncryption(i);
+    }
+    scanChannel(i) {
+        return wifiScanChannel(i);
+    }
+}
+WiFiClass.__instance_name = "WiFi";
+export const WiFi = new WiFiClass();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typecad/hal",
-  "version": "0.1.0-alpha.2",
+  "version": "1.0.0-alpha.11",
   "description": "TypeCAD hardware abstraction layer — GPIO, I2C, SPI, UART as regular TypeScript",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,7 +13,8 @@
     "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:basics": "npm exec -- cuttlefish-test tests/01-gpio.test.ts",
+    "test:hw:preferences": "npm exec -- cuttlefish-test tests/14-preferences.test.ts"
   },
   "license": "MIT",
   "publishConfig": {
@@ -49,9 +50,9 @@
   },
   "author": "typecad0",
   "devDependencies": {
-    "@typecad/expect": "0.1.0-alpha.2",
-    "@typecad/board-arduino-uno": "0.1.0-alpha.2",
-    "@typecad/mcu-atmega328p": "0.1.0-alpha.2"
+    "@typecad/expect": "1.0.0-alpha.11",
+    "@typecad/board-arduino-uno": "1.0.0-alpha.11",
+    "@typecad/mcu-atmega328p": "1.0.0-alpha.11"
   },
   "sideEffects": false,
   "exports": {

package/src/ble.ts

@@ -0,0 +1,209 @@
+import {
+  bleServerBegin,
+  bleAdvertiseStart,
+  bleAdvertiseStop,
+  bleAddService,
+  bleAddChar,
+  bleOnRead,
+  bleOnWrite,
+  bleOnConnect,
+  bleOnDisconnect,
+  bleNotify,
+  bleIsConnected,
+  bleClientCount,
+  bleSetName,
+  bleUntilConnected,
+  bleUntilConnectedStart,
+  bleSetTxPower,
+  bleStatus,
+} from './emit.js';
+import { callback } from './callback.js';
+
+/** Characteristic value encoding — drives both TS callback types and C++ marshalling. */
+export enum BleValueType {
+  Uint8 = 'uint8',
+  Uint16 = 'uint16',
+  Uint32 = 'uint32',
+  Int8 = 'int8',
+  Int16 = 'int16',
+  Int32 = 'int32',
+  Float32 = 'float32',
+  Utf8 = 'utf8',
+  Boolean = 'boolean',
+  Bytes = 'bytes',
+}
+
+/** GATT characteristic permission flags. Combine with `|`. */
+export enum BlePerm {
+  Read = 1,
+  Write = 2,
+  Notify = 4,
+}
+
+/** BLE peripheral status (mirrored by the runtime shim). */
+export enum BleStatus {
+  Idle = 0,
+  Initializing = 1,
+  Advertising = 2,
+  Connected = 3,
+  Error = 4,
+}
+
+export enum BleAdvertisingMode {
+  Connectable = 'connectable',
+  NonConnectable = 'non_connectable',
+}
+
+/** A well-known GATT characteristic entry in the catalog. */
+export interface GattCharacteristicDef {
+  readonly uuid: string;
+  readonly type: BleValueType;
+  readonly read?: boolean;
+  readonly write?: boolean;
+  readonly notify?: boolean;
+}
+
+/**
+ * Standard GATT services/characteristics. Autocomplete walks the hierarchy:
+ *   GATT.ENVIRONMENTAL. -> TEMPERATURE, HUMIDITY, ...
+ * Pass the .uuid, .type, and computed perms to BleServer.characteristic().
+ */
+export const GATT = {
+  DEVICE_INFO: {
+    MANUFACTURER_NAME: { uuid: '2A29', type: BleValueType.Utf8, read: true },
+    MODEL_NUMBER: { uuid: '2A24', type: BleValueType.Utf8, read: true },
+    FIRMWARE_REVISION: { uuid: '2A26', type: BleValueType.Utf8, read: true },
+  },
+  ENVIRONMENTAL: {
+    TEMPERATURE: { uuid: '2A6E', type: BleValueType.Int16, read: true, notify: true },
+    HUMIDITY: { uuid: '2A6F', type: BleValueType.Uint16, read: true, notify: true },
+    PRESSURE: { uuid: '2A6D', type: BleValueType.Uint32, read: true, notify: true },
+  },
+  BATTERY: {
+    LEVEL: { uuid: '2A19', type: BleValueType.Uint8, read: true, notify: true },
+  },
+} as const;
+
+/** The value passed to/from callbacks — narrowed per characteristic by type. */
+export type CharValue = number | string | boolean | Uint8Array;
+
+/**
+ * BLE GATT peripheral control, lowered to native ESP-IDF NimBLE
+ * (`nimble_host` / `ble_gap` / `ble_gatts`) by framework-esp32.
+ *
+ * No `include()` calls here — NimBLE headers are framework-owned and added via
+ * forcedIncludes when the program uses ble.* ops.
+ *
+ * Transpiler note: method bodies pass parameters directly into semantic calls
+ * (no local consts / module counters) so the resolver can statically track every
+ * argument. The characteristic index is carried through the chain via
+ * `this._charCount` fieldValues, mirroring how HttpRequest carries _method/_url.
+ */
+export class BleClass {
+  static readonly __instance_name = "Ble";
+
+  /** Begin building a GATT server with the given advertised device name. */
+  server(name: string): BleServer {
+    bleSetName(name);
+    return new BleServer(name, 0, 1);
+  }
+
+  /** Initialize NimBLE, register services, and start advertising. */
+  begin(): void {
+    bleServerBegin("TypeCAD");
+    bleAdvertiseStart();
+  }
+
+  advertise(): void { bleAdvertiseStart(); }
+  stopAdvertising(): void { bleAdvertiseStop(); }
+
+  /** Blocking at top level; cooperatively awaitable inside async functions. */
+  untilConnected(timeoutMs: number = 0): Promise<boolean> {
+    bleUntilConnected(timeoutMs);
+    return Promise.resolve(false);
+  }
+
+  untilConnectedStart(): void { bleUntilConnectedStart(); }
+  isConnected(): boolean { return bleIsConnected(); }
+  status(): BleStatus { return bleStatus() as BleStatus; }
+  clientCount(): number { return bleClientCount(); }
+  txPower(dbm: number): this { bleSetTxPower(dbm); return this; }
+  notify(index: number, value: number): void { bleNotify(index, value); }
+}
+
+/**
+ * Fluent GATT server builder. Returned by `Ble.server()`.
+ *
+ * Single-class fluent chain (like HttpRequest): characteristic() returns `this`,
+ * so onRead/onWrite/onSubscribe chain directly. The _charCount field tracks
+ * which characteristic slot the callbacks attach to.
+ *
+ * Field tracking (read by the transpiler resolver via ctor field assignment):
+ *   _name      — advertised device name
+ *   _charCount — current characteristic index (the last characteristic() target)
+ *   _svcCount  — current service index
+ */
+export class BleServer {
+  private _name: string;
+  private _charCount: number;
+  private _lastChar: number;
+  private _svcCount: number;
+
+  constructor(name: string, charCount: number, svcCount: number) {
+    this._name = name;
+    this._charCount = charCount;
+    this._lastChar = charCount;
+    this._svcCount = svcCount;
+  }
+
+  /** Add a characteristic by UUID, value type, and permissions.
+   *  Combine permissions with `|`: `BlePerm.Read | BlePerm.Notify`.
+   *  Returns this for chaining. */
+  characteristic(uuid: string, type: BleValueType, perms: number): this {
+    bleAddChar(this._charCount, uuid, type, perms, this._svcCount);
+    return this;
+  }
+
+  /** Begin a new service grouping. Subsequent characteristics attach to it. */
+  service(uuid: string): this {
+    bleAddService(uuid);
+    return this;
+  }
+
+  /** Register a read handler for the most recently added characteristic. */
+  onRead(handler: () => CharValue): this {
+    bleOnRead(this._lastChar, callback(handler));
+    return this;
+  }
+
+  /** Register a write handler for the most recently added characteristic. */
+  onWrite(handler: (value: number) => void): this {
+    bleOnWrite(this._lastChar, callback(handler));
+    return this;
+  }
+
+  /** Register a connect handler (called when a central connects). */
+  onConnect(handler: () => void): this {
+    bleOnConnect(callback(handler));
+    return this;
+  }
+
+  /** Register a disconnect handler (called when a central disconnects). */
+  onDisconnect(handler: () => void): this {
+    bleOnDisconnect(callback(handler));
+    return this;
+  }
+
+  /** Push a new value to subscribed clients on the most recently added characteristic. */
+  notify(value: number): void {
+    bleNotify(this._lastChar, value);
+  }
+
+  /** Initialize NimBLE, register services, and start advertising. */
+  begin(): void {
+    bleServerBegin(this._name);
+    bleAdvertiseStart();
+  }
+}
+
+export const Ble = new BleClass();

package/src/capacitive.ts

@@ -0,0 +1,31 @@
+/**
+ * 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; }