@typecad/hal 0.1.0-alpha.1

package/src/adc.ts

@@ -0,0 +1,30 @@
+import { adcRead, adcSetReference, boardResolve } from './emit.js';
+
+export class ADCClass {
+  static readonly __instance_name = "ADC";
+  static readonly __default_fields = { _reference: "DEFAULT" };
+  _reference: string;
+
+  constructor() {
+    this._reference = "DEFAULT";
+  }
+
+  getAnalogResolution(): number {
+    return boardResolve("peripherals.adc.0.resolution");
+  }
+
+  setAnalogReference(ref: string): void {
+    this._reference = ref;
+    adcSetReference(ref);
+  }
+
+  getAnalogReference(): number {
+    return boardResolve("peripherals.adc.0.referenceVoltages." + this._reference);
+  }
+
+  read(pin: number): number {
+    return adcRead(pin);
+  }
+}
+
+export const ADC = new ADCClass();

package/src/async.ts

@@ -0,0 +1,63 @@
+// ---------------------------------------------------------------------------
+// Async — Top-level cooperative async / scheduling abstraction for TypeCAD
+//
+// Provides a platform-independent API for:
+//   - sleep(ms)      — non-blocking delay via Promise + microtask
+//   - yield()        — cooperative yield to other tasks
+//   - sleepUntil(condition) — await a condition (promise-based)
+//   - currentTask()  — return a description of the currently executing task
+//
+// Framework packages (Arduino, Native, etc.) provide the C++ runtime behind
+// the rawCpp() markers; the transpiler resolves these to the correct platform
+// implementation at compile time.
+// ---------------------------------------------------------------------------
+
+import { rawCpp } from './emit.js';
+
+export class AsyncClass {
+  static readonly __instance_name = "Async";
+
+  /**
+   * Non-blocking sleep for `ms` milliseconds.
+   * Returns a Promise<void> that resolves after the given delay.
+   * The underlying C++ implementation uses the platform's timer/microtask
+   * mechanism (e.g. millis-based polling on Arduino, std::this_thread::sleep_for
+   * on native, or a FreeRTOS vTaskDelay in the future).
+   */
+  sleep(ms: number): Promise<void> {
+    rawCpp(`__cuttlefish_async_sleep(${ms});`);
+    return Promise.resolve();
+  }
+
+  /**
+   * Cooperative yield — suspend the current task and allow other tasks
+   * (microtasks, timers) to run. Resumes on the next microtask pump cycle.
+   */
+  yield(): Promise<void> {
+    rawCpp(`__cuttlefish_async_yield();`);
+    return Promise.resolve();
+  }
+
+  /**
+   * Await a polling condition.
+   * Repeatedly checks `condition()` every `pollIntervalMs` milliseconds
+   * until it returns true, then resolves.
+   * The underlying implementation uses the platform's timer mechanism.
+   */
+  sleepUntil(condition: () => boolean, pollIntervalMs: number = 10): Promise<void> {
+    rawCpp(`__cuttlefish_async_sleep_until(${pollIntervalMs});`);
+    return Promise.resolve();
+  }
+
+  /**
+   * Return a human-readable description of the currently executing async task.
+   * Useful for debugging / logging in cooperative multitasking environments.
+   */
+  currentTask(): string {
+    rawCpp(`return __cuttlefish_async_current_task();`);
+    return "";
+  }
+}
+
+/** Singleton instance — consumers use `Async.sleep(...)` directly. */
+export const Async = new AsyncClass();

package/src/board.ts

@@ -0,0 +1,5 @@
+/** Compile-time function: resolves a board definition path to a literal value.
+ *  At runtime (tests, type-checking) this is a no-op that returns undefined. */
+export function board(_path: string): any {
+  return undefined;
+}

package/src/callback.ts

@@ -0,0 +1,6 @@
+/** Compile-time function: registers a function argument as a standalone C++ callback.
+ *  Returns the generated function name for use in rawCpp() templates.
+ *  At runtime (tests, type-checking) this is a no-op. */
+export function callback<T extends (...args: any[]) => any>(_fn: T): string {
+  return "";
+}

