Add autorouting guide for the freeroute pipeline
This commit is contained in:
parent
847e38e8a3
commit
fd81e63f1d
@ -38,6 +38,7 @@ export default defineConfig({
|
||||
{ label: "Netlist Import", slug: "guides/netlist" },
|
||||
{ label: "BOM Management", slug: "guides/bom" },
|
||||
{ label: "Design Rule Checks", slug: "guides/drc" },
|
||||
{ label: "Autorouting", slug: "guides/routing" },
|
||||
{ label: "Board Analysis", slug: "guides/analysis" },
|
||||
{ label: "Export & Manufacturing", slug: "guides/export" },
|
||||
{ label: "Prompt Templates", slug: "guides/prompts" },
|
||||
|
||||
125
docs-site/src/content/docs/guides/routing.md
Normal file
125
docs-site/src/content/docs/guides/routing.md
Normal file
@ -0,0 +1,125 @@
|
||||
---
|
||||
title: "Autorouting"
|
||||
description: "Route PCBs automatically through a headless, Java-free pipeline"
|
||||
---
|
||||
|
||||
The routing tools take an unrouted (or partially routed) PCB and lay copper for the remaining nets automatically. The whole pipeline is headless and needs no display, no running KiCad GUI, and no Java runtime by default, which makes it usable in CI, containers, and from an MCP client.
|
||||
|
||||
Routing runs through [freeroute](https://git.supported.systems/warehack.ing/freeroute), a native-Python port of the FreeRouting engine, with the original FreeRouting JAR available as an optional fallback for dense boards.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- KiCad with its bundled `pcbnew` Python module (used for DSN export and the native SES applier)
|
||||
- [freeroute](https://git.supported.systems/warehack.ing/freeroute) installed and on your PATH:
|
||||
|
||||
```bash
|
||||
uv tool install freeroute
|
||||
# or: pip install freeroute
|
||||
```
|
||||
|
||||
freeroute is pure Python standard library with no dependencies. mckicad auto-discovers the `freeroute` command; if it is installed off-PATH, set `FREEROUTE_CLI` to the executable in your `.env`. Confirm your setup before routing:
|
||||
|
||||
```
|
||||
Check whether automated routing is available for my board
|
||||
```
|
||||
|
||||
The `check_routing_capability` tool reports which router it found (freeroute, the JAR, or both) and whether the board is ready to route.
|
||||
|
||||
## The routing pipeline
|
||||
|
||||
When you route a board, mckicad runs a fully headless sequence:
|
||||
|
||||
1. **Export to DSN.** The board is exported to a Specctra DSN file using KiCad's bundled `pcbnew` Python. KiCad 10's `kicad-cli` dropped the DSN export and SES import subcommands, so mckicad does this itself rather than shelling out to the CLI.
|
||||
2. **Route.** freeroute reads the DSN, routes the nets, and writes a Specctra SES file. No Java, no GUI.
|
||||
3. **Apply the SES natively.** A native, headless SES applier writes the routed copper straight back into the `.kicad_pcb` file. There is no GUI import step and no display required.
|
||||
4. **Validate.** Run a DRC check and inspect the routing result to confirm the board is clean.
|
||||
|
||||
To run it:
|
||||
|
||||
```
|
||||
Automatically route my PCB at /path/to/project.kicad_pcb
|
||||
```
|
||||
|
||||
The `route_pcb_automatically` tool orchestrates the whole pipeline and returns routing statistics along with the path to the updated board.
|
||||
|
||||
## Choosing an engine
|
||||
|
||||
freeroute ships three engines. mckicad defaults to `room` with channel packing enabled, which is a good all-round starting point. Select an engine through the `routing_config` argument (see [Configuration](/getting-started/configuration/)).
|
||||
|
||||
| Engine | What it does | Reach for it when |
|
||||
|--------|--------------|-------------------|
|
||||
| `room` | Continuous free-space router with channel packing and shove. DRC-clean output. | Default. Best general-purpose choice for most boards. |
|
||||
| `exact` | Orthogonal router whose output is verified exactly DRC-clean. Supports shove and 45-degree / diagonal shortening. | You want provably clean, predictable orthogonal routing. |
|
||||
| `grid` | Fast maze router, grid-quantised. | Quick first passes and simpler boards where speed matters more than density. |
|
||||
|
||||
The relevant `routing_config` keys are:
|
||||
|
||||
- `freeroute_engine` -- `room` (default), `exact`, or `grid`
|
||||
- `freeroute_pack` -- enable channel packing for tighter routing (default `true`)
|
||||
- `freeroute_shove` -- allow shoving existing traces to make room
|
||||
- `freeroute_diagonal` -- allow 45-degree / diagonal trace shortening
|
||||
|
||||
## DRC-clean output
|
||||
|
||||
freeroute is built to never emit a design rule violation. Every engine produces DRC-clean copper, and `exact` verifies its output as exactly clean. The trade-off is deliberate: when the router cannot place a net without breaking clearance, it **drops the net rather than route it into a violation**. You get a board that passes DRC with some nets still unrouted, not a fully connected board that fails DRC.
|
||||
|
||||
After routing, verify the result:
|
||||
|
||||
```
|
||||
Analyze the routing quality of my board
|
||||
```
|
||||
|
||||
`analyze_routing_quality` reports on trace characteristics, via usage, and potential issues. To see how many nets actually got connected:
|
||||
|
||||
```
|
||||
Check the routing connectivity of my PCB
|
||||
```
|
||||
|
||||
`check_connectivity` reports total nets, routed vs unrouted counts, and the routing completion percentage. Any nets freeroute dropped show up here as unrouted, so you can decide whether to reroute with different settings, route them by hand, or reach for the JAR fallback.
|
||||
|
||||
## Fallback: the FreeRouting JAR
|
||||
|
||||
If freeroute is not installed, or it cannot route a particular board, mckicad falls back to the original FreeRouting JAR. This path requires a Java runtime and the JAR on disk (see [Installation](/getting-started/installation/)). The JAR reaches higher net completion on dense commercial boards, at the cost of pulling Java back into the pipeline.
|
||||
|
||||
mckicad picks the router for you: freeroute when it is available and can route the board, the JAR otherwise. You do not have to choose manually, but you can keep both installed so the fallback is there when you need it.
|
||||
|
||||
## What freeroute is and is not
|
||||
|
||||
freeroute is **Alpha**. Being honest about its scope saves surprises:
|
||||
|
||||
**What it does today:** routes real KiCad boards across multiple layers with vias, rip-up and retry, channel packing, and 45-degree shortening, and it produces DRC-clean output.
|
||||
|
||||
**What it does not do yet:** it is **not** at FreeRouting/JAR density parity on dense commercial boards. Because it drops a net rather than emit a DRC violation, it completes fewer nets than the JAR on a hard board.
|
||||
|
||||
**Recommendation:** use freeroute for headless, JVM-free routing -- CI, containers, and MCP-driven workflows where you cannot or do not want to run Java. Keep the FreeRouting JAR as a fallback when you need maximum net completion on a dense board.
|
||||
|
||||
## Routing tools
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `check_routing_capability` | Check whether automated routing is available and which router was found |
|
||||
| `route_pcb_automatically` | Run the full headless routing pipeline (freeroute, JAR fallback) |
|
||||
| `analyze_routing_quality` | Analyze the routed board for quality and potential issues |
|
||||
| `check_connectivity` | Report routed vs unrouted nets and completion percentage |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### No router found
|
||||
|
||||
1. Confirm freeroute is installed: `freeroute --version`
|
||||
2. If it is installed off-PATH, set `FREEROUTE_CLI` to the executable path
|
||||
3. Run `check_routing_capability` to see what mckicad detected
|
||||
4. As a fallback, install the FreeRouting JAR and a Java runtime (see [Installation](/getting-started/installation/))
|
||||
|
||||
### Some nets are unrouted
|
||||
|
||||
1. This is expected behaviour: freeroute drops nets it cannot route cleanly rather than create DRC violations
|
||||
2. Try a different engine (`exact` or `grid`) or adjust `freeroute_pack` / `freeroute_shove` / `freeroute_diagonal`
|
||||
3. Route the remaining nets by hand in KiCad
|
||||
4. For a dense board, install the FreeRouting JAR and let mckicad fall back to it for higher completion
|
||||
|
||||
### DSN export or SES apply fails
|
||||
|
||||
1. Ensure KiCad's bundled `pcbnew` Python module is available to the server
|
||||
2. Verify the `.kicad_pcb` file opens cleanly in KiCad
|
||||
3. Check the server logs (`mckicad.log`) for the exact failure
|
||||
Loading…
x
Reference in New Issue
Block a user