+
// system design
+
Project Architecture
+
+ Velxio is a fully local Arduino emulator using official Wokwi repositories for maximum
+ compatibility. It features real AVR8 CPU emulation, 48+ interactive electronic components,
+ a comprehensive wire system, and a build-time component discovery pipeline.
+
+
+
High-Level Overview
+
{`Browser (React + Vite)
+ ├── Monaco Editor ──► useEditorStore (Zustand)
+ ├── SimulatorCanvas ──► useSimulatorStore (Zustand)
+ │ ├── AVRSimulator (avr8js) 16 MHz AVR8 CPU
+ │ ├── RP2040Simulator (rp2040js)
+ │ ├── PinManager pin → component mapping
+ │ ├── PartSimulationRegistry 16 interactive parts
+ │ └── 48+ wokwi-elements Lit Web Components
+ └── HTTP (Axios) ──► FastAPI Backend (port 8001)
+ └── ArduinoCLIService ──► arduino-cli subprocess`}
+
+
Data Flows
+
+
1. Compilation
+
{`Click "Compile"
+ → EditorToolbar reads all workspace files
+ → POST /api/compile/ { files, board_fqbn }
+ → Backend: ArduinoCLIService writes temp dir
+ → arduino-cli compile --fqbn --output-dir build/
+ → Returns hex_content (Intel HEX string)
+ → useSimulatorStore.setCompiledHex() → loadHex()`}
+
+
2. Simulation Loop
+
{`Click "Run"
+ → AVRSimulator.start()
+ → requestAnimationFrame loop @ ~60 FPS
+ → Each frame: Math.floor(267 000 × speed) cycles
+ ├── avrInstruction(cpu) — decode + execute one AVR instruction
+ └── cpu.tick() — advance Timer0/1/2, USART, ADC
+ → PORTB/C/D write listeners fire
+ → PinManager.updatePort() → per-pin callbacks
+ → PartSimulationRegistry.onPinStateChange()
+ → wokwi-elements update visually`}
+
+
3. Input Components
+
{`User presses button on canvas
+ → wokwi web component fires 'button-press' event
+ → DynamicComponent catches event
+ → PartSimulationRegistry.attachEvents() handler
+ → AVRSimulator.setPinState(arduinoPin, LOW)
+ → AVRIOPort.setPin() injects external pin state
+ → CPU reads pin in next instruction`}
+
+
Key Frontend Stores (Zustand)
+
+
+ | Store | Key State | Purpose |
|---|
+
+
+ useEditorStore | files[], activeFileId | Multi-file Monaco workspace |
+ useSimulatorStore | simulator, components, wires, running | Simulation + canvas state |
+ useAuthStore | user, token | Auth (persisted localStorage) |
+ useProjectStore | projectId, slug | Currently open project |
+
+
+
+
Backend Routes
+
+
+ | Route | Description |
|---|
+
+
+ POST /api/compile/ | Compile sketch files → Intel HEX / UF2 |
+ GET /api/compile/boards | List available boards |
+ GET/POST /api/auth/* | Email/password + Google OAuth |
+ GET/POST /api/projects/* | CRUD project persistence (SQLite) |
+ GET /api/libraries/* | Arduino Library Manager integration |
+ GET /health | Health check endpoint |
+
+
+
+
Wire System
+
Wires are stored as objects with start/end endpoints tied to component pin positions:
+
{`{
+ id: string
+ start: { componentId, pinName, x, y }
+ end: { componentId, pinName, x, y }
+ color: string
+ signalType: 'digital' | 'analog' | 'power-vcc' | 'power-gnd'
+}`}
+
+ - Orthogonal routing — no diagonal segments
+ - Segment drag — drag perpendicular to segment orientation
+ - Auto-update — wire positions recalculate when components move
+ - Grid snapping — 20 px grid for all wire endpoints
+
+
+
+
+
// open-source libs
+
Wokwi Libraries
+
+ Velxio uses official Wokwi open-source repositories cloned locally in wokwi-libs/.
+ This gives you up-to-date, compatible emulation engines and visual components without npm registry
+ dependencies.
+
+
+
Cloned Repositories
+
+
+ | Library | Location | Purpose |
|---|
+
+
+
+ | wokwi-elements |
+ wokwi-libs/wokwi-elements/ |
+ 48+ Lit Web Components (LEDs, LCDs, sensors, buttons…) |
+
+
+ | avr8js |
+ wokwi-libs/avr8js/ |
+ ATmega328p / ATmega2560 CPU emulator at 16 MHz |
+
+
+ | rp2040js |
+ wokwi-libs/rp2040js/ |
+ Raspberry Pi Pico (RP2040) emulator |
+
+
+
+
+
Vite Configuration
+
frontend/vite.config.ts uses path aliases so imports resolve to the local builds:
+
{`resolve: {
+ alias: {
+ 'avr8js': '../wokwi-libs/avr8js/dist/esm',
+ '@wokwi/elements': '../wokwi-libs/wokwi-elements/dist/esm',
+ },
+}`}
+
+
Updating the Libraries
+
All at once (recommended)
+
{`# Windows
+update-wokwi-libs.bat`}
+
+
Manually
+
{`cd wokwi-libs/wokwi-elements
+git pull origin main
+npm install && npm run build
+
+cd ../avr8js
+git pull origin main
+npm install && npm run build
+
+cd ../rp2040js
+git pull origin main
+npm install && npm run build`}
+
+
After updating wokwi-elements
+
Regenerate component metadata so new components appear in the picker:
+
{`cd frontend
+npx tsx ../scripts/generate-component-metadata.ts`}
+
+
Available Wokwi Components (48)
+
+
+ | Category | Components |
|---|
+
+
+ | Boards | Arduino Uno, Mega, Nano, ESP32 DevKit |
+ | Sensors | DHT22, HC-SR04, PIR, Photoresistor, NTC, Joystick |
+ | Displays | LCD 16×2, LCD 20×4, 7-Segment |
+ | Input | Push button, 6mm button, Slide switch, DIP switch 8, Potentiometer |
+ | Output | LED, RGB LED, LED bar graph, Buzzer, NeoPixel |
+ | Motors | Servo, Stepper motor |
+ | Passive | Resistor, Slide potentiometer, LED ring, Matrix keypad |
+ | Other | IR receiver, DS1307 RTC, breadboards, etc. |
+
+
+
+
How avr8js Powers the Simulation
+
{`import { CPU, avrInstruction, AVRTimer, AVRUSART, AVRADC, AVRIOPort } from 'avr8js';
+
+const cpu = new CPU(programMemory); // ATmega328p at 16 MHz
+const portB = new AVRIOPort(cpu, portBConfig); // digital pins 8-13
+const portC = new AVRIOPort(cpu, portCConfig); // analog pins A0-A5
+const portD = new AVRIOPort(cpu, portDConfig); // digital pins 0-7
+
+function runFrame() {
+ const cycles = Math.floor(267_000 * speed);
+ for (let i = 0; i < cycles; i++) {
+ avrInstruction(cpu); // execute one AVR instruction
+ cpu.tick(); // advance timers + peripherals
+ }
+ requestAnimationFrame(runFrame);
+}`}
+
+
+
+
// AI integration
+
MCP Server
+
+ Velxio exposes a{' '}
+
+ Model Context Protocol
+ {' '}
+ (MCP) server that lets AI agents (Claude, Cursor, and others) create circuits,
+ generate code, and compile Arduino sketches directly.
+
+
+
Available Tools
+
+
+ | Tool | Description |
|---|
+
+
+ compile_project | Compile Arduino sketch files → Intel HEX / binary |
+ run_project | Compile and mark artifact as simulation-ready |
+ import_wokwi_json | Parse a Wokwi diagram.json → Velxio circuit |
+ export_wokwi_json | Serialise a Velxio circuit → Wokwi diagram.json |
+ create_circuit | Create a new circuit definition |
+ update_circuit | Merge changes into an existing circuit |
+ generate_code_files | Generate starter .ino code from a circuit |
+
+
+
+
Transport Options
+
+
1. stdio — Claude Desktop / CLI agents
+
{`cd backend
+python mcp_server.py`}
+
Claude Desktop config (~/.claude/claude_desktop_config.json):
+
{`{
+ "mcpServers": {
+ "velxio": {
+ "command": "python",
+ "args": ["/absolute/path/to/velxio/backend/mcp_server.py"]
+ }
+ }
+}`}
+
+
2. SSE / HTTP — Cursor IDE / web agents
+
{`cd backend
+python mcp_sse_server.py --port 8002`}
+
MCP client config:
+
{`{
+ "mcpServers": {
+ "velxio": { "url": "http://localhost:8002/sse" }
+ }
+}`}
+
+
Circuit Data Format
+
Velxio circuits are plain JSON objects:
+
{`{
+ "board_fqbn": "arduino:avr:uno",
+ "version": 1,
+ "components": [
+ { "id": "led1", "type": "wokwi-led", "left": 200, "top": 100,
+ "rotate": 0, "attrs": { "color": "red" } }
+ ],
+ "connections": [
+ { "from_part": "uno", "from_pin": "13",
+ "to_part": "led1", "to_pin": "A", "color": "green" }
+ ]
+}`}
+
+
Supported Board FQBNs
+
+
+ | Board | FQBN |
|---|
+
+
+ | Arduino Uno | arduino:avr:uno |
+ | Arduino Mega | arduino:avr:mega |
+ | Arduino Nano | arduino:avr:nano |
+ | Raspberry Pi Pico | rp2040:rp2040:rpipico |
+
+
+
+
Example — Blink LED from Scratch
+
{`// Step 1 — Create a circuit
+{
+ "tool": "create_circuit",
+ "arguments": {
+ "board_fqbn": "arduino:avr:uno",
+ "components": [
+ { "id": "led1", "type": "wokwi-led",
+ "left": 150, "top": 100, "attrs": { "color": "red" } },
+ { "id": "r1", "type": "wokwi-resistor",
+ "left": 150, "top": 180, "attrs": { "value": "220" } }
+ ],
+ "connections": [
+ { "from_part": "uno", "from_pin": "13",
+ "to_part": "led1", "to_pin": "A", "color": "green" },
+ { "from_part": "led1", "from_pin": "C",
+ "to_part": "r1", "to_pin": "1", "color": "black" },
+ { "from_part": "r1", "from_pin": "2",
+ "to_part": "uno", "to_pin": "GND.1", "color": "black" }
+ ]
+ }
+}
+
+// Step 2 — Generate code
+{
+ "tool": "generate_code_files",
+ "arguments": {
+ "circuit": "",
+ "sketch_name": "blink",
+ "extra_instructions": "Blink the red LED every 500ms"
+ }
+}
+
+// Step 3 — Compile
+{
+ "tool": "compile_project",
+ "arguments": {
+ "files": [
+ {
+ "name": "blink.ino",
+ "content": "void setup(){pinMode(13,OUTPUT);}\\nvoid loop(){digitalWrite(13,HIGH);delay(500);digitalWrite(13,LOW);delay(500);}"
+ }
+ ],
+ "board": "arduino:avr:uno"
+ }
+}`}
+
+
Setup
+
{`cd backend
+pip install -r requirements.txt
+
+# Ensure arduino-cli is installed
+arduino-cli version
+arduino-cli core update-index
+arduino-cli core install arduino:avr
+
+# Run tests
+python -m pytest tests/test_mcp_tools.py -v`}
+
+
+
Full reference:{' '}
+ See{' '}
+
+ docs/MCP.md
+ {' '}
+ in the repository.
+
+