KiCad — Hardware Design

Agents don't have to hand-guess XY coordinates: build the document with components and nets but rough (or no) positions, then call auto_place before validate_document / export_document. A shelf-packing algorithm sizes each component from its real pad geometry (plus a keepout margin) and packs everything inside the board outline — guaranteed zero overlap and zero components off the board.

Large parts (QFPs/QFNs/modules, by footprint area) are kept away from the board edges (large_component_inset, default 5mm) so the autorouter keeps escape channels on all their sides — tuned empirically, this lifted the Arduino Uno example from 22 to 25 routed nets. Mark a manually positioned component "locked": true (e.g. an edge connector) and the rest packs around it; the returned board_utilization percentage signals when the board needs to grow.

validate_document backs this up with a hard board-outline containment check: a component whose pad footprint extends outside the outline fails validation at document time — not after opening KiCad — and the error message points at auto_place as the fix.

After placement, route_board turns the netlist into real copper: a 2-layer grid-based maze router (Lee's algorithm) connects every net with track and via nodes that the KiCad exporter emits as actual (segment ...)/(via ...) S-expressions.

Copper is modelled physically: pads obstruct the copper the exporters actually render (their explicit size, or a shared pitch-aware default for size-less pads), and vias are placed only where their real via_diameter barrel keeps clearance to every other net's pads, tracks and vias — a net with no legal path fails cleanly instead of getting shorted copper. Nets the maze search cannot connect come back in nets_failed for manual routing instead of failing the run.

Set expectations correctly: this is a basic router for simple-to-moderate boards (the Arduino Uno / ESP32 dev-board range), not a replacement for a commercial autorouter on dense designs. On the packed Arduino Uno example, 25 of 32 multi-pad nets route at the default 0.15mm grid, with the remaining failures concentrated on residual congestion and the highest-fanout power nets.

check_fabrication validates the routed geometry — not just the declared design rules — against a PCB fab's rules (JLCPCB / PCBWay / OSH Park) with real geometric clearance checks between every copper pair: track-track, via-pad, via-via, pad-pad, track-pad, track-via. These are the same collisions KiCad's DRC reports.

That claim is checked, not assumed: kicad-cli pcb drc on the Arduino Uno export reports zero copper violations, verified in integration tests whenever kicad-cli is installed. (An earlier version reported a board as passing while KiCad's DRC found 199 real short circuits — pads and vias were treated as dimensionless points. That bug is why the verification exists.)

The pipeline ends fab-ready: export_document(tool='gerber', output_path='board_gerbers.zip') writes a zip a fab house can accept — front/back copper (routed tracks, via annulars, flashed pad apertures), soldermask openings, silkscreen reference designators, board outline, and an Excellon drill file with one hole per via — validated against a real Gerber parser (gerbonara reads back every layer and recognizes the full stack).

Run check_gerber_completeness first: it re-checks the fab rules on the routed geometry and warns if the board has no tracks yet.

The IR is Y-up — millimetres, origin at the board outline's lower-left corner, +X right, +Y up, rotation in degrees counterclockwise — the way a person naturally reasons about parts on a board.

Format tools translate at the boundary, never inside the IR: Gerber output is natively Y-up and passes coordinates through unchanged, while KiCad files are Y-down, so the KiCad exporter/importer mirror Y about the outline's vertical centre (and negate pad-local offsets) on the way out and in — round trips stay exact. A dedicated test pins specific coordinates on both sides so a frame regression fails CI immediately.