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

package/src/gpio-pin.ts

@@ -0,0 +1,91 @@
+// ---------------------------------------------------------------------------
+// GPIO — the thin Zephyr-shaped digital pin class
+//
+// One configured pin handle ≈ gpio_dt_spec + flags, mirroring Zephyr's verbs:
+// construction carries the flag combination (GPIO.OUTPUT | GPIO.PULL_UP),
+// set/get/toggle lower to gpio_pin_set_dt / get_dt / toggle_dt (logical
+// levels — polarity comes from the board's DT node when the pin has a dtSpec),
+// and the configure itself is emitted guarded-per-pin ahead of the first use,
+// so construction flags apply exactly once. No mode strings, no shadow reads.
+//
+// Flag and interrupt tokens are Zephyr's names under the GPIO. namespace
+// (GPIO_OUTPUT ↔ GPIO.OUTPUT, GPIO_INT_EDGE_FALLING ↔ GPIO.INT_EDGE_FALLING);
+// the lowering maps token NAMES to macros, so any Zephyr doc greps both ways.
+// ----------------------------------------------------------------------------
+
+import { gpioWrite, gpioReadCfg, gpioToggle, gpioConfigure, interruptAttachFlags, interruptDetach } from './emit.js';
+import { callback } from './callback.js';
+import type { Pin } from './gpio.js';
+
+export class GPIO {
+  // ── Config flags (gpio.h) ──────────────────────────────────────────────
+  static readonly INPUT = 0x001;
+  static readonly OUTPUT = 0x002;
+  /** Configure the output buffer's initial level atomically — no
+   *  configure-then-write glitch window. */
+  static readonly OUTPUT_INIT_LOW = 0x004;
+  static readonly OUTPUT_INIT_HIGH = 0x008;
+  static readonly PULL_UP = 0x010;
+  static readonly PULL_DOWN = 0x020;
+  static readonly OPEN_DRAIN = 0x040;
+  static readonly OPEN_SOURCE = 0x080;
+  static readonly DISCONNECTED = 0x100;
+
+  // ── Interrupt flags (GPIO_INT_* minus the prefix) ──────────────────────
+  static readonly INT_DISABLE = 0x01;
+  static readonly INT_EDGE_RISING = 0x02;
+  static readonly INT_EDGE_FALLING = 0x04;
+  static readonly INT_EDGE_BOTH = 0x08;
+  static readonly INT_LEVEL_LOW = 0x10;
+  static readonly INT_LEVEL_HIGH = 0x20;
+
+  private readonly _pin: number;
+  private readonly _flags: number;
+
+  /** Construct a configured pin. `flags` is a combination of the GPIO.*
+   *  statics (the transpiler carries the token text; the values are for the
+   *  editor only). The configure applies once, ahead of the first
+   *  set/get/toggle/onInterrupt call. */
+  constructor(pin: number | Pin, flags: number) {
+    this._pin = typeof pin === 'number' ? pin : pin.number;
+    this._flags = flags;
+  }
+
+  /** Drive the pin (gpio_pin_set_dt / set_raw). Logical level: on a pin with
+   *  a board dtSpec (LED, BUTTON), true means "active" — the DT node's
+   *  GPIO_ACTIVE_LOW is honored. */
+  set(value: boolean): void {
+    gpioConfigure(this._pin, this._flags);
+    gpioWrite(this._pin, value);
+  }
+
+  /** Read the pin (gpio_pin_get_dt / get_raw). Logical level. The guarded
+   *  configure is FUSED into the read's lowering (one statement-expression),
+   *  so the pin is correctly configured even when the call sits in a pure
+   *  expression position (if-conditions, comparisons) where a method's
+   *  leading side-effect ops would otherwise be dropped. */
+  get(): boolean {
+    return gpioReadCfg(this._pin, this._flags) as unknown as boolean;
+  }
+
+  /** Toggle the pin (gpio_pin_toggle_dt — the driver's atomic toggle). */
+  toggle(): void {
+    gpioConfigure(this._pin, this._flags);
+    gpioToggle(this._pin);
+  }
+
+  /** Attach an interrupt (gpio_pin_interrupt_configure_dt +
+   *  gpio_init_callback + gpio_add_callback). `intFlags` is one GPIO.INT_*
+   *  token — Zephyr's names verbatim, covering the level modes the legacy
+   *  onHigh/onLow strings could not express. */
+  onInterrupt(intFlags: number, handler: () => void): void {
+    gpioConfigure(this._pin, this._flags);
+    interruptAttachFlags(this._pin, callback(handler), intFlags);
+  }
+
+  /** Detach the interrupt (disable + remove callback). */
+  offInterrupt(): void {
+    interruptDetach(this._pin);
+  }
+}
+

