@typecad/simulator 0.1.0-alpha.1

package/dist/gpio/digital-pin-sim.js

@@ -0,0 +1,172 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — Simulated digital pin
+// ---------------------------------------------------------------------------
+import { PinMode } from '@typecad/hal';
+/**
+ * Convert a DigitalValue to a plain 0/1 number.
+ */
+function toBitValue(value) {
+    return value ? 1 : 0;
+}
+/**
+ * Simulated digital pin that tracks state transitions.
+ */
+/** Default capability flags for a digital pin. */
+const DEFAULT_DIGITAL_CAPS = {
+    digitalInput: true,
+    digitalOutput: true,
+    analogInput: false,
+    analogOutput: false,
+    pwm: false,
+    interrupt: false,
+    pullUp: true,
+    pullDown: false,
+    touch: false,
+    openDrain: false,
+};
+export class SimDigitalPin {
+    constructor(pinNum, caps) {
+        this._value = 0;
+        this._pinMode = PinMode.OUTPUT;
+        this._history = [];
+        this._startTime = Date.now();
+        this.number = pinNum;
+        this.gpio = pinNum;
+        this.capabilities = { ...DEFAULT_DIGITAL_CAPS, ...caps };
+    }
+    // --- BasePin ---
+    getMode() {
+        return this._pinMode;
+    }
+    setMode(mode) {
+        this._pinMode = mode;
+    }
+    has(capability) {
+        return this.capabilities[capability];
+    }
+    // --- Pin configuration ---
+    inputPullUp() {
+        this._pinMode = PinMode.INPUT_PULLUP;
+        this._setBitValue(1);
+    }
+    inputPullDown() {
+        this._pinMode = PinMode.INPUT_PULLDOWN;
+        this._setBitValue(0);
+    }
+    outputOpenDrain(initial) {
+        this._pinMode = PinMode.OUTPUT_OPEN_DRAIN;
+        if (initial !== undefined) {
+            this._setBitValue(toBitValue(initial));
+        }
+    }
+    // --- Fluent mode conversion ---
+    asOutput(initial) {
+        this._pinMode = PinMode.OUTPUT;
+        if (initial !== undefined) {
+            this._setBitValue(toBitValue(initial));
+        }
+        return this;
+    }
+    asInput() {
+        this._pinMode = PinMode.INPUT;
+        return this;
+    }
+    asInputPullUp() {
+        this.inputPullUp();
+        return this;
+    }
+    // --- IDigitalInput ---
+    read() {
+        return this._value === 1;
+    }
+    isHigh() {
+        return this._value === 1;
+    }
+    isLow() {
+        return this._value === 0;
+    }
+    async waitForRising(_timeout) {
+        // In simulation, this resolves immediately.
+        // Tests should use injectValue() + explicit assertions instead.
+    }
+    async waitForFalling(_timeout) {
+        // In simulation, this resolves immediately.
+    }
+    // --- IDigitalOutput ---
+    write(value) {
+        this._setBitValue(toBitValue(value));
+    }
+    high() {
+        this._setBitValue(1);
+    }
+    low() {
+        this._setBitValue(0);
+    }
+    toggle() {
+        this._setBitValue(this._value === 1 ? 0 : 1);
+    }
+    pulse(_duration) {
+        // In simulation the pulse duration is not awaited, so a pulse produces no
+        // observable transition — leave both pin state and history unchanged.
+    }
+    tone(_frequency) {
+        return {
+            for(_duration) {
+                // No-op in simulation
+            },
+        };
+    }
+    noTone() {
+        // No-op in simulation
+    }
+    stop() {
+        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) {
+        this._setBitValue(value & 1);
+    }
+    /**
+     * Get the history of all state changes on this pin.
+     */
+    getHistory() {
+        return this._history;
+    }
+    /**
+     * Clear the state change history.
+     */
+    clearHistory() {
+        this._history = [];
+    }
+    /**
+     * Get the current value as a plain number (0 or 1).
+     */
+    getBitValue() {
+        return this._value;
+    }
+    /**
+     * Reset the pin to its initial state.
+     */
+    reset() {
+        this._value = 0;
+        this._pinMode = PinMode.OUTPUT;
+        this._history = [];
+        this._startTime = Date.now();
+    }
+    // --- Internal ---
+    _setBitValue(newValue) {
+        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,
+            });
+        }
+    }
+}

package/dist/gpio/interrupt-sim.d.ts

