Nadzor različic za odprtokodno strojno opremo: 10 korakov

2024 Avtor: John Day | [email protected]. Nazadnje spremenjeno: 2024-01-30 12:06

Ekipa podjetja Brainbow ima v okviru pasu številne elektronske projekte, zato smo želeli deliti naš postopek uporabe nadzora različic za upravljanje našega delovnega toka oblikovanja elektronike. Ta potek dela je bil uporabljen za velike in majhne projekte, od preprostih dvoslojnih plošč do kompleksnih 10-slojnih velikanov in temelji na odprtokodnih orodjih. Upajmo, da bodo drugi lahko sami sprejeli naš potek dela in pridobili prednosti nadzora različic za svoje projekte. Kakšne koristi pa lahko nadzor nad različicami ponudi projektu elektronike?

1. korak: Zakaj različica nadzoruje vašo elektroniko?

Nadzor različic (znan tudi kot nadzor nad viri ali revizija) je dobro razumljen in splošno sprejet koncept v programskem inženiringu. Zamisel o nadzoru vira je sistematično sledenje spremembam izvorne kode programa ali aplikacije. Če spremembe prekinejo aplikacijo, lahko datoteke izvorne kode povrnete v znano delovno stanje iz preteklosti. V praksi sistemi za nadzor virov omogočajo sledenje zgodovini zbirke datotek (običajno datoteke izvorne kode za računalniški program, spletno mesto itd.) Ter vizualizacijo in upravljanje sprememb teh datotek.

Sledenje zgodovini sprememb projekta se zdi koristno za elektronske projekte; če naredite napako v shemi vezja ali uporabite napačen odtis komponente v postavitvi tiskanega vezja, bi bilo lepo spremljati, kakšne napake so bile narejene in kateri popravki so bili izvedeni pri različnih revizijah projekta. Prav tako bi bilo koristno, da bi drugi ustvarjalci videli to zgodovino in razumeli kontekst in motivacijo različnih sprememb.

2. korak: Orodja: KiCad in Git

V tem projektu uporabljamo dve glavni orodji: sistem za nadzor različic (VCS) in program za avtomatizacijo načrtovanja elektronike (EDA ali ECAD).

Obstaja veliko sistemov za nadzor različic, vendar uporabljamo porazdeljeni VCS Git. Uporabljamo ga iz več razlogov, ključni pa so, da je odprtokodni (preverite!), Enostaven za uporabo (preverite!) In de facto standardni VCS za odprtokodno programsko opremo (preverite!). Git bomo uporabljali kot VCS za sledenje spremembam datotek, ki jih uporablja naš program ECAD. Ta Instructable ne zahteva poznavanja Gita, vendar se predvideva splošno udobje z uporabo ukazne vrstice. Poskusil se bom povezati s koristnimi viri za uporabo Gita in ukazne vrstice, če je potrebno.

Večina sistemov za nadzor virov deluje še posebej dobro pri besedilnih datotekah, zato bi bil program ECAD, ki uporablja besedilne datoteke, odličen. Vstopite v KiCad, odprtokodno zbirko "Cross Platform and Open Source Electronics Design Automation Suite", ki jo podpirajo raziskovalci na CERN-u. KiCad je tudi odprtokodni (preverite!), Enostaven za uporabo (čeprav se nekateri glede tega ne bi strinjali z mano) in zelo sposoben za napredno oblikovanje elektronike.

3. korak: Namestitev

Če želite namestiti te programe, sledite navodilom z različnih spletnih mest za prenos, navedenih spodaj.

• KiCad je za več platform (in vrtoglavo tako; njihova stran za prenos vsebuje 13 podprtih operacijskih sistemov in ponuja prenos izvorne kode, če vam nič od tega ne ustreza). Uporabite enotno privzeto namestitev, poenoteno s kicadom, ne gradnjo nočnega razvoja. Glejte 4. korak za dodatne izbirne podrobnosti o namestitvi knjižnice.
• Git je tudi med platformami. Če uporabljate Windows, bi priporočil impresiven projekt Git for Windows za bolj uporabno in celovito izkušnjo.

Dokumentacija za namestitev, ki je na voljo na obeh teh mestih, bo popolnejša od vseh opisov, ki jih lahko ponudim tukaj. Ko sta oba programa naložena in nameščena, lahko klonirate predlogo projekta Brainbow iz našega skladišča Github. Ukaz git clone prevzame strukturo `git clone {src directory} {target directory}`; za naš projekt uporabite `git clone https://github.com/builtbybrainbow/kicad-starter.git {target directory}`.