package/src/constants.ts

@@ -0,0 +1,23 @@
+// These constants are resolved from the board definition at compile time by the
+// transpiler. At runtime (tests, type-checking) they default to 0.
+export const INPUT: number = 0;
+export const OUTPUT: number = 0;
+export const INPUT_PULLUP: number = 0;
+export const INPUT_PULLDOWN: number = 0;
+export const OUTPUT_OPEN_DRAIN: number = 0;
+export const ANALOG: number = 0;
+export const HIGH: number = 0;
+export const LOW: number = 0;
+export const LED_BUILTIN: number = 0;
+export const LSBFIRST: number = 0;
+export const MSBFIRST: number = 0;
+export const WDTO_15MS: number = 0;
+export const WDTO_30MS: number = 0;
+export const WDTO_60MS: number = 0;
+export const WDTO_120MS: number = 0;
+export const WDTO_250MS: number = 0;
+export const WDTO_500MS: number = 0;
+export const WDTO_1S: number = 0;
+export const WDTO_2S: number = 0;
+export const WDTO_4S: number = 0;
+export const WDTO_8S: number = 0;

package/src/dac.ts

@@ -0,0 +1,21 @@
+import { dacWrite, boardResolve } from './emit.js';
+
+/**
+ * DACClass provides access to true digital-to-analog converters.
+ * 
+ * Note: This is for true analog output (DAC), distinct from PWM-based
+ * analog simulation provided by Pin.pwm().
+ */
+export class DACClass {
+  static readonly __instance_name = "DAC";
+
+  write(pin: number, value: number): void {
+    dacWrite(pin, value);
+  }
+
+  getResolution(): number {
+    return boardResolve("peripherals.dac.0.resolution");
+  }
+}
+
+export const DAC = new DACClass();

package/src/eeprom.ts

@@ -0,0 +1,26 @@
+import { rawCpp } from './emit.js';
+import { include } from './include.js';
+
+export class EEPROMClass {
+  static readonly __instance_name = "EEPROM";
+  static readonly __includes = ["<EEPROM.h>"];
+  static readonly __default_fields = { _name: "EEPROM" };
+
+  private _name: string;
+  constructor(name: string) {
+    include("<EEPROM.h>");
+    this._name = name;
+  }
+
+  read(address: number): number { return 0; }
+  write(address: number, value: number): void { rawCpp(`${this._name}.write(${address}, ${value});`); }
+  update(address: number, value: number): void { rawCpp(`${this._name}.update(${address}, ${value});`); }
+  length(): number { return 0; }
+  get<T>(address: number, ref: T): T {
+    rawCpp(`${this._name}.get(${address}, ${ref});`);
+    return ref;
+  }
+  put<T>(address: number, value: T): void { rawCpp(`${this._name}.put(${address}, ${value});`); }
+}
+
+export const EEPROM = new EEPROMClass("EEPROM");

package/src/emit.ts

