@typecad/hal 0.1.0-alpha.1

package/src/pulse.ts

@@ -0,0 +1,63 @@
+import { rawCpp } from './emit.js';
+import { HIGH, LOW } from './constants.js';
+import type { Pin, InputPin } from './gpio.js';
+
+export function pulseIn(pin: number, value: number, timeout?: number): number {
+  if (timeout !== undefined) {
+    rawCpp(`return pulseIn(${pin}, ${value}, ${timeout});`);
+  } else {
+    rawCpp(`return pulseIn(${pin}, ${value});`);
+  }
+  return 0;
+}
+export function pulseInLong(pin: number, value: number, timeout?: number): number {
+  if (timeout !== undefined) {
+    rawCpp(`return pulseInLong(${pin}, ${value}, ${timeout});`);
+  } else {
+    rawCpp(`return pulseInLong(${pin}, ${value});`);
+  }
+  return 0;
+}
+
+export class Pulse {
+  /** 
+   * Functional entrypoint for measuring pulses.
+   * @example Pulse.on(D7).high()
+   */
+  static on(pin: Pin | InputPin): PulseMeasurement {
+    return new PulseMeasurement(pin);
+  }
+
+  /** Measure long pulses using high-precision 64-bit timers. */
+  static long(pin: Pin | InputPin, value: number): number {
+    rawCpp(`return pulseInLong(${pin.number}, ${value});`);
+    return 0;
+  }
+}
+
+class PulseMeasurement {
+  private _pin: number;
+  private _timeout: number | undefined;
+
+  constructor(pin: Pin | InputPin) {
+    this._pin = pin.number;
+  }
+
+  /** Set the maximum wait time for a pulse (in microseconds). */
+  timeout(us: number): this {
+    this._timeout = us;
+    return this;
+  }
+
+  /** Measures the next HIGH pulse duration in microseconds. */
+  high(): number {
+    rawCpp(`return pulseIn(${this._pin}, HIGH${this._timeout !== undefined ? `, ${this._timeout}` : ""});`);
+    return 0;
+  }
+
+  /** Measures the next LOW pulse duration in microseconds. */
+  low(): number {
+    rawCpp(`return pulseIn(${this._pin}, LOW${this._timeout !== undefined ? `, ${this._timeout}` : ""});`);
+    return 0;
+  }
+}

package/src/random.ts

@@ -0,0 +1,31 @@
+import { rawCpp } from './emit.js';
+
+export function randomSeed(seed: number): void {}
+export function random(minOrMax: number, max?: number): number { return 0; }
+
+export class Random {
+  /** Seeds the PRNG with a starting value. */
+  static seed(val: number): void {
+    rawCpp(`randomSeed(${val});`);
+  }
+
+  /** Returns a random number in range [0, max-1]. */
+  static upTo(max: number): number {
+    rawCpp(`return random(${max});`);
+    return 0;
+  }
+
+  /** Returns a random number in range [min, max-1]. */
+  static between(min: number, max: number): number {
+    rawCpp(`return random(${min}, ${max});`);
+    return 0;
+  }
+
+  /** Returns a random non-negative 31-bit integer [0, 2147483646]. */
+  static int(): number {
+    // Arduino random(max) returns [0, max-1]; 2147483647 = INT_MAX gives a
+    // non-negative 31-bit range (sign bit always 0).
+    rawCpp(`return random(2147483647);`);
+    return 0;
+  }
+}

package/src/register.ts

