Control de versions per a maquinari de codi obert: 10 passos

2024 Autora: John Day | [email protected]. Última modificació: 2024-01-30 08:15

L’equip de Brainbow té una sèrie de projectes electrònics sota la nostra cintura i volíem compartir el nostre procés d’utilitzar el control de versions per gestionar el nostre flux de treball de disseny electrònic. Aquest flux de treball s’ha utilitzat per a projectes grans i petits, des de taulers simples de 2 capes fins a grans complexos de 10 capes, i es basa en eines de codi obert. Amb sort, altres poden adoptar el nostre flux de treball per si mateixos i obtenir els avantatges del control de versions per als seus propis projectes. Però, quins avantatges pot oferir el control de versions d’un projecte electrònic?

Pas 1: per què la versió controla l'electrònica?

El control de versions (també conegut com control de font o control de revisió) és un concepte ben entès i àmpliament adoptat en enginyeria de programari. La idea darrere del control font és fer un seguiment sistemàtic dels canvis fets al codi font d’un programa o aplicació. Si els canvis trenquen l'aplicació, podeu tornar els fitxers de codi font a un estat de treball conegut del passat. A la pràctica, els sistemes de control de fonts us permeten fer un seguiment de l'historial d'una col·lecció de fitxers (normalment els fitxers de codi font d'un programa d'ordinador, lloc web, etc.) i visualitzar i gestionar els canvis en aquests fitxers.

El seguiment de la història dels canvis en un projecte sembla útil per a projectes electrònics; si cometeu un error en l’esquema del circuit o utilitzeu una petjada de component incorrecta en el disseny del PCB, seria bo fer un seguiment de quins errors es van cometre i quines correccions es van implementar en diverses revisions d’un projecte. També seria útil per a altres creadors veure aquesta història i entendre el context i les motivacions de diversos canvis.

Pas 2: les eines: KiCad i Git

Utilitzem dues eines principals en aquest projecte: el sistema de control de versions (VCS) i el programa d’automatització del disseny electrònic (EDA o ECAD).

Hi ha MOLTS sistemes de control de versions, però fem servir el VCS Git distribuït. L’utilitzem per diversos motius, però la clau és que és de codi obert (comprovar!), Fàcil d’utilitzar (comprovar!) I el VCS estàndard de facto per al programari de codi obert (comprovar!). Utilitzarem Git com a VCS per fer un seguiment dels canvis als fitxers que utilitza el nostre programa ECAD. Aquest instructable no requereix familiaritat amb Git, però se suposa un confort general amb la línia d'ordres. Intentaré enllaçar a recursos útils tant per a l'ús de Git com per a la línia d'ordres, segons sigui necessari.

La majoria dels sistemes de control de fonts funcionen especialment bé per als fitxers basats en text, de manera que seria fantàstic un programa ECAD que utilitzi fitxers de text. Introduïu KiCad, la "Suite d’automatització de disseny d’electrònica multiplataforma i de codi obert" de codi obert, amb el suport d’investigadors del CERN. KiCad també és de codi obert (comproveu-ho!), Fàcil d'utilitzar (tot i que alguns no hi estarien d'acord), i és altament capaç de dissenyar electrònica avançada.

Pas 3: Instal·lació

Per instal·lar aquests programes, seguiu les instruccions dels diferents llocs de descàrrega enllaçats a continuació.

