Kicad Review

Design review: triple diff + rule canon

Triple diff (vs git baseline)

Implemented: cd $(kx root) && python3 -m kicad_lib.cli diff REV /abs/path/FILE.kicad_sch → JSON with semantic (symbols added/removed/moved/changed, labels, count deltas), pixel (changed_px + bbox_mm + composite path), erc_new/erc_gone. Artifacts land in ~/.cache/kx_scratch/ (never /tmp — flatpak kicad-cli can't see host /tmp): diff.png composite (grey = unchanged, red = removed, green = added). Crop the bbox_mm region and Read it as evidence.

Python API: probe() lives in kicad_lib.cli (NOT .source); diff.semantic_diff(probe_a, probe_b) takes its dicts. kx diff needs the FILE inside a git repo (baseline = revision); for two loose files call diff.render_png/pixel_diff/semantic_diff directly. Crop formula: px = mm * render_width_px / paper_width_mm (A4=297, A3=420; render default 2400 px wide).

Gotchas baked into kicad_lib/diff.py — keep them if reimplementing:

• kicad-cli --no-background-color SVGs rasterize to TRANSPARENT PNGs; flatten onto white before grayscale or convert("L") maps the whole background to black and the diff goes blind.
• ERC report lines normalize to type @(x mm, y mm); set-diff both ways.

Reading common ERC codes (fix, don't just silence)

• power_pin_not_driven — a power INPUT pin has no driver on its rail. NOT a wiring bug: add power:PWR_FLAG at the rail's passive source (connector/battery/regulator INPUT), one per rail. PWR_FLAG ≠ PWRGND (the latter is only a GND graphic). kx power-audit FILE lists rails + flag coverage. The exported netlist CANNOT detect this (it drops PWR_FLAG/power nodes) — trust ERC, not a netlist driver scan.
• pin_not_connected on block I/O / undriven inputs awaiting later wiring = expected-benign; keep in the baseline, judge only NEW entries. For a GENUINELY unused pin (spare gate, NC silicon pad), the fix is a No-Connect flag to document intent — never lower the rule's severity.
• no_connect_connected — a NC flag sits on a pin/node that IS wired; the flag and the wiring contradict. Fix = delete the flag (pin is used) OR the wire (pin isn't), not both. NC means "nothing else attaches here". (KiCad emits one entry at the flag and one at the connected pin.)
• missing_unit / missing_input_pin — a multi-unit part (dual/quad opamp, logic-gate pack) has an unplaced unit. Place EVERY unit; a SPARE you don't use still goes on a sheet AND gets tied off (opamp: in+ → GND, in− → out; logic: inputs to a defined level) or its inputs throw missing_input_pin. kx unit-audit FILE lists each multi-unit ref's placed-vs-expected units and front-runs ERC (it agrees on missing_unit); ERC stays the authority for whether a placed spare is actually tied off.

What headless ERC does NOT catch (verify separately — don't assume a green kicad-cli sch erc means these are clean):

• Duplicate reference designators & unannotated ? symbols — Annotation-tool checks, not ERC. kx ref-audit FILE (multi-unit aware) catches them; ERC stays 0/0 even with two R1s. (kicad.info t/32585)
• Power-driver gaps once a PWR_FLAG exists in the netlist export — see power_pin_not_driven above; use kx power-audit.

Rule canon — machine tier (verifier enforces)

grid 1.27 mm · no diagonals · junction dots at every connection · no cross-net touch/overlap · every pin on exactly one net · refs unique project-wide · ERC delta ∅ · netlist members == design intent.

Rule canon — render-judged tier (check on the PNG)

signal flow L→R · V+ up, GND down · power symbols not long wires · all text horizontal · decoupling caps adjacent to their IC · descriptive UPPERCASE net names · polarity marks visible · every IC pin accounted for (incl. explicit no-connects) · notes at non-obvious circuitry · title block filled · no text/symbol collisions at readable zoom.

Verdict format: PASS/FAIL per tier + per-finding file:line-equivalent (sheet + coordinates) + cropped evidence PNG paths.