Controllo della versione per hardware open source: 10 passaggi

2024 Autore: John Day | [email protected]. Ultima modifica: 2024-01-30 10:03

Il team di Brainbow ha una serie di progetti di elettronica alle spalle e volevamo condividere il nostro processo per l'utilizzo del controllo di versione per gestire il nostro flusso di lavoro di progettazione elettronica. Questo flusso di lavoro è stato utilizzato per progetti grandi e piccoli, da semplici schede a 2 livelli a complessi colossi a 10 livelli e si basa su strumenti open source. Si spera che altri possano adottare il nostro flusso di lavoro per se stessi e ottenere i vantaggi del controllo della versione per i propri progetti. Ma quali vantaggi può offrire il controllo di versione a un progetto di elettronica?

Passaggio 1: perché la versione controlla la tua elettronica?

Il controllo della versione (noto anche come controllo del codice sorgente o controllo della revisione) è un concetto ben compreso e ampiamente adottato nell'ingegneria del software. L'idea alla base del controllo del codice sorgente è il monitoraggio sistematico delle modifiche apportate al codice sorgente di un programma o di un'applicazione. Se le modifiche interrompono l'applicazione, è possibile ripristinare i file del codice sorgente a uno stato funzionante noto dal passato. In pratica, i sistemi di controllo del codice sorgente consentono di tenere traccia della cronologia di una raccolta di file (di solito i file del codice sorgente per un programma per computer, un sito Web, ecc.) e visualizzare e gestire le modifiche a tali file.

Tenere traccia della cronologia delle modifiche a un progetto sembra utile per i progetti di elettronica; se si commette un errore nello schema del circuito o si utilizza l'impronta del componente sbagliata nel layout del PCB, sarebbe bello tenere traccia di quali errori sono stati commessi e quali correzioni sono state implementate nelle varie revisioni di un progetto. Sarebbe anche utile per altri creatori vedere quella storia e capire il contesto e le motivazioni dei vari cambiamenti.

Passaggio 2: gli strumenti: KiCad e Git

In questo progetto utilizziamo due strumenti principali: il sistema di controllo della versione (VCS) e il programma di automazione della progettazione elettronica (EDA o ECAD).

Ci sono MOLTI sistemi di controllo di versione là fuori, ma usiamo il VCS distribuito Git. Lo usiamo per una serie di motivi, ma la chiave è che è open-source (controlla!), facile da usare (controlla!) e lo standard di fatto VCS per software open source (controlla!). Useremo Git come VCS per tenere traccia delle modifiche ai file utilizzati dal nostro programma ECAD. Questo Instructable non richiede familiarità con Git, ma si presume una comodità generale nell'uso della riga di comando. Cercherò di collegarmi a risorse utili per l'uso sia di Git che della riga di comando, se necessario.

