Skip to main content

boardwright

Check Docs PyPI Python License: Apache-2.0

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.

RP2040 board generated by boardwright

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             # 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, every board.py option, 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.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for boardwright 0.4.0
File Size Uploaded Provenance Actions
boardwright-0.4.0.tar.gz 102.1 kB With provenance Details for boardwright-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for boardwright 0.4.0
File Interpreter ABI Platform Actions
boardwright-0.4.0-py3-none-any.whl Python 3 none any Details for boardwright-0.4.0-py3-none-any.whl

Total release size: 195.2 kB

Release files / boardwright-0.4.0.tar.gz

Download URL boardwright-0.4.0.tar.gz
Size 102.1 kB
Tags Source
SHA-256 checksum
How to use checksums
e7dd56931f141aed2647013ba23064359ce52b35686a159103af832927bee58d
BLAKE2b-256 checksum
How to use checksums
35d545f178b736997fcc37ab14ad29fe92b0f48caed9a7601b4f329cf1290e81
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 15, 2026.

Transparency log

Release files / boardwright-0.4.0-py3-none-any.whl

Download URL boardwright-0.4.0-py3-none-any.whl
Size 93.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
dfb3e90ee2af34fc5d6b9b95f33f69f7ddcc598e0f4f6da59263cfd2bad7e03a
BLAKE2b-256 checksum
How to use checksums
8fd449df4d17cb62d6f7e45ae61bc760330187d2748d558581a119abf65f0693
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 15, 2026.

Transparency log

Security for boardwright 0.4.0

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.

Select from 2 files

Attestation for boardwright-0.4.0.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 15, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page