@typecad/simulator 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 typecad0
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# @typecad/simulator
+
+Node.js hardware simulation runtime for TypeCAD.
+
+## Overview
+
+`@typecad/simulator` provides a simulated hardware runtime for TypeCAD firmware and tests. It exposes simulated GPIO pins, serial ports, I2C buses, SPI buses, PWM pins, and interrupt pins so you can verify hardware logic without using a physical board.
+
+## When to use the simulator
+
+`@typecad/simulator` is best for testing and validating hardware-facing logic in Node.js before you use a real board. It is not a transpiler output checker, and it does not replace `@typecad/expect` for firmware-level hardware tests.
+
+Use the simulator when you want to:
+
+- unit test control logic for buttons, LEDs, and buses
+- verify that a parser sends the correct serial bytes
+- mock sensor input through analog or I2C injection
+- exercise interrupt-driven code paths without physical hardware
+- run CI-friendly tests that are fast and deterministic
+
+Do not use it for:
+
+- verifying TypeCAD transpilation output
+- measuring real ADC noise or analog timing
+- checking exact microsecond timing behavior
+
+## Quick start
+
+```ts
+import { createSimBoard } from '@typecad/simulator';
+
+const board = createSimBoard({ boardType: 'arduino-uno' });
+
+const button = board.digital(2).asInputPullUp();
+const led = board.digital(13).asOutput();
+
+button.injectValue(0); // simulate a pressed active-low button
+if (!button.read()) {
+  led.high();
+}
+
+console.log(led.getBitValue()); // 1
+```
+
+## Example: button-driven LED logic
+
+This pattern is the real value of the simulator: you can test logic driven by external inputs without a board.
+
+```ts
+import { describe, it, expect } from 'vitest';
+import { createSimBoard } from '@typecad/simulator';
+
+function updateLed(button: any, led: any) {
+  if (!button.read()) {
+    led.high();
+  } else {
+    led.low();
+  }
+}
+
+describe('button toggle logic', () => {
+  it('turns the LED on when the button is pressed', () => {
+    const board = createSimBoard({ boardType: 'arduino-uno' });
+    const button = board.digital(2).asInputPullUp();
+    const led = board.digital(13).asOutput();
+
+    button.injectValue(0); // press button
+    updateLed(button, led);
+
+    expect(led.getBitValue()).toBe(1);
+  });
+});
+```
+
+## How to use
+
+### Create a simulated board
+
+Use `createSimBoard()` with a board type and optional custom counts:
+
+- `boardType` — board identifier such as `arduino-uno` or `arduino-nano`. Known board types carry default PWM/interrupt pin maps; custom/unknown types have no capability pins unless declared via `pwmPins`/`interruptPins`.
+- `digitalPinCount` — number of digital pins
+- `analogPinCount` — number of analog pins
+- `uartCount` — number of serial ports
+- `i2cBusCount` — number of I2C buses
+- `spiBusCount` — number of SPI buses
+- `pwmPins` / `interruptPins` — override the capability pin numbers (defaults to the board type's map, or empty for custom boards)
+
+### Access simulated peripherals
+
+The `SimBoard` instance exposes typed accessors:
+
+- `board.digital(pin)` — `SimDigitalPin`
+- `board.analog(pin)` — `SimAnalogPin`
+- `board.pwm(pin)` — `SimPWMPin`
+- `board.interrupt(pin)` — `SimInterruptPin`
+- `board.serial(port)` — `SimSerialPort`
+- `board.i2c(bus)` — `SimI2CBus`
+- `board.spi(bus)` — `SimSPIBus`
+
+### Simulating a real board package
+
+When you already depend on a `@typecad/board-*` package, use `createBoardFromDefinition()` to build a `SimBoard` whose pin layout, PWM/interrupt pins, ADC resolution/reference, and bus counts match the real board — instead of hardcoding them in `createSimBoard()`:
+
+```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 (pin 13)
+board.pwm(9).pwm(50);                  // PWM on PB1 (pin 9)
+board.analog(0).injectVoltage(2.5);    // A0, 10-bit ADC, 5V reference
+```
+
+This is the recommended path for board-specific tests. The board package must be built so its `BoardDefinition` is importable at runtime. See the [Software-Defined Hardware docs](https://typecad.dev/docs/simulation/software-defined-hardware#simulating-a-real-board-package) for the full list of derived fields.
+
+### Verify state and reset
+
+The simulated board supports reset and state inspection, making it useful for unit tests and firmware validation without hardware:
+
+```ts
+board.digital(13).output();
+board.digital(13).high();
+expect(board.digital(13).getBitValue()).toBe(1);
+board.reset();
+expect(board.digital(13).getBitValue()).toBe(0);
+```
+
+### HAL compatibility
+
+`@typecad/simulator` is built on the same hardware abstraction contract used by the rest of the ecosystem. The simulator package owns the runtime contract hierarchy (`BasePin`, `PWMPin`, `AnalogPin`, `InterruptPin`, `II2CBus`, `ISPIBus`, `ISerialPort`, and the `I2CStatus`/`SPIStatus`/`UARTStatus` enums) in its own `contracts.ts`, and re-exports it for consumers. Primitive and protocol-shape types (`PinMode`, `DigitalValue`, `AnalogValue`, `InterruptHandler`, `I2CAddress`, `SPIMode`, `SPIBitOrder`, `SPISettings`) are imported from `@typecad/hal`:
+
+- `SimDigitalPin` implements `BasePin` and digital pin semantics.
+- `SimAnalogPin` implements `AnalogPin` semantics.
+- `SimPWMPin` implements `PWMPin` semantics (including `getPwmFrequency()` / `getPwmResolution()`).
+- `SimInterruptPin` implements `InterruptPin` semantics.
+- `SimSerialPort` implements `ISerialPort` / UART communication semantics.
+- `SimI2CBus` and `SimSPIBus` expose the same bus-style APIs expected by TypeCAD HAL consumers.
+
+### How the simulator uses HAL concepts
+
+- `PinMode` values are imported from `@typecad/hal` and used to track simulated pin direction and pull state.
+- capability flags like `digitalInput`, `pwm`, and `interrupt` are modeled using the same type definitions that HAL packages expose for pin capabilities.
+- serial, I2C, and SPI simulation classes rely on the shared TypeCAD bus interfaces to ensure host code can interact with them using the same method names and semantics as real hardware.
+- `createSimBoard()` selects default PWM and interrupt pin sets by board type, matching the physical pin layout conventions used by TypeCAD board packages.
+
+This makes the simulator a practical way to validate hardware logic and unit tests while staying aligned with TypeCAD's HAL abstraction layer.

package/dist/board/board-sim.d.ts

@@ -0,0 +1,52 @@
+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';
+/**
+ * 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 declare 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);
+    /** Get digital pin by number. Throws if out of range. */
+    digital(pin: number): SimDigitalPin;
+    /** Get analog pin by number (A0=0, A1=1, ...). Throws if out of range. */
+    analog(pin: number): SimAnalogPin;
+    /** Get PWM pin by number. Throws if not a PWM pin. */
+    pwm(pin: number): SimPWMPin;
+    /** Get interrupt pin by number. Throws if not an interrupt pin. */
+    interrupt(pin: number): SimInterruptPin;
+    /** Get serial port by number (0 = UART0). */
+    serial(port?: number): SimSerialPort;
+    /** Get I2C bus by number (0 = I2C0). */
+    i2c(bus?: number): SimI2CBus;
+    /** Get SPI bus by number (0 = SPI0). */
+    spi(bus?: number): SimSPIBus;
+    /** Reset all peripherals to initial state. */
+    reset(): void;
+}
+/**
+ * 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 declare function createSimBoard(config: SimBoardConfig): SimBoard;

package/dist/board/board-sim.js

@@ -0,0 +1,188 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — Simulated board factory
+// ---------------------------------------------------------------------------
+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 {
+    constructor(config) {
+        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();
+        for (let i = 0; i < digitalCount; i++) {
+            digitalMap.set(i, new SimDigitalPin(i));
+        }
+        this.digitalPins = digitalMap;
+        // Analog pins (A0, A1, ...)
+        const analogMap = new Map();
+        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();
+        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();
+        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();
+        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();
+        for (let i = 0; i < i2cCount; i++) {
+            i2cMap.set(i, new SimI2CBus(i));
+        }
+        this.i2cBuses = i2cMap;
+        // SPI buses
+        const spiMap = new Map();
+        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) {
+        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) {
+        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) {
+        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) {
+        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 = 0) {
+        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 = 0) {
+        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 = 0) {
+        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() {
+        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) {
+    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) {
+    switch (boardType) {
+        case 'arduino-uno':
+        case 'arduino-nano':
+            return [3, 5, 6, 9, 10, 11];
+        default:
+            return [];
+    }
+}
+function getInterruptPinsForBoard(boardType) {
+    switch (boardType) {
+        case 'arduino-uno':
+        case 'arduino-nano':
+            return [2, 3];
+        default:
+            return [];
+    }
+}

package/dist/board/from-definition.d.ts

@@ -0,0 +1,43 @@
+import type { BoardDefinition } from '@typecad/cuttlefish/api/schema';
+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 declare function createBoardFromDefinition(def: BoardDefinition): SimBoard;

package/dist/board/from-definition.js

@@ -0,0 +1,82 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — Derive a SimBoard from a BoardDefinition
+// ---------------------------------------------------------------------------
+import { createSimBoard } 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) {
+    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/dist/bus/i2c-sim.d.ts

@@ -0,0 +1,61 @@
+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';
+/**
+ * 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 declare class SimI2CBus implements II2CBus {
+    readonly busNumber: number;
+    isEnabled: boolean;
+    errorPolicy: ErrorPolicy;
+    private _devices;
+    private _speed;
+    private _slaveAddress;
+    private _errorHandler;
+    /** Track all operations for test assertions. */
+    private _log;
+    constructor(busNumber?: number);
+    begin(address?: I2CAddress): void;
+    end(): void;
+    setClock(hz: number): void;
+    device(address: I2CAddress): II2CDeviceAccessor;
+    onError(handler: (status: I2CStatus, address: I2CAddress, operation: 'read' | 'write') => void): void;
+    recover(): boolean;
+    /**
+     * Attach a mock I2C device at the given address.
+     */
+    attachDevice(address: I2CAddress, device: ISimI2CDevice): void;
+    /**
+     * Remove a mock device.
+     */
+    detachDevice(address: I2CAddress): void;
+    /**
+     * Get the operation log for test assertions.
+     */
+    getLog(): readonly I2COperationLog[];
+    /**
+     * Clear the operation log.
+     */
+    clearLog(): void;
+    /**
+     * Reset all state.
+     */
+    reset(): void;
+    /** @internal */
+    _getDevice(address: I2CAddress): ISimI2CDevice | undefined;
+    /** @internal */
+    _logOperation(op: I2COperationLog): void;
+    /** @internal */
+    _fireError(status: I2CStatus, address: I2CAddress, operation: 'read' | 'write'): void;
+}
+export interface I2COperationLog {
+    operation: 'read' | 'write';
+    address: I2CAddress;
+    register: number;
+    data?: number[];
+    timestamp: number;
+}