145 lines
4.6 KiB
Markdown
145 lines
4.6 KiB
Markdown
# 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).
|