boardwright
Generate and edit KiCad boards and schematics from a short Python description, checked by KiCad itself.
Status: alpha. It makes real, routed, DRC-clean KiCad 10 projects and edits existing ones in place. None of the example boards has been fabricated. The command line is the stable surface; the Python modules will move.
pip install boardwright # add [live] to edit the board open in KiCad
boardwright doctor # what this machine has for each step
Needs KiCad 10 (its libraries and kicad-cli) and Freerouting
for autorouting. boardwright doctor finds them in the usual install places, Flatpak
included, and names the setting to use when it cannot.
What it does
A board is a directory with a board.py: the circuit, where the parts go, and what
matters about the layout.
from boardwright.circuit import Circuit
NAME, W, H = "ldo_breakout", 30, 20
CIRCUIT = c = Circuit("LDO breakout")
c.add("J1", "Connector_Generic:Conn_01x02", "VIN", "Connector_PinHeader_2.54mm:PinHeader_1x02_P2.54mm_Vertical", {1: "VIN", 2: "GND"})
c.add("U1", "Regulator_Linear:AMS1117-3.3", "AMS1117-3.3", "Package_TO_SOT_SMD:SOT-223-3_TabPin2", {1: "GND", 2: "+3V3", 3: "VIN"})
c.add("C1", "Device:C", "10u", "Capacitor_SMD:C_0805_2012Metric", {1: "VIN", 2: "GND"})
# ...
PLACE = {"J1": (3, 8.7, 0), "C1": (8.5, 10, 90), "U1": (15, 10, 270)}
REVIEW = {"near": [("C1.1", "U1.3", 6.0)]} # input capacitor within 6 mm of the input pin
boardwright place examples/boards/ldo_breakout # placement + ratsnest preview, ~5 s, no KiCad
boardwright gen examples/boards/ldo_breakout # schematic, board, routing, pours
boardwright check examples/boards/ldo_breakout # KiCad: ERC, DRC + parity, netlist, gerbers, plots
boardwright verify examples/boards/ldo_breakout # PASS / NOT DONE
verify passes only when KiCad reports zero ERC and DRC findings at every
severity, schematic parity included, KiCad's netlist equals the declared circuit,
the fab files exist, and the engineering review is clean.
The review exists because a zero DRC is not a good board. An autorouter will run a
signal through a power polygon and leave the halves joined by a thin trace, and KiCad
accepts it. REVIEW checks what a reviewer would: decoupler-to-pin distance,
routed path lengths and pair matching (vias counted), how far a signal runs with no
ground on the adjacent layer, ground vias beside signal vias, pour coverage and
whether each pour is still one piece, and current capacity per IPC-2221.
Boards that already exist are edited in place and nothing is regenerated:
boardwright existing MYPROJ info # layers, nets, pours, preview; any size of board
boardwright existing MYPROJ review # the same review, against a spec beside the board
boardwright existing MYPROJ apply # REMOVE, MOVE, RIPUP, ROUTES, TRACKS, VIAS, ZONES from the spec
boardwright existing MYPROJ reroute /SDA # re-route named nets; every other net stays byte-identical
boardwright existing MYPROJ verify # review + no DRC finding that is not in the baseline
boardwright sch MYPROJ set R12 Value=4k7 # one block of the schematic replaced, the rest untouched
boardwright live apply edit.py # the same edits to the board open in KiCad, one undo step
Exit codes
The same as the other heibench tools, so a script or CI job can branch on them:
| Code | Meaning |
|---|---|
| 0 | done: the board passed, or the edit was made |
| 1 | violated or refused: a finding about the design, or an edit not made |
| 2 | could not tell: a check could not be decided (a KiCad report is missing or stale) |
| 4 | environment fault: KiCad, a library or Freerouting missing or failing; never a verdict on the design |
| 64 | usage: bad arguments, or a spec naming parts, nets or layers that are not there |
How it decides
- KiCad is the judge. Nothing is "done" on the tool's own arithmetic. Every
generated board goes through
kicad-cli, and edits to existing designs are compared against a baseline that KiCad produced. Connectivity before and after an edit is checked with netspec, which this project uses to find KiCad. - Placement and hand copper are yours; the rest is routed. Power loops, USB pairs and
anything sensitive are drawn in
board.py(TRACKS,VIAS,ZONES). Parts can be placed by intent:pad_at(1, ("U1", 24), dy=-1.7)puts a capacitor's pad 1.7 mm from pin 24. Freerouting does the remaining small signals, and a pad-to-pad router finishes what it leaves open. - Edits are plain data. An edit to an existing board is an ordered list of operations in the board's own coordinates, checked against the board before it runs, so the same file can be applied to the file on disk or to KiCad's open board.
Examples
examples/boards/ has seven boards made with it; all but the library fixture follow a vendor
reference design:
| Board | Layers | What it exercises |
|---|---|---|
ldo_breakout |
2 | the loop itself |
rp2040_min |
2 | 0.4 mm QFN, USB-C, crystal, QSPI flash |
tps54202_buck |
2 | a switching regulator's current loops, hand-routed power |
stm32f103_min |
2 | 0.5 mm LQFP-48, bottom-side decoupling, USB pair |
esp32c3_min |
2 | RF module with antenna keep-out, USB on the bottom layer |
stm32f103_4l |
4 | inner ground planes, return-path and via review |
customlib_test |
2 | parts from a library outside KiCad's stock set |
examples/existing/ has specs for demo projects that ship with KiCad, for trying the
existing-board and schematic commands. docs/devlog/ records what each
board broke in the tool and what was changed.
Documentation
The site is at https://heibench.com/boardwright/. In this repository:
docs/guide.md: the full workflow, everyboard.pyoption, existing boards and schematics, the live KiCad client, and what the tool does badly.docs/devlog/gaps.md: known limits.
Known limits
- Freerouting is not repeatable on dense boards; the pad-to-pad router does not push other tracks aside, tune lengths or route pairs as pairs.
- Schematic editing changes fields, removes parts, and adds a part by copying one with the same symbol. It cannot add a symbol the sheet does not already use, and a schematic change is pushed to the board in KiCad.
- Generated schematics are one flat sheet.
- Impedance figures are closed-form (IPC-2141, about +-10 %); confirm with your fab.
- KiCad 10 only. The live client uses KiCad's IPC API, which is what KiCad 11 builds on.
Development
just setup # uv sync --all-extras
just check # ruff
just test # pytest; the full KiCad pipeline test skips where KiCad is absent
License
Apache-2.0. The example boards are generated from KiCad's libraries, whose licence (CC-BY-SA 4.0 with an exception for designs that use them) places no restriction on the boards.
Metadata
Release files for boardwright 0.5.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| boardwright-0.5.1.tar.gz | 111.3 kB | With provenance | Details for boardwright-0.5.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| boardwright-0.5.1-py3-none-any.whl | Python 3 | none | any | Details for boardwright-0.5.1-py3-none-any.whl |
Total release size: 208.5 kB
Release files / boardwright-0.5.1.tar.gz
| Download URL | boardwright-0.5.1.tar.gz |
|---|---|
| Size | 111.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
655813a2a309c5a4d2c33f07db702f628b6cd6e3a21c688d674ef76a8abb25ea
|
|
BLAKE2b-256 checksum How to use checksums |
d6b49d5fedcf2179d559f39a2d6a910fab92beae251c27403bd47c425f2cc2a4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logRelease files / boardwright-0.5.1-py3-none-any.whl
| Download URL | boardwright-0.5.1-py3-none-any.whl |
|---|---|
| Size | 97.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2150e1afe0d3582ef469b04bc825adbbaa78079e39923e4bd9fc354d1c74ac14
|
|
BLAKE2b-256 checksum How to use checksums |
6d5d43e5bccc6413bc29e01d3a16c73ed87749ddb325cecd5132128896aa59c7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logSecurity for boardwright 0.5.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for boardwright-0.5.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.