Kontrola verzija za hardver otvorenog koda: 10 koraka

2024 Autor: John Day | [email protected]. Zadnja promjena: 2024-01-30 09:36

Tim u Brainbowu ima pojam o brojnim projektima elektronike, a mi smo htjeli podijeliti naš postupak korištenja kontrole verzija za upravljanje tijekom dizajna elektronike. Ovaj tijek rada korišten je za velike i male projekte, od jednostavnih dvoslojnih ploča do složenih 10 slojnih behemota, a temelji se na alatima otvorenog koda. Nadajmo se da će drugi moći usvojiti naš tijek rada i steći prednosti kontrole verzija za vlastite projekte. No, koje prednosti kontrola verzija može ponuditi elektroničkom projektu?

Korak 1: Zašto verzija kontrolira vašu elektroniku?

Kontrola verzija (poznata i kao kontrola izvora ili kontrola revizije) dobro je razumljiv i široko prihvaćen koncept u softverskom inženjeringu. Ideja iza kontrole izvora je sustavno praćenje promjena u izvornom kodu programa ili aplikacije. Ako promjene prekinu aplikaciju, možete datoteke izvornog koda vratiti u poznato radno stanje iz prošlosti. U praksi, sustavi kontrole izvora omogućuju vam praćenje povijesti zbirke datoteka (obično datoteke izvornog koda za računalni program, web stranicu itd.) Te vizualiziranje i upravljanje promjenama tih datoteka.

Praćenje povijesti promjena projekta čini se korisnim za elektroničke projekte; ako pogriješite u shemi kola ili upotrijebite pogrešan otisak komponente u rasporedu PCB -a, bilo bi lijepo pratiti koje su greške napravljene i koji su popravci implementirani u različitim revizijama projekta. Također bi bilo korisno da drugi tvorci vide tu povijest, te razumiju kontekst i motive različitih promjena.

Korak 2: Alati: KiCad i Git

U ovom projektu koristimo dva glavna alata: sustav kontrole verzija (VCS) i program za automatizaciju dizajna elektronike (EDA ili ECAD).

Postoji mnogo sustava za kontrolu verzija, ali mi koristimo distribuirani VCS Git. Koristimo ga iz više razloga, no ključno je to što je otvorenog koda (provjeri!), Jednostavan za korištenje (provjeri!) I de-facto standardni VCS za softver otvorenog koda (provjeri!). Git ćemo koristiti kao VCS za praćenje promjena u datotekama koje koristi naš ECAD program. Ovaj Instructable ne zahtijeva poznavanje Gita, ali pretpostavlja se opća udobnost korištenjem naredbenog retka. Pokušat ću se povezati s korisnim resursima za upotrebu Gita i naredbenog retka prema potrebi.

Većina sustava za kontrolu izvora posebno dobro funkcionira za datoteke temeljene na tekstu, pa bi ECAD program koji koristi tekstualne datoteke bio izvrstan. Uđite u KiCad, open source "Cross Platform and Open Source Electronics Design Automation Suite" koji podržavaju istraživači iz CERN-a. KiCad je također otvorenog koda (provjerite!), Jednostavan za korištenje (iako se neki ne bi složili sa mnom u vezi s tim) i vrlo sposoban za napredne dizajnerske radove u elektronici.

Korak 3: Instalacija

Da biste instalirali ove programe, slijedite upute s njihovih različitih web mjesta za preuzimanje povezanih u nastavku.

• KiCad ima više platformi (i vrtoglavo tako; njihova stranica za preuzimanje navodi 13 podržanih OS-a i nudi preuzimanje izvornog koda ako vam ništa od toga ne odgovara). Koristite kicad-objedinjenu zadanu instalaciju, a ne noćnu razvojnu verziju. Pogledajte korak 4 za napredne izborne pojedinosti o instalaciji knjižnice.
• Git je također cross-platform. Ako koristite Windows, preporučio bih impresivan projekt Git for Windows za korisnije, potpunije iskustvo.

Dokumentacija za instalaciju dostupna na obje ove stranice bit će potpunija od bilo kojeg opisa koji ovdje mogu ponuditi. Nakon što se oba programa preuzmu i instaliraju, možete klonirati predložak projekta Brainbow iz našeg Github spremišta. Naredba git clone preuzima strukturu `git clone {src directory} {target directory}`; za naš projekt upotrijebite `git clone https://github.com/builtbybrainbow/kicad-starter.git {target directory}`.

