Cm5

kicad-scripted-pcb

繁體中文

Three KiCad 10 boards designed entirely as code: Python scripts produce the schematic, the PCB placement, the routing (via freerouting) and the copper pours, and each board rebuilds from scratch with one command. The KiCad GUI is never opened.

The point is verification. Every build runs several independent checks, because each one is blind to errors the others catch. Some of those errors turned up while these boards were being built and are listed below.

	Board	Result
	usbc-ldo: USB-C 5 V → 3.3 V LDO → LED. 40 × 24 mm, 2 layers. Includes an ngspice power-path simulation.	ERC 0, DRC 0, schematic parity
	esp32c3: ESP32-C3 minimal board with native USB, LP38693 LDO, RESET/BOOT, LEDs and an 8-pin header. 32 × 49 mm.	ERC 0, DRC 0, schematic parity, pin-by-pin netlist check
	relay8: ESP32-C3 + ULN2803 driving 8 mains relays from one mains cable: on-board HLK-10M05 AC-DC (100–240 VAC), T8A fuse, varistor, L/N bus traces, per-channel NO · N · NC terminals, isolation slots and custom mains clearance rules. 232 × 110 mm. Not safety-certified.	ERC 0, DRC errors 0 (40 silkscreen-clipped-by-slot/edge warnings listed), schematic parity

Each ESP32 board has a FIRMWARE.md with the pin map, flashing steps, a first program, and, for relay8, the mains wiring.

Pipeline

gen/board.py ──► .kicad_sch ──► ERC ──► netlist ──► netlist check (vs expected_nets.json)
                                                     │
                                                     ▼
                                     design review (lib/review.py, datasheet rules)
                                                     │
gen/pcb.py ◄─────────────────────────────────────────┘   place footprints, board outline,
   │                                                     net classes, placement self-check
   ▼
.kicad_pcb ──► Specctra DSN ──► freerouting ──► SES ──► import + GND pour ──► DRC (+ schematic parity)
                                                                                   │
                     lcsc.json ──► lib/lcsc.py (online, run by hand) ──► lcsc-check.json
                                                                                   │
                                                       lib/fab.py ◄────────────────┘
                                     Gerber + drill zip, JLCPCB BOM / CPL, hand-solder list

Every step stops the build on failure; nothing is passed downstream with a known error.

kicad-cli has no "update PCB from schematic" command, so lib/pcbgen.py builds the board from the exported netlist with pcbnew.

What each check catches, and what it missed

Things that cost time (so they don't cost yours)

• freerouting-cli 2.5.0 crashes on KiCad 10 DSN files (freerouting#957). Use the jar, which needs Java 25.
• freerouting's automatic neck-down narrows tracks to 0.125 mm beside 0402 pads, below JLCPCB's 0.127 mm minimum. Use --router.automatic_neckdown=false --router.neck_width_um=150.
• The DSN carries no copper-to-edge rule. Pass --router.copper_to_edge_clearance_um. That setting does not cover internal slots, so put keepouts around slots.
• Net classes live in .kicad_pro, not .kicad_pcb. Save with pcbnew.SaveBoard(), which writes both.
• board.Remove(zone) from Python can raise 'SwigPyObject' has no attribute 'thisown' or crash pcbnew (0xC0000005). Use board.Delete().
• freerouting reports pin-to-pin "violations" inside fine-pitch footprints where KiCad's DRC is clean. The cause is KiCad's DSN exporter inflating every edge of a rounded-rect pad (specctra_export.cpp) by the arc-approximation margin.
• Windows PowerShell 5.1 reads BOM-less UTF-8 scripts as ANSI. The build scripts here are ASCII-only for that reason.

Requirements

• Windows (the build scripts are PowerShell; the Python parts are cross-platform)
• KiCad 10 (uses its bundled Python for pcbnew, and its ngspice). Set KICAD_BIN / KICAD_SHARE if it is not in the default location.
• Python 3.10+ on PATH for schematic generation and the design review (standard library only). The simulations and the field solver need numpy, scipy and matplotlib.
• Network access only for lib/lcsc.py (JLCPCB parts API). The build itself runs offline.
• freerouting 2.5.0 jar + a Java 25 runtime. Run tools\setup-tools.ps1 once; it downloads both into tools\ with pinned SHA-256 checks.

Quick start

powershell -ExecutionPolicy Bypass -File tools\setup-tools.ps1
powershell -ExecutionPolicy Bypass -File boards\esp32c3\build.ps1
python lib\review_test.py          # design-review mutation tests; needs the boards built once

The build ends with boards/<b>/fab/:

Also written to boards/<b>/: review.txt (design review, including the inferred net voltages) and lcsc-check.json (part numbers as checked against JLCPCB, with stock and attributes).

Layout

lib/schgen.py, ksym.py, netlabel.py   schematic writer (symbols flattened from the KiCad library)
lib/check_netlist.py                  netlist vs expected_nets.json
lib/review.py, review_test.py         design review rules + mutation tests
lib/pcbgen.py, route.py               PCB builder (BoardSpec), freerouting round trip, GND pour
lib/lcsc.py, fab.py, jlc_rotations.json   part-number check, fabrication outputs
lib/field2d.py, field2d_check.py      2-D field solver for trace impedance + validation
boards/<b>/gen/board.py   the circuit (pin -> net table)
boards/<b>/gen/pcb.py     placement (BoardSpec)
boards/<b>/lcsc.json      hand-written LCSC part numbers ("value|footprint" -> part)
boards/<b>/review-waivers.json   accepted review findings, each with a reason
boards/<b>/build.ps1      one-command build
boards/<b>/sim/           ngspice and field-solver studies
tools/      setup-tools.ps1 (downloads are git-ignored)

Want to add a board or a review rule? See CONTRIBUTING.md.

Code comments are in Chinese. The boards were built while comparing AI-assisted workflows in KiCad and EasyEDA Pro.

Limits

These are two-layer boards with modules and simple power. There is no controlled-impedance routing, no length matching, no BGA and no SI/PI analysis; freerouting does none of these (lib/field2d.py can tell you whether a trace needs it). The fabrication files are complete enough to order, but nobody has built these boards yet: CPL rotations are unverified and the design review is a set of rules, not an engineer. Have a person review before ordering. This applies above all to relay8, which switches mains voltage.

License

MIT. freerouting (GPL-3.0) and the Temurin JRE (GPL-2.0 with Classpath Exception) are downloaded at setup time and are not part of this repository.