---
title: "Autowiring"
description: "Automatically wire unconnected nets with optimal strategies"
---

The `autowire_schematic` tool analyzes unconnected nets in a KiCad schematic and automatically selects the best wiring strategy for each one. It provides a single-call alternative to manually deciding wire vs label vs power symbol for every net.

## 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 have 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 automatically.

### Filtering nets

To wire only specific nets:

```
Autowire only the MOSI, MISO, and SCK nets in my schematic
```

To exclude nets you have 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 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 are not 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.

### Batch file

The generated `.mckicad/autowire_batch.json` uses the same schema as `apply_batch`. You can inspect it, edit it manually, and apply it yourself 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 do not count).

This keeps the schematic visually clean by falling back to labels when wires would create crossing patterns.

## 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 do not follow standard naming conventions.

## Recommended 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

## Tips

- **Always dry-run first** -- review the plan before applying. The default `dry_run=True` exists for good reason.
- **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.
- **Use exclude_nets for partially-wired designs** -- if you have already connected some nets, exclude them to avoid duplicate labels.
- **Run ERC after autowiring** -- `validate_schematic` confirms the wiring is electrically correct.

## 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 is already wired.

### Wrong strategy for a net

1. **Check pin types in the netlist** -- a pin with `power_in` type will force POWER_SYMBOL even if the net name is unusual.
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

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.