@typecad/hal 0.1.0-alpha.1

package/dist/emit.js

@@ -0,0 +1,177 @@
+// ---------------------------------------------------------------------------
+// HAL compile-time semantic functions
+//
+// These functions are resolved to HALOpIR nodes by the transpiler's HAL
+// resolver.  The framework strategy translates each operation into
+// framework-specific C++ at code generation time.
+//
+// Pin parameters accept both `number` (legacy framework pin number) and
+// `string` (MCU port name like "PB5"). The transpiler resolves port names
+// to framework pin numbers via the MCU package's pin mapping.
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// GPIO — digital pin control
+// ---------------------------------------------------------------------------
+/** Set a digital pin HIGH or LOW. */
+export function gpioWrite(pin, value) { }
+/** Read a digital pin. Returns HIGH (1) or LOW (0). */
+export function gpioRead(pin) { return 0; }
+/** Toggle a digital pin. */
+export function gpioToggle(pin) { }
+/** Set pin mode: "output" | "input" | "input_pullup" | "input_pulldown". */
+export function gpioSetMode(pin, mode) { }
+// ---------------------------------------------------------------------------
+// PWM — pulse-width modulation
+// ---------------------------------------------------------------------------
+/** Write PWM duty cycle to a pin. */
+export function pwmWrite(pin, duty) { }
+// ---------------------------------------------------------------------------
+// ADC — analog-to-digital conversion
+// ---------------------------------------------------------------------------
+/** Read analog value from a pin. */
+export function adcRead(pin) { return 0; }
+/** Read analog voltage from a pin (ADC value converted to voltage). */
+export function adcReadVoltage(pin) { return 0; }
+/** Set the analog reference. */
+export function adcSetReference(ref) { }
+// ---------------------------------------------------------------------------
+// Interrupts
+// ---------------------------------------------------------------------------
+/** Attach an interrupt handler to a pin. */
+export function interruptAttach(pin, handler, mode) { }
+/** Detach an interrupt from a pin. */
+export function interruptDetach(pin) { }
+// ---------------------------------------------------------------------------
+// Tone / audio output
+// ---------------------------------------------------------------------------
+/** Play a tone on a pin at the given frequency, optionally for a duration. */
+export function tonePlay(pin, frequency, duration) { }
+/** Stop tone playback on a pin. */
+export function toneStop(pin) { }
+// ---------------------------------------------------------------------------
+// Timing
+// ---------------------------------------------------------------------------
+/** Delay for the given number of milliseconds. */
+export function delayMs(ms) { }
+/** Delay for the given number of microseconds. */
+export function delayMicro(us) { }
+/** Get milliseconds since boot. */
+export function getMillis() { return 0; }
+/** Get microseconds since boot. */
+export function getMicros() { return 0; }
+/** Get free heap bytes. Architecture-aware: the strategy maps this to the right
+ *  symbol per target (ESP.getFreeHeap() on ESP32, __heap_start trick on AVR). */
+export function getFreeHeap() { return 0; }
+// ---------------------------------------------------------------------------
+// I2C — inter-integrated circuit bus
+// ---------------------------------------------------------------------------
+/** Initialize I2C bus (master mode if no address, slave mode with address). */
+export function i2cBegin(bus, address) { }
+/** Disable I2C bus. */
+export function i2cEnd(bus) { }
+/** Set I2C bus clock speed. */
+export function i2cSetClock(bus, hz) { }
+/** Begin I2C transmission to a slave address. */
+export function i2cBeginTx(bus, address) { }
+/** Write data to I2C bus. */
+export function i2cWrite(bus, data) { }
+/** Write a byte buffer to I2C bus (expands array literals to per-byte writes). */
+export function i2cWriteBuffer(bus, data) { }
+/** End I2C transmission. Returns status. */
+export function i2cEndTx(bus, stop) { return 0; }
+/** Request bytes from I2C slave. */
+export function i2cRequestFrom(bus, address, quantity, stop) { return 0; }
+/** Check if bytes are available from I2C. */
+export function i2cAvailable(bus) { return 0; }
+/** Read a byte from I2C. */
+export function i2cRead(bus) { return 0; }
+// ---------------------------------------------------------------------------
+// SPI — serial peripheral interface
+// ---------------------------------------------------------------------------
+/** Initialize SPI bus. */
+export function spiBegin(bus) { }
+/** Disable SPI bus. */
+export function spiEnd(bus) { }
+/** Transfer data on SPI bus. */
+export function spiTransfer(bus, data) { return 0; }
+/** Begin SPI transaction with settings. */
+export function spiBeginTx(bus, settings) { }
+/** End SPI transaction. */
+export function spiEndTx(bus) { }
+/** Set SPI chip-select pin LOW. */
+export function spiCsLow(pin) { }
+/** Set SPI chip-select pin HIGH. */
+export function spiCsHigh(pin) { }
+/** Set SPI data mode. */
+export function spiSetMode(bus, mode) { }
+/** Set SPI bit order. */
+export function spiSetBitOrder(bus, order) { }
+// ---------------------------------------------------------------------------
+// UART — serial communication
+// ---------------------------------------------------------------------------
+/** Initialize serial port with baud rate. */
+export function uartBegin(port, baud) { }
+/** Disable serial port. */
+export function uartEnd(port) { }
+/** Print value to serial. */
+export function uartPrint(port, value) { }
+/** Print value with newline to serial. */
+export function uartPrintln(port, value) { }
+/** printf-style formatted print to serial. */
+export function uartPrintf(port, format, args) { }
+/** Write raw data to serial. */
+export function uartWrite(port, data) { }
+/** Read a byte from serial. */
+export function uartRead(port) { return 0; }
+/** Peek at next byte from serial without consuming. */
+export function uartPeek(port) { return 0; }
+/** Check if bytes are available from serial. */
+export function uartAvailable(port) { return 0; }
+/** Flush serial output. */
+export function uartFlush(port) { }
+// ---------------------------------------------------------------------------
+// Pulse measurement
+// ---------------------------------------------------------------------------
+/** Measure pulse duration on a pin. */
+export function pulseIn_(pin, value, timeout) { return 0; }
+/** Measure long pulse using high-precision timer. */
+export function pulseInLong_(pin, value) { return 0; }
+// ---------------------------------------------------------------------------
+// Shift register
+// ---------------------------------------------------------------------------
+/** Shift a byte out to a pin. */
+export function shiftOut_(dataPin, clockPin, bitOrder, value) { }
+/** Shift a byte in from a pin. */
+export function shiftIn_(dataPin, clockPin, bitOrder) { return 0; }
+// ---------------------------------------------------------------------------
+// Board constant resolution
+// ---------------------------------------------------------------------------
+/** Write a value to a DAC pin. */
+export function dacWrite(pin, value) { }
+// ---------------------------------------------------------------------------
+// Watchdog timer (WDT)
+// ---------------------------------------------------------------------------
+/** Enable the watchdog timer with the given timeout (string preset or number). */
+export function wdtEnable(timeout) { }
+/** Reset (kick) the watchdog timer. */
+export function wdtReset() { }
+/** Disable the watchdog timer. */
+export function wdtDisable() { }
+/** Resolve a board definition path to a compile-time constant. */
+export function boardResolve(path) { return undefined; }
+// ---------------------------------------------------------------------------
+// Power — MCU power states and clock frequency
+// ---------------------------------------------------------------------------
+/** Enter deep sleep for the given duration (ms). Architecture-aware: the
+ *  strategy emits the right call per target (esp_deep_sleep on ESP32, a
+ *  not-supported comment elsewhere). */
+export function powerDeepSleep(ms) { }
+/** Enter light sleep. Architecture-aware. */
+export function powerLightSleep() { }
+/** Set the CPU frequency (MHz). */
+export function powerSetCpuFrequency(mhz) { }
+// ---------------------------------------------------------------------------
+// Raw C++ escape hatch
+// ---------------------------------------------------------------------------
+/** Emit raw C++ code (escape hatch for unsupported operations). */
+export function rawCpp(code) { }

