aidanbrzezinski/KiCad_Library
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: aidanbrzezinski:83c5fa5e4011f80686c6897d9a7308e03c80383c
Branches Tags
aidanbrzezinski:main
...
compare: aidanbrzezinski:0df4e2a3828ed10af7ba5df5aae51962102bbe7f
Branches Tags
aidanbrzezinski:main

1 Commits
83c5fa5e40 ... 0df4e2a382

Author SHA1 Message Date
aidanbrzezinski
0df4e2a382 updated README.md 2026-03-08 14:39:49 -04:00
2 changed files with 233 additions and 202 deletions
Expand all files Collapse all files

432
README.md
View File

@@ -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
<!-- AUTO-GENERATED — do not edit this section manually -->
<!-- Updated automatically by GitHub Actions on push to symbols/ -->
<!-- Run locally: python3 .github/scripts/update_component_index.py -->
| 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 |

3
update_component_index.py
View File

@@ -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/
"""