🌊 v0.20.0 — planes first: the pour becomes information, and one step owns every piece of copper

[drandyhaas]

🔧 Update 2026-08-07 — v0.20.1 is out (release). A small Python-only follow-up to v0.20.0 — same 0.20.0 router binaries, so it's a drop-in update:

• Via-in-pad can now be disabled board-wide (route.py: option to avoid via-in-pad on SMD pads (off-pad escape vias) #581). Via-in-pad stays the default, but --same-net-pad-clearance > 0 (previously a plane-stitching option) now turns it off as a whole-chain assembly constraint: every via any step places — routing escape vias, the last-resort via-in-pad rescue, plane taps, layer-swap pad vias, even the sub-grid via nudge — stays that far off same-net SMD pads. BGA fanout switches to dog-bone escapes, QFN fanout refuses via-in-pad outright, and the value is recorded in the .kicad_pro so one flag at the top of a chain covers every later step. In the GUI it's the new Allow via-in-pad checkbox at the top of the Basic tab. If your fab frowns on vias in SMD pads (solder wicking, tombstoning), this is for you. Leaving it unset changes nothing.
• A real routing-correctness fix (route.py emits copper violating clearance against board copper GRAPHICS (KiCad DRC confirms); 2-net repro on apple1_aci_card #583). On boards whose copper is hand-drawn as net-tagged graphics (retro/reproduction boards), the layer-swap machinery could treat those graphics as movable stubs and silently blind the router to real copper — shipping tracks through its clearance, confirmed by KiCad's own DRC. Graphics are now never touched by stub machinery.
• Planes GUI fixes. A zone you delete on the live board stays deleted — the pour step no longer resurrects it from the file on disk — and the Planes tab now reports the zones it poured (and tells you when one was skipped) instead of leaving you guessing.
• Plugin install fix (install_plugin.py fails at import: No module named 'startup_checks' after the py_router/` refactor #582), stress-harness robustness, and the test suite is fully green for the first time (250/0).

Hey everyone! 👋

v0.20.0 is out, and it's the biggest structural change this router has had. It is worth explaining as an idea rather than a changelog, because almost everything else follows from it.

For most of this project's life, routing a board with power planes went like this: route the signals, pour the planes, then repair the damage. Each step was self-contained and each one made life harder for the next. Signals were routed into space the plane would later want. The pour arrived last and filled whatever was left, getting carved into islands by tracks that never knew it was coming. Then a repair pass went looking for plane pads that ended up connected to nothing, and welded them on — with rip-up authority, after the fact, with less information than the steps that caused the problem.

"Repair" is an honest word for that. It also gives the game away: a pipeline that needs a repair step is one whose earlier steps are allowed to break things.

v0.20.0 reorganizes the chain around a single principle: pour the planes first, treat that pour as information every later step can see, and let one step own every piece of copper the planes imply. There is no repair step any more. There are no taps in the pour step any more. The chain is now:

pour the planes  →  fanout  →  diff pairs  →  ONE route step (which finishes the planes itself)

📦 How to get it: download KiCadRoutingTools-0.20.0.zip from the Releases page, then in KiCad open Plugin and Content Manager → Install from File… and pick that zip. Prebuilt router binaries for Linux/macOS/Windows are attached — python build_router.py fetches them automatically, no Rust toolchain needed. (This release also finally publishes the 0.20.0 Rust binaries. The crate had been at 0.20.0 with nothing published, which quietly meant that anyone without a Rust toolchain couldn't install HEAD at all.)

⚠️ One thing to change in your scripts: the engine moved into py_router/, so it's python3 py_router/route.py … now (#522).

🌊 Why pouring first changes everything downstream

The pour is the single largest piece of copper on most boards. Making it last meant every earlier decision was taken blind to it — and every one of those decisions constrained it.

Pour it first and it stops being an obstacle to be worked around after the fact. It becomes information:

The fanout can see real fill. When the plane already exists, the fanout's plane-drop pass looks at actual filled copper rather than a zone outline. A BGA ball that the pour already covers needs no via at all — the pour touches the pad, and that is the connection. Balls that do need a via get one placed into intact copper, at fanout time, where the escape is being planned anyway. This is what a person does by hand: you look at where the plane actually is, and you only add a via where the plane isn't.

Signal routing can be charged for the damage it does. With a real fill in hand, the plane-fragility field prices every cut through the pour by how narrow the copper is there. Crossing the middle of a wide plane is nearly free; slicing through a 0.3 mm neck that is the only thing connecting two halves of your ground is expensive. Signals therefore cross planes where planes can take it, instead of severing them at their weakest point and leaving a repair pass to discover the wreckage. The pour reflows around tracks; it does not get amputated by them.

Return vias and stitching still come last, deliberately. The Step 1 pour is bare — nets and layers only, no --add-gnd-vias, no stitching. Those adapt to signals that do not exist yet, and placing them early is how a stitching via ends up sitting in a differential pair's only channel. So they run in a final pass, once the signals are real and the vias can arrange themselves around them.

🚫 The pour step stopped drawing copper — on purpose

This is the change I'd most like to convince you is right, because it looks like a feature removal.

route_planes used to tap. It had a per-pad tap loop, a via-in-pad spiral search, same-net strapping, distant-trace routing, and a rip-and-retry ladder with fallbacks — roughly 520 lines whose job was to reach out from the pour and grab pads that the fill hadn't caught. All of it is deleted, with no kill switch. When we discussed keeping it behind a revert flag, the argument against won: that would leave a second, unexercised way for the pour step to draw copper.

That's the principle. One authority draws copper. The pour step now declares intent — this net owns this layer — and fills. Nothing else. Which means:

• The pour step cannot rip anything, so --rip-blocker-nets is gone from it. (The measured failure mode of ripping there was real: routed signals destroyed to serve tap pads that the fanout's plane drops already covered.)
• Six now-dead plane flags were removed rather than shimmed, and the recorded manifest corpus was migrated to match. Dead flags that still parse are a lie the CLI tells you.
• The one thing deliberately kept is the thermal via array — it stamps vias under an exposed pad and draws no traces, so it's a pour/fab feature rather than routing. When a lattice doesn't fit, the pad is deferred, never traced to.
• The pour's post-write check used to warn that N pads weren't connected. Unconnected-by-the-pour is now simply the expected intermediate state — the route step is what finishes them — so it says that instead of raising an alarm.

🎯 The plane as a place to route to, not around

If the pour step no longer reaches out to pads, something has to connect them. That something is the router, and this is the part I find genuinely elegant.

Every pad-covered fill region of a plane now contributes launch cells to the search: real, laddered target cells on the actual filled copper. A pad doesn't get welded to the plane by a later pass — it gets routed to the plane, as a first-class destination, by the same A* that routes everything else.

Two details make it trustworthy rather than approximate:

• Region-exact crediting. Attaching to a fill region unions you with that region's component only — no majority vote, no cross-region credit. If a pour is secretly two islands, the router knows which one you reached, and plans the join edge for the other.
• Fragility-scored landing sites. Candidate cells are scored by distance and by how fragile the copper is there. Landing on a strait or a pour boundary costs; landing deep in solid fill is free. So the router drops into the plane where the plane is strong — again, exactly the judgment a person applies by eye.

🧩 Everything finishes inside the route step

The last piece: the plane finalize — taps, region joins, cleanup, and a KiCad-verified completion check — now runs inside batch_route, on both front-ends (the CLI against its output file, the GUI in-process against the live board).

Why this is better in principle, and not just fewer commands to type: a separate repair step is a second process reasoning about a board it did not route. It re-parses a written file, rebuilds an obstacle map from scratch, and has no idea which copper the routing step had just placed, ripped, or deliberately protected. It is structurally forced to guess. Running the same work as the run's final phase means it inherits everything: the live obstacle map, custody of every ripped net, the DRC floors actually in force, and the routing scope. And the run commits copper once, at the end, instead of a chain of steps each writing a file the next one must re-interpret.

The rule this creates for you: the finalize covers the pours it knows about, so put the plane nets in your route step's --nets. A route step that excludes GND excludes GND's pours from its own finalize — by plan, not by accident.

repair_planes.py still exists as a standalone utility (renamed from route_disconnected_planes.py) if you want to run it against someone else's board. It is simply no longer a step in the chain.

🔩 Fanout: escapes that are legal by construction

Two fixes here matter more than their size suggests, because both replace assumed legality with checked legality.

Via-in-pad at a ball centre now checks real copper (#567). The centre site used to be granted a blanket pass, which honored the mutual-reservation contract between escape passes but also waived conflicts with copper that was already committed — an earlier pass's escape run may legitimately pass close to a pad centre, since an SMD pad blocks only its own layer. The via was then dropped straight through it (measured intrusions of 0.19–0.24 mm, in both orderings). It now runs the full site-conflict check with the pad-clamped ring and drill, waiving only the reservations that contract actually covers.

A via that doesn't fit no longer kills the net (#568) — which needed a change in the Rust core, and is the subject of the next section.

The same idea now exists at whole-net scale as a last resort: a net that is still open after everything else gets a retry ladder where track width and via size march down together toward the fab floor (clearance never reduced), with no rip authority so it can never take a casualty — and a rung is accepted only if the net then grades fully connected, otherwise it is undone completely. Better a proven-smaller trace than a shipped open.

⚙️ In the Rust core: via size stops being one number for the whole board

Until now the router carried a single via geometry for an entire search. Every grid cell was either via-legal or it wasn't, decided once against that one size. That sounds harmless and isn't, because it makes via size a global commitment made before the router has seen a single obstacle — and dense regions become via-deserts. A net that needed a layer change under a BGA, or between two pads on a tight pitch, simply failed. The only remedies were board-wide and bad: shrink every via (pushing the whole board into a finer, pricier fab class, and derating current on power vias that never needed it), or add layers.

That's not how anyone designs by hand. You use your standard via everywhere, and you drop to a smaller one only in the spots that demand it — under the fine-pitch part, threading a gap. Via size is a property of a site, not of a board.

The Rust core now models it that way (0.20.0). Alongside its via-block map it keeps a second refcounted map at the small fab-rung reserve, and searches can ask is_via_blocked_rung(cell, rung) — so the same board can be via-illegal at your normal via and legal at the next rung down, cell by cell. On top of that sits the escalation: when an edge would otherwise fail for want of a via, the router samples that edge's neighbourhood on a fine subgrid, exact-validates the smaller via at each blocked cell — per-layer copper clearance plus drill-to-drill spacing against existing board vias and plated through-holes — and re-searches with those cells opened, emitting vias that genuinely are the smaller rung (re-validated again at emission, so what ships is what was proven).

Two properties I'd point at as the reason to trust it:

• It cannot perturb boards that don't use it. The small-rung map has subset semantics: empty means "unpopulated", and any query at rung ≥ 1 falls back to the ordinary map — so a single-rung caller is byte-identical to 0.19.x. This is geometry escalation that is provably inert until something actually needs it.
• Every relaxation is proven at the exact spot it's used, against real neighbouring copper and real drills — not granted by a rule of thumb or a global setting.

The net effect is that the router gets to answer a local problem locally, instead of failing a net or degrading the whole board. On the three-board check, the boards that had tight spots picked up completions (ulx3s 18 → 16 unrouted with 126 escalation firings, orangecrab 18 → 17 with 720) and the clean control board was untouched at zero firings — which is exactly the shape you want: nothing happens where nothing is needed.

This is also why this release had to publish new binaries: the via_rung argument doesn't exist on a 0.19.x .so, so HEAD simply wasn't installable without a Rust toolchain until now. The same crate release also removed the pygame visualizer and its snapshot machinery (#569) — grading, manifest replay and the GUI cover that debugging workflow.

🧷 Welds you can believe

Two related fixes, in the same spirit of replacing claims with checks.

The KiCad-oracle tier could credit a weld it never made: its escalated strap fell back to routing the two largest fragments in a window, "fixed" an unrelated 0.14 mm gap 7 mm away on the wrong layer, and reported the link welded — after which the same debris re-stacked every round. Copper emitted outside the link's own corridor is now rejected, never credited, and a caller welding a specific pair of points fails honestly when it cannot anchor there.

We also deleted a heuristic that tried to infer a weld from geometry: it treated an exact-fill anchor that happened to coincide with a pre-existing track endpoint as a connection. That's a kiss, not a weld, and it re-cleared the very net the fix existed to route. Geometry doesn't get to overrule a fresh failure.

And when a forced link dies against a genuinely pre-existing wall, its evidence used to be trapped inside a sub-run where the escalation that could act on it never looked. That evidence is now exported, filtered through the same protection rules as everything else (protected nets, negated nets and zone-backed copper are never named), and the run takes another lap with authority to rip the specific blocker — with full custody, so a failed attempt restores what it moved.

🗂️ The reorganization (#522)

104 engine modules moved into py_router/, 11 leaf tools into py_tools/, and the plugin resolves its engine directory itself so PCM installs are unaffected. Beyond tidiness, the point is that the engine is now a thing with a boundary — you can tell at a glance whether a file is the router or a tool that uses it, and the parity gate that guards CLI/GUI drift can name the engine as a path prefix instead of a hand-kept list.

We took the layout seriously enough to verify it behaviorally rather than by imports: replaying a recorded chain on the old and new layouts produced copper-identical boards, geometry hash included. Three real bugs surfaced because of that comparison and were fixed before it landed.

😬 The honesty section — treat this as a beta

This is a beta. Not the code quality — the ordering. A new chain sequence is the single most invasive thing we can change, it lands in both the CLI and the GUI at once, and it is new. Commands moved (py_router/), a whole step disappeared, flags that used to exist are gone rather than deprecated, and the plane work now happens somewhere it never used to.

So: keep your 0.19.3 chain scripts until you've run the new one on a board you know well, put the plane nets in your route step's --nets, and grade the result (check_drc.py + check_connected.py) rather than trusting the summary. If something looks wrong, tell us — that's exactly the feedback this release needs.

Full commit-level detail in the v0.19.3…v0.20.0 compare (144 commits) and the Rust changelog in rust_router/README.md.

Bug reports and feedback hugely welcome — open an issue or reply here. Happy routing! 🎉