From 5e3477f330d23b0046254a5ee01c2827e2d94a7c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20B=C3=B6hmer?= Date: Sun, 1 Mar 2026 19:37:15 +0100 Subject: [PATCH] Moved kicad:populate documentation to central docs --- contrib/kicad-populate/README.md | 183 ------------------------------- docs/usage/console_commands.md | 3 + docs/usage/eda_integration.md | 28 +++++ 3 files changed, 31 insertions(+), 183 deletions(-) delete mode 100644 contrib/kicad-populate/README.md diff --git a/contrib/kicad-populate/README.md b/contrib/kicad-populate/README.md deleted file mode 100644 index bd918d14..00000000 --- a/contrib/kicad-populate/README.md +++ /dev/null @@ -1,183 +0,0 @@ -# KiCad Footprint & Symbol Populate Command - -A Symfony console command for Part-DB that bulk-populates KiCad footprint paths on Footprint entities and KiCad symbol paths on Category entities. - -## Overview - -Part-DB's KiCad EDA integration allows parts to inherit KiCad metadata from their Footprint and Category entities. This command automates populating those fields based on standard KiCad library paths. - -**What it does:** -- Maps footprint names (e.g., `SOT-23`, `0805`, `DIP-8`) to KiCad footprint library paths -- Maps category names (e.g., `Resistors`, `Capacitors`, `LED`) to KiCad symbol library paths -- Checks alternative names on entities when the primary name doesn't match -- Only updates empty values by default (use `--force` to overwrite) -- Supports dry-run mode to preview changes -- Supports custom mapping files to override or extend the built-in defaults - -## Installation - -The command is included with Part-DB. No additional installation steps needed. - -### Verify installation - -```bash -php bin/console list partdb:kicad -``` - -You should see: -``` -partdb:kicad:populate Populate KiCad footprint paths and symbol paths for footprints and categories -``` - -## Usage - -### List current values - -See what's currently in the database: - -```bash -php bin/console partdb:kicad:populate --list -``` - -### Preview changes (recommended first step) - -See what would be updated without making changes: - -```bash -php bin/console partdb:kicad:populate --dry-run -``` - -### Apply changes - -Update all empty footprint and category KiCad fields: - -```bash -php bin/console partdb:kicad:populate -``` - -### Options - -| Option | Description | -|--------|-------------| -| `--list` | List all footprints and categories with their current KiCad values | -| `--dry-run` | Preview changes without applying them | -| `--footprints` | Only update footprint entities | -| `--categories` | Only update category entities | -| `--force` | Overwrite existing values (default: only fills empty values) | -| `--mapping-file ` | Path to a JSON file with custom mappings (merges with built-in defaults) | - -### Examples - -```bash -# Only update footprints, preview first -php bin/console partdb:kicad:populate --footprints --dry-run - -# Only update categories -php bin/console partdb:kicad:populate --categories - -# Force overwrite all values (careful!) -php bin/console partdb:kicad:populate --force - -# Use a custom mapping file -php bin/console partdb:kicad:populate --mapping-file my_mappings.json -``` - -## Name Matching - -### Footprints (exact match) -Footprint names are matched exactly against the mapping keys. If the primary entity name doesn't match, the command also checks **alternative names** configured on the Footprint entity. - -For example, if a Footprint is named "SOT23" but has an alternative name "SOT-23", the mapping for "SOT-23" will be used. - -### Categories (pattern match) -Category names are matched using case-insensitive substring matching. A category named "Zener Diodes" will match the pattern "Zener". Order matters — more specific patterns are checked first. Alternative names on Category entities are also checked. - -## Custom Mapping Files - -You can provide a JSON file with `--mapping-file` to override or extend the built-in defaults. User mappings take priority over built-in ones. - -### JSON format - -```json -{ - "footprints": { - "MyCustomPackage": "MyLibrary:MyFootprint", - "0805": "Capacitor_SMD:C_0805_2012Metric" - }, - "categories": { - "Sensor": "Sensor:Sensor_Temperature", - "MCU": "MCU_Microchip:PIC16F877A" - } -} -``` - -Both `footprints` and `categories` keys are optional — you can provide just one. - -A reference file with all built-in defaults exported as JSON is available at [`default_mappings.json`](default_mappings.json). You can copy this file as a starting point for your own customizations. - -## Built-in Mappings - -### Footprints (~100 mappings) - -| Package Type | Examples | -|--------------|----------| -| SOT packages | SOT-23, SOT-23-5, SOT-23-6, SOT-223, SOT-89, SOT-323, SOT-363 | -| TO packages | TO-92, TO-220, TO-220AB, TO-247-3, TO-252, TO-263 | -| SOIC/TSSOP/MSOP | SOIC-8, SOIC-16, TSSOP-16, MSOP-16 | -| DIP | DIP-4 through DIP-40 | -| QFN/DFN | QFN-8 through QFN-48, DFN-2, DFN-6, DFN-8 | -| TQFP/LQFP | TQFP-32 through TQFP-100, LQFP variants | -| Chip sizes | 0201, 0402, 0603, 0805, 1206, 1210, 2512, etc. | -| Diode packages | SOD-123, SOD-323, SMA, DO-35, DO-41, etc. | -| Electrolytic caps | SMD (D4-D10mm), Through-hole (D5-D12.5mm) | -| Tantalum caps | Case A through Case E | -| LED packages | 3mm, 5mm, 0603, 0805, WS2812B | -| Crystal packages | HC-49, HC-49/S, HC-49/US | -| Connectors | USB-A/B/Mini/Micro/C, pin headers (1x2 to 2x20) | -| SIP packages | SIP-3 through SIP-5 | - -### Categories (~35 mappings) - -| Component Type | KiCad Symbol | -|----------------|--------------| -| Resistors | `Device:R` | -| Capacitors | `Device:C` | -| Electrolytic/Tantalum | `Device:C_Polarized` | -| Inductors | `Device:L` | -| Diodes | `Device:D` | -| Zener Diodes | `Device:D_Zener` | -| Schottky Diodes | `Device:D_Schottky` | -| TVS | `Device:D_TVS` | -| LEDs | `Device:LED` | -| NPN Transistors | `Device:Q_NPN_BCE` | -| PNP Transistors | `Device:Q_PNP_BCE` | -| N-MOSFETs | `Device:Q_NMOS_GDS` | -| P-MOSFETs | `Device:Q_PMOS_GDS` | -| Ferrite Beads | `Device:Ferrite_Bead` | -| Crystals | `Device:Crystal` | -| Oscillators | `Oscillator:Oscillator_Crystal` | -| Fuses | `Device:Fuse` | -| Relays | `Relay:Relay_DPDT` | -| Potentiometers | `Device:R_POT` | -| Thermistors | `Device:Thermistor` | -| Varistors | `Device:Varistor` | -| Op-Amps | `Amplifier_Operational:LM358` | -| Comparators | `Comparator:LM393` | -| Voltage Regulators | `Regulator_Linear:LM317_TO-220` | -| LDOs | `Regulator_Linear:AMS1117-3.3` | -| Optocouplers | `Isolator:PC817` | -| Connectors | `Connector:Conn_01x02` | -| Switches/Buttons | `Switch:SW_Push` | -| Transformers | `Device:Transformer_1P_1S` | - -## Backup Recommendation - -Always backup before running on production: - -```bash -php bin/console partdb:backup --database backup.zip -``` - -## License - -Same as Part-DB (AGPL-3.0) diff --git a/docs/usage/console_commands.md b/docs/usage/console_commands.md index 576b3314..bc9bb013 100644 --- a/docs/usage/console_commands.md +++ b/docs/usage/console_commands.md @@ -88,3 +88,6 @@ The value of the environment variable is copied to the settings database, so the * `php bin/console partdb:attachments:download`: Download all attachments that are not already downloaded to the local filesystem. This is useful to create local backups of the attachments, no matter what happens on the remote, and also makes picture thumbnails available for the frontend for them. + +## EDA integration commands +* `php bin/console partdb:kicad:populate`: Populate KiCad footprint paths and symbol paths for footprints and categories based on their names. Use `--dry-run` to preview changes without applying them, and `--list` to list current values. See the [EDA integration documentation](eda_integration.md) for more details. diff --git a/docs/usage/eda_integration.md b/docs/usage/eda_integration.md index 28386a91..b99ed4dd 100644 --- a/docs/usage/eda_integration.md +++ b/docs/usage/eda_integration.md @@ -87,3 +87,31 @@ To show more levels of categories, you can set this value to a higher number. If you set this value to -1, all parts are shown inside a single category in KiCad, without any subcategories. You can view the "real" category path of a part in the part details dialog in KiCad. + +### Kicad:populate command + +Part-DB also provides a command that attempts to automatically populate the KiCad symbol and footprint fields based on the part's category and footprint names. +This is especially useful if you have a large database and want to quickly assign symbols and footprints to parts without doing it manually. + +For this run `bin/console partdb:kicad:populate --dry-run` in the terminal, it will show you a list of suggestions for mappings for your existing categories and footprints. +It uses names and alternative names, when the primary name doesn't match, to find the right mapping. +If you are happy with the suggestions, you can run the command without the `--dry-run` option to apply the changes to your database. By default, only empty values are updated, but you can use the `--force` option to overwrite existing values as well. + +It uses the mapping under `assets/commands/kicad_populate_default_mappings.json` by default, but you can extend/override it by providing your own mapping file +with the `--mapping-file` option. +The mapping file is a JSON file with the following structure, where the key is the name of the footprint or category, and the value is the corresponding KiCad library path: +```json +{ + "footprints": { + "MyCustomPackage": "MyLibrary:MyFootprint", + "0805": "Capacitor_SMD:C_0805_2012Metric" + }, + "categories": { + "Sensor": "Sensor:Sensor_Temperature", + "MCU": "MCU_Microchip:PIC16F877A" + } +} +``` +Its okay if the file contains just one of the `footprints` or `categories` keys, so you can choose to only provide mappings for one of them if you want. + +It is recommended to take a backup of your database before running this command.