# kicad-build — PCB generation from opencode

Use this skill when building PCBs with the kicad-claude-toolkit inside opencode.
It wires KiCad's pcbnew (only available in KiCad's bundled Python) into opencode's
bash toolchain so you can generate .kicad_sch, .kicad_pcb, run ERC/DRC, and export
gerbers — all from opencode.

## Prerequisites

- KiCad.app installed at `/Applications/KiCad/KiCad.app`
- `kicad-cli` on PATH (`brew install kicad`)
- `ngspice` on PATH for simulation (`brew install ngspice`)
- `netlistsvg` on PATH for schematic SVG (`npm install -g netlistsvg`)
- Run `tools/install-kicad-toolkit` once to install circuit_toolkit into KiCad's Python

## Key paths

| What | Path |
|------|------|
| KiCad Python (has pcbnew) | `/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/3.9/bin/python3` |
| Launcher script | `tools/kicad-python` |
| Build orchestrator | `tools/kicad-build` |
| Install script | `tools/install-kicad-toolkit` |
| circuit_toolkit source | `kicad-claude-toolkit/python/circuit_toolkit` |
| S-expression editor | `tools/retire_block.py` |
| KiCad CLI | `/opt/homebrew/bin/kicad-cli` (or `kicad-cli` on PATH) |

## How it works

The toolkit has two layers:

1. **circuit_toolkit** (Python) — describes circuit topology (components, nets) and
   generates `.kicad_sch` / `.kicad_pcb` files. The PCB builder (`builders/pcb.py`)
   calls `pcbnew` directly, so it MUST run inside KiCad's Python.
2. **kicad-cli** (binary) — runs ERC, DRC, exports gerbers/BOM/PDF/netlist. Runs
   anywhere on PATH.

### The launcher

`tools/kicad-python` finds KiCad's Python and execs it. Use it for any script that
imports `pcbnew` or `circuit_toolkit.builders.pcb`:

```bash
./tools/kicad-python -c "from circuit_toolkit.builders.pcb import build_pcb"
./tools/kicad-python my_script.py
./tools/kicad-python -m circuit_toolkit.build board_dir/
```

### The build orchestrator

`tools/kicad-build <board-dir> [--all]` runs the full pipeline:

```
1. circuit_toolkit build → .kicad_sch + .kicad_pcb
2. kicad-cli sch erc     → ERC report
3. kicad-cli pcb drc     → DRC report
4. kicad-cli pcb export  → gerber + drill + position
5. kicad-cli sch export  → BOM + PDF + netlist
6. ngspice -b            → SPICE simulations (if sim/ present)
```

Output lands in `<board-dir>/output/`.

## Writing a board

A board is a Python script using `circuit_toolkit.blocks`:

```python
# my-board/build.py
from circuit_toolkit import Board
from circuit_toolkit.blocks import usbc_power, ams1117_ldo, led_indicator, pin_header, m2_mounting_hole

board = Board("my-board", size=(48, 30))
vbus, gnd, cc1, cc2 = usbc_power(board, ref="J1", cc_pulldowns="5.1k")
v3v3 = ams1117_ldo(board, ref="U1", vin=vbus, gnd=gnd, output_voltage=3.3)
led_indicator(board, ref_led="D1", ref_resistor="R3", vin=v3v3, gnd=gnd, color="red")
pin_header(board, ref="J2", pins=2, label="3V3_OUT", nets=[v3v3, gnd])
for ref in ("H1", "H2", "H3", "H4"):
    m2_mounting_hole(board, ref=ref)
```

Then run:
```bash
./tools/kicad-python build.py
```

A separate `layout.py` provides component positions + tracks + vias + zones, passed
to `build_pcb()`.

## Editing KiCad s-expressions directly

For surgical edits to `.kicad_sch` or `.kicad_pcb` s-expressions (removing blocks,
flooded net cleanup, no-connect markers), use `tools/retire_block.py`:

```bash
python3 tools/retire_block.py carrier/CM5IO.kicad_sch \
    --symbols J7,U18 --nets 'SD_*' \
    --apply
```

## Common opencode patterns

### Generate a PCB from a board definition
```bash
cd <board-dir>
./tools/kicad-python build.py
```

### Run ERC after schematic changes
```bash
kicad-cli sch erc *.kicad_sch --output output/erc/erc_report.txt
```

### Run DRC after layout changes
```bash
kicad-cli pcb drc *.kicad_pcb --output output/drc/drc_report.html
```

### Export gerbers for fab
```bash
kicad-cli pcb export gerbers *.kicad_pcb --output output/fab/gerber
kicad-cli pcb export drill *.kicad_pcb --output output/fab/gerber
kicad-cli pcb export pos *.kicad_pcb --output output/fab/positions.csv
```

### Render 3D PCB view
```bash
kicad-cli pcb render *.kicad_pcb -o output/3d.png
```

### SPICE simulation
```bash
ngspice -b -r output/sim/run.raw sim/circuit.cir
```

## Troubleshooting

- **"pcbnew not found"**: use `tools/kicad-python` instead of system python3
- **"kicad-cli not found"**: `brew install kicad`
- **"ngspice not found"**: `brew install ngspice`
- **KiCad updates**: re-run `tools/install-kicad-toolkit` after KiCad updates
- **Python 3.9 vs 3.10**: KiCad ships 3.9; toolkit pyproject says >=3.10. The
  `--no-build-isolation` flag in install-kicad-toolkit bypasses this (code is
  compatible with 3.9).