Control versiune pentru hardware open source: 10 pași

2024 Autor: John Day | [email protected]. Modificat ultima dată: 2024-01-30 11:45

Echipa de la Brainbow are o serie de proiecte electronice sub centură și am vrut să împărtășim procesul nostru de utilizare a controlului versiunilor pentru a gestiona fluxul nostru de lucru de proiectare electronică. Acest flux de lucru a fost utilizat pentru proiecte mari și mici, de la plăci simple cu 2 straturi la behemoti complexi cu 10 straturi și se bazează pe instrumente open-source. Sperăm că alții pot adopta fluxul nostru de lucru pentru ei înșiși și pot obține beneficiile controlului versiunilor pentru propriile proiecte. Dar ce beneficii poate oferi controlul versiunii unui proiect electronic?

Pasul 1: De ce versiunea vă controlează aparatele electronice?

Controlul versiunilor (alias control sursă sau control revizie) este un concept bine înțeles și adoptat pe scară largă în ingineria software. Ideea din spatele controlului sursă este urmărirea sistematică a modificărilor aduse codului sursă al unui program sau aplicație. Dacă modificările întrerup aplicația, puteți readuce fișierele codului sursă la o stare de lucru cunoscută din trecut. În practică, sistemele de control sursă vă permit să urmăriți istoricul unei colecții de fișiere (de obicei fișierele cu cod sursă pentru un program de computer, site web etc.) și să vizualizați și să gestionați modificările aduse fișierelor respective.

Urmărirea istoricului modificărilor unui proiect pare utilă pentru proiectele electronice; dacă faceți o greșeală în schema circuitului sau utilizați o amprentă greșită a componentei în aspectul PCB-ului, ar fi bine să țineți evidența a ceea ce au fost făcute greșeli și a ce remedieri au fost implementate în diferite revizuiri ale unui proiect. De asemenea, ar fi util ca alți producători să vadă acea istorie și să înțeleagă contextul și motivațiile diferitelor schimbări.

Pasul 2: Instrumentele: KiCad și Git

Folosim două instrumente principale în acest proiect: sistemul de control al versiunilor (VCS) și programul de automatizare a proiectării electronice (EDA sau ECAD).

Există MULTE sisteme de control al versiunilor, dar folosim VCS Git distribuit. O folosim din mai multe motive, dar esențialul este că este open-source (verificați!), Ușor de utilizat (verificați!) Și VCS standard de facto pentru software-ul open-source (verificați!). Vom folosi Git ca VCS pentru a urmări modificările aduse fișierelor pe care le folosește programul nostru ECAD. Acest Instructable nu necesită familiarizarea cu Git, dar se presupune confortul general folosind linia de comandă. Voi încerca să fac legătura cu resurse utile atât pentru Git, cât și pentru utilizarea liniei de comandă, după cum este necesar.

Majoritatea sistemelor de control sursă funcționează deosebit de bine pentru fișierele bazate pe text, astfel încât un program ECAD care utilizează fișiere text ar fi minunat. Intrați în KiCad, open-source-ul „Suită multiplată și electronică de proiectare electronică open source” susținut de cercetătorii de la CERN. KiCad este, de asemenea, open-source (verificați!), Ușor de utilizat (deși unii nu ar fi de acord cu mine în acest sens) și foarte capabil pentru lucrări avansate de proiectare electronică.

Pasul 3: Instalare

Pentru a instala aceste programe, urmați instrucțiunile de pe diferitele site-uri de descărcare legate mai jos.

• KiCad este multiplataforma (și amețitor; pagina lor de descărcare listează 13 sisteme de operare acceptate și oferă o descărcare a codului sursă dacă niciunul dintre acestea nu vi se potrivește). Utilizați instalarea implicită unificată kicad, nu versiunea de dezvoltare nocturnă. Consultați Pasul 4 pentru detalii opționale avansate despre instalarea bibliotecii.
• Git este, de asemenea, pe mai multe platforme. Dacă folosesc Windows, aș recomanda impresionantul proiect Git pentru Windows pentru o experiență mai utilă, cu funcții complete.

Documentația de instalare disponibilă pe ambele site-uri va fi mai completă decât orice descriere pe care o pot oferi aici. Odată ce ambele programe sunt descărcate și instalate, puteți clona șablonul de proiect Brainbow din depozitul nostru Github. Comanda git clone ia structura `git clone {src directory} {target directory}`; pentru proiectul nostru, utilizați `git clone https://github.com/builtbybrainbow/kicad-starter.git {director țintă}`.

