velxio/ARCHITECTURE.md

Project Architecture - Arduino Emulator

Overview

This project is a fully local Arduino emulator using official Wokwi repositories for maximum compatibility.

┌─────────────────────────────────────────────────────────────┐
│                    USER (Browser)                           │
│                   http://localhost:5173                      │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                  FRONTEND (React + Vite)                     │
│                                                              │
│  ┌────────────────┐  ┌──────────────────┐  ┌─────────────┐ │
│  │ Monaco Editor  │  │  Zustand Store   │  │  Simulator  │ │
│  │  (Code Edit)   │  │  (State Mgmt)    │  │   Canvas    │ │
│  └────────────────┘  └──────────────────┘  └─────────────┘ │
│           │                   │                      │       │
│           └───────────────────┴──────────────────────┘       │
│                              │                               │
│                              ▼                               │
│  ┌──────────────────────────────────────────────────────┐   │
│  │         Wokwi Components Integration                 │   │
│  │  (wokwi-elements + avr8js from local repos)         │   │
│  └──────────────────────────────────────────────────────┘   │
└──────────────────────────┬──────────────────────────────────┘
                           │ HTTP (axios)
                           ▼
┌─────────────────────────────────────────────────────────────┐
│              BACKEND (FastAPI + Python)                      │
│                http://localhost:8000                         │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  POST /api/compile                                   │    │
│  │  - Receives Arduino code (.ino)                      │    │
│  │  - Compiles with arduino-cli                         │    │
│  │  - Returns .hex file                                 │    │
│  └─────────────────────────────────────────────────────┘    │
│                           │                                  │
│                           ▼                                  │
│  ┌─────────────────────────────────────────────────────┐    │
│  │         Arduino CLI Service                          │    │
│  │  (Invokes arduino-cli as subprocess)                 │    │
│  └─────────────────────────────────────────────────────┘    │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
                ┌──────────────────────┐
                │    arduino-cli       │
                │   (Local system)     │
                └──────────────────────┘

Data Flow: Compilation and Simulation

1. Code Editing

User writes code
    ↓
Monaco Editor
    ↓
Zustand (useEditorStore)
    ↓
State: code

2. Compilation

Click "Compile"
    ↓
EditorToolbar.tsx → compileCode()
    ↓
Axios POST → http://localhost:8000/api/compile
    ↓
Backend: ArduinoCLIService.compile()
    ↓
arduino-cli compile --fqbn arduino:avr:uno
    ↓
Generates .hex file in temp directory
    ↓
Backend reads .hex and returns content
    ↓
Frontend: useSimulatorStore.setCompiledHex()

3. Simulation (Currently simplified)

Click "Run"
    ↓
useSimulatorStore.setRunning(true)
    ↓
SimulatorCanvas: useEffect detects running=true
    ↓
setInterval every 1000ms
    ↓
updateComponentState('led-builtin', !state)
    ↓
wokwi-led component updates visually

4. Real Simulation (Coming with avr8js)

Compiled .hex file
    ↓
AVRSimulator.loadHex(hex)
    ↓
hexParser → Uint16Array (program memory)
    ↓
CPU = new CPU(program)
    ↓
Click "Run" → AVRSimulator.start()
    ↓
requestAnimationFrame loop
    ↓
CPU.tick() × 267,000 cycles/frame
    ↓
Writes to PORTB/PORTC/PORTD
    ↓
Write hooks → PinManager.updatePort()
    ↓
PinManager notifies callbacks
    ↓
Components update visual state

Key Components

Frontend

1. Stores (Zustand)

• useEditorStore.ts

  • code: Current source code
  • theme: Editor theme (dark/light)
  • setCode(): Update code

• useSimulatorStore.ts

  • running: Simulation state
  • compiledHex: Compiled hex file
  • components: List of electronic components
  • setCompiledHex(): Save hex
  • updateComponentState(): Update LED/component

2. UI Components

• CodeEditor.tsx

  • Monaco Editor wrapper
  • C++ syntax highlighting
  • Auto-completion

• EditorToolbar.tsx

  • Buttons: Compile, Run, Stop
  • Compilation state handling
  • Error/success messages