package/src/gpio.ts

@@ -1,320 +1,49 @@
-import { gpioWrite, gpioRead, gpioToggle, gpioSetMode, tonePlay, toneStop, adcRead, adcReadVoltage, adcSetReference, interruptAttach, interruptDetach, pwmWrite, rawCpp, boardResolve } from './emit.js';
-import { callback } from './callback.js';
-import { ADC } from './adc.js';
-
-export class OutputPin {
-  private _pin: number;
-  readonly number: number;
-  readonly gpio: number;
-
-  constructor(pin: number) {
-    this._pin = pin;
-    this.number = pin;
-    this.gpio = pin;
-  }
-
-  high(): void {
-    gpioWrite(this._pin, 1);
-  }
-
-  low(): void {
-    gpioWrite(this._pin, 0);
-  }
-
-  toggle(): void {
-    gpioToggle(this._pin);
-  }
-
-  write(value: number | boolean): void {
-    gpioWrite(this._pin, value);
-  }
-
-  /**
-   * Returns the level the program last drove onto this output pin.
-   *
-   * The transpiler tracks every write (high/low/write/toggle and the
-   * asOutput initial value) and lowers this to a compile-time constant
-   * when the state is statically known, or to a tracked shadow variable
-   * the generated writes keep updated. No hardware pin read is performed —
-   * reading back an OUTPUT-only pin is not portable (e.g. Zephyr), so this
-   * reports software truth, not electrical truth.
-   */
-  read(): boolean {
-    return gpioRead(this._pin) as unknown as boolean;
-  }
-
-  isHigh(): boolean {
-    return this.read();
-  }
-
-  isLow(): boolean {
-    return !this.read();
-  }
-
-  pulse(durationMs: number): void {
-    gpioWrite(this._pin, 1);
-    rawCpp(`delay(${durationMs});`);
-    gpioWrite(this._pin, 0);
-  }
-
-  tone(frequency: number): ToneChain {
-    tonePlay(this._pin, frequency);
-    return new ToneChain(this._pin, frequency);
-  }
-
-  toneFor(frequency: number, duration: number): void {
-    tonePlay(this._pin, frequency, duration);
-  }
-
-  noTone(): void {
-    toneStop(this._pin);
-  }
-
-  pwm(duty: number): void {
-    pwmWrite(this._pin, duty);
-  }
-
-  getPwmFrequency(): number {
-    return boardResolve("peripherals.pwm.maxFrequency");
-  }
-
-  getPwmResolution(): number {
-    return boardResolve("peripherals.pwm.resolution");
-  }
-}
-
-export class InputPin {
-  private _pin: number;
-  readonly number: number;
-  readonly gpio: number;
-
-  constructor(pin: number) {
-    this._pin = pin;
-    this.number = pin;
-    this.gpio = pin;
-  }
-
-  read(): boolean {
-    return gpioRead(this._pin) as unknown as boolean;
-  }
-
-  isHigh(): boolean {
-    return this.read();
-  }
-
-  isLow(): boolean {
-    return !this.read();
-  }
-
-  readAnalog(): number {
-    return adcRead(this._pin);
-  }
-
-  readVoltage(): number {
-    return adcReadVoltage(this._pin);
-  }
-
-  getAnalogResolution(): number {
-    return boardResolve("peripherals.adc.0.resolution");
-  }
-
-  setAnalogReference(ref: string): void {
-    ADC._reference = ref;
-    adcSetReference(ref);
-  }
-
-  onFalling(handler: () => void): void {
-    interruptAttach(this._pin, callback(handler), "FALLING");
-  }
-
-  onRising(handler: () => void): void {
-    interruptAttach(this._pin, callback(handler), "RISING");
-  }
-
-  onChange(handler: () => void): void {
-    interruptAttach(this._pin, callback(handler), "CHANGE");
-  }
-
-  offAll(): void {
-    interruptDetach(this._pin);
-  }
-
-  /** Alias matching the BasePin.offInterrupts() interface name. */
-  offInterrupts(): void {
-    interruptDetach(this._pin);
-  }
-
-  /**
-   * Wait for a RISING edge on this input pin.
-   * Returns a Promise<void> that resolves when the pin transitions from LOW to HIGH.
-   * The platform strategy controls whether this uses interrupts, polling, or a stub.
-   *
-   * @param timeout Optional timeout in milliseconds. If provided, the promise
-   *   rejects (or resolves with a false/error) after the timeout expires.
-   */
-  waitForRising(timeout?: number): Promise<void> {
-    rawCpp(`__cuttlefish_wait_pin_edge(${this._pin}, RISING, ${timeout ?? -1});`);
-    return Promise.resolve();
-  }
-
-  /**
-   * Wait for a FALLING edge on this input pin.
-   * Returns a Promise<void> that resolves when the pin transitions from HIGH to LOW.
-   *
-   * @param timeout Optional timeout in milliseconds. If provided, the promise
-   *   rejects (or resolves with a false/error) after the timeout expires.
-   */
-  waitForFalling(timeout?: number): Promise<void> {
-    rawCpp(`__cuttlefish_wait_pin_edge(${this._pin}, FALLING, ${timeout ?? -1});`);
-    return Promise.resolve();
-  }
-}
-
-export class ToneChain {
-  private _pin: number;
-  private _lastFreq: number;
-
-  constructor(pin: number, frequency: number) {
-    this._pin = pin;
-    this._lastFreq = frequency;
-  }
-
-  for(duration: number): void {
-    tonePlay(this._pin, this._lastFreq, duration);
-  }
-}
-
-/**
- * Represents a physical hardware pin before it has been configured for a specific mode.
- * Use `.asInput()` or `.asOutput()` to obtain a functional pin instance.
- *
- * Pins can be created two ways:
- * - `new Pin(number)` — legacy, using framework pin number (e.g. Arduino pin 13)
- * - `Pin.fromPort("PB5")` — preferred, using MCU datasheet port name
- *
- * When created via `fromPort()`, the pin carries its canonical port identity.
- * The transpiler resolves the port name to a framework pin number at compile time
- * using the MCU package's pin mapping (e.g. arduino-map.ts).
- */
-export class Pin {
-  /** MCU port name (e.g. "PB5") — empty string for legacy numeric pins */
-  private _port: string;
-  /** Framework pin number (e.g. 13 for Arduino). -1 for port-based pins. */
-  private _pin: number;
-  /** Public readonly access to port name */
-  readonly port: string;
-  readonly number: number;
-  readonly gpio: number;
-
-  /** Legacy constructor — creates a Pin from a framework pin number */
-  constructor(pin: number) {
-    this._port = '';
-    this._pin = pin;
-    this.port = '';
-    this.number = pin;
-    this.gpio = pin;
-  }
-
-  /**
-   * Create a Pin from its MCU datasheet port name (e.g. "PB5", "PC0").
-   * The port name is the canonical identity; framework-specific pin numbers
-   * are resolved at transpile time via the MCU package's pin mapping.
-   */
-  static fromPort(portName: string): Pin {
-    const p = new Pin(-1);
-    p._port = portName;
-    // Bypass readonly for factory method
-    (p as any).port = portName;
-    return p;
-  }
-
-  asOutput(initial?: number | boolean): OutputPin {
-    gpioSetMode(this._pin, "OUTPUT");
-    if (initial !== undefined) {
-      gpioWrite(this._pin, initial);
-    }
-    // Returns `this` so the transpiler can suppress the C++ return emission
-    // (it resolves `this` to the same instance and tracks the result as an
-    // OutputPin via the method name). Returning `new OutputPin(this._pin)`
-    // would leak the literal text into generated C++. The cast is required
-    // because Pin and OutputPin are structurally distinct classes; the
-    // transpiler handles the mode transition semantically.
-    return this as unknown as OutputPin;
-  }
-
-  /** Alias for asOutput() — shorter fluent form. */
-  output(initial?: number | boolean): OutputPin {
-    gpioSetMode(this._pin, "OUTPUT");
-    if (initial !== undefined) {
-      gpioWrite(this._pin, initial);
-    }
-    return this as unknown as OutputPin;
-  }
-
-  asInput(): InputPin {
-    gpioSetMode(this._pin, "INPUT");
-    return this as unknown as InputPin;
-  }
-
-  asInputPullUp(): InputPin {
-    gpioSetMode(this._pin, "INPUT_PULLUP");
-    return this as unknown as InputPin;
-  }
-
-  asInputPullDown(): InputPin {
-    gpioSetMode(this._pin, "INPUT_PULLDOWN");
-    return this as unknown as InputPin;
-  }
-
-  inputPullUp(): InputPin {
-    gpioSetMode(this._pin, "INPUT_PULLUP");
-    return this as unknown as InputPin;
-  }
-
-  /** Alias for asInputPullDown() — shorter fluent form. */
-  inputPullDown(): InputPin {
-    gpioSetMode(this._pin, "INPUT_PULLDOWN");
-    return this as unknown as InputPin;
-  }
-
-  read(): boolean {
-    return gpioRead(this._pin) as unknown as boolean;
-  }
-
-  isHigh(): boolean {
-    return this.read();
-  }
-
-  isLow(): boolean {
-    return !this.read();
-  }
-
-  write(value: number | boolean): void {
-    gpioWrite(this._pin, value);
-  }
-
-  high(): void {
-    gpioWrite(this._pin, 1);
-  }
-
-  low(): void {
-    gpioWrite(this._pin, 0);
-  }
-
-  toggle(): void {
-    gpioToggle(this._pin);
-  }
-
-  pwm(duty: number): void {
-    pwmWrite(this._pin, duty);
-  }
-
-  tone(frequency: number): ToneChain {
-    tonePlay(this._pin, frequency);
-    return new ToneChain(this._pin, frequency);
-  }
-
-  noTone(): void {
-    toneStop(this._pin);
-  }
-}
+// ---------------------------------------------------------------------------
+// Pin — the board-addressable pin identity (legacy GPIO classes removed)
+//
+// A Pin carries its canonical datasheet port name (Pin.fromPort("PB5")) and/or
+// framework pin number; the transpiler resolves it via the MCU package's pin
+// mapping. It is an ADDRESS, not a configured peripheral — configure pins by
+// constructing the thin peripherals with them:
+//
+//   new GPIO(PB5, GPIO.OUTPUT | GPIO.PULL_UP)
+//   new PWM(PA5, { periodNs: 20_000_000 })
+//   new ADC(A1)
+//
+// The former OutputPin/InputPin/ToneChain classes (and their as*/read/write/
+// pwm methods) were removed with the legacy Arduino surface. Their thin
+// replacements are gpio-pin.ts / pwm-pin.ts / adc-pin.ts.
+// ---------------------------------------------------------------------------
+
+export class Pin {
+  /** MCU port name (e.g. "PB5") — empty string for legacy numeric pins */
+  private _port: string;
+  /** Framework pin number (e.g. 13 for Arduino). -1 for port-based pins. */
+  private _pin: number;
+  /** Public readonly access to port name */
+  readonly port: string;
+  readonly number: number;
+  readonly gpio: number;
+
+  /** Legacy constructor — creates a Pin from a framework pin number */
+  constructor(pin: number) {
+    this._port = '';
+    this._pin = pin;
+    this.port = '';
+    this.number = pin;
+    this.gpio = pin;
+  }
+
+  /**
+   * Create a Pin from its MCU datasheet port name (e.g. "PB5", "PC0").
+   * The port name is the canonical identity; framework-specific pin numbers
+   * are resolved at transpile time via the MCU package's pin mapping.
+   */
+  static fromPort(portName: string): Pin {
+    const p = new Pin(-1);
+    p._port = portName;
+    // Bypass readonly for factory method
+    (p as any).port = portName;
+    return p;
+  }
+}