La maggior parte dei sistemi di controllo del codice sorgente funziona particolarmente bene per i file basati su testo, quindi un programma ECAD che utilizza file di testo sarebbe ottimo. Entra in KiCad, la "Cross Platform and Open Source Electronics Design Automation Suite" open-source supportata dai ricercatori del CERN. KiCad è anche open-source (controlla!), facile da usare (anche se alcuni non sarebbero d'accordo con me su questo) e altamente capace per lavori di progettazione elettronica avanzata.

Passaggio 3: installazione

Per installare questi programmi, seguire le istruzioni dai vari siti di download collegati di seguito.

• KiCad è multipiattaforma (e in modo vertiginoso; la loro pagina di download elenca 13 sistemi operativi supportati e offre un download del codice sorgente se nessuno di questi è adatto a te). Usa l'installazione predefinita di kicad unificata, non la build di sviluppo notturna. Vedere il passaggio 4 per i dettagli facoltativi avanzati sull'installazione della libreria.
• Git è anche multipiattaforma. Se utilizzi Windows, consiglierei l'impressionante progetto Git per Windows per un'esperienza più utile e completa.

La documentazione di installazione disponibile su entrambi questi siti sarà più completa di qualsiasi descrizione che posso offrire qui. Una volta scaricati e installati entrambi i programmi, puoi clonare il modello di progetto di Brainbow dal nostro repository Github. Il comando git clone prende la struttura `git clone {directory src} {directory di destinazione}`; per il nostro progetto, usa `git clone https://github.com/builtbybrainbow/kicad-starter.git {directory di destinazione}`.

La clonazione di un repository git è una forma speciale di copia; quando cloni un progetto, ottieni una copia di tutti i file inclusi nel repository e l'intera cronologia tracciata da Git del progetto. Clonando il nostro repository, ottieni una directory di progetto già strutturata con i nostri consigli per l'utilizzo di Git con KiCad. Tratteremo di più sulla struttura del progetto nel passaggio 6, oppure puoi saltare al passaggio 7 se hai voglia di lavorare.

Alcune rapide attività di pulizia: esegui `git remote rm origin` per rimuovere il collegamento al progetto Github da cui hai clonato. Inoltre, esegui `git commit --amend --author="John Doe "`, sostituendo il parametro dell'autore con il tuo nome e la tua email. Questo modifica l'ultimo commit (che in questo caso è anche il primo commit) e cambia l'autore in te, invece di Brainbow.

Passaggio 4: Nota sull'installazione: Librerie KiCad

Una breve nota sulla struttura della libreria di KiCad. KiCad fornisce una serie di librerie gestite dal team di sviluppatori per un'ampia gamma di componenti elettrici. Ci sono tre librerie principali:

• Simboli schematici: simboli utilizzati per rappresentare componenti elettronici in un disegno schematico di un circuito.
• Impronte PCB: disegni 2D che rappresentano l'impronta effettiva (tamponi in rame, testo serigrafato, ecc.) da utilizzare quando si dispone il circuito su un PCB.
• Modelli 3D: modelli 3D di componenti elettronici.

Queste librerie vengono scaricate insieme alla suite di programmi KiCad appena installata. Puoi usare KiCad senza ulteriori sforzi. Tuttavia, per gli "utenti esperti", i file sorgente per le librerie sono archiviati in un repository git su Github, consentendo agli utenti che desiderano rimanere aggiornati con le ultime modifiche di clonare i repository della libreria sulla propria macchina. Tracciare le librerie con git ha una serie di vantaggi: puoi scegliere quando vuoi aggiornare le tue librerie e gli aggiornamenti devono solo incorporare le modifiche ai file, piuttosto che scaricare di nuovo l'intero set di file della libreria. Tuttavia, sei responsabile dell'aggiornamento delle librerie, che può essere facile da dimenticare.

Se desideri clonare le librerie, questo sito descrive in dettaglio i vari repository Github offerti da KiCad. Git clona le librerie sul tuo computer (es: `git clone https://github.com/KiCad/kicad-symbols.git`), quindi apri KiCad, seleziona la voce "Preferenze" della barra dei menu e fai clic su "Configura percorsi… ". Questo ti permette di dire a KiCad il percorso della directory in cui cercare ogni libreria. Queste variabili d'ambiente sono predefinite sul percorso delle librerie installate con l'installazione di KiCad; Ho preso nota di questi valori in modo da poter tornare alle librerie predefinite, se necessario. Il percorso KICAD_SYMBOL_DIR dovrebbe puntare alla libreria kicad-symbols clonata, KISYSMOD alla libreria kicad-footprints clonata e KISYS3DMOD alla libreria kicad-packages3d clonata.

Quando vuoi aggiornare le librerie, puoi eseguire un semplice comando `git pull` nel repository della libreria che dirà a Git di verificare le differenze tra la tua copia locale del repository della libreria e il repository "remoto" di Github e aggiornare automaticamente il tuo copia locale per incorporare le modifiche.

Passaggio 5: Fondamenti di Git

Git è un programma complesso e sfaccettato, con interi libri dedicati alla sua padronanza. Tuttavia, ci sono alcuni semplici concetti che ti aiuteranno a capire come stiamo usando Git nel nostro flusso di lavoro.

Git tiene traccia delle modifiche ai file utilizzando una serie di fasi. Le normali modifiche avvengono nella directory di lavoro. Quando sei soddisfatto delle modifiche apportate a una serie di file, aggiungi i file che hai modificato nell'area di staging. Dopo aver apportato tutte le modifiche che pianifichi e aver messo in scena tutti i file che desideri tenere traccia in Git, esegui il commit di tali modifiche nel repository. I commit sono essenzialmente istantanee dello stato dei file in un repository in un momento specifico. Poiché Git tiene traccia delle modifiche ai file e memorizza queste modifiche nei commit, in qualsiasi momento puoi ripristinare un progetto allo stato in cui si trovava in qualsiasi commit precedente.

Esistono argomenti più complessi, come branching e remote, ma non è necessario utilizzarli per ottenere i vantaggi del controllo del codice sorgente. Tutto ciò di cui abbiamo bisogno è tenere traccia delle modifiche ai nostri file di progettazione KiCad con una serie di commit.

Passaggio 6: struttura del progetto KiCad

Diamo un'occhiata più da vicino alla struttura del progetto KiCad-Starter che hai clonato in precedenza. È diviso in una serie di sottodirectory per una facile organizzazione:

• Circuito: questa cartella contiene i file del progetto KiCad effettivi (schema, PCB, ecc.). Non rinomino questa cartella, ma rinomino tutti i file all'interno con il nome del progetto (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: il file di progetto di KiCad
  • Circuit.sch: il file schematico di KiCad.
  • Circuit.kicad_pcb: il file di layout PCB di KiCad.
• Documentazione: questa cartella serve per archiviare la documentazione relativa al progetto. Abbiamo in programma di migliorare questo spazio in futuro, ma per ora contiene un semplice file README. Usalo per memorizzare note sul progetto da rivedere in futuro.
• Fabbricazione: questa cartella è dove conserverai i file gerber che la maggior parte delle case favolose utilizzerà per produrre il tuo circuito. Lo usiamo anche per archiviare file BOM e altri documenti che potrebbero essere necessari per la produzione e l'assemblaggio.
• Librerie: questa cartella serve per memorizzare i file di libreria specifici del progetto (ne parleremo meglio in pochi passaggi).

Potresti aver notato anche alcuni altri file (in particolare se `ls -a` la directory). La directory.git è dove Git fa la sua magia, memorizzando la cronologia del repository. Il file.gitignore viene utilizzato per indicare a Git quali file deve ignorare e non memorizzare nel controllo del codice sorgente. Questi sono per lo più file di backup generati da KiCad o alcuni file "generati" diversi, come le netlist, che non dovrebbero essere archiviati nel controllo del codice sorgente perché sono generati dalla fonte che è il file schematico.

Questa struttura del progetto è solo un punto di partenza. Dovresti adattarlo alle tue esigenze e aggiungere sezioni se necessario. In alcuni progetti abbiamo incluso una cartella del software o una cartella degli allegati, dove abbiamo archiviato i modelli per gli allegati di stampa 3D per il progetto.

Passaggio 7: utilizzo di Git per i progetti KiCad

Siamo finalmente pronti per vedere come utilizzare Git per monitorare i tuoi progetti. Questo Instructable non ha lo scopo di insegnarti come usare KiCad (anche se potrei farne uno in futuro se c'è richiesta), quindi esamineremo alcuni esempi banali per mostrarti come funziona il flusso di lavoro. Dovrebbe essere facile capire come adattare queste idee a un progetto reale.

Apri la directory kicad-starter, quindi esegui `git log` per visualizzare la cronologia dei commit. Dovrebbe esserci un commit qui, l'inizializzazione del repository da parte di Brainbow. L'esecuzione di `git status` ti dirà lo stato dei file nel tuo repository (non tracciato, modificato, cancellato, organizzato).

Al momento, non dovresti avere cambiamenti nel tuo repository. Facciamo un cambiamento. Apri il progetto KiCad e aggiungi un resistore allo schema, quindi salva. Ora l'esecuzione di `git status` dovrebbe mostrare che hai modificato il file schematico, ma non hai ancora messo in scena tali modifiche per il commit. Se sei curioso di sapere cosa ha fatto esattamente KiCad quando hai aggiunto il resistore, puoi eseguire il comando diff sul file modificato `git diff Circuit/Circuit.sch`. Questo evidenzierà le modifiche tra la versione corrente del file nella directory di lavoro e lo stato del file all'ultimo commit.

Ora che abbiamo apportato una modifica, proviamo ad applicare tale modifica alla cronologia del nostro progetto. Dobbiamo spostare le modifiche dalla nostra directory di lavoro all'area di staging. Questo in realtà non sposta i file nel file system, ma è concettualmente un modo per far sapere a Git che hai apportato tutte le modifiche pianificate per un particolare file e sei pronto per eseguire il commit di tali modifiche. In modo utile, Git fornisce alcuni suggerimenti quando si esegue `git status` per l'azione successiva. Notare il messaggio `(usa "git add …" per aggiornare cosa verrà commesso)` sotto `Modifiche non gestite per commit:`. Git ti sta dicendo come spostare le modifiche nell'area di staging. Esegui `git add Circuit/Circuit.sch` per mettere in scena le modifiche, quindi `git status` per vedere cosa è successo. Ora vediamo il file schematico sotto le modifiche da confermare. Se non vuoi ancora eseguire il commit di queste modifiche, Git offre un altro suggerimento utile: `(usa "git reset HEAD …" per annullare lo stage)`. Vogliamo confermare queste modifiche, quindi eseguiamo `git commit -m "Resistore aggiunto allo schema"`. Questo conferma le modifiche con il messaggio fornito. L'esecuzione di git log mostrerà questo commit nella cronologia dei commit del progetto.

Qualche altro consiglio sui commit.

1. Non impegnarti ad ogni salvataggio. Impegnati quando senti di aver raggiunto un punto in cui i tuoi cambiamenti si sono in qualche modo solidificati. Mi impegno dopo aver terminato uno schema, non dopo ogni aggiunta di componenti. Inoltre, non vuoi impegnarti troppo di rado, perché ricordare il contesto del motivo per cui hai apportato le modifiche che hai fatto 3 settimane dopo può essere difficile. Capire quando impegnarsi è un po' un'arte, ma ti sentirai più a tuo agio man mano che utilizzerai Git di più.
2. Solo la fonte del negozio (principalmente). Ciò include i file di progetto, schematico e layout, nonché le librerie specifiche del progetto. Questo può includere anche file di documentazione. Prestare attenzione quando si archiviano oggetti derivati perché possono perdere facilmente la sincronizzazione con la fonte originale e ciò causa mal di testa in seguito. I file BOM e gerber vengono desincronizzati in modo particolarmente semplice, quindi è meglio evitarli (sebbene una guida più dettagliata sia trattata nel passaggio 9).
3. I messaggi di commit sono molto utili, ma i messaggi di commit ben strutturati sono inestimabili. Questo eccellente articolo fornisce alcune linee guida per scrivere messaggi di commit chiari, concisi e utili. Ciò potrebbe richiedere l'utilizzo di un editor di testo da riga di comando, che può essere complicato per i principianti (`git commit` senza l'opzione -m message aprirà un editor di testo). Per la maggior parte delle persone, consiglio l'editor Nano. StackOverflow ha una buona spiegazione per cambiare il tuo editor

Passaggio 8: Avanzato: Versionamento semantico per l'elettronica

Per le anime avventurose, i seguenti suggerimenti sono idee avanzate, raccolte da molte ore di sviluppo di KiCad. Non sono particolarmente utili su progetti più piccoli, ma possono davvero salvarti dal dolore man mano che i tuoi progetti crescono in complessità.

Nel software c'è il concetto di Semantic Versioning (semver). Semver definisce una metodologia di denominazione comune per identificare le versioni del software per "numero di versione", seguendo uno schema di "Major. Minor. Patch". Per citare le specifiche di Semver, si fa avanzare il numero di versione in base alle seguenti categorie di modifica.

1. Versione MAJOR quando si apportano modifiche API incompatibili,
2. Versione MINOR quando si aggiungono funzionalità in modo compatibile con le versioni precedenti,
3. versione PATCH quando si apportano correzioni di bug compatibili con le versioni precedenti.

Noi di Brainbow utilizziamo la nostra versione di semver adattata alle esigenze dei progetti hardware. La nostra specifica segue lo stesso modello "Major. Minor. Patch", anche se le nostre definizioni di quali cambiamenti rientrano in quale categoria ovviamente differiscono.

1. Versione MAJOR: utilizzata per modifiche significative alle funzionalità principali del circuito (es: passaggio del processore da ATmegaa a ESP8266).
2. Versione MINOR: utilizzata per lo scambio di componenti che potrebbero influire sul funzionamento del circuito (es: scambio flash SPI con parte compatibile con pin che potrebbe avere un set di comandi diverso) o l'aggiunta di alcune funzionalità aggiuntive minori (es: sensore di temperatura aggiuntivo aggiunto).
3. Versione PATCH: utilizzata per correzioni di bug minori che non modificano il funzionamento del circuito (es: regolazione della serigrafia, regolazione del layout della traccia minore, semplici cambi di componenti come il condensatore 0603 su 0805).

In hardware semver, il numero di versione viene aggiornato solo alla produzione (proprio come nel software, i numeri di versione cambiano solo con le versioni, non ogni singolo commit di un progetto). Di conseguenza, molti progetti hanno numeri di versione bassi. Dobbiamo ancora avere un progetto che utilizzi più di 4 versioni principali.

Oltre ai vantaggi in termini di coerenza e comprensibilità che si ottengono passando a un sistema di denominazione ben definito, si ottengono anche vantaggi in termini di compatibilità del firmware e soddisfazione del cliente. Il firmware può essere scritto tenendo conto della versione della scheda di destinazione e può essere più semplice eseguire il debug del motivo per cui un particolare programma non funziona su una determinata scheda ( giusto, il firmware 2.4.1 non funziona su 1.2 schede perché non abbiamo ….”). I clienti hanno anche beneficiato del nostro server hardware perché il servizio clienti e la risoluzione dei problemi sono molto più semplici con uno standard definito.

Passaggio 9: Avanzato: utilizzo della versione semantica dell'hardware

Per utilizzare l'hardware semver nei tuoi progetti, utilizziamo una funzionalità di Git chiamata tagging. Quando produci per la prima volta una scheda, questa è la versione 1.0.0 di quella scheda. Assicurati di aver eseguito il commit di tutte le modifiche nel tuo progetto, quindi esegui `git tag -a v1.0.0`. Questo aprirà un editor in modo da poter scrivere un messaggio di annotazione per questo tag (molto simile a un messaggio di commit). Includo dettagli sulla produzione (chi ha realizzato il PCB, chi ha assemblato la scheda), che possono essere informazioni utili in seguito.

Il tag di rilascio viene aggiunto alla cronologia dei commit e indica lo stato dei file alla produzione 1.0.0. Questo può essere particolarmente utile dopo diverse revisioni quando è necessario fare riferimento a questo punto per la risoluzione dei problemi. Senza un tag di rilascio specificato, potrebbe essere difficile capire quale commit fosse il più recente al momento della produzione. Un tag 1.0.0 (e 1.1, 1.1.1, ecc.) consente di specificare che questi file di origine specifici erano quelli utilizzati in una particolare corsa di produzione.

Una nota su Gerbers. Alcune case favolose richiedono file gerber per creare la tua scheda e puoi generarli con KiCad. Questi sono oggetti derivati, generati dal file.kicad_pcb di origine e normalmente non controlliamo la versione dei file derivati. Noi di Brainbow non memorizziamo i gerber nel controllo della versione TRANNE per quando tagghiamo una versione. Quando siamo pronti per costruire, generiamo i file gerber, li memorizziamo nella cartella Fabrication e commettiamo e tagghiamo. Quindi rimuoviamo i gerber e commettiamo la cancellazione. Questo può sembrare un po' confuso all'inizio, ma assicura che i commit normali memorizzino solo i file sorgente e che le versioni con tag memorizzino anche i file esatti usati per produrre le schede. Ciò si è dimostrato estremamente utile nel rintracciare gli errori di produzione settimane dopo.

Passaggio 10: passaggi successivi

Si spera che questa introduzione ti abbia insegnato abbastanza per iniziare a utilizzare il controllo di versione sui tuoi progetti di elettronica. Non siamo arrivati ad alcuni degli argomenti più avanzati, come il controllo della versione per le librerie condivise tra progetti o rami di funzionalità. Tuttavia, il controllo della versione è come mangiare le tue verdure: potresti non ottenere ciò che pensi che dovresti, ma ogni parte che ottieni conta.

Brainbow sta lavorando a una guida più dettagliata ad alcune delle funzionalità più avanzate del nostro flusso di lavoro. Speriamo di pubblicarlo nei prossimi mesi. Seguici qui su Instructables e ti faremo sapere quando potrai leggerlo.

Grazie per aver letto e non vediamo l'ora di vedere cosa realizzerai!