• KiCad és multiplataforma (i és vertiginós; la seva pàgina de descàrrega llista 13 sistemes operatius compatibles i ofereix una descàrrega de codi font si cap d'aquests us convé). Utilitzeu la instal·lació predeterminada unificada per kicad, no la compilació nocturna de desenvolupament. Consulteu el pas 4 per obtenir detalls opcionals avançats sobre la instal·lació de la biblioteca.
• Git també és multiplataforma. Si utilitzeu Windows, recomanaria l’impressionant projecte Git per a Windows per obtenir una experiència més útil i amb totes les funcions.

La documentació d’instal·lació disponible en aquests dos llocs serà més completa que qualsevol altra descripció que puc oferir aquí. Un cop descarregats i instal·lats els dos programes, podeu clonar la plantilla de projecte de Brainbow des del nostre dipòsit de Github. L'ordre git clone pren l'estructura `git clone {src directory} {target directory}`; per al nostre projecte, utilitzeu `git clone https://github.com/builtbybrainbow/kicad-starter.git {directori de destinació} '.

Clonar un repositori de git és una forma especial de copiar; quan cloneu un projecte, obteniu una còpia de tots els fitxers inclosos a la reposició, així com de tot l'historial del projecte amb seguiment de Git. En clonar la nostra reposició, obtindreu un directori de projectes ja estructurat amb les nostres recomanacions per utilitzar Git amb KiCad. Al pas 6 tractarem més sobre l'estructura del projecte o podeu passar al pas 7 si esteu desitjant començar a treballar.

Unes quantes tasques ràpides de neteja: executeu `git remote rm origin` per eliminar l'enllaç al projecte Github del qual vau clonar. A més, executeu `git commit --amend --author =" John Doe "`, substituint el paràmetre autor pel vostre nom i correu electrònic. Això modifica l’última confirmació (que en aquest cas també és la primera confirmació) i canvia l’autor per vosaltres en lloc de Brainbow.

Pas 4: Nota d'instal·lació: biblioteques KiCad

Una nota ràpida sobre l’estructura de la biblioteca de KiCad. KiCad proporciona un conjunt de biblioteques mantingudes per l'equip de desenvolupadors per a una àmplia gamma de components elèctrics. Hi ha tres biblioteques principals:

• Símbols esquemàtics: símbols utilitzats per representar components electrònics en un dibuix esquemàtic de circuits.
• Petjades de PCB: dibuixos en 2D que representen la petjada real (coixinets de coure, text de serigrafia, etc.) que s’utilitzaran quan es col·loqui el circuit en un PCB.
• Models 3D: models 3D de components electrònics.

Aquestes biblioteques es descarreguen junt amb el paquet de programes KiCad que acabeu d’instal·lar. Podeu utilitzar KiCad sense cap més esforç. Tanmateix, per als "usuaris avançats", els fitxers font de les biblioteques s'emmagatzemen en un dipòsit git de Github, cosa que permet als usuaris que vulguin estar al dia dels darrers canvis per clonar els dipòsits de biblioteca a la seva pròpia màquina. El seguiment de les biblioteques amb git té una sèrie d’avantatges: podeu triar quan voleu actualitzar les biblioteques i les actualitzacions només han d’incorporar canvis als fitxers en lloc de tornar a descarregar tot el conjunt de fitxers de la biblioteca. Tot i això, sou responsable d’actualitzar les biblioteques, cosa que pot ser fàcil d’oblidar.

Si voleu clonar les biblioteques, aquest lloc detalla els diversos dipòsits de Github que ofereix KiCad. Git cloneu les biblioteques a l'ordinador (per exemple: `git clone https:// github.com / KiCad / kicad-symbols.git`), obriu KiCad, seleccioneu l'element" Preferències "de la barra de menú i feu clic a" Configura camins … ". Això us permet indicar a KiCad el camí del directori per cercar cada biblioteca. Aquestes variables d'entorn són per defecte el camí de les biblioteques instal·lades amb la instal·lació de KiCad; Vaig prendre nota d’aquests valors per poder tornar a les biblioteques predeterminades si calia. El camí KICAD_SYMBOL_DIR hauria d’apuntar a la vostra biblioteca de símbols kicad clonats, KISYSMOD a la biblioteca clonada kicad-footprints i KISYS3DMOD a la biblioteca kicad-packages3d clonada.

Quan vulgueu actualitzar les biblioteques, podeu executar una senzilla ordre `git pull` a la reposició de la biblioteca que indicarà a Git que comprovi si hi ha diferències entre la vostra còpia local de la reposició de la biblioteca i la reposició" remota "de Github i actualitzeu automàticament la vostra còpia local per incorporar canvis.

Pas 5: Fonaments bàsics de Git

Git és un programa complex i amb múltiples facetes, amb llibres sencers dedicats a dominar-lo. Tot i això, hi ha alguns conceptes senzills que us ajudaran a entendre com fem servir Git al nostre flux de treball.

Git fa un seguiment dels canvis als fitxers mitjançant una sèrie d'etapes. Els canvis normals es produeixen al directori de treball. Quan estigueu satisfet amb els canvis que heu fet a una sèrie de fitxers, afegiu els fitxers que heu canviat a l'àrea de prova. Un cop hàgiu fet tots els canvis previstos i hàgiu posat en escena tots els fitxers dels quals voleu fer un seguiment a Git, envieu aquests canvis al dipòsit. Les confirmacions són essencialment instantànies de l’estat dels fitxers d’una reposició en un moment concret. Atès que Git fa un seguiment dels canvis als fitxers i emmagatzema aquests canvis en els commit, en qualsevol moment podeu tornar un projecte a l'estat en què es trobava en qualsevol commit anterior.

Hi ha temes més complexos, com la derivació i els comandaments a distància, però no cal que els utilitzem per obtenir els avantatges del control de fonts. Tot el que necessitem és fer un seguiment dels canvis als fitxers de disseny de KiCad amb una sèrie de confirmacions.

Pas 6: Estructura del projecte KiCad

Vegem més de prop l’estructura del projecte KiCad-Starter que vau clonar anteriorment. Està dividit en diversos subdirectoris per facilitar la seva organització:

• Circuit: aquesta carpeta conté els fitxers reals del projecte KiCad (esquemàtic, PCB, etc.). No canvio el nom d'aquesta carpeta, però sí que renombo tots els fitxers que hi ha dins amb el nom del projecte (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: el fitxer del projecte KiCad
  • Circuit.sch: el fitxer esquemàtic de KiCad.
  • Circuit.kicad_pcb: el fitxer de disseny del PCB KiCad.
• Documentació: aquesta carpeta serveix per emmagatzemar documentació relativa al projecte. Tenim plans per millorar aquest espai en el futur, però de moment conté un simple fitxer README. Utilitzeu-lo per emmagatzemar notes sobre el projecte perquè el pugueu revisar en un futur.
• Fabricació: aquesta carpeta és on emmagatzemareu els fitxers gerber que utilitzaran la majoria de cases fabuloses per fabricar la vostra placa de circuit. També l’utilitzem per emmagatzemar fitxers BOM i altres documents que puguin ser necessaris per a la fabricació i el muntatge.
• Biblioteques: aquesta carpeta serveix per emmagatzemar fitxers de biblioteca específics del projecte (en tractarem més en pocs passos).

És possible que també hagueu notat alguns altres fitxers (sobretot si el directori `ls -a`). El directori.git és on Git fa la seva màgia, emmagatzemant l’historial del dipòsit. El fitxer.gitignore s'utilitza per indicar a Git quins fitxers hauria d'ignorar i no emmagatzemar-los al control font. Es tracta principalment de fitxers de còpia de seguretat que genera KiCad, o alguns fitxers "generats" diferents, com ara llistes de xarxa, que no s'han d'emmagatzemar en el control d'origen perquè es generen a partir de l'origen que és el fitxer esquemàtic.

Aquesta estructura del projecte és només un punt de partida. Haureu d'adaptar-lo a les vostres necessitats i afegir seccions segons sigui necessari. En alguns projectes, hem inclòs una carpeta de programari o carpeta de recintes, on hem emmagatzemat models per a recintes d’impressió en 3D per al projecte.

Pas 7: utilitzar Git per a projectes KiCad

Finalment estem preparats per veure com utilitzar Git per fer el seguiment dels vostres projectes. Aquesta instrucció no pretén ensenyar-vos a utilitzar KiCad (tot i que en puc fer una en el futur si hi ha demanda), així que passarem a través d’alguns exemples trivials per mostrar-vos com s’executa el flux de treball. Hauria de ser fàcil entendre com adaptar aquestes idees a un projecte real.

Obriu el directori kicad-starter i, a continuació, executeu `git log` per mostrar l'historial de confirmacions. Aquí hi hauria d’haver un commit, la inicialització del repo per Brainbow. L'execució de `git status` us indicarà l'estat dels fitxers de la vostra reposició (no rastrejats, modificats, suprimits, programats).

De moment, no hauríeu de fer cap canvi a la vostra reposició. Fem un canvi. Obriu el projecte KiCad i afegiu una resistència a l'esquema i deseu-la. Ara, si s'executa `git status`, s'hauria de mostrar que heu modificat el fitxer esquemàtic, però que encara no heu realitzat aquests canvis per al commit. Si teniu curiositat per saber què va fer exactament KiCad quan vau afegir la resistència, podeu executar l'ordre diff al fitxer modificat `git diff Circuit / Circuit.sch`. Això ressaltarà els canvis entre la versió actual del fitxer al directori de treball i l'estat del fitxer a l'última confirmació.

Ara que hem fet un canvi, intentem cometre aquest canvi al nostre historial de projectes. Hem de moure els canvis del nostre directori de treball a l'àrea de prova. En realitat, això no mou els fitxers del sistema de fitxers, però conceptualment és una manera de fer saber a Git que heu fet tots els canvis previstos per a un fitxer concret i que esteu preparats per comprometre'ls. Útilment, Git proporciona alguns consells quan executeu "git status" per a la següent acció. Tingueu en compte el missatge `(utilitzeu" git add … "per actualitzar el que es comprometrà) a la secció` Canvis no organitzats per a commit: Git us explica com moure els canvis a l'àrea d'intervenció. Executeu `git add Circuit / Circuit.sch` per escenificar els canvis i, a continuació, 'git status` per veure què ha passat. Ara veiem el fitxer esquemàtic sota els canvis que s'han de comprometre. Si encara no voleu comprometre aquests canvis, Git us ofereix un altre consell útil: `(utilitzeu" git reset HEAD … "per deixar d'escenari)`. Volem confirmar aquests canvis, de manera que executem `git commit -m" Resistència afegida a l'esquema "`. Això compromet els canvis amb el missatge proporcionat. L'execució del registre de git mostrarà aquesta confirmació a l'historial de validacions del projecte.

Alguns consells més sobre els compromisos.

1. No us comprometeu amb cada estalvi. Comprometeu-vos quan creieu que heu arribat a un punt en què els vostres canvis s’han solidificat una mica. Em comprometo després d'acabar un esquema, no després de cada addició de components. Tampoc no us voleu comprometre amb massa freqüència, ja que recordar el context de per què heu fet els canvis que heu fet 3 setmanes després pot ser difícil. Esbrinar quan comprometre’s és una mica artístic, però us anireu sentint més còmode a mesura que utilitzeu Git més.
2. Només font de la botiga (principalment). Això inclou els fitxers de projecte, esquemàtics i de disseny, així com les biblioteques específiques del projecte. Això també pot incloure fitxers de documentació. Aneu amb compte a l'hora d'emmagatzemar objectes derivats, ja que poden desconnectar-se fàcilment de la font original i això provoca mals de cap més endavant. Els fitxers BOM i gerber es sincronitzen especialment fàcilment, de manera que s’eviten millor (tot i que al pas 9 es descriuen orientacions més detallades).
3. Els missatges de confirmació són molt útils, però els missatges de confirmació ben estructurats són inestimables. Aquest excel·lent article proporciona algunes pautes per escriure missatges de confirmació clars, concisos i útils. Fer-ho pot requerir l’ús d’un editor de text a la línia d’ordres, cosa que em pot complicar per a principiants (`git commit` sense l’opció de missatge -m obrirà un editor de text). Per a la majoria de la gent, recomano l'editor Nano. StackOverflow té una bona explicació sobre el canvi d’editor

Pas 8: avançat: versions semàntiques per a electrònica

Per a les ànimes aventureres, els consells següents són idees avançades, recollides de moltes hores de desenvolupament de KiCad. No són particularment útils en projectes més petits, però sí que us poden estalviar dolor a mesura que els vostres projectes creixen en complexitat.

Al programari, hi ha un concepte de Versió Semàntica (semver). Semver defineix una metodologia de denominació comuna per identificar les versions de programari per "número de versió", seguint un patró de "Major. Minor. Patch". Per citar les especificacions de semver, avanceu el número de versió segons les categories de canvis següents.

1. Versió MAJOR quan feu canvis d'API incompatibles,
2. Versió MENOR quan afegiu funcionalitats compatibles amb les versions anteriors,
3. Versió PATCH quan feu correccions d’errors compatibles amb la versió anterior.

A Brainbow utilitzem la nostra pròpia versió de semver adaptada a les necessitats dels projectes de maquinari. Les nostres especificacions segueixen el mateix patró de "Major. Minor. Patch", tot i que les nostres definicions de quins canvis es troben sota quina categoria és evident que difereixen.

1. Versió MAJOR: s'utilitza per a canvis significatius en la funcionalitat principal del circuit (per exemple: commutació de processador d'ATmegaa a ESP8266).
2. Versió MENOR: s'utilitza per a intercanvis de components que poden afectar el funcionament del circuit (per exemple: intercanvi de flaix SPI amb una peça compatible amb pin que pot tenir un conjunt d'ordres diferent) o per afegir alguna característica addicional menor (per exemple: sensor de temperatura addicional afegit).
3. Versió PATCH: s'utilitza per a correccions d'errors menors que no canvien el funcionament del circuit (per exemple: ajust de serigrafia, ajust de distribució de traça menor, permutes de components simples com el condensador 0603 a 0805).

