diff --git a/docs-site/src/content/docs/development/architecture.md b/docs-site/src/content/docs/development/architecture.md index f681887..064eb01 100644 --- a/docs-site/src/content/docs/development/architecture.md +++ b/docs-site/src/content/docs/development/architecture.md @@ -29,7 +29,7 @@ src/mckicad/ drc.py # DRC checking + manufacturing constraints bom.py # BOM generation and export export.py # Gerber, drill, PDF, SVG via kicad-cli - routing.py # FreeRouting autorouter integration + routing.py # Autorouter integration (freeroute CLI, JAR fallback) analysis.py # Board validation + real-time analysis pcb.py # IPC-based PCB manipulation via kipy resources/ @@ -42,7 +42,7 @@ src/mckicad/ path_validator.py # Path security / directory traversal prevention secure_subprocess.py # Safe subprocess execution with timeouts ipc_client.py # kipy IPC wrapper for live KiCad connection - freerouting.py # FreeRouting JAR engine + freerouting.py # Autorouter engine: prefers freeroute CLI, falls back to FreeRouting JAR; native headless SES applier file_utils.py # Project file discovery kicad_utils.py # KiCad path detection, project search sexp_parser.py # S-expression parsing for pin position resolution diff --git a/docs-site/src/content/docs/getting-started.md b/docs-site/src/content/docs/getting-started.md index 67e697f..fd9778e 100644 --- a/docs-site/src/content/docs/getting-started.md +++ b/docs-site/src/content/docs/getting-started.md @@ -26,7 +26,7 @@ Tools degrade gracefully: if KiCad is not running, IPC-dependent tools report th **Export and manufacturing** -- Generate Gerber files, drill files, PDFs, and SVGs for your boards. Everything goes through kicad-cli with proper layer selection and output directory organization. -**Autorouting** -- Route PCBs automatically via FreeRouting integration with configurable strategies (conservative, balanced, aggressive) and technology profiles. +**Autorouting** -- Route PCBs automatically through a fully headless, Java-free pipeline built on [freeroute](https://git.supported.systems/warehack.ing/freeroute) (a native-Python port of the FreeRouting engine), with the FreeRouting JAR available as a fallback for maximum net completion on dense boards. **Board analysis** -- Live board statistics, connectivity monitoring, component detail inspection, and routing quality analysis through the IPC API. diff --git a/docs-site/src/content/docs/getting-started/configuration.md b/docs-site/src/content/docs/getting-started/configuration.md index bb71038..33ca174 100644 --- a/docs-site/src/content/docs/getting-started/configuration.md +++ b/docs-site/src/content/docs/getting-started/configuration.md @@ -28,7 +28,21 @@ These settings control where the server looks for KiCad projects: |---------------------|-------------|---------|---------| | `KICAD_APP_PATH` | Path to the KiCad installation | Auto-detected per platform | `/Applications/KiCad/KiCad.app` | | `KICAD_CLI_PATH` | Explicit path to kicad-cli | Auto-detected | `/usr/bin/kicad-cli` | -| `FREEROUTING_JAR_PATH` | Path to FreeRouting JAR | Auto-detected in common locations | `~/freerouting.jar` | +| `FREEROUTE_CLI` | Path to the freeroute CLI (preferred autorouter) | Auto-discovered on PATH | `~/.local/bin/freeroute` | +| `FREEROUTING_JAR_PATH` | Path to the FreeRouting JAR (optional fallback) | Auto-detected in common locations | `~/freerouting.jar` | + +### Routing options + +Autorouting is configured per call through the `routing_config` argument of `route_pcb_automatically`, not through environment variables. The freeroute-specific keys are: + +| Key | Description | Default | +|-----|-------------|---------| +| `freeroute_engine` | Router engine: `room`, `exact`, or `grid` | `room` | +| `freeroute_pack` | Enable channel packing for tighter routing | `true` | +| `freeroute_shove` | Allow shoving existing traces to make room | Engine-dependent | +| `freeroute_diagonal` | Allow 45-degree / diagonal trace shortening | Engine-dependent | + +See the [Autorouting guide](/guides/routing/) for what each engine does and when to reach for it. ### Server settings diff --git a/docs-site/src/content/docs/getting-started/installation.md b/docs-site/src/content/docs/getting-started/installation.md index a8435ac..e081fb2 100644 --- a/docs-site/src/content/docs/getting-started/installation.md +++ b/docs-site/src/content/docs/getting-started/installation.md @@ -101,15 +101,29 @@ List all my KiCad projects If the server is running and configured correctly, it will scan your search paths and return a list of `.kicad_pro` files. -## Optional: FreeRouting (autorouting) +## Optional: autorouting -For automated PCB routing, install FreeRouting: +For automated PCB routing, install [freeroute](https://git.supported.systems/warehack.ing/freeroute), a native-Python, Java-free autorouter: + +```bash +uv tool install freeroute +# or: pip install freeroute +``` + +That is the whole setup. freeroute is pure standard library with no dependencies and no Java runtime. mckicad auto-discovers the `freeroute` command on your PATH; if it lives somewhere unusual, set `FREEROUTE_CLI` in your `.env` to the executable path. Verify with the `check_routing_capability` tool. + +See the [Autorouting guide](/guides/routing/) for the full pipeline, engine choices, and honest scope. + +### Fallback: FreeRouting JAR + +freeroute completes fewer nets than the original FreeRouting engine on dense commercial boards (it drops a net rather than emit a DRC violation). If you need maximum completion on a hard board and have Java available, keep the FreeRouting JAR as a fallback: 1. Download the JAR from [freerouting.app](https://freerouting.app/) 2. Place it at one of the auto-detected paths: `~/freerouting.jar`, `/usr/local/bin/freerouting.jar`, or `/opt/freerouting/freerouting.jar` 3. Install a Java runtime (`java` must be on your PATH) -4. Verify with the `check_routing_capability` tool -5. Or set `FREEROUTING_JAR_PATH` in your `.env` file to an explicit path +4. Or set `FREEROUTING_JAR_PATH` in your `.env` file to an explicit path + +mckicad prefers freeroute when it is installed and falls back to the JAR only when freeroute is missing or cannot route the board. ## Development commands diff --git a/docs-site/src/content/docs/reference/environment.md b/docs-site/src/content/docs/reference/environment.md index 707b3fb..d9ea2f9 100644 --- a/docs-site/src/content/docs/reference/environment.md +++ b/docs-site/src/content/docs/reference/environment.md @@ -58,9 +58,23 @@ KICAD_APP_PATH=/Applications/KiCad/KiCad.app - Windows: `C:\Program Files\KiCad` - Linux: `/usr/share/kicad` +### FREEROUTE_CLI + +Path to the [freeroute](https://git.supported.systems/warehack.ing/freeroute) CLI, the preferred autorouter. freeroute is a native-Python, Java-free port of the FreeRouting engine. + +``` +FREEROUTE_CLI=~/.local/bin/freeroute +``` + +**Default:** Auto-discovered on your system PATH. Set this only if the `freeroute` executable is installed in a location that is not on PATH. Install it with `uv tool install freeroute` or `pip install freeroute`. + +Used by: `route_pcb_automatically`, `check_routing_capability`. + +Per-call engine and packing behaviour is controlled through the `routing_config` argument (`freeroute_engine`, `freeroute_pack`, `freeroute_shove`, `freeroute_diagonal`), not through environment variables. See the [Autorouting guide](/guides/routing/). + ### FREEROUTING_JAR_PATH -Path to the FreeRouting JAR file for automated PCB routing. +Path to the FreeRouting JAR file. This is the optional fallback autorouter, used only when freeroute is not installed or cannot route a given board. mckicad prefers freeroute (see `FREEROUTE_CLI`). ``` FREEROUTING_JAR_PATH=~/freerouting.jar @@ -71,7 +85,7 @@ FREEROUTING_JAR_PATH=~/freerouting.jar - `/usr/local/bin/freerouting.jar` - `/opt/freerouting/freerouting.jar` -Requires a Java runtime (`java` must be on PATH). +Requires a Java runtime (`java` must be on PATH). Only needed for maximum net completion on dense boards; the primary freeroute path needs no Java. ### LOG_LEVEL @@ -104,7 +118,11 @@ KICAD_USER_DIR=~/Documents/KiCad # KiCad application path # KICAD_APP_PATH=/usr/share/kicad -# FreeRouting JAR for autorouting +# Autorouter: freeroute is preferred and auto-discovered on PATH. +# Set FREEROUTE_CLI only if it is installed off-PATH. +# FREEROUTE_CLI=~/.local/bin/freeroute + +# Optional FreeRouting JAR fallback (needs Java; only for dense boards) # FREEROUTING_JAR_PATH=~/freerouting.jar # Logging level diff --git a/docs-site/src/content/docs/reference/tools.md b/docs-site/src/content/docs/reference/tools.md index c68cc25..6f47edd 100644 --- a/docs-site/src/content/docs/reference/tools.md +++ b/docs-site/src/content/docs/reference/tools.md @@ -155,12 +155,12 @@ See [Autowiring guide](/guides/autowire/) for details on the decision tree. ## Routing tools -`tools/routing.py` -- FreeRouting autorouter integration. +`tools/routing.py` -- autorouter integration. Prefers the Java-free [freeroute](https://git.supported.systems/warehack.ing/freeroute) CLI and falls back to the FreeRouting JAR. See the [Autorouting guide](/guides/routing/). | Tool | Description | |------|-------------| -| `check_routing_capability` | Check whether automated PCB routing is available | -| `route_pcb_automatically` | Automatically route a PCB using FreeRouting | +| `check_routing_capability` | Check whether automated PCB routing is available (freeroute or JAR) | +| `route_pcb_automatically` | Automatically route a PCB, headless, via freeroute (JAR fallback) | | `analyze_routing_quality` | Analyze current PCB routing for quality and potential issues | ## PCB tools (IPC)