# AidanBrzezinski KiCad Library

Personal KiCad component library. Used as a git submodule in all projects.

---

## Table of Contents

- [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)

---

## Cloning a Project That Uses This Library

The library is a submodule — it does not download automatically with a plain clone.

```bash
# Clone and initialise submodule in one step
git clone --recurse-submodules https://git.lokislair.com/aidanbrzezinski/YourProject

# Or if you already cloned without it
git submodule update --init --recursive
```

To never think about this again, set this globally on your machine:

```bash
git config --global submodule.recurse true
```

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.

---

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

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

---

## Best Practices

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

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

**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
cd ../..
git add lib/shared
git commit -m "lib: update shared library to latest"
git push
```

### Make library changes from within a project

```bash
# The submodule directory IS the library repo
cd lib/shared

# Make changes — add symbol, footprint etc
git add symbols/0_ic_logic.kicad_sym
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
```

Two commits are produced — one in the library repo with the actual change,
one in the project repo advancing the pinned commit pointer.

### 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 Components to the Library

### Standard components (exist in KiCad global library)

```
1. KiCad → Symbol Editor
2. Find chip in global 74xx / 4xxx / Device library
3. Right click → Copy
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:      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

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:
   → 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
lib: add SN74HC193DR SN74HC163DR
lib: fix HV5622PG footprint pad spacing
lib: update SMBJ15A Digikey PN
lib: add 0_ic_analog category
```

---

## Naming Conventions

### Symbol names
Always use the full MPN including package suffix:
```
SN74HC193DR      ✓   includes package suffix (SOIC-16)
SN74HC193        ✗   ambiguous — which package?
74HC193          ✗   missing manufacturer prefix
```

### Footprint file names
```
# Standard packages — KiCad convention
SOIC-16_3.9x9.9mm_P1.27mm.kicad_mod

# Custom parts — MPN + package
HV5622PG_DIP44.kicad_mod

# Custom parts with no single MPN — function + mounting type
IN14_NixieTube_THT.kicad_mod
EC11_Encoder_THT.kicad_mod
```

### 3D model file names
Match the footprint name exactly:
```
HV5622PG_DIP44.step
IN14_NixieTube_THT.step
```

### Datasheet URLs
Always link directly to the manufacturer PDF, not a product page:
```
# Texas Instruments
https://www.ti.com/lit/ds/symlink/sn74hc193.pdf

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

---

## 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/
│
├── .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                   # Named by MPN or footprint name
│
├── sym-lib-table                        # ← COPY TO PROJECT ROOT
├── fp-lib-table                         # ← COPY TO PROJECT ROOT
├── CHANGELOG.md
├── LICENSE
└── README.md
```

---

## Component Index

| MPN | Description | Manufacturer | Symbol Library | Footprint | Digikey PN |
|---|---|---|---|---|---|
| 74LS192 | Synchronous 4-bit Up/Down (2 clk) counter | - | 0_ic_logic | - | - |

*1 components — auto-generated 2026-03-08*


## Projects Using This Library

| Project | Repo |
|---|---|
| Nixie Tube Clock | git.lokislair.com/aidanbrzezinski/Nixie_Tube_Clock |