From 458583ee08a42159508fd818f420a3e2235eb584 Mon Sep 17 00:00:00 2001 From: Ryan Malloy Date: Mon, 9 Mar 2026 00:35:15 -0600 Subject: [PATCH] Add autowire documentation and update project structure Autowire guide covers the decision tree, threshold tuning, workflow patterns, and troubleshooting. CLAUDE.md updated to reflect the new autowire/ package and tools/autowire.py. --- CLAUDE.md | 5 + docs/autowire_guide.md | 218 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 223 insertions(+) create mode 100644 docs/autowire_guide.md diff --git a/CLAUDE.md b/CLAUDE.md index 81ea4a7..e437f93 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -26,7 +26,12 @@ src/mckicad/ __init__.py # __version__ only server.py # FastMCP 3 server + lifespan + module imports config.py # Lazy config functions (no module-level env reads) + autowire/ + __init__.py # Package init + strategy.py # Wiring decision tree: classify_net, crossing estimation + planner.py # NetPlan → apply_batch JSON conversion tools/ + autowire.py # autowire_schematic MCP tool (1 tool) schematic.py # kicad-sch-api: create/edit schematics (9 tools) project.py # Project discovery and structure (3 tools) drc.py # DRC checking + manufacturing constraints (4 tools) diff --git a/docs/autowire_guide.md b/docs/autowire_guide.md new file mode 100644 index 0000000..7ad887b --- /dev/null +++ b/docs/autowire_guide.md @@ -0,0 +1,218 @@ +# Autowire Guide + +This guide explains the `autowire_schematic` tool, which analyzes unconnected nets in a KiCad schematic and automatically selects the best wiring strategy for each one. + +## Overview + +The autowire tool provides a single-call alternative to manually deciding wire vs label vs power symbol for every net. It: + +1. Analyzes the schematic's netlist to find unconnected nets +2. Classifies each net into an optimal wiring strategy based on distance, fanout, crossings, and net name patterns +3. Generates a batch plan compatible with `apply_batch` +4. Optionally applies the wiring in one atomic operation + +Existing manual tools (`add_wire`, `connect_pins`, `add_label`, `apply_batch`) remain available for fine-grained control. Autowire is the "do the obvious thing" option. + +## Quick Reference + +| Task | Example Prompt | +|------|---------------| +| Preview wiring plan | `Autowire my schematic at /path/to/project.kicad_sch` | +| Apply wiring | `Autowire my schematic at /path/to/project.kicad_sch with dry_run=False` | +| Wire specific nets only | `Autowire only the SPI nets in my schematic` | +| Exclude power nets | `Autowire my schematic, excluding GND and VCC` | +| Adjust distance threshold | `Autowire with direct_wire_max_distance=30` | + +## How the Decision Tree Works + +For each unconnected net, the tool walks through these checks in order: + +| Priority | Condition | Strategy | Rationale | +|----------|-----------|----------|-----------| +| 1 | Power net (name matches GND/VCC/+3V3/etc, or pin type is `power_in`/`power_out`) | Power symbol | Standard KiCad convention for power rails | +| 2 | Single-pin net | No-connect flag | Avoids ERC warnings on intentionally unused pins | +| 3 | Cross-sheet net | Global label | Global labels are required for inter-sheet connectivity | +| 4 | High fanout (>5 pins by default) | Global label | Labels scale better than wire stars for many connections | +| 5 | Two-pin net, distance <= 10mm | Direct wire | Short enough that a wire is cleaner than a label | +| 6 | Two-pin net, distance > 50mm | Local label | Too far for a clean wire run | +| 7 | Two-pin net, mid-range with >2 crossings | Local label | Avoids visual clutter from crossing wires | +| 8 | Two-pin net, mid-range with few crossings | Direct wire | Wire is the simplest connection | +| 9 | 3-4 pin net | Local label | Star topology with labels is cleaner than a wire tree | + +All thresholds are tunable via tool parameters. + +## Using Autowire + +### Dry Run (Preview) + +Autowire defaults to `dry_run=True` — it shows you the plan without touching the schematic: + +``` +Autowire my schematic at ~/Projects/KiCad/amplifier/amplifier.kicad_sch +``` + +The response includes: +- **Strategy summary** — counts by method (e.g., 12 direct wires, 8 local labels, 4 power symbols, 2 no-connects) +- **Per-net plan** — each net's chosen method and the reasoning +- **Batch file** — the generated JSON written to `.mckicad/autowire_batch.json` + +### Applying the Plan + +Once you've reviewed the dry run, apply with: + +``` +Autowire my schematic at ~/Projects/KiCad/amplifier/amplifier.kicad_sch with dry_run=False +``` + +This calls `apply_batch` internally, which means you get collision detection, label placement optimization, and power symbol stub generation for free. + +### Filtering Nets + +To wire only specific nets: + +``` +Autowire only the MOSI, MISO, and SCK nets in my schematic +``` + +To exclude nets you've already wired manually: + +``` +Autowire my schematic, excluding USB_D_P and USB_D_N +``` + +To exclude entire components (e.g., a connector you want to wire by hand): + +``` +Autowire my schematic, excluding refs J1 and J2 +``` + +### Tuning Thresholds + +The default thresholds work well for typical schematics, but you can adjust them: + +| Parameter | Default | Effect | +|-----------|---------|--------| +| `direct_wire_max_distance` | 50.0mm | Pins farther apart than this get labels instead of wires | +| `crossing_threshold` | 2 | More crossings than this triggers label fallback | +| `high_fanout_threshold` | 5 | Nets with more pins than this get global labels | + +For dense boards with tight pin spacing: + +``` +Autowire my schematic with direct_wire_max_distance=25 and crossing_threshold=1 +``` + +For sparse layouts where longer wires are acceptable: + +``` +Autowire my schematic with direct_wire_max_distance=80 +``` + +## Understanding Results + +### Strategy Summary + +```json +{ + "strategy_summary": { + "direct_wire": 12, + "local_label": 8, + "global_label": 3, + "power_symbol": 6, + "no_connect": 2 + }, + "total_nets_classified": 31, + "nets_skipped": 45 +} +``` + +- **nets_skipped** includes already-connected nets plus any you excluded — these aren't counted in the classification total. + +### Per-Net Plan + +Each net entry explains the decision: + +```json +{ + "net": "SPI_CLK", + "method": "local_label", + "pin_count": 2, + "reason": "long distance (67.3mm > 50.0mm)" +} +``` + +The `reason` field traces which branch of the decision tree was taken, useful for understanding why a particular strategy was chosen. + +### Batch File + +The generated `.mckicad/autowire_batch.json` uses the same schema as `apply_batch`. You can inspect it, edit it, and apply it manually if you want to tweak individual connections before committing: + +``` +Show me the contents of .mckicad/autowire_batch.json +``` + +## Crossing Estimation + +The crossing estimator checks whether a proposed direct wire between two pins would cross existing wires. It uses axis-aligned segment intersection: a horizontal wire crosses a vertical wire when their X/Y ranges overlap (strict inequality — touching endpoints don't count). + +This keeps the schematic visually clean by falling back to labels when wires would create a tangled crossing pattern. + +## Power Net Detection + +Power nets are identified by two methods: + +1. **Name matching** — GND, VCC, VDD, VSS, +3V3, +5V, +12V, +1.8V, VBUS, VBAT, and variants (AGND, DGND, PGND, etc.) +2. **Pin type metadata** — if any pin on the net has `pintype` of `power_in` or `power_out` in the netlist, the net is treated as power regardless of its name + +This handles custom power rails that don't follow standard naming conventions. + +## Tips + +### Best Practices + +1. **Always dry-run first** — review the plan before applying. The default `dry_run=True` exists for a reason. +2. **Wire critical nets manually** — for sensitive analog paths, differential pairs, or impedance-controlled traces, use `add_wire` or `connect_pins` directly, then let autowire handle the rest. +3. **Use exclude_nets for partially-wired designs** — if you've already connected some nets, exclude them to avoid duplicate labels. +4. **Run ERC after autowiring** — `validate_schematic` confirms the wiring is electrically correct. + +### Workflow + +A typical autowire workflow: + +1. Place all components and set values/footprints +2. Wire critical signal paths manually (`connect_pins`, `add_wire`) +3. Run `autowire_schematic` in dry-run to preview +4. Review the plan — adjust thresholds or exclude specific nets if needed +5. Apply with `dry_run=False` +6. Run `validate_schematic` to verify +7. Open in KiCad to visually inspect + +## Troubleshooting + +### No Nets Classified + +If autowire reports 0 nets classified: + +1. **Check that kicad-cli is available** — autowire needs it to export the netlist. Set `KICAD_CLI_PATH` if needed. +2. **Verify the schematic has components** — an empty schematic has no nets to wire. +3. **Check if nets are already connected** — autowire skips nets that appear in the connectivity graph. Run `analyze_connectivity` to see what's already wired. + +### Wrong Strategy for a Net + +If a net gets classified incorrectly: + +1. **Check pin types in the netlist** — a pin with `power_in` type will force POWER_SYMBOL even if the net name is unusual. Export and inspect the netlist with `import_netlist`. +2. **Adjust thresholds** — if too many nets get labels when you want wires, increase `direct_wire_max_distance`. +3. **Use only_nets/exclude_nets** — wire the problematic net manually and exclude it from autowire. + +### Netlist Export Fails + +If the auto-export step fails: + +1. **Provide a pre-exported netlist** — use `export_netlist` to create one, then pass it as `netlist_path`. +2. **Check kicad-cli version** — KiCad 9+ is required for the `kicadsexpr` format. +3. **Check schematic validity** — run `validate_schematic` to catch structural issues. + +## Attribution + +The wiring strategy decision tree is informed by [KICAD-autowire](https://github.com/arashmparsa/KICAD-autowire) (MIT, arashmparsa), which demonstrated the concept of automated wiring strategy selection. The mckicad implementation is original, built on the existing batch pipeline.