Hardware designreference
Catching invented footprints on an agent-generated KiCad board
This page is about one board that passed every gate it had and was still wrong, and about the checks added so the same mistakes fail. It is for anyone who lets an agent generate a KiCad board and relies on gates, not on looking, to decide when the board is ready to order. The gates the board already had are described in Generating and checking the GRIDDLE LX PCB from code; this page adds three that check the footprints themselves.
The board is a small two-layer click-latency test rig carrying an RP2040 dev module, two SOP-4 PhotoMOS relays, a USB-C power input and a USB-A port for the device under test. An agent generated its schematic, placement and routing on 2026-11-18 and 2026-11-19. Every finding quoted from the rig was produced on 2026-11-20 by re-running the checks on the routed board as committed, on kicad-cli 10.0.8. The check tools and both project repos are private, so their behaviour is described here and not linked; KiCad, the KiCad Library Convention (KLC), EasyEDA and the two licences are cited to their public pages. The evidence table separates what was run from what is documented.
TL;DR:
- The rig passed ERC, DRC with a JSON report gate, a live BOM check against JLC’s parts API (10 of 10 part groups) and a CPL rotation check against JLC’s footprints (18 of 18 placements), with three invented footprints on it: the RP2040 module, the USB-A receptacle and the two SOP-4 relays. The USB-A port also carried C168688, the LCSC number of a USB-C receptacle.
- The BOM check skipped hand-fit (DNP) parts, and the USB-A port was hand-fit. KiCad’s
missing_courtyardcheck is set toignoreby default, so a footprint with no courtyard raises nothing, andcourtyards_overlaphas nothing to test against. Nothing compared a part number with the copper it was placed on. pcb-checkreads the.kicad_pcbdirectly and fails a footprint with no courtyard or an open one, a pad outside its courtyard, a cable connector away from the board edge, and a non-stock footprint with no recorded source. On the rig it reports 7 findings, among them all four invented footprints.- The BOM check now covers hand-fit parts, checks each part’s JLC category against its reference prefix and fails a footprint whose USB family differs from the part’s.
fp-checkcompares each footprint carrying an LCSC number with that part’s EasyEDA footprint: pad-site count, repeated pitch and copper extent. On the rig it fails the USB-A port on all three. The extent tolerance is 20 % because KiCad and EasyEDA lands for the same 0805 or 1206 package differ by more than 10 %.- Each rule has a planted fault that must fail and a clean control that must pass. The checks reuse no code from KiCad’s GPL-3.0 library checker or the AGPL-3.0 easyeda2kicad; the tools are MIT, so the rules were re-implemented from the published conventions and file format.
Topology
Section titled “Topology”The first four gates existed when the rig was generated. pcb-check and fp-check are new, and the BOM check gained hand-fit parts, reference-prefix categories and USB families.
Which check catches what
Section titled “Which check catches what”| Defect on the rig | ERC | DRC | BOM check (before) | Rotation | pcb-check | BOM check (now) | fp-check |
|---|---|---|---|---|---|---|---|
| RP2040 module footprint drawn from memory, no courtyard, no LCSC number | - | - | - | - | no-courtyard, no-source | - | cannot see it (no LCSC number) |
| Two SOP-4 footprints with no courtyard | - | - | - | - | no-courtyard | - | pass against C719593 |
| USB-A footprint with no courtyard | - | - | - | - | no-courtyard | - | pad-count, pitch, extent |
| USB-C part number on the USB-A port | - | - | skipped (hand-fit) | not in the CPL | - | USB family mismatch | pad-count, pitch, extent |
| USB-C power input 5.29 mm and USB-A 2.50 mm inside the board edge | - | - | - | - | connector-off-edge | - | - |
No single check covers every row. The module carries no part number, so only pcb-check sees it; the USB-C number on the USB-A port is caught twice, by the BOM check from the part’s catalogue category and by fp-check from its copper.
What the board carried
Section titled “What the board carried”The RP2040 module footprint was drawn by the agent: 24 SMD pads at a 2.5 mm pitch spanning 21.3 x 35.3 mm of copper, with no courtyard, no 3D model and no datasheet, LCSC or EasyEDA reference. The review of the rig found its orientation and pitch wrong against the real module. The USB-A receptacle and the two SOP-4 relays were drawn the same way, without courtyards or 3D models. The USB-A footprint has 6 SMD pad sites; the part number on it, C168688, is a 16-pin USB-C receptacle with 12 SMD and 4 through-hole sites.
The SOP-4 relays show that “invented” and “wrong copper” are separate questions. Their part number was corrected to C719593 with the datasheet’s 2.54 mm pitch before the review, so their copper matches the part’s EasyEDA footprint, but the footprints still have no courtyard and no 3D model.
Across the rig, “no 3D model and no courtyard” picked out exactly the footprints the agent had invented. A missing model on its own is common in honest project libraries, so pcb-check prints it as a warning and names the pairing in the no-courtyard message.
Why each existing gate passed it
Section titled “Why each existing gate passed it”DRC: missing_courtyard defaults to ignore
Section titled “DRC: missing_courtyard defaults to ignore”KiCad’s manual describes a “Footprint has no courtyard defined” violation for any footprint without graphics on F.Courtyard or B.Courtyard, unless the footprint carries the “exempt from courtyard requirement” attribute1. The check behind it, missing_courtyard, ships at severity ignore. On kicad-cli 10.0.8 a board with no project file lists missing_courtyard under ignored_checks in the JSON report and reports nothing for a footprint with no courtyard; the rig’s own .kicad_pro carries "missing_courtyard": "ignore" too. The bundled KiCad project templates set it the same way.
A missing courtyard also disables courtyards_overlap. That check was at error on the rig, but two parts collide only if both have courtyards, so nothing could be reported as overlapping the module. A custom DRC rule does not close the gap either: KiCad’s rule language can require every pad to lie inside its own courtyard with insideCourtyard()1, but with no courtyard there is nothing to be inside and the rule never matches.
The KLC requires a fully enclosed courtyard on F.CrtYd, drawn with 0.05 mm lines on a 0.01 mm grid, with clearances of 0.25 mm by default and 0.5 mm for connectors2. That rule applies to footprints submitted to KiCad’s library; nothing applies it to a project’s own .pretty library unless a separate check enforces it.
BOM check: hand-fit parts were skipped
Section titled “BOM check: hand-fit parts were skipped”The BOM check resolved every LCSC number against JLC’s parts API for value, package size and stock, and it skipped parts marked do-not-populate, because JLC would not place them. The USB-A port was hand-fit, so its USB-C part number was never looked up. A hand-fit part is still bought by its LCSC number, so skipping it hid a wrong purchase as well as a wrong footprint.
Rotation check and ERC: what they inspect
Section titled “Rotation check and ERC: what they inspect”The CPL rotation check maps each assembled part’s KiCad pads onto JLC’s footprint for that LCSC number to check the placement angle. Hand-fit parts are not in the CPL file, so the module and the USB-A port were outside it. ERC checks the schematic’s connectivity; a footprint is a field there, and ERC does not read its copper.
No tie between part number and copper
Section titled “No tie between part number and copper”Both failures have one cause: the agent picked the LCSC number and the footprint separately, and no gate compared them. The BOM check compared the number with the schematic’s value and package text, the rotation check compared angles, and DRC compared copper with copper.
pcb-check: courtyard, edge and source rules
Section titled “pcb-check: courtyard, edge and source rules”pcb-check reads the .kicad_pcb as text, with no pcbnew and no DRC, so it does not depend on the project’s severity settings. It exits 0 when clean, 1 on findings and 2 on a usage or parse error, and prints one line per finding.
| Rule | Fails on | Measured semantics |
|---|---|---|
no-courtyard | No graphic on F.CrtYd or B.CrtYd and no allow_missing_courtyard attribute | The attribute is KiCad’s “exempt from courtyard requirement”, spelled as in the 10.0.8 stock library; footprints with no copper pad (logos, unplated locators) are skipped |
open-courtyard | Courtyard lines and arcs that do not chain into a closed loop | Endpoints within 0.02 mm join. KiCad 10.0.8’s malformed_courtyard closes gaps of 0.0178 mm or less and reports gaps of 0.0229 mm or more on every stock footprint probed |
pad-outside-courtyard | A pad outline leaving the union of the courtyard loops by more than 0.01 mm | Pad shape, size and rotation are used; unplated holes are skipped because stabiliser and peg holes sit outside bodies by design |
connector-off-edge | A cable-mating connector whose courtyard and pads are all farther than 0.5 mm from Edge.Cuts | Connectors are recognised by name tokens (USB, RJ45, barrel jack, audio jack, SD card, HDMI, edge-mount SMA and others); Vertical names, pin headers, wire-to-board and U.FL are skipped; mating direction is not checked |
no-source | A non-stock footprint with no datasheet URL, LCSC number, EasyEDA id or URL in its description | A footprint is stock when its library nickname names a stock .pretty directory, or when a stock footprint of the same name has the same pads; with no stock directory every footprint is non-stock |
stale-allow | An --allow REF:RULE that suppressed nothing | Keeps exceptions from outliving the defect |
The geometry follows KiCad’s own conventions and was checked against KiCad’s output: a child’s local coordinates map to the board through the footprint’s position and a rotation matrix with y growing down, a B.Cu footprint’s children are stored already mirrored, and a pad’s angle is absolute. Pad positions match the IPC-D-356 netlist kicad-cli exports on boards with B.Cu footprints at 30, 45, 90, 180 and 270 degrees, and the courtyard verdicts match kicad-cli’s DRC with missing_courtyard forced to error.
The no-source rule’s stock-equivalence test catches one form of invention directly: a footprint named like stock R_0603 but with its pads moved is non-stock and must say where it came from.
The BOM check after the fix
Section titled “The BOM check after the fix”Hand-fit parts now get every check except stock. Their value check is off, because a hand-fit value is a label, and when JLC’s assembly search does not list a hand-fit part its existence is checked against LCSC’s own catalogue instead. Every part, assembled or hand-fit, also gets two new checks:
- Category by reference prefix: the part’s JLC parent category must fit its reference, for R, C, L, F, D, Q, Y/X, J/P/CN and SW.
- Connector family: a footprint whose name gives a USB family (USB-A, USB-C, micro-B and so on) must not carry a part of another family.
KiCad 10.0.8 netlists carry the native do-not-populate and exclude-from-BOM flags as valueless properties; the check reads those as well as a legacy DNP field. Parts excluded from the BOM are skipped and listed. On the rig the USB-A port fails with “footprint is USB-A but JLC part is USB-C”. The first live run also found that five small breakout panels from another project carried C2338 on their 2xN headers, a number that exists at neither JLC nor LCSC.
JLC’s parts search is the endpoint JLC’s own website calls, not a documented API, so the check depends on an interface JLC can change without notice.
fp-check: footprint against the part’s EasyEDA footprint
Section titled “fp-check: footprint against the part’s EasyEDA footprint”The LCSC number already says what copper the part needs: LCSC parts carry an EasyEDA footprint. fp-check fetches it for every footprint with an LCSC number, hand-fit parts included, and compares three properties with the placed copper.
The footprint comes from https://easyeda.com/api/products/<LCSC>/components, the endpoint easyeda2kicad calls3. It is in the EasyEDA Standard format: a list of ~-separated shape strings with coordinates in units of 10 mil, 0.254 mm4. A PAD string carries shape, centre, width, height, layer, net, number, hole radius, outline points, rotation, id, hole length, hole points and a plated flag. An unknown part answers HTTP 200 with {"success": false, "code": 404}. The CDN in front of the API answered 403 to the user agents Python-urllib/3.x and bare Mozilla/5.0 on 2026-11-20, and to every request for about 2.5 minutes after about 40 requests in about 3 minutes, so the tool sends its own user agent, waits 1.5 s between requests, retries after 30, 60 and 120 s, and caches every response, 404s included.
Pad sites
Section titled “Pad sites”Only copper pads count: a KiCad pad on a copper layer that is not np_thru_hole, and an EasyEDA PAD on the top, bottom or multi-layer that is not an unplated hole. Pads that overlap so that one pad’s centre lies inside another are one site, whatever their numbers. That merges an exposed pad with its thermal-via pads, KiCad’s stacked USB-C A1/B12 pads and EasyEDA’s combined A9B4 pad, which otherwise differ in count between the two libraries for the same part. A site is SMD or through-hole by its largest pad.
| Rule | Fails when |
|---|---|
pad-count | The number of pad sites, or its SMD/through-hole split, differs |
pitch | A repeated pitch on one side has no match within 0.05 mm (plus 0.001 mm for EasyEDA’s rounding) on the other |
extent | The copper bounding box differs in either dimension by more than 20 % of EasyEDA’s value or 0.3 mm, whichever is larger |
Repeated pitch only
Section titled “Repeated pitch only”A footprint’s pitches are the distances from each site to its nearest same-size site, kept only when the same distance occurs between at least two different pairs: a row of three or more pads, or two parallel pairs. A one-off gap, such as the two pads of a chip resistor or a signal pad to a shell tab, is a land-pattern choice rather than a pitch. KiCad’s R_0603 puts its pads 1.65 mm apart and EasyEDA’s R0603 1.51 mm, and both are correct for the same part. Pitch is compared as distances, so rotation and mirroring do not matter, and with no repeated pitch on either side the rule is silent.
Extent tolerance: 20 %, not 10 %
Section titled “Extent tolerance: 20 %, not 10 %”The extent is the bounding box of all copper, with its two sides sorted so a library rotated 90 degrees still compares. KiCad and EasyEDA draw the same package with different lands, longest along the leads:
| Package | KiCad land | EasyEDA land | Difference of EasyEDA’s |
|---|---|---|---|
| 0805 capacitor | C_0805 2.90 mm | C0805 3.41 mm | 15.0 % |
| 1206 resistor against a 1206 capacitor part | R_1206 4.05 mm | C1206 4.67 mm | 13.3 % |
| SOT-23-5 | 3.60 mm | 3.20 mm | 12.5 % |
| 2-pin 5 mm terminal block | 2.8 mm pads | 2.4 mm pads | 16.7 % |
At 10 % every one of these same-package pairs fails. A re-run for this page compared KiCad’s stock R, C, LED and fuse lands in 0402, 0603, 0805 and 1206 with the cached EasyEDA footprints of real R, C, LED, fuse and ferrite parts in those sizes: 160 pairs. At 10 %, 11 same-size pairs failed, all 0805 and 1206; the 0.3 mm floor kept the 0402 and 0603 pairs inside. At 20 %, no same-size pair failed and no pair of different sizes passed. The nearest wrong package is still outside 20 %: R_0603 against an 0805 resistor part differs by 21.8 % along the leads.
Cut-strip headers
Section titled “Cut-strip headers”A pin header is usually bought as a breakaway strip and cut to length: C2337 is a 1x40 header, and a 1x5 cut from it is a correct part for a 1x5 footprint. When the EasyEDA footprint is one regular row or grid of equal pads and the placed footprint has the same pitch, rows and pad size with fewer sites, the check prints a cut-strip note and skips pad count and extent. A 2x5 header carrying the 1x40 strip’s number still fails, because the row count differs. Two other notes never fail: no-easyeda (no such part, or no footprint on it) and holes (unplated hole counts differ).
On the rig
Section titled “On the rig”pad-count J2 USB_A_Receptacle_USB_A_90deg: placed 6 pad sites (6 SMD), EasyEDA C168688 (USB-C-SMD_TYPE-C-USB-4) 16 pad sites (12 SMD, 4 THT)pitch J2 USB_A_Receptacle_USB_A_90deg: placed pad spacings 3.00, 11.00 mm, EasyEDA C168688 (USB-C-SMD_TYPE-C-USB-4) 0.50, 0.80, 11.16 mmextent J2 USB_A_Receptacle_USB_A_90deg: placed copper spans 13.00 x 13.50 mm, EasyEDA C168688 (USB-C-SMD_TYPE-C-USB-4) 6.57 x 12.36 mmNOTE cut-strip J3 PinHeader_1x05_P2.54mm_Vertical: placed 5 sites of a 40-site strip (2.54 mm pitch, 1 row), EasyEDA C2337 (HDR-TH_40P-P2.54-V-M-1): a cut-to-length header; pad count and extent not comparedNOTE cut-strip J5 PinHeader_1x04_P2.54mm_Vertical: placed 4 sites of a 40-site strip (2.54 mm pitch, 1 row), EasyEDA C2337 (HDR-TH_40P-P2.54-V-M-1): a cut-to-length header; pad count and extent not comparedFAIL: 3 finding(s)The module carries no LCSC number, so fp-check cannot see it; pcb-check catches it. The cached EasyEDA responses stay out of the repositories, so CI runs pcb-check (offline, against the stock footprint directory) but not fp-check, which runs in the local check and order targets.
Fault-injection tests
Section titled “Fault-injection tests”Each rule has a planted fault on a copy of a real board or a fixture board, a run of the real tool, and an assertion on the exit code and the finding that names the fault. Each suite also has a clean control that must pass, so a red fault test cannot come from a broken copy.
| Fault planted | Check | Expected finding |
|---|---|---|
| Whole courtyard removed from a stock TSSOP-16 on the keyboard board | pcb-check | no-courtyard on that part |
| One courtyard edge removed from the same TSSOP-16 | pcb-check | open-courtyard |
| Fixture footprint with no courtyard and no source | pcb-check | no-courtyard and no-source |
| Pad outside the courtyard, footprint at 90 deg; B.Cu footprint at 30 deg with a polygon courtyard | pcb-check | pad-outside-courtyard on each |
| Courtyard with a gap | pcb-check | open-courtyard |
| USB connector placed away from the edge | pcb-check | connector-off-edge |
Footprint named like stock R_0603 with its pads moved; a B.Cu-mirrored pad layout placed on F.Cu | pcb-check | no-source on each |
| Exempt net-tie, B.Cu copy of a stock footprint, stock footprint at 90 deg | pcb-check | none (controls) |
An --allow that suppresses nothing | pcb-check | stale-allow |
| 0603 land carrying an 0402 part | fp-check | extent |
| 1.27 mm SOP-4 land carrying the 2.54 mm AQY221R2S | fp-check | pitch, extent |
| USB-A land carrying C168688 (the rig’s own footprint) | fp-check | pad-count, pitch, extent |
| 2x5 header carrying the 1x40 strip’s number | fp-check | pad-count, extent |
| TSSOP-16 land on the keyboard board carrying a SOT-23-6 part number | fp-check | pad-count |
| Hand-fit USB-A footprint carrying a USB-C part | BOM check | USB family mismatch |
| Part whose JLC category does not fit its reference prefix | BOM check | category mismatch |
| Hand-fit part missing at JLC and at LCSC | BOM check | not found |
On real boards: the rig fails pcb-check with 7 findings and fp-check with 3, and the routed keyboard board passes both (302 footprints checked by pcb-check and 225 with an LCSC number by fp-check on the main board). The breakout panels from another project flagged a USB-C receptacle set inside the board edge.
Lessons
Section titled “Lessons”- When a gate goes through KiCad’s DRC, a check left at its default severity of
ignoreis off. Read the board file directly for rules that must hold whatever the project’s settings say. - Check a hand-fit part like an assembled one. It is bought by the same part number, and the number is the only thing tying the purchase to the copper.
- Tie the part number to the copper. A footprint and an LCSC number chosen separately pass every check that looks at only one of them.
- Calibrate a tolerance on correct pairs before shipping it. 10 % looked strict and failed 0805 and 1206 parts that were right; the threshold was set from the measured spread between two correct libraries and the nearest wrong package.
- No courtyard plus no 3D model is a cheap signature for a footprint drawn from memory. The visual gap remains: a rendered board showing pads rotated against the module outline is not checked by anything here.
Decision guide
Section titled “Decision guide”The same guide as a list:
- A footprint from outside the stock KiCad libraries: record where it came from (datasheet URL, LCSC number or EasyEDA id), or
pcb-checkfails it. - A part with an LCSC number: compare the footprint with the part’s EasyEDA footprint, then run the BOM check’s category and connector-family checks, hand-fit parts included.
- Every footprint: a closed courtyard with every pad inside it, following the KLC clearances; a cable connector within 0.5 mm of the board edge.
- Only then order.
Evidence
Section titled “Evidence”| Claim | How it was checked | Status |
|---|---|---|
| Rig passed ERC, DRC, BOM (10/10 part groups) and rotation (18/18) checks with the invented footprints | The rig’s plan document and commit history, 2026-11-19 | project result |
Rig pcb-check: 7 findings (U1, Q1, Q2, J2 no courtyard; U1 no source; J1 5.29 mm and J2 2.50 mm from the edge) | pcb-check on the committed routed board, 2026-11-20 | measured |
Rig fp-check: J2 6 vs 16 sites, spacings 3.00/11.00 vs 0.50/0.80/11.16 mm, 13.00 x 13.50 vs 6.57 x 12.36 mm; J3/J5 cut-strip notes | fp-check on the same board, 2026-11-20 | measured |
| Module footprint: 24 SMD sites, 2.5 mm pitch, 21.3 x 35.3 mm copper | The tool’s own site and pitch functions on U1, 2026-11-20 | measured |
| Module orientation and pitch wrong against the real part | The rig’s review | reported by the review, not re-measured here |
missing_courtyard defaults to ignore | kicad-cli 10.0.8 DRC on a board with no project file lists it under ignored_checks; rig and bundled templates set ignore | measured |
A footprint without courtyard is a violation unless exempt; insideCourtyard() rule function | KiCad PCB editor manual1 | documented |
| KLC courtyard: fully enclosed, 0.05 mm line, 0.01 mm grid, 0.25/0.5 mm clearances | KLC F5.32 | documented |
| Courtyard join tolerance matches KiCad (0.0178 mm closes, 0.0229 mm does not) | Tool tests against kicad-cli 10.0.8 malformed_courtyard on stock footprints | measured by the tool’s tests |
| Pad positions match kicad-cli’s IPC-D-356 export | Tool tests on boards with B.Cu parts at 30-270 deg | measured by the tool’s tests |
| BOM check covers hand-fit parts, categories, USB family; rig J2 fails | Tool tests; commit message of the fix with the live run | project result |
| EasyEDA endpoint, 10 mil units, 404 shape, CDN 403s | Tool docstring, probed 2026-11-20; EasyEDA format spec4 | measured + documented |
| Same-package land differences up to 16.7 %; 11 of 160 pairs fail at 10 %, 0 at 20 %; nearest wrong package 21.8 % | Tool docstring (144 pairs); re-run for this page over cached EasyEDA responses, 2026-11-20 (160 pairs) | measured |
| Fault rows | The tool suites and the keyboard project’s fault suite, 2026-11-20 | project result |
| Keyboard board passes both checks (302 / 225 footprints) | Commit message adding the checks to the keyboard board’s gates | project result |
| kicad-library-utils GPL-3.0, easyeda2kicad AGPL-3.0 | GitLab and GitHub API licence fields, 2026-11-2053 | documented |
Related docs
Section titled “Related docs”- Generating and checking the GRIDDLE LX PCB from code - the board-as-code pipeline, the report gate and the fault-injection method these checks plug into
- Ordering a 4-layer PCBA keyboard board from JLC - where the BOM and rotation checks run before an order
- Loop or graph: a sensor-gated coding-agent loop - the same idea for code: a check the agent cannot argue with decides when work is done
References
Section titled “References”-
KiCad, “PCB Editor: footprint properties and custom design rules,” KiCad 10.0 Documentation. https://docs.kicad.org/10.0/en/pcbnew/pcbnew.html ↩ ↩2 ↩3
-
KiCad, “F5.3 Courtyard layer requirements,” KiCad Library Convention. https://klc.kicad.org/footprint/f5/f5.3/ ↩ ↩2
-
uPesy, “easyeda2kicad.py,” GitHub. https://github.com/uPesy/easyeda2kicad.py ↩ ↩2 ↩3
-
EasyEDA, “EasyEDA PCB File Format,” EasyEDA Documents. https://docs.easyeda.com/en/DocumentFormat/3-EasyEDA-PCB-File-Format/ ↩ ↩2
-
KiCad, “kicad-library-utils,” GitLab. https://gitlab.com/kicad/libraries/kicad-library-utils ↩ ↩2