Kloniranje git repo je posebna oblika kopiranja; ko klonirate projekt, dobite kopijo vseh datotek, vključenih v repo, pa tudi celotno zgodovino projekta, ki mu sledi Git. S kloniranjem našega repo -ja dobite imenik projektov, že strukturiran z našimi priporočili za uporabo Gita s KiCadom. Več o strukturi projekta bomo obravnavali v 6. koraku ali pa preskočite na 7. korak, če vas srbi delo.

Nekaj hitrih gospodinjskih opravil - zaženite `git remote rm origin`, da odstranite povezavo do projekta Github, iz katerega ste klonirali. Zaženite tudi `git commit --amend --author =" John Doe "` in parameter avtorja zamenjajte z vašim imenom in e -poštnim naslovom. S tem se spremeni zadnja zaveza (ki je v tem primeru tudi prva) in avtor, ne pa Brainbow, se spremeni v vas.

4. korak: Opomba za namestitev: Knjižnice KiCad

Nekaj kratkih opomb o strukturi knjižnice KiCad. KiCad ponuja nabor knjižnic, ki jih vzdržuje ekipa razvijalcev za široko paleto električnih komponent. Obstajajo tri glavne knjižnice:

• Shematski simboli: Simboli, ki se uporabljajo za predstavitev elektronskih komponent na shematski shemi vezja.
• Odtisi PCB: 2D risbe, ki predstavljajo dejanski odtis (bakrene blazinice, sitotisk itd.), Ki jih je treba uporabiti pri polaganju vezja na tiskano vezje.
• 3D modeli: 3D modeli elektronskih komponent.

Te knjižnice se prenesejo skupaj s programskim paketom KiCad, ki ste ga pravkar namestili. KiCad lahko uporabljate brez več truda. Vendar so za "napredne uporabnike" izvorne datoteke knjižnic shranjene v skladišču git na Githubu, kar uporabnikom, ki želijo biti na tekočem z najnovejšimi spremembami, klonira repo knjižnice na svoj računalnik. Sledenje knjižnicam z gitom ima številne prednosti - lahko izberete, kdaj želite posodobiti svoje knjižnice, posodobitve pa morajo vključevati le spremembe datotek, namesto da znova naložite celoten nabor knjižničnih datotek. Vendar ste odgovorni za posodabljanje knjižnic, na kar je enostavno pozabiti.

Če želite klonirati knjižnice, to spletno mesto opisuje različne ponudbe Github repos KiCad. Git klonirajte knjižnice v svoj računalnik (npr.: `git clone https:// github.com/KiCad/kicad-symbols.git`), nato odprite KiCad, izberite menijsko vrstico" Nastavitve "in kliknite" Konfiguriraj poti … ". To vam omogoča, da KiCadu povežete pot imenika, da poišče vsako knjižnico. Te spremenljivke okolja privzeto določajo pot do knjižnic, nameščenih z namestitvijo KiCad; Te vrednosti sem upošteval, da sem se lahko po potrebi vrnil na privzete knjižnice. Pot KICAD_SYMBOL_DIR mora kazati na vašo knjižnico kloniranih simbolov kicad, KISYSMOD na knjižnico kloniranih kicad-footprints in KISYS3DMOD na klonirano knjižnico kicad-packages3d.

Ko želite posodobiti knjižnice, lahko v repoju knjižnice zaženete preprost ukaz `git pull`, ki bo Gitu povedal, naj preveri razlike med vašo lokalno kopijo repo knjižnice in" oddaljenim "repo Github in samodejno posodobi vaš lokalna kopija za vključitev sprememb.

5. korak: Osnove Gita

Git je kompleksen in večplasten program, ki ga obvladajo cele knjige. Vendar pa obstaja nekaj preprostih konceptov, ki vam bodo pomagali razumeti, kako uporabljamo Git v svojem delovnem toku.

Git sledi spremembam datotek po vrsti korakov. Običajne spremembe se zgodijo v delovnem imeniku. Ko ste zadovoljni s spremembami, ki ste jih naredili v vrsti datotek, datoteke, ki ste jih spremenili, dodate v uprizoritveno območje. Ko naredite vse spremembe, ki jih nameravate, in vse datoteke, ki jih želite slediti v Gitu, uprizorite, jih spremenite v skladišče. Odredi so v bistvu posnetki stanja datotek v repo -ju v določenem času. Ker Git sledi spremembam datotek in shranjuje te spremembe v predajah, lahko kadar koli projekt vrnete v stanje, v katerem je bil ob kateri koli predhodni predaji.

