@typecad/simulator 0.1.0-alpha.1

package/src/contracts.ts

@@ -0,0 +1,330 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — Runtime contract interfaces
+//
+// These types define the runtime contracts that @typecad/simulator's simulated
+// peripheral classes implement (SimDigitalPin, SimI2CBus, SimSPIBus,
+// SimSerialPort, ...). They were relocated here from @typecad/hal so that HAL
+// contains only its transpiler-shim surface, and the simulator owns the
+// hierarchy that matches its job (real behavioral objects, not IR emitters).
+//
+// Primitive aliases that the contracts still reference (DigitalValue,
+// AnalogValue, InterruptHandler) and the protocol-shape types (I2CAddress,
+// SPIMode, SPIBitOrder, SPISettings) remain in @typecad/hal and are imported
+// below. The dependency direction is simulator → hal (already established).
+// ---------------------------------------------------------------------------
+
+import type {
+  DigitalValue,
+  AnalogValue,
+  InterruptHandler,
+  I2CAddress,
+} from '@typecad/hal';
+import type {
+  SPIMode,
+  SPIBitOrder,
+  SPISettings,
+} from '@typecad/hal';
+
+// ---------------------------------------------------------------------------
+// Pin capability flags
+// ---------------------------------------------------------------------------
+
+export interface PinCapabilityFlags {
+  digitalInput: boolean;
+  digitalOutput: boolean;
+  analogInput: boolean;
+  /** DAC output */
+  analogOutput: boolean;
+  pwm: boolean;
+  interrupt: boolean;
+  pullUp: boolean;
+  pullDown: boolean;
+  touch: boolean;
+  openDrain: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Tone attachment (returned by tone() for chaining .for() duration)
+// ---------------------------------------------------------------------------
+
+export interface IToneAttachment {
+  for(duration: number): void;
+}
+
+// ---------------------------------------------------------------------------
+// Interrupt handler types
+// ---------------------------------------------------------------------------
+
+export interface InterruptOptions {
+  debounce?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Pin interfaces (used by the simulator package)
+// ---------------------------------------------------------------------------
+
+export interface BasePin {
+  readonly number: number;
+  readonly gpio: number;
+  readonly capabilities: PinCapabilityFlags;
+  read(): DigitalValue;
+  isHigh(): boolean;
+  isLow(): boolean;
+  write(value: DigitalValue): void;
+  high(): void;
+  low(): void;
+  toggle(): void;
+  pulse(duration: number): void;
+  tone(frequency: number): IToneAttachment;
+  noTone(): void;
+  inputPullUp(): void;
+  inputPullDown?(): void;
+  outputOpenDrain(initial?: DigitalValue): void;
+  asOutput(initial?: DigitalValue): IOutputModePin;
+  asInput(): IInputModePin;
+  asInputPullUp(): IInputModePin;
+  pwm?(percent: number): void;
+  getPwmFrequency?(): number;
+  getPwmResolution?(): number;
+  readAnalog?(): AnalogValue;
+  readVoltage?(): number;
+  setAnalogReference?(voltage: number): void;
+  getAnalogResolution?(): number;
+  onRising?(handler: InterruptHandler, options?: InterruptOptions): void;
+  onFalling?(handler: InterruptHandler, options?: InterruptOptions): void;
+  onChange?(handler: InterruptHandler, options?: InterruptOptions): void;
+  offInterrupts?(): void;
+  waitForRising(timeout?: number): Promise<void>;
+  waitForFalling(timeout?: number): Promise<void>;
+}
+
+export interface IOutputModePin {
+  readonly number: number;
+  readonly gpio: number;
+  readonly capabilities: PinCapabilityFlags;
+  write(value: DigitalValue): void;
+  high(): void;
+  low(): void;
+  toggle(): void;
+  pulse(duration: number): void;
+  tone(frequency: number): IToneAttachment;
+  noTone(): void;
+  pwm?(percent: number): void;
+  getPwmFrequency?(): number;
+  getPwmResolution?(): number;
+  asOutput(initial?: DigitalValue): IOutputModePin;
+  asInput(): IInputModePin;
+  asInputPullUp(): IInputModePin;
+  inputPullUp(): void;
+  inputPullDown?(): void;
+  outputOpenDrain(initial?: DigitalValue): void;
+}
+
+export interface IInputModePin {
+  readonly number: number;
+  readonly gpio: number;
+  readonly capabilities: PinCapabilityFlags;
+  read(): DigitalValue;
+  isHigh(): boolean;
+  isLow(): boolean;
+  readAnalog?(): AnalogValue;
+  readVoltage?(): number;
+  setAnalogReference?(voltage: number): void;
+  getAnalogResolution?(): number;
+  onRising?(handler: InterruptHandler, options?: InterruptOptions): void;
+  onFalling?(handler: InterruptHandler, options?: InterruptOptions): void;
+  onChange?(handler: InterruptHandler, options?: InterruptOptions): void;
+  offInterrupts?(): void;
+  waitForRising(timeout?: number): Promise<void>;
+  waitForFalling(timeout?: number): Promise<void>;
+  asOutput(initial?: DigitalValue): IOutputModePin;
+  asInput(): IInputModePin;
+  asInputPullUp(): IInputModePin;
+  inputPullUp(): void;
+  inputPullDown?(): void;
+  outputOpenDrain(initial?: DigitalValue): void;
+}
+
+/** Pin with PWM output capability. */
+export type PWMPin = BasePin & { pwm: NonNullable<BasePin['pwm']> };
+
+/** Pin with analog input capability. */
+export type AnalogPin = BasePin & { readAnalog: NonNullable<BasePin['readAnalog']> };
+
+/** Pin with interrupt capability. */
+export type InterruptPin = BasePin & { onRising: NonNullable<BasePin['onRising']> };
+
+// ---------------------------------------------------------------------------
+// Capability type guards and assertions
+// ---------------------------------------------------------------------------
+
+function isBasePin(value: unknown): value is BasePin {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'number' in value &&
+    'gpio' in value
+  );
+}
+
+export function hasPWM(pin: unknown): pin is PWMPin {
+  return isBasePin(pin) && 'pwm' in pin && typeof pin.pwm === 'function';
+}
+
+export function hasAnalogInput(pin: unknown): pin is AnalogPin {
+  return isBasePin(pin) && 'readAnalog' in pin && typeof pin.readAnalog === 'function';
+}
+
+export function hasInterrupt(pin: unknown): pin is InterruptPin {
+  return isBasePin(pin) && 'onRising' in pin && typeof pin.onRising === 'function';
+}
+
+export function assertPWM(pin: BasePin, message?: string): asserts pin is PWMPin {
+  if (!hasPWM(pin)) {
+    throw new Error(message ?? 'Pin does not support PWM');
+  }
+}
+
+export function assertAnalog(pin: BasePin, message?: string): asserts pin is AnalogPin {
+  if (!hasAnalogInput(pin)) {
+    throw new Error(message ?? 'Pin does not support analog input');
+  }
+}
+
+export function assertInterrupt(pin: BasePin, message?: string): asserts pin is InterruptPin {
+  if (!hasInterrupt(pin)) {
+    throw new Error(message ?? 'Pin does not support interrupts');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Error policy
+// ---------------------------------------------------------------------------
+
+export type ErrorPolicy = 'throw' | 'callback' | 'silent';
+
+// ---------------------------------------------------------------------------
+// I2C types
+// ---------------------------------------------------------------------------
+
+export enum I2CStatus {
+  SUCCESS = 0,
+  DATA_TOO_LONG = 1,
+  NACK_ON_ADDRESS = 2,
+  NACK_ON_DATA = 3,
+  OTHER_ERROR = 4,
+  PARTIAL_READ = 5,
+}
+
+export interface II2CDeviceAccessor {
+  readonly address: I2CAddress;
+  readByte(register: number): number;
+  readBytes(register: number, count: number): Uint8Array;
+  writeByte(register: number, value: number): void;
+  writeBytes(register: number, data: Uint8Array | number[]): void;
+}
+
+export interface II2CBus {
+  readonly busNumber: number;
+  readonly isEnabled: boolean;
+  begin(): void;
+  begin(address: I2CAddress): void;
+  end(): void;
+  setClock(hz: number): void;
+  device(address: I2CAddress): II2CDeviceAccessor;
+  onError(handler: (status: I2CStatus, address: I2CAddress, operation: 'read' | 'write') => void): void;
+  errorPolicy: ErrorPolicy;
+  recover(): boolean;
+}
+
+// ---------------------------------------------------------------------------
+// SPI types
+// ---------------------------------------------------------------------------
+
+export enum SPIStatus {
+  SUCCESS = 0,
+  NOT_INITIALIZED = 1,
+  TRANSFER_FAILED = 2,
+  INVALID_CONFIG = 3,
+  TIMEOUT = 4,
+  DEVICE_ERROR = 5,
+}
+
+export interface ISPIDevice {
+  readonly chipSelect: BasePin;
+  transfer(data: number | Uint8Array): Uint8Array;
+  write(data: number | Uint8Array): void;
+  read(count: number): Uint8Array;
+  writeRegister(register: number, data: number | Uint8Array): void;
+  readRegister(register: number, count: number): Uint8Array;
+}
+
+export interface ISPIBus {
+  readonly isEnabled: boolean;
+  begin(): void;
+  end(): void;
+  setMode(mode: SPIMode): void;
+  setBitOrder(order: SPIBitOrder): void;
+  setFrequency(hz: number): void;
+  beginTransaction(settings: SPISettings): void;
+  endTransaction(): void;
+  device(chipSelect: BasePin): ISPIDevice;
+  onError(handler: (status: SPIStatus, operation: 'transfer' | 'read' | 'write') => void): void;
+  errorPolicy: ErrorPolicy;
+}
+
+// ---------------------------------------------------------------------------
+// UART types
+// ---------------------------------------------------------------------------
+
+export enum UARTStatus {
+  SUCCESS = 0,
+  NOT_INITIALIZED = 1,
+  TIMEOUT = 2,
+  BUFFER_OVERFLOW = 3,
+  OVERRUN_ERROR = 4,
+  PARITY_ERROR = 5,
+  FRAMING_ERROR = 6,
+  BREAK_DETECTED = 7,
+  WRITE_FAILED = 8,
+  READ_FAILED = 9,
+}
+
+export interface UARTStatusInfo {
+  available: number;
+  writeAvailable: number;
+  overrunError: boolean;
+  parityError: boolean;
+  framingError: boolean;
+  breakDetected: boolean;
+}
+
+export interface IUARTBus {
+  readonly uartNumber: number;
+  readonly baudRate: number;
+  readonly isEnabled: boolean;
+  begin(baud: number): void;
+  end(): void;
+  read(): number;
+  peek(): number;
+  readLine(): string;
+  readBytes(count: number): Uint8Array;
+  readString(): string;
+  available(): number;
+  write(data: number | Uint8Array | string): number;
+  flush(): void;
+  getStatus(): UARTStatusInfo;
+  clearErrors(): void;
+  onReceive(callback: (bytesAvailable: number) => void): void;
+  onTransmitComplete(callback: () => void): void;
+  onError(callback: (status: UARTStatus) => void): void;
+  errorPolicy: ErrorPolicy;
+}
+
+export interface ISerialPort extends IUARTBus {
+  print(...args: unknown[]): void;
+  println(...args: unknown[]): void;
+  printf(format: string, ...args: unknown[]): void;
+  isConnected(): boolean;
+  waitForConnection(timeout?: number): Promise<void>;
+}

package/src/gpio/analog-pin-sim.ts

@@ -0,0 +1,91 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — Simulated analog input pin
+// ---------------------------------------------------------------------------
+
+import type { AnalogPin } from '../contracts.js';
+import type { AnalogValue } from '@typecad/hal';
+import { SimDigitalPin } from './digital-pin-sim.js';
+
+/**
+ * Simulated analog input pin.
+ *
+ * Extends SimDigitalPin with analog read capabilities.
+ * Tests can inject values via `injectValue()` and verify readings.
+ *
+ * - `read()` returns a digital boolean (HIGH if above half-scale).
+ * - `readAnalog()` returns the raw ADC value.
+ */
+export class SimAnalogPin extends SimDigitalPin implements AnalogPin {
+  private _analogValue: AnalogValue = 0;
+  private _voltage: number = 0;
+  private _reference: number = 5.0; // Default 5V reference
+  private _resolution: number = 10; // Default 10-bit (0-1023)
+
+  constructor(pinNum: number) {
+    super(pinNum, { analogInput: true });
+  }
+
+  // --- AnalogPin capability methods ---
+
+  /** Convenience: set pin to analog input mode. */
+  analog(): void {
+    this.asInput();
+  }
+
+  readAnalog(): AnalogValue {
+    return this._analogValue;
+  }
+
+  readVoltage(): number {
+    return this._voltage;
+  }
+
+  setAnalogReference(voltage: number): void {
+    this._reference = voltage;
+  }
+
+  getAnalogResolution(): number {
+    return this._resolution;
+  }
+
+  // --- Simulation helpers ---
+
+  /**
+   * Inject an analog value (e.g., sensor reading).
+   * Also updates the digital read state based on threshold.
+   * @param value - Raw ADC value (0 to 2^resolution - 1)
+   */
+  override injectValue(value: AnalogValue): void {
+    this._analogValue = value;
+    // Calculate voltage from ADC value
+    const maxAdc = (1 << this._resolution) - 1;
+    this._voltage = (value / maxAdc) * this._reference;
+    // Update digital state: HIGH if above half-scale
+    super.injectValue(value > (maxAdc / 2) ? 1 : 0);
+  }
+
+  /**
+   * Inject a voltage directly. Converts to ADC value based on resolution.
+   */
+  injectVoltage(voltage: number): void {
+    this._voltage = voltage;
+    const maxAdc = (1 << this._resolution) - 1;
+    this._analogValue = Math.round((voltage / this._reference) * maxAdc);
+    super.injectValue(this._analogValue > (maxAdc / 2) ? 1 : 0);
+  }
+
+  /**
+   * Set the ADC resolution in bits.
+   */
+  setResolution(bits: number): void {
+    this._resolution = bits;
+  }
+
+  override reset(): void {
+    super.reset();
+    this._analogValue = 0;
+    this._voltage = 0;
+    this._reference = 5.0;
+    this._resolution = 10;
+  }
+}

package/src/gpio/digital-pin-sim.ts

@@ -0,0 +1,234 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — Simulated digital pin
+// ---------------------------------------------------------------------------
+
+import type {
+  BasePin,
+  IToneAttachment,
+  PinCapabilityFlags,
+} from '../contracts.js';
+import { PinMode } from '@typecad/hal';
+import type { DigitalValue } from '@typecad/hal';
+
+/**
+ * Tracks the history of pin state changes for test assertions.
+ */
+export interface PinStateChange {
+  /** Timestamp (ms since simulation start) */
+  timestamp: number;
+  /** Previous value (0 or 1) */
+  from: number;
+  /** New value (0 or 1) */
+  to: number;
+}
+
+/**
+ * Convert a DigitalValue to a plain 0/1 number.
+ */
+function toBitValue(value: DigitalValue): number {
+  return value ? 1 : 0;
+}
+
+/**
+ * Simulated digital pin that tracks state transitions.
+ */
+/** Default capability flags for a digital pin. */
+const DEFAULT_DIGITAL_CAPS: PinCapabilityFlags = {
+  digitalInput: true,
+  digitalOutput: true,
+  analogInput: false,
+  analogOutput: false,
+  pwm: false,
+  interrupt: false,
+  pullUp: true,
+  pullDown: false,
+  touch: false,
+  openDrain: false,
+};
+
+export class SimDigitalPin implements BasePin {
+  readonly number: number;
+  readonly gpio: number;
+  readonly capabilities: PinCapabilityFlags;
+
+  private _value: number = 0;
+  private _pinMode: PinMode = PinMode.OUTPUT;
+  private _history: PinStateChange[] = [];
+  protected _startTime: number = Date.now();
+
+  constructor(pinNum: number, caps?: Partial<PinCapabilityFlags>) {
+    this.number = pinNum;
+    this.gpio = pinNum;
+    this.capabilities = { ...DEFAULT_DIGITAL_CAPS, ...caps };
+  }
+
+  // --- BasePin ---
+
+  getMode(): PinMode {
+    return this._pinMode;
+  }
+
+  setMode(mode: PinMode): void {
+    this._pinMode = mode;
+  }
+
+  has(capability: keyof PinCapabilityFlags): boolean {
+    return this.capabilities[capability];
+  }
+
+  // --- Pin configuration ---
+
+  inputPullUp(): void {
+    this._pinMode = PinMode.INPUT_PULLUP;
+    this._setBitValue(1);
+  }
+
+  inputPullDown(): void {
+    this._pinMode = PinMode.INPUT_PULLDOWN;
+    this._setBitValue(0);
+  }
+
+  outputOpenDrain(initial?: DigitalValue): void {
+    this._pinMode = PinMode.OUTPUT_OPEN_DRAIN;
+    if (initial !== undefined) {
+      this._setBitValue(toBitValue(initial));
+    }
+  }
+
+  // --- Fluent mode conversion ---
+
+  asOutput(initial?: DigitalValue): any {
+    this._pinMode = PinMode.OUTPUT;
+    if (initial !== undefined) {
+      this._setBitValue(toBitValue(initial));
+    }
+    return this;
+  }
+
+  asInput(): any {
+    this._pinMode = PinMode.INPUT;
+    return this;
+  }
+
+  asInputPullUp(): any {
+    this.inputPullUp();
+    return this;
+  }
+
+  // --- IDigitalInput ---
+
+  read(): DigitalValue {
+    return this._value === 1;
+  }
+
+  isHigh(): boolean {
+    return this._value === 1;
+  }
+
+  isLow(): boolean {
+    return this._value === 0;
+  }
+
+  async waitForRising(_timeout?: number): Promise<void> {
+    // In simulation, this resolves immediately.
+    // Tests should use injectValue() + explicit assertions instead.
+  }
+
+  async waitForFalling(_timeout?: number): Promise<void> {
+    // In simulation, this resolves immediately.
+  }
+
+  // --- IDigitalOutput ---
+
+  write(value: DigitalValue): void {
+    this._setBitValue(toBitValue(value));
+  }
+
+  high(): void {
+    this._setBitValue(1);
+  }
+
+  low(): void {
+    this._setBitValue(0);
+  }
+
+  toggle(): void {
+    this._setBitValue(this._value === 1 ? 0 : 1);
+  }
+
+  pulse(_duration: number): void {
+    // In simulation the pulse duration is not awaited, so a pulse produces no
+    // observable transition — leave both pin state and history unchanged.
+  }
+
+  tone(_frequency: number): IToneAttachment {
+    return {
+      for(_duration: number): void {
+        // No-op in simulation
+      },
+    };
+  }
+
+  noTone(): void {
+    // No-op in simulation
+  }
+
+  stop(): void {
+    this.noTone();
+  }
+
+  // --- Simulation helpers ---
+
+  /**
+   * Inject a value into this pin (simulates external signal).
+   * Use this in tests to simulate button presses, sensor triggers, etc.
+   */
+  injectValue(value: number): void {
+    this._setBitValue(value & 1);
+  }
+
+  /**
+   * Get the history of all state changes on this pin.
+   */
+  getHistory(): readonly PinStateChange[] {
+    return this._history;
+  }
+
+  /**
+   * Clear the state change history.
+   */
+  clearHistory(): void {
+    this._history = [];
+  }
+
+  /**
+   * Get the current value as a plain number (0 or 1).
+   */
+  getBitValue(): number {
+    return this._value;
+  }
+
+  /**
+   * Reset the pin to its initial state.
+   */
+  reset(): void {
+    this._value = 0;
+    this._pinMode = PinMode.OUTPUT;
+    this._history = [];
+    this._startTime = Date.now();
+  }
+
+  // --- Internal ---
+
+  private _setBitValue(newValue: number): void {
+    const oldValue = this._value;
+    this._value = newValue & 1;
+    if (oldValue !== this._value) {
+      this._history.push({
+        timestamp: Date.now() - this._startTime,
+        from: oldValue,
+        to: this._value,
+      });
+    }
+  }
+}