aidanbrzezinski/KiCad_Library
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
83c5fa5e4011f80686c6897d9a7308e03c80383c
KiCad_Library/README.md

13 KiB
Raw Blame History

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.

Table of Contents

  1. Adding to a New Project
  2. Setting Up KiCad Library Tables
  3. Updating the Library From Within a Project
  4. Adding New Components
  5. Best Practices
  6. Directory Structure
  7. Conventions
  8. Component Index
  9. Projects Using This Library

Adding to a New Project

# Add as submodule — lib/shared is the conventional mount point
git submodule add https://github.com/AidanBrzezinski/KiCad_Library lib/shared

# 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:

# 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

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

# 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

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:

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

git submodule status
# +a3f8c2d lib/shared (heads/main)
#  ^ the hash is the exact commit your project uses

Pull library updates into your project

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:

# 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.

Directory Structure

AidanBrzezinski_KiCad_Library/
│
├── .github/
│   ├── workflows/
│   │   └── update_component_index.yml   # Auto-updates Component Index in README
│   └── scripts/
│       └── update_component_index.py    # Parser script — run locally or in CI
│
├── 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
│
├── 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
│
├── 3d_models/                           # STEP and WRL 3D models (flat)
│   └── *.step / *.wrl
│
├── 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

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
— — — — — —

0 components — populate by running update_component_index.py after adding symbols

Projects Using This Library

Project Repo Submodule Commit
Nixie Tube Clock github.com/AidanBrzezinski/Nixie_Tube_Clock —
Reference in New Issue View Git Blame Copy Permalink