322 lines
12 KiB
Markdown
322 lines
12 KiB
Markdown
# Arquitectura del Proyecto - Arduino Emulator
|
||
|
||
## Visión General
|
||
|
||
Este proyecto es un emulador de Arduino que funciona completamente local, utilizando los repositorios oficiales de Wokwi para máxima compatibilidad.
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ USUARIO (Navegador) │
|
||
│ http://localhost:5173 │
|
||
└──────────────────────────┬──────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ FRONTEND (React + Vite) │
|
||
│ │
|
||
│ ┌────────────────┐ ┌──────────────────┐ ┌─────────────┐ │
|
||
│ │ Monaco Editor │ │ Zustand Store │ │ Simulator │ │
|
||
│ │ (Code Edit) │ │ (State Mgmt) │ │ Canvas │ │
|
||
│ └────────────────┘ └──────────────────┘ └─────────────┘ │
|
||
│ │ │ │ │
|
||
│ └───────────────────┴──────────────────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌──────────────────────────────────────────────────────┐ │
|
||
│ │ Wokwi Components Integration │ │
|
||
│ │ (wokwi-elements + avr8js desde repos locales) │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
└──────────────────────────┬──────────────────────────────────┘
|
||
│ HTTP (axios)
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ BACKEND (FastAPI + Python) │
|
||
│ http://localhost:8000 │
|
||
│ │
|
||
│ ┌─────────────────────────────────────────────────────┐ │
|
||
│ │ POST /api/compile │ │
|
||
│ │ - Recibe código Arduino (.ino) │ │
|
||
│ │ - Compila con arduino-cli │ │
|
||
│ │ - Retorna archivo .hex │ │
|
||
│ └─────────────────────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌─────────────────────────────────────────────────────┐ │
|
||
│ │ Arduino CLI Service │ │
|
||
│ │ (Invoca arduino-cli como subprocess) │ │
|
||
│ └─────────────────────────────────────────────────────┘ │
|
||
└──────────────────────────┬──────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌──────────────────────┐
|
||
│ arduino-cli │
|
||
│ (Sistema local) │
|
||
└──────────────────────┘
|
||
```
|
||
|
||
## Flujo de Datos: Compilación y Simulación
|
||
|
||
### 1. Edición de Código
|
||
```
|
||
Usuario escribe código
|
||
↓
|
||
Monaco Editor
|
||
↓
|
||
Zustand (useEditorStore)
|
||
↓
|
||
Estado: code
|
||
```
|
||
|
||
### 2. Compilación
|
||
```
|
||
Click en "Compile"
|
||
↓
|
||
EditorToolbar.tsx → compileCode()
|
||
↓
|
||
Axios POST → http://localhost:8000/api/compile
|
||
↓
|
||
Backend: ArduinoCLIService.compile()
|
||
↓
|
||
arduino-cli compile --fqbn arduino:avr:uno
|
||
↓
|
||
Genera archivo .hex en directorio temporal
|
||
↓
|
||
Backend lee .hex y retorna contenido
|
||
↓
|
||
Frontend: useSimulatorStore.setCompiledHex()
|
||
```
|
||
|
||
### 3. Simulación (Actualmente simplificada)
|
||
```
|
||
Click en "Run"
|
||
↓
|
||
useSimulatorStore.setRunning(true)
|
||
↓
|
||
SimulatorCanvas: useEffect detecta running=true
|
||
↓
|
||
setInterval cada 1000ms
|
||
↓
|
||
updateComponentState('led-builtin', !state)
|
||
↓
|
||
wokwi-led component actualiza visualmente
|
||
```
|
||
|
||
### 4. Simulación Real (Próximamente con avr8js)
|
||
```
|
||
Archivo .hex compilado
|
||
↓
|
||
AVRSimulator.loadHex(hex)
|
||
↓
|
||
hexParser → Uint16Array (program memory)
|
||
↓
|
||
CPU = new CPU(program)
|
||
↓
|
||
Click "Run" → AVRSimulator.start()
|
||
↓
|
||
requestAnimationFrame loop
|
||
↓
|
||
CPU.tick() × 267,000 cycles/frame
|
||
↓
|
||
Escribe en PORTB/PORTC/PORTD
|
||
↓
|
||
Write hooks → PinManager.updatePort()
|
||
↓
|
||
PinManager notifica callbacks
|
||
↓
|
||
Componentes actualizan estado visual
|
||
```
|
||
|
||
## Componentes Clave
|
||
|
||
### Frontend
|
||
|
||
#### 1. Stores (Zustand)
|
||
- **[useEditorStore.ts](frontend/src/store/useEditorStore.ts)**
|
||
- `code`: Código fuente actual
|
||
- `theme`: Tema del editor (dark/light)
|
||
- `setCode()`: Actualizar código
|
||
|
||
- **[useSimulatorStore.ts](frontend/src/store/useSimulatorStore.ts)**
|
||
- `running`: Estado de simulación
|
||
- `compiledHex`: Archivo hex compilado
|
||
- `components`: Lista de componentes electrónicos
|
||
- `setCompiledHex()`: Guardar hex
|
||
- `updateComponentState()`: Actualizar LED/componente
|
||
|
||
#### 2. Componentes UI
|
||
- **[CodeEditor.tsx](frontend/src/components/editor/CodeEditor.tsx)**
|
||
- Wrapper de Monaco Editor
|
||
- Syntax highlighting C++
|
||
- Auto-completado
|
||
|
||
- **[EditorToolbar.tsx](frontend/src/components/editor/EditorToolbar.tsx)**
|
||
- Botones: Compile, Run, Stop
|
||
- Manejo de estados de compilación
|
||
- Mensajes de error/éxito
|
||
|
||
- **[SimulatorCanvas.tsx](frontend/src/components/simulator/SimulatorCanvas.tsx)**
|
||
- Renderiza Arduino Uno
|
||
- Renderiza componentes (LEDs)
|
||
- Loop de simulación
|
||
|
||
#### 3. Wokwi Components Wrappers
|
||
- **[LED.tsx](frontend/src/components/components-wokwi/LED.tsx)**
|
||
- Wrapper React para `<wokwi-led>`
|
||
- Props: color, value, x, y
|
||
|
||
- **[ArduinoUno.tsx](frontend/src/components/components-wokwi/ArduinoUno.tsx)**
|
||
- Wrapper React para `<wokwi-arduino-uno>`
|
||
- Control de LED interno (pin 13)
|
||
|
||
- **[Resistor.tsx](frontend/src/components/components-wokwi/Resistor.tsx)**
|
||
- Wrapper React para `<wokwi-resistor>`
|
||
- Props: value (ohms)
|
||
|
||
- **[Pushbutton.tsx](frontend/src/components/components-wokwi/Pushbutton.tsx)**
|
||
- Wrapper React para `<wokwi-pushbutton>`
|
||
- Events: onPress, onRelease
|
||
|
||
### Backend
|
||
|
||
#### 1. API Routes
|
||
- **[compile.py](backend/app/api/routes/compile.py)**
|
||
- `POST /api/compile`: Compilar código
|
||
- `GET /api/compile/boards`: Listar placas
|
||
|
||
#### 2. Services
|
||
- **[arduino_cli.py](backend/app/services/arduino_cli.py)**
|
||
- `compile()`: Compilar sketch con arduino-cli
|
||
- `list_boards()`: Obtener placas disponibles
|
||
- Manejo de directorios temporales
|
||
|
||
### Wokwi Libraries (Clonadas Localmente)
|
||
|
||
#### 1. wokwi-elements
|
||
- **Ubicación**: `wokwi-libs/wokwi-elements/`
|
||
- **Build**: `dist/esm/` y `dist/cjs/`
|
||
- **Componentes**: 50+ elementos electrónicos
|
||
- **Tecnología**: Lit (Web Components)
|
||
|
||
#### 2. avr8js
|
||
- **Ubicación**: `wokwi-libs/avr8js/`
|
||
- **Build**: `dist/esm/` y `dist/cjs/`
|
||
- **Funcionalidad**: Emulador completo de ATmega328p
|
||
- **Soporta**: CPU, Timers, USART, GPIO, ADC, etc.
|
||
|
||
#### 3. rp2040js
|
||
- **Ubicación**: `wokwi-libs/rp2040js/`
|
||
- **Uso futuro**: Soporte para Raspberry Pi Pico
|
||
|
||
## Integración con Vite
|
||
|
||
### 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'),
|
||
},
|
||
}
|
||
```
|
||
|
||
Esto permite:
|
||
- Usar repos locales en lugar de npm
|
||
- Actualizar fácilmente con `git pull`
|
||
- Modificar código fuente si es necesario
|
||
|
||
## Stack Tecnológico
|
||
|
||
### Frontend
|
||
| Tecnología | Versión | Propósito |
|
||
|------------|---------|-----------|
|
||
| React | 19.2 | Framework UI |
|
||
| Vite | 7.3 | Build tool & dev server |
|
||
| TypeScript | 5.9 | Tipado estático |
|
||
| Monaco Editor | 4.7 | Editor de código (VSCode) |
|
||
| Zustand | 5.0 | State management |
|
||
| Axios | 1.13 | HTTP client |
|
||
| wokwi-elements | 1.9.2 | Componentes electrónicos |
|
||
| avr8js | 0.21.0 | Emulador AVR8 |
|
||
|
||
### Backend
|
||
| Tecnología | Versión | Propósito |
|
||
|------------|---------|-----------|
|
||
| Python | 3.12+ | Runtime |
|
||
| FastAPI | 0.115 | Web framework |
|
||
| Uvicorn | 0.32 | ASGI server |
|
||
| SQLAlchemy | 2.0 | ORM (futuro) |
|
||
| aiosqlite | 0.20 | DB async (futuro) |
|
||
|
||
### Herramientas Externas
|
||
| Herramienta | Propósito |
|
||
|-------------|-----------|
|
||
| arduino-cli | Compilador de Arduino |
|
||
| Git | Control de versiones de Wokwi libs |
|
||
|
||
## Ventajas de la Arquitectura
|
||
|
||
### ✅ Separación de Responsabilidades
|
||
- **Frontend**: UI, UX, visualización
|
||
- **Backend**: Compilación, lógica de negocio
|
||
- **Wokwi Libs**: Emulación y componentes (mantenido por Wokwi)
|
||
|
||
### ✅ Compatibilidad con Wokwi
|
||
- Repositorios oficiales = misma funcionalidad
|
||
- Actualizaciones automáticas con `git pull`
|
||
- Nuevos componentes disponibles inmediatamente
|
||
|
||
### ✅ Escalabilidad
|
||
- Frontend puede agregar más componentes fácilmente
|
||
- Backend puede agregar más endpoints (proyectos, sensores)
|
||
- Wokwi libs se actualizan independientemente
|
||
|
||
### ✅ Desarrollo Local
|
||
- No requiere internet para funcionar
|
||
- Compilación local con arduino-cli
|
||
- Base de datos local (SQLite)
|
||
|
||
## Próximas Mejoras
|
||
|
||
### Fase 2: Emulación Real (avr8js)
|
||
```
|
||
[ ] Implementar AVRSimulator.ts
|
||
[ ] Parser de archivos Intel HEX
|
||
[ ] PinManager con write hooks
|
||
[ ] Integrar CPU execution loop
|
||
[ ] Mapear pines Arduino a componentes
|
||
```
|
||
|
||
### Fase 3: Más Componentes
|
||
```
|
||
[ ] Integrar más wokwi-elements
|
||
[ ] Botones, potenciómetros
|
||
[ ] Sensores (DHT22, HC-SR04)
|
||
[ ] Pantallas (LCD, 7-segment)
|
||
```
|
||
|
||
### Fase 4: Persistencia
|
||
```
|
||
[ ] Base de datos SQLite
|
||
[ ] Modelos SQLAlchemy
|
||
[ ] CRUD de proyectos
|
||
[ ] Guardar circuitos como JSON
|
||
```
|
||
|
||
### Fase 5: Features Avanzadas
|
||
```
|
||
[ ] Serial Monitor
|
||
[ ] Wiring visual (drag & drop)
|
||
[ ] Múltiples placas (Mega, Nano, ESP32)
|
||
[ ] Exportar a Wokwi.com
|
||
```
|
||
|
||
## Referencias
|
||
|
||
- [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/)
|