@@ -0,0 +1,35 @@
+// ---------------------------------------------------------------------------
+// Register-mapped struct decorators — compile-time markers
+//
+// `@register(address)` and `@bits(hi, lo)` are recognized by-name by the
+// cuttlefish transpiler (packages/cuttlefish/src/ir/register-decorators.ts).
+// The transpiler intercepts a class carrying @register, lowers it to a
+// `volatile uint32_t*` pointer at the given address, and rewrites field
+// reads/writes to shift/mask arithmetic. The decorators themselves are erased
+// and never execute, so these are ambient stubs that exist purely so user code
+// type-checks under tsc before transpilation.
+//
+//   @register(0x40011000)
+//   class USART1 {
+//     @bits(0, 0)  static UE:   Bit       = 0;
+//     @bits(9, 8)  static PS:   Bits<2>   = 0;
+//     @bits(15, 8) static BAUD: Bits<8>   = 0;
+//   }
+//   USART1.UE = 1;              // (*USART1 & ~1UL) | ((1 & 1UL) << 0)
+//   const parity = USART1.PS;   // ((*USART1 >> 8) & ((1UL << 2) - 1))
+// ---------------------------------------------------------------------------
+
+/** A single-bit register field (0 or 1). */
+export type Bit = 0 | 1;
+
+/** A multi-bit register field spanning N bits. The numeric type arg carries
+ *  the bit width for documentation only; the value is the raw field contents. */
+export type Bits<N extends number = number> = number;
+
+/** Class decorator marking a struct as a memory-mapped register at `address`.
+ *  Erased at transpile time — the class becomes a `volatile uint32_t*`. */
+export declare function register(address: number): ClassDecorator;
+
+/** Property decorator carrying the bit range [lo, hi] (inclusive) of a field
+ *  within its register. Erased at transpile time. */
+export declare function bits(hi: number, lo: number): PropertyDecorator;

package/src/shift.ts

@@ -0,0 +1,88 @@
+import { rawCpp } from './emit.js';
+import { LSBFIRST, MSBFIRST } from './constants.js';
+import type { Pin, OutputPin, InputPin } from './gpio.js';
+
+export function shiftIn(dataPin: number, clockPin: number, bitOrder: number): number {
+  rawCpp(`return shiftIn(${dataPin}, ${clockPin}, ${bitOrder});`);
+  return 0;
+}
+export function shiftOut(dataPin: number, clockPin: number, bitOrder: number, value: number): void {
+  rawCpp(`shiftOut(${dataPin}, ${clockPin}, ${bitOrder}, ${value});`);
+}
+
+export class Shift {
+  /** Directly shifts a byte out to a pin. */
+  static out(dataPin: Pin | OutputPin, clockPin: Pin | OutputPin, order: 'lsb' | 'msb', value: number): void {
+    const bitOrder = order === 'lsb' ? LSBFIRST : MSBFIRST;
+    rawCpp(`shiftOut(${dataPin.number}, ${clockPin.number}, ${bitOrder}, ${value});`);
+  }
+
+  /** Directly shifts a byte in from a pin. */
+  static in(dataPin: Pin | InputPin, clockPin: Pin | OutputPin, order: 'lsb' | 'msb'): number {
+    const bitOrder = order === 'lsb' ? LSBFIRST : MSBFIRST;
+    rawCpp(`return shiftIn(${dataPin.number}, ${clockPin.number}, ${bitOrder});`);
+    return 0;
+  }
+
+  /** Fluent builder for shifting out. */
+  static write(dataPin: Pin | OutputPin, value: number): ShiftOutBuilder {
+    return new ShiftOutBuilder(dataPin, value);
+  }
+
+  /** Fluent builder for shifting in. */
+  static read(dataPin: Pin | InputPin): ShiftInBuilder {
+    return new ShiftInBuilder(dataPin);
+  }
+}
+
+class ShiftOutBuilder {
+  private _dataPin: number;
+  private _value: number;
+  private _clockPin: number | undefined;
+
+  constructor(dataPin: Pin | OutputPin, value: number) {
+    this._dataPin = dataPin.number;
+    this._value = value;
+  }
+
+  clock(clk: Pin | OutputPin): this {
+    this._clockPin = clk.number;
+    return this;
+  }
+
+  msbFirst(): void {
+    if (this._clockPin === undefined) throw new Error("Clock pin must be specified");
+    rawCpp(`shiftOut(${this._dataPin}, ${this._clockPin}, MSBFIRST, ${this._value});`);
+  }
+
+  lsbFirst(): void {
+    if (this._clockPin === undefined) throw new Error("Clock pin must be specified");
+    rawCpp(`shiftOut(${this._dataPin}, ${this._clockPin}, LSBFIRST, ${this._value});`);
+  }
+}
+
+class ShiftInBuilder {
+  private _dataPin: number;
+  private _clockPin: number | undefined;
+
+  constructor(dataPin: Pin | InputPin) {
+    this._dataPin = dataPin.number;
+  }
+
+  clock(clk: Pin | OutputPin): this {
+    this._clockPin = clk.number;
+    return this;
+  }
+
+  msbFirst(): number {
+    if (this._clockPin === undefined) throw new Error("Clock pin must be specified");
+    rawCpp(`return shiftIn(${this._dataPin}, ${this._clockPin}, MSBFIRST);`);
+    return 0;
+  }
+
+  lsbFirst(): number {
+    if (this._clockPin === undefined) throw new Error("Clock pin must be specified");
+    rawCpp(`return shiftIn(${this._dataPin}, ${this._clockPin}, LSBFIRST);`);
+    return 0;
+  }
+}

