From 0df4e2a3828ed10af7ba5df5aae51962102bbe7f Mon Sep 17 00:00:00 2001 From: aidanbrzezinski Date: Sun, 8 Mar 2026 14:39:49 -0400 Subject: [PATCH] updated README.md --- README.md | 432 ++++++++++++++++++++------------------ update_component_index.py | 3 + 2 files changed, 233 insertions(+), 202 deletions(-) diff --git a/README.md b/README.md index 8a5d1dc..92e9879 100644 --- a/README.md +++ b/README.md @@ -1,132 +1,118 @@ # AidanBrzezinski KiCad Library -Personal KiCad component library used as a git submodule across all projects. -All symbols, footprints, and 3D models are verified against manufacturer datasheets. +Personal KiCad component library. Used as a git submodule in all projects. --- ## Table of Contents -1. [Adding to a New Project](#adding-to-a-new-project) -2. [Setting Up KiCad Library Tables](#setting-up-kicad-library-tables) -3. [Updating the Library From Within a Project](#updating-the-library-from-within-a-project) -4. [Adding New Components](#adding-new-components) -5. [Best Practices](#best-practices) -6. [Directory Structure](#directory-structure) -7. [Conventions](#conventions) -8. [Component Index](#component-index) -9. [Projects Using This Library](#projects-using-this-library) + +- [Cloning a Project That Uses This Library](#cloning-a-project-that-uses-this-library) +- [Adding This Library to a New Project](#adding-this-library-to-a-new-project) +- [Best Practices](#best-practices) +- [Updating the Library Inside a Project](#updating-the-library-inside-a-project) +- [Adding Components to the Library](#adding-components-to-the-library) +- [Naming Conventions](#naming-conventions) +- [Symbol Field Reference](#symbol-field-reference) +- [Reference Designator Prefixes](#reference-designator-prefixes) +- [Value Field Conventions](#value-field-conventions) +- [Library Structure](#library-structure) +- [Component Index](#component-index) +- [Projects Using This Library](#projects-using-this-library) --- -## Adding to a New Project +## Cloning a Project That Uses This Library + +The library is a submodule — it does not download automatically with a plain clone. ```bash -# Add as submodule — lib/shared is the conventional mount point -git submodule add https://github.com/AidanBrzezinski/KiCad_Library lib/shared +# Clone and initialise submodule in one step +git clone --recurse-submodules https://git.lokislair.com/aidanbrzezinski/YourProject -# Commit the submodule reference -git add .gitmodules lib/shared -git commit -m "lib: add shared KiCad library as submodule" -git push -``` - -When cloning a project that uses this library: - -```bash -# Clone with submodules in one step -git clone --recurse-submodules https://github.com/AidanBrzezinski/YourProject - -# Or initialise submodules after a plain clone +# Or if you already cloned without it git submodule update --init --recursive ``` ---- - -## Setting Up KiCad Library Tables - -**This step is required every time you add this library to a new project.** - -KiCad locates symbol and footprint libraries through two plain-text table files: - -| File | Purpose | -|---|---| -| `sym-lib-table` | Registers all symbol libraries (.kicad_sym) | -| `fp-lib-table` | Registers all footprint libraries (.pretty folders) | - -**These files must live in the project root** — the same folder as the `.kicad_pro` file. -They cannot live inside the submodule. KiCad looks for them relative to the open project. - -### Step 1 — Copy the table files from the submodule into your project root +To never think about this again, set this globally on your machine: ```bash -# Run from your project root -cp lib/shared/sym-lib-table ./sym-lib-table -cp lib/shared/fp-lib-table ./fp-lib-table +git config --global submodule.recurse true ``` -### Step 2 — Commit them to your project repo - -```bash -git add sym-lib-table fp-lib-table -git commit -m "lib: add KiCad library table files" -git push -``` - -KiCad detects these files automatically the next time the project is opened. -Anyone who clones the project repo gets correct library registrations immediately — -no manual configuration required on their machine. +After that, `git pull` and `git clone` always include submodule updates automatically. > **If KiCad prompts about missing libraries on open:** the submodule was not > initialised. Run `git submodule update --init --recursive` and reopen the project. -> **If you add libraries manually via KiCad's GUI:** KiCad will modify these files. -> Commit the updated versions so other machines stay in sync. +--- -### Why `${KIPRJMOD}` and not an absolute path - -All paths in these table files use `${KIPRJMOD}` as the root: - -``` -${KIPRJMOD}/lib/shared/symbols/0_ic_logic.kicad_sym -``` - -`${KIPRJMOD}` is a KiCad built-in variable that always resolves to the folder -containing the `.kicad_pro` file, regardless of OS or where the repo is cloned. -Never replace this with an absolute path — it will break on every other machine. - -### Keeping table files in sync with the library - -If the library adds a new category and updates its own `sym-lib-table` or `fp-lib-table`, -re-copy them into your project root: +## Adding This Library to a New Project ```bash +# From your project root +git submodule add https://git.lokislair.com/aidanbrzezinski/KiCad_Library lib/shared + +# Copy the library table files into the project root cp lib/shared/sym-lib-table ./sym-lib-table cp lib/shared/fp-lib-table ./fp-lib-table -git add sym-lib-table fp-lib-table -git commit -m "lib: sync library table files from submodule" + +# Commit everything +git add .gitmodules lib/shared sym-lib-table fp-lib-table +git commit -m "lib: add shared KiCad library as submodule" +git push ``` +KiCad reads `sym-lib-table` and `fp-lib-table` from the project root automatically. +These files must live in the **project root** — not inside `lib/shared`. +Always use `${KIPRJMOD}` in paths, never an absolute path. +`${KIPRJMOD}` resolves to the project root on any machine regardless of OS or +directory structure, keeping the repo portable. + --- -## Updating the Library From Within a Project +## Best Practices -The submodule is pinned to a specific commit. It **never updates automatically** — -this ensures a library change can never silently break an existing project. +**Never modify the symbol drawing for standard parts.** +When copying from KiCad's global library, only change fields — never move pins, +resize the body, or change pin length. This keeps visual consistency across +every schematic that uses the library. -### Check which library commit your project is pinned to +**Always use the full MPN as the symbol name.** +`SN74HC193DR` not `SN74HC193` or `74HC193`. The package suffix matters — +it determines the footprint and is what gets ordered from Digikey. -```bash -git submodule status -# +a3f8c2d lib/shared (heads/main) -# ^ the hash is the exact commit your project uses -``` +**One component per commit where possible.** +Makes git history readable and makes it easy to revert a bad footprint +without affecting anything else. + +**Push library commit before updating the project pointer.** +If you update the pointer before pushing, other machines get a broken +submodule reference that cannot be resolved. + +**Verify custom footprints against the physical part before committing.** +Draw from the datasheet first. When parts arrive, check with calipers. +A pad spacing error costs a full board respin. + +**Re-copy table files when library categories are added.** +If `sym-lib-table` or `fp-lib-table` is updated in the library (new category added), +re-copy them into your project root and commit. See [Updating the Library](#updating-the-library-inside-a-project). + +**Never register this library globally in KiCad.** +Global registration uses absolute paths that break on other machines. +Always use project-level table files with `${KIPRJMOD}`. + +--- + +## Updating the Library Inside a Project + +The submodule is pinned to a specific commit and never updates automatically. +This is intentional — library changes cannot silently break an existing project. ### Pull library updates into your project ```bash cd lib/shared -git pull origin main # fetch latest library changes - +git pull origin main cd ../.. git add lib/shared git commit -m "lib: update shared library to latest" @@ -135,15 +121,12 @@ git push ### Make library changes from within a project -When you need to add a component while working on a specific project: - ```bash # The submodule directory IS the library repo cd lib/shared -# Make your changes — add symbol, footprint, datasheet +# Make changes — add symbol, footprint etc git add symbols/0_ic_logic.kicad_sym -git add Datasheets/SN74HC193.pdf git commit -m "lib: add SN74HC193DR" git push origin main # pushes to the LIBRARY repo @@ -154,111 +137,191 @@ git commit -m "lib: update shared library pointer" git push # pushes to the PROJECT repo ``` -This produces two commits — one in the library repo with the actual change, +Two commits are produced — one in the library repo with the actual change, one in the project repo advancing the pinned commit pointer. -**Always push the library commit before updating the project pointer.** -If you update the pointer before pushing, other machines cannot resolve the commit. +### Check which library commit your project is using + +```bash +git submodule status +# a3f8c2d lib/shared (heads/main) +# ^ this hash is the exact library commit your project is pinned to +``` + +### Re-sync table files after library structure changes + +```bash +cp lib/shared/sym-lib-table ./sym-lib-table +cp lib/shared/fp-lib-table ./fp-lib-table +git add sym-lib-table fp-lib-table +git commit -m "lib: sync library table files" +``` --- -## Adding New Components +## Adding Components to the Library ### Standard components (exist in KiCad global library) ``` -1. Open KiCad → Symbol Editor -2. Find chip in global library (74xx, 4xxx, Device etc) +1. KiCad → Symbol Editor +2. Find chip in global 74xx / 4xxx / Device library 3. Right click → Copy -4. Navigate to your 0_xx library in the left panel -5. Right click 0_xx → Paste -6. Right click pasted symbol → Rename → full MPN (e.g. SN74HC193DR) -7. Double click symbol → Edit Symbol Fields: +4. Navigate to your 0_xx library → Right click → Paste +5. Right click → Rename to full MPN including package suffix + e.g. SN74HC193 → SN74HC193DR +6. Double click → Edit Symbol Fields: - Value: SN74HC193DR - Footprint: 0_package_SO:SOIC-16_3.9x9.9mm_P1.27mm - Datasheet: ../../Datasheets/SN74HC193.pdf - MPN: SN74HC193DR - Digikey_PN: 296-1191-1-ND - Manufacturer: Texas Instruments - Library_Source: KiCad 8.0 global 74xx lib + Value: SN74HC193DR + Footprint: 0_package_SO:SOIC-16_3.9x9.9mm_P1.27mm + Datasheet: https://www.ti.com/lit/ds/symlink/sn74hc193.pdf + MPN: SN74HC193DR + Digikey_PN: 296-1191-1-ND + Manufacturer: Texas Instruments + Library_Source: KiCad 8.0 global 74xx lib -8. File → Save -9. Download datasheet PDF → save as Datasheets/SN74HC193.pdf -10. Commit from inside lib/shared: - git add symbols/0_ic_logic.kicad_sym Datasheets/SN74HC193.pdf - git commit -m "lib: add SN74HC193DR" - git push origin main -11. Update submodule pointer in project repo +7. File → Save +8. Commit and push from inside lib/shared: + + git add symbols/0_ic_logic.kicad_sym + git commit -m "lib: add SN74HC193DR" + git push origin main + +9. Update submodule pointer in the project repo: + + cd ../.. + git add lib/shared + git commit -m "lib: update shared library pointer" + git push ``` ### Custom components (not in KiCad global library) ``` 1. Check SnapEDA: snapeda.com/search/?q=PARTNUMBER -2. If found on SnapEDA: - → Download KiCad package (symbol + footprint + 3D model) - → Import symbol into Symbol Editor - → Clean up to match KiCad style: - pin length: 100mil - text size: 1.27mm - pins: inputs left, outputs right, power top/bottom - → Set all fields (same as standard components above) - → Copy .kicad_mod → footprints/0_custom.pretty/ - → Copy .step → 3d_models/ -3. If not found — draw manually: - → Symbol from datasheet pin table - → Footprint from datasheet mechanical drawing - → Verify footprint with calipers on physical part before committing PCB -4. Same commit process as standard components +2. If found: + → Download KiCad package (symbol + footprint + 3D model) + → Import symbol → clean up to match KiCad style: + pin length 100mil, text size 1.27mm + inputs on left, outputs on right, power top/bottom + → Copy .kicad_mod → footprints/0_custom.pretty/ + → Copy .step → 3d_models/ +3. If not found — draw from datasheet: + → Symbol from pin table + → Footprint from mechanical drawing + → Verify footprint with calipers on physical part before PCB layout +4. Set all fields and commit same as above ``` ### Commit message format ``` -lib: add SN74HC193DR ← single new component -lib: add SN74HC193DR SN74HC163DR ← multiple components -lib: fix HV5622PG footprint pad spacing ← footprint correction -lib: update SMBJ15A Digikey PN ← field update only -lib: add 0_ic_analog category ← new library category +lib: add SN74HC193DR +lib: add SN74HC193DR SN74HC163DR +lib: fix HV5622PG footprint pad spacing +lib: update SMBJ15A Digikey PN +lib: add 0_ic_analog category ``` --- -## Best Practices +## Naming Conventions -**One component per commit where possible.** -Makes git history readable and makes it easy to revert a bad footprint -without affecting anything else. +### Symbol names +Always use the full MPN including package suffix: +``` +SN74HC193DR ✓ includes package suffix (SOIC-16) +SN74HC193 ✗ ambiguous — which package? +74HC193 ✗ missing manufacturer prefix +``` -**Never modify the symbol drawing for standard parts.** -When copying from KiCad's global library, only change fields — never move pins, -resize the body, or change pin length. This keeps visual consistency across -the schematic. +### Footprint file names +``` +# Standard packages — KiCad convention +SOIC-16_3.9x9.9mm_P1.27mm.kicad_mod -**Always verify custom footprints against physical parts.** -Draw from the datasheet first. When parts arrive, check with calipers before -sending PCB to fab. A pad spacing error costs a full board respin. +# Custom parts — MPN + package +HV5622PG_DIP44.kicad_mod -**Keep the library repo and project pointer in sync.** -Push library commits before updating the project's submodule pointer. -If you forget, other developers get a broken submodule reference. +# Custom parts with no single MPN — function + mounting type +IN14_NixieTube_THT.kicad_mod +EC11_Encoder_THT.kicad_mod +``` -**Update the sym-lib-table and fp-lib-table in the library when adding categories.** -Then re-copy them into any project that uses this library (see sync instructions above). -This way all projects get the new category without manual GUI registration. +### 3D model file names +Match the footprint name exactly: +``` +HV5622PG_DIP44.step +IN14_NixieTube_THT.step +``` -**Never register libraries globally in KiCad for project-shared libraries.** -Global registration uses absolute paths that break on other machines. Always -use `${KIPRJMOD}` via project-level table files as described above. +### Datasheet URLs +Always link directly to the manufacturer PDF, not a product page: +``` +# Texas Instruments +https://www.ti.com/lit/ds/symlink/sn74hc193.pdf -**Add the Datasheets/ folder .gitignore if datasheet size becomes a concern.** -For now all PDFs are committed directly. If the repo grows too large, -switch to storing only datasheet URLs in the symbol Datasheet field instead. +# ON Semiconductor +https://www.onsemi.com/pdf/datasheet/mc74hc193a-d.pdf + +# Microchip +https://ww1.microchip.com/downloads/en/DeviceDoc/HV5622.pdf +``` + +TI pattern: `https://www.ti.com/lit/ds/symlink/LOWERCASE_MPN.pdf` --- -## Directory Structure +## Symbol Field Reference + +Every symbol must have these fields populated before committing: + +| Field | Example | Notes | +|---|---|---| +| Value | `SN74HC193DR` | Full MPN including package suffix | +| Footprint | `0_package_SO:SOIC-16_3.9x9.9mm_P1.27mm` | Library nickname : footprint name | +| Datasheet | `https://www.ti.com/lit/ds/symlink/sn74hc193.pdf` | Direct PDF link — manufacturer only | +| MPN | `SN74HC193DR` | Exact manufacturer part number | +| Digikey_PN | `296-1191-1-ND` | Digikey PN at time of addition | +| Manufacturer | `Texas Instruments` | Manufacturer name | +| Library_Source | `KiCad 8.0 global 74xx lib` | Where the symbol drawing came from | + +--- + +## Reference Designator Prefixes + +| Component | Prefix | +|---|---| +| All ICs (logic, power, driver, MCU) | U | +| Resistors | R | +| Capacitors | C | +| Inductors | L | +| Diodes | D | +| Crystals | Y | +| Connectors | J | +| Switches / buttons | SW | +| Transistors / FETs | Q | +| Test points | TP | +| Nixie tubes | NX | +| Ferrite beads | FB | + +--- + +## Value Field Conventions + +| Component | Value field contains | +|---|---| +| ICs | Full MPN — `SN74HC193DR` | +| Resistors | `10k`, `4.7k`, `100R` | +| Capacitors | `100nF 50V`, `10uF 25V` | +| Crystals | `32.768kHz` | +| Diodes | MPN — `SMBJ15A` | +| Connectors | Function — `12V_IN` | +| Buttons | Function — `SW_CYCLE` | + +--- + +## Library Structure ``` AidanBrzezinski_KiCad_Library/ @@ -307,10 +370,7 @@ AidanBrzezinski_KiCad_Library/ │ └── 0_custom.pretty/ # Non-standard parts: IN-14 HV5622 NCH6300HV EC11 │ ├── 3d_models/ # STEP and WRL 3D models (flat) -│ └── *.step / *.wrl -│ -├── Datasheets/ # Component datasheets -│ └── *.pdf # Named by MPN: SN74HC193.pdf +│ └── *.step / *.wrl # Named by MPN or footprint name │ ├── sym-lib-table # ← COPY TO PROJECT ROOT ├── fp-lib-table # ← COPY TO PROJECT ROOT @@ -321,49 +381,17 @@ AidanBrzezinski_KiCad_Library/ --- -## Conventions - -### Symbol fields — required on every component - -| Field | Example | Notes | -|---|---|---| -| Value | `SN74HC193DR` | Full MPN including package suffix | -| Footprint | `0_package_SO:SOIC-16_3.9x9.9mm_P1.27mm` | Registered nickname:footprint name | -| Datasheet | `../../Datasheets/SN74HC193.pdf` | Relative path from symbols/ folder | -| MPN | `SN74HC193DR` | Exact manufacturer part number | -| Digikey_PN | `296-1191-1-ND` | Digikey PN at time of addition | -| Manufacturer | `Texas Instruments` | Manufacturer name | -| Library_Source | `KiCad 8.0 global 74xx lib` | Where symbol drawing came from | - -### Symbol drawing rules -- Copied from KiCad global library → drawing unchanged, fields only -- Custom drawn → 100mil pin length, 1.27mm text, inputs left, outputs right -- Reference designator prefix must be set (U, R, C, D, SW, J etc) - -### Footprint rules -- Pad numbering must match symbol pin numbers exactly -- All layers present: F.Cu, F.Courtyard, F.Silkscreen, F.Fab -- 3D model path: `${KIPRJMOD}/lib/shared/3d_models/MPN.step` -- Dimensions verified against datasheet before committing - ---- - ## Component Index - - - - | MPN | Description | Manufacturer | Symbol Library | Footprint | Digikey PN | |---|---|---|---|---|---| -| — | — | — | — | — | — | +| 74LS192 | Synchronous 4-bit Up/Down (2 clk) counter | - | 0_ic_logic | - | - | -*0 components — populate by running update_component_index.py after adding symbols* +*1 components — auto-generated 2026-03-08* ---- ## Projects Using This Library -| Project | Repo | Submodule Commit | -|---|---|---| -| Nixie Tube Clock | github.com/AidanBrzezinski/Nixie_Tube_Clock | — | +| Project | Repo | +|---|---| +| Nixie Tube Clock | git.lokislair.com/aidanbrzezinski/Nixie_Tube_Clock | diff --git a/update_component_index.py b/update_component_index.py index c471bd7..c8e2c32 100644 --- a/update_component_index.py +++ b/update_component_index.py @@ -6,6 +6,9 @@ table in README.md with the actual contents of the library. Reads the following fields from each symbol: Value, MPN, Digikey_PN, Manufacturer, Footprint, ki_description (or Description) +Symbol Library column = which .kicad_sym file the symbol lives in. +Used to locate a symbol quickly in KiCad Symbol Editor. + Run locally: python3 .github/scripts/update_component_index.py Run in CI: triggered automatically on push to symbols/ """