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

added automation, updated tables and read.me

Browse Source
This commit is contained in:
aidanbrzezinski
2026-03-03 15:26:13 -05:00
parent b9eb4abfdd
commit 83c5fa5e40
5 changed files with 592 additions and 152 deletions
Download Patch File Download Diff File Expand all files Collapse all files

440
README.md
View File

@@ -5,24 +5,256 @@ All symbols, footprints, and 3D models are verified against manufacturer datashe
---
## Usage
## 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)
Add to a project as a git submodule:
---
## Adding to a New Project
```bash
# Add as submodule — lib/shared is the conventional mount point
git submodule add https://github.com/AidanBrzezinski/KiCad_Library lib/shared
git submodule update --init --recursive
# 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
git submodule update --init --recursive
```
Register libraries in KiCad using the included `sym-lib-table` and `fp-lib-table` files,
or add manually via `Preferences → Manage Symbol/Footprint Libraries → Project Libraries`.
Always use `${KIPRJMOD}/lib/shared/...` as the path prefix.
---
## 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
# Run from your project root
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
```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
> 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:
```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 from submodule"
```
---
## Updating the Library From Within a Project
The submodule is pinned to a specific commit. It **never updates automatically** —
this ensures a library change can never silently break an existing project.
### Check which library commit your project is pinned to
```bash
git submodule status
# +a3f8c2d lib/shared (heads/main)
# ^ the hash is the exact commit your project uses
```
### Pull library updates into your project
```bash
cd lib/shared
git pull origin main # fetch latest library changes
cd ../..
git add lib/shared
git commit -m "lib: update shared library to latest"
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
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
# Return to project root and update the pointer
cd ../..
git add lib/shared
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,
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.
---
## Adding New Components
### Standard components (exist in KiCad global library)
```
1. Open KiCad → Symbol Editor
2. Find chip in global library (74xx, 4xxx, Device etc)
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:
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
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
```
### 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
```
### 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
```
---
## Best Practices
**One component per commit where possible.**
Makes git history readable and makes it easy to revert a bad footprint
without affecting anything else.
**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.
**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.
**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.
**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.
**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.
**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.
---
@@ -31,80 +263,58 @@ Always use `${KIPRJMOD}/lib/shared/...` as the path prefix.
```
AidanBrzezinski_KiCad_Library/
│
├── symbols/ # KiCad symbol libraries (.kicad_sym)
│ ├── 0_ic_logic.kicad_sym # 74xx, 4xxx series general logic
│ │ # SN74HC193, CD4060, SN74HC138 etc
│ ├── 0_ic_mcu.kicad_sym # Microcontrollers
│ │ # STM32, RP2040, ATmega etc
│ ├── 0_ic_driver.kicad_sym # Motor, HV, gate, LED drivers
│ │ # HV5622, DRV8353, ULN2003 etc
│ ├── 0_ic_power.kicad_sym # Regulators, converters, power management
│ │ # LM7805, NCH6300HV, TPS62172 etc
│ ├── 0_ic_analog.kicad_sym # Op-amps, comparators, ADCs, DACs
│ │ # LM358, MCP3204, TL072 etc
│ ├── 0_ic_rf.kicad_sym # RF ICs, transceivers, antennas
│ │ # CC1101, nRF24L01, SX1276 etc
│ ├── 0_ic_interface.kicad_sym # CAN, RS-422, USB, SPI interface ICs
│ │ # SN65HVD35, TCAN1051, CP2102 etc
│ ├── 0_passive.kicad_sym # Resistors, capacitors, inductors, crystals
│ │ # Generic R/C/L + specific crystals
│ ├── 0_connector.kicad_sym # All connector types
│ │ # Barrel jack, JST, XT60, headers etc
│ └── 0_discrete.kicad_sym # Diodes, transistors, buttons, encoders
│ # TVS, Schottky, MOSFET, tactile SW etc
├── .github/
│ ├── workflows/
│ │ └── update_component_index.yml # Auto-updates Component Index in README
│ └── scripts/
│ └── update_component_index.py # Parser script — run locally or in CI
│
├── footprints/ # KiCad footprint libraries (.pretty folders)
│ ├── 0_capacitor_smd.pretty/ # SMD capacitor footprints
│ │ └── *.kicad_mod
│ ├── 0_inductor_smd.pretty/ # SMD inductor footprints
│ │ └── *.kicad_mod
│ ├── 0_resistor_smd.pretty/ # SMD resistor footprints
│ │ └── *.kicad_mod
│ ├── 0_diode_smd.pretty/ # SMD diode footprints (SOD, SMA, SMB etc)
│ │ └── *.kicad_mod
│ ├── 0_led_smd.pretty/ # SMD LED footprints
│ │ └── *.kicad_mod
│ ├── 0_transistor_fet.pretty/ # Transistor and FET footprints
│ │ └── *.kicad_mod
│ ├── 0_package_SO.pretty/ # SOIC, SOP, SSOP packages
│ │ └── *.kicad_mod
│ ├── 0_package_QFP.pretty/ # QFP, LQFP packages
│ │ └── *.kicad_mod
│ ├── 0_package_DFN_QFN.pretty/ # DFN, QFN packages
│ │ └── *.kicad_mod
│ ├── 0_package_SOT_TO_SMD.pretty/ # SOT-23, TO-252, TO-263 packages
│ │ └── *.kicad_mod
│ ├── 0_package_SON.pretty/ # SON packages
│ │ └── *.kicad_mod
│ ├── 0_connector.pretty/ # Connector footprints
│ │ └── *.kicad_mod
│ ├── 0_switch_button.pretty/ # Switch and button footprints
│ │ └── *.kicad_mod
│ ├── 0_switching_regulator.pretty/# Switching regulator module footprints
│ │ └── *.kicad_mod
│ ├── 0_interface_uart.pretty/ # Interface connector footprints
│ │ └── *.kicad_mod
│ ├── 0_testpoint.pretty/ # Test point footprints
│ │ └── *.kicad_mod
│ ├── 0_fiducials.pretty/ # Fiducial marker footprints
│ │ └── *.kicad_mod
│ ├── 0_pad.pretty/ # Bare pad footprints
│ │ └── *.kicad_mod
│ ├── 0_net_tie.pretty/ # Net tie footprints
│ │ └── *.kicad_mod
│ └── 0_mousebites.pretty/ # Mouse bite footprints for panelisation
│ └── *.kicad_mod
├── symbols/ # KiCad symbol libraries (.kicad_sym)
│ ├── 0_ic_logic.kicad_sym # 74xx 4xxx general logic
│ ├── 0_ic_mcu.kicad_sym # Microcontrollers
│ ├── 0_ic_driver.kicad_sym # Motor HV gate LED drivers
│ ├── 0_ic_power.kicad_sym # Regulators converters
│ ├── 0_ic_analog.kicad_sym # Op-amps comparators ADCs DACs
│ ├── 0_ic_rf.kicad_sym # RF ICs transceivers
│ ├── 0_ic_interface.kicad_sym # CAN RS-422 USB interface ICs
│ ├── 0_passive.kicad_sym # R C L crystals
│ ├── 0_connector.kicad_sym # All connectors
│ └── 0_discrete.kicad_sym # Diodes transistors buttons encoders
│
├── 3d_models/ # STEP and WRL 3D models (flat structure)
│ ├── *.step # STEP models for 3D viewer and MCAD export
│ └── *.wrl # WRL models for photorealistic rendering
├── footprints/ # Footprint libraries (.pretty folders)
│ │ # Standard packages: populated as needed
│ │ # or reference KiCad global via ${KICAD8_FOOTPRINT_DIR}
│ ├── 0_package_SO.pretty/ # SOIC SOP SSOP
│ ├── 0_package_SOT_TO_SMD.pretty/ # SOT-23 TO-252 TO-263
│ ├── 0_package_QFP.pretty/ # QFP LQFP
│ ├── 0_package_DFN_QFN.pretty/ # DFN QFN
│ ├── 0_package_SON.pretty/ # SON
│ ├── 0_capacitor_smd.pretty/ # SMD capacitors
│ ├── 0_resistor_smd.pretty/ # SMD resistors
│ ├── 0_inductor_smd.pretty/ # SMD inductors
│ ├── 0_diode_smd.pretty/ # SMD diodes
│ ├── 0_led_smd.pretty/ # SMD LEDs
│ ├── 0_transistor_fet.pretty/ # Transistors FETs
│ ├── 0_connector.pretty/ # Connectors
│ ├── 0_switch_button.pretty/ # Switches buttons
│ ├── 0_switching_regulator.pretty/ # Regulator modules
│ ├── 0_interface_uart.pretty/ # Interface connectors
│ ├── 0_testpoint.pretty/ # Test points
│ ├── 0_fiducials.pretty/ # Fiducials
│ ├── 0_pad.pretty/ # Bare pads
│ ├── 0_net_tie.pretty/ # Net ties
│ ├── 0_mousebites.pretty/ # Panel breakaway tabs
│ └── 0_custom.pretty/ # Non-standard parts: IN-14 HV5622 NCH6300HV EC11
│
├── Datasheets/ # Component datasheets (PDF)
│ └── *.pdf # One PDF per unique part, named by MPN
├── 3d_models/ # STEP and WRL 3D models (flat)
│ └── *.step / *.wrl
│
├── sym-lib-table # KiCad symbol library registration file
├── fp-lib-table # KiCad footprint library registration file
├── CHANGELOG.md # Library revision history
├── Datasheets/ # Component datasheets
│ └── *.pdf # Named by MPN: SN74HC193.pdf
│
├── sym-lib-table # ← COPY TO PROJECT ROOT
├── fp-lib-table # ← COPY TO PROJECT ROOT
├── CHANGELOG.md
├── LICENSE
└── README.md
```
@@ -113,74 +323,42 @@ AidanBrzezinski_KiCad_Library/
## Conventions
### Symbols
- All symbols copied from KiCad global library retain the original drawing unchanged
- Only fields are modified — never pin positions, body size, or pin length
- Custom drawn symbols follow KiCad standard: 100mil pin length, 1.27mm text size
- Fields set on every symbol:
### 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` | Points to library footprint |
| Datasheet | `../../Datasheets/SN74HC193.pdf` | Local relative path |
| 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 part number at time of addition |
| 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 |
### Footprints
- All footprints verified against physical datasheet dimensions
- Courtyard, silkscreen, fab, and copper layers all present
- 3D model linked via `${KIPRJMOD}/lib/shared/3d_models/PartName.step`
- Pad numbering matches symbol pin numbering exactly
### 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)
### 3D Models
- Stored flat in `3d_models/` — no subfolders
- Named by MPN e.g. `SN74HC193DR.step`
- Referenced in footprints via `${KIPRJMOD}/lib/shared/3d_models/`
- Source noted in footprint description field (SnapEDA, manufacturer, KiCad built-in)
### Datasheets
- One PDF per unique MPN, named exactly by MPN e.g. `SN74HC193.pdf`
- Symbol Datasheet field points to local relative path
- Do not commit datasheets for parts with stable public URLs if file size is a concern
### Git Commits
- One component per commit where possible
- Commit message format: `lib: add SN74HC193DR symbol footprint and datasheet`
- Library structure changes committed separately from component additions
### 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 | Symbol Library | Footprint Library | Added |
|---|---|---|---|---|
| SN74HC193DR | 4-bit Up/Down BCD Counter | 0_ic_logic | 0_package_SO | - |
| SN74HC163DR | 4-bit Synchronous Binary Counter | 0_ic_logic | 0_package_SO | - |
| SN74HC138DR | 3-to-8 Line Decoder | 0_ic_logic | 0_package_SO | - |
| SN74HC132PWR | Quad NAND Schmitt Trigger | 0_ic_logic | 0_package_SO | - |
| SN74HC08DR | Quad 2-Input AND Gate | 0_ic_logic | 0_package_SO | - |
| SN74HC74DR | Dual D-type Flip-Flop | 0_ic_logic | 0_package_SO | - |
| SN74HC42DR | BCD-to-Decimal Decoder | 0_ic_logic | 0_package_SO | - |
| SN74HC373DR | Octal Transparent Latch | 0_ic_logic | 0_package_SO | - |
| SN74HC165DR | 8-bit Parallel-In Serial-Out Shift Reg | 0_ic_logic | 0_package_SO | - |
| SN74HC14DR | Hex Schmitt-Trigger Inverter | 0_ic_logic | 0_package_SO | - |
| MC74HC157ADR2G | Quad 2:1 Data Selector/MUX | 0_ic_logic | 0_package_SO | - |
| MC74HC04ADG | Hex Inverter | 0_ic_logic | 0_package_SO | - |
| MC74HC32ADR2G | Quad 2-Input OR Gate | 0_ic_logic | 0_package_SO | - |
| CD4060BM96 | 14-Stage Oscillator + Divider | 0_ic_logic | 0_package_SO | - |
| CD4020BM96 | 14-Stage Binary Ripple Divider | 0_ic_logic | 0_package_SO | - |
| CD4514BM96 | 4-to-16 Latch Decoder | 0_ic_logic | 0_package_SO | - |
| HV5622PG-G | 32-Ch HV Serial Shift Register | 0_ic_driver | 0_package_SO | - |
| NCH6300HV | Nixie HV Boost Converter | 0_ic_power | 0_switching_regulator | - |
| LM7805CT | 5V Linear Regulator | 0_ic_power | 0_package_SOT_TO_SMD | - |
| SMBJ15A | TVS Diode 15V | 0_discrete | 0_diode_smd | - |
| SS34 | Schottky Diode | 0_discrete | 0_diode_smd | - |
| EC11E15244B3 | Rotary Encoder | 0_discrete | 0_switch_button | - |
| B3F-4000 | Tactile Push Button | 0_discrete | 0_switch_button | - |
| PJ-002A | DC Barrel Jack 5.5mm/2.1mm | 0_connector | 0_connector | - |
<!-- 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 |
|---|---|---|---|---|---|
| — | — | — | — | — | — |
*0 components — populate by running update_component_index.py after adding symbols*
---
@@ -188,4 +366,4 @@ AidanBrzezinski_KiCad_Library/
| Project | Repo | Submodule Commit |
|---|---|---|
| Nixie Tube Clock | github.com/AidanBrzezinski/Nixie_Tube_Clock | - |
| Nixie Tube Clock | github.com/AidanBrzezinski/Nixie_Tube_Clock | — |