package/src/spi.ts

@@ -0,0 +1,118 @@
+import { spiBegin, spiEnd, spiTransfer, spiBeginTx, spiEndTx, spiCsLow, spiCsHigh, spiSetMode, spiSetBitOrder, rawCpp } from './emit.js';
+import { include } from './include.js';
+import type { Pin } from './gpio.js';
+import type { SPIMode, SPISettings } from './types.js';
+
+export class SPIDevice {
+  private _bus: string;
+  private _cs: number;
+
+  constructor(bus: string, chipSelect: number) {
+    this._bus = bus;
+    this._cs = chipSelect;
+  }
+
+  transfer(data: number | Uint8Array): number {
+    include("<SPI.h>");
+    spiCsLow(this._cs);
+    rawCpp(`auto __res = ${this._bus}.transfer(${data});`);
+    spiCsHigh(this._cs);
+    rawCpp(`return __res;`);
+    return 0;
+  }
+
+  write(data: number | Uint8Array): void {
+    include("<SPI.h>");
+    spiCsLow(this._cs);
+    spiTransfer(this._bus, data);
+    spiCsHigh(this._cs);
+  }
+
+  readRegister(register: number, count: number): Uint8Array {
+    include("<SPI.h>");
+    rawCpp(`digitalWrite(${this._cs}, LOW);`);
+    rawCpp(`${this._bus}.transfer(${register});`);
+    rawCpp(`static uint8_t __spi_buf[${count}];`);
+    rawCpp(`for (int i=0; i<${count}; i++) __spi_buf[i] = ${this._bus}.transfer(0x00);`);
+    rawCpp(`digitalWrite(${this._cs}, HIGH);`);
+    rawCpp(`return __spi_buf;`);
+    return new Uint8Array(count);
+  }
+
+  writeRegister(register: number, value: number): void {
+    include("<SPI.h>");
+    spiCsLow(this._cs);
+    spiTransfer(this._bus, register);
+    spiTransfer(this._bus, value);
+    spiCsHigh(this._cs);
+  }
+}
+
+export class SPIBus {
+  static readonly __includes = ["<SPI.h>"];
+  private _bus: string;
+
+  constructor(bus: string) {
+    this._bus = bus;
+  }
+
+  device(chipSelect: Pin): SPIDevice {
+    return new SPIDevice(this._bus, chipSelect.number);
+  }
+
+  begin(): this {
+    include("<SPI.h>");
+    spiBegin(this._bus);
+    return this;
+  }
+
+  end(): void {
+    spiEnd(this._bus);
+  }
+
+  take(): this | null {
+    return this;
+  }
+
+  release(): void {
+    // No-op for standard Arduino.
+  }
+
+
+  transfer(value: number | Uint8Array): number {
+    return spiTransfer(this._bus, value);
+  }
+
+  setFrequency(hz: number): void {
+    spiBeginTx(this._bus, `SPISettings(${hz}, MSBFIRST, SPI_MODE0)`);
+  }
+
+  beginTransaction(settings: SPISettings): void {
+    spiBeginTx(this._bus, settings);
+  }
+
+  endTransaction(): void {
+    spiEndTx(this._bus);
+  }
+
+  setMode(mode: SPIMode): void {
+    spiSetMode(this._bus, mode);
+  }
+
+  setBitOrder(order: 'lsb' | 'msb'): void {
+    spiSetBitOrder(this._bus, order);
+  }
+
+  write(value: number): void {
+    spiTransfer(this._bus, value);
+  }
+
+  write16(value: number): void {
+    rawCpp(`${this._bus}.transfer16(${value});`);
+  }
+}
+
+/** Map TypeCAD SPI instance number to Arduino C++ object name. SPI0→SPI, SPI1→SPI1 */
+export function spiName(instance: number): string {
+  return instance === 0 ? "SPI" : `SPI${instance}`;
+}

