@typecad/hal 0.1.0-alpha.1

package/src/gpio.ts

@@ -0,0 +1,298 @@
+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);
+  }
+
+  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);
+  }
+}

package/src/i2c.ts

@@ -0,0 +1,155 @@
+import { i2cBegin, i2cEnd, i2cSetClock, i2cBeginTx, i2cWrite, i2cWriteBuffer, i2cEndTx, i2cRequestFrom, i2cAvailable, i2cRead, rawCpp } from './emit.js';
+import { include } from './include.js';
+
+export class I2CDevice {
+  private _bus: string;
+  private _address: number;
+
+  constructor(bus: string, address: number) {
+    this._bus = bus;
+    this._address = address;
+  }
+
+  writeByte(register: number, value: number): void {
+    include("<Wire.h>");
+    i2cBeginTx(this._bus, this._address);
+    i2cWrite(this._bus, register);
+    i2cWrite(this._bus, value);
+    i2cEndTx(this._bus, true);
+  }
+
+  readByte(register: number): number {
+    include("<Wire.h>");
+    i2cBeginTx(this._bus, this._address);
+    i2cWrite(this._bus, register);
+    i2cEndTx(this._bus, false);
+    i2cRequestFrom(this._bus, this._address, 1);
+    return i2cRead(this._bus);
+  }
+
+  writeBytes(register: number, data: number[] | Uint8Array): void {
+    include("<Wire.h>");
+    i2cBeginTx(this._bus, this._address);
+    i2cWrite(this._bus, register);
+    i2cWriteBuffer(this._bus, data);
+    i2cEndTx(this._bus, true);
+  }
+
+  readBytes(register: number, count: number): Uint8Array {
+    include("<Wire.h>");
+    i2cBeginTx(this._bus, this._address);
+    i2cWrite(this._bus, register);
+    i2cEndTx(this._bus, false);
+    i2cRequestFrom(this._bus, this._address, count, true);
+    rawCpp(`static uint8_t __buf[${count}];`);
+    rawCpp(`for (int __i = 0; __i < ${count}; __i++) __buf[__i] = ${this._bus}.read();`);
+    rawCpp(`return __buf;`);
+    return new Uint8Array(count);
+  }
+}
+
+export class I2CBus {
+  static readonly __includes = ["<Wire.h>"];
+  private _bus: string;
+
+  constructor(bus: string) {
+    this._bus = bus;
+  }
+
+  device(address: number): I2CDevice {
+    return new I2CDevice(this._bus, address);
+  }
+
+  begin(): this {
+    include("<Wire.h>");
+    i2cBegin(this._bus);
+    return this;
+  }
+
+  beginSlave(address: number): void {
+    i2cBegin(this._bus, address);
+  }
+
+  end(): void {
+    i2cEnd(this._bus);
+  }
+
+  setClock(hz: number): void {
+    i2cSetClock(this._bus, hz);
+  }
+
+  /** 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 {
+    include("<Wire.h>");
+    rawCpp(`pinMode(SCL, OUTPUT);`);
+    rawCpp(`for (int i = 0; i < 16; i++) {`);
+    rawCpp(`  digitalWrite(SCL, LOW);`);
+    rawCpp(`  delayMicroseconds(10);`);
+    rawCpp(`  digitalWrite(SCL, HIGH);`);
+    rawCpp(`  delayMicroseconds(10);`);
+    rawCpp(`}`);
+    rawCpp(`${this._bus}.begin();`);
+  }
+
+  take(): this | null {
+    include("<Wire.h>");
+    return this;
+  }
+
+  release(): void {
+    // No-op for standard Arduino.
+  }
+
+  writeByte(address: number, register: number, value: number): void {
+    i2cBeginTx(this._bus, address);
+    i2cWrite(this._bus, register);
+    i2cWrite(this._bus, value);
+    i2cEndTx(this._bus, true);
+  }
+
+  readByte(address: number, register: number): number {
+    i2cBeginTx(this._bus, address);
+    i2cWrite(this._bus, register);
+    i2cEndTx(this._bus, false);
+    i2cRequestFrom(this._bus, address, 1);
+    return i2cRead(this._bus);
+  }
+
+  // Low-level Wire API pass-through methods
+  beginTransmission(address: number): void {
+    i2cBeginTx(this._bus, address);
+  }
+
+  write(data: number | number[] | Uint8Array): void {
+    i2cWrite(this._bus, data);
+  }
+
+  endTransmission(stop?: boolean): number {
+    return i2cEndTx(this._bus, stop ?? true);
+  }
+
+  requestFrom(address: number, quantity: number, stop?: boolean): number {
+    return i2cRequestFrom(this._bus, address, quantity, stop ?? true);
+  }
+
+  available(): number {
+    return i2cAvailable(this._bus);
+  }
+
+  read(): number {
+    return i2cRead(this._bus);
+  }
+}
+
+
+/** Map TypeCAD I2C instance number to Arduino C++ object name. I2C0→Wire, I2C1→Wire1 */
+export function i2cName(instance: number): string {
+  return instance === 0 ? "Wire" : `Wire${instance}`;
+}

package/src/include.ts

@@ -0,0 +1,5 @@
+/**
+ * Compile-time function: adds a C++ #include header to the generated output.
+ * At runtime (tests, type-checking) this is a no-op.
+ */
+export function include(_text: string): void {}

package/src/index.ts

@@ -0,0 +1,48 @@
+// Re-export commonly-used types so consumers can import everything from @typecad/hal
+//
+// Runtime-contract interfaces (BasePin, II2CBus, ISPIBus, ISerialPort, the
+// status enums, capability guards, PinCapabilityFlags, IToneAttachment, ...)
+// now live in @typecad/simulator. Import them from there.
+export type { DigitalValue, AnalogValue } from './types.js';
+export { PinMode, InterruptMode } from './types.js';
+export type { IPinGroup, PinGroupMember } from './types.js';
+export { createPinGroup } from './types.js';
+
+export type { InterruptHandler } from './types.js';
+
+export type { ArchitectureIdentifier } from './types.js';
+
+// Protocol-shape types (re-exported downstream by @typecad/framework-arduino)
+export type { I2CAddress } from './types.js';
+export type { SPIBitOrder, SPIMode, SPISettings } from './types.js';
+
+export { include } from './include.js';
+export { board } from './board.js';
+export { callback } from './callback.js';
+export { rawCpp, boardResolve } from './emit.js';
+export { HIGH, LOW, OUTPUT, INPUT, INPUT_PULLUP, INPUT_PULLDOWN, OUTPUT_OPEN_DRAIN, ANALOG, LED_BUILTIN, LSBFIRST, MSBFIRST, WDTO_15MS, WDTO_30MS, WDTO_60MS, WDTO_120MS, WDTO_250MS, WDTO_500MS, WDTO_1S, WDTO_2S, WDTO_4S, WDTO_8S } from './constants.js';
+export { delay, millis, micros, delayMicroseconds, map, constrain, TimingClass, Timing } from './timing.js';
+export { freeHeap, setInterval, setTimeout, clearInterval, clearTimeout } from './timing.js';
+export { abs, min, max, NumClass, Num, MapChain, ConstrainChain } from './math.js';
+export { Pulse, pulseIn, pulseInLong } from './pulse.js';
+export { Shift, shiftIn, shiftOut } from './shift.js';
+export { Random } from './random.js';
+export { randomSeed, random } from './random.js';
+export { noInterrupts, interrupts, attachInterrupt, detachInterrupt } from './interrupts.js';
+export { Pin, OutputPin, InputPin, ToneChain } from './gpio.js';
+export { I2CBus, I2CDevice, i2cName } from './i2c.js';
+export { SPIBus, SPIDevice, spiName } from './spi.js';
+export { SerialPort, serialName } from './uart.js';
+export { createHALInstances } from './utils.js';
+// Register-mapped struct decorators (compile-time markers, erased by transpiler)
+export type { Bit, Bits } from './register.js';
+export { register, bits } from './register.js';
+export { EEPROMClass, EEPROM } from './eeprom.js';
+export { WDTClass, WDT } from './wdt.js';
+export { ADCClass, ADC } from './adc.js';
+export { DACClass, DAC } from './dac.js';
+export { PreferencesClass, Preferences } from './preferences.js';
+export { HardwareTimer, Timer0, Timer1, Timer2 } from './timer.js';
+export { FSClass, FS } from './fs.js';
+export { PowerClass, Power } from './power.js';
+export { AsyncClass, Async } from './async.js';

package/src/interrupts.ts

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

package/src/math.ts

@@ -0,0 +1,32 @@
+export class MapChain {
+  constructor(value: number) {}
+  from(low: number, high: number): MapChain { return this; }
+  to(low: number, high: number): number { return 0; }
+  toPercent(): number { return 0; }
+  toByte(): number { return 0; }
+}
+
+export class ConstrainChain {
+  constructor(value: number) {}
+  between(low: number, high: number): number { return 0; }
+}
+
+export class NumClass {
+  // No __instance_name — Num methods must NOT be intercepted by the HAL
+  // resolver. They pass through as bare C++ calls (Num.abs(-7)), which the
+  // strategy's __tc_Num polyfill struct provides. The strategy post-processes
+  // the output to rename Num.abs( → Num._abs( to match the polyfill's
+  // parenthesized method names (which avoid macro collisions with Arduino's
+  // abs/min/max macros). See strategy.ts __tc_Num struct + the rewrite regex.
+  abs(x: number): number { return 0; }
+  min(a: number, b: number): number { return 0; }
+  max(a: number, b: number): number { return 0; }
+  constrain(value: number): ConstrainChain { return new ConstrainChain(value); }
+  map(value: number): MapChain { return new MapChain(value); }
+}
+
+export const Num = new NumClass();
+
+export function abs(x: number): number { return 0; }
+export function min(a: number, b: number): number { return 0; }
+export function max(a: number, b: number): number { return 0; }

package/src/power.ts

@@ -0,0 +1,26 @@
+import { powerDeepSleep, powerLightSleep, powerSetCpuFrequency } from './emit.js';
+
+/**
+ * PowerClass provides control over MCU power states and clock frequencies.
+ *
+ * The arch guard (ESP32 family vs AVR) lives in the strategy, not here — it
+ * relies on the FQBN-derived architecture which is always available at
+ * transpile time, unlike `board("architecture")` which needs a board package.
+ */
+export class PowerClass {
+  static readonly __instance_name = "Power";
+
+  deepSleep(ms: number): void {
+    powerDeepSleep(ms);
+  }
+
+  lightSleep(): void {
+    powerLightSleep();
+  }
+
+  setCpuFrequency(mhz: number): void {
+    powerSetCpuFrequency(mhz);
+  }
+}
+
+export const Power = new PowerClass();

package/src/preferences.ts

@@ -0,0 +1,58 @@
+import { rawCpp } from './emit.js';
+
+export class PreferencesClass {
+  static readonly __instance_name = "Preferences";
+  // NOTE: no __includes here. The transpiler emits singleton __includes on
+  // every architecture with no filtering, and <Preferences.h> is ESP32-only —
+  // adding it would break AVR builds. The class is ESP32-only by convention.
+
+  begin(name: string, readOnly: boolean = false): void {
+    rawCpp(`Preferences.begin(${name}.c_str(), ${readOnly});`);
+  }
+  end(): void {
+    rawCpp(`Preferences.end();`);
+  }
+  clear(): void {
+    rawCpp(`Preferences.clear();`);
+  }
+  remove(key: string): void {
+    rawCpp(`Preferences.remove(${key}.c_str());`);
+  }
+  putInt(key: string, value: number): void {
+    rawCpp(`Preferences.putInt(${key}.c_str(), ${value});`);
+  }
+  getInt(key: string, defaultValue: number = 0): number {
+    rawCpp(`return Preferences.getInt(${key}.c_str(), ${defaultValue});`);
+    return 0;
+  }
+  putUInt(key: string, value: number): void {
+    rawCpp(`Preferences.putUInt(${key}.c_str(), ${value});`);
+  }
+  getUInt(key: string, defaultValue: number = 0): number {
+    rawCpp(`return Preferences.getUInt(${key}.c_str(), ${defaultValue});`);
+    return 0;
+  }
+  putFloat(key: string, value: number): void {
+    rawCpp(`Preferences.putFloat(${key}.c_str(), ${value});`);
+  }
+  getFloat(key: string, defaultValue: number = 0): number {
+    rawCpp(`return Preferences.getFloat(${key}.c_str(), ${defaultValue});`);
+    return 0;
+  }
+  putBool(key: string, value: boolean): void {
+    rawCpp(`Preferences.putBool(${key}.c_str(), ${value});`);
+  }
+  getBool(key: string, defaultValue: boolean = false): boolean {
+    rawCpp(`return Preferences.getBool(${key}.c_str(), ${defaultValue});`);
+    return false;
+  }
+  putString(key: string, value: string): void {
+    rawCpp(`Preferences.putString(${key}.c_str(), ${value}.c_str());`);
+  }
+  getString(key: string, defaultValue: string = ""): string {
+    rawCpp(`return Preferences.getString(${key}.c_str(), ${defaultValue}.c_str());`);
+    return "";
+  }
+}
+
+export const Preferences = new PreferencesClass();