94 lines
5.4 KiB
Markdown
94 lines
5.4 KiB
Markdown
---
|
|
name: kicad-port
|
|
description: "Project skill for porting the Raspberry Pi CM5IO reference design into this custom CM5 carrier board. Use this skill on EVERY schematic/PCB task in this repo: editing .kicad_sch, defining or changing pinouts and nets, adding/removing circuit blocks, or verifying a design change. It encodes the source-of-truth for CM5 pins, the s-expression editing rules, and the MANDATORY verify loop (kicad-cli ERC + kicad-happy analyzer + diff-vs-reference). Always consult this skill before editing any KiCad file here, and run the verify loop after."
|
|
---
|
|
|
|
# CM5 Carrier — Port Workflow
|
|
|
|
We are building a custom Raspberry Pi **CM5 carrier board** by porting the official
|
|
**CM5IO reference design**. Work is currently in the **schematic / pinout phase**.
|
|
|
|
This is a **diff-from-reference** project: every change starts from a known-good reference
|
|
and must stay electrically defensible against it. Claude is the *editor* (surgical s-expr
|
|
text edits); the tooling below is the *verifier*. Never edit without verifying.
|
|
|
|
## Source of truth (consult before any pin/net decision)
|
|
|
|
1. `cm5-datasheet.pdf` — authoritative CM5 module pinout, power sequencing, pin reservations.
|
|
2. `CM5_Carrier_Pinout_BOM.md` / `CM5_Carrier_Design.md` — this board's intended pin map and BOM.
|
|
3. `refs/CM5IO.kicad_sch` (+ `CM5_GPIO`, `CM5_HighSpeed`, `PCIe-M2` sub-sheets) — the reference
|
|
schematic we port FROM. Hierarchical design; sub-sheets are referenced by UUID.
|
|
|
|
If a pin assignment disagrees between the datasheet and any other doc, **the datasheet wins** —
|
|
flag the discrepancy, don't silently pick one.
|
|
|
|
## S-expression editing rules (footguns)
|
|
|
|
KiCad `.kicad_sch` / `.kicad_pcb` files are s-expression text — readable and Edit-able.
|
|
But:
|
|
|
|
- **NEVER hand-edit or hand-invent UUIDs.** Copy-pasting a symbol/sheet block as text and
|
|
reusing its UUID corrupts the schematic (KiCad treats duplicates as the same object).
|
|
If you need a new instance, generate a fresh UUID:
|
|
`python3 -c "import uuid; print(uuid.uuid4())"`
|
|
- **Hierarchical nets:** a net can carry multiple labels across sheets (the analyzer's `LB-001`
|
|
finding). Prefer one canonical label style per cross-sheet net; don't rename one half.
|
|
- **Power nets need a driver:** every power rail needs a power symbol or `PWR_FLAG`, or ERC fails.
|
|
- After ANY structural edit, re-run the verify loop below. A passing Edit is not a passing design.
|
|
- Coordinate edits through git. Another (context-free) agent may touch these files; commit small,
|
|
review diffs, never blind-overwrite a sheet you didn't just read.
|
|
|
|
## The verify loop (MANDATORY after every schematic change)
|
|
|
|
`python3` here is Homebrew 3.14 (the kicad-happy scripts require Python ≥ 3.10).
|
|
Scripts live under `~/.claude/skills/kicad/scripts/` (symlinked from `kicad-happy/`).
|
|
|
|
```bash
|
|
SCH=path/to/your.kicad_sch # the file you changed
|
|
KSCR=~/.claude/skills/kicad/scripts
|
|
|
|
# 1. KiCad's own ERC (the hard gate — must be clean before commit)
|
|
kicad-cli sch erc --exit-code-violations --output /tmp/erc.json --format json "$SCH"
|
|
# non-zero exit => fix or revert before proceeding.
|
|
|
|
# 2. kicad-happy structural review (catches what ERC won't: decoupling gaps,
|
|
# connector ground ratios, protocol/voltage mismatches, multi-label nets)
|
|
python3 $KSCR/analyze_schematic.py "$SCH" --text # human-readable
|
|
python3 $KSCR/analyze_schematic.py "$SCH" -o /tmp/head.json # machine-readable
|
|
|
|
# 3. Diff against the committed reference baseline to see what your change moved
|
|
python3 $KSCR/diff_analysis.py analysis/baseline/cm5io.json /tmp/head.json --text
|
|
```
|
|
|
|
Treat new WARN/ERROR findings in step 2/3 as regressions to justify or fix — not noise.
|
|
|
|
## Optional deeper checks
|
|
|
|
- **SPICE** (`spice` skill): validates analog subcircuits (regulator feedback dividers, RC/LC
|
|
filters, crystal load caps). Requires a simulator on PATH — **`ngspice` IS installed**
|
|
(`/opt/homebrew/bin/ngspice`) and the loop is validated end-to-end on the reference
|
|
(8 subcircuits pass, incl. the 5V→3.3V buck feedback divider). Run after the analyzer:
|
|
`python3 ~/.claude/skills/spice/scripts/simulate_subcircuits.py <analysis.json> -o sim.json`.
|
|
- **Datasheets** (`datasheets` skill): extract CM5 / IC specs from PDFs so analyzer findings are
|
|
`datasheet-backed` rather than `heuristic`. Start with `cm5-datasheet.pdf`.
|
|
|
|
## Schematic hygiene checklist (before declaring a sheet done)
|
|
|
|
- [ ] All nets named — no auto-generated `Net-(R1-Pad1)` names in the final design
|
|
- [ ] Power rails ALL_CAPS (`+3V3`, `+5V`, `GND`); active-low uses `n` prefix (`nRESET`, `nCS`)
|
|
- [ ] `PWR_FLAG` on every power net with no explicit driver
|
|
- [ ] No-connect markers on all intentionally unconnected pins
|
|
- [ ] Hierarchical port names match the nets they carry
|
|
- [ ] Reference designators follow convention (U/R/C/L/D/Q/J/SW/F/TP/BT), annotated by block
|
|
- [ ] Title block filled (project, rev, date, author, one-line description)
|
|
- [ ] Design notes added for non-obvious choices (pull-up values, protection ratings, placement)
|
|
- [ ] **ERC passes with zero errors** (step 1 above)
|
|
|
|
## Reference shelf (not wired into the loop)
|
|
|
|
- `MCP-KiCad/` — MCP server over `pcbnew` (SWIG). PCB/fabrication only, Linux/flatpak-first.
|
|
Ignore until layout phase, and even then prefer `kicad-cli pcb` over it.
|
|
- `kicad-claude-toolkit/` — greenfield "circuit-as-Python → PCB" generator + IPC bridge.
|
|
Built for new designs, not porting. Only its `schematic-hygiene` guidance (folded in above)
|
|
is relevant now.
|