Kloniranje git repoa poseban je oblik kopiranja; kada klonirate projekt, dobivate kopiju svih datoteka uključenih u repo, kao i cijelu povijest projekta koju prati Git. Kloniranjem našeg repo -a dobivate direktorij projekta koji je već strukturiran s našim preporukama za korištenje Gita s KiCadom. Više o strukturi projekta pokazat ćemo u 6. koraku ili možete prijeći na 7. korak ako vas svrbi rad.

Nekoliko brzih kućanskih poslova - pokrenite `git remote rm origin` da biste uklonili vezu na projekt Github iz kojeg ste klonirali. Također pokrenite `git commit --amend --author =" John Doe "`, zamijenivši parametar autora svojim imenom i adresom e -pošte. Time se mijenja posljednje urezivanje (koje je u ovom slučaju ujedno i prvo urezivanje) i mijenja se autor umjesto vas, a ne Brainbow.

Korak 4: Napomena o instalaciji: Knjižnice KiCad

Jedna kratka napomena o strukturi knjižnice KiCada. KiCad nudi skup knjižnica koje održava razvojni tim za širok raspon električnih komponenti. Postoje tri glavne biblioteke:

• Shematski simboli: Simboli koji se koriste za predstavljanje elektroničkih komponenti u shematskom crtežu sklopa.
• Otisci PCB -a: 2D crteži koji predstavljaju stvarni otisak (bakreni jastučići, tekst na sitotisku itd.) Koji će se koristiti pri postavljanju kruga na PCB.
• 3D modeli: 3D modeli elektroničkih komponenti.

Ove se knjižnice preuzimaju zajedno s programskim paketom KiCad koji ste upravo instalirali. KiCad možete koristiti bez ikakvog napora. Međutim, za "napredne korisnike" izvorne datoteke za knjižnice pohranjene su u git spremištu na Githubu, dopuštajući korisnicima koji žele biti u tijeku s najnovijim izmjenama da kloniraju repo biblioteke na svoj stroj. Praćenje knjižnica pomoću programa git ima niz prednosti - možete izabrati kada želite ažurirati svoje knjižnice, a ažuriranja trebaju samo unijeti promjene u datoteke, umjesto ponovnog preuzimanja cijelog skupa datoteka knjižnice. Međutim, vi ste odgovorni za ažuriranje knjižnica, što se može lako zaboraviti.

Ako želite klonirati knjižnice, ova web stranica opisuje različite Github repos KiCad ponude. Git klonirajte biblioteke na svoje računalo (npr: `git clone https:// github.com/KiCad/kicad-symbols.git`), zatim otvorite KiCad, odaberite traku izbornika" Postavke "i kliknite" Konfiguriraj staze … ". To vam omogućuje da kažete KiCadu put direktorija da traži svaku knjižnicu. Ove varijable okruženja zadane su prema stazi do knjižnica instaliranih s KiCad instalacijom; Zabilježio sam ove vrijednosti kako bih se po potrebi mogao vratiti na zadane knjižnice. KICAD_SYMBOL_DIR put trebao bi upućivati na vašu biblioteku kloniranih kicad-simbola, KISYSMOD na biblioteku kloniranih kicad-footprints, a KISYS3DMOD na kloniranu biblioteku kicad-packages3d.

Kad želite ažurirati knjižnice, možete pokrenuti jednostavnu naredbu `git pull` u repou knjižnice koja će reći Gitu da provjeri postoje li razlike između vaše lokalne kopije bibliotečkog repoa i" udaljenog "repoa Github -a i automatski ažurirati vaš lokalna kopija za uključivanje promjena.

Korak 5: Osnove Gita

Git je složen i mnogostruki program s čitavim knjigama posvećenim ovladavanju njime. Međutim, postoji nekoliko jednostavnih koncepata koji će vam pomoći razumjeti kako koristimo Git u svom tijeku rada.

Git prati promjene datoteka pomoću niza faza. Normalne promjene događaju se u radnom imeniku. Kad ste zadovoljni promjenama koje ste izvršili u nizu datoteka, datoteke koje ste promijenili dodate u područje za postavljanje. Nakon što ste izvršili sve promjene koje planirate i postavili sve datoteke koje želite pratiti u Gitu, urezujete te promjene u spremište. Urezivanja su u biti snimke stanja datoteka u repo -u u određeno vrijeme. Budući da Git prati promjene u datotekama i pohranjuje te promjene u urezivanjima, u bilo kojem trenutku možete vratiti projekt u stanje u kojem je bio pri bilo kojem prethodnom urezivanju.

