kicad-mcp/docs/autowire_guide.md

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

{
  "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:

{
  "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 (MIT, arashmparsa), which demonstrated the concept of automated wiring strategy selection. The mckicad implementation is original, built on the existing batch pipeline.