@typecad/simulator 0.1.0-alpha.1

package/src/gpio/interrupt-sim.ts

@@ -0,0 +1,151 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — Interrupt simulation
+// ---------------------------------------------------------------------------
+
+import type { InterruptPin, InterruptOptions } from '../contracts.js';
+import type { InterruptHandler } from '@typecad/hal';
+import { SimDigitalPin } from './digital-pin-sim.js';
+
+type InterruptMode = 'rising' | 'falling' | 'change';
+
+/**
+ * Tracks interrupt firings for test assertions.
+ */
+export interface InterruptEvent {
+  /** Timestamp (ms since simulation start) */
+  timestamp: number;
+  /** The trigger mode */
+  mode: InterruptMode;
+  /** The pin value at time of interrupt */
+  pinValue: number;
+}
+
+/**
+ * Simulated interrupt controller for a single pin.
+ *
+ * Extends SimDigitalPin with interrupt capabilities.
+ * Tests can fire interrupts manually via `fireInterrupt()` and verify
+ * that handlers were called with the correct arguments.
+ */
+export class SimInterruptPin extends SimDigitalPin implements InterruptPin {
+  private _handlers: Map<InterruptMode, InterruptHandler> = new Map();
+  private _debounceMs: number = 0;
+  private _events: InterruptEvent[] = [];
+
+  constructor(pinNum: number) {
+    super(pinNum, { interrupt: true });
+  }
+
+  // --- InterruptPin capability methods ---
+
+  onRising(handler: InterruptHandler, options?: InterruptOptions): void {
+    this._handlers.set('rising', handler);
+    if (options?.debounce) this._debounceMs = options.debounce;
+  }
+
+  onFalling(handler: InterruptHandler, options?: InterruptOptions): void {
+    this._handlers.set('falling', handler);
+    if (options?.debounce) this._debounceMs = options.debounce;
+  }
+
+  onChange(handler: InterruptHandler, options?: InterruptOptions): void {
+    this._handlers.set('change', handler);
+    if (options?.debounce) this._debounceMs = options.debounce;
+  }
+
+  offInterrupts(): void {
+    this._handlers.clear();
+  }
+
+  /** Remove the rising-edge handler. */
+  offRising(): void {
+    this._handlers.delete('rising');
+  }
+
+  /** Remove the falling-edge handler. */
+  offFalling(): void {
+    this._handlers.delete('falling');
+  }
+
+  /** Remove all interrupt handlers. */
+  offAll(): void {
+    this._handlers.clear();
+  }
+
+  /** Check if any interrupt handlers are registered. */
+  hasInterrupt(): boolean {
+    return this._handlers.size > 0;
+  }
+
+  // --- Simulation helpers ---
+
+  /**
+   * Fire an interrupt manually from test code.
+   * @param mode - The interrupt mode to fire
+   * @param pinValue - The current pin value (for event logging)
+   */
+  fireInterrupt(mode: InterruptMode, pinValue: number = 0): void {
+    const handler = this._handlers.get(mode);
+    if (handler) {
+      handler();
+    }
+
+    // Also fire 'change' handler for any edge
+    if (mode !== 'change' && this._handlers.has('change')) {
+      this._handlers.get('change')!();
+    }
+
+    this._events.push({
+      timestamp: Date.now() - this._startTime,
+      mode,
+      pinValue,
+    });
+  }
+
+  /**
+   * Simulate a pin value transition, automatically firing the appropriate interrupts.
+   * @param from - Previous pin value (0 or 1)
+   * @param to - New pin value (0 or 1)
+   */
+  simulateTransition(from: number, to: number): void {
+    if (from === to) return;
+
+    if (from === 0 && to === 1) {
+      this.fireInterrupt('rising', to);
+    } else if (from === 1 && to === 0) {
+      this.fireInterrupt('falling', to);
+    }
+  }
+
+  /**
+   * Get all recorded interrupt events.
+   */
+  getEvents(): readonly InterruptEvent[] {
+    return this._events;
+  }
+
+  /**
+   * Clear interrupt event history.
+   */
+  clearEvents(): void {
+    this._events = [];
+  }
+
+  /**
+   * Get the configured debounce time.
+   */
+  getDebounceMs(): number {
+    return this._debounceMs;
+  }
+
+  /**
+   * Reset to initial state.
+   */
+  override reset(): void {
+    super.reset();
+    this._handlers.clear();
+    this._debounceMs = 0;
+    this._events = [];
+    this._startTime = Date.now();
+  }
+}

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