package/dist/fs.d.ts

@@ -0,0 +1,13 @@
+/**
+ * FSClass provides a high-level abstraction for filesystem operations.
+ * Maps to SD.h or LittleFS depending on the board configuration.
+ */
+export declare class FSClass {
+    static readonly __instance_name = "FS";
+    begin(): boolean;
+    readText(path: string): string;
+    writeText(path: string, content: string): void;
+    exists(path: string): boolean;
+    remove(path: string): boolean;
+}
+export declare const FS: FSClass;

package/dist/fs.js

@@ -0,0 +1,39 @@
+import { rawCpp } from './emit.js';
+import { include } from './include.js';
+/**
+ * FSClass provides a high-level abstraction for filesystem operations.
+ * Maps to SD.h or LittleFS depending on the board configuration.
+ */
+export class FSClass {
+    begin() {
+        include("<FS.h>");
+        rawCpp(`return FS.begin();`);
+        return true;
+    }
+    readText(path) {
+        include("<FS.h>");
+        rawCpp(`File f = FS.open(${path}.c_str(), "r");`);
+        rawCpp(`if (!f) return "";`);
+        rawCpp(`String s = f.readString();`);
+        rawCpp(`f.close();`);
+        rawCpp(`return s.c_str();`);
+        return "";
+    }
+    writeText(path, content) {
+        include("<FS.h>");
+        rawCpp(`File f = FS.open(${path}.c_str(), "w");`);
+        rawCpp(`if (f) { f.print(${content}.c_str()); f.close(); }`);
+    }
+    exists(path) {
+        include("<FS.h>");
+        rawCpp(`return FS.exists(${path}.c_str());`);
+        return false;
+    }
+    remove(path) {
+        include("<FS.h>");
+        rawCpp(`return FS.remove(${path}.c_str());`);
+        return false;
+    }
+}
+FSClass.__instance_name = "FS";
+export const FS = new FSClass();