Postoje složenije teme, poput grananja i daljinskog upravljača, ali ne moramo ih koristiti da bismo stekli prednosti kontrole izvora. Sve što trebamo je pratiti promjene u našim KiCad dizajnerskim datotekama s nizom urezivanja.

Korak 6: Struktura projekta KiCad

Pogledajmo pobliže strukturu projekta KiCad-Starter koji ste ranije klonirali. Podijeljen je u nekoliko poddirektorija radi lakše organizacije:

• Krug: Ova mapa sadrži stvarne datoteke projekta KiCad (sheme, PCB, itd.). Ne preimenujem ovu mapu, ali preimenujem sve datoteke u njoj s imenom projekta (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: datoteka projekta KiCad
  • Circuit.sch: KiCad shematska datoteka.
  • Circuit.kicad_pcb: datoteka izgleda KiCad PCB -a.
• Dokumentacija: Ova mapa služi za pohranu dokumentacije o projektu. Imamo planove za poboljšanje ovog prostora u budućnosti, ali za sada sadrži jednostavnu datoteku README. Koristite ga za spremanje bilješki o projektu za buduće preglede.
• Izrada: Ova mapa je mjesto gdje ćete pohraniti gerber datoteke koje će većina kućica koristiti za proizvodnju vaše ploče. Također ga koristimo za spremanje BOM datoteka i drugih dokumenata koji mogu biti potrebni za proizvodnju i montažu.
• Knjižnice: Ova mapa služi za spremanje datoteka biblioteka specifičnih za projekt (o tome ćemo više govoriti u nekoliko koraka).

Možda ste primijetili i nekoliko drugih datoteka (osobito ako ste `ls -a` direktorij). Direktorij.git je mjesto gdje Git čini magiju, spremajući povijest spremišta. Datoteka.gitignore koristi se da kaže Gitu koje datoteke treba zanemariti, a ne pohraniti u izvornoj kontroli. To su uglavnom sigurnosne kopije datoteka koje KiCad generira, ili nekoliko različitih "generiranih" datoteka, poput popisa mreža, koje se ne bi trebale pohraniti u izvornu kontrolu jer su generirane iz izvora koji je shematska datoteka.

Ova struktura projekta samo je polazište. Trebali biste ga prilagoditi svojim potrebama i prema potrebi dodati odjeljke. U neke smo projekte uključili programsku mapu ili mapu kućišta u koju smo pohranili modele za 3D ispis kućišta za projekt.

Korak 7: Korištenje Gita za KiCad projekte

Napokon smo spremni vidjeti kako koristiti Git za praćenje vaših projekata. Ovaj Instructable ne želi vas naučiti kako koristiti KiCad (iako ću ga možda napraviti u budućnosti ako za njim postoji potražnja), pa ćemo proći kroz neke trivijalne primjere kako bismo vam pokazali kako teče tijek rada. Trebalo bi biti lako razumjeti kako prilagoditi te ideje stvarnom projektu.

Otvorite direktorij kicad-starter, a zatim pokrenite `git log` za prikaz povijesti urezivanja. Ovdje bi trebalo postojati jedno urezivanje, inicijalizacija repo -a od strane Brainbow -a. Pokretanje `git statusa` reći će vam status datoteka u vašem repo -u (bez pratnje, izmijenjene, obrisane, iscenirane).

Trenutno ne biste trebali imati promjena u svom repo -u. Učinimo promjenu. Otvorite projekt KiCad i u shemu dodajte otpornik, a zatim spremite. Sada pokretanje `git statusa` trebalo bi pokazati da ste promijenili datoteku sheme, ali još niste postavili te izmjene za urezivanje. Ako vas zanima što je točno KiCad učinio kad ste dodali otpornik, možete pokrenuti naredbu diff na izmijenjenoj datoteci `git diff Circuit/Circuit.sch`. Ovo će istaknuti promjene između trenutne verzije datoteke u radnom direktoriju i stanja datoteke pri zadnjem urezivanju.

Sada kada smo napravili promjenu, pokušajmo tu promjenu unijeti u našu povijest projekta. Moramo premjestiti izmjene iz našeg radnog imenika u početno područje. Ovo zapravo ne pomiče datoteke u datotečnom sustavu, ali je konceptualno način da se Gitu da do znanja da ste izvršili sve planirane izmjene za određenu datoteku i da ste spremni izvršiti te promjene. Korisno je što Git daje neke savjete kada pokrenete `git status` za sljedeću radnju. Primijetite poruku `(upotrijebite" git add … "da biste ažurirali ono što će biti predano)` pod `Promjene nisu etažirane za urezivanje:`. Git vam govori kako premjestiti promjene u područje za postavljanje. Pokrenite `git add Circuit/Circuit.sch` da biste postavili promjene, a zatim` git status` da vidite što se dogodilo. Sada vidimo shematsku datoteku pod promjenama koje treba zabilježiti. Ako još ne želite izvršiti ove promjene, Git korisno nudi još jedan savjet: `(upotrijebite" git reset HEAD … "za nestabilizaciju)`. Mi želimo predati ove promjene, pa pokrećemo `git commit -m" Dodan otpornik shemi "". Ovo potvrđuje promjene s ponuđenom porukom. Pokretanje git dnevnika prikazat će ovo urezivanje u povijesti predavanja projekta.

Još nekoliko savjeta o urezivanjima.

1. Ne obvezujte se pri svakom spremanju. Počinite kad se osjećate da ste dosegli točku u kojoj su se vaše promjene donekle učvrstile. Obvezujem nakon što dovršim shemu, a ne nakon svakog dodavanja komponente. Također se ne želite obvezati previše rijetko, jer pamćenje konteksta zašto ste unijeli promjene koje ste unijeli 3 tjedna kasnije može biti teško. Shvatiti kada se obvezati malo je umjetnost, ali postat ćete ugodniji što više budete koristili Git.
2. Samo izvor trgovine (uglavnom). To uključuje datoteke projekta, sheme i rasporede, kao i biblioteke specifične za projekt. To također može uključivati dokumentacijske datoteke. Budite oprezni pri pohranjivanju izvedenih objekata jer se oni lako mogu sinkronizirati s izvornim izvorom, što kasnije uzrokuje glavobolje. BOM i gerber datoteke posebno se deinhroniziraju pa ih je bolje izbjegavati (iako su detaljnije upute obrađene u koraku 9).
3. Poruke urezivanja vrlo su korisne, ali dobro strukturirane poruke predavanja neprocjenjive su. Ovaj izvrstan članak pruža neke smjernice za pisanje jasnih, sažetih, korisnih poruka predavanja. To može zahtijevati korištenje uređivača teksta naredbenog retka, što početnicima može biti komplicirano (`git commit` bez opcije -m poruka otvorit će uređivač teksta). Za većinu ljudi preporučujem Nano editor. StackOverflow ima dobro objašnjenje za promjenu uređivača

Korak 8: Napredno: semantičko određivanje verzija za elektroniku

Za avanturističke duše, sljedeći savjeti su napredne ideje, prikupljene iz više sati razvoja KiCada. Nisu osobito korisni na manjim projektima, ali vam mogu doista uštedjeti bol u glavi jer vaši projekti postaju sve složeniji.

U softveru postoji koncept semantičkog određivanja verzija (semver). Semver definira uobičajenu metodologiju imenovanja za identifikaciju izdanja softvera prema "broju verzije", slijedeći obrazac "Major. Minor. Patch". Da citirate semverove specifikacije, unaprijedite broj verzije prema sljedećim kategorijama promjena.

1. VEĆA verzija kada unosite nekompatibilne izmjene API -ja,
2. MINOR verzija kada dodate funkcionalnost na unatrag kompatibilan način,
3. PATCH verzija kada ispravite pogreške kompatibilne sa unatrag.

Mi u Brainbowu koristimo vlastitu verziju semvera prilagođenu potrebama hardverskih projekata. Naše specifikacije slijede isti obrazac "Major. Minor. Patch", iako se naše definicije o tome koje promjene spadaju u koju kategoriju očito razlikuju.

1. MAJOR verzija: koristi se za značajne promjene u osnovnoj funkcionalnosti kruga (npr. Prebacivanje procesora s ATmegae na ESP8266).
2. MINOR verzija: koristi se za zamjenu komponenti koje bi mogle utjecati na rad kruga (npr. Zamjena bljeskalice SPI s dijelom kompatibilnim sa pin-om koji može imati drugačiji skup naredbi) ili dodavanjem neke manje dodatne značajke (npr. Dodatni senzor temperature).
3. Verzija PATCH -a: koristi se za manje ispravke programskih pogrešaka koji neće promijeniti rad kruga (npr.: podešavanje sitotiska, manje podešavanje izgleda tragova, jednostavne zamjene komponenti poput kondenzatora 0603 na 0805).

U hardverskom semveru broj verzije ažurira se samo u proizvodnji (baš kao i u softveru, brojevi verzija mijenjaju se samo s izdanjima, a ne svaki pojedinac koji se obvezuje na projekt). Zbog toga mnogi projekti imaju male brojeve verzija. Još moramo imati projekt koji koristi više od 4 glavne verzije.

Osim prednosti u dosljednosti i razumljivosti koje dobivate prelaskom na dobro definiran sustav imenovanja, dobivate i prednosti u kompatibilnosti firmvera i zadovoljstvu korisnika. Firmware se može napisati uzimajući u obzir verziju ploče na koju cilja, i može biti lakše otkloniti pogreške zašto određeni program ne radi na određenoj ploči ("dobro, firmver 2.4.1 ne radi na 1.2 ploče jer nemamo … "). Korisnici su također imali koristi od našeg hardvera semver jer je korisnička usluga i rješavanje problema mnogo lakše s definiranim standardom.

Korak 9: Napredno: Korištenje hardverskog semantičkog verzija

Za korištenje hardverskog semvera u vlastitim projektima koristimo značajku Git koja se naziva označavanje. Kad prvi put proizvodite ploču, to je 1.0.0 verzija te ploče. Provjerite jeste li izvršili sve promjene u svom projektu, a zatim pokrenite `git tag -a v1.0.0`. Ovo će otvoriti uređivač tako da možete napisati poruku s bilješkom za ovu oznaku (vrlo slično poruci urezivanja). Uključujem pojedinosti o proizvodnji (tko je napravio PCB, tko je sastavio ploču), što kasnije može biti korisno.

Oznaka izdanja dodaje se u povijest urezivanja i pokazuje stanje datoteka pri izradi 1.0.0. Ovo može biti osobito korisno nekoliko revizija kasnije kada se morate vratiti na ovu točku radi rješavanja problema. Bez navedene oznake izdanja moglo bi biti teško shvatiti koja je predaja bila posljednja u vrijeme proizvodnje. Oznaka 1.0.0 (i 1.1, 1.1.1, itd.) Omogućuje vam da navedete da su te određene izvorne datoteke bile one koje su korištene u određenom proizvodnom ciklusu.

Bilješka o Gerberima. Neke kućice zahtijevaju gerber datoteke za izradu vaše ploče, a možete ih generirati pomoću KiCada. To su izvedeni objekti, generirani iz izvorne.kicad_pcb datoteke i obično ne kontroliramo izvedbe izvedenih datoteka. Mi u Brainbowu ne spremamo gerbere u kontrolu verzija OSIM za označavanje izdanja. Kad smo spremni za izradu, generiramo gerber datoteke, pohranjujemo ih u mapu Fabrication te urezujemo i označavamo. Zatim uklonimo gerbere i izvršimo brisanje. Ovo se u početku može činiti pomalo zbunjujućim, ali osigurava da normalne predaje pohranjuju samo izvorne datoteke, a označena izdanja također pohranjuju točne datoteke korištene za izradu ploča. Ovo se pokazalo izuzetno korisnim u praćenju grešaka u proizvodnji tjednima kasnije.

Korak 10: Sljedeći koraci

Nadamo se da vas je ovaj uvod naučio dovoljno da počnete koristiti kontrolu verzija na vlastitim projektima elektronike. Nismo došli do nekih naprednijih tema, poput kontrole verzija za knjižnice koje se dijele između projekata ili grana značajki. Ipak, kontrola verzija je poput konzumiranja vašeg povrća: možda nećete dobiti ono što mislite da biste trebali, ali svaki vaš dio se računa.

Brainbow radi na detaljnijem vodiču za neke od naprednijih značajki našeg tijeka rada. Nadamo se da ćemo ga objaviti u sljedećih nekoliko mjeseci. Pratite nas ovdje na stranici Instructables, a mi ćemo vas svakako obavijestiti kad je možete pročitati.

Hvala vam na čitanju i jedva čekamo vidjeti što ćete napraviti!