package/src/timer.ts

@@ -0,0 +1,59 @@
+import { rawCpp, boardResolve } from './emit.js';
+import { callback } from './callback.js';
+
+/**
+ * HardwareTimer provides direct control over the board's hardware timers.
+ * 
+ * Hardware timers are distinct from the software-based setInterval/setTimeout
+ * and are typically used for high-precision timing, PWM generation, or
+ * interrupt-driven tasks.
+ */
+export class HardwareTimer {
+  private _instance: number;
+
+  constructor(instance: number) {
+    this._instance = instance;
+  }
+
+  /**
+   * Sets the timer frequency in Hertz.
+   * Note: The actual frequency may be limited by the hardware's clock dividers.
+   */
+  setFrequency(hz: number): void {
+    rawCpp(`Timer${this._instance}.setFrequency(${hz});`);
+  }
+
+  /**
+   * Attaches an interrupt handler that executes when the timer overflows.
+   */
+  onOverflow(handler: () => void): void {
+    rawCpp(`Timer${this._instance}.onOverflow(${callback(handler)});`);
+  }
+
+  /**
+   * Starts the timer.
+   */
+  start(): void {
+    rawCpp(`Timer${this._instance}.start();`);
+  }
+
+  /**
+   * Stops the timer.
+   */
+  stop(): void {
+    rawCpp(`Timer${this._instance}.stop();`);
+  }
+
+  /**
+   * Returns the bit resolution of the timer (e.g., 8, 16, 32).
+   */
+  getBits(): number {
+    // "peripherals.timer" (singular) matches the board-resolver's array-key
+    // derivation (TIMER_INSTANCES → peripherals.timer.<index>.*).
+    return boardResolve("peripherals.timer." + this._instance + ".bits");
+  }
+}
+
+export const Timer0 = new HardwareTimer(0);
+export const Timer1 = new HardwareTimer(1);
+export const Timer2 = new HardwareTimer(2);

package/src/timing.ts