package/dist/gpio.d.ts

@@ -0,0 +1,108 @@
+export declare class OutputPin {
+    private _pin;
+    readonly number: number;
+    readonly gpio: number;
+    constructor(pin: number);
+    high(): void;
+    low(): void;
+    toggle(): void;
+    write(value: number | boolean): void;
+    pulse(durationMs: number): void;
+    tone(frequency: number): ToneChain;
+    toneFor(frequency: number, duration: number): void;
+    noTone(): void;
+    pwm(duty: number): void;
+    getPwmFrequency(): number;
+    getPwmResolution(): number;
+}
+export declare class InputPin {
+    private _pin;
+    readonly number: number;
+    readonly gpio: number;
+    constructor(pin: number);
+    read(): boolean;
+    isHigh(): boolean;
+    isLow(): boolean;
+    readAnalog(): number;
+    readVoltage(): number;
+    getAnalogResolution(): number;
+    setAnalogReference(ref: string): void;
+    onFalling(handler: () => void): void;
+    onRising(handler: () => void): void;
+    onChange(handler: () => void): void;
+    offAll(): void;
+    /** Alias matching the BasePin.offInterrupts() interface name. */
+    offInterrupts(): void;
+    /**
+     * 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>;
+    /**
+     * 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>;
+}
+export declare class ToneChain {
+    private _pin;
+    private _lastFreq;
+    constructor(pin: number, frequency: number);
+    for(duration: number): void;
+}
+/**
+ * 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 declare class Pin {
+    /** MCU port name (e.g. "PB5") — empty string for legacy numeric pins */
+    private _port;
+    /** Framework pin number (e.g. 13 for Arduino). -1 for port-based pins. */
+    private _pin;
+    /** 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);
+    /**
+     * 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;
+    asOutput(initial?: number | boolean): OutputPin;
+    /** Alias for asOutput() — shorter fluent form. */
+    output(initial?: number | boolean): OutputPin;
+    asInput(): InputPin;
+    asInputPullUp(): InputPin;
+    asInputPullDown(): InputPin;
+    inputPullUp(): InputPin;
+    /** Alias for asInputPullDown() — shorter fluent form. */
+    inputPullDown(): InputPin;
+    read(): boolean;
+    isHigh(): boolean;
+    isLow(): boolean;
+    write(value: number | boolean): void;
+    high(): void;
+    low(): void;
+    toggle(): void;
+    pwm(duty: number): void;
+    tone(frequency: number): ToneChain;
+    noTone(): void;
+}

package/dist/gpio.js

