velxio/test/test_circuit/plan/phase_0_scope.md

30 lines
1.7 KiB
Markdown
Raw Normal View History

feat: electrical simulation via ngspice-WASM (eecircuit-engine) Adds full SPICE-accurate electrical simulation to Velxio, behind a lazy- loaded ⚡ toolbar toggle. Arduino / ESP32 / RP2040 sketches now co-simulate with real analog behaviour: correct voltages on wires, real I–V curves on LEDs, working potentiometers, NTC thermistors read by analogRead(), PWM driving RC filters, transistors, op-amps, diodes, MOSFETs, etc. Engine: eecircuit-engine (ngspice compiled to WebAssembly). Main bundle stays at 2.4 MB; the 20 MB SPICE chunk only loads when the user activates electrical mode. Disabled at build time via VITE_ELECTRICAL_SIM=false. Frontend additions: - simulation/spice/: SpiceEngine wrapper + lazy entry, NetlistBuilder with UnionFind over wires, componentToSpice mapping (24 metadataIds incl. real part numbers: 2N2222, 2N3055, BC547, IRF540, 2N7000, 1N4148, 1N4007, 1N4733, LEDs, NTC, op-amp ideal), CircuitScheduler with debounced coalescing, AVRSpiceBridge for quasi-static co-simulation. - store/useElectricalStore: Zustand slice, feature-flag aware. - components/analog-ui/: ⚡ toolbar toggle + SVG voltage overlay. - components/components-instruments/: Voltmeter, Ammeter probes. - 62 tests (spice-*, netlist-builder, component-to-spice, instruments). Sandbox (test/test_circuit/): 47-test validation sandbox that proved the approach (hand-rolled MNA baseline + ngspice pipeline) before porting to the app. Kept as reference. Docs: docs/wiki/circuit-emulation-*.md (13 engineering pages covering architecture, solvers, components, AVR bridge, gotchas, performance, integration plan, API reference, appendix) + electrical-simulation- user-guide.md (end-user facing). Reference plan: test/test_circuit/plan/phase_8_velxio_implementation.md Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 19:11:54 +07:00
# Fase 0 — Alcance de la campaña
## Objetivo
Probar que podemos emular circuitos completos (analógicos + digitales + Arduino) en JavaScript puro, validando el enfoque antes de integrarlo en Velxio. El plan1.md propone usar ngspice-WASM (40 MB); esta campaña explora una alternativa **nativa JS** más ligera.
## No es objetivo
- Producir código listo para producción (es sandbox de pruebas).
- Reemplazar a ngspice en precisión numérica para circuitos analógicos complejos.
- Cubrir todos los componentes de wokwi-elements.
## Éxito =
1. Solver DC (MNA) resuelve redes con R, V, I, diodo, LED, termistor, potenciómetro con error < 1 % vs valor analítico conocido.
2. Solver transitorio resuelve RC charging, filtro pasa-bajos con error < 5 % vs solución analítica en t = τ.
3. Integración con `avr8js` (igual que Velxio) ejecuta una .hex real y el solver responde al estado de pines en cada frame.
4. Caso end-to-end: potenciómetro → `analogRead(A0)``analogWrite(9, val/4)` → brillo de LED varía monótonamente con la posición del potenciómetro.
5. Caso end-to-end: termistor NTC + divisor → lectura ADC corresponde a una temperatura esperada vía Steinhart-Hart.
## Riesgos / supuestos
- **avr-gcc no instalado** — los sketches se ensamblan a mano o se usa HEX pre-compilada cometida (pequeña).
- **Precisión numérica** — MNA-DC con Newton-Raphson para diodos puede no converger en topologías patológicas. Aceptamos fallos y los documentamos.
- **Co-simulación AVR ↔ circuito** — se hace en modo cuasi-estático (solver recalcula cuando cambian pines o cada N ms), no ciclo a ciclo.
## Plazo
Sesión única. Todo código generado bajo `test/test_circuit/`.