11 KiB

Raw Blame History

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:

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:

{
  "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)

# Script para actualizar todos los repositorios
update-wokwi-libs.bat

Opción 2: Actualizar manualmente cada repositorio

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

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:

cd frontend
npx tsx ../scripts/generate-component-metadata.ts

Script de Actualización Automática

El script update-wokwi-libs.bat facilita las actualizaciones:

@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:

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)

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)

// 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

Actualización Fácil: Un simple git pull + rebuild te da las últimas mejoras
Compatible con Wokwi: Usas exactamente el mismo código que Wokwi.com
Descubrimiento Automático: Nuevos componentes aparecen automáticamente tras regenerar metadata
Control de Versiones: Puedes hacer checkout a versiones específicas
Desarrollo Flexible: Código fuente disponible para debugging y modificaciones
Sin Dependencia de npm: No dependes de que publiquen actualizaciones en npm
100% Offline: Funciona completamente sin internet después de la configuración inicial

⚠️ Consideraciones

Espacio en Disco: Los repositorios clonados ocupan más espacio (~200MB)
Compilación: Debes compilar los repositorios después de actualizarlos
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:

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:

cd wokwi-libs/avr8js
npm install
npm run build

Los componentes no se muestran en el picker

Regenera la metadata de componentes:

cd frontend
npx tsx ../scripts/generate-component-metadata.ts

Nuevo componente de wokwi-elements no aparece

Actualiza wokwi-elements: cd wokwi-libs/wokwi-elements && git pull && npm run build
Regenera metadata: cd frontend && npx tsx ../scripts/generate-component-metadata.ts
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
AVR8js Repository
Wokwi Simulator
Lit Documentation — Framework usado por wokwi-elements
Web Components Guide

11 KiB Raw Blame History Unescape Escape