rpicarrierboard/.claude/skills/kicad-build/SKILL.md

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:

./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:

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

./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:

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

cd <board-dir>
./tools/kicad-python build.py

Run ERC after schematic changes

kicad-cli sch erc *.kicad_sch --output output/erc/erc_report.txt

Run DRC after layout changes

kicad-cli pcb drc *.kicad_pcb --output output/drc/drc_report.html

Export gerbers for fab

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

kicad-cli pcb render *.kicad_pcb -o output/3d.png

SPICE simulation

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