@typecad/simulator 0.1.0-alpha.1

package/src/bus/serial-sim.ts

@@ -0,0 +1,280 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — Serial port simulation
+// ---------------------------------------------------------------------------
+
+import { UARTStatus } from '../contracts.js';
+import type {
+  ISerialPort,
+  UARTStatusInfo,
+  ErrorPolicy,
+} from '../contracts.js';
+
+// ---------------------------------------------------------------------------
+// SimSerialPort
+// ---------------------------------------------------------------------------
+
+/**
+ * Simulated serial port for testing UART communication.
+ *
+ * Tests can inject bytes into the RX buffer and inspect the TX buffer
+ * to verify that sketch code sends the expected data.
+ */
+export class SimSerialPort implements ISerialPort {
+  readonly uartNumber: number;
+  baudRate: number = 0;
+  isEnabled: boolean = false;
+  errorPolicy: ErrorPolicy = 'callback';
+
+  private _rxBuffer: number[] = [];
+  private _txBuffer: number[] = [];
+  private _rxBufferSize: number;
+  private _txBufferSize: number;
+  private _overrunError: boolean = false;
+  private _parityError: boolean = false;
+  private _framingError: boolean = false;
+  private _breakDetected: boolean = false;
+
+  private _onReceiveCallback: ((bytesAvailable: number) => void) | null = null;
+  private _onTransmitCompleteCallback: (() => void) | null = null;
+  private _onErrorCallback: ((status: UARTStatus) => void) | null = null;
+
+  constructor(uartNumber: number = 0, rxBufferSize: number = 256, txBufferSize: number = 256) {
+    this.uartNumber = uartNumber;
+    this._rxBufferSize = rxBufferSize;
+    this._txBufferSize = txBufferSize;
+  }
+
+  // --- IUARTBus methods ---
+
+  begin(baud: number): void {
+    this.baudRate = baud;
+    this.isEnabled = true;
+  }
+
+  end(): void {
+    // In simulation, ending the port disables it without destroying buffers.
+    this.isEnabled = false;
+  }
+
+  read(): number {
+    if (this._rxBuffer.length === 0) return -1;
+    return this._rxBuffer.shift()!;
+  }
+
+  peek(): number {
+    if (this._rxBuffer.length === 0) return -1;
+    return this._rxBuffer[0];
+  }
+
+  readLine(): string {
+    const idx = this._rxBuffer.findIndex(b => b === 0x0A);
+    if (idx === -1) return '';
+    const lineBytes = this._rxBuffer.splice(0, idx + 1);
+    return new TextDecoder().decode(new Uint8Array(lineBytes)).trimEnd();
+  }
+
+  readBytes(count: number): Uint8Array {
+    if (this._rxBuffer.length < count) {
+      const available = this._rxBuffer.splice(0, this._rxBuffer.length);
+      return new Uint8Array(available);
+    }
+    const result = this._rxBuffer.splice(0, count);
+    return new Uint8Array(result);
+  }
+
+  readString(): string {
+    const result = new Uint8Array(this._rxBuffer);
+    this._rxBuffer = [];
+    return new TextDecoder().decode(result);
+  }
+
+  available(): number {
+    return this._rxBuffer.length;
+  }
+
+  write(data: number | Uint8Array | string): number {
+    const bytes = typeof data === 'number'
+      ? [data & 0xFF]
+      : typeof data === 'string'
+        ? this._encodeString(data)
+        : Array.from(data);
+    return this._pushTxBytes(bytes);
+  }
+
+  flush(): void {
+    // In simulation, data is "sent" immediately when written to TX buffer.
+    // Flush triggers the transmit complete callback.
+    if (this._onTransmitCompleteCallback) {
+      this._onTransmitCompleteCallback();
+    }
+  }
+
+  getStatus(): UARTStatusInfo {
+    return {
+      available: this._rxBuffer.length,
+      writeAvailable: this._txBufferSize - this._txBuffer.length,
+      overrunError: this._overrunError,
+      parityError: this._parityError,
+      framingError: this._framingError,
+      breakDetected: this._breakDetected,
+    };
+  }
+
+  clearErrors(): void {
+    this._overrunError = false;
+    this._parityError = false;
+    this._framingError = false;
+    this._breakDetected = false;
+  }
+
+  onReceive(callback: (bytesAvailable: number) => void): void {
+    this._onReceiveCallback = callback;
+  }
+
+  onTransmitComplete(callback: () => void): void {
+    this._onTransmitCompleteCallback = callback;
+  }
+
+  onError(callback: (status: UARTStatus) => void): void {
+    this._onErrorCallback = callback;
+  }
+
+  // --- ISerialPort methods ---
+
+  print(...args: unknown[]): void {
+    const text = args.map(a => String(a)).join('');
+    this.write(text);
+  }
+
+  println(...args: unknown[]): void {
+    const text = args.map(a => String(a)).join('');
+    this.write(text + '\r\n');
+  }
+
+  printf(format: string, ...args: unknown[]): void {
+    const text = this._formatString(format, args);
+    this.write(text);
+  }
+
+  isConnected(): boolean {
+    return this.isEnabled;
+  }
+
+  async waitForConnection(_timeout?: number): Promise<void> {
+    // In simulation, just resolve immediately
+  }
+
+  // --- Simulation helpers ---
+
+  /**
+   * Inject bytes into the RX buffer (simulating received data).
+   * Triggers onReceive callback if registered.
+   */
+  injectRx(data: Uint8Array | number[] | string): void {
+    const bytes = typeof data === 'string'
+      ? this._encodeString(data)
+      : Array.isArray(data)
+        ? data
+        : Array.from(data);
+
+    for (const b of bytes) {
+      if (this._rxBuffer.length >= this._rxBufferSize) {
+        this._overrunError = true;
+        break;
+      }
+      this._rxBuffer.push(b & 0xFF);
+    }
+
+    if (this._onReceiveCallback) {
+      this._onReceiveCallback(this._rxBuffer.length);
+    }
+  }
+
+  /**
+   * Get all bytes written to the TX buffer since the last call.
+   * Clears the TX buffer.
+   */
+  flushTx(): number[] {
+    const result = this._txBuffer.slice();
+    this._txBuffer = [];
+    if (this._onTransmitCompleteCallback) {
+      this._onTransmitCompleteCallback();
+    }
+    return result;
+  }
+
+  /**
+   * Get the TX buffer contents without clearing.
+   */
+  peekTx(): readonly number[] {
+    return this._txBuffer;
+  }
+
+  /**
+   * Get the TX buffer contents as a string.
+   */
+  peekTxAsString(): string {
+    return new TextDecoder().decode(new Uint8Array(this._txBuffer));
+  }
+
+  /**
+   * Reset all buffers and state.
+   */
+  reset(): void {
+    this._rxBuffer = [];
+    this._txBuffer = [];
+    this._overrunError = false;
+    this._parityError = false;
+    this._framingError = false;
+    this._breakDetected = false;
+    this.isEnabled = false;
+    this.baudRate = 0;
+  }
+
+  // --- Private helpers ---
+
+  private _pushTxBytes(bytes: number[]): number {
+    let written = 0;
+    for (const b of bytes) {
+      if (this._txBuffer.length >= this._txBufferSize) break;
+      this._txBuffer.push(b & 0xFF);
+      written++;
+    }
+    return written;
+  }
+
+  private _encodeString(text: string): number[] {
+    return Array.from(new TextEncoder().encode(text));
+  }
+
+  private _formatString(fmt: string, args: unknown[]): string {
+    let result = '';
+    let argIdx = 0;
+    for (let i = 0; i < fmt.length; i++) {
+      if (fmt[i] === '{' && fmt[i + 1] === '}') {
+        result += String(args[argIdx++] ?? '');
+        i++;
+      } else if (fmt[i] === '%' && i + 1 < fmt.length) {
+        const spec = fmt[i + 1];
+        if (spec === 'd' || spec === 'i') {
+          result += String(Number(args[argIdx++]) || 0);
+          i++;
+        } else if (spec === 's') {
+          result += String(args[argIdx++] ?? '');
+          i++;
+        } else if (spec === 'f') {
+          result += String(Number(args[argIdx++]) || 0.0);
+          i++;
+        } else if (spec === '%') {
+          result += '%';
+          i++;
+        } else {
+          result += fmt[i];
+        }
+      } else {
+        result += fmt[i];
+      }
+    }
+    return result;
+  }
+}

