netlist: API & Usage Documentation

A modular JavaScript library for simulating and validating Arduino-style breadboard circuits.

Installation

npm install netlist

Core Modules and Classes

1. Component (Base Class)

• Usage: Extend this to create your own components.
• Constructor: new Component(name: string)
• Properties:
  • name — The component's name.
  • pins — An object mapping pin names to Pin instances.
• Methods:
  • addPin(pin: Pin) — Add a pin to the component.

2. Pin

• Usage: Represents a pin on any component.
• Constructor: new Pin(name: string, type: string)
• Properties:
  • name — Pin name (e.g., 'A', 'C', '1', '2', etc.)
  • type — Pin type (e.g., 'anode', 'cathode', 'terminal', 'power', 'ground', etc.)
  • connectedTo — Array of other Pin instances this pin is connected to.

3. Breadboard

• Usage: Simulates a breadboard with rows, columns, and power rails.
• Constructor: new Breadboard(name: string, rows: number = 30)
• Public Methods:
  • connectRow(row: number) — Internally connects all pins in a row (e.g., 1a–1j).
  • connectRail(rail: string) — Internally connects all pins in a rail ('ra' or 'rb').
  • propagateRailConnections(rail: string) — Propagates external connections to all pins in a rail (simulates bus behavior).
• Example:

  const bb = new Breadboard('BB');
  bb.connectRow(1);
  bb.connectRail('ra');
  bb.connectRail('rb');

4. LED

• Usage: Single-color or RGB LED.
• Constructor: new LED(name: string, type: 'led' | 'rgb-led' = 'led')
• Pins:
  • Single-color: 'A' (anode), 'C' (cathode)
  • RGB: 'R', 'G', 'B' (anodes), 'C' (common cathode)
• Example:

  const led = new LED('LED1'); // single-color
  const rgb = new LED('RGB1', 'rgb-led');

5. Resistor

• Usage: Two-terminal resistor.
• Constructor: new Resistor(name: string)
• Pins: '1', '2'
• Example:

  const r = new Resistor('R1');

6. Arduino

• Usage: Simulates an Arduino board with digital, power, and ground pins.
• Constructor: new Arduino()
• Pins: 'D2'–'D13', 'GND', '5V'
• Example:

  const arduino = new Arduino();

7. connect

• Usage: Connects two pins (bidirectional).
• Signature: connect(pin1: Pin, pin2: Pin)
• Example:

  connect(arduino.pins['D2'], led.pins['A']);
  connect(led.pins['C'], arduino.pins['GND']);

8. validateCircuit

• Usage: Validates a list of components for wiring issues.
• Signature: validateCircuit(components: Component[]): string[]
• Returns: Array of issue strings (empty if no issues).
• Checks:
  • Short circuits (power to ground, direct or indirect)
  • Floating pins (inputs, anodes, cathodes, terminals)
  • Incorrect LED polarity
  • Output-to-output connections
• Example:

  const issues = validateCircuit([arduino, led, resistor]);
  if (issues.length) {
    console.log('Issues:', issues);
  }

Example: Classic LED Circuit on Breadboard

import Breadboard from 'netlist/components/Breadboard.js';
import LED from 'netlist/components/LED.js';
import Resistor from 'netlist/components/Resistor.js';
import Arduino from 'netlist/components/Arduino.js';
import connect from 'netlist/circuit/connect.js';
import validateCircuit from 'netlist/circuit/validateCircuit.js';

const bb = new Breadboard('BB');
bb.connectRow(1);
bb.connectRail('ra');
bb.connectRail('rb');
const arduino = new Arduino();
const led = new LED('LED1');
const resistor = new Resistor('R1');

connect(arduino.pins['5V'], bb.pins['ra1']);
connect(arduino.pins['GND'], bb.pins['rb1']);
bb.propagateRailConnections('ra');
bb.propagateRailConnections('rb');
connect(bb.pins['ra5'], resistor.pins['1']);
connect(resistor.pins['2'], bb.pins['1a']);
connect(bb.pins['1b'], led.pins['A']);
connect(led.pins['C'], bb.pins['rb5']);
connect(bb.pins['1a'], bb.pins['1b']);

const issues = validateCircuit([bb, arduino, led, resistor]);
console.log(issues); // []

Example: Detecting Errors

// Floating LED cathode
const led = new LED('LED1');
connect(arduino.pins['D2'], led.pins['A']);
const issues = validateCircuit([arduino, led]);
console.log(issues); // ['Floating input: LED1.C is not connected']

// Short circuit via breadboard rail
const powerPin = new Pin('PWR', 'power');
const groundPin = new Pin('GND', 'ground');
const dummy = { name: 'Dummy', pins: { PWR: powerPin, GND: groundPin } };
connect(powerPin, bb.pins['ra1']);
connect(groundPin, bb.pins['ra2']);
bb.propagateRailConnections('ra');
const issues2 = validateCircuit([bb, dummy]);
console.log(issues2); // ['Short circuit: PWR (power) connected to GND (ground)']

How to Use in Your Project

1. Install:
   npm install netlist

2. Import and Use:
   Import the classes and functions you need, build your circuit, connect pins, and validate.

3. Extend:
   Add your own components by extending Component and defining pins.

API Summary

| Class/Function | Purpose | |------------------------|----------------------------------------------| | Component | Base for all components | | Pin | Represents a pin | | Breadboard | Simulates a breadboard | | LED | Single-color or RGB LED | | Resistor | Two-terminal resistor | | Arduino | Simulates Arduino board | | connect | Connects two pins | | validateCircuit | Validates a list of components |

License

MIT

If you need more advanced usage, integration with other simulation tools, or want to see more real-world project examples, let me know!