@@ -0,0 +1,210 @@
+// ---------------------------------------------------------------------------
+// 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: number | string, value: number | boolean): void {}
+/** Read a digital pin. Returns HIGH (1) or LOW (0). */
+export function gpioRead(pin: number | string): number { return 0; }
+/** Toggle a digital pin. */
+export function gpioToggle(pin: number | string): void {}
+/** Set pin mode: "output" | "input" | "input_pullup" | "input_pulldown". */
+export function gpioSetMode(pin: number | string, mode: string): void {}
+
+// ---------------------------------------------------------------------------
+// PWM — pulse-width modulation
+// ---------------------------------------------------------------------------
+
+/** Write PWM duty cycle to a pin. */
+export function pwmWrite(pin: number | string, duty: number): void {}
+
+// ---------------------------------------------------------------------------
+// ADC — analog-to-digital conversion
+// ---------------------------------------------------------------------------
+
+/** Read analog value from a pin. */
+export function adcRead(pin: number | string): number { return 0; }
+/** Read analog voltage from a pin (ADC value converted to voltage). */
+export function adcReadVoltage(pin: number | string): number { return 0; }
+/** Set the analog reference. */
+export function adcSetReference(ref: string | number): void {}
+
+// ---------------------------------------------------------------------------
+// Interrupts
+// ---------------------------------------------------------------------------
+
+/** Attach an interrupt handler to a pin. */
+export function interruptAttach(pin: number | string, handler: string, mode: string): void {}
+/** Detach an interrupt from a pin. */
+export function interruptDetach(pin: number | string): void {}
+
+// ---------------------------------------------------------------------------
+// Tone / audio output
+// ---------------------------------------------------------------------------
+
+/** Play a tone on a pin at the given frequency, optionally for a duration. */
+export function tonePlay(pin: number | string, frequency: number, duration?: number): void {}
+/** Stop tone playback on a pin. */
+export function toneStop(pin: number | string): void {}
+
+// ---------------------------------------------------------------------------
+// Timing
+// ---------------------------------------------------------------------------
+
+/** Delay for the given number of milliseconds. */
+export function delayMs(ms: number): void {}
+/** Delay for the given number of microseconds. */
+export function delayMicro(us: number): void {}
+/** Get milliseconds since boot. */
+export function getMillis(): number { return 0; }
+/** Get microseconds since boot. */
+export function getMicros(): number { 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(): number { return 0; }
+
+// ---------------------------------------------------------------------------
+// I2C — inter-integrated circuit bus
+// ---------------------------------------------------------------------------
+
+/** Initialize I2C bus (master mode if no address, slave mode with address). */
+export function i2cBegin(bus: string, address?: number): void {}
+/** Disable I2C bus. */
+export function i2cEnd(bus: string): void {}
+/** Set I2C bus clock speed. */
+export function i2cSetClock(bus: string, hz: number): void {}
+/** Begin I2C transmission to a slave address. */
+export function i2cBeginTx(bus: string, address: number): void {}
+/** Write data to I2C bus. */
+export function i2cWrite(bus: string, data: string | number | number[] | Uint8Array): void {}
+/** Write a byte buffer to I2C bus (expands array literals to per-byte writes). */
+export function i2cWriteBuffer(bus: string, data: number[] | Uint8Array): void {}
+/** End I2C transmission. Returns status. */
+export function i2cEndTx(bus: string, stop: boolean): number { return 0; }
+/** Request bytes from I2C slave. */
+export function i2cRequestFrom(bus: string, address: number, quantity: number, stop?: boolean): number { return 0; }
+/** Check if bytes are available from I2C. */
+export function i2cAvailable(bus: string): number { return 0; }
+/** Read a byte from I2C. */
+export function i2cRead(bus: string): number { return 0; }
+
+// ---------------------------------------------------------------------------
+// SPI — serial peripheral interface
+// ---------------------------------------------------------------------------
+
+/** Initialize SPI bus. */
+export function spiBegin(bus: string): void {}
+/** Disable SPI bus. */
+export function spiEnd(bus: string): void {}
+/** Transfer data on SPI bus. */
+export function spiTransfer(bus: string, data: string | number | Uint8Array): number { return 0; }
+/** Begin SPI transaction with settings. */
+export function spiBeginTx(bus: string, settings: string | any): void {}
+/** End SPI transaction. */
+export function spiEndTx(bus: string): void {}
+/** Set SPI chip-select pin LOW. */
+export function spiCsLow(pin: number | string): void {}
+/** Set SPI chip-select pin HIGH. */
+export function spiCsHigh(pin: number | string): void {}
+/** Set SPI data mode. */
+export function spiSetMode(bus: string, mode: number): void {}
+/** Set SPI bit order. */
+export function spiSetBitOrder(bus: string, order: string): void {}
+
+// ---------------------------------------------------------------------------
+// UART — serial communication
+// ---------------------------------------------------------------------------
+
+/** Initialize serial port with baud rate. */
+export function uartBegin(port: string, baud: number): void {}
+/** Disable serial port. */
+export function uartEnd(port: string): void {}
+/** Print value to serial. */
+export function uartPrint(port: string, value: any): void {}
+/** Print value with newline to serial. */
+export function uartPrintln(port: string, value: any): void {}
+/** printf-style formatted print to serial. */
+export function uartPrintf(port: string, format: any, args: any[]): void {}
+/** Write raw data to serial. */
+export function uartWrite(port: string, data: any): void {}
+/** Read a byte from serial. */
+export function uartRead(port: string): number { return 0; }
+/** Peek at next byte from serial without consuming. */
+export function uartPeek(port: string): number { return 0; }
+/** Check if bytes are available from serial. */
+export function uartAvailable(port: string): number { return 0; }
+/** Flush serial output. */
+export function uartFlush(port: string): void {}
+
+// ---------------------------------------------------------------------------
+// Pulse measurement
+// ---------------------------------------------------------------------------
+
+/** Measure pulse duration on a pin. */
+export function pulseIn_(pin: number | string, value: number, timeout?: number): number { return 0; }
+/** Measure long pulse using high-precision timer. */
+export function pulseInLong_(pin: number | string, value: number): number { return 0; }
+
+// ---------------------------------------------------------------------------
+// Shift register
+// ---------------------------------------------------------------------------
+
+/** Shift a byte out to a pin. */
+export function shiftOut_(dataPin: number | string, clockPin: number | string, bitOrder: number, value: number): void {}
+/** Shift a byte in from a pin. */
+export function shiftIn_(dataPin: number | string, clockPin: number | string, bitOrder: number): number { return 0; }
+
+// ---------------------------------------------------------------------------
+// Board constant resolution
+// ---------------------------------------------------------------------------
+
+/** Write a value to a DAC pin. */
+export function dacWrite(pin: number | string, value: number): void {}
+
+// ---------------------------------------------------------------------------
+// Watchdog timer (WDT)
+// ---------------------------------------------------------------------------
+
+/** Enable the watchdog timer with the given timeout (string preset or number). */
+export function wdtEnable(timeout: string | number): void {}
+
+/** Reset (kick) the watchdog timer. */
+export function wdtReset(): void {}
+
+/** Disable the watchdog timer. */
+export function wdtDisable(): void {}
+
+/** Resolve a board definition path to a compile-time constant. */
+export function boardResolve(path: string): any { return undefined as any; }
+
+// ---------------------------------------------------------------------------
+// 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: number): void {}
+/** Enter light sleep. Architecture-aware. */
+export function powerLightSleep(): void {}
+/** Set the CPU frequency (MHz). */
+export function powerSetCpuFrequency(mhz: number): void {}
+
+// ---------------------------------------------------------------------------
+// Raw C++ escape hatch
+// ---------------------------------------------------------------------------
+
+/** Emit raw C++ code (escape hatch for unsupported operations). */
+export function rawCpp(code: string): void {}

package/src/fs.ts

@@ -0,0 +1,46 @@
+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 {
+  static readonly __instance_name = "FS";
+
+  begin(): boolean {
+    include("<FS.h>");
+    rawCpp(`return FS.begin();`);
+    return true;
+  }
+
+  readText(path: string): string {
+    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: string, content: string): void {
+    include("<FS.h>");
+    rawCpp(`File f = FS.open(${path}.c_str(), "w");`);
+    rawCpp(`if (f) { f.print(${content}.c_str()); f.close(); }`);
+  }
+
+  exists(path: string): boolean {
+    include("<FS.h>");
+    rawCpp(`return FS.exists(${path}.c_str());`);
+    return false;
+  }
+
+  remove(path: string): boolean {
+    include("<FS.h>");
+    rawCpp(`return FS.remove(${path}.c_str());`);
+    return false;
+  }
+}
+
+export const FS = new FSClass();