PitSimulator

PitSimulator es un prototipo de simulador visual de componentes electrónicos para experimentar con conexiones, pines y lógica básica sin necesidad de hardware físico.

Estructura general

• index.html: punto de entrada de la interfaz.
• js/simulator: lógica principal del motor de simulación, renderizado, gestión de componentes y cables.
• css: estilos del tablero, cuadrícula, paneles y componentes.
• components: definiciones de componentes en formato JSON y archivos auxiliares de hardware.
• server: puente QEMU (proceso Node aparte) -- lanza el firmware MicroPython real bajo emulación y lo conecta al frontend por WebSocket. Ver server/README.md.
• COMUNICACION_INALAMBRICA.md: guía para alumnos sobre ESP-NOW, WiFi/HTTP y BLE simulados (modo navegador) -- multi-ESP32, ejemplos de código listos para copiar.

Cómo agregar un componente nuevo

El motor consulta ComponentBehaviorRegistry (ver js/simulator/ComponentBehaviorRegistry.js) antes de decidir cómo evaluar la señal, dibujar el componente o armar su panel de propiedades. Esto significa que agregar un componente nuevo no requiere editar SignalEngine.js, Renderer.js ni PropertyPanel.js — solo se declaran archivos nuevos:

1. components/<tipo>/<tipo>.json — definición (pines, propiedades, categoría). Obligatorio.

2. components/<tipo>/<tipo>.svg — gráfico. Obligatorio, salvo que el componente se dibuje por código (ver usesCodeGraphic más abajo, como neopixel_matrix/max7219).

3. components/<tipo>/<tipo>.hal.py — driver MicroPython que corre dentro de QEMU y habla el protocolo por WebSocket (GPIO:, OLED:, PININFO:, etc. — ver QemuBridge.parseLine()). Opcional: solo hace falta si el componente necesita hardware simulado del lado del firmware (sensor, display, bus I2C propio, etc.).

4. components/<tipo>/<tipo>.behavior.js — opcional. Solo hace falta si el componente necesita algo más que "dibujar el .svg tal cual y mostrar el panel de propiedades genérico". Se auto-registra llamando a ComponentBehaviorRegistry.register(...), y app.js lo carga solo (fetch dinámico basado en manifest.json — un 404 acá es normal si el tipo no lo necesita). Forma:

   ComponentBehaviorRegistry.register("mi_tipo", {
     signal: {
       evaluate(component, engine) { /* reemplaza evaluateXxx() */ },
     },
     render: {
       usesCodeGraphic: false,                     // true = se dibuja por código, sin .svg
       tag(component, graphic, renderer) { /* decorar el .svg recién cargado */ },
       initialState(component, renderer) { /* estado apagado/default al crear */ },
     },
     propertyPanel: {
       render(component, panel) { /* panel.content, panel.simulator, panel._renderCommonProperties(component) */ },
     },
   });
   

   Dos tipos que comparten EXACTAMENTE el mismo comportamiento (ej. lcd16x2/lcd_16x2_i2c, keypad3x4/keypad4x4) pueden registrarse juntos: ComponentBehaviorRegistry.register(["tipoA", "tipoB"], behavior), o incluso desde un solo archivo físico (ver components/keypad4x4/keypad4x4.behavior.js — keypad3x4 no tiene archivo propio, comparte el registro del otro).

5. Una línea nueva en components/manifest.json ({ type, name, category }) para que aparezca en el Toolbox.

La mayoría de los sensores/actuadores simples (que no necesitan decorar su SVG ni tener un panel especial) no necesitan .behavior.js en absoluto — el motor cae solo en el comportamiento genérico (sin signal.evaluate propio, .svg sin decorar, panel _renderGeneric).

Otras recomendaciones:

• Mantener la lógica de simulación separada de la UI.
• Los cables deberían seguir un patrón de routing ortogonal y reutilizable para evitar que cada mejora introduzca inconsistencias visuales.

Tests de la lógica pura del simulador

Cubre las partes de SignalEngine, Utils y Component que no dependen del DOM, del navegador ni de QEMU — se pueden correr con Node solo, sin abrir index.html ni levantar server.js.

Cómo correrlos

npm test

(usa node --test, incluido en Node ≥ 18 — no hace falta instalar Jest, Mocha ni nada más)

Qué cubre hoy

• tests/signalEngine.test.js — getNet (BFS sobre cables + botones presionados), isKeyConnectedToHighDriver, isKeyConnectedToGnd, isComponentPowered, evaluateLed. Incluye un test que documenta a propósito un comportamiento no definido: dos drivers en conflicto sobre la misma net (cortocircuito real) hoy no se detecta. No es un bug — es una decisión de diseño pendiente, dejada visible para que no se cuele por sorpresa en un refactor futuro.
• tests/utils.test.js — snapToGrid (incluye test de regresión del bug de división por cero con gridSize=0 que ya está resuelto en el código real, para que no vuelva), computeElbow, normalizeHex, lightenColor, clamp, generateId.
• tests/component.test.js — getPinPosition con rotación, flip, y ambos combinados (es la matemática más fácil de romper sin darse cuenta en un refactor de Component.js, y no tenía ningún test). Incluye test de regresión del bug x=0 (|| vs ??) ya corregido en el código real.

lib/SignalEngineCore.js — por qué existe

Es una copia textual (sin reescribir ni una línea) de los métodos de SignalEngine.js que no tocan renderer/DOM. Se separó así por dos motivos:

1. Para poder testear el algoritmo de resolución de red (getNet) con Node puro, sin mockear todo un navegador.
2. Porque separar el motor de señales del renderizado es, de todas formas, uno de los refactors sugeridos para cuando el proyecto crezca (ver ComponentBehaviorRegistry en la conversación de diseño) — este archivo es, en chiquito, la prueba de que esa separación es viable sin romper nada: los 15 tests de signalEngine.test.js pasan exactamente igual con la lógica aislada del resto.

Importante: si SignalEngine.js cambia alguno de estos métodos en el código real, lib/SignalEngineCore.js hay que actualizarlo a mano para que siga siendo un espejo fiel — no está importado automáticamente del archivo real (para no arrastrar sus dependencias de window/DOM). El paso siguiente natural es que estos métodos vivan en su propio archivo sin mezcla de DOM en el proyecto real, y ahí lib/SignalEngineCore.js deja de hacer falta: se importa directo.

Qué falta cubrir (siguiente prioridad sugerida)

• evaluateL298n / _computeL298nMotorState (lógica de puente H, tiene varias combinaciones IN1/IN2/enable que se prestan a tests de tabla).
• isWiredToDeclaredPins (la validación de PININFO contra el cableado real).
• WireManager.movePointWithConstraint / Utils.buildOrthogonalPoints (geometría de ruteo de cables).