367 lines
11 KiB
Markdown
367 lines
11 KiB
Markdown
# Wokwi Libraries Integration
|
||
|
||
Este proyecto utiliza los repositorios oficiales de Wokwi clonados localmente, lo que permite mantenerlos actualizados y compatibles con las últimas versiones. Los repositorios locales alimentan tanto la emulación AVR como el sistema dinámico de componentes con 48+ elementos electrónicos.
|
||
|
||
## Repositorios Clonados
|
||
|
||
### 📦 wokwi-elements
|
||
- **Ubicación**: `wokwi-libs/wokwi-elements/`
|
||
- **Descripción**: Web Components (Lit) para 48+ elementos electrónicos (LEDs, resistencias, botones, LCDs, sensores, etc.)
|
||
- **Repositorio**: https://github.com/wokwi/wokwi-elements
|
||
- **Licencia**: MIT
|
||
- **Uso actual**: Renderizado visual de todos los componentes en el canvas de simulación. Un script de generación de metadata (`scripts/generate-component-metadata.ts`) parsea el código fuente TypeScript para descubrir automáticamente todos los componentes, sus propiedades y pines.
|
||
|
||
### 🎮 avr8js
|
||
- **Ubicación**: `wokwi-libs/avr8js/`
|
||
- **Descripción**: Emulador completo de microcontroladores AVR8 (ATmega328p) en JavaScript
|
||
- **Repositorio**: https://github.com/wokwi/avr8js
|
||
- **Licencia**: MIT
|
||
- **Uso actual**: Emulación real del CPU a 16MHz, con Timer0/1/2, USART, ADC, y puertos GPIO (PORTB/C/D). Ejecuta ~267,000 ciclos por frame a ~60fps.
|
||
|
||
### 🚀 rp2040js
|
||
- **Ubicación**: `wokwi-libs/rp2040js/`
|
||
- **Descripción**: Emulador de Raspberry Pi Pico (RP2040) en JavaScript
|
||
- **Repositorio**: https://github.com/wokwi/rp2040js
|
||
- **Licencia**: MIT
|
||
- **Uso**: Clonado para futuro soporte de Raspberry Pi Pico
|
||
|
||
### 📝 wokwi-features
|
||
- **Ubicación**: `wokwi-libs/wokwi-features/`
|
||
- **Descripción**: Documentación y tracking de features de Wokwi
|
||
- **Repositorio**: https://github.com/wokwi/wokwi-features
|
||
|
||
## Configuración del Proyecto
|
||
|
||
### Frontend (Vite)
|
||
|
||
El archivo `frontend/vite.config.ts` está configurado para usar los repositorios locales mediante aliases:
|
||
|
||
```typescript
|
||
resolve: {
|
||
alias: {
|
||
'avr8js': path.resolve(__dirname, '../wokwi-libs/avr8js/dist/esm'),
|
||
'@wokwi/elements': path.resolve(__dirname, '../wokwi-libs/wokwi-elements/dist/esm'),
|
||
},
|
||
},
|
||
optimizeDeps: {
|
||
include: ['avr8js', '@wokwi/elements'],
|
||
}
|
||
```
|
||
|
||
El archivo `frontend/package.json` referencia los paquetes locales:
|
||
|
||
```json
|
||
{
|
||
"dependencies": {
|
||
"@wokwi/elements": "file:../wokwi-libs/wokwi-elements",
|
||
"avr8js": "file:../wokwi-libs/avr8js"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Generación Automática de Metadata
|
||
|
||
El script `scripts/generate-component-metadata.ts` parsea el código fuente de wokwi-elements usando AST de TypeScript para extraer:
|
||
- Nombre del tag (`@customElement('wokwi-led')` → `wokwi-led`)
|
||
- Propiedades (`@property()` decorators → tipo, valor por defecto)
|
||
- Cantidad de pines
|
||
- Categoría, descripción y tags
|
||
|
||
El resultado se almacena en `frontend/public/components-metadata.json` y es consumido por el `ComponentRegistry` en tiempo de ejecución.
|
||
|
||
## Actualizar las Librerías de Wokwi
|
||
|
||
Para mantener tu proyecto actualizado con las últimas versiones de Wokwi:
|
||
|
||
### Opción 1: Actualizar todas las librerías (Recomendado)
|
||
|
||
```bash
|
||
# Script para actualizar todos los repositorios
|
||
update-wokwi-libs.bat
|
||
```
|
||
|
||
### Opción 2: Actualizar manualmente cada repositorio
|
||
|
||
```bash
|
||
cd wokwi-libs
|
||
|
||
# Actualizar wokwi-elements
|
||
cd wokwi-elements
|
||
git pull origin main
|
||
npm install
|
||
npm run build
|
||
|
||
# Actualizar avr8js
|
||
cd ../avr8js
|
||
git pull origin main
|
||
npm install
|
||
npm run build
|
||
|
||
# Actualizar rp2040js
|
||
cd ../rp2040js
|
||
git pull origin main
|
||
npm install
|
||
npm run build
|
||
```
|
||
|
||
### Opción 3: Actualizar a una versión específica
|
||
|
||
```bash
|
||
cd wokwi-libs/wokwi-elements
|
||
|
||
# Ver versiones disponibles
|
||
git tag -l
|
||
|
||
# Cambiar a una versión específica
|
||
git checkout v1.9.2
|
||
|
||
# Recompilar
|
||
npm install
|
||
npm run build
|
||
```
|
||
|
||
### Después de Actualizar wokwi-elements
|
||
|
||
Si actualizaste wokwi-elements, regenera la metadata de componentes para que nuevos componentes aparezcan en la UI:
|
||
|
||
```bash
|
||
cd frontend
|
||
npx tsx ../scripts/generate-component-metadata.ts
|
||
```
|
||
|
||
## Script de Actualización Automática
|
||
|
||
El script `update-wokwi-libs.bat` facilita las actualizaciones:
|
||
|
||
```batch
|
||
@echo off
|
||
echo ========================================
|
||
echo Actualizando Wokwi Libraries
|
||
echo ========================================
|
||
|
||
cd wokwi-libs
|
||
|
||
echo [1/3] Actualizando wokwi-elements...
|
||
cd wokwi-elements
|
||
git pull origin main
|
||
npm install
|
||
npm run build
|
||
cd ..
|
||
|
||
echo [2/3] Actualizando avr8js...
|
||
cd avr8js
|
||
git pull origin main
|
||
npm install
|
||
npm run build
|
||
cd ..
|
||
|
||
echo [3/3] Actualizando rp2040js...
|
||
cd rp2040js
|
||
git pull origin main
|
||
npm install
|
||
npm run build
|
||
cd ..
|
||
|
||
echo ========================================
|
||
echo Actualizacion completada!
|
||
echo ========================================
|
||
pause
|
||
```
|
||
|
||
## Cómo Se Usan las Librerías
|
||
|
||
### avr8js — Emulación AVR
|
||
|
||
El `AVRSimulator` (`frontend/src/simulation/AVRSimulator.ts`) usa avr8js para crear:
|
||
|
||
```typescript
|
||
import { CPU, avrInstruction, AVRTimer, AVRUSART, AVRADC, AVRIOPort } from 'avr8js';
|
||
|
||
// CPU ATmega328p a 16MHz
|
||
const cpu = new CPU(programMemory);
|
||
|
||
// Periféricos
|
||
const timer0 = new AVRTimer(cpu, timer0Config);
|
||
const timer1 = new AVRTimer(cpu, timer1Config);
|
||
const timer2 = new AVRTimer(cpu, timer2Config);
|
||
const usart = new AVRUSART(cpu, usart0Config, CLOCK);
|
||
const adc = new AVRADC(cpu, adcConfig);
|
||
const portB = new AVRIOPort(cpu, portBConfig); // pins 8-13
|
||
const portC = new AVRIOPort(cpu, portCConfig); // A0-A5
|
||
const portD = new AVRIOPort(cpu, portDConfig); // pins 0-7
|
||
|
||
// Loop de simulación (~60fps)
|
||
function runFrame() {
|
||
const cyclesToRun = Math.floor(267000 * speed);
|
||
for (let i = 0; i < cyclesToRun; i++) {
|
||
avrInstruction(cpu); // Ejecuta instrucción AVR
|
||
cpu.tick(); // Actualiza periféricos
|
||
}
|
||
requestAnimationFrame(runFrame);
|
||
}
|
||
```
|
||
|
||
### wokwi-elements — Componentes Visuales
|
||
|
||
Los componentes se renderizan de dos formas:
|
||
|
||
**1. DynamicComponent (sistema actual — 48 componentes)**
|
||
|
||
```typescript
|
||
import { ComponentRegistry } from './services/ComponentRegistry';
|
||
|
||
// Carga metadata desde /components-metadata.json
|
||
const registry = ComponentRegistry.getInstance();
|
||
const metadata = registry.getById('led');
|
||
|
||
// DynamicComponent crea el web component dinámicamente
|
||
// document.createElement(metadata.tagName) → <wokwi-led>
|
||
// Sincroniza propiedades React → web component
|
||
// Extrae pinInfo del DOM para wire connections
|
||
```
|
||
|
||
**2. React wrappers legacy (5 componentes)**
|
||
|
||
```tsx
|
||
// ArduinoUno.tsx — sigue en uso activo para el board principal
|
||
<wokwi-arduino-uno ref={ref} led13={led13} />
|
||
```
|
||
|
||
### PartSimulationRegistry — Comportamientos de Simulación
|
||
|
||
16 partes tienen lógica de simulación registrada que conecta los web components con el emulador AVR:
|
||
|
||
| Parte | Tipo | Comportamiento |
|
||
|-------|------|----------------|
|
||
| `led` | Output | Pin state → `element.value` |
|
||
| `rgb-led` | Output | Digital + PWM en R/G/B |
|
||
| `led-bar-graph` | Output | 10 LEDs independientes |
|
||
| `7segment` | Output | 8 segmentos (A-G + DP) |
|
||
| `pushbutton` | Input | Press/release → `setPinState()` |
|
||
| `pushbutton-6mm` | Input | Mismo que pushbutton |
|
||
| `slide-switch` | Input | Change event → pin state |
|
||
| `dip-switch-8` | Input | 8 switches independientes |
|
||
| `potentiometer` | Input | Valor → voltaje ADC |
|
||
| `slide-potentiometer` | Input | Misma lógica por SIG/OUT |
|
||
| `photoresistor-sensor` | Input/Output | Voltaje analógico + LED digital |
|
||
| `analog-joystick` | Input | VRX/VRY (ADC) + SW (digital) |
|
||
| `servo` | Output | Registros OCR1A/ICR1 → ángulo 0-180° |
|
||
| `buzzer` | Output | Web Audio API + Timer2 |
|
||
| `lcd1602` | Output | Protocolo HD44780 4-bit completo (16×2) |
|
||
| `lcd2004` | Output | Protocolo HD44780 4-bit completo (20×4) |
|
||
|
||
## Componentes Wokwi Disponibles (48)
|
||
|
||
### Boards (4)
|
||
- `wokwi-arduino-uno` — Arduino Uno R3
|
||
- `wokwi-arduino-mega` — Arduino Mega 2560
|
||
- `wokwi-arduino-nano` — Arduino Nano
|
||
- `wokwi-esp32-devkit-v1` — ESP32 DevKit v1
|
||
|
||
### Sensors (6)
|
||
- `wokwi-dht22` — Temperatura y humedad
|
||
- `wokwi-hc-sr04` — Ultrasónico de distancia
|
||
- `wokwi-pir-motion-sensor` — Sensor de movimiento PIR
|
||
- `wokwi-photoresistor-sensor` — Fotoresistor (LDR)
|
||
- `wokwi-ntc-temperature-sensor` — Sensor NTC
|
||
- `wokwi-analog-joystick` — Joystick analógico
|
||
|
||
### Displays (3)
|
||
- `wokwi-lcd1602` — LCD 16x2 con protocolo HD44780
|
||
- `wokwi-lcd2004` — LCD 20x4 con protocolo HD44780
|
||
- `wokwi-7segment` — Display de 7 segmentos
|
||
|
||
### Input (5)
|
||
- `wokwi-pushbutton` — Botón pulsador
|
||
- `wokwi-pushbutton-6mm` — Botón 6mm
|
||
- `wokwi-slide-switch` — Interruptor deslizante
|
||
- `wokwi-dip-switch-8` — DIP switch de 8 posiciones
|
||
- `wokwi-potentiometer` — Potenciómetro
|
||
|
||
### Output (5)
|
||
- `wokwi-led` — LED de colores
|
||
- `wokwi-rgb-led` — LED RGB
|
||
- `wokwi-led-bar-graph` — Barra de LEDs (10)
|
||
- `wokwi-buzzer` — Buzzer piezoeléctrico
|
||
- `wokwi-neopixel` — LED RGB direccionable (WS2812)
|
||
|
||
### Motors (2)
|
||
- `wokwi-servo` — Servo motor
|
||
- `wokwi-stepper-motor` — Motor paso a paso
|
||
|
||
### Passive (4)
|
||
- `wokwi-resistor` — Resistencia con código de colores
|
||
- `wokwi-slide-potentiometer` — Potenciómetro deslizante
|
||
- `wokwi-led-ring` — Anillo de LEDs
|
||
- `wokwi-membrane-keypad` — Teclado matricial
|
||
|
||
### Other (19)
|
||
- Componentes variados incluyendo `wokwi-ir-receiver`, `wokwi-ds1307`, breadboards, etc.
|
||
|
||
## Ventajas de Este Enfoque
|
||
|
||
### ✅ Ventajas
|
||
|
||
1. **Actualización Fácil**: Un simple `git pull` + rebuild te da las últimas mejoras
|
||
2. **Compatible con Wokwi**: Usas exactamente el mismo código que Wokwi.com
|
||
3. **Descubrimiento Automático**: Nuevos componentes aparecen automáticamente tras regenerar metadata
|
||
4. **Control de Versiones**: Puedes hacer checkout a versiones específicas
|
||
5. **Desarrollo Flexible**: Código fuente disponible para debugging y modificaciones
|
||
6. **Sin Dependencia de npm**: No dependes de que publiquen actualizaciones en npm
|
||
7. **100% Offline**: Funciona completamente sin internet después de la configuración inicial
|
||
|
||
### ⚠️ Consideraciones
|
||
|
||
1. **Espacio en Disco**: Los repositorios clonados ocupan más espacio (~200MB)
|
||
2. **Compilación**: Debes compilar los repositorios después de actualizarlos
|
||
3. **Metadata**: Regenerar `components-metadata.json` después de actualizar wokwi-elements
|
||
|
||
## Troubleshooting
|
||
|
||
### Error: "Module not found: @wokwi/elements"
|
||
|
||
Asegúrate de que wokwi-elements esté compilado:
|
||
|
||
```bash
|
||
cd wokwi-libs/wokwi-elements
|
||
npm install
|
||
npm run build
|
||
```
|
||
|
||
### Error: "Cannot find module 'avr8js'"
|
||
|
||
Verifica que el alias en `vite.config.ts` esté correcto y que avr8js esté compilado:
|
||
|
||
```bash
|
||
cd wokwi-libs/avr8js
|
||
npm install
|
||
npm run build
|
||
```
|
||
|
||
### Los componentes no se muestran en el picker
|
||
|
||
Regenera la metadata de componentes:
|
||
|
||
```bash
|
||
cd frontend
|
||
npx tsx ../scripts/generate-component-metadata.ts
|
||
```
|
||
|
||
### Nuevo componente de wokwi-elements no aparece
|
||
|
||
1. Actualiza wokwi-elements: `cd wokwi-libs/wokwi-elements && git pull && npm run build`
|
||
2. Regenera metadata: `cd frontend && npx tsx ../scripts/generate-component-metadata.ts`
|
||
3. Si necesita simulación, registra su comportamiento en `frontend/src/simulation/parts/`
|
||
|
||
### Los componentes se ven pero no responden a la simulación
|
||
|
||
Verifica que el componente tenga lógica de simulación registrada en `PartSimulationRegistry` (archivos `BasicParts.ts` o `ComplexParts.ts`). Solo los 16 componentes registrados tienen comportamiento interactivo.
|
||
|
||
## Referencias
|
||
|
||
- [Wokwi Elements Documentation](https://elements.wokwi.com/)
|
||
- [AVR8js Repository](https://github.com/wokwi/avr8js)
|
||
- [Wokwi Simulator](https://wokwi.com)
|
||
- [Lit Documentation](https://lit.dev/) — Framework usado por wokwi-elements
|
||
- [Web Components Guide](https://developer.mozilla.org/en-US/docs/Web/Web_Components)
|