Obstajajo bolj zapletene teme, kot so razvejanje in daljinski upravljalniki, vendar nam jih ni treba uporabiti za pridobitev prednosti nadzora vira. Vse, kar potrebujemo, je slediti spremembam v naših oblikovalskih datotekah KiCad z vrsto zavez.

6. korak: Struktura projekta KiCad

Poglejmo si podrobneje strukturo projekta KiCad-Starter, ki ste ga klonirali prej. Za enostavno organizacijo je razdeljen na številne podimenike:

• Vezje: Ta mapa vsebuje dejanske datoteke projekta KiCad (sheme, tiskano vezje itd.). Te mape ne preimenujem, ampak vse datoteke v njej preimenujem z imenom projekta (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: datoteka projekta KiCad
  • Circuit.sch: shematska datoteka KiCad.
  • Circuit.kicad_pcb: datoteka postavitve tiskanega vezja KiCad.
• Dokumentacija: Ta mapa je za shranjevanje dokumentacije o projektu. Imamo načrte za izboljšanje tega prostora v prihodnosti, vendar zaenkrat vsebuje preprosto datoteko README. Uporabite ga za shranjevanje zapiskov o projektu za prihodnji pregled.
• Izdelava: V tej mapi boste shranili datoteke gerber, ki jih bo večina hišk uporabila za izdelavo vašega vezja. Uporabljamo ga tudi za shranjevanje datotek BOM in drugih dokumentov, ki so morda potrebni za izdelavo in montažo.
• Knjižnice: Ta mapa je za shranjevanje knjižničnih datotek, značilnih za projekt (to bomo podrobneje obravnavali v nekaj korakih).

Morda ste opazili tudi nekaj drugih datotek (zlasti če imenik `ls -a`). Mapa.git je tam, kjer Git naredi magijo in shrani zgodovino skladišča. Datoteka.gitignore se uporablja, da Gitu pove, katere datoteke naj prezre in ne shrani v izvorni nadzor. To so večinoma varnostne kopije datotek, ki jih ustvari KiCad, ali nekaj različnih "ustvarjenih" datotek, na primer netlists, ki jih ne bi smeli shranjevati v izvornem nadzoru, ker so ustvarjeni iz vira, ki je shematska datoteka.

Ta struktura projekta je le izhodišče. Prilagodite ga svojim potrebam in po potrebi dodajte razdelke. V nekatere projekte smo vključili mapo s programsko opremo ali mapo ohišja, kamor smo shranili modele ohišij za 3D tiskanje za projekt.

7. korak: Uporaba Gita za KiCad projekte

Končno smo pripravljeni videti, kako uporabiti Git za sledenje vašim projektom. Ta Instructable vas ne želi naučiti uporabljati KiCad (čeprav ga bom morda naredil v prihodnosti, če bo povpraševanje po njem), zato bomo preučili nekaj trivialnih primerov, ki vam bodo pokazali, kako poteka potek dela. Moral bi biti enostaven za razumevanje, kako te ideje prilagoditi resničnemu projektu.

Odprite imenik kicad-starter, nato zaženite `git log`, da prikažete zgodovino sporočil. Tu bi morala biti ena zaveza, inicializacija repo -ja s strani Brainbow. Zagon 'git statusa' vam bo povedal stanje datotek v vašem repo -ju (brez sledi, spremenjenih, izbrisanih, uprizorjenih).

Trenutno v svojem repo -ju ne bi smeli imeti sprememb. Naredimo spremembo. Odprite projekt KiCad in shemi dodajte upor, nato pa shranite. Zdaj, ko se izvaja 'git status', bi moralo biti prikazano, da ste datoteko sheme spremenili, vendar teh sprememb še niste uprizorili za oddajo. Če vas zanima, kaj točno je KiCad storil, ko ste dodali upor, lahko zaženete ukaz diff na spremenjeni datoteki `git diff Circuit/Circuit.sch`. To bo poudarilo spremembe med trenutno različico datoteke v delovnem imeniku in stanjem datoteke pri zadnji izdaji.

Zdaj, ko smo naredili spremembo, poskusimo to spremembo vnesti v zgodovino projekta. Spremembe moramo premakniti iz našega delovnega imenika v uprizoritveno območje. To dejansko ne premakne datotek v datotečnem sistemu, ampak je konceptualno način, da Gitu sporočite, da ste naredili vse načrtovane spremembe za določeno datoteko in ste pripravljeni na spremembe. Z veseljem vam Git ponudi nekaj namigov, ko zaženete `git status` za naslednje dejanje. Upoštevajte sporočilo `(uporabite" git add … ", da posodobite, kaj bo zavezano)` pod "Spremembe, ki niso nameščene za oddajo:". Git vam pove, kako premakniti spremembe na uprizoritveno območje. Za zagon sprememb zaženite `git add Circuit/Circuit.sch`, nato` git status`, da vidite, kaj se je zgodilo. Zdaj vidimo shematsko datoteko, ki jo je treba spremeniti. Če teh sprememb še ne želite uveljaviti, vam Git v pomoč ponuja še en nasvet: `(uporabite" git reset HEAD … "za odstranitev postave)`. Te spremembe želimo potrditi, zato zaženimo `git commit -m" Dodan upor shemi "". To potrdi spremembe s priloženim sporočilom. Izvajanje dnevnika git bo prikazalo to predajo v zgodovini predaj projekta.

Še nekaj nasvetov o zavezah.

1. Ne zavezujte se z vsakim shranjevanjem. Zavežite se, ko začutite, da ste dosegli točko, ko so se vaše spremembe nekoliko utrdile. Zavežem se, ko končam shemo, ne po vsakem dodajanju komponente. Prav tako se ne želite zavezati preveč redko, saj si je težko zapomniti kontekst, zakaj ste naredili spremembe, ki ste jih naredili 3 tedne kasneje. Ugotavljanje, kdaj se zavezati, je malo umetnost, vendar vam bo z uporabo Gita bolj udobno.
2. Shranjujte samo vir (večinoma). To vključuje datoteke projekta, sheme in postavitve ter knjižnice, značilne za projekt. To lahko vključuje tudi dokumentacijske datoteke. Pri shranjevanju izpeljanih predmetov bodite previdni, ker se lahko zlahka sinhronizirajo s prvotnim virom, kar kasneje povzroči glavobol. Datoteke BOM in gerber se posebej enostavno sinhronizirajo, zato se jim je bolje izogniti (čeprav so podrobnejša navodila zajeta v 9. koraku).
3. Sporočila o oddaji so zelo uporabna, vendar so dobro strukturirana sporočila o predaji neprecenljiva. Ta odličen članek vsebuje nekaj smernic za pisanje jasnih, jedrnatih, uporabnih sporočil o zavezi. To lahko zahteva uporabo urejevalnika besedila ukazne vrstice, kar je lahko zapleteno za začetnike ("git commit" brez možnosti sporočila -m odpre urejevalnik besedil). Za večino ljudi priporočam urejevalnik Nano. StackOverflow ima dobro razlago o spremembi urejevalnika

8. korak: Napredno: pomensko različico za elektroniko

Za pustolovske duše so naslednji nasveti napredne ideje, pridobljene iz več ur razvoja KiCada. Pri manjših projektih niso posebej uporabni, lahko pa vam resnično prihranijo srčne bolečine, ko vaši projekti postajajo vse bolj zapleteni.

V programski opremi obstaja koncept pomenske različice (semver). Semver opredeljuje skupno metodologijo poimenovanja za identifikacijo izdaj programske opreme po "številki različice" po vzorcu "Major. Minor. Patch". Če želite citirati specifikacije semver, napredujete številko različice v skladu z naslednjimi kategorijami sprememb.

1. GLAVNA različica, ko naredite nezdružljive spremembe API -ja,
2. MINOR različica, ko funkcijo dodate na nazaj združljiv način,
3. Različica PATCH, ko popravite napake, ki so združljive z nazaj.

V podjetju Brainbow uporabljamo lastno različico semverja, prilagojeno potrebam projektov strojne opreme. Naša specifikacija sledi istemu vzorcu "Major. Minor. Patch", čeprav se naše definicije, katere spremembe spadajo v katero kategorijo, očitno razlikujejo.

1. MAJOR različica: uporablja se za pomembne spremembe osnovne funkcije vezja (npr.: preklop procesorja z ATmegae na ESP8266).
2. MINOR različica: uporablja se za zamenjavo komponent, ki bi lahko vplivale na delovanje vezja (npr.: zamenjava bliskavice SPI z delom, združljivim z zatiči, ki ima lahko drugačen nabor ukazov) ali dodajanje nekaterih manjših dodatnih funkcij (npr.: dodano dodatno tipalo temperature).
3. Različica PATCH: uporablja se za manjše popravke napak, ki ne spremenijo delovanja vezja (npr.: nastavitev svilenega sita, manjša prilagoditev postavitve sledi, enostavne zamenjave komponent, kot je kondenzator 0603 na 0805).

V strojni opremi semver se številka različice posodobi le pri izdelavi (tako kot v programski opremi se številke različic spreminjajo le z izdajami, ne pa se vsak posameznik zaveže k projektu). Posledično imajo številni projekti nizke številke različic. Projekt še ne uporablja več kot 4 večjih različic.

Poleg prednosti doslednosti in razumljivosti, ki jih dobite s prehodom na dobro opredeljen sistem poimenovanja, pridobite tudi koristi pri združljivosti vdelane programske opreme in zadovoljstvu strank. Vdelano programsko opremo lahko zapišete ob upoštevanju različice plošče, na katero cilja, in lažje je odpraviti napake, zakaj določen program ne deluje na določeni plošči ("prav, strojna programska oprema 2.4.1 se ne izvaja na 1.2 plošče, ker nimamo … "). Stranke so imele koristi tudi od naše strojne opreme semver, ker je storitev za stranke in odpravljanje težav veliko lažje z opredeljenim standardom.

9. korak: Napredno: uporaba semantičnih različic strojne opreme

Za uporabo strojne opreme semver v lastnih projektih uporabljamo funkcijo Git, imenovano označevanje. Ko prvič izdelate ploščo, je to različica 1.0.0 te plošče. Prepričajte se, da ste potrdili vse spremembe v svojem projektu, nato zaženite `git tag -a v1.0.0`. S tem se odpre urejevalnik, tako da lahko za to oznako napišete sporočilo z opombami (zelo podobno sporočilu o predaji). Vključujem podrobnosti o proizvodnji (kdo je izdelal tiskano vezje, kdo je sestavil ploščo), ki so lahko kasneje koristne informacije.

Oznaka za izdajo je dodana v zgodovino predaje in označuje stanje datotek pri izdelavi 1.0.0. To je lahko še posebej koristno pozneje, ko se morate za odpravljanje težav obrniti na to točko. Brez določene oznake izdaje bi bilo težko ugotoviti, katera zaveza je bila zadnja v času izdelave. Oznaka 1.0.0 (in 1.1, 1.1.1 itd.) Vam omogoča, da določite, da so bile te posebne izvorne datoteke tiste, ki so bile uporabljene v določenem proizvodnem ciklu.

Zapis o Gerbersu. Nekatere hiše za izdelavo plošče zahtevajo datoteke gerber, ki jih lahko ustvarite s programom KiCad. To so izpeljani predmeti, ustvarjeni iz izvorne datoteke.kicad_pcb, in običajno ne izvajamo nadzora različic izpeljanih datotek. V podjetju Brainbow ne hranimo gerberjev v nadzoru različic, razen ko označimo izdajo. Ko smo pripravljeni za izdelavo, generiramo datoteke gerber, jih shranimo v mapo Fabrication ter potrdimo in označimo. Nato odstranimo gerberje in izvršimo izbris. To se morda sprva zdi nekoliko zmedeno, vendar zagotavlja, da običajne urejenosti shranjujejo samo izvorne datoteke, označene izdaje pa hranijo tudi natančne datoteke, uporabljene za izdelavo plošč. To se je izkazalo za izjemno koristno pri odkrivanju proizvodnih napak nekaj tednov kasneje.

10. korak: Naslednji koraki

Upajmo, da vas je ta uvod dovolj naučil, da začnete uporabljati nadzor različic pri svojih projektih elektronike. Do nekaterih naprednejših tem, na primer nadzora različic za knjižnice, ki so v skupni rabi med projekti ali vejami funkcij, nismo prišli. Kljub temu je nadzor različic podoben uživanju zelenjave: morda ne boste dobili tistega, za kar mislite, da bi morali, a vsak vaš delček šteje.

Brainbow dela na podrobnejšem vodniku po nekaterih naprednejših funkcijah našega delovnega toka. Upamo, da ga bomo objavili v naslednjih nekaj mesecih. Sledite nam tukaj na strani Instructables in zagotovo vas bomo obvestili, ko jo boste lahko prebrali.

Hvala za branje in komaj čakamo, da vidimo, kaj naredite!