Clonarea unui repo git este o formă specială de copiere; când clonați un proiect, primiți o copie a tuturor fișierelor incluse în repo, precum și a întregului istoric al proiectului urmărit de Git. Clonând repo-ul nostru, veți obține un director de proiect deja structurat cu recomandările noastre pentru utilizarea Git cu KiCad. Vom acoperi mai multe despre structura proiectului în Pasul 6 sau puteți trece la Pasul 7 dacă doriți să începeți să lucrați.

Câteva sarcini rapide de menaj - rulați `git remote rm origin` pentru a elimina linkul către proiectul Github din care ați clonat. De asemenea, rulați `git commit --amend --author =" John Doe "`, înlocuind parametrul autorului cu numele și adresa de e-mail. Aceasta modifică ultima comitere (care în acest caz este și prima comitere) și schimbă autorul în locul dvs., mai degrabă decât Brainbow.

Pasul 4: Notă de instalare: Bibliotecile KiCad

O notă rapidă despre structura bibliotecii KiCad. KiCad oferă un set de biblioteci întreținute de echipa de dezvoltatori pentru o gamă largă de componente electrice. Există trei biblioteci principale:

• Simboluri schematice: simboluri utilizate pentru reprezentarea componentelor electronice într-un desen schematic al circuitului.
• Amprente PCB: desene 2D reprezentând amprenta reală (tampoane de cupru, text cu serigrafie etc.) care urmează să fie utilizate la amplasarea circuitului pe un PCB.
• Modele 3D: modele 3D de componente electronice.

Aceste biblioteci sunt descărcate împreună cu suita de programe KiCad pe care tocmai ați instalat-o. Puteți utiliza KiCad fără niciun efort. Cu toate acestea, pentru „utilizatorii avansați”, fișierele sursă pentru biblioteci sunt stocate într-un depozit git de pe Github, permițând utilizatorilor care doresc să rămână la curent cu ultimele modificări să cloneze repourile bibliotecii pe propria mașină. Urmărirea bibliotecilor cu git are o serie de avantaje - puteți alege când doriți să vă actualizați bibliotecile, iar actualizările trebuie doar să încorporeze modificări la fișiere, mai degrabă decât să descărcați din nou întregul set de fișiere de bibliotecă. Cu toate acestea, sunteți responsabil pentru actualizarea bibliotecilor, ceea ce poate fi ușor de uitat.

Dacă doriți să clonați bibliotecile, acest site detaliază diversele oferte KiCad Github repos. Git clonează bibliotecile pe computerul dvs. (de exemplu: `git clone https:// github.com / KiCad / kicad-symbols.git`), apoi deschideți KiCad, selectați bara de meniu„ Preferințe”și faceți clic pe„ Configurare căi … . Acest lucru vă permite să spuneți KiCad calea directorului pentru a căuta fiecare bibliotecă. Aceste variabile de mediu sunt implicite pentru calea către bibliotecile instalate cu instalarea KiCad; Am luat act de aceste valori pentru a putea reveni la bibliotecile implicite, dacă este necesar. Calea KICAD_SYMBOL_DIR ar trebui să indice spre biblioteca dvs. de simboluri kicad clonate, KISYSMOD către biblioteca clonată kicad-footprints și KISYS3DMOD către biblioteca kicad-packages3d clonată.

Când doriți să actualizați bibliotecile, puteți rula o comandă simplă `git pull` în repo bibliotecă, care îi va spune lui Git să verifice diferențele dintre copia locală a repo bibliotecii și Github„ la distanță”repo și să actualizeze automat copie locală pentru a încorpora modificări.

Pasul 5: Fundamentele Git

Git este un program complex și cu multe fațete, cu cărți întregi dedicate stăpânirii acestuia. Cu toate acestea, există câteva concepte simple care vă vor ajuta să înțelegeți cum folosim Git în fluxul nostru de lucru.

Git urmărește modificările la fișiere utilizând o serie de etape. Modificările normale au loc în directorul de lucru. Când sunteți mulțumit de modificările pe care le-ați făcut unei serii de fișiere, adăugați fișierele pe care le-ați modificat în zona intermediară. După ce ați făcut toate modificările pe care intenționați și le-ați aranjat toate fișierele pe care doriți să le urmăriți în Git, trimiteți aceste modificări în depozit. Confirmările sunt în esență instantanee ale stării fișierelor dintr-o repo la un anumit moment. Deoarece Git urmărește modificările la fișiere și stochează aceste modificări în confirmări, în orice moment puteți readuce un proiect înapoi la starea în care se afla, la orice confirmare anterioară.

