circuitsnap

Captúralo, simúlalo. Convierte un dibujo de circuito — una foto, un boceto o simplemente una descripción — en una simulación en vivo en Falstad's CircuitJS1.

Se distribuye como un servidor MCP (para que Claude y otros asistentes puedan construir circuitos), una CLI, y una librería.

$ circuitsnap build rc.json
https://www.falstad.com/circuit/circuitjs.html?ctz=CQAgjCAMB0l3BWcMBMcUHYMGZIA4UA2ATmIxAUgo...

$ 1 0.000005 10.20027730826997 50 5 50
v 128 64 192 64 0 0 40 5 0 0 0.5
r 384 64 448 64 0 10000
c 128 176 192 176 0 0.000001 0 0
...

Abre la URL y el circuito se ejecuta.

Por qué

Pedir a un modelo de lenguaje que escriba directamente el formato de archivo de CircuitJS1 no funciona. El formato es posicional e implacable — v 128 64 192 64 0 0 40 5 0 0 0.5 tiene seis parámetros finales cuyo orden, unidades y bits de bandera solo se pueden descubrir leyendo el código fuente Java del simulador. Una suposición incorrecta produce un circuito que se carga sin problemas y simula incorrectamente, que es el peor fallo posible: el usuario no puede notarlo.

circuitsnap traslada esa tarea a código probado. El modelo describe qué se conecta con qué; esta librería se encarga del formato, la geometría, el escape y la codificación.

Related MCP server: circuit-sim-mcp

Instalación

npm install -g circuitsnap

Como servidor MCP

{
  "mcpServers": {
    "circuitsnap": { "command": "npx", "args": ["-y", "circuitsnap-mcp"] }
  }
}

(circuitsnap es la CLI; circuitsnap-mcp es el servidor stdio. circuitsnap mcp también ejecuta el servidor, si prefieres un único binario).

Para Claude Code, copia también skills/circuitsnap/ en .claude/skills/ para obtener el flujo de trabajo /circuitsnap, que cubre la lectura de un dibujo y la verificación del resultado.

Uso

Describe el circuito como una netlist — componentes y nombres de red, sin coordenadas:

{
  "title": "RC lowpass",
  "components": [
    { "id": "V1", "kind": "voltage",   "nodes": ["gnd", "in"],  "value": 5 },
    { "id": "R1", "kind": "resistor",  "nodes": ["in", "out"],  "value": "10k" },
    { "id": "C1", "kind": "capacitor", "nodes": ["out", "gnd"], "value": "1uF" }
  ]
}

Los terminales que comparten un nombre de red están conectados. Ese es todo el modelo.

circuitsnap build rc.json          # URL + circuit text
circuitsnap build rc.json --url    # just the URL
circuitsnap elements               # pin order and parameters for every kind
circuitsnap decode "<share-url>"   # read someone else's circuit

Como librería:

import { snap } from 'circuitsnap';

const { url, text, diagnostics } = snap({
  components: [
    { id: 'V1', kind: 'voltage',  nodes: ['gnd', 'in'], value: 5 },
    { id: 'R1', kind: 'resistor', nodes: ['in', 'gnd'], value: '1k' },
  ],
});
console.log(url.url);

Valores

Notación de ingeniería, escrita como una persona la escribe en un esquemático:

M es mega y m es mili — la convención de los esquemáticos. El hecho de que en SPICE M signifique mili convertiría una "resistencia de 10M" etiquetada a mano en 10 miliohmios.

Elementos

wire, resistor, capacitor, inductor, voltage, rail, ground, switch, diode, led, current, labeledNode, transistor, opamp, output, probe, text.

Ejecuta circuitsnap elements para conocer el orden de los pines, los parámetros, las unidades y los valores por defecto. El orden de los pines importa: un transistor es [base, collector, emitter], un op-amp es [minus, plus, out].

Tierra

Usa el nombre de red gnd (o ground, 0, vss). Esos terminales reciben un símbolo de tierra real, no una etiqueta — un nodo etiquetado llamado "gnd" no lleva ninguna referencia de 0 V y dejaría al solucionador sin un punto de referencia. circuitsnap avisa si un circuito no tiene tierra en absoluto.

Cómo funciona

El proceso es netlist -> validar -> diseñar la disposición -> emitir -> URL, y solo el paso de leer un dibujo necesita un modelo. Hay dos decisiones que merece la pena conocer:

• Las redes se cablean con etiquetas con nombre, no con cables enrutados. Un autoenrutador que es correcto al 95% produce circuitos que se ven bien y simulan mal. Una etiqueta junto a un pin es verificable. La salida se lee como un esquemático jerárquico.

• Emitimos el formato de texto heredado, no XML. El upstream actual escribe XML pero todavía lee texto, por lo que el texto es la única codificación que se carga tanto en versiones antiguas como nuevas.

Consulta docs/ARCHITECTURE.md para ver el razonamiento y docs/FORMAT.md para la referencia del formato de archivo, derivada del código fuente upstream con citas de líneas.

Corrección

El formato se ha obtenido mediante ingeniería inversa, por lo que la corrección es fundamental:

• 372 circuitos upstream hacen un viaje de ida y vuelta byte a byte idéntico a través del analizador.

• La salida generada se comprueba en cuanto a coincidencia de terminales, escape y los bits de bandera que el upstream fuerza.

• Verificación en vivo: los circuitos generados se cargan en el simulador real y se leen las tensiones de los nodos. Así se validó la geometría de múltiples pines: un seguidor de op-amp debe seguir de verdad, y un transistor debe informar de fwd active con Ic/Ib = β.

npm run reference:fetch   # clone upstream (not vendored; see docs/LICENSING.md)
npm test

La suite de pruebas no realiza peticiones de red.

Licencia

circuitsnap es MIT. CircuitJS1 es GPL-2.0-or-later, de Paul Falstad e Iain Sharp, y no se incluye ni se modifica aquí — circuitsnap genera archivos en su formato y abre su URL. Consulta docs/LICENSING.md para ver el razonamiento completo, incluido cómo este proyecto maneja las señales de rastreadores de IA de falstad.com (versión corta: sin rastreo, sin scraping, las pruebas son totalmente offline, y --base-url te permite apuntar a tu propia copia autoalojada).

No está afiliado a los autores de CircuitJS1 ni cuenta con su respaldo.