@@ -0,0 +1,69 @@
+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 declare class SimInterruptPin extends SimDigitalPin implements InterruptPin {
+    private _handlers;
+    private _debounceMs;
+    private _events;
+    constructor(pinNum: number);
+    onRising(handler: InterruptHandler, options?: InterruptOptions): void;
+    onFalling(handler: InterruptHandler, options?: InterruptOptions): void;
+    onChange(handler: InterruptHandler, options?: InterruptOptions): void;
+    offInterrupts(): void;
+    /** Remove the rising-edge handler. */
+    offRising(): void;
+    /** Remove the falling-edge handler. */
+    offFalling(): void;
+    /** Remove all interrupt handlers. */
+    offAll(): void;
+    /** Check if any interrupt handlers are registered. */
+    hasInterrupt(): boolean;
+    /**
+     * 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): void;
+    /**
+     * 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;
+    /**
+     * Get all recorded interrupt events.
+     */
+    getEvents(): readonly InterruptEvent[];
+    /**
+     * Clear interrupt event history.
+     */
+    clearEvents(): void;
+    /**
+     * Get the configured debounce time.
+     */
+    getDebounceMs(): number;
+    /**
+     * Reset to initial state.
+     */
+    reset(): void;
+}
+export {};

package/dist/gpio/interrupt-sim.js

@@ -0,0 +1,118 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — Interrupt simulation
+// ---------------------------------------------------------------------------
+import { SimDigitalPin } from './digital-pin-sim.js';
+/**
+ * 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 {
+    constructor(pinNum) {
+        super(pinNum, { interrupt: true });
+        this._handlers = new Map();
+        this._debounceMs = 0;
+        this._events = [];
+    }
+    // --- InterruptPin capability methods ---
+    onRising(handler, options) {
+        this._handlers.set('rising', handler);
+        if (options?.debounce)
+            this._debounceMs = options.debounce;
+    }
+    onFalling(handler, options) {
+        this._handlers.set('falling', handler);
+        if (options?.debounce)
+            this._debounceMs = options.debounce;
+    }
+    onChange(handler, options) {
+        this._handlers.set('change', handler);
+        if (options?.debounce)
+            this._debounceMs = options.debounce;
+    }
+    offInterrupts() {
+        this._handlers.clear();
+    }
+    /** Remove the rising-edge handler. */
+    offRising() {
+        this._handlers.delete('rising');
+    }
+    /** Remove the falling-edge handler. */
+    offFalling() {
+        this._handlers.delete('falling');
+    }
+    /** Remove all interrupt handlers. */
+    offAll() {
+        this._handlers.clear();
+    }
+    /** Check if any interrupt handlers are registered. */
+    hasInterrupt() {
+        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, pinValue = 0) {
+        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, to) {
+        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() {
+        return this._events;
+    }
+    /**
+     * Clear interrupt event history.
+     */
+    clearEvents() {
+        this._events = [];
+    }
+    /**
+     * Get the configured debounce time.
+     */
+    getDebounceMs() {
+        return this._debounceMs;
+    }
+    /**
+     * Reset to initial state.
+     */
+    reset() {
+        super.reset();
+        this._handlers.clear();
+        this._debounceMs = 0;
+        this._events = [];
+        this._startTime = Date.now();
+    }
+}

package/dist/gpio/pwm-pin-sim.d.ts

@@ -0,0 +1,41 @@
+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 declare class SimPWMPin extends SimDigitalPin implements PWMPin {
+    private _pwmPercent;
+    private _pwmFrequency;
+    private _pwmResolution;
+    private _attached;
+    constructor(pinNum: number);
+    write(value: DigitalValue | AnalogValue): void;
+    pwm(percent?: number): void;
+    setFrequency(hz: number): void;
+    /** Current PWM frequency in Hz (contract method name). */
+    getPwmFrequency(): number;
+    /** Current PWM resolution in bits (contract method name). */
+    getPwmResolution(): number;
+    /** @deprecated Use getPwmFrequency() to match the HAL contract. */
+    getFrequency(): number;
+    /** @deprecated Use getPwmResolution() to match the HAL contract. */
+    getResolution(): number;
+    /**
+     * Get the current PWM duty cycle as a percentage (0-100).
+     */
+    getPwmPercent(): number;
+    /**
+     * Get the current PWM duty cycle as a raw value (0 to 2^resolution - 1).
+     */
+    getPwmValue(): number;
+    /**
+     * Check if PWM is currently active.
+     */
+    isPwmActive(): boolean;
+    /**
+     * Set the PWM resolution in bits.
+     */
+    setResolution(bits: number): void;
+    reset(): void;
+}

package/dist/gpio/pwm-pin-sim.js

