DSH FreeRouting
English | 简体中文 | Documentation
Autoroute the open KiCad PCB through DSH. Intermediate tracks and vias appear in KiCad; the task card shows progress, cleanup choices and the final result.
This preview release supports Windows x64, compatible KiCad 10.0.7+ releases in the 10.0 series, and their bundled Python 3.11. The DSH SDK baseline is 0.2.1-rc.2. Save the board at least once before routing; later unsaved edits can be exported.
Behavior and limits
- Preserve existing tracks and vias. Add final tracks and vias in one KiCad transaction.
- Show temporary routing in KiCad when configured. If recorded preview geometry was edited, ask whether to delete identifiable run-owned objects or keep them.
- Stop routing from the task card. After requesting cancellation, wait for computation and protected board operations to settle before reporting the outcome.
- Keep the initiating DSH session running until routing and cleanup finish. Support its native Stop action and retain the final card in the tool row, without a separate background completion notice. Composer buttons retain DSH's native draft behavior.
- Optionally refill existing zones. Create no zones and retain confirmed imported copper after later failures.
- Use KiCad's bin/freerouting.exe with bundled Python dependencies. No separate system Python or Java installation is required.
- Never save automatically. Automatic repair, rerouting, DRC, final connectivity checks and design-check reports are disabled.
- Do not compare PCB text or board-content fingerprints. Avoid editing, saving or undoing during routing; arbitrary changes may go undetected.
Confirmed import does not guarantee complete connectivity, differential-pair coupling, length matching, impedance or crystal-circuit performance. Inspect the board before saving. See current behavior and capability limits.
Install and connect
For standalone DSH, install a published package or a local tarball:
dsh plugin --profile web add -w --ignore-scripts @huaqiu/dsh-tool-freerouting
# Replace the package name with the absolute path to a local dist/*.tgz build.
Restart DSH when idle and load one copy only. Host/browser entries and cordis.patch.yml are included; no separate skill is needed. KiCad-bundled DSH development links use the separate workflow below.
Enable the KiCad API in the PCB editor. A KiCad-bundled host can locate Python within its installation. Standalone DSH needs the actual path in its active profile's cordis.patch.yml:
- id: huaqiu-dsh-tool-freerouting
config:
kicadPythonPath: C:/Program Files/KiCad/10.0/bin/python.exe
Connection precedence is explicit kicadApiSocket, then KICAD_API_SOCKET, then discovery when neither is set. Multiple connectable editors require explicit selection. An invalid explicit address does not fall back to another board.
Settings and tools
| Setting | Default | Meaning |
|---|
| realtime | true | Show temporary copper in KiCad |
| drawtimeSec | 5 | Interval between preview attempts; snapshots and native operations determine actual timing |
| requestTimeoutMs | 120000 | Request wait; begun board writes retain separate lifetime protection |
| freeroutingBaseUrl | empty | Allocate a private loopback endpoint; nonempty selects a fixed endpoint |
| resultTtlMs | 3600000 | Download retention after completion, one hour by default |
See config.ts for all settings and ranges. Keep ipcStateDirectory stable; do not delete ownership or uncertainty records to work around a failure. One active task is allowed, with no queue or maxPendingRuns setting.
| Tool | Current behavior |
|---|
| pcb_route | Whole-board routing; fast=false, skip_net_classes=[], fill_zones=true by default |
| pcb_cancel_route | Request cancellation and report the source and stop confirmation |
| pcb_confirm_board_checked | Explicit confirmation after inspection; new routing requests also verify prior ownership |
| pcb_repair_route | Retained entry that reports automatic rerouting is disabled |
fast=true disables optimization, not the routing algorithm. skip_net_classes passes exact internal class names to autorouter.ignore_net_classes for the main autorouter stage. The default class is usually default; fanout and optimization may still process excluded classes. Arbitrary net-name filtering, skip_nets and pcb_route_nets are unavailable.
Routing has no overall time limit. It continues until completion, cancellation or a reported failure; individual requests still have timeouts.
The engine comes from the selected KiCad installation or DSH_FREEROUTING_EXE. Managed startup chooses a private local port; an explicit service URL remains fixed. Unconfirmed old calculations prevent another calculation from starting.
Run and inspect
- Back up the project, open its PCB and enable the API.
- Ask DSH to run pcb_route, preserve existing copper, use skip_net_classes=[], fast=false and fill_zones=false, and leave the file unsaved.
- Watch KiCad and the task card. Small boards can finish before a preview appears.
- Inspect the confirmed additions and zone-fill result, then save manually.
Edited temporary copper presents a delete/keep choice. No answer within five minutes keeps it. Confirmed deletion ends the round without final import so the board can be inspected; user-created, split or unidentifiable fragments may remain.
One undo normally removes final additions. Older undo steps may restore previews; zone filling is separate from this guarantee. Closing the target PCB editor requests cancellation and stops owned compute even if the project manager remains open. The plugin checks the bound instance's PCB documents about every two seconds; communication timeouts or busy responses are not evidence of closure. Closing a browser tab does not cancel routing. Begun writes finish their commit or rollback; a timeout is not proof that no write occurred.
Confirmed counts survive download or cleanup failures. Browser status/choice requests have a 20-second deadline and downloads have 60 seconds. Retrying a read does not reroute or re-import. A new routing request first checks whether the old task's PCB is still open. Confirmed closure or an already cancelled task permits waiting for its cleanup; a healthy active task is retained. With no other active task, the plugin reclaims its own busy or unresponsive engine and confirms exit before preparing new computation. It never forcibly stops an externally configured service. Clearing target-board state still requires old host/writer ownership checks; it does not delete copper or prove an unknown operation was rolled back. Tasks and downloads do not recover across restarts.
Closure detection uses periodic queries. Closing and reopening the same PCB path between queries may go undetected because the current interface does not identify individual document-opening sessions.
Windows: the PCB is open, but IPC cannot read it
If the API is enabled and KiCad version queries succeed, but reading the current board returns the following error, check the project and PCB filenames and the actual running KiCad processes:
no handler available for request of type kiapi.common.commands.GetOpenDocuments
KiCad can open a PCB with a different base name, but it uses matching filenames to identify the project's PCB. The official manual specifies one PCB per project and matching base names for the project file, root schematic and PCB, such as project.kicad_pro, project.kicad_sch and project.kicad_pcb. The manager finds the project PCB by replacing the project file's extension; see the PcbFileName implementation. This convention lets it derive the PCB path without a separate file mapping.
The project tree also shows other files in the project directory. Being listed there and opening from that tree does not establish that a file is the current project's PCB. Even with only one project manager launched, KiCad can automatically start another process for a differently named PCB.
The following comparison used the same PCB copy on Windows with KiCad 10.0.7-6-g78d68fa7a5:
| How the PCB was opened | Actual processes and IPC result |
|---|
Open other-board.kicad_pcb from the manager for project.kicad_pro | KiCad treats it as outside the project and starts pcbnew.exe; the connection address belongs to kicad.exe, and reading the board returns the error above |
Open the same PCB from the manager for the existing other-board.kicad_pro | kicad.exe hosts the PCB without an additional pcbnew.exe; IPC returns the correct board name and copy directory |
Starting a separate editor process for a differently named PCB is KiCad's design; the subsequent IPC failure is abnormal. This trigger can explain why one project fails while others work, without establishing that the PCB file is damaged. IPC is the interface used to communicate with KiCad. Official reports describe Windows connection-address problems across multiple processes: #20880, #23994, and proposed fix !2532. These are investigation leads; the comparison above does not prove that this failure has exactly the same root cause.
Verified workaround:
- Resolve any unsaved changes in the separately opened PCB editor, then close it.
- Open the existing
.kicad_pro whose base name matches the target PCB, such as other-board.kicad_pro, in the project manager.
- Open
other-board.kicad_pcb from that project manager, then reconnect DSH.
- Verify that the connected board path is correct before routing.
This avoids the known trigger; it does not fix KiCad. Different .kicad_pro files can contain different design rules. Do not overwrite or merge project settings, or rename the board blindly. If no matching project file exists, first check the project-to-board association and design rules in a project copy. Diagnose other connection errors from their actual details; a generic connection failure alone does not identify this issue.
Standalone development
Work from this repository root using Node 22.19+ in the 22.x line or 24+, and the packageManager declared in package.json. Use fresh local dependencies and an isolated developer venv; do not install developer tools into KiCad Python.
pnpm install --frozen-lockfile
$env:DSH_IPC_TEST_PYTHON = 'C:/Program Files/KiCad/10.0/bin/python.exe'
$env:PYTHONUTF8 = '1'
& $env:DSH_IPC_TEST_PYTHON -m venv .build-cache/python-types
& ./.build-cache/python-types/Scripts/python.exe -m pip install -r requirements-dev.txt
$env:DSH_RUFF_BIN = "$PWD/.build-cache/python-types/Scripts/ruff.exe"
pnpm exec playwright install chromium
pnpm run package:plugin
package:plugin prepares locked Python dependencies, checks, builds, packs and verifies a fresh isolated installation. Tarballs go to dist/. Initial preparation can require wheel downloads. The SDK wheel, source record and SHA-256 locks are maintained in this repository. Runtime packages include Python libraries, while engine source, Java builds and engine regressions remain outside this project.
prepack checks this project's LICENSE and builds; it does not copy a license from a parent checkout. Tests, internal documents and caches are excluded from the installed package. Changes to transactions or process lifetime require additional isolated live checks. See Python maintenance and the test guide.
KiCad-bundled DSH development links
Prepare FreeRouting dependencies and build each participating plugin separately. The sibling .dsh-dev-packages/sources.json must list the complete enabled plugin collection and absolute source paths.
pnpm run prepare:dependencies
pnpm run check:dev-links
pnpm run link-plugins:kicad
pnpm run plugin-status:kicad
# Append --runtime and --collection for other locations.
The script uses the runtime's official hq-edge-plugins tool. It stages published files for FreeRouting and pcb-autoplacement in .build-cache/dev-plugin-packages/ while retaining source links for other plugins. Runtime dependencies are included and development files excluded. Failed preparation preserves the old snapshot; status commands are read-only. Building this repository does not build other plugins.
The script does not edit profiles or restart the host. Wait for routing, board writes and cleanup to finish before Reset DSH. Standalone checks and packaging do not require the old monorepo. Existing source metadata retains historical origins and is not evidence of the current Git remote or installed version.
License and feedback
First-party code uses the MIT license in this project's LICENSE. KiCad distributes the GPL-3.0 FreeRouting engine separately; bundled/freerouting.LICENSE retains its reference notice. Obtain corresponding engine source from its distributor. See THIRD_PARTY_NOTICES.md.
If you encounter a bug, report it in Huaqiu-Electronics/dsh-tool-freerouting Issues. Include steps to reproduce, expected and actual results, plugin, DSH and KiCad versions, the failed stage, final message and redacted logs. You may attach retained downloads or a project copy suitable for public sharing; do not attach tokens, account settings or confidential PCB data.
