Add ADG936BCPZ, OSD32MP157F-1G-BAA, TPS22965DSGR, AXP2101; add programmatic API and usage guide
- scripts/mikilab_lib.py / mikilab_cli.py: typed Python API + JSON CLI
for add/update/remove/query, for other apps to integrate without
shelling out to add_component.py
- lib_common.py/import_component.py/import_batch.py: regenerate
sym-lib-table.global/fp-lib-table.global on every mutating call, not
just the project-local tables
- scripts/find_missing_3d_models.py: lists components with no 3D model
and search links to fill the gap
- docs/GUIDA_USO.md: practical Italian usage guide (companion to README.md)
- checkup fixes: removed orphan duplicate footprint
footprints/other/CP_20_1_ADI.kicad_mod, and a dangling
${easyeda2kicad}/tmp 3D model reference in AXP2101's footprint that
pointed at a file that never existed on disk
This commit is contained in:
@@ -0,0 +1,189 @@
|
||||
# Guida rapida all'uso della libreria MIKILAB
|
||||
|
||||
> Questa guida è il complemento pratico, in italiano, al `README.md` alla
|
||||
> radice del repository (che resta il riferimento tecnico completo, in
|
||||
> inglese, con anche la provenienza dettagliata di ogni componente).
|
||||
> Qui trovi solo "cosa fare" per i compiti di tutti i giorni.
|
||||
|
||||
## Cos'è
|
||||
|
||||
Una libreria KiCad personale e autonoma: simboli, footprint e modelli 3D
|
||||
per i progetti hardware di MIKILAB. Non dipende da nessun'altra cartella
|
||||
sul disco — puoi spostarla, zipparla o sincronizzarla su un'altra
|
||||
macchina e continua a funzionare.
|
||||
|
||||
```
|
||||
mikylab_kikad_library/
|
||||
├── sym-lib-table / fp-lib-table # registrano tutte le librerie
|
||||
├── symbols/<categoria>/<Nome>.kicad_sym
|
||||
├── footprints/<categoria>/<Nome>.pretty/<Nome>.kicad_mod
|
||||
├── 3dmodels/<categoria>/<Nome>.step
|
||||
├── scripts/ # tutti gli strumenti descritti qui sotto
|
||||
└── MANIFEST.csv # log di provenienza, una riga per file
|
||||
```
|
||||
|
||||
Categorie: `analog`, `audio`, `display`, `fpga_cpld`, `interface`,
|
||||
`logic`, `mechanical`, `memory`, `microcontrollers`, `other`, `power`,
|
||||
`rf`.
|
||||
|
||||
## 1. Installare la libreria in KiCad
|
||||
|
||||
**Un solo progetto** — se il tuo `.kicad_pro` sta dentro
|
||||
`mikylab_kikad_library/` (o copi `sym-lib-table`/`fp-lib-table` nella
|
||||
cartella del progetto), KiCad li trova da solo grazie a `${KIPRJMOD}`.
|
||||
Nessuna configurazione extra.
|
||||
|
||||
**Tutti i progetti** (consigliato per una libreria personale):
|
||||
|
||||
1. KiCad → Preferences → Configure Paths… → aggiungi `MIKILAB` che punta
|
||||
a `/Users/michelebigi/Development/mikylab_kikad_library`.
|
||||
2. Rigenera le tabelle "globali" ogni volta che aggiungi componenti:
|
||||
```
|
||||
python3 scripts/generate_global_tables.py
|
||||
```
|
||||
3. Copia le righe `(lib ...)` di `sym-lib-table.global` e
|
||||
`fp-lib-table.global` dentro le tabelle globali reali di KiCad
|
||||
(`~/Library/Preferences/kicad/10.0/sym-lib-table` e `fp-lib-table`),
|
||||
prima della parentesi finale. Vedi README §1 per lo script Python
|
||||
pronto che lo fa automaticamente (fai un backup prima).
|
||||
4. Riavvia KiCad.
|
||||
|
||||
## 2. Usare simboli e footprint
|
||||
|
||||
- Schematico: cerca `MIKILAB_<Libreria>:<Simbolo>`, es.
|
||||
`MIKILAB_TPS7A2012PDBVR:TPS7A2012PDBVR`.
|
||||
- PCB / footprint assignment: `MIKILAB_<Libreria>:<Footprint>`, es.
|
||||
`MIKILAB_SOT95P280X145_5N:SOT95P280X145-5N`.
|
||||
|
||||
Se un footprint non mostra il corpo 3D, quasi sempre è uno dei ~48 casi
|
||||
noti "`${KISBLIB}` gap" (footprint importati da fornitori il cui file
|
||||
STEP originale non era incluso nell'export) — vedi la sezione checkup o
|
||||
`python3 scripts/check_library.py` per l'elenco. Non è un errore da
|
||||
correggere subito: pad, courtyard e serigrafia restano corretti, manca
|
||||
solo la resa 3D.
|
||||
|
||||
## 3. Aggiungere un componente nuovo
|
||||
|
||||
**Un componente singolo** (hai già i file `.kicad_sym`/`.kicad_mod`/`.step`):
|
||||
|
||||
```
|
||||
python3 scripts/add_component.py \
|
||||
--name TPS7A2018PDBVR \
|
||||
--symbol /percorso/TPS7A2018PDBVR.kicad_sym \
|
||||
--footprint /percorso/SOT95P280X145-5N.kicad_mod \
|
||||
--model /percorso/TPS7A2018PDBVR.step \
|
||||
--category power
|
||||
```
|
||||
|
||||
`--footprint` e `--model` sono opzionali. `--category` è opzionale,
|
||||
viene auto-rilevata dal nome (altrimenti finisce in `other`).
|
||||
|
||||
**Da uno zip SnapEDA** ("Download KiCad"):
|
||||
```
|
||||
python3 scripts/import_snapeda.py --zip ~/Downloads/PARTNUMBER.zip [--category ...]
|
||||
```
|
||||
|
||||
**Da uno zip UltraLibrarian**:
|
||||
```
|
||||
python3 scripts/import_ultralibrarian.py --zip ~/Downloads/PARTNUMBER.zip [--category ...]
|
||||
```
|
||||
|
||||
**Molti componenti insieme**: una sottocartella per componente dentro
|
||||
una directory, poi:
|
||||
```
|
||||
python3 scripts/import_batch.py --source /percorso/batch_dir [--category power]
|
||||
```
|
||||
|
||||
Tutti gli importer: rifiutano di sovrascrivere un componente esistente
|
||||
(a meno di `--update`), deduplicano i footprint per contenuto (non per
|
||||
nome file), rigenerano le lib-table da zero e appendono una riga a
|
||||
`MANIFEST.csv` per ogni file toccato.
|
||||
|
||||
## 4. Aggiornare un componente esistente
|
||||
|
||||
Aggiungi `--update` allo stesso comando di import (qualunque sorgente:
|
||||
file locali, SnapEDA, UltraLibrarian) per sostituire in-place
|
||||
symbol/footprint/modello di un componente già presente, invece di
|
||||
ottenere l'errore "esiste già":
|
||||
|
||||
```
|
||||
python3 scripts/import_ultralibrarian.py --zip ~/Downloads/PARTNUMBER.zip --name NOME_ESISTENTE --update
|
||||
```
|
||||
|
||||
`--update` non cambia la categoria di un componente — per ricategorizzare
|
||||
serve `remove` + `add` nella nuova categoria (vedi §6).
|
||||
|
||||
## 5. Cercare / consultare componenti
|
||||
|
||||
Da riga di comando, senza scrivere Python:
|
||||
```
|
||||
python3 scripts/mikilab_cli.py list [--category power]
|
||||
python3 scripts/mikilab_cli.py find --query tps22 [--category power]
|
||||
python3 scripts/mikilab_cli.py get --name TPS7A2018PDBVR
|
||||
```
|
||||
Ogni comando stampa un JSON `{"ok": true, "data": ...}` su stdout.
|
||||
|
||||
Da Python, per integrare in un altro programma:
|
||||
```python
|
||||
import sys
|
||||
sys.path.insert(0, "/Users/michelebigi/Development/mikylab_kikad_library/scripts")
|
||||
import mikilab_lib as mikilab
|
||||
|
||||
mikilab.list_components(category="power")
|
||||
mikilab.find_components("tps22")
|
||||
mikilab.get_component("TPS7A2018PDBVR")
|
||||
```
|
||||
|
||||
## 6. Rimuovere / rinominare / ricategorizzare un componente
|
||||
|
||||
```
|
||||
python3 scripts/mikilab_cli.py remove --name NOME
|
||||
```
|
||||
oppure `mikilab.remove_component(name="NOME")` in Python. Per spostare un
|
||||
componente in un'altra categoria: `remove` seguito da un nuovo `add`
|
||||
(`--update`) nella categoria corretta.
|
||||
|
||||
## 7. Controllare l'integrità della libreria
|
||||
|
||||
Da lanciare dopo ogni import/modifica manuale, e comunque periodicamente:
|
||||
```
|
||||
python3 scripts/check_library.py
|
||||
```
|
||||
Verifica: struttura delle cartelle, sintassi di simboli/footprint,
|
||||
duplicati reali (per hash, non per nome), validità e portabilità dei
|
||||
riferimenti ai modelli 3D, sintassi e coerenza di
|
||||
`sym-lib-table`/`fp-lib-table`, e che ogni simbolo MIKILAB punti a un
|
||||
footprint esistente. Esce con `RESULT: OK` se non ci sono errori (i
|
||||
warning sono lacune note e documentate, non bloccanti — vedi README §4).
|
||||
|
||||
Per un elenco mirato dei componenti senza modello 3D (con link rapidi a
|
||||
SnapEDA/Octopart/UltraLibrarian per cercarlo):
|
||||
```
|
||||
python3 scripts/find_missing_3d_models.py
|
||||
```
|
||||
|
||||
## 8. Verificare che non ci siano percorsi assoluti o dipendenze esterne
|
||||
|
||||
La libreria non deve mai contenere percorsi assoluti né dipendere da
|
||||
`kicad-personal-library`. Puoi verificarlo in qualsiasi momento con:
|
||||
```
|
||||
grep -R "/Users/$(whoami)" --include="*.kicad_mod" --include="*.kicad_sym" .
|
||||
grep -R "kicad-personal-library" .
|
||||
```
|
||||
Entrambi i comandi devono restituire nessun risultato (a parte, per il
|
||||
secondo, le menzioni storiche nel README).
|
||||
|
||||
## Riferimento rapido comandi
|
||||
|
||||
| Cosa vuoi fare | Comando |
|
||||
|---|---|
|
||||
| Installare/aggiornare in tutti i progetti | `python3 scripts/generate_global_tables.py` |
|
||||
| Aggiungere un componente (file locali) | `python3 scripts/add_component.py --name ... --symbol ... [--footprint ...] [--model ...] [--category ...]` |
|
||||
| Aggiungere da zip SnapEDA | `python3 scripts/import_snapeda.py --zip ...` |
|
||||
| Aggiungere da zip UltraLibrarian | `python3 scripts/import_ultralibrarian.py --zip ...` |
|
||||
| Aggiungere molti componenti | `python3 scripts/import_batch.py --source ...` |
|
||||
| Aggiornare un componente esistente | aggiungi `--update` al comando di import |
|
||||
| Cercare un componente | `python3 scripts/mikilab_cli.py find --query ...` |
|
||||
| Rimuovere un componente | `python3 scripts/mikilab_cli.py remove --name ...` |
|
||||
| Controllare l'integrità della libreria | `python3 scripts/check_library.py` |
|
||||
| Trovare componenti senza modello 3D | `python3 scripts/find_missing_3d_models.py` |
|
||||
Reference in New Issue
Block a user