@@ -0,0 +1,85 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — Simulated PWM pin
+// ---------------------------------------------------------------------------
+import { SimDigitalPin } from './digital-pin-sim.js';
+/**
+ * Simulated PWM pin. Extends digital pin with PWM duty cycle control.
+ */
+export class SimPWMPin extends SimDigitalPin {
+    constructor(pinNum) {
+        super(pinNum);
+        this._pwmPercent = 0;
+        this._pwmFrequency = 490; // Default Arduino PWM frequency
+        this._pwmResolution = 8; // Default 8-bit
+        this._attached = false;
+    }
+    // --- PWMPin ---
+    write(value) {
+        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);
+        }
+    }
+    pwm(percent) {
+        // 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) {
+        this._pwmFrequency = hz;
+    }
+    /** Current PWM frequency in Hz (contract method name). */
+    getPwmFrequency() {
+        return this._pwmFrequency;
+    }
+    /** Current PWM resolution in bits (contract method name). */
+    getPwmResolution() {
+        return this._pwmResolution;
+    }
+    /** @deprecated Use getPwmFrequency() to match the HAL contract. */
+    getFrequency() {
+        return this.getPwmFrequency();
+    }
+    /** @deprecated Use getPwmResolution() to match the HAL contract. */
+    getResolution() {
+        return this.getPwmResolution();
+    }
+    // --- Simulation helpers ---
+    /**
+     * Get the current PWM duty cycle as a percentage (0-100).
+     */
+    getPwmPercent() {
+        return this._pwmPercent;
+    }
+    /**
+     * Get the current PWM duty cycle as a raw value (0 to 2^resolution - 1).
+     */
+    getPwmValue() {
+        return Math.round((this._pwmPercent / 100) * ((1 << this._pwmResolution) - 1));
+    }
+    /**
+     * Check if PWM is currently active.
+     */
+    isPwmActive() {
+        return this._attached;
+    }
+    /**
+     * Set the PWM resolution in bits.
+     */
+    setResolution(bits) {
+        this._pwmResolution = bits;
+    }
+    reset() {
+        super.reset();
+        this._pwmPercent = 0;
+        this._pwmFrequency = 490;
+        this._pwmResolution = 8;
+        this._attached = false;
+    }
+}

package/dist/helpers.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 declare function createByteReadResult(bytes: Uint8Array, ok?: boolean, status?: number, timedOut?: boolean): IByteReadResult;
+/**
+ * Create an IWriteResult with the given bytesWritten count.
+ */
+export declare function createWriteResult(bytesWritten: number, ok?: boolean, status?: number): IWriteResult;

package/dist/helpers.js

@@ -0,0 +1,57 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — Result factory helpers
+// ---------------------------------------------------------------------------
+/**
+ * Create an IByteReadResult with the given bytes.
+ */
+export function createByteReadResult(bytes, ok = true, status = 0, timedOut = false) {
+    return {
+        ok,
+        status,
+        bytes,
+        bytesRead: bytes.length,
+        timedOut,
+        asUint8() { return bytes[0] ?? 0; },
+        asInt8() { const v = bytes[0] ?? 0; return v > 127 ? v - 256 : v; },
+        asUint16(endian) {
+            if (bytes.length < 2)
+                return 0;
+            return endian === 'be'
+                ? ((bytes[0] << 8) | bytes[1]) >>> 0
+                : ((bytes[1] << 8) | bytes[0]) >>> 0;
+        },
+        asInt16(endian) {
+            const v = this.asUint16(endian);
+            return v > 32767 ? v - 65536 : v;
+        },
+        asUint32(endian) {
+            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) {
+            const v = this.asUint32(endian);
+            return v > 2147483647 ? v - 4294967296 : v;
+        },
+        asString() { return new TextDecoder().decode(bytes); },
+        asStringTrim() { return this.asString().trim(); },
+        asInt() { return parseInt(this.asString(), 10) || 0; },
+        asFloat() { return parseFloat(this.asString()) || 0; },
+        unwrap() { return bytes; },
+        unwrapOr(defaultValue) { return ok ? bytes : defaultValue; },
+    };
+}
+/**
+ * Create an IWriteResult with the given bytesWritten count.
+ */
+export function createWriteResult(bytesWritten, ok = true, status = 0) {
+    return {
+        ok,
+        status,
+        bytesWritten,
+        unwrap() { return bytesWritten; },
+        unwrapOr(defaultValue) { return ok ? bytesWritten : defaultValue; },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+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';
+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';
+export { SimBoard, createSimBoard } from './board/board-sim.js';
+export { createBoardFromDefinition } from './board/from-definition.js';
+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';
+export { PinMode } from '@typecad/hal';
+export type { PinChangeCallback, InterruptCallback, ISimI2CDevice, ISimSPIDevice, SimBoardType, SimBoardConfig, } from './types.js';
+export { createByteReadResult, createWriteResult } from './helpers.js';

package/dist/index.js

@@ -0,0 +1,21 @@
+// ---------------------------------------------------------------------------
+// @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';
+// --- Bus simulation ---
+export { SimSerialPort } from './bus/serial-sim.js';
+export { SimI2CBus } from './bus/i2c-sim.js';
+export { SimSPIBus } from './bus/spi-sim.js';
+// --- Board factory ---
+export { SimBoard, createSimBoard } from './board/board-sim.js';
+export { createBoardFromDefinition } from './board/from-definition.js';
+export { I2CStatus, SPIStatus, UARTStatus } from './contracts.js';
+export { hasPWM, hasAnalogInput, hasInterrupt, assertPWM, assertAnalog, assertInterrupt } from './contracts.js';
+// --- Types ---
+export { PinMode } from '@typecad/hal';
+// --- Helpers ---
+export { createByteReadResult, createWriteResult } from './helpers.js';