Medinstech

Perfboard circuit design and soldering guides

A desktop app that takes a schematic netlist, lays it out on pad-per-hole
perfboard, lets the router work out the connections, proves the board matches
the schematic, and writes a step-by-step build guide with measurement
checkpoints.

tests latest release Python 3.12+ Apache-2.0

Download · uv tool install perfstudio · MCP server · Example boards · Changelog · Türkçe

the 2D editor, with an NE555 astable placed and routed

The status bar is the whole claim: fourteen connections across seven nets,
three of which needed a wire, DRC clean and LVS agreeing with the schematic.

• A soldering guide with verification steps. Not just "solder R1 here", but "block 2 complete → U1 pin 4 to C3(−) must show continuity" and "before power-on: GND to V+ must read above 10 kΩ". Derived from the netlist, so it is exact rather than generic advice.
• Perfboard LVS. The board's real connectivity is extracted and compared against the schematic. Opens, shorts and floating conductors are reported before you pick up the iron.
• Six kinds of connection, not one. A lead bend, a solder trace, a wired solder trace, bare wire, insulated wire and a top jumper have different costs, limits and failure modes, and the router prices all six — which is what makes a layout that is pleasant to actually solder.
• Three rules only the third dimension can see. A part too tall for the case, a jumper trapped under a body that gets soldered down on top of it, and a heat-sensitive part sitting too close to a hot one. The 3D view is a checking tool, not a picture.
• The sheet is derived, never stored. No symbol positions live in the file, so there is no second copy of the circuit to keep in step with the netlist and nothing to lay out by hand.
• Agent-native. An MCP server, a headless CLI and a git-diffable project file, all driving the same command bus as the GUI — so undo works across a session where a human and a model both edit the board.

Status: pre-alpha, and end to end. A netlist goes in and a soldering guide comes out. What is missing is the dogfood test — nobody has yet built a real board by following a generated guide, and PLAN.md §11 says M5 does not close until somebody has. Everything else runs: v0.10.0 ships an installer for each of the three desktop platforms, none code-signed.

Jump to — Running it · Connections · Both faces · The schematic · The guide · From an agent · How it is built · Documentation · Contributing

Most tools model a perfboard connection as "a wire". Perfboard has six physically distinct ways to join two points, each with its own cost, limits and failure modes — and modelling that difference is what lets the router produce a layout that is pleasant to actually solder:

The 0.6 mm gap to the neighbouring pad is why solder traces are both so useful and so easy to get wrong. PerfStudio scores that risk into the router's cost function, and turns every flagged spot into a measurement step in the build guide.

The solder side is where the copper is, so it is a first-class view rather than a mirror mode — and copper on the face you are not looking at is hatched, because a board is opaque and a trace drawn solid says this is in front of you.

The solder side, with far-side copper hatched

The 3D view is a checking tool, not a picture. Three rules exist that a top-down view cannot see at all: a part too tall for the case, a jumper trapped under a body that will be soldered down on top of it, and a heat-sensitive part sitting too close to a hot one.

The same board in 3D

The board says where everything goes. The schematic panel (Ctrl+5) says what you are building — and it is where you say it: Add Part, Wire two pins, Place on the Board. The circuit comes first and the layout second, which is how every other EDA tool works and is the order this one could not do until now.

The NE555 astable, drawn from its netlist

The sheet is derived, never stored. No symbol positions live in the file, so there is no second copy of the circuit to keep in step with the netlist and nothing to lay out by hand. Ground and power become rail symbols instead of wires, which is the difference between a sheet you can read and eleven lines crossing everything. Polarity comes from the parts library's own pin names, so an LED's cathode and a diode's cathode both end up on the barred end — they are opposite pins, and a rule that guessed from pin 1 would draw one of them backwards. A part whose pinout the library does not record, like a TO-92, is a labelled box: drawing a transistor there would be asserting which lead is the base.

It also cross-probes: click a symbol and that part is selected on the board, click a wire and its net lights up in both places. LVS saying net VOUT is open is a great deal more useful when you can look at VOUT.

And it leaves the window. File ▸ Export Schematic... writes the sheet beside the document three ways: SVG to embed or edit, PDF to print and keep next to the board, PNG to paste into the message that asks somebody why the circuit does not work. All three come out of the same SVG, so they cannot disagree about what the circuit is — and the exported sheet is black on white rather than the panel's light-on-dark, because the rail symbols already say which rail sinks and which sources, and a photocopier keeps shapes rather than colours.

The NE555 board assembling itself: parts first, then the board turns over and the copper goes on

Parts go in shortest first — a tall part fitted early stops the board lying flat on the bench while the short ones are soldered. Then the board is turned over and the copper goes on, and ICs are last for heat and ESD. A jumper that would end up trapped under a part body is moved to the first phase, because by the time that part is down it is too late.

The animation turns the board over halfway through for the same reason you would: a perfboard is opaque, and fourteen of this build's twenty-two steps happen on the face you cannot see from above. It is generated by playing the guide back through the same function the 3D panel's assembly slider calls, so it cannot show an order the guide does not actually give you.

It is a desktop application, so the ordinary way to get it is to install one. No Python required.

⬇ Download the latest release

Each is built and smoke-tested by the tag that produced it. None of them is code-signed, so each warns on first run and the release notes say how to get past it — a Windows EV certificate is ~300ドル/year and Apple notarization 99ドル/year, and neither is bought yet. See docs/RELEASING.md.

The interface speaks English and Turkish (--lang tr, or follow the system locale).

