@typecad/simulator 0.1.0-alpha.1

package/dist/bus/i2c-sim.js

@@ -0,0 +1,155 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — I2C bus simulation
+// ---------------------------------------------------------------------------
+import { I2CStatus } from '../contracts.js';
+// ---------------------------------------------------------------------------
+// SimI2CBus
+// ---------------------------------------------------------------------------
+/**
+ * Simulated I2C bus for testing I2C communication.
+ *
+ * Tests register mock devices via `attachDevice()`. When sketch code reads
+ * or writes to an address, the corresponding mock device handles the operation.
+ */
+export class SimI2CBus {
+    constructor(busNumber = 0) {
+        this.isEnabled = false;
+        this.errorPolicy = 'callback';
+        this._devices = new Map();
+        this._speed = 100000;
+        this._slaveAddress = null;
+        this._errorHandler = null;
+        /** Track all operations for test assertions. */
+        this._log = [];
+        this.busNumber = busNumber;
+    }
+    // --- II2CBus methods ---
+    begin(address) {
+        if (address !== undefined) {
+            this._slaveAddress = address;
+        }
+        this.isEnabled = true;
+    }
+    end() {
+        // In simulation, ending the bus disables it without releasing mock devices.
+        this.isEnabled = false;
+    }
+    setClock(hz) {
+        this._speed = hz;
+    }
+    device(address) {
+        return createDeviceAccessor(this, address);
+    }
+    onError(handler) {
+        this._errorHandler = handler;
+    }
+    recover() {
+        return true;
+    }
+    // --- Simulation helpers ---
+    /**
+     * Attach a mock I2C device at the given address.
+     */
+    attachDevice(address, device) {
+        this._devices.set(address, device);
+    }
+    /**
+     * Remove a mock device.
+     */
+    detachDevice(address) {
+        this._devices.delete(address);
+    }
+    /**
+     * Get the operation log for test assertions.
+     */
+    getLog() {
+        return this._log;
+    }
+    /**
+     * Clear the operation log.
+     */
+    clearLog() {
+        this._log = [];
+    }
+    /**
+     * Reset all state.
+     */
+    reset() {
+        this._devices.clear();
+        this._log = [];
+        this._errorHandler = null;
+        this.isEnabled = false;
+        this._speed = 100000;
+        this._slaveAddress = null;
+    }
+    // --- Internal ---
+    /** @internal */
+    _getDevice(address) {
+        return this._devices.get(address);
+    }
+    /** @internal */
+    _logOperation(op) {
+        this._log.push(op);
+    }
+    /** @internal */
+    _fireError(status, address, operation) {
+        if (this._errorHandler) {
+            this._errorHandler(status, address, operation);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Device accessor factory
+// ---------------------------------------------------------------------------
+function createDeviceAccessor(bus, address) {
+    return {
+        address,
+        readByte(register) {
+            const device = bus._getDevice(address);
+            const timestamp = Date.now();
+            if (!device) {
+                bus._logOperation({ operation: 'read', address, register, timestamp });
+                bus._fireError(I2CStatus.NACK_ON_ADDRESS, address, 'read');
+                return 0;
+            }
+            const data = device.read(register, 1);
+            bus._logOperation({ operation: 'read', address, register, data, timestamp });
+            return data[0] ?? 0;
+        },
+        readBytes(register, count) {
+            const device = bus._getDevice(address);
+            const timestamp = Date.now();
+            if (!device) {
+                bus._logOperation({ operation: 'read', address, register, timestamp });
+                bus._fireError(I2CStatus.NACK_ON_ADDRESS, address, 'read');
+                return new Uint8Array(0);
+            }
+            const data = device.read(register, count);
+            bus._logOperation({ operation: 'read', address, register, data, timestamp });
+            return new Uint8Array(data);
+        },
+        writeByte(register, value) {
+            const device = bus._getDevice(address);
+            const timestamp = Date.now();
+            if (!device) {
+                bus._logOperation({ operation: 'write', address, register, data: [value], timestamp });
+                bus._fireError(I2CStatus.NACK_ON_ADDRESS, address, 'write');
+                return;
+            }
+            device.write(register, [value]);
+            bus._logOperation({ operation: 'write', address, register, data: [value], timestamp });
+        },
+        writeBytes(register, data) {
+            const device = bus._getDevice(address);
+            const dataArray = Array.isArray(data) ? data : Array.from(data);
+            const timestamp = Date.now();
+            if (!device) {
+                bus._logOperation({ operation: 'write', address, register, data: dataArray, timestamp });
+                bus._fireError(I2CStatus.NACK_ON_ADDRESS, address, 'write');
+                return;
+            }
+            device.write(register, dataArray);
+            bus._logOperation({ operation: 'write', address, register, data: dataArray, timestamp });
+        },
+    };
+}

package/dist/bus/serial-sim.d.ts

@@ -0,0 +1,71 @@
+import { UARTStatus } from '../contracts.js';
+import type { ISerialPort, UARTStatusInfo, ErrorPolicy } from '../contracts.js';
+/**
+ * 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 declare class SimSerialPort implements ISerialPort {
+    readonly uartNumber: number;
+    baudRate: number;
+    isEnabled: boolean;
+    errorPolicy: ErrorPolicy;
+    private _rxBuffer;
+    private _txBuffer;
+    private _rxBufferSize;
+    private _txBufferSize;
+    private _overrunError;
+    private _parityError;
+    private _framingError;
+    private _breakDetected;
+    private _onReceiveCallback;
+    private _onTransmitCompleteCallback;
+    private _onErrorCallback;
+    constructor(uartNumber?: number, rxBufferSize?: number, txBufferSize?: number);
+    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;
+    print(...args: unknown[]): void;
+    println(...args: unknown[]): void;
+    printf(format: string, ...args: unknown[]): void;
+    isConnected(): boolean;
+    waitForConnection(_timeout?: number): Promise<void>;
+    /**
+     * Inject bytes into the RX buffer (simulating received data).
+     * Triggers onReceive callback if registered.
+     */
+    injectRx(data: Uint8Array | number[] | string): void;
+    /**
+     * Get all bytes written to the TX buffer since the last call.
+     * Clears the TX buffer.
+     */
+    flushTx(): number[];
+    /**
+     * Get the TX buffer contents without clearing.
+     */
+    peekTx(): readonly number[];
+    /**
+     * Get the TX buffer contents as a string.
+     */
+    peekTxAsString(): string;
+    /**
+     * Reset all buffers and state.
+     */
+    reset(): void;
+    private _pushTxBytes;
+    private _encodeString;
+    private _formatString;
+}

package/dist/bus/serial-sim.js

@@ -0,0 +1,241 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — Serial port simulation
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// 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 {
+    constructor(uartNumber = 0, rxBufferSize = 256, txBufferSize = 256) {
+        this.baudRate = 0;
+        this.isEnabled = false;
+        this.errorPolicy = 'callback';
+        this._rxBuffer = [];
+        this._txBuffer = [];
+        this._overrunError = false;
+        this._parityError = false;
+        this._framingError = false;
+        this._breakDetected = false;
+        this._onReceiveCallback = null;
+        this._onTransmitCompleteCallback = null;
+        this._onErrorCallback = null;
+        this.uartNumber = uartNumber;
+        this._rxBufferSize = rxBufferSize;
+        this._txBufferSize = txBufferSize;
+    }
+    // --- IUARTBus methods ---
+    begin(baud) {
+        this.baudRate = baud;
+        this.isEnabled = true;
+    }
+    end() {
+        // In simulation, ending the port disables it without destroying buffers.
+        this.isEnabled = false;
+    }
+    read() {
+        if (this._rxBuffer.length === 0)
+            return -1;
+        return this._rxBuffer.shift();
+    }
+    peek() {
+        if (this._rxBuffer.length === 0)
+            return -1;
+        return this._rxBuffer[0];
+    }
+    readLine() {
+        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) {
+        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() {
+        const result = new Uint8Array(this._rxBuffer);
+        this._rxBuffer = [];
+        return new TextDecoder().decode(result);
+    }
+    available() {
+        return this._rxBuffer.length;
+    }
+    write(data) {
+        const bytes = typeof data === 'number'
+            ? [data & 0xFF]
+            : typeof data === 'string'
+                ? this._encodeString(data)
+                : Array.from(data);
+        return this._pushTxBytes(bytes);
+    }
+    flush() {
+        // In simulation, data is "sent" immediately when written to TX buffer.
+        // Flush triggers the transmit complete callback.
+        if (this._onTransmitCompleteCallback) {
+            this._onTransmitCompleteCallback();
+        }
+    }
+    getStatus() {
+        return {
+            available: this._rxBuffer.length,
+            writeAvailable: this._txBufferSize - this._txBuffer.length,
+            overrunError: this._overrunError,
+            parityError: this._parityError,
+            framingError: this._framingError,
+            breakDetected: this._breakDetected,
+        };
+    }
+    clearErrors() {
+        this._overrunError = false;
+        this._parityError = false;
+        this._framingError = false;
+        this._breakDetected = false;
+    }
+    onReceive(callback) {
+        this._onReceiveCallback = callback;
+    }
+    onTransmitComplete(callback) {
+        this._onTransmitCompleteCallback = callback;
+    }
+    onError(callback) {
+        this._onErrorCallback = callback;
+    }
+    // --- ISerialPort methods ---
+    print(...args) {
+        const text = args.map(a => String(a)).join('');
+        this.write(text);
+    }
+    println(...args) {
+        const text = args.map(a => String(a)).join('');
+        this.write(text + '\r\n');
+    }
+    printf(format, ...args) {
+        const text = this._formatString(format, args);
+        this.write(text);
+    }
+    isConnected() {
+        return this.isEnabled;
+    }
+    async waitForConnection(_timeout) {
+        // In simulation, just resolve immediately
+    }
+    // --- Simulation helpers ---
+    /**
+     * Inject bytes into the RX buffer (simulating received data).
+     * Triggers onReceive callback if registered.
+     */
+    injectRx(data) {
+        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() {
+        const result = this._txBuffer.slice();
+        this._txBuffer = [];
+        if (this._onTransmitCompleteCallback) {
+            this._onTransmitCompleteCallback();
+        }
+        return result;
+    }
+    /**
+     * Get the TX buffer contents without clearing.
+     */
+    peekTx() {
+        return this._txBuffer;
+    }
+    /**
+     * Get the TX buffer contents as a string.
+     */
+    peekTxAsString() {
+        return new TextDecoder().decode(new Uint8Array(this._txBuffer));
+    }
+    /**
+     * Reset all buffers and state.
+     */
+    reset() {
+        this._rxBuffer = [];
+        this._txBuffer = [];
+        this._overrunError = false;
+        this._parityError = false;
+        this._framingError = false;
+        this._breakDetected = false;
+        this.isEnabled = false;
+        this.baudRate = 0;
+    }
+    // --- Private helpers ---
+    _pushTxBytes(bytes) {
+        let written = 0;
+        for (const b of bytes) {
+            if (this._txBuffer.length >= this._txBufferSize)
+                break;
+            this._txBuffer.push(b & 0xFF);
+            written++;
+        }
+        return written;
+    }
+    _encodeString(text) {
+        return Array.from(new TextEncoder().encode(text));
+    }
+    _formatString(fmt, args) {
+        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/dist/bus/spi-sim.d.ts

@@ -0,0 +1,65 @@
+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';
+/**
+ * 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 declare class SimSPIBus implements ISPIBus {
+    isEnabled: boolean;
+    errorPolicy: ErrorPolicy;
+    private _frequency;
+    private _mode;
+    private _bitOrder;
+    private _devices;
+    private _inTransaction;
+    /** Track all operations for test assertions. */
+    private _log;
+    begin(): void;
+    end(): void;
+    setMode(mode: SPIMode): void;
+    setBitOrder(order: SPIBitOrder): void;
+    setFrequency(hz: number): void;
+    beginTransaction(_settings: SPISettings): void;
+    endTransaction(): void;
+    transfer(data: number | Uint8Array): Uint8Array;
+    write(data: number | Uint8Array): void;
+    write16(value: number): void;
+    device(chipSelect: BasePin): ISPIDevice;
+    /**
+     * Attach a mock SPI device for the given chip-select pin.
+     */
+    attachDevice(csPin: BasePin, device: ISimSPIDevice): void;
+    /**
+     * Remove a mock device.
+     */
+    detachDevice(csPin: BasePin): void;
+    /**
+     * Get the operation log for test assertions.
+     */
+    getLog(): readonly SPIOperationLog[];
+    /**
+     * Clear the operation log.
+     */
+    clearLog(): void;
+    onError(_handler: (status: SPIStatus, operation: 'transfer' | 'read' | 'write') => void): void;
+    /**
+     * Reset all state.
+     */
+    reset(): void;
+    /** @internal */
+    _getDevice(csKey: string): ISimSPIDevice | undefined;
+    /** @internal */
+    _logOperation(op: SPIOperationLog): void;
+}
+export interface SPIOperationLog {
+    operation: 'read' | 'write' | 'transfer';
+    register?: number;
+    count?: number;
+    data?: number[];
+    response?: number[];
+    timestamp: number;
+}