Motor control circuit simulator

Wire it. Run it. Break it.
Let an agent drive it.

VoltLab simulates electromechanical motor-control circuits — DOL starters, interlocks, timers, reversing starters, even a 10-story relay elevator — with a real per-tick electrical solver and IEC-style schematics. And because it speaks MCP, an LLM agent can build, wire, fault and document every circuit for you.

CI License: MIT Node ≥ 18 MCP server
▶ Try it live Source on GitHub Get started
VoltLab running the DOL starter demo in dark theme
No install, no backend

This is the real simulator

Not a video, not a mock-up: the page below runs the actual sim/engine.js solver in your browser — the same code the desktop app and the MCP agents drive.

Try: hold S1 on the schematic — the contactor picks up and the motor spins (release: the seal-in keeps it running). Toggle breaker Q1 by clicking it. Pick reversing-starter from the dropdown and watch the interlock. When the thermal overload KK1 trips (⏩ 5s after a stall), click its red RESET.

Why VoltLab

A trainer bench, a drawing office and an agent playground

🔌Real physics

Per-tick union-find netlists and phase propagation: 6× FLC inrush, class-10 thermal trip curves, single-phasing, coast-down, fuse blowing — not a canned animation.

📐IEC-style schematics

16 device types drawn as proper IEC symbols, phase-colored live wires, terminal-level wiring, zoom from 25–300 %, inspector and event log.

🤖MCP agent layer

26 tools over stdio JSON-RPC (or plain HTTP): agents build, wire, fault, reset, fast-forward and inspect circuits — the full test suite is an agent session.

📄Self-documenting exports

Any circuit exports as an IEC 61082-1-style multi-sheet PDF drawing set (zone grids, title blocks, sheet index) and a scripted 720p demo video.

🎓Learn as you go

An 11-step interactive tutorial with action gates, five worked example circuits with behavior tests, light and dark themes.

📦Zero runtime deps

Server, simulator and MCP bridge are pure Node stdlib. Electron is the only dev dependency. npm run serve and you're running.

Examples included

Five worked circuits, all test-covered

CircuitWhat it demonstrates
dol-starterDirect-On-Line start/stop, seal-in holding, class-10 overload trip, trip lamp
reversing-starterForward/reverse contactors, phase-swap wiring, an interlock that makes simultaneous energizing impossible
timer-sequenceOn-delay timer starts a second conveyor motor 3 s after the first
elevator-2floorCall latching, travel limit switches, NC cross-interlock, hoist overload
elevator-10floorFull 10-story relay elevator — 3-deck floor cam, per-floor call relays, auto-dispatch with dwell: 46 components, 169 wires
The 10-story relay elevator circuit overview
The 10-story relay elevator — every K1–K10 call relay, contactor and cam deck is live.
Tripped thermal overload close-up
After ~15 s of locked rotor the class-10 overload trips: coil dropped, trip lamp lit, red RESET waiting.
Documentation that writes itself

Exports a real drawing set

One click (or one agent tool call) turns any circuit into an IEC 61082-1-style PDF drawing package — and records a narrated-by-captions demo video.

PDF drawing set index sheet with tile map
Sheet 1: cover with full-circuit overview, numbered tile map and sheet index.
PDF schematic sheet with zone grid and title block
Schematic sheets: 1:1 tiling across A4 landscape, zone grids, title blocks — the elevator spans 17 sheets.
Run the full app

Quick start

git clone https://github.com/touhidsiddiqueeraj-bit/VoltLab.git
cd voltlab
npm install            # once — installs Electron only

npm run serve          # browser mode → http://127.0.0.1:8123
npm start              # or the Electron desktop window
npm test               # 31 headless tests: engine + circuits + MCP end-to-end

Agents connect over MCP — point any client at mcp/server.mjs and it gets the full 26-tool catalog (reference).

Go deeper

Documentation

🏛 Architecture

How the solver, host, UI and MCP layer fit together — and the sharp edges we hit building it.

🤖 MCP reference

All 26 tools with arguments, raw-HTTP equivalents and a worked agent session.

🧾 Circuit format

The JSON schema: components, wires, waypoints and demo scripts.

💡 Example circuits

A guided tour of all five examples with scenarios and exercises.