For the two platforms with no build — an Intel Mac, Linux on ARM — and for anyone who would rather not click past a signing warning. Needs Python 3.12+:

uv tool install perfstudio # or: pipx install perfstudio
perfstudio # launch on a blank board
perfstudio some/board.perf # ...or open a document
perfstudio --version

uv tool or pipx, not a bare pip install, because this is an application and not a library. Both put it in an environment of its own and perfstudio on your PATH, where pip install would either put 400 MB of Qt and VTK into a shared site-packages or, on Debian, Ubuntu and Fedora, be refused outright by the system Python (PEP 668). From a clone, pip install -e . inside a virtualenv.

Qt and VTK are most of that 400 MB. There is no smaller build, because the 3D view is a checking tool the application depends on rather than an optional extra.

Open the schematic panel (Ctrl+5) and draw the circuit: Add Part for each part, Wire to click two pins together, then Place on the Board. From there Place → Auto-place Board (Ctrl+Shift+A), Ctrl+R to route, and File → Export Build Guide (Ctrl+B). No KiCad anywhere in that.

With a circuit that already exists, start at File → Import KiCad Netlist on examples/ne555-astable.net and accept the offered placement instead. That is the exact sequence the screenshots above come out of — see tools/screenshots.py.

Four examples ship as both the netlist and the finished board:

perfstudio examples/lm317-supply.perf

All four route to completion, match their schematics under LVS and carry no DRC error — tests/test_examples.py asserts it on every commit.

The MCP server drives the identical command bus, so undo works across both:

claude mcp add perfstudio -- uvx --from "perfstudio[mcp]" perfstudio-mcp

Nothing has to be installed first — uvx fetches the package into its own cache. From a clone it is pip install -e ".[mcp]" and then claude mcp add perfstudio -- perfstudio-mcp.

Fifty-one tools, every hole addressed the way people talk about perfboard (A1, C7, AC12) and never as raw coordinates. See docs/MCP.md for the tool list, the JSON config other clients want, and the rest of the setup.

Renders 2D/3D/PDF to files, runs DRC and LVS and prints timings, with no display. It is how the visual output is exercised in CI, and the fastest way to check that a rendering change did not crash:

python -m perfstudio.ui.main --headless tools/diffcheck/golden/dense.perf

The document is immutable and every mutation is a command dispatched through one bus — which is what makes undo work across a mixed human/agent session. The engine is pure: no clock, no RNG, no filesystem, no Qt or VTK below ui/. The placer's annealing is seeded, so the same document and the same seed give the same board.

That purity is load-bearing rather than decorative. This Python engine is a port of the TypeScript one still in packages/, and its acceptance criterion was never "the tests pass" but "it produces byte-identical results to the implementation it replaces" — golden fixtures in tools/diffcheck/, down to the last IEEE-754 double.

src/perfstudio/ the engine: document model, command bus, connectivity,
 router, autorouter, placer, DRC, LVS, persistence
src/perfstudio/guide.py the soldering guide, and guide_export.py for HTML/CSV/JSON
src/perfstudio/stripboard.py the board whose copper arrives joined, and striproute.py
 for the cuts-and-links planner that designs on one
src/perfstudio/parsers/ KiCad netlist importer
src/perfstudio/ui/ Qt application: 2D editor, VTK 3D view, 1:1 PDF export,
 and headless.py, the no-display run CI checks the output with
src/perfstudio/mcp/ the MCP server (docs/MCP.md)
examples/ a netlist to import
tests/ ~2080 tests; the engine is mypy --strict clean
packages/ the original TypeScript engine, kept as the reference the
 Python port is proved against

The 61 THT footprints are generated from numeric parameters, not shipped as assets — no mesh library, no share-alike licence to inherit. The same spec that draws a part in 2D extrudes its body in 3D, so the two cannot disagree.

A part that is not among the 61 is described, not installed. Custom Part... asks for a pin grid and three dimensions and hands back an identifier that carries them: box-4x2-p1-r3-15x10x8 is a four-by-two pin grid, three holes between the rows, in a 15 ×ばつ 10 ×ばつ 8 mm body. Nothing is stored — the identifier is the definition — so a board using a part nobody else has still opens as that part on their machine, with no library to install and nothing to go missing.

Done: the editor, the library, connectivity and LVS, DRC, the router and the placement optimiser, the build guide with rendered step images and assembly playback, the 1:1 PDF export, the schematic panel and the sheet export beside it, parts described by their own measurements when the library does not have them, crash recovery, the MCP server, TR/EN localisation, the three-platform packaging that a v* tag runs, and the update check that tells you a release exists and fetches it (Help ▸ Check for Updates; it verifies the download against the release's SHA256SUMS and then hands it to you — running it stays your click).

Next, in the order PLAN.md §11 puts them:

• The dogfood build (M5). Somebody has to solder a real board from a generated guide. Until that has happened, every claim on this page is a claim about software rather than about a working circuit. It is also the one thing on this list that a stranger can do for the project — there is an issue template for it.
• Code signing. A Windows EV certificate is ~300ドル/year and Apple notarization 99ドル/year, so until then the installers warn on first run and the release notes say how to get past it.

Issues and pull requests are welcome. Please read CONTRIBUTING.md first — it covers how to run the suite, which checks are gates and which are not, and one licence boundary that matters more here than in most projects: do not read or port code from the GPL-licensed tools in this space. PerfStudio is clean-room with respect to them, and that has to stay true. The record is in docs/prior-art.md.

Apache-2.0. See LICENSE and NOTICE.