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

410
README.md
View File

@@ -1,132 +1,118 @@
# AidanBrzezinski KiCad Library # AidanBrzezinski KiCad Library
Personal KiCad component library used as a git submodule across all projects. Personal KiCad component library. Used as a git submodule in all projects.
All symbols, footprints, and 3D models are verified against manufacturer datasheets.
--- ---
## Table of Contents ## 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) - [Cloning a Project That Uses This Library](#cloning-a-project-that-uses-this-library)
3. [Updating the Library From Within a Project](#updating-the-library-from-within-a-project) - [Adding This Library to a New Project](#adding-this-library-to-a-new-project)
4. [Adding New Components](#adding-new-components) - [Best Practices](#best-practices)
5. [Best Practices](#best-practices) - [Updating the Library Inside a Project](#updating-the-library-inside-a-project)
6. [Directory Structure](#directory-structure) - [Adding Components to the Library](#adding-components-to-the-library)
7. [Conventions](#conventions) - [Naming Conventions](#naming-conventions)
8. [Component Index](#component-index) - [Symbol Field Reference](#symbol-field-reference)
9. [Projects Using This Library](#projects-using-this-library) - [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 ```bash
# Add as submodule — lib/shared is the conventional mount point # Clone and initialise submodule in one step
git submodule add https://github.com/AidanBrzezinski/KiCad_Library lib/shared git clone --recurse-submodules https://git.lokislair.com/aidanbrzezinski/YourProject
# Commit the submodule reference # Or if you already cloned without it
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
git submodule update --init --recursive git submodule update --init --recursive
``` ```
--- To never think about this again, set this globally on your machine:
## 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
```bash ```bash
# Run from your project root git config --global submodule.recurse true
cp lib/shared/sym-lib-table ./sym-lib-table
cp lib/shared/fp-lib-table ./fp-lib-table
``` ```
### Step 2 — Commit them to your project repo After that, `git pull` and `git clone` always include submodule updates automatically.
```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.
> **If KiCad prompts about missing libraries on open:** the submodule was not > **If KiCad prompts about missing libraries on open:** the submodule was not
> initialised. Run `git submodule update --init --recursive` and reopen the project. > 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 ## Adding This Library to a New Project
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:
```bash ```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/sym-lib-table ./sym-lib-table
cp lib/shared/fp-lib-table ./fp-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** — **Never modify the symbol drawing for standard parts.**
this ensures a library change can never silently break an existing project. 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 **One component per commit where possible.**
git submodule status Makes git history readable and makes it easy to revert a bad footprint
# +a3f8c2d lib/shared (heads/main) without affecting anything else.
# ^ the hash is the exact commit your project uses
``` **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 ### Pull library updates into your project
```bash ```bash
cd lib/shared cd lib/shared
git pull origin main # fetch latest library changes git pull origin main
cd ../.. cd ../..
git add lib/shared git add lib/shared
git commit -m "lib: update shared library to latest" git commit -m "lib: update shared library to latest"
@@ -135,15 +121,12 @@ git push
### Make library changes from within a project ### Make library changes from within a project
When you need to add a component while working on a specific project:
```bash ```bash
# The submodule directory IS the library repo # The submodule directory IS the library repo
cd lib/shared 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 symbols/0_ic_logic.kicad_sym
git add Datasheets/SN74HC193.pdf
git commit -m "lib: add SN74HC193DR" git commit -m "lib: add SN74HC193DR"
git push origin main # pushes to the LIBRARY repo 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 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. one in the project repo advancing the pinned commit pointer.
**Always push the library commit before updating the project pointer.** ### Check which library commit your project is using
If you update the pointer before pushing, other machines cannot resolve the commit.
```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) ### Standard components (exist in KiCad global library)
``` ```
1. Open KiCad → Symbol Editor 1. KiCad → Symbol Editor
2. Find chip in global library (74xx, 4xxx, Device etc) 2. Find chip in global 74xx / 4xxx / Device library
3. Right click → Copy 3. Right click → Copy
4. Navigate to your 0_xx library in the left panel 4. Navigate to your 0_xx library → Right click → Paste
5. Right click 0_xx → Paste 5. Right click → Rename to full MPN including package suffix
6. Right click pasted symbol → Rename → full MPN (e.g. SN74HC193DR) e.g. SN74HC193 → SN74HC193DR
7. Double click symbol → Edit Symbol Fields: 6. Double click → Edit Symbol Fields:
Value: SN74HC193DR Value: SN74HC193DR
Footprint: 0_package_SO:SOIC-16_3.9x9.9mm_P1.27mm Footprint: 0_package_SO:SOIC-16_3.9x9.9mm_P1.27mm
Datasheet: ../../Datasheets/SN74HC193.pdf Datasheet: https://www.ti.com/lit/ds/symlink/sn74hc193.pdf
MPN: SN74HC193DR MPN: SN74HC193DR
Digikey_PN: 296-1191-1-ND Digikey_PN: 296-1191-1-ND
Manufacturer: Texas Instruments Manufacturer: Texas Instruments
Library_Source: KiCad 8.0 global 74xx lib Library_Source: KiCad 8.0 global 74xx lib
8. File → Save 7. File → Save
9. Download datasheet PDF → save as Datasheets/SN74HC193.pdf 8. Commit and push from inside lib/shared:
10. Commit from inside lib/shared:
git add symbols/0_ic_logic.kicad_sym Datasheets/SN74HC193.pdf git add symbols/0_ic_logic.kicad_sym
git commit -m "lib: add SN74HC193DR" git commit -m "lib: add SN74HC193DR"
git push origin main git push origin main
11. Update submodule pointer in project repo
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) ### Custom components (not in KiCad global library)
``` ```
1. Check SnapEDA: snapeda.com/search/?q=PARTNUMBER 1. Check SnapEDA: snapeda.com/search/?q=PARTNUMBER
2. If found on SnapEDA: 2. If found:
→ Download KiCad package (symbol + footprint + 3D model) → Download KiCad package (symbol + footprint + 3D model)
→ Import symbol into Symbol Editor → Import symbol → clean up to match KiCad style:
→ Clean up to match KiCad style: pin length 100mil, text size 1.27mm
pin length: 100mil inputs on left, outputs on right, power top/bottom
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 .kicad_mod → footprints/0_custom.pretty/
→ Copy .step → 3d_models/ → Copy .step → 3d_models/
3. If not found — draw manually: 3. If not found — draw from datasheet:
→ Symbol from datasheet pin table → Symbol from pin table
→ Footprint from datasheet mechanical drawing → Footprint from mechanical drawing
→ Verify footprint with calipers on physical part before committing PCB → Verify footprint with calipers on physical part before PCB layout
4. Same commit process as standard components 4. Set all fields and commit same as above
``` ```
### Commit message format ### Commit message format
``` ```
lib: add SN74HC193DR ← single new component lib: add SN74HC193DR
lib: add SN74HC193DR SN74HC163DR ← multiple components lib: add SN74HC193DR SN74HC163DR
lib: fix HV5622PG footprint pad spacing ← footprint correction lib: fix HV5622PG footprint pad spacing
lib: update SMBJ15A Digikey PN ← field update only lib: update SMBJ15A Digikey PN
lib: add 0_ic_analog category ← new library category lib: add 0_ic_analog category
``` ```
--- ---
## Best Practices ## Naming Conventions
**One component per commit where possible.** ### Symbol names
Makes git history readable and makes it easy to revert a bad footprint Always use the full MPN including package suffix:
without affecting anything else. ```
SN74HC193DR ✓ includes package suffix (SOIC-16)
SN74HC193 ✗ ambiguous — which package?
74HC193 ✗ missing manufacturer prefix
```
**Never modify the symbol drawing for standard parts.** ### Footprint file names
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 # Standard packages — KiCad convention
the schematic. SOIC-16_3.9x9.9mm_P1.27mm.kicad_mod
**Always verify custom footprints against physical parts.** # Custom parts — MPN + package
Draw from the datasheet first. When parts arrive, check with calipers before HV5622PG_DIP44.kicad_mod
sending PCB to fab. A pad spacing error costs a full board respin.
**Keep the library repo and project pointer in sync.** # Custom parts with no single MPN — function + mounting type
Push library commits before updating the project's submodule pointer. IN14_NixieTube_THT.kicad_mod
If you forget, other developers get a broken submodule reference. EC11_Encoder_THT.kicad_mod
```
**Update the sym-lib-table and fp-lib-table in the library when adding categories.** ### 3D model file names
Then re-copy them into any project that uses this library (see sync instructions above). Match the footprint name exactly:
This way all projects get the new category without manual GUI registration. ```
HV5622PG_DIP44.step
IN14_NixieTube_THT.step
```
**Never register libraries globally in KiCad for project-shared libraries.** ### Datasheet URLs
Global registration uses absolute paths that break on other machines. Always Always link directly to the manufacturer PDF, not a product page:
use `${KIPRJMOD}` via project-level table files as described above. ```
# Texas Instruments
https://www.ti.com/lit/ds/symlink/sn74hc193.pdf
**Add the Datasheets/ folder .gitignore if datasheet size becomes a concern.** # ON Semiconductor
For now all PDFs are committed directly. If the repo grows too large, https://www.onsemi.com/pdf/datasheet/mc74hc193a-d.pdf
switch to storing only datasheet URLs in the symbol Datasheet field instead.
# 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/ AidanBrzezinski_KiCad_Library/
@@ -307,10 +370,7 @@ AidanBrzezinski_KiCad_Library/
│ └── 0_custom.pretty/ # Non-standard parts: IN-14 HV5622 NCH6300HV EC11 │ └── 0_custom.pretty/ # Non-standard parts: IN-14 HV5622 NCH6300HV EC11
│ │
├── 3d_models/ # STEP and WRL 3D models (flat) ├── 3d_models/ # STEP and WRL 3D models (flat)
│ └── *.step / *.wrl │ └── *.step / *.wrl # Named by MPN or footprint name
│
├── Datasheets/ # Component datasheets
│ └── *.pdf # Named by MPN: SN74HC193.pdf
│ │
├── sym-lib-table # ← COPY TO PROJECT ROOT ├── sym-lib-table # ← COPY TO PROJECT ROOT
├── fp-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 ## 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 | | 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 ## Projects Using This Library
| Project | Repo | Submodule Commit | | Project | Repo |
|---|---|---| |---|---|
| Nixie Tube Clock | github.com/AidanBrzezinski/Nixie_Tube_Clock | — | | 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: Reads the following fields from each symbol:
Value, MPN, Digikey_PN, Manufacturer, Footprint, ki_description (or Description) 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 locally: python3 .github/scripts/update_component_index.py
Run in CI: triggered automatically on push to symbols/ Run in CI: triggered automatically on push to symbols/
""" """