@@ -0,0 +1,103 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — Simulated PWM pin
+// ---------------------------------------------------------------------------
+
+import type { PWMPin } from '../contracts.js';
+import type { AnalogValue, DigitalValue } from '@typecad/hal';
+import { SimDigitalPin } from './digital-pin-sim.js';
+
+/**
+ * Simulated PWM pin. Extends digital pin with PWM duty cycle control.
+ */
+export class SimPWMPin extends SimDigitalPin implements PWMPin {
+  private _pwmPercent: number = 0;
+  private _pwmFrequency: number = 490; // Default Arduino PWM frequency
+  private _pwmResolution: number = 8; // Default 8-bit
+  private _attached: boolean = false;
+
+  constructor(pinNum: number) {
+    super(pinNum);
+  }
+
+  // --- PWMPin ---
+
+  write(value: DigitalValue | AnalogValue): void {
+    if (typeof value === 'number' && value > 1) {
+      // Analog write — treat as PWM duty cycle value
+      this.pwm((value / ((1 << this._pwmResolution) - 1)) * 100);
+    } else {
+      super.write(value as DigitalValue);
+    }
+  }
+
+  pwm(percent?: number): void {
+    // Calling pwm() (no args) activates PWM mode, pwm(x) sets duty cycle
+    // 0% duty cycle means PWM is inactive
+    this._attached = percent === undefined || percent > 0;
+    if (percent !== undefined) {
+      this._pwmPercent = Math.max(0, Math.min(100, percent));
+    }
+  }
+
+  setFrequency(hz: number): void {
+    this._pwmFrequency = hz;
+  }
+
+  /** Current PWM frequency in Hz (contract method name). */
+  getPwmFrequency(): number {
+    return this._pwmFrequency;
+  }
+
+  /** Current PWM resolution in bits (contract method name). */
+  getPwmResolution(): number {
+    return this._pwmResolution;
+  }
+
+  /** @deprecated Use getPwmFrequency() to match the HAL contract. */
+  getFrequency(): number {
+    return this.getPwmFrequency();
+  }
+
+  /** @deprecated Use getPwmResolution() to match the HAL contract. */
+  getResolution(): number {
+    return this.getPwmResolution();
+  }
+
+  // --- Simulation helpers ---
+
+  /**
+   * Get the current PWM duty cycle as a percentage (0-100).
+   */
+  getPwmPercent(): number {
+    return this._pwmPercent;
+  }
+
+  /**
+   * Get the current PWM duty cycle as a raw value (0 to 2^resolution - 1).
+   */
+  getPwmValue(): number {
+    return Math.round((this._pwmPercent / 100) * ((1 << this._pwmResolution) - 1));
+  }
+
+  /**
+   * Check if PWM is currently active.
+   */
+  isPwmActive(): boolean {
+    return this._attached;
+  }
+
+  /**
+   * Set the PWM resolution in bits.
+   */
+  setResolution(bits: number): void {
+    this._pwmResolution = bits;
+  }
+
+  override reset(): void {
+    super.reset();
+    this._pwmPercent = 0;
+    this._pwmFrequency = 490;
+    this._pwmResolution = 8;
+    this._attached = false;
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,100 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — Result factory helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Result of a byte read operation (used internally by bus simulators).
+ */
+export interface IByteReadResult {
+  ok: boolean;
+  status: number;
+  bytes: Uint8Array;
+  bytesRead: number;
+  timedOut: boolean;
+  asUint8(): number;
+  asInt8(): number;
+  asUint16(endian: 'be' | 'le'): number;
+  asInt16(endian: 'be' | 'le'): number;
+  asUint32(endian: 'be' | 'le'): number;
+  asInt32(endian: 'be' | 'le'): number;
+  asString(): string;
+  asStringTrim(): string;
+  asInt(): number;
+  asFloat(): number;
+  unwrap(): Uint8Array;
+  unwrapOr(defaultValue: Uint8Array): Uint8Array;
+}
+
+/**
+ * Result of a write operation (used internally by bus simulators).
+ */
+export interface IWriteResult {
+  ok: boolean;
+  status: number;
+  bytesWritten: number;
+  unwrap(): number;
+  unwrapOr(defaultValue: number): number;
+}
+
+/**
+ * Create an IByteReadResult with the given bytes.
+ */
+export function createByteReadResult(
+  bytes: Uint8Array,
+  ok: boolean = true,
+  status: number = 0,
+  timedOut: boolean = false,
+): IByteReadResult {
+  return {
+    ok,
+    status,
+    bytes,
+    bytesRead: bytes.length,
+    timedOut,
+    asUint8(): number { return bytes[0] ?? 0; },
+    asInt8(): number { const v = bytes[0] ?? 0; return v > 127 ? v - 256 : v; },
+    asUint16(endian: 'be' | 'le'): number {
+      if (bytes.length < 2) return 0;
+      return endian === 'be'
+        ? ((bytes[0]! << 8) | bytes[1]!) >>> 0
+        : ((bytes[1]! << 8) | bytes[0]!) >>> 0;
+    },
+    asInt16(endian: 'be' | 'le'): number {
+      const v = this.asUint16(endian);
+      return v > 32767 ? v - 65536 : v;
+    },
+    asUint32(endian: 'be' | 'le'): number {
+      if (bytes.length < 4) return 0;
+      return endian === 'be'
+        ? ((bytes[0]! << 24) | (bytes[1]! << 16) | (bytes[2]! << 8) | bytes[3]!) >>> 0
+        : ((bytes[3]! << 24) | (bytes[2]! << 16) | (bytes[1]! << 8) | bytes[0]!) >>> 0;
+    },
+    asInt32(endian: 'be' | 'le'): number {
+      const v = this.asUint32(endian);
+      return v > 2147483647 ? v - 4294967296 : v;
+    },
+    asString(): string { return new TextDecoder().decode(bytes); },
+    asStringTrim(): string { return this.asString().trim(); },
+    asInt(): number { return parseInt(this.asString(), 10) || 0; },
+    asFloat(): number { return parseFloat(this.asString()) || 0; },
+    unwrap(): Uint8Array { return bytes; },
+    unwrapOr(defaultValue: Uint8Array): Uint8Array { return ok ? bytes : defaultValue; },
+  };
+}
+
+/**
+ * Create an IWriteResult with the given bytesWritten count.
+ */
+export function createWriteResult(
+  bytesWritten: number,
+  ok: boolean = true,
+  status: number = 0,
+): IWriteResult {
+  return {
+    ok,
+    status,
+    bytesWritten,
+    unwrap(): number { return bytesWritten; },
+    unwrapOr(defaultValue: number): number { return ok ? bytesWritten : defaultValue; },
+  };
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — Barrel export
+// ---------------------------------------------------------------------------
+
+// --- GPIO simulation ---
+export { SimDigitalPin } from './gpio/digital-pin-sim.js';
+export { SimAnalogPin } from './gpio/analog-pin-sim.js';
+export { SimPWMPin } from './gpio/pwm-pin-sim.js';
+export { SimInterruptPin } from './gpio/interrupt-sim.js';
+export type { InterruptEvent } from './gpio/interrupt-sim.js';
+
+// --- Bus simulation ---
+export { SimSerialPort } from './bus/serial-sim.js';
+export { SimI2CBus } from './bus/i2c-sim.js';
+export type { I2COperationLog } from './bus/i2c-sim.js';
+export { SimSPIBus } from './bus/spi-sim.js';
+export type { SPIOperationLog } from './bus/spi-sim.js';
+
+// --- Board factory ---
+export { SimBoard, createSimBoard } from './board/board-sim.js';
+export { createBoardFromDefinition } from './board/from-definition.js';
+
+// --- Runtime contract interfaces (relocated from @typecad/hal) ---
+// Pin/bus contracts implemented by the Sim* classes above.
+export type {
+  BasePin,
+  PWMPin,
+  AnalogPin,
+  InterruptPin,
+  IOutputModePin,
+  IInputModePin,
+  II2CBus,
+  II2CDeviceAccessor,
+  ISPIBus,
+  ISPIDevice,
+  IUARTBus,
+  ISerialPort,
+  PinCapabilityFlags,
+  IToneAttachment,
+  UARTStatusInfo,
+  InterruptOptions,
+  ErrorPolicy,
+} from './contracts.js';
+export { I2CStatus, SPIStatus, UARTStatus } from './contracts.js';
+export { hasPWM, hasAnalogInput, hasInterrupt, assertPWM, assertAnalog, assertInterrupt } from './contracts.js';
+
+// --- Types ---
+export { PinMode } from '@typecad/hal';
+export type {
+  PinChangeCallback,
+  InterruptCallback,
+  ISimI2CDevice,
+  ISimSPIDevice,
+  SimBoardType,
+  SimBoardConfig,
+} from './types.js';
+
+// --- Helpers ---
+export { createByteReadResult, createWriteResult } from './helpers.js';

package/src/types.ts

@@ -0,0 +1,104 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — Simulator-specific types
+// ---------------------------------------------------------------------------
+
+/**
+ * Callback signature for pin state change events.
+ * @param pinNumber - The pin number that changed
+ * @param newValue - The new digital value (HIGH=1 or LOW=0)
+ */
+export type PinChangeCallback = (pinNumber: number, newValue: number) => void;
+
+/**
+ * Callback signature for interrupt events.
+ * @param pinNumber - The interrupt pin number
+ * @param mode - The trigger mode ('rising', 'falling', or 'change')
+ */
+export type InterruptCallback = (pinNumber: number, mode: 'rising' | 'falling' | 'change') => void;
+
+/**
+ * A simulated I2C device that responds to register reads and writes.
+ * Tests register mock devices to simulate sensor behavior.
+ */
+export interface ISimI2CDevice {
+  /**
+   * Handle a register read from the bus master.
+   * @param register - The register address being read
+   * @param count - Number of bytes requested
+   * @returns Array of byte values to return
+   */
+  read(register: number, count: number): number[];
+
+  /**
+   * Handle a register write from the bus master.
+   * @param register - The register address being written
+   * @param data - The data bytes being written
+   */
+  write(register: number, data: number[]): void;
+}
+
+/**
+ * A simulated SPI device that responds to transfers.
+ */
+export interface ISimSPIDevice {
+  /**
+   * Handle a full-duplex SPI transfer.
+   * @param mosiData - Data sent from master (MOSI)
+   * @returns Data received from device (MISO)
+   */
+  transfer(mosiData: number[]): number[];
+
+  /**
+   * Handle a register write (optional).
+   * If not provided, falls back to transfer().
+   * @param register - The register address
+   * @param data - The data bytes being written
+   */
+  write?(register: number, data: number[]): void;
+
+  /**
+   * Handle a register read (optional).
+   * If not provided, falls back to transfer() with dummy bytes.
+   * @param register - The register address
+   * @param count - Number of bytes to read
+   * @returns Data bytes read from the register
+   */
+  readRegister?(register: number, count: number): number[];
+}
+
+/**
+ * Board type identifiers for the simulator factory.
+ */
+export type SimBoardType = 'arduino-uno' | 'arduino-nano' | string;
+
+/**
+ * Configuration for creating a simulated board.
+ */
+export interface SimBoardConfig {
+  /** Board type identifier. Determines pin count and peripheral availability. */
+  boardType: SimBoardType;
+  /** Number of digital pins (default: 14 for Uno) */
+  digitalPinCount?: number;
+  /** Number of analog input pins (default: 6 for Uno) */
+  analogPinCount?: number;
+  /** Number of I2C buses (default: 1) */
+  i2cBusCount?: number;
+  /** Number of SPI buses (default: 1) */
+  spiBusCount?: number;
+  /** Number of UART ports (default: 1) */
+  uartCount?: number;
+  /**
+   * PWM-capable pin numbers. Overrides the board type's default PWM pin map.
+   * For unknown/custom board types the default is empty (no PWM pins).
+   */
+  pwmPins?: number[];
+  /**
+   * Interrupt-capable pin numbers. Overrides the board type's default interrupt
+   * pin map. For unknown/custom board types the default is empty.
+   */
+  interruptPins?: number[];
+  /** RX buffer size for UART simulation (default: 256) */
+  uartRxBufferSize?: number;
+  /** TX buffer size for UART simulation (default: 256) */
+  uartTxBufferSize?: number;
+}