KiCad 10: come organizzo davvero le librerie di simboli e footprint

Le librerie diventano un problema soltanto dopo qualche anno

Se avete usato KiCad per parecchi progetti saprete certamente che creare un simbolo nuovo è la parte facile, il problema arriva molto dopo quando quel simbolo deve essere ritrovato, quando un footprint è stato corretto tre volte, quando la libreria ufficiale cambia ed aprendo un progetto di cinque anni prima non ricordiamo più se quel componente arrivasse da KiCad, da una libreria personale oppure da qualche directory copiata sul notebook che avevamo allora. È per questo che oggi considero l'organizzazione delle librerie una parte del progetto esattamente come lo schema, il PCB ed il firmware, perché una libreria non è una raccolta di disegni ma una DIPENDENZA del progetto e se non so da dove arriva non posso nemmeno essere certo di poter ricostruire quella scheda fra qualche anno.

KiCad 10 continua ad utilizzare due livelli distinti per simboli e footprint, ovvero una tabella globale ed una tabella specifica del progetto. Per i simboli il riferimento è sym-lib-table, per i footprint fp-lib-table, mentre ${KIPRJMOD} permette di riferire le librerie che stanno dentro la directory del progetto senza legarle ad un percorso assoluto della mia macchina. Questa separazione, che può sembrare soltanto una possibilità offerta dal programma, per me è diventata una regola: ciò che è veramente generale può stare fuori, ciò che serve a QUEL progetto deve poter viaggiare assieme al progetto.

Il nome deve dirmi cosa sto usando prima ancora di aprirlo

La disciplina sul naming nasce sempre nello stesso modo, cioè dopo avere scoperto che nomi come connettore_nuovo, rele2, modulo_ok oppure SO8_mio hanno un significato chiarissimo il giorno in cui vengono creati e diventano praticamente archeologia qualche anno dopo. La regola che applico oggi è che il nome deve identificare prima di tutto ciò che non posso permettermi di confondere, quindi famiglia o funzione quando serve, codice del componente quando il simbolo è specifico ed impronta fisica quando il footprint non è realmente generico. Se un package è un normale SOIC conforme ad una geometria standard posso utilizzare quello ufficiale, se invece sto costruendo il footprint di un modulo, di un trasformatore, di un connettore particolare oppure di un componente nel quale un millimetro sbagliato significa buttare il PCB allora il nome deve rendere evidente CHE COSA È e non soltanto assomigliare ad un nome comodo da digitare.

La mia convenzione reale di naming, quella accumulata negli anni sui progetti, va però riportata con i nomi che uso davvero e non sostituita con una convenzione inventata soltanto per rendere l'articolo più elegante: [DA INSERIRE: REGOLA DI NAMING REALE E DUE O TRE NOMI VERI DI SIMBOLI O FOOTPRINT]. È un dettaglio importante perché il valore di questa organizzazione non sta nel dire che bisogna essere ordinati, cosa abbastanza ovvia, ma nel mostrare una regola che ha già dovuto sopravvivere a progetti diversi ed agli errori che inevitabilmente si fanno.

Cosa tengo globale e cosa lascio chiuso dentro al progetto

Nelle librerie personali globali tengo soltanto ciò che considero realmente riutilizzabile, cioè componenti che ho già verificato e dei quali sono disposto ad accettare una sola definizione comune fra progetti diversi. Il concetto sembra banale ma cambia parecchio il modo di lavorare, perché se modifico un elemento globale devo partire dal presupposto che quella modifica possa interessare più schede. Un simbolo personale di uso generale, un footprint meccanico che ho controllato sul datasheet ed eventualmente anche sul componente reale oppure una parte che utilizzo ripetutamente possono quindi avere senso in una libreria comune.

Al contrario lascio nel progetto tutto ciò che nasce da una necessità specifica di quella scheda, soprattutto quando il componente è particolare, quando il footprint contiene scelte meccaniche legate al contenitore, quando ho modificato volutamente pad o serigrafia oppure quando non sono ancora sicuro che quell'oggetto meriti di diventare uno standard personale. Con ${KIPRJMOD} il progetto può puntare ad una propria libreria senza dipendere dal fatto che sul mio PC esista la stessa lettera di unità, lo stesso percorso oppure la stessa home directory, ed è esattamente il genere di dettaglio che sembra inutile finché non si clona il repository su un'altra macchina.