@@ -0,0 +1,230 @@
+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 {
+    constructor(pin) {
+        this._pin = pin;
+        this.number = pin;
+        this.gpio = pin;
+    }
+    high() {
+        gpioWrite(this._pin, 1);
+    }
+    low() {
+        gpioWrite(this._pin, 0);
+    }
+    toggle() {
+        gpioToggle(this._pin);
+    }
+    write(value) {
+        gpioWrite(this._pin, value);
+    }
+    pulse(durationMs) {
+        gpioWrite(this._pin, 1);
+        rawCpp(`delay(${durationMs});`);
+        gpioWrite(this._pin, 0);
+    }
+    tone(frequency) {
+        tonePlay(this._pin, frequency);
+        return new ToneChain(this._pin, frequency);
+    }
+    toneFor(frequency, duration) {
+        tonePlay(this._pin, frequency, duration);
+    }
+    noTone() {
+        toneStop(this._pin);
+    }
+    pwm(duty) {
+        pwmWrite(this._pin, duty);
+    }
+    getPwmFrequency() {
+        return boardResolve("peripherals.pwm.maxFrequency");
+    }
+    getPwmResolution() {
+        return boardResolve("peripherals.pwm.resolution");
+    }
+}
+export class InputPin {
+    constructor(pin) {
+        this._pin = pin;
+        this.number = pin;
+        this.gpio = pin;
+    }
+    read() {
+        return gpioRead(this._pin);
+    }
+    isHigh() {
+        return this.read();
+    }
+    isLow() {
+        return !this.read();
+    }
+    readAnalog() {
+        return adcRead(this._pin);
+    }
+    readVoltage() {
+        return adcReadVoltage(this._pin);
+    }
+    getAnalogResolution() {
+        return boardResolve("peripherals.adc.0.resolution");
+    }
+    setAnalogReference(ref) {
+        ADC._reference = ref;
+        adcSetReference(ref);
+    }
+    onFalling(handler) {
+        interruptAttach(this._pin, callback(handler), "FALLING");
+    }
+    onRising(handler) {
+        interruptAttach(this._pin, callback(handler), "RISING");
+    }
+    onChange(handler) {
+        interruptAttach(this._pin, callback(handler), "CHANGE");
+    }
+    offAll() {
+        interruptDetach(this._pin);
+    }
+    /** Alias matching the BasePin.offInterrupts() interface name. */
+    offInterrupts() {
+        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) {
+        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) {
+        rawCpp(`__cuttlefish_wait_pin_edge(${this._pin}, FALLING, ${timeout ?? -1});`);
+        return Promise.resolve();
+    }
+}
+export class ToneChain {
+    constructor(pin, frequency) {
+        this._pin = pin;
+        this._lastFreq = frequency;
+    }
+    for(duration) {
+        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 {
+    /** Legacy constructor — creates a Pin from a framework pin number */
+    constructor(pin) {
+        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) {
+        const p = new Pin(-1);
+        p._port = portName;
+        // Bypass readonly for factory method
+        p.port = portName;
+        return p;
+    }
+    asOutput(initial) {
+        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;
+    }
+    /** Alias for asOutput() — shorter fluent form. */
+    output(initial) {
+        gpioSetMode(this._pin, "OUTPUT");
+        if (initial !== undefined) {
+            gpioWrite(this._pin, initial);
+        }
+        return this;
+    }
+    asInput() {
+        gpioSetMode(this._pin, "INPUT");
+        return this;
+    }
+    asInputPullUp() {
+        gpioSetMode(this._pin, "INPUT_PULLUP");
+        return this;
+    }
+    asInputPullDown() {
+        gpioSetMode(this._pin, "INPUT_PULLDOWN");
+        return this;
+    }
+    inputPullUp() {
+        gpioSetMode(this._pin, "INPUT_PULLUP");
+        return this;
+    }
+    /** Alias for asInputPullDown() — shorter fluent form. */
+    inputPullDown() {
+        gpioSetMode(this._pin, "INPUT_PULLDOWN");
+        return this;
+    }
+    read() {
+        return gpioRead(this._pin);
+    }
+    isHigh() {
+        return this.read();
+    }
+    isLow() {
+        return !this.read();
+    }
+    write(value) {
+        gpioWrite(this._pin, value);
+    }
+    high() {
+        gpioWrite(this._pin, 1);
+    }
+    low() {
+        gpioWrite(this._pin, 0);
+    }
+    toggle() {
+        gpioToggle(this._pin);
+    }
+    pwm(duty) {
+        pwmWrite(this._pin, duty);
+    }
+    tone(frequency) {
+        tonePlay(this._pin, frequency);
+        return new ToneChain(this._pin, frequency);
+    }
+    noTone() {
+        toneStop(this._pin);
+    }
+}

package/dist/i2c.d.ts

@@ -0,0 +1,40 @@
+export declare class I2CDevice {
+    private _bus;
+    private _address;
+    constructor(bus: string, address: number);
+    writeByte(register: number, value: number): void;
+    readByte(register: number): number;
+    writeBytes(register: number, data: number[] | Uint8Array): void;
+    readBytes(register: number, count: number): Uint8Array;
+}
+export declare class I2CBus {
+    static readonly __includes: string[];
+    private _bus;
+    constructor(bus: string);
+    device(address: number): I2CDevice;
+    begin(): this;
+    beginSlave(address: number): void;
+    end(): void;
+    setClock(hz: number): void;
+    /** Recover a locked I2C bus by clocking SCL until the stuck slave releases SDA.
+     *
+     *  NOTE: This references the board-defined `SCL` pin macro. All current MCU
+     *  packages (atmega328p, esp32, esp32c3, esp32c6, esp32s3) export SCL, so
+     *  this works in practice. A fully portable version would resolve the SCL
+     *  pin number via a board constant (e.g. peripherals.i2c.0.sclPin), but that
+     *  requires adding resolved numeric pin fields to the board-constants
+     *  pipeline — deferred for now. */
+    recover(): void;
+    take(): this | null;
+    release(): void;
+    writeByte(address: number, register: number, value: number): void;
+    readByte(address: number, register: number): number;
+    beginTransmission(address: number): void;
+    write(data: number | number[] | Uint8Array): void;
+    endTransmission(stop?: boolean): number;
+    requestFrom(address: number, quantity: number, stop?: boolean): number;
+    available(): number;
+    read(): number;
+}
+/** Map TypeCAD I2C instance number to Arduino C++ object name. I2C0→Wire, I2C1→Wire1 */
+export declare function i2cName(instance: number): string;