many eda additions

2026-06-29 16:31:02 -04:00
parent 818f965896
commit 6082613e88
41 changed files with 58827 additions and 1 deletions
--- a/.claude/skills/kicad-build/SKILL.md
+++ b/.claude/skills/kicad-build/SKILL.md
@@ -0,0 +1,144 @@
+# 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).
--- a/.claude/skills/kicad-port/SKILL.md
+++ b/.claude/skills/kicad-port/SKILL.md
@@ -0,0 +1,93 @@
+---
+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.