La mia struttura reale delle directory deve essere mostrata con i nomi veri perché altrimenti questo diventerebbe uno dei tanti articoli nei quali si inventano symbols, footprints e 3dmodels per fare una schermata ordinata: [DA INSERIRE: ALBERO DELLE DIRECTORY REALI]. Nello stesso punto inserirò anche il conteggio reale, oggi pari a [DA INSERIRE: NUMERO SIMBOLI PERSONALIZZATI] simboli personalizzati ed [DA INSERIRE: NUMERO FOOTPRINT PERSONALIZZATI] footprint, contando soltanto quelli che considero miei e non le copie provenienti dalle librerie ufficiali.

Le librerie ufficiali non le modifico

Questa è probabilmente la regola sulla quale sono meno disposto a fare eccezioni: NON MODIFICO MAI DIRETTAMENTE LE LIBRERIE UFFICIALI DI KICAD. Se trovo un simbolo ufficiale che voglio cambiare oppure un footprint che per il mio progetto deve essere diverso, ne creo una copia nella mia libreria e lavoro su quella. Il motivo non è soltanto l'ordine, è molto più concreto, perché le librerie ufficiali sono mantenute separatamente dal progetto KiCad ed evolvono assieme alle release, quindi una modifica locale dentro quel patrimonio prima o poi si trova a convivere con un aggiornamento, con una reinstallazione oppure con una nuova macchina.

KiCad 10 distribuisce le librerie ufficiali in repository separati per simboli, footprint, modelli 3D e template, ed il progetto mantiene versioni allineate alle release. Questo per me significa che l'ufficiale deve restare UFFICIALE. Posso usarlo, posso controllarlo ed eventualmente partire da lì per creare una variante personale, ma non voglio che un aggiornamento debba decidere se conservare una mia modifica nascosta dentro una libreria che non mi appartiene.

C'è anche un secondo motivo, meno evidente ma forse più importante: se apro un progetto su un'altra workstation devo sapere che Device:R significa ciò che KiCad intende per Device:R, non ciò che io ho deciso tre anni prima modificando accidentalmente la copia installata sul computer principale. Cambiare un elemento ufficiale senza cambiare anche la sua identità crea una specie di falsa compatibilità, il progetto sembra portabile ma in realtà dipende da una DIFFERENZA INVISIBILE.

Git deve conservare il progetto, non fotografare il caos della workstation

Le librerie specifiche del progetto, assieme ai relativi sym-lib-table e fp-lib-table, sono esattamente il tipo di file che voglio versionare con il progetto perché definiscono una parte necessaria a ricostruirlo. Lo stesso vale per eventuali modelli 3D personalizzati quando sono necessari al progetto e quando la loro licenza permette naturalmente di conservarli nel repository. Non considero invece sensato riversare dentro Git l'intera installazione delle librerie ufficiali soltanto per avere la sensazione di avere salvato tutto, perché quelle librerie hanno già un proprio versionamento ed una propria distribuzione.

Per le mie librerie globali il discorso è diverso: se sono davvero parte del mio patrimonio tecnico comune meritano un repository dedicato, con una cronologia propria e non copie differenti sparse dentro dieci progetti. In questo modo una correzione importante è una modifica identificabile, posso sapere quando è stata fatta ed eventualmente quale progetto utilizza ancora una versione precedente. La configurazione locale della workstation, le cache ed i file generati non devono invece diventare sorgenti soltanto perché KiCad li ha creati da qualche parte.

Anche qui preferisco non fingere una .gitignore che magari non coincide con quella che uso realmente. La mia situazione va riportata così: [DA INSERIRE: COSA VERSIONO REALMENTE IN GIT] mentre escludo [DA INSERIRE: COSA IGNORO REALMENTE]. Questa distinzione, una volta scritta con i file veri, vale molto più di una .gitignore universale copiata da Internet perché racconta ciò che serve a RICOSTRUIRE i miei progetti e ciò che invece appartiene soltanto alla macchina sulla quale sto lavorando.

Il problema che costa tempo arriva quando una dipendenza non sembra una dipendenza