Sempre al maquinari, el número de versió només s’actualitza a la fabricació (igual que al programari, els números de versió només canvien amb les versions, no totes les persones es comprometen amb un projecte). Com a resultat, molts projectes tenen números de versió baixos. Encara no hem tingut un projecte que utilitzi més de 4 versions principals.

A part dels avantatges de la coherència i la comprensibilitat que obté de canviar a un sistema de noms ben definit, també obtindreu avantatges en compatibilitat de microprogramari i satisfacció del client. El microprogramari es pot escriure tenint en compte la versió de la placa a la qual s'orienta, i pot ser més fàcil depurar per què un programa concret no funciona en una placa concreta ("correcte, el microprogramari 2.4.1 no s'executa a l'1.2 perquè no tenim … "). Els clients també s’han beneficiat del nostre hardware sempre, perquè el servei i la solució de problemes al client són molt més fàcils amb un estàndard definit.

Pas 9: Avançat: utilització de versions semàntiques de maquinari

Per utilitzar sempre el maquinari en els vostres propis projectes, fem servir una funció Git anomenada etiquetatge. Quan fabriqueu una placa per primera vegada, aquesta és la versió 1.0.0 d’aquesta placa. Assegureu-vos que hàgiu compromès tots els canvis del vostre projecte i, a continuació, executeu `git tag -a v1.0.0`. Això obrirà un editor perquè pugueu escriure un missatge d'anotació per a aquesta etiqueta (molt similar a un missatge de confirmació). Inclou detalls sobre la fabricació (qui va fabricar el PCB, qui va muntar el tauler), que pot ser informació útil més endavant.

