kicad-library-install

@@ -0,0 +1,194 @@+---+name: kicad-library-install+description: Install/register a KiCad symbol or footprint library, or hand-generate .kicad_sch / .kicad_mod / .kicad_sym files, without silently corrupting the user's setup. Read BEFORE editing fp-lib-table or sym-lib-table, before writing a schematic programmatically, before repointing a footprint at a new 3D model, and before shipping generated KiCad files to a desktop. Covers the five failure modes that produce no useful error message - KiCad rewriting the lib tables on exit, a UTF-8 BOM disabling every library, lib_symbols sub-unit naming, a 3D model whose Z datum sinks the part into the board, and footprint name/filename mismatch - plus the headless kicad-cli verification loop that catches them. Triggers - install kicad library, register footprint library, fp-lib-table, sym-lib-table, add library to kicad, footprint not found, Cannot add U1, Failed to load schematic, library table UNINITIALIZED, 3d model inside the board, model sunk into pcb, step z offset, generate kicad_sch, write kicad_mod, kicad-cli verify.+---++# Installing KiCad libraries and generating KiCad files++Five traps. Each produces either no error message or a misleading one. All five+are cheap to avoid and expensive to debug.++---++## 1. NEVER edit the lib tables while KiCad is running++`fp-lib-table` / `sym-lib-table` (in `<config>/kicad/<ver>/`) are read **once at+startup** and **written back from memory on exit**. So editing them under a+running KiCad gives you the worst of both:++- the running instance never sees your new library — the user gets+  **"Cannot add U1 (footprint 'Nick:Part' not found)"** on Update PCB from+  Schematic, while the file on disk plainly contains the entry;+- on exit KiCad may overwrite the file with its older in-memory copy, silently+  deleting what you added.++**Always check first, and refuse if it is up:**++```powershell+$running = Get-Process -Name kicad,eeschema,pcbnew -ErrorAction SilentlyContinue+if ($running) { Write-Output "ABORT: KiCad is running (pids $($running.Id -join ','))"; exit 2 }+```++If it IS running, do not just print a note and continue — **stop and tell the+user to close KiCad first**. A warning buried in script output is not a+handoff. After they close it, re-verify the entry survived before declaring+success; if KiCad stripped it, re-add it then.++The live alternative, when a restart is genuinely unwelcome: the user adds it+via **Preferences → Manage Footprint Libraries → Global**. That takes effect+immediately without a restart.++## 2. The tables must be UTF-8 with NO BOM++PowerShell's `Set-Content -Encoding UTF8` writes a BOM. KiCad then reports:++```+Library table '.../sym-lib-table' has type UNINITIALIZED but expected SYMBOL; skipping+```++and skips **every** library in the file — not just yours. Write it explicitly:++```powershell+$utf8NoBom = New-Object System.Text.UTF8Encoding($false)+[System.IO.File]::WriteAllText($file, $text, $utf8NoBom)+```++Prove it afterward by reading the first bytes — `(f p _ l` = `28 66 70 5F`, not+`EF BB BF`:++```powershell+([System.IO.File]::ReadAllBytes($file)[0..3] | ForEach-Object { $_.ToString('X2') }) -join ' '+```++Back up before editing (`Copy-Item $file "$file.bak"`), and make the edit+idempotent — check for `(name "<Nick>")` before appending.++## 3. In `lib_symbols`, only the TOP-LEVEL symbol carries the library nickname++Inside a `.kicad_sch`:++```+(symbol "Adom_Machine:MachinePinLargeShort"      <- nickname, yes+    ...+    (symbol "MachinePinLargeShort_0_1" ...)      <- bare, NO nickname+    (symbol "MachinePinLargeShort_1_1" ...)      <- bare, NO nickname+)+```++Prefixing the sub-units makes eeschema reject the **entire file** with a bare+`Failed to load schematic` — no line number, no symbol name. When copying a+symbol out of a `.kicad_sym` into a schematic, rename only the first+occurrence:++```python+blk = blk.replace('(symbol "%s"' % name, '(symbol "%s:%s"' % (nick, name), 1)+```++## 4. Check a 3D model's Z datum before you point a footprint at it++KiCad's convention is **origin at the seating plane, body extending +Z**. Vendor+and CAD-exported STEP files frequently use a different datum — origin at the top+of the body, or at its centre. Point a footprint at one of those with+`(offset (xyz 0 0 0))` and the part renders **sunk into the board**. Nothing+errors; it just looks wrong in the 3D viewer, and the wrong geometry bakes into+any STEP/GLB you export downstream.++This bites hardest when you **swap** a model — e.g. repointing a footprint from+KiCad's stock `${KICAD*_3DMODEL_DIR}/Package_DFN_QFN.3dshapes/...` (authored to+KiCad convention) to a page's own vendor STEP. Measure before you swap.++Read the STEP's Z extent straight out of the file — no CAD tool needed:++```python+import re+s = open("part.step", errors="ignore").read()+z = [float(m[2]) for m in re.findall(+    r"CARTESIAN_POINT\s*\(\s*'[^']*'\s*,\s*\(\s*([-\dEe.+]+)\s*,\s*([-\dEe.+]+)\s*,\s*([-\dEe.+]+)\s*\)", s)]+print(min(z), max(z))   # also grep LENGTH_UNIT to confirm mm+```++| Z extent | Datum | Fix |+|---|---|---|+| `0 .. +h` | seating plane (KiCad) | none |+| `-h .. 0` | top of body | `(offset (xyz 0 0 h))` |+| `-h/2 .. +h/2` | body centre | `(offset (xyz 0 0 h/2))` |++Sanity-check `h` against the package height in the datasheet, and confirm X/Y are+centred on the origin while you are in there. `offset` xyz is in **mm** in the+current footprint format.++## 5. A footprint's internal name should match its filename++KiCad derives the library item name from the **filename** (`ADS1220IRVAR.kicad_mod`+→ `ADS1220IRVAR`). If the internal `(footprint "Some_Other_Name"` disagrees,+KiCad renames it on save and references drift. Set both to the same string.++Same idea for the symbol's `Footprint` property — it must read+`<Nick>:<ItemName>` and point at the library you actually installed, not the+one the source file happened to reference.++---++## Verify headlessly — never by opening the GUI++The user is usually running other work; launching KiCad steals focus (see+`foreground-etiquette`). `kicad-cli` proves everything from the command line:++```bash+kicad-cli sch export svg     --output _check f.kicad_sch   # does it parse at all?+kicad-cli sch export netlist --output _check/net.net f.kicad_sch  # do footprints RESOLVE?+kicad-cli sch erc            --output _check/erc.txt f.kicad_sch+kicad-cli fp  export svg     --output _check/fp  MyLib.pretty     # footprint parses?+kicad-cli sym export svg     --output _check/sym MyLib.kicad_sym  # symbol parses?+kicad-cli pcb drc            --output _check/drc.txt f.kicad_pcb  # loads fp-lib-table+```++**The netlist export is the load-bearing check** — it is what proves each+`Footprint` property resolves to a real file. An SVG can render fine while a+footprint reference is dangling.++To actually *look* at a sheet, rasterize the SVG headlessly and read the PNG:++```powershell+msedge.exe --headless --disable-gpu --screenshot="out.png" --window-size=2000,1420 "file:///.../sheet.svg"+```++### Run a control before blaming your file++If a generated file fails to load, run the identical command against a+**known-good existing project** first. That separates "my file is malformed"+from "the toolchain or the lib tables are broken" in one step — and in the BOM+case above, the control is what reveals that every library is skipped.++### Bisect parse failures++`Failed to load schematic` carries no location. Cut the file down — header+only, then header + `lib_symbols`, then + one symbol — and test each. Add a+hand-written trivial symbol as a control to separate "my embedding mechanics+are wrong" from "this particular source symbol is bad".++### Clean up++Delete the `_check` output directories when done. Do not leave scratch renders+in the user's project folder.++---++## Vendor/wiki-sourced parts are not automatically correct++Inspect a downloaded symbol before installing it. Real defects seen in shipped+parts:++- **OCR damage in pin names** — capital `I` read as `L`, zero as `O`+  (`ALN3/REFN1` for `AIN3/REFN1`, `REFNO` for `REFN0`). Pin *numbers* drive the+  netlist, so this is cosmetic — but it makes the schematic lie. Check names+  against the manufacturer datasheet.+- **Missing exposed-pad pin** — QFN/DFN footprints carry pad 17 (EP + thermal+  vias) while the symbol stops at 16, so the EP cannot be netted. Add it as a+  `power_in` pin.+- **A stray instance designator as the library reference prefix** (`U451`+  instead of `U`).++Compare symbol pin count against numbered footprint pads as a standing check,+and tell the user about every correction you make — they may want it reported+upstream.