322 lines
11 KiB
Markdown
322 lines
11 KiB
Markdown
# 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](frontend/src/store/useEditorStore.ts)**
|
||
- `code`: Current source code
|
||
- `theme`: Editor theme (dark/light)
|
||
- `setCode()`: Update code
|
||
|
||
- **[useSimulatorStore.ts](frontend/src/store/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](frontend/src/components/editor/CodeEditor.tsx)**
|
||
- Monaco Editor wrapper
|
||
- C++ syntax highlighting
|
||
- Auto-completion
|
||
|
||
- **[EditorToolbar.tsx](frontend/src/components/editor/EditorToolbar.tsx)**
|
||
- Buttons: Compile, Run, Stop
|
||
- Compilation state handling
|
||
- Error/success messages
|
||
|
||
- **[SimulatorCanvas.tsx](frontend/src/components/simulator/SimulatorCanvas.tsx)**
|
||
- Renders Arduino Uno
|
||
- Renders components (LEDs)
|
||
- Simulation loop
|
||
|
||
#### 3. Wokwi Component Wrappers
|
||
- **[LED.tsx](frontend/src/components/components-wokwi/LED.tsx)**
|
||
- React wrapper for `<wokwi-led>`
|
||
- Props: color, value, x, y
|
||
|
||
- **[ArduinoUno.tsx](frontend/src/components/components-wokwi/ArduinoUno.tsx)**
|
||
- React wrapper for `<wokwi-arduino-uno>`
|
||
- Internal LED control (pin 13)
|
||
|
||
- **[Resistor.tsx](frontend/src/components/components-wokwi/Resistor.tsx)**
|
||
- React wrapper for `<wokwi-resistor>`
|
||
- Props: value (ohms)
|
||
|
||
- **[Pushbutton.tsx](frontend/src/components/components-wokwi/Pushbutton.tsx)**
|
||
- React wrapper for `<wokwi-pushbutton>`
|
||
- Events: onPress, onRelease
|
||
|
||
### Backend
|
||
|
||
#### 1. API Routes
|
||
- **[compile.py](backend/app/api/routes/compile.py)**
|
||
- `POST /api/compile`: Compile code
|
||
- `GET /api/compile/boards`: List boards
|
||
|
||
#### 2. Services
|
||
- **[arduino_cli.py](backend/app/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
|
||
```typescript
|
||
// 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](https://github.com/wokwi/wokwi-elements)
|
||
- [AVR8js Repo](https://github.com/wokwi/avr8js)
|
||
- [Wokwi Simulator](https://wokwi.com)
|
||
- [Arduino CLI](https://arduino.github.io/arduino-cli/)
|
||
- [FastAPI Docs](https://fastapi.tiangolo.com/)
|
||
- [Vite Docs](https://vitejs.dev/)
|