package/src/http.ts

@@ -1,9 +1,31 @@
+// ---------------------------------------------------------------------------
+// Request — the thin HTTP/S client
+//
+// The request is CONSTRUCTION facts: method, URL, and the policy opts
+// (timeout, body, TLS mode) ride the constructor; headers attach with the
+// header() chain; send() lowers the facts into the shim and performs the
+// request; the response is read from this request afterwards (the shim
+// holds the response until the next request).
+//
+//   const req = new Request(Request.POST, url, {
+//     timeoutMs: 10_000,
+//     body: '{"v":1}', json: true,
+//     caCert: PEM,            // pin a CA (verified TLS)
+//   });
+//   req.header('X-Custom', 'v');
+//   if (req.send()) { console.log(req.status()); }
+//
+// Method tokens: Request.GET / POST / PUT / DELETE / HEAD / PATCH (plain
+// 'GET' strings also accepted). `insecure: true` skips TLS certificate
+// verification (development only). Awaiting send() inside async functions
+// still splits into a background request + done-poll (the async machinery
+// intercepts the send op; the facts were already lowered at send()).
+// ----------------------------------------------------------------------------
+
 import {
   httpBegin,
-  httpReset,
   httpSetHeader,
   httpSetTimeout,
-  httpSetMaxBody,
   httpSetBody,
   httpSetInsecure,
   httpSetCaCert,
@@ -15,80 +37,71 @@ import {
   httpResponseHeader,
 } from './emit.js';
 
-export enum HttpMethod {
-  GET = 0,
-  POST = 1,
-  PUT = 2,
-  DELETE = 3,
-  HEAD = 4,
-  PATCH = 5,
+/** Request construction facts beyond method + URL. */
+export interface RequestOpts {
+  /** Response timeout in ms (default 10_000). */
+  timeoutMs?: number;
+  /** Request body (raw). */
+  body?: string;
+  /** The body is JSON — sets the JSON content type. */
+  json?: boolean;
+  /** Skip TLS certificate verification (development only). */
+  insecure?: boolean;
+  /** PEM of a trusted CA — enables verified TLS. */
+  caCert?: string;
 }
 
-/**
- * Fluent HTTP/S request builder, lowered to native ESP-IDF
- * `esp_http_client` by framework-esp32 (TLS via esp-tls / mbedTLS bundle).
- * Response fields are read from this object after send() — mirrors
- * `await WiFi.connect(); WiFi.localIP()`.
- *
- * No `include()` calls here — ESP-IDF headers are framework-owned and added
- * via forcedIncludes when the program uses http.* ops.
- */
-export class HttpRequest {
-  private _method: string;
-  private _url: string;
-
-  constructor(method: string, url: string) {
-    this._method = method;
+export class Request {
+  static readonly GET = 'GET';
+  static readonly POST = 'POST';
+  static readonly PUT = 'PUT';
+  static readonly DELETE = 'DELETE';
+  static readonly HEAD = 'HEAD';
+  static readonly PATCH = 'PATCH';
+
+  private readonly _method: string;
+  private readonly _url: string;
+  private readonly _timeoutMs: number;
+  private readonly _body: string;
+  private readonly _json: boolean;
+  private readonly _insecure: boolean;
+  private readonly _caCert: string;
+
+  constructor(method: string, url: string, opts: RequestOpts = {}) {
+    this._method = method.toUpperCase();
     this._url = url;
+    this._timeoutMs = opts.timeoutMs ?? 10_000;
+    this._body = opts.body ?? '';
+    this._json = opts.json === true;
+    this._insecure = opts.insecure === true;
+    this._caCert = opts.caCert ?? '';
   }
 
+  /** Attach a request header. Chainable — one per header. */
   header(name: string, value: string): this {
     httpSetHeader(name, value);
     return this;
   }
 
-  timeout(ms: number): this {
-    httpSetTimeout(ms);
-    return this;
-  }
-
-  maxBody(bytes: number): this {
-    httpSetMaxBody(bytes);
-    return this;
-  }
-
-  body(data: string): this {
-    httpSetBody(data, false);
-    return this;
-  }
-
-  jsonBody(json: string): this {
-    httpSetBody(json, true);
-    return this;
-  }
-
-  /** Skip TLS certificate verification (development only). */
-  insecure(): this {
-    httpSetInsecure();
-    return this;
-  }
-
-  caCert(pem: string): this {
-    httpSetCaCert(pem);
-    return this;
-  }
-
-  /** Blocking at top level; cooperatively awaitable inside async functions. */
-  send(): Promise<boolean> {
+  /** Send the request (blocking). The construction facts lower into the
+   *  shim first (timeout/body/TLS mode), then the request performs.
+   *  Awaitable inside async functions — the async machinery splits the
+   *  send into a background request + done-poll. */
+  send(): boolean {
+    httpSetTimeout(this._timeoutMs);
+    httpSetBody(this._body, this._json);
+    httpSetInsecure(this._insecure);
+    httpSetCaCert(this._caCert);
     httpBegin(this._method, this._url);
-    httpSend();
-    return Promise.resolve(false);
+    return httpSend();
   }
 
+  /** Response status code (0 before a completed send). */
   status(): number {
     return httpStatus();
   }
 
+  /** True when the response status is 2xx. */
   ok(): boolean {
     return httpOk();
   }
@@ -98,47 +111,14 @@ export class HttpRequest {
     return httpBody();
   }
 
+  /** Response Content-Length (0 when absent). */
   contentLength(): number {
     return httpContentLength();
   }
 
+  /** One response header value ("" when absent; valid until the next
+   *  request). */
   responseHeader(name: string): string {
     return httpResponseHeader(name);
   }
 }
-
-export class HttpClass {
-  static readonly __instance_name = "Http";
-
-  get(url: string): HttpRequest {
-    httpReset();
-    return new HttpRequest("GET", url);
-  }
-
-  post(url: string): HttpRequest {
-    httpReset();
-    return new HttpRequest("POST", url);
-  }
-
-  put(url: string): HttpRequest {
-    httpReset();
-    return new HttpRequest("PUT", url);
-  }
-
-  del(url: string): HttpRequest {
-    httpReset();
-    return new HttpRequest("DELETE", url);
-  }
-
-  head(url: string): HttpRequest {
-    httpReset();
-    return new HttpRequest("HEAD", url);
-  }
-
-  patch(url: string): HttpRequest {
-    httpReset();
-    return new HttpRequest("PATCH", url);
-  }
-}
-
-export const Http = new HttpClass();