Il caso più istruttivo sarebbe facile da inventare, per esempio raccontando di un footprint modificato, di un pad sbagliato e di una produzione da rifare. Ma non avrebbe alcun senso farlo, perché proprio questa parte dell'articolo deve nascere da un errore vero. L'episodio che va inserito è questo: [DA INSERIRE: EPISODIO REALE, PROGETTO COINVOLTO, COME ERA ORGANIZZATA MALE LA LIBRERIA, COSA È SUCCESSO IN PRODUZIONE, QUANTO TEMPO È STATO PERSO E QUALE REGOLA È NATA DA QUELL'ERRORE].

È qui che cambia il valore di tutto il discorso. Posso spiegare per pagine intere che una libreria globale deve contenere soltanto oggetti realmente comuni e che quella di progetto deve viaggiare assieme alla scheda, ma finché non si vede cosa succede quando un progetto dipende da un footprint che sul computer nuovo non esiste più oppure quando due oggetti con lo stesso nome non sono realmente uguali sembra ancora soltanto una questione di ordine. In produzione l'ordine smette di essere estetica e diventa RIPRODUCIBILITÀ.

Gli aggiornamenti di KiCad non devono diventare un test di coraggio

Un aggiornamento importante del programma non dovrebbe costringermi a sperare che le mie librerie personali siano ancora dove le avevo lasciate oppure che una modifica fatta anni prima dentro una libreria ufficiale sia sopravvissuta. È questo il motivo per cui tengo i confini separati. Le librerie ufficiali possono aggiornarsi secondo il ciclo di KiCad, le mie librerie comuni hanno il loro repository ed il loro ritmo, mentre una libreria specifica resta collegata al progetto che la richiede.

La documentazione di KiCad 10 distingue espressamente la tabella globale da quella specifica del progetto sia per i footprint sia per i simboli, quindi non sto forzando il programma ad un'organizzazione estranea al suo funzionamento, sto semplicemente usando quella separazione come una disciplina. Il file fp-lib-table del progetto rimane nella directory del progetto, lo stesso principio vale per sym-lib-table, ed utilizzando ${KIPRJMOD} posso evitare riferimenti assoluti che trasformerebbero il progetto in qualche cosa che funziona soltanto sul mio computer.

Le librerie sono anche una delle prime cose che l'automazione finisce per toccare

Nel mio articolo su Python e kicad-cli avevo mostrato come KiCad 10 possa essere trattato sempre meno come un semplice programma nel quale muovere oggetti con il mouse e sempre più come un sistema che possiamo interrogare, verificare ed inserire dentro pipeline. Le librerie sono una conseguenza naturale di quel discorso perché script, controlli e generazione automatica incontrano molto presto simboli, footprint, percorsi e dipendenze, ed una libreria organizzata male funziona finché c'è un essere umano davanti allo schermo che sa dove andare a cercare il file mancante.

Una pipeline invece non ricorda che tre anni fa avevo messo una libreria in una cartella sul disco D. O trova ciò che il progetto dichiara oppure fallisce, ed a pensarci bene è un vantaggio perché rende immediatamente visibili quelle dipendenze nascoste che nel lavoro manuale possiamo trascinarci dietro per anni. Per questo considero questo articolo la continuazione naturale di quello sull'automazione con Python e CLI, mentre nell'articolo precedente aggiungerò il collegamento di ritorno proprio nel punto nel quale parlo di progetti riproducibili e pipeline.

La regola finale è molto meno elegante di quanto sembri

Dopo anni di elettronica non credo che esista una struttura perfetta delle librerie che possa essere copiata da tutti. Esiste invece una domanda molto concreta che faccio ad ogni nuovo simbolo ed ogni nuovo footprint: QUESTO OGGETTO APPARTIENE DAVVERO A TUTTI I MIEI PROGETTI O SOLTANTO A QUESTO? Se la risposta non è chiarissima preferisco lasciarlo nel progetto, provarlo ed eventualmente promuoverlo più avanti nella libreria comune, perché spostare un oggetto verificato verso una libreria globale costa poco mentre scoprire che dieci progetti dipendono da una definizione sbagliata costa parecchio di più.

Ed è anche per questo che non tocco le librerie ufficiali, versiono ciò che serve a ricostruire il progetto e tengo separate le mie parti comuni da quelle locali. Alla fine simboli e footprint sembrano elementi minuscoli rispetto ad uno schema complesso oppure ad un PCB multistrato, ma sono proprio quei piccoli oggetti che attraversano decine di progetti, anni di aggiornamenti e macchine differenti, quindi vale la pena nominarli, separarli e conservarli con una disciplina precisa, USANDO L'ESPERIENZA DEGLI ERRORI PER NON DOVERLI PAGARE DUE VOLTE!