L'etiqueta de llançament s'afegeix a l'historial de confirmacions i indica l'estat dels fitxers a la fabricació 1.0.0. Això pot resultar especialment útil per a diverses revisions més endavant quan hagueu de tornar a referir-vos a aquest punt per a la resolució de problemes. Sense una etiqueta de llançament especificada, podria ser difícil esbrinar quina confirmació era la més recent en el moment de la fabricació. Una etiqueta 1.0.0 (i 1.1, 1.1.1, etc.) us permet especificar que aquests fitxers font específics eren els que s’utilitzaven en una execució de fabricació concreta.

Una nota sobre Gerbers. Algunes cases fabuloses requereixen fitxers gerber per crear el vostre tauler i podeu generar-les amb KiCad. Són objectes derivats, generats a partir del fitxer.kicad_pcb font, i normalment no controlem els fitxers derivats de versions. A Brainbow no emmagatzemem gerbers al control de versió, tret de quan etiquetem una versió. Quan estiguem preparats per generar, generem els fitxers gerber, els emmagatzemem a la carpeta Fabrication i el commit i l’etiqueta. A continuació, traiem els gerbers i cometem la supressió. Això pot semblar una mica confús al principi, però assegura que els compromisos normals només emmagatzemen els fitxers font i que les versions etiquetades també emmagatzemen els fitxers exactes utilitzats per fabricar els taulers. Això ha demostrat ser molt útil per rastrejar els errors de fabricació setmanes després.

Pas 10: passos següents

Esperem que aquesta introducció us hagi ensenyat prou com per començar a utilitzar el control de versions en els vostres propis projectes electrònics. No hem arribat a alguns dels temes més avançats, com ara el control de versions per a biblioteques compartides entre projectes o branques de funcions. Tot i així, el control de versions és com menjar-se les verdures: és possible que no obtingueu el que creieu que hauríeu de fer, però cada cop que obteniu compta.

Brainbow està treballant en una guia més detallada d'algunes de les funcions més avançades del nostre flux de treball. Esperem publicar-lo algun dia en els propers mesos. Seguiu-nos aquí a Instructables i estarem segurs de comunicar-vos quan el pugueu llegir.

Gràcies per llegir i no podem esperar a veure què en feu.