@@ -0,0 +1,67 @@
+import { rawCpp, getMillis, getMicros, getFreeHeap, delayMs, delayMicro } from './emit.js';
+import { callback } from './callback.js';
+
+export class TimingClass {
+  static readonly __instance_name = "Timing";
+  millis(): number { return getMillis(); }
+  micros(): number { return getMicros(); }
+  delay(ms: number): void { delayMs(ms); }
+  delayMicroseconds(us: number): void { delayMicro(us); }
+  freeHeap(): number {
+    return getFreeHeap();
+  }
+
+
+  setInterval(handler: () => void, timeout: number): number {
+    rawCpp(`return __tc_setInterval(${callback(handler)}, ${timeout});`);
+    return 0;
+  }
+
+  setTimeout(handler: () => void, timeout: number): number {
+    rawCpp(`return __tc_setTimeout(${callback(handler)}, ${timeout});`);
+    return 0;
+  }
+
+  clearInterval(id: number): void {
+    rawCpp(`__tc_clearInterval(${id});`);
+  }
+
+  clearTimeout(id: number): void {
+    rawCpp(`__tc_clearTimeout(${id});`);
+  }
+}
+
+export const Timing = new TimingClass();
+
+export function delay(ms: number): void { delayMs(ms); }
+export function millis(): number { return getMillis(); }
+export function micros(): number { return getMicros(); }
+export function delayMicroseconds(us: number): void { delayMicro(us); }
+export function freeHeap(): number { return Timing.freeHeap(); }
+
+
+export function setInterval(handler: () => void, timeout: number): number {
+  rawCpp(`return __tc_setInterval(${callback(handler)}, ${timeout});`);
+  return 0;
+}
+
+export function setTimeout(handler: () => void, timeout: number): number {
+  rawCpp(`return __tc_setTimeout(${callback(handler)}, ${timeout});`);
+  return 0;
+}
+
+export function clearInterval(id: number): void {
+  rawCpp(`__tc_clearInterval(${id});`);
+}
+
+export function clearTimeout(id: number): void {
+  rawCpp(`__tc_clearTimeout(${id});`);
+}
+
+/** Re-map a number from one range to another. Passes through to the Arduino
+ *  core `map()` macro — the transpiler lowers this to a bare `map(...)` call,
+ *  so the target framework must provide the implementation (Arduino.h does). */
+export function map(value: number, fromLow: number, fromHigh: number, toLow: number, toHigh: number): number { return 0; }
+/** Constrain a number to a range. Passes through to the Arduino core
+ *  `constrain()` macro — see note on `map()` above. */
+export function constrain(value: number, low: number, high: number): number { return 0; }

package/src/types.ts

