kicad-library-install

@@ -16,7 +16,7 @@ are cheap to avoid and expensive to debug. 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+- 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@@ -29,12 +29,11 @@ $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+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+When a restart is genuinely unwelcome, the live alternative is for the user to add it via **Preferences → Manage Footprint Libraries → Global**. That takes effect immediately without a restart. @@ -46,14 +45,14 @@ 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:+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+Prove it afterward by reading the first bytes, `(f p _ l` = `28 66 70 5F`, not `EF BB BF`:  ```powershell@@ -61,7 +60,7 @@ Prove it afterward by reading the first bytes — `(f p _ l` = `28 66 70 5F`, no ```  Back up before editing (`Copy-Item $file "$file.bak"`), and make the edit-idempotent — check for `(name "<Nick>")` before appending.+idempotent, check for `(name "<Nick>")` before appending.  ## 3. In `lib_symbols`, only the TOP-LEVEL symbol carries the library nickname @@ -76,7 +75,7 @@ Inside a `.kicad_sch`: ```  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+`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: @@ -87,17 +86,17 @@ 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+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+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:+Read the STEP's Z extent straight out of the file, no CAD tool needed:  ```python import re@@ -123,13 +122,13 @@ KiCad derives the library item name from the **filename** (`ADS1220IRVAR.kicad_m → `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+Same idea for the symbol's `Footprint` property, it must read+`<Nick>:<ItemName>` and point at the library you installed, not the one the source file happened to reference.  --- -## Verify headlessly — never by opening the GUI+## 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:@@ -143,11 +142,11 @@ kicad-cli sym export svg     --output _check/sym MyLib.kicad_sym  # symbol parse 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+**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:+To *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"@@ -157,13 +156,13 @@ msedge.exe --headless --disable-gpu --screenshot="out.png" --window-size=2000,14  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+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+`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". @@ -179,16 +178,16 @@ in the user's project folder. 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`+- **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+  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+- **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+and tell the user about every correction you make, they may want it reported upstream.