Kicad Helper

Modification

Scoring & Visual Analysis

Observability & Analysis

The scoring framework automatically renders PCB images alongside JSON results.

Visual Review Workflow

After running score_layout.py, you MUST complete a visual review:

1. Find renders: The JSON result contains metrics.render_paths in the visual category. The renders are in results/renders_<timestamp>/.
2. Read each PNG: Use the Read tool to view each rendered PNG (front_all.png, back_copper.png, copper_both.png).
3. Review checklist — evaluate and report on each:
   • Connector access: USB, barrel jacks, headers, test points at board edges with correct orientation (not facing inward)
   • Component grouping: Related components (e.g. buck converter + inductor + caps) placed close together
   • Trace routing: No unnecessary detours, avoid 90-degree corners, clean flow
   • Ground plane: B.Cu copper pour intact, no fragmentation from traces cutting through
   • Thermal management: Power ICs have thermal vias, adequate copper area
   • Silkscreen: Readable, not overlapping pads or other text
   • Board utilization: Components spread out efficiently, no wasted space
   • Mechanical fit: Mounting holes accessible, no components blocking board edges
4. Report findings: Include specific component references and locations for any issues found.

Session Tracking

Each score_layout.py run automatically records a board state snapshot in results/session.json. This tracks:

• Change classification: Each iteration is classified as NO_CHANGE, MINOR_TWEAK, MODERATE_REWORK, or MAJOR_REDESIGN based on component movement distances and counts.
• Token budget: Cumulative token usage across all iterations, plus tokens-per-score-point efficiency.
• Stagnation detection: If score spread is <1 point over 3 consecutive runs, a warning is printed suggesting a major redesign instead of continued tweaking.

Use python3 scripts/layout_session.py summary to review the full session history. Use --no-track on score_layout.py to skip recording.

Experiment Observability

The autoexperiment system collects detailed per-round data for post-run analysis:

• Round detail JSONs: .experiments/rounds/round_NNNN.json — full config, per-net routing results (timing, layer split, failure reasons), phase timings, DRC violations with (x,y) coordinates, placement scores
• Enriched JSONL: experiments.jsonl includes placement_ms, routing_ms, failed_net_names, grid_occupancy_pct
• GIF frames: Short-circuit markers (red X) overlaid on PCB snapshots; border color indicates kept (green), shorts (red), or discarded (gray)

Post-run analysis workflow:

1. Generate HTML report: python3 scripts/generate_report.py .experiments/ — interactive report with score timeline, round browser (click to expand per-net details), net failure analysis, shorts dashboard
2. Compare rounds: python3 scripts/diff_rounds.py .experiments/ 5 20 — shows config changes, score deltas, nets that changed routing status, DRC diff
3. DRC overlay: python3 scripts/render_drc_overlay.py board.kicad_pcb .experiments/rounds/round_0015.json — highlights violations on board render
4. Failure heatmap: python3 scripts/render_failure_heatmap.py .experiments/ board.kicad_pcb — shows where routing consistently fails
5. Live monitoring: python3 scripts/dashboard_app.py — Flask dashboard with auto-refreshing status, history table (with shorts/DRC columns), stagnation warnings

Important Rules

1. Always back up before modifying: Scripts that modify the PCB save to <filename>_modified.kicad_pcb by default. Pass --in-place to overwrite.
2. Units: The pcbnew API uses nanometers internally. Scripts accept millimeters and convert with pcbnew.FromMM() / pcbnew.ToMM().
3. After modification: Tell the user to reload the PCB in KiCad (File > Revert).
4. Do NOT modify .kicad_pcb files with text editing — always use these scripts or the pcbnew API.

Extending

To add a new script, write Python using pcbnew.LoadBoard(path) to load and board.Save(path) to save. Key API patterns:

import pcbnew

board = pcbnew.LoadBoard("file.kicad_pcb")

# Iterate footprints
for fp in board.Footprints():
    ref = fp.GetReferenceAsString()
    pos = fp.GetPosition()
    x_mm, y_mm = pcbnew.ToMM(pos.x), pcbnew.ToMM(pos.y)

# Iterate tracks
for track in board.GetTracks():
    width_mm = pcbnew.ToMM(track.GetWidth())
    layer = track.GetLayerName()
    net = track.GetNetname()

# Move a footprint
fp.SetPosition(pcbnew.VECTOR2I(pcbnew.FromMM(x), pcbnew.FromMM(y)))
fp.SetOrientationDegrees(angle)

# Save
board.Save("output.kicad_pcb")