@@ -0,0 +1,144 @@
+// ---------------------------------------------------------------------------
+// @typecad/hal — Public type definitions
+//
+// Transpiler-shim type surface: enums, type aliases, and the pin-group API
+// consumed by the HAL's transpiler-shim classes (Pin/OutputPin/InputPin,
+// I2CBus/SPIBus/SerialPort) and re-exported for downstream type-checking.
+//
+// Runtime-contract interfaces (BasePin, II2CBus, ISPIBus, ISerialPort, the
+// status enums, capability guards, etc.) have been relocated to
+// @typecad/simulator/src/contracts.ts — they describe the runtime objects the
+// simulator implements, not the transpiler shims that live here.
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Digital/analog value types
+// ---------------------------------------------------------------------------
+
+/** A digital value is a plain boolean. */
+export type DigitalValue = boolean;
+
+/** An analog value is a plain number (resolution-dependent). */
+export type AnalogValue = number;
+
+// ---------------------------------------------------------------------------
+// Pin mode enum
+// ---------------------------------------------------------------------------
+
+export enum PinMode {
+  INPUT             = 'INPUT',
+  OUTPUT            = 'OUTPUT',
+  INPUT_PULLUP      = 'INPUT_PULLUP',
+  INPUT_PULLDOWN    = 'INPUT_PULLDOWN',
+  OUTPUT_OPEN_DRAIN = 'OUTPUT_OPEN_DRAIN',
+  ANALOG            = 'ANALOG',
+}
+
+// ---------------------------------------------------------------------------
+// Interrupt mode enum
+// ---------------------------------------------------------------------------
+
+export enum InterruptMode {
+  RISING  = 'RISING',
+  FALLING = 'FALLING',
+  CHANGE  = 'CHANGE',
+  LOW     = 'LOW',
+  HIGH    = 'HIGH',
+}
+
+// ---------------------------------------------------------------------------
+// Interrupt handler type
+// ---------------------------------------------------------------------------
+
+export type InterruptHandler = () => void;
+
+// ---------------------------------------------------------------------------
+// Pin groups
+// ---------------------------------------------------------------------------
+
+export interface PinGroupMember {
+  readonly number: number;
+  readonly gpio: number;
+  write(value: DigitalValue): void;
+  high(): void;
+  low(): void;
+  toggle(): void;
+  read(): DigitalValue;
+  isHigh(): boolean;
+  isLow(): boolean;
+}
+
+export interface IPinGroup<T extends PinGroupMember = PinGroupMember> {
+  readonly name: string;
+  readonly pins: ReadonlyArray<T>;
+  writePattern(pattern: number): void;
+  readPattern(): number;
+  fill(value: DigitalValue): void;
+}
+
+export function createPinGroup<T extends PinGroupMember>(
+  pins: T[]
+): IPinGroup<T> {
+  return {
+    name: 'PinGroup',
+    pins: Object.freeze(pins) as ReadonlyArray<T>,
+    writePattern(pattern: number): void {
+      for (let i = 0; i < this.pins.length; i++) {
+        const bit = (pattern >> i) & 1;
+        const pin = this.pins[i];
+        if ('write' in pin && typeof pin.write === 'function') {
+          pin.write(bit === 1);
+        }
+      }
+    },
+    readPattern(): number {
+      let value = 0;
+      for (let i = 0; i < this.pins.length; i++) {
+        const pin = this.pins[i];
+        if ('isHigh' in pin && typeof pin.isHigh === 'function' && pin.isHigh()) {
+          value |= (1 << i);
+        }
+      }
+      return value;
+    },
+    fill(value: DigitalValue): void {
+      for (const pin of this.pins) {
+        if ('write' in pin && typeof pin.write === 'function') {
+          pin.write(value);
+        }
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Architecture identifier
+// ---------------------------------------------------------------------------
+
+export type ArchitectureIdentifier =
+  | 'avr'
+  | 'esp32'
+  | 'esp32s2'
+  | 'esp32s3'
+  | 'esp32c3'
+  | 'esp32c6'
+  | 'rp2040'
+  | 'samd'
+  | 'stm32'
+  | 'nrf52'
+  | (string & {});
+
+// ---------------------------------------------------------------------------
+// Protocol-shape types (re-exported by @typecad/framework-arduino)
+// ---------------------------------------------------------------------------
+
+export type I2CAddress = number;
+
+export type SPIBitOrder = 'msb' | 'lsb';
+export type SPIMode = 0 | 1 | 2 | 3;
+
+export interface SPISettings {
+  frequency: number;
+  mode: SPIMode;
+  bitOrder: SPIBitOrder;
+}

package/src/uart.ts

@@ -0,0 +1,77 @@
+import { uartBegin, uartEnd, uartPrint, uartPrintln, uartPrintf, uartWrite, uartRead, uartPeek, uartAvailable, uartFlush, rawCpp } from './emit.js';
+
+export class SerialPort {
+  static readonly __includes = ["<Arduino.h>"];
+  private _port: string;
+
+  constructor(port: string) {
+    this._port = port;
+  }
+
+  begin(baud: number = 9600): this {
+    uartBegin(this._port, baud);
+    return this;
+  }
+
+  end(): void {
+    uartEnd(this._port);
+  }
+
+  print(value: any): void {
+    uartPrint(this._port, value);
+  }
+
+  println(value: any): void {
+    uartPrintln(this._port, value);
+  }
+
+  printf(format: string, ...args: any[]): void {
+    uartPrintf(this._port, format, args);
+  }
+
+  write(data: any): void {
+    uartWrite(this._port, data);
+  }
+
+  read(): number {
+    return uartRead(this._port);
+  }
+
+  readLine(): string {
+    rawCpp(`return ${this._port}.readStringUntil('\\n');`);
+    return "";
+  }
+
+  peek(): number {
+    return uartPeek(this._port);
+  }
+
+  available(): number {
+    return uartAvailable(this._port);
+  }
+
+  flush(): void {
+    uartFlush(this._port);
+  }
+
+  waitForConnection(timeout?: number): Promise<void> {
+    rawCpp(`while (!${this._port}) { delay(10); }`);
+    return Promise.resolve();
+  }
+
+  take(): this | null {
+    // Basic implementation for single-threaded Arduino; 
+    // real locking would be framework-specific.
+    return this;
+  }
+
+  release(): void {
+    // No-op for standard Arduino.
+  }
+}
+
+
+/** Map TypeCAD UART instance number to Arduino C++ object name. UART0→Serial, UART1→Serial1 */
+export function serialName(instance: number): string {
+  return instance === 0 ? "Serial" : `Serial${instance}`;
+}