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

```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.