groove/Part-DB-server
1
0
Fork 0
mirror of https://github.com/Part-DB/Part-DB-server.git synced 2026-05-20 18:31:33 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

Moved kicad:populate documentation to central docs

Browse source
This commit is contained in:
Jan Böhmer 2026-03-01 19:37:15 +01:00
parent 5cd5a3c22e
commit 5e3477f330
3 changed files with 31 additions and 183 deletions
Download patch file Download diff file Expand all files Collapse all files

183
contrib/kicad-populate/README.md
View file

@ -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>` | 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)

3
docs/usage/console_commands.md
View file

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

28
docs/usage/eda_integration.md
View file

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