Există subiecte mai complexe, cum ar fi ramificarea și telecomandele, dar nu este nevoie să le folosim pentru a obține beneficiile controlului sursei. Tot ce ne trebuie este să urmărim modificările aduse fișierelor noastre de proiectare KiCad cu o serie de comitere.

Pasul 6: Structura proiectului KiCad

Să aruncăm o privire mai atentă asupra structurii proiectului KiCad-Starter pe care l-ați clonat mai devreme. Este împărțit în mai multe subdirectoare pentru o organizare ușoară:

• Circuit: Acest folder conține fișierele reale ale proiectului KiCad (schematică, PCB etc.). Nu redenumesc acest folder, dar redenumesc toate fișierele din interior cu numele proiectului (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: fișierul proiectului KiCad
  • Circuit.sch: fișierul schematic KiCad.
  • Circuit.kicad_pcb: fișierul de aspect KiCad PCB.
• Documentație: acest folder este destinat stocării documentației referitoare la proiect. Avem planuri de îmbunătățire a acestui spațiu în viitor, dar pentru moment conține un fișier README simplu. Folosiți-l pentru a stoca note despre proiect, pe care vi le puteți examina ulterior.
• Fabricare: Acest folder este locul unde veți stoca fișierele gerber pe care majoritatea caselor fabuloase le vor folosi pentru fabricarea plăcii dvs. de circuite. De asemenea, îl folosim pentru a stoca fișiere BOM și alte documente care ar putea fi necesare pentru fabricare și asamblare.
• Biblioteci: acest dosar este pentru stocarea fișierelor de bibliotecă specifice proiectului (vom acoperi acest aspect mai mult în câțiva pași).

Este posibil să fi observat și câteva alte fișiere (mai ales dacă „ls -a` directorul). Directorul.git este locul în care Git își face magia, stocând istoricul depozitului. Fișierul.gitignore este folosit pentru a spune Git ce fișiere ar trebui să ignore și nu să stocheze în controlul sursă. Acestea sunt în mare parte fișiere de rezervă pe care le generează KiCad sau câteva fișiere „generate” diferite, cum ar fi listele de rețea, care nu ar trebui să fie stocate în controlul sursei, deoarece acestea sunt generate din sursa care este fișierul schematic.

Această structură a proiectului este doar un punct de plecare. Ar trebui să-l adaptați pentru a se potrivi nevoilor dvs. și să adăugați secțiuni după cum este necesar. În unele proiecte am inclus un folder software sau un folder de carcase, unde am stocat modele pentru carcase de tipărire 3D pentru proiect.

Pasul 7: Utilizarea Git pentru proiectele KiCad

În sfârșit, suntem gata să vedem cum să folosim Git pentru urmărirea proiectelor dvs. Acest instructabil nu este menit să vă învețe cum să utilizați KiCad (deși aș putea face unul în viitor, dacă există cerere pentru el), așa că vom parcurge câteva exemple banale pentru a vă arăta cum rulează fluxul de lucru. Ar trebui să fie ușor de înțeles cum să adaptezi aceste idei la un proiect real.

Deschideți directorul kicad-starter, apoi rulați `git log` pentru a afișa istoricul de comitere. Ar trebui să existe un singur commit aici, inițializarea repo de către Brainbow. Rularea `stării git` vă va arăta starea fișierelor din repo-ul dvs. (nedetectat, modificat, șters, etapizat).

În acest moment, nu ar trebui să aveți nicio modificare în repo. Să facem o schimbare. Deschideți proiectul KiCad și adăugați un rezistor la schemă, apoi salvați. Acum, rularea `statusului git` ar trebui să arate că ați modificat fișierul schematic, dar nu ați organizat încă aceste modificări pentru commit. Dacă sunteți curios de ceea ce a făcut exact KiCad când ați adăugat rezistorul, puteți rula comanda diff pe fișierul modificat `git diff Circuit / Circuit.sch`. Aceasta va evidenția modificările dintre versiunea curentă a fișierului din directorul de lucru și starea fișierului la ultima confirmare.

Acum că am făcut o schimbare, să încercăm să comitem această schimbare în istoricul proiectului nostru. Trebuie să mutăm modificările din directorul nostru de lucru în zona intermediară. Acest lucru nu mută de fapt fișierele din sistemul de fișiere, dar este conceptual un mod de a anunța Git că ați făcut toate modificările planificate pentru un anumit fișier și că sunteți gata să comiteți aceste modificări. În mod util, Git oferă câteva indicii atunci când rulați „starea git” pentru următoarea acțiune. Observați mesajul `(utilizați„ git add …”pentru a actualiza ceea ce va fi angajat)` sub „Modificări care nu sunt organizate pentru commit:`. Git vă spune cum să mutați modificările în zona de etapă. Rulați `git add Circuit / Circuit.sch` pentru a realiza modificările, apoi„ git status` pentru a vedea ce s-a întâmplat. Acum vedem fișierul schematic sub modificările care urmează să fie comise. Dacă nu doriți încă să comiteți aceste modificări, Git vă oferă cu ajutor un alt sfat: `(folosiți„ git reset HEAD …”pentru a demara). Vrem să comitem aceste modificări, așa că rulăm `git commit -m" Rezistor adăugat la schemă "`. Aceasta comite modificările cu mesajul furnizat. Rularea jurnalului git va afișa acest commit în istoricul de commit al proiectului.

Câteva sfaturi despre comitere.

1. Nu vă angajați la fiecare salvare. Angajează-te atunci când simți că ai ajuns la un punct în care modificările tale s-au solidificat oarecum. Mă angajez după ce termin o schemă, nu după fiecare adăugare de componentă. De asemenea, nu doriți să vă angajați prea rar, deoarece amintirea contextului de ce ați făcut modificările pe care le-ați făcut 3 săptămâni mai târziu poate fi dificilă. A afla când să comiți este un pic o artă, dar vei deveni mai confortabil pe măsură ce folosești mai mult Git.
2. Numai sursa magazinului (mai ales). Aceasta include fișierele de proiect, schematice și de aspect, precum și bibliotecile specifice proiectului. Aceasta poate include și fișiere de documentare. Aveți grijă atunci când stocați obiecte derivate, deoarece acestea se pot desincroniza cu sursa originală cu ușurință și asta provoacă dureri de cap mai târziu. Fișierele BOM și gerber se sincronizează în mod deosebit cu ușurință, deci sunt mai bine evitate (deși îndrumarea mai detaliată este acoperită în Pasul 9).
3. Mesajele de confirmare sunt foarte utile, dar mesajele de confirmare bine structurate sunt de neprețuit. Acest articol excelent oferă câteva linii directoare pentru scrierea mesajelor de confirmare clare, concise, utile. Pentru a face acest lucru, este necesar să folosiți un editor de text din linia de comandă, ceea ce mă poate complica pentru începători („git commit” fără opțiunea -m mesaj va deschide un editor de text). Pentru majoritatea oamenilor, recomand editorul Nano. StackOverflow are o explicație bună despre schimbarea editorului

Pasul 8: Avansat: versiuni semantice pentru electronică

Pentru sufletele aventuroase, următoarele sfaturi sunt idei avansate, culese din multe ore de dezvoltare KiCad. Nu sunt deosebit de utile pentru proiectele mai mici, dar vă pot salva durerea, pe măsură ce proiectele dvs. cresc în complexitate.

În software, există un concept de versiune semantică (semver). Semver definește o metodologie comună de denumire pentru a identifica lansările de software după „numărul versiunii”, urmând un model „Major. Minor. Patch”. Pentru a cita specificațiile semver, avansați numărul versiunii în funcție de următoarele categorii de modificări.

1. Versiunea MAJORĂ când faceți modificări API incompatibile,
2. Versiunea MINORĂ atunci când adăugați funcționalitate într-o manieră compatibilă cu versiunile anterioare,
3. Versiunea PATCH atunci când efectuați remedieri de erori compatibile cu versiunile anterioare.

La Brainbow folosim propria noastră versiune de semver adaptată pentru a se potrivi nevoilor proiectelor hardware. Specificațiile noastre urmează același model „Major. Minor. Patch”, deși definițiile noastre privind modificările se încadrează în care categorie diferă în mod evident.

1. Versiune MAJORĂ: utilizată pentru modificări semnificative ale funcționalității de bază a circuitului (de exemplu: comutarea procesorului de la ATmegaa la ESP8266).
2. Versiune MINORĂ: utilizată pentru schimbarea componentelor care ar putea afecta funcționarea circuitului (de exemplu: schimbarea blițului SPI cu piesă compatibilă cu pin care poate avea un set de comenzi diferit) sau adăugarea unor caracteristici suplimentare minore (de exemplu: senzor de temperatură suplimentar adăugat).
3. Versiunea PATCH: utilizată pentru remedieri de erori minore care nu vor schimba funcționarea circuitului (de exemplu: reglarea serigrafiei, reglarea aspectului de urmărire minoră, schimbarea componentelor simple, cum ar fi condensatorul 0603 la 0805).

În hardware semver, numărul versiunii este actualizat doar la fabricare (la fel ca în software, numerele versiunii se schimbă numai cu versiunile, nu fiecare persoană se angajează la un proiect). Drept urmare, multe proiecte au numere de versiune reduse. Încă nu am avut un proiect care să folosească mai mult de 4 versiuni majore.

În afară de avantajele de consistență și înțelegere pe care le obțineți de la trecerea la un sistem de denumire bine definit, veți obține beneficii și în ceea ce privește compatibilitatea firmware-ului și satisfacția clienților. Firmware-ul poate fi scris ținând cont de versiunea plăcii pe care o vizează și poate fi mai ușor să depanați de ce un anumit program nu funcționează pe o placă anume („corect, firmware-ul 2.4.1 nu rulează pe 1.2 plăci pentru că nu avem …. ). Clienții au beneficiat, de asemenea, de hardware-ul nostru semver, deoarece serviciul pentru clienți și depanarea este mult mai ușor cu un standard definit.

Pasul 9: Avansat: Utilizarea versiunilor semantice hardware

Pentru a utiliza hardware semver în propriile dvs. proiecte, utilizăm o caracteristică Git numită etichetare. Când fabricați prima o placă, aceasta este versiunea 1.0.0 a plăcii respective. Asigurați-vă că ați comis toate modificările din proiect, apoi rulați `git tag -a v1.0.0`. Aceasta va deschide un editor, astfel încât să puteți scrie un mesaj de adnotare pentru această etichetă (foarte asemănător cu un mesaj de confirmare). Includ detalii despre producție (cine a realizat PCB-ul, cine a asamblat placa), care pot fi informații utile ulterior.

Eticheta de lansare este adăugată la istoricul de confirmare și indică starea fișierelor la fabricarea 1.0.0. Acest lucru poate fi deosebit de util mai multe revizuiri ulterior, atunci când trebuie să vă referiți la acest punct pentru depanare. Fără o etichetă de lansare specificată, ar putea fi dificil să ne dăm seama care angajare a fost cea mai recentă la momentul fabricării. O etichetă 1.0.0 (și 1.1, 1.1.1 etc.) vă permite să specificați că aceste fișiere sursă specifice au fost cele utilizate într-o anumită etapă de fabricație.

O notă despre Gerbers. Unele case fabuloase necesită fișiere gerber pentru a vă crea bordul și le puteți genera cu KiCad. Acestea sunt obiecte derivate, generate din fișierul.kicad_pcb sursă, iar în mod normal nu controlăm versiunea de fișiere derivate. Noi de la Brainbow nu stocăm gerber-uri în controlul de versiune EXCEPȚIE pentru când etichetăm o versiune. Când suntem gata să construim, generăm fișierele gerber, le stocăm în folderul Fabrication și comitem și etichetăm. Apoi eliminăm gerberii și comitem ștergerea. Acest lucru poate părea puțin confuz la început, dar asigură faptul că angajamentele normale stochează doar fișierele sursă, iar versiunile etichetate stochează și fișierele exacte utilizate pentru fabricarea plăcilor. Acest lucru s-a dovedit extrem de util în depistarea erorilor de fabricație săptămâni mai târziu.

Pasul 10: Pașii următori

Sperăm că această introducere v-a învățat suficient pentru a începe să utilizați controlul versiunilor în propriile dvs. proiecte electronice. Nu am ajuns la unele dintre subiectele mai avansate, cum ar fi controlul versiunilor pentru bibliotecile partajate între proiecte sau ramuri de caracteristici. Totuși, controlul versiunilor este ca și cum ai mânca legumele tale: este posibil să nu obții ceea ce crezi că ar trebui, dar fiecare bucată pe care o primești contează.

Brainbow lucrează la un ghid mai detaliat pentru unele dintre funcțiile mai avansate ale fluxului nostru de lucru. Sperăm să-l publicăm cândva în următoarele luni. Urmați-ne aici pe Instructables și vă vom informa cu siguranță când îl puteți citi.

Vă mulțumim pentru lectură și abia așteptăm să vedem ce faceți!