@typecad/simulator 0.1.0-alpha.1

package/dist/types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 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;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — Simulator-specific types
+// ---------------------------------------------------------------------------
+export {};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@typecad/simulator",
+  "version": "0.1.0-alpha.1",
+  "description": "Hardware simulation runtime for TypeCAD — test HAL code in Node.js without hardware",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@typecad/hal": "0.1.0-alpha.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "@types/node": "^22.10.7",
+    "@typecad/cuttlefish": "0.1.0-alpha.1"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/justind000/typecode.git",
+    "directory": "packages/simulator"
+  },
+  "homepage": "https://github.com/justind000/typecode/tree/main/packages/simulator",
+  "bugs": {
+    "url": "https://github.com/justind000/typecode/issues"
+  },
+  "keywords": [
+    "arduino",
+    "cpp",
+    "cuttlefish",
+    "desktop",
+    "embedded",
+    "emulator",
+    "firmware",
+    "microcontroller",
+    "simulator",
+    "typecad",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "typecad0",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  }
+}

package/src/board/board-sim.ts

@@ -0,0 +1,208 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — Simulated board factory
+// ---------------------------------------------------------------------------
+
+import type { SimBoardConfig } from '../types.js';
+import { SimDigitalPin } from '../gpio/digital-pin-sim.js';
+import { SimAnalogPin } from '../gpio/analog-pin-sim.js';
+import { SimPWMPin } from '../gpio/pwm-pin-sim.js';
+import { SimInterruptPin } from '../gpio/interrupt-sim.js';
+import { SimSerialPort } from '../bus/serial-sim.js';
+import { SimI2CBus } from '../bus/i2c-sim.js';
+import { SimSPIBus } from '../bus/spi-sim.js';
+
+// ---------------------------------------------------------------------------
+// SimBoard
+// ---------------------------------------------------------------------------
+
+/**
+ * A fully simulated board with GPIO pins and bus peripherals.
+ *
+ * Tests create a `SimBoard` via `createSimBoard()`, then access pins
+ * and buses to inject data and verify behavior.
+ */
+export class SimBoard {
+  readonly digitalPins: ReadonlyMap<number, SimDigitalPin>;
+  readonly analogPins: ReadonlyMap<number, SimAnalogPin>;
+  readonly pwmPins: ReadonlyMap<number, SimPWMPin>;
+  readonly interruptPins: ReadonlyMap<number, SimInterruptPin>;
+  readonly serialPorts: ReadonlyMap<number, SimSerialPort>;
+  readonly i2cBuses: ReadonlyMap<number, SimI2CBus>;
+  readonly spiBuses: ReadonlyMap<number, SimSPIBus>;
+
+  constructor(config: SimBoardConfig) {
+    const digitalCount = config.digitalPinCount ?? 14;
+    const analogCount = config.analogPinCount ?? 6;
+    const uartCount = config.uartCount ?? 1;
+    const i2cCount = config.i2cBusCount ?? 1;
+    const spiCount = config.spiBusCount ?? 1;
+
+    // Digital pins
+    const digitalMap = new Map<number, SimDigitalPin>();
+    for (let i = 0; i < digitalCount; i++) {
+      digitalMap.set(i, new SimDigitalPin(i));
+    }
+    this.digitalPins = digitalMap;
+
+    // Analog pins (A0, A1, ...)
+    const analogMap = new Map<number, SimAnalogPin>();
+    for (let i = 0; i < analogCount; i++) {
+      analogMap.set(i, new SimAnalogPin(i));
+    }
+    this.analogPins = analogMap;
+
+    // PWM pins (e.g. 3, 5, 6, 9, 10, 11 on Uno). Custom/unknown board types
+    // default to no PWM pins unless explicitly configured via `pwmPins`.
+    const pwmMap = new Map<number, SimPWMPin>();
+    const pwmPinNumbers = config.pwmPins ?? getPwmPinsForBoard(config.boardType);
+    for (const pinNum of pwmPinNumbers) {
+      if (pinNum < digitalCount) {
+        pwmMap.set(pinNum, new SimPWMPin(pinNum));
+      }
+    }
+    this.pwmPins = pwmMap;
+
+    // Interrupt pins (e.g. 2, 3 on Uno). Custom/unknown board types default
+    // to no interrupt pins unless explicitly configured via `interruptPins`.
+    const interruptMap = new Map<number, SimInterruptPin>();
+    const intPinNumbers = config.interruptPins ?? getInterruptPinsForBoard(config.boardType);
+    for (const pinNum of intPinNumbers) {
+      if (pinNum < digitalCount) {
+        interruptMap.set(pinNum, new SimInterruptPin(pinNum));
+      }
+    }
+    this.interruptPins = interruptMap;
+
+    // Serial ports
+    const serialMap = new Map<number, SimSerialPort>();
+    for (let i = 0; i < uartCount; i++) {
+      serialMap.set(i, new SimSerialPort(i, config.uartRxBufferSize, config.uartTxBufferSize));
+    }
+    this.serialPorts = serialMap;
+
+    // I2C buses
+    const i2cMap = new Map<number, SimI2CBus>();
+    for (let i = 0; i < i2cCount; i++) {
+      i2cMap.set(i, new SimI2CBus(i));
+    }
+    this.i2cBuses = i2cMap;
+
+    // SPI buses
+    const spiMap = new Map<number, SimSPIBus>();
+    for (let i = 0; i < spiCount; i++) {
+      spiMap.set(i, new SimSPIBus());
+    }
+    this.spiBuses = spiMap;
+  }
+
+  // --- Convenience accessors ---
+
+  /** Get digital pin by number. Throws if out of range. */
+  digital(pin: number): SimDigitalPin {
+    const p = this.digitalPins.get(pin);
+    if (!p) throw new Error(`Digital pin ${pin} not available on this board`);
+    return p;
+  }
+
+  /** Get analog pin by number (A0=0, A1=1, ...). Throws if out of range. */
+  analog(pin: number): SimAnalogPin {
+    const p = this.analogPins.get(pin);
+    if (!p) throw new Error(`Analog pin A${pin} not available on this board`);
+    return p;
+  }
+
+  /** Get PWM pin by number. Throws if not a PWM pin. */
+  pwm(pin: number): SimPWMPin {
+    const p = this.pwmPins.get(pin);
+    if (!p) throw new Error(`Pin ${pin} is not a PWM pin on this board`);
+    return p;
+  }
+
+  /** Get interrupt pin by number. Throws if not an interrupt pin. */
+  interrupt(pin: number): SimInterruptPin {
+    const p = this.interruptPins.get(pin);
+    if (!p) throw new Error(`Pin ${pin} is not an interrupt pin on this board`);
+    return p;
+  }
+
+  /** Get serial port by number (0 = UART0). */
+  serial(port: number = 0): SimSerialPort {
+    const s = this.serialPorts.get(port);
+    if (!s) throw new Error(`Serial port UART${port} not available on this board`);
+    return s;
+  }
+
+  /** Get I2C bus by number (0 = I2C0). */
+  i2c(bus: number = 0): SimI2CBus {
+    const b = this.i2cBuses.get(bus);
+    if (!b) throw new Error(`I2C bus ${bus} not available on this board`);
+    return b;
+  }
+
+  /** Get SPI bus by number (0 = SPI0). */
+  spi(bus: number = 0): SimSPIBus {
+    const b = this.spiBuses.get(bus);
+    if (!b) throw new Error(`SPI bus ${bus} not available on this board`);
+    return b;
+  }
+
+  // --- Reset ---
+
+  /** Reset all peripherals to initial state. */
+  reset(): void {
+    for (const pin of this.digitalPins.values()) pin.reset();
+    for (const pin of this.analogPins.values()) pin.reset();
+    for (const pin of this.pwmPins.values()) pin.reset();
+    for (const pin of this.interruptPins.values()) pin.reset();
+    for (const port of this.serialPorts.values()) port.reset();
+    for (const bus of this.i2cBuses.values()) bus.reset();
+    for (const bus of this.spiBuses.values()) bus.reset();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a simulated board with the given configuration.
+ *
+ * @example
+ * ```ts
+ * const board = createSimBoard({ boardType: 'arduino-uno' });
+ * board.digital(13).output();
+ * board.digital(13).high();
+ * expect(board.digital(13).getBitValue()).toBe(1);
+ * ```
+ */
+export function createSimBoard(config: SimBoardConfig): SimBoard {
+  return new SimBoard(config);
+}
+
+// ---------------------------------------------------------------------------
+// Board-specific pin maps
+//
+// Only known board types carry a default capability pin map. Custom and
+// unrecognized board types return an empty set — use `pwmPins` /
+// `interruptPins` on SimBoardConfig to declare capability pins for them.
+// ---------------------------------------------------------------------------
+
+function getPwmPinsForBoard(boardType: string): number[] {
+  switch (boardType) {
+    case 'arduino-uno':
+    case 'arduino-nano':
+      return [3, 5, 6, 9, 10, 11];
+    default:
+      return [];
+  }
+}
+
+function getInterruptPinsForBoard(boardType: string): number[] {
+  switch (boardType) {
+    case 'arduino-uno':
+    case 'arduino-nano':
+      return [2, 3];
+    default:
+      return [];
+  }
+}

package/src/board/from-definition.ts

@@ -0,0 +1,91 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — Derive a SimBoard from a BoardDefinition
+// ---------------------------------------------------------------------------
+
+import type { BoardDefinition } from '@typecad/cuttlefish/api/schema';
+import { createSimBoard } from './board-sim.js';
+import type { SimBoard } from './board-sim.js';
+
+/**
+ * Build a simulated board from a board package's `BoardDefinition`.
+ *
+ * Every `@typecad/board-*` package exports a `BoardDefinition` whose `pins.all`
+ * entries carry real framework pin numbers and per-pin capability flags, and
+ * whose `peripherals` describe the ADC resolution/reference and bus counts.
+ * This helper reads that authoritative data and produces a `SimBoard` whose
+ * pin layout, PWM/interrupt pins, analog ADC config, and bus counts match the
+ * real board — without hardcoding them.
+ *
+ * @example
+ * ```ts
+ * import { ArduinoUno } from '@typecad/board-arduino-uno';
+ * import { createBoardFromDefinition } from '@typecad/simulator';
+ *
+ * const board = createBoardFromDefinition(ArduinoUno);
+ * board.digital(13).asOutput().high();   // LED on PB5
+ * board.analog(0).injectVoltage(2.5);    // A0, 10-bit / 5V reference
+ * ```
+ *
+ * The board package must be built (its `dist/`) so the `BoardDefinition` is
+ * importable at runtime.
+ *
+ * **Derived from the `BoardDefinition`:**
+ *
+ * | SimBoard field | BoardDefinition source |
+ * |----------------|------------------------|
+ * | `digitalPinCount` | `pins.digital.length` |
+ * | `analogPinCount`  | `pins.analog.length` |
+ * | `pwmPins`         | `pins.all` filtered by `capabilities.pwm` |
+ * | `interruptPins`   | `pins.all` filtered by `capabilities.interrupt` (excluding `unsafe`) |
+ * | `i2cBusCount`     | `peripherals.i2c.length` |
+ * | `spiBusCount`     | `peripherals.spi.length` |
+ * | `uartCount`       | `peripherals.uart.length` |
+ * | ADC resolution    | `peripherals.adc[0].resolution` |
+ * | ADC reference     | `peripherals.adc[0].referenceVoltage` |
+ *
+ * @param def - The board package's `BoardDefinition` (e.g. `ArduinoUno`).
+ * @returns A `SimBoard` configured to match the board.
+ */
+export function createBoardFromDefinition(def: BoardDefinition): SimBoard {
+  const all = def.pins.all;
+
+  const pwmPins = all
+    .filter(p => p.capabilities?.pwm)
+    .map(p => p.number);
+
+  // Interrupt-capable pins, excluding any marked unsafe (e.g. boot-strap pins).
+  // The `interrupt` capability flag is set per-pin in the board definition's
+  // `pins.all`; for ATmega328P only PD2 (INT0) and PD3 (INT1) carry it, so
+  // this yields [2, 3] on Uno. Override with `createSimBoard({ interruptPins })`
+  // if your board's flagging differs from the interrupts you want to simulate.
+  const interruptPins = all
+    .filter(p => p.capabilities?.interrupt && !p.unsafe)
+    .map(p => p.number);
+
+  const board = createSimBoard({
+    boardType: def.id,
+    digitalPinCount: def.pins.digital.length,
+    analogPinCount: def.pins.analog.length,
+    i2cBusCount: def.peripherals.i2c?.length ?? 1,
+    spiBusCount: def.peripherals.spi?.length ?? 1,
+    uartCount: def.peripherals.uart?.length ?? 1,
+    pwmPins,
+    interruptPins,
+  });
+
+  // Apply the board's ADC resolution and reference voltage to every analog
+  // pin so readVoltage() produces board-accurate values out of the box.
+  const adc = def.peripherals.adc?.[0];
+  if (adc) {
+    for (const pin of board.analogPins.values()) {
+      if (typeof adc.resolution === 'number') {
+        pin.setResolution(adc.resolution);
+      }
+      if (typeof adc.referenceVoltage === 'number') {
+        pin.setAnalogReference(adc.referenceVoltage);
+      }
+    }
+  }
+
+  return board;
+}

package/src/bus/i2c-sim.ts

@@ -0,0 +1,212 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — I2C bus simulation
+// ---------------------------------------------------------------------------
+
+import { I2CStatus } from '../contracts.js';
+import type {
+  II2CBus,
+  II2CDeviceAccessor,
+  ErrorPolicy,
+} from '../contracts.js';
+import type { I2CAddress } from '@typecad/hal';
+import type { ISimI2CDevice } from '../types.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 implements II2CBus {
+  readonly busNumber: number;
+  isEnabled: boolean = false;
+  errorPolicy: ErrorPolicy = 'callback';
+
+  private _devices: Map<I2CAddress, ISimI2CDevice> = new Map();
+  private _speed: number = 100000;
+  private _slaveAddress: I2CAddress | null = null;
+  private _errorHandler: ((status: I2CStatus, address: I2CAddress, operation: 'read' | 'write') => void) | null = null;
+
+  /** Track all operations for test assertions. */
+  private _log: I2COperationLog[] = [];
+
+  constructor(busNumber: number = 0) {
+    this.busNumber = busNumber;
+  }
+
+  // --- II2CBus methods ---
+
+  begin(address?: I2CAddress): void {
+    if (address !== undefined) {
+      this._slaveAddress = address;
+    }
+    this.isEnabled = true;
+  }
+
+  end(): void {
+    // In simulation, ending the bus disables it without releasing mock devices.
+    this.isEnabled = false;
+  }
+
+  setClock(hz: number): void {
+    this._speed = hz;
+  }
+
+  device(address: I2CAddress): II2CDeviceAccessor {
+    return createDeviceAccessor(this, address);
+  }
+
+  onError(handler: (status: I2CStatus, address: I2CAddress, operation: 'read' | 'write') => void): void {
+    this._errorHandler = handler;
+  }
+
+  recover(): boolean {
+    return true;
+  }
+
+  // --- Simulation helpers ---
+
+  /**
+   * Attach a mock I2C device at the given address.
+   */
+  attachDevice(address: I2CAddress, device: ISimI2CDevice): void {
+    this._devices.set(address, device);
+  }
+
+  /**
+   * Remove a mock device.
+   */
+  detachDevice(address: I2CAddress): void {
+    this._devices.delete(address);
+  }
+
+  /**
+   * Get the operation log for test assertions.
+   */
+  getLog(): readonly I2COperationLog[] {
+    return this._log;
+  }
+
+  /**
+   * Clear the operation log.
+   */
+  clearLog(): void {
+    this._log = [];
+  }
+
+  /**
+   * Reset all state.
+   */
+  reset(): void {
+    this._devices.clear();
+    this._log = [];
+    this._errorHandler = null;
+    this.isEnabled = false;
+    this._speed = 100000;
+    this._slaveAddress = null;
+  }
+
+  // --- Internal ---
+
+  /** @internal */
+  _getDevice(address: I2CAddress): ISimI2CDevice | undefined {
+    return this._devices.get(address);
+  }
+
+  /** @internal */
+  _logOperation(op: I2COperationLog): void {
+    this._log.push(op);
+  }
+
+  /** @internal */
+  _fireError(status: I2CStatus, address: I2CAddress, operation: 'read' | 'write'): void {
+    if (this._errorHandler) {
+      this._errorHandler(status, address, operation);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Operation log
+// ---------------------------------------------------------------------------
+
+export interface I2COperationLog {
+  operation: 'read' | 'write';
+  address: I2CAddress;
+  register: number;
+  data?: number[];
+  timestamp: number;
+}
+
+// ---------------------------------------------------------------------------
+// Device accessor factory
+// ---------------------------------------------------------------------------
+
+function createDeviceAccessor(bus: SimI2CBus, address: I2CAddress): II2CDeviceAccessor {
+  return {
+    address,
+
+    readByte(register: number): number {
+      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: number, count: number): Uint8Array {
+      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: number, value: number): void {
+      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: number, data: Uint8Array | number[]): void {
+      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 });
+    },
+  };
+}