diff --git a/README.md b/README.md index 7ea3e3d..8a5d1dc 100644 --- a/README.md +++ b/README.md @@ -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 | - | + + + + +| 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 | — | diff --git a/fp-lib-table b/fp-lib-table index 472db39..2c4050b 100644 --- a/fp-lib-table +++ b/fp-lib-table @@ -1,13 +1,24 @@ (fp_lib_table - (lib (name "0_capacitor_smd") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_capacitor_smd.pretty") (options "") (descr "SMD capacitors")) - (lib (name "0_resistor_smd") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_resistor_smd.pretty") (options "") (descr "SMD resistors")) - (lib (name "0_diode_smd") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_diode_smd.pretty") (options "") (descr "SMD diodes")) - (lib (name "0_package_SO") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_package_SO.pretty") (options "") (descr "SOIC SOP packages")) - (lib (name "0_package_QFP") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_package_QFP.pretty") (options "") (descr "QFP packages")) - (lib (name "0_package_SOT_TO") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_package_SOT_TO_SMD.pretty")(options "") (descr "SOT TO SMD packages")) - (lib (name "0_connector") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_connector.pretty") (options "") (descr "Connectors")) - (lib (name "0_switch_button") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_switch_button.pretty") (options "") (descr "Switches and buttons")) - (lib (name "0_transistor_fet") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_transistor_fet.pretty") (options "") (descr "Transistors FETs")) - (lib (name "0_testpoint") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_testpoint.pretty") (options "") (descr "Test points")) - (lib (name "0_switching_reg") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_switching_regulator.pretty")(options "") (descr "Switching regulator modules")) + (version 7) + (lib (name "0_package_SO") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_package_SO.pretty") (options "") (descr "SOIC SOP SSOP packages - standard IC packages")) + (lib (name "0_package_SOT_TO_SMD") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_package_SOT_TO_SMD.pretty") (options "") (descr "SOT-23 TO-252 TO-263 SMD transistor and regulator packages")) + (lib (name "0_package_QFP") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_package_QFP.pretty") (options "") (descr "QFP LQFP quad flat packages")) + (lib (name "0_package_DFN_QFN") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_package_DFN_QFN.pretty") (options "") (descr "DFN QFN leadless packages")) + (lib (name "0_package_SON") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_package_SON.pretty") (options "") (descr "SON small outline no-lead packages")) + (lib (name "0_capacitor_smd") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_capacitor_smd.pretty") (options "") (descr "SMD capacitor footprints - 0201 0402 0603 0805 etc")) + (lib (name "0_resistor_smd") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_resistor_smd.pretty") (options "") (descr "SMD resistor footprints - 0201 0402 0603 0805 etc")) + (lib (name "0_inductor_smd") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_inductor_smd.pretty") (options "") (descr "SMD inductor and ferrite bead footprints")) + (lib (name "0_diode_smd") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_diode_smd.pretty") (options "") (descr "SMD diode footprints - SOD SMA SMB SMC DO-214")) + (lib (name "0_led_smd") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_led_smd.pretty") (options "") (descr "SMD LED footprints")) + (lib (name "0_transistor_fet") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_transistor_fet.pretty") (options "") (descr "Transistor and FET footprints - SOT TO through-hole")) + (lib (name "0_connector") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_connector.pretty") (options "") (descr "All connector footprints - barrel jack JST XT60 pin headers")) + (lib (name "0_switch_button") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_switch_button.pretty") (options "") (descr "Switch and tactile button footprints")) + (lib (name "0_switching_regulator")(type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_switching_regulator.pretty") (options "") (descr "Switching regulator and power module footprints")) + (lib (name "0_interface_uart") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_interface_uart.pretty") (options "") (descr "Interface connector footprints - UART SPI I2C debug headers")) + (lib (name "0_testpoint") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_testpoint.pretty") (options "") (descr "Test point footprints")) + (lib (name "0_fiducials") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_fiducials.pretty") (options "") (descr "Fiducial marker footprints for pick and place")) + (lib (name "0_pad") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_pad.pretty") (options "") (descr "Bare copper pad footprints - heatsink pads thermal vias")) + (lib (name "0_net_tie") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_net_tie.pretty") (options "") (descr "Net tie footprints for intentional net connections")) + (lib (name "0_mousebites") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_mousebites.pretty") (options "") (descr "Mouse bite footprints for PCB panel breakaway tabs")) + (lib (name "0_custom") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/footprints/0_custom.pretty") (options "") (descr "Custom footprints with no standard KiCad equivalent - IN-14 HV5622 NCH6300HV EC11")) ) diff --git a/sym-lib-table b/sym-lib-table index 9efb649..b7dd56f 100644 --- a/sym-lib-table +++ b/sym-lib-table @@ -1,12 +1,13 @@ (sym_lib_table - (lib (name "0_ic_logic") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/symbols/0_ic_logic.kicad_sym") (options "") (descr "General logic ICs - 74xx 4xxx series")) - (lib (name "0_ic_mcu") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/symbols/0_ic_mcu.kicad_sym") (options "") (descr "Microcontrollers")) - (lib (name "0_ic_driver") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/symbols/0_ic_driver.kicad_sym") (options "") (descr "Motor drivers HV drivers gate drivers")) - (lib (name "0_ic_power") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/symbols/0_ic_power.kicad_sym") (options "") (descr "Regulators converters power management")) - (lib (name "0_ic_analog") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/symbols/0_ic_analog.kicad_sym") (options "") (descr "Op-amps comparators ADCs DACs")) - (lib (name "0_ic_rf") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/symbols/0_ic_rf.kicad_sym") (options "") (descr "RF ICs transceivers")) - (lib (name "0_ic_interface")(type "KiCad") (uri "${KIPRJMOD}/lib/shared/symbols/0_ic_interface.kicad_sym")(options "") (descr "CAN RS422 USB SPI interface ICs")) - (lib (name "0_passive") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/symbols/0_passive.kicad_sym") (options "") (descr "Resistors capacitors inductors crystals")) - (lib (name "0_connector") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/symbols/0_connector.kicad_sym") (options "") (descr "All connector types")) - (lib (name "0_discrete") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/symbols/0_discrete.kicad_sym") (options "") (descr "Diodes transistors buttons encoders")) + (version 7) + (lib (name "0_ic_logic") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/symbols/0_ic_logic.kicad_sym") (options "") (descr "General logic ICs - 74xx 4xxx series counters gates decoders latches")) + (lib (name "0_ic_mcu") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/symbols/0_ic_mcu.kicad_sym") (options "") (descr "Microcontrollers - STM32 RP2040 ATmega ESP32 etc")) + (lib (name "0_ic_driver") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/symbols/0_ic_driver.kicad_sym") (options "") (descr "Motor drivers HV drivers gate drivers LED drivers - HV5622 DRV8353 etc")) + (lib (name "0_ic_power") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/symbols/0_ic_power.kicad_sym") (options "") (descr "Voltage regulators buck boost converters power management - LM7805 NCH6300HV etc")) + (lib (name "0_ic_analog") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/symbols/0_ic_analog.kicad_sym") (options "") (descr "Op-amps comparators ADCs DACs analog ICs - LM358 TL072 MCP3204 etc")) + (lib (name "0_ic_rf") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/symbols/0_ic_rf.kicad_sym") (options "") (descr "RF ICs transceivers antennas - CC1101 nRF24L01 SX1276 etc")) + (lib (name "0_ic_interface")(type "KiCad") (uri "${KIPRJMOD}/lib/shared/symbols/0_ic_interface.kicad_sym") (options "") (descr "CAN RS-422 USB SPI I2C interface ICs - SN65HVD35 CP2102 etc")) + (lib (name "0_passive") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/symbols/0_passive.kicad_sym") (options "") (descr "Resistors capacitors inductors crystals ferrite beads")) + (lib (name "0_connector") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/symbols/0_connector.kicad_sym") (options "") (descr "All connector types - barrel jack JST XT60 pin headers USB etc")) + (lib (name "0_discrete") (type "KiCad") (uri "${KIPRJMOD}/lib/shared/symbols/0_discrete.kicad_sym") (options "") (descr "Diodes transistors MOSFETs buttons encoders - TVS Schottky MOSFET tactile etc")) ) diff --git a/update_component_index.py b/update_component_index.py new file mode 100644 index 0000000..c471bd7 --- /dev/null +++ b/update_component_index.py @@ -0,0 +1,213 @@ +#!/usr/bin/env python3 +""" +Parses all .kicad_sym files in symbols/ and updates the Component Index +table in README.md with the actual contents of the library. + +Reads the following fields from each symbol: + Value, MPN, Digikey_PN, Manufacturer, Footprint, ki_description (or Description) + +Run locally: python3 .github/scripts/update_component_index.py +Run in CI: triggered automatically on push to symbols/ +""" + +import re +import os +from pathlib import Path +from datetime import date + +SYMBOLS_DIR = Path("symbols") +README_PATH = Path("README.md") + +# Maps symbol filename (without extension) to a human-readable category label +LIBRARY_LABELS = { + "0_ic_logic": "0_ic_logic", + "0_ic_mcu": "0_ic_mcu", + "0_ic_driver": "0_ic_driver", + "0_ic_power": "0_ic_power", + "0_ic_analog": "0_ic_analog", + "0_ic_rf": "0_ic_rf", + "0_ic_interface": "0_ic_interface", + "0_passive": "0_passive", + "0_connector": "0_connector", + "0_discrete": "0_discrete", +} + +# Order categories should appear in the table +CATEGORY_ORDER = [ + "0_ic_logic", + "0_ic_driver", + "0_ic_power", + "0_ic_analog", + "0_ic_mcu", + "0_ic_rf", + "0_ic_interface", + "0_passive", + "0_connector", + "0_discrete", +] + + +def parse_field(symbol_block: str, field_name: str) -> str: + """Extract a named field value from a symbol block.""" + # KiCad sym format: (property "FieldName" "Value" ...) + pattern = rf'\(property\s+"{re.escape(field_name)}"\s+"([^"]*)"' + match = re.search(pattern, symbol_block) + return match.group(1).strip() if match else "" + + +def parse_symbols_from_file(filepath: Path) -> list[dict]: + """ + Parse all symbols from a .kicad_sym file. + Returns a list of dicts with keys: name, mpn, description, footprint, digikey_pn, manufacturer + """ + content = filepath.read_text(encoding="utf-8") + symbols = [] + + # Find all top-level symbol blocks + # Each starts with: (symbol "NAME" + symbol_pattern = re.compile(r'\(symbol\s+"([^"]+)"(?!\s+\(extends)', re.MULTILINE) + + matches = list(symbol_pattern.finditer(content)) + + for i, match in enumerate(matches): + name = match.group(1) + + # Skip sub-units (contain _ followed by digits at the end e.g. "SN74HC193_0_1") + # KiCad uses these internally for multi-unit symbols + if re.search(r'_\d+_\d+$', name): + continue + + # Extract the block for this symbol (up to next top-level symbol or end) + start = match.start() + end = matches[i + 1].start() if i + 1 < len(matches) else len(content) + block = content[start:end] + + mpn = parse_field(block, "MPN") or parse_field(block, "Value") or name + description = (parse_field(block, "ki_description") + or parse_field(block, "Description") + or parse_field(block, "description") + or "") + footprint = parse_field(block, "Footprint") + digikey_pn = parse_field(block, "Digikey_PN") or parse_field(block, "Digikey PN") or "-" + manufacturer = parse_field(block, "Manufacturer") or "-" + + # Shorten footprint for table readability — keep library:name but trim long paths + if footprint and ":" in footprint: + lib_part, fp_name = footprint.split(":", 1) + # Truncate very long footprint names + if len(fp_name) > 30: + fp_name = fp_name[:27] + "..." + footprint = f"{lib_part}:{fp_name}" + + symbols.append({ + "name": name, + "mpn": mpn, + "description": description, + "footprint": footprint or "-", + "digikey_pn": digikey_pn, + "manufacturer": manufacturer, + }) + + return symbols + + +def build_component_table(all_symbols: dict[str, list[dict]]) -> str: + """Build the full markdown component index table.""" + lines = [] + lines.append("| MPN | Description | Manufacturer | Symbol Library | Footprint | Digikey PN |") + lines.append("|---|---|---|---|---|---|") + + total = 0 + for category in CATEGORY_ORDER: + symbols = all_symbols.get(category, []) + if not symbols: + continue + for s in sorted(symbols, key=lambda x: x["mpn"]): + lines.append( + f"| {s['mpn']} " + f"| {s['description'] or '—'} " + f"| {s['manufacturer']} " + f"| {category} " + f"| {s['footprint']} " + f"| {s['digikey_pn']} |" + ) + total += 1 + + lines.append("") + lines.append(f"*{total} components — auto-generated {date.today().isoformat()}*") + return "\n".join(lines) + + +def update_readme(new_table: str) -> bool: + """ + Replace the content between the Component Index header and the next + top-level ## header in README.md with the new table. + Returns True if the file was changed. + """ + readme = README_PATH.read_text(encoding="utf-8") + + # Match from ## Component Index to the next ## section or end of file + pattern = re.compile( + r'(## Component Index\n+)(.*?)(\n## |\Z)', + re.DOTALL + ) + + match = pattern.search(readme) + if not match: + print("ERROR: Could not find '## Component Index' section in README.md") + return False + + original_block = match.group(2) + new_block = new_table + "\n\n" + + if original_block == new_block: + return False + + updated_readme = ( + readme[:match.start(2)] + + new_block + + readme[match.start(3):] + ) + + README_PATH.write_text(updated_readme, encoding="utf-8") + return True + + +def main(): + if not SYMBOLS_DIR.exists(): + print(f"ERROR: symbols/ directory not found. Run from repo root.") + return + + if not README_PATH.exists(): + print(f"ERROR: README.md not found. Run from repo root.") + return + + all_symbols: dict[str, list[dict]] = {} + + for sym_file in sorted(SYMBOLS_DIR.glob("*.kicad_sym")): + lib_name = sym_file.stem + symbols = parse_symbols_from_file(sym_file) + if symbols: + all_symbols[lib_name] = symbols + print(f" {lib_name}: {len(symbols)} symbol(s)") + else: + print(f" {lib_name}: empty") + + if not any(all_symbols.values()): + print("No symbols found — README not updated.") + return + + total = sum(len(v) for v in all_symbols.values()) + print(f"\nTotal: {total} symbols across {len(all_symbols)} libraries") + + table = build_component_table(all_symbols) + changed = update_readme(table) + + if changed: + print("\nREADME.md component index updated.") + else: + print("\nREADME.md already up to date.") + + +if __name__ == "__main__": + main() diff --git a/update_component_index.yml b/update_component_index.yml new file mode 100644 index 0000000..ccd2a80 --- /dev/null +++ b/update_component_index.yml @@ -0,0 +1,37 @@ +name: Update Component Index + +on: + push: + paths: + - 'symbols/**.kicad_sym' + workflow_dispatch: + +jobs: + update-index: + runs-on: ubuntu-latest + permissions: + contents: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Parse symbol libraries and update README + run: python3 .github/scripts/update_component_index.py + + - name: Commit updated README if changed + run: | + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + git add README.md + if git diff --staged --quiet; then + echo "No changes to component index." + else + git commit -m "docs: auto-update component index [skip ci]" + git push + fi