package/src/bus/spi-sim.ts

@@ -0,0 +1,269 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — SPI bus simulation
+// ---------------------------------------------------------------------------
+
+import { SPIStatus } from '../contracts.js';
+import type {
+  ISPIBus,
+  ISPIDevice,
+  BasePin,
+  ErrorPolicy,
+} from '../contracts.js';
+import type { SPIMode, SPIBitOrder, SPISettings } from '@typecad/hal';
+import type { ISimSPIDevice } from '../types.js';
+
+// ---------------------------------------------------------------------------
+// SimSPIBus
+// ---------------------------------------------------------------------------
+
+/**
+ * Simulated SPI bus for testing SPI communication.
+ *
+ * Tests register mock devices via `attachDevice()`. When sketch code performs
+ * transfers, the corresponding mock device handles the operation.
+ */
+export class SimSPIBus implements ISPIBus {
+  isEnabled: boolean = false;
+  errorPolicy: ErrorPolicy = 'callback';
+
+  private _frequency: number = 4000000;
+  private _mode: SPIMode = 0;
+  private _bitOrder: SPIBitOrder = 'msb';
+  private _devices: Map<string, ISimSPIDevice> = new Map();
+  private _inTransaction: boolean = false;
+
+  /** Track all operations for test assertions. */
+  private _log: SPIOperationLog[] = [];
+
+  // --- ISPIBus methods ---
+
+  begin(): void {
+    this.isEnabled = true;
+  }
+
+  end(): void {
+    // In simulation, ending the bus disables it without releasing mock devices.
+    this.isEnabled = false;
+  }
+
+  setMode(mode: SPIMode): void {
+    this._mode = mode;
+  }
+
+  setBitOrder(order: SPIBitOrder): void {
+    this._bitOrder = order;
+  }
+
+  setFrequency(hz: number): void {
+    this._frequency = hz;
+  }
+
+  beginTransaction(_settings: SPISettings): void {
+    this._inTransaction = true;
+  }
+
+  endTransaction(): void {
+    this._inTransaction = false;
+  }
+
+  transfer(data: number | Uint8Array): Uint8Array {
+    const mosiData = typeof data === 'number' ? [data] : Array.from(data);
+    const timestamp = Date.now();
+
+    // Bus-level transfer (no CS pin) — log but no device interaction
+    this._log.push({ operation: 'transfer', data: mosiData, timestamp });
+    return new Uint8Array(mosiData.length);
+  }
+
+  write(data: number | Uint8Array): void {
+    const mosiData = typeof data === 'number' ? [data] : Array.from(data);
+    const timestamp = Date.now();
+    this._log.push({ operation: 'write', data: mosiData, timestamp });
+  }
+
+  write16(value: number): void {
+    const msb = (value >> 8) & 0xFF;
+    const lsb = value & 0xFF;
+    this.write(new Uint8Array([msb, lsb]));
+  }
+
+  device(chipSelect: BasePin): ISPIDevice {
+    return new SimSPIDevice(this, chipSelect);
+  }
+
+  // --- Simulation helpers ---
+
+  /**
+   * Attach a mock SPI device for the given chip-select pin.
+   */
+  attachDevice(csPin: BasePin, device: ISimSPIDevice): void {
+    this._devices.set(String(csPin.number), device);
+  }
+
+  /**
+   * Remove a mock device.
+   */
+  detachDevice(csPin: BasePin): void {
+    this._devices.delete(String(csPin.number));
+  }
+
+  /**
+   * Get the operation log for test assertions.
+   */
+  getLog(): readonly SPIOperationLog[] {
+    return this._log;
+  }
+
+  /**
+   * Clear the operation log.
+   */
+  clearLog(): void {
+    this._log = [];
+  }
+
+  onError(_handler: (status: SPIStatus, operation: 'transfer' | 'read' | 'write') => void): void {
+    // No-op in simulator
+  }
+
+  /**
+   * Reset all state.
+   */
+  reset(): void {
+    this._devices.clear();
+    this._log = [];
+    this.isEnabled = false;
+    this._inTransaction = false;
+    this._frequency = 4000000;
+    this._mode = 0;
+    this._bitOrder = 'msb';
+  }
+
+  // --- Internal ---
+
+  /** @internal */
+  _getDevice(csKey: string): ISimSPIDevice | undefined {
+    return this._devices.get(csKey);
+  }
+
+  /** @internal */
+  _logOperation(op: SPIOperationLog): void {
+    this._log.push(op);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// SimSPIDevice — implements ISPIDevice
+// ---------------------------------------------------------------------------
+
+class SimSPIDevice implements ISPIDevice {
+  readonly bus: ISPIBus;
+  readonly chipSelect: BasePin;
+  private readonly _simBus: SimSPIBus;
+
+  constructor(bus: SimSPIBus, chipSelect: BasePin) {
+    this.bus = bus;
+    this._simBus = bus;
+    this.chipSelect = chipSelect;
+  }
+
+  transfer(data: number | Uint8Array): Uint8Array {
+    const csKey = String(this.chipSelect.number);
+    const mosiData = typeof data === 'number' ? [data] : Array.from(data);
+    const timestamp = Date.now();
+    const device = this._simBus._getDevice(csKey);
+
+    if (!device) {
+      this._simBus._logOperation({ operation: 'transfer', data: mosiData, timestamp });
+      return new Uint8Array(0);
+    }
+
+    const misoData = device.transfer(mosiData);
+    this._simBus._logOperation({ operation: 'transfer', data: mosiData, response: misoData, timestamp });
+    return new Uint8Array(misoData);
+  }
+
+  write(data: number | Uint8Array): void {
+    const csKey = String(this.chipSelect.number);
+    const dataArray = typeof data === 'number' ? [data] : Array.from(data);
+    const timestamp = Date.now();
+    const device = this._simBus._getDevice(csKey);
+
+    if (!device) {
+      this._simBus._logOperation({ operation: 'write', data: dataArray, timestamp });
+      return;
+    }
+
+    if (device.write) {
+      // Write without register — use register 0 as placeholder
+      device.write(0, dataArray);
+    } else {
+      device.transfer(dataArray);
+    }
+    this._simBus._logOperation({ operation: 'write', data: dataArray, timestamp });
+  }
+
+  read(count: number): Uint8Array {
+    const csKey = String(this.chipSelect.number);
+    const timestamp = Date.now();
+    const device = this._simBus._getDevice(csKey);
+
+    if (!device) {
+      this._simBus._logOperation({ operation: 'read', count, timestamp });
+      return new Uint8Array(0);
+    }
+
+    // Send dummy bytes to read
+    const misoData = device.transfer(new Array(count).fill(0));
+    this._simBus._logOperation({ operation: 'read', count, data: misoData, timestamp });
+    return new Uint8Array(misoData);
+  }
+
+  writeRegister(register: number, data: number | Uint8Array): void {
+    const csKey = String(this.chipSelect.number);
+    const dataArray = typeof data === 'number' ? [data] : Array.from(data);
+    const timestamp = Date.now();
+    const device = this._simBus._getDevice(csKey);
+
+    if (!device) {
+      this._simBus._logOperation({ operation: 'write', register, data: dataArray, timestamp });
+      return;
+    }
+
+    if (device.write) {
+      device.write(register, dataArray);
+    } else {
+      device.transfer([register, ...dataArray]);
+    }
+    this._simBus._logOperation({ operation: 'write', register, data: dataArray, timestamp });
+  }
+
+  readRegister(register: number, count: number): Uint8Array {
+    const csKey = String(this.chipSelect.number);
+    const timestamp = Date.now();
+    const device = this._simBus._getDevice(csKey);
+
+    if (!device) {
+      this._simBus._logOperation({ operation: 'read', register, count, timestamp });
+      return new Uint8Array(0);
+    }
+
+    const data = device.readRegister
+      ? device.readRegister(register, count)
+      : device.transfer([register, ...new Array(count).fill(0)]).slice(1);
+    this._simBus._logOperation({ operation: 'read', register, count, data, timestamp });
+    return new Uint8Array(data);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Operation log
+// ---------------------------------------------------------------------------
+
+export interface SPIOperationLog {
+  operation: 'read' | 'write' | 'transfer';
+  register?: number;
+  count?: number;
+  data?: number[];
+  response?: number[];
+  timestamp: number;
+}