• SimulatorCanvas.tsx

  • Renders Arduino Uno
  • Renders components (LEDs)
  • Simulation loop

3. Wokwi Component Wrappers

• LED.tsx

  • React wrapper for <wokwi-led>
  • Props: color, value, x, y

• ArduinoUno.tsx

  • React wrapper for <wokwi-arduino-uno>
  • Internal LED control (pin 13)

• Resistor.tsx

  • React wrapper for <wokwi-resistor>
  • Props: value (ohms)

• Pushbutton.tsx

  • React wrapper for <wokwi-pushbutton>
  • Events: onPress, onRelease

Backend

1. API Routes

• compile.py
  • POST /api/compile: Compile code
  • GET /api/compile/boards: List boards

2. Services

• arduino_cli.py
  • compile(): Compile sketch with arduino-cli
  • list_boards(): Get available boards
  • Temporary directory management

Wokwi Libraries (Cloned Locally)

1. wokwi-elements

• Location: wokwi-libs/wokwi-elements/
• Build: dist/esm/ and dist/cjs/
• Components: 50+ electronic elements
• Technology: Lit (Web Components)

2. avr8js

• Location: wokwi-libs/avr8js/
• Build: dist/esm/ and dist/cjs/
• Functionality: Complete ATmega328p emulator
• Supports: CPU, Timers, USART, GPIO, ADC, etc.

3. rp2040js

• Location: wokwi-libs/rp2040js/
• Future use: Raspberry Pi Pico support

Vite Integration

Alias Configuration

// vite.config.ts
resolve: {
  alias: {
    'avr8js': path.resolve(__dirname, '../wokwi-libs/avr8js/dist/esm'),
    '@wokwi/elements': path.resolve(__dirname, '../wokwi-libs/wokwi-elements/dist/esm'),
  },
}

This allows:

• Use local repos instead of npm
• Easy updates with git pull
• Modify source code if needed

Technology Stack

Frontend

Technology	Version	Purpose
React	19.2	UI framework
Vite	7.3	Build tool & dev server
TypeScript	5.9	Static typing
Monaco Editor	4.7	Code editor (VSCode)
Zustand	5.0	State management
Axios	1.13	HTTP client
wokwi-elements	1.9.2	Electronic components
avr8js	0.21.0	AVR8 emulator

Backend

Technology	Version	Purpose
Python	3.12+	Runtime
FastAPI	0.115	Web framework
Uvicorn	0.32	ASGI server
SQLAlchemy	2.0	ORM (future)
aiosqlite	0.20	Async DB (future)

External Tools

Tool	Purpose
arduino-cli	Arduino compiler
Git	Version control for Wokwi libs

Architecture Advantages

✅ Separation of Concerns

• Frontend: UI, UX, visualization
• Backend: Compilation, business logic
• Wokwi Libs: Emulation and components (maintained by Wokwi)

✅ Wokwi Compatibility

• Official repositories = same functionality
• Automatic updates with git pull
• New components available immediately

✅ Scalability

• Frontend can easily add more components
• Backend can add more endpoints (projects, sensors)
• Wokwi libs update independently

✅ Local Development

• No internet required to work
• Local compilation with arduino-cli
• Local database (SQLite)

Upcoming Improvements

Phase 2: Real Emulation (avr8js)

[ ] Implement AVRSimulator.ts
[ ] Intel HEX file parser
[ ] PinManager with write hooks
[ ] Integrate CPU execution loop
[ ] Map Arduino pins to components

Phase 3: More Components

[ ] Integrate more wokwi-elements
[ ] Buttons, potentiometers
[ ] Sensors (DHT22, HC-SR04)
[ ] Displays (LCD, 7-segment)

Phase 4: Persistence

[ ] SQLite database
[ ] SQLAlchemy models
[ ] Project CRUD
[ ] Save circuits as JSON

Phase 5: Advanced Features

[ ] Serial Monitor
[ ] Visual wiring (drag & drop)
[ ] Multiple boards (Mega, Nano, ESP32)
[ ] Export to Wokwi.com

References

• Wokwi Elements Repo
• AVR8js Repo
• Wokwi Simulator
• Arduino CLI
• FastAPI Docs
• Vite Docs