KiCad_Library/README.md

# 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](#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)

---

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

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

---

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

---

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

<!-- 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*

---

## Projects Using This Library

| Project | Repo | Submodule Commit |
|---|---|---|
| Nixie Tube Clock | github.com/AidanBrzezinski/Nixie_Tube_Clock | — |