Kontrola verzija za hardver otvorenog koda: 10 koraka

2024 Autor: John Day | [email protected]. Zadnja izmjena: 2024-01-30 08:07

Tim iz Brainbow -a ima niz elektroničkih projekata pod pojasom, a mi smo htjeli podijeliti naš proces korištenja kontrole verzija za upravljanje našim 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 zasnovan je na alatima otvorenog koda. Nadajmo se da će drugi moći usvojiti naš tijek rada i steći prednosti kontrole verzija za svoje vlastite projekte. Ali 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, datoteke izvornog koda možete vratiti u poznato radno stanje iz prošlosti. U praksi, sistemi za kontrolu izvora dozvoljavaju vam da pratite istoriju zbirke datoteka (obično datoteke izvornog koda za računarski program, web lokaciju itd.), Te vizualizirate i upravljate promjenama tih datoteka.

Praćenje povijesti promjena na projektu č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 koje su popravke implementirane u različitim revizijama projekta. Bilo bi korisno i za druge tvorce da vide tu povijest i razumiju kontekst i motive različitih promjena.

Korak 2: Alati: KiCad i Git

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

Postoji mnogo sistema za kontrolu verzija, ali mi koristimo distribuirani VCS Git. Koristimo ga iz više razloga, ali ključno je to što je otvorenog koda (provjeri!), Jednostavan za korištenje (provjeri!) I de-facto standardni VCS za softver otvorenog koda (provjeri!). Koristit ćemo Git 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 naredbene linije. Pokušat ću se povezati s korisnim resursima za upotrebu Gita i naredbenog retka prema potrebi.

Većina sistema za kontrolu izvora radi posebno dobro za tekstualne datoteke, pa bi ECAD program koji koristi tekstualne datoteke bio odličan. 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 upotrebu (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 stranica za preuzimanje koje su dolje navedene.

• KiCad je za 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-unified default install, a ne noćnu razvojnu verziju. Pogledajte korak 4 za napredne opcionalne detalje o instalaciji biblioteke.
• Git je takođe cross-platform. Ako koristite Windows, preporučio bih impresivan projekt Git for Windows za korisnije, potpuno opremljeno 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 koristite `git clone https://github.com/builtbybrainbow/kicad-starter.git {target directory}`.

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

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

Korak 4: Instalacija Napomena: KiCad biblioteke

Jedna kratka napomena o strukturi biblioteke KiCad -a. KiCad pruža skup biblioteka koje održava razvojni tim za širok raspon električnih komponenti. Postoje tri glavne biblioteke:

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

Ove biblioteke se preuzimaju zajedno sa KiCad programskim paketom koji ste upravo instalirali. KiCad možete koristiti bez dodatnih napora. Međutim, za "napredne korisnike" izvorne datoteke za biblioteke pohranjene su u git spremištu na Githubu, omogućavajući korisnicima koji žele biti u toku s najnovijim promjenama da kloniraju repo biblioteke na vlastitu mašinu. Praćenje biblioteka pomoću gita ima niz prednosti - možete izabrati kada želite ažurirati svoje biblioteke, a ažuriranja samo trebaju unijeti promjene u datoteke, umjesto ponovnog preuzimanja cijelog skupa datoteka biblioteke. Međutim, vi ste odgovorni za ažuriranje biblioteka, što se lako može zaboraviti.

Ako želite klonirati biblioteke, 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 stavku izbornika" Preferences "i kliknite" Configure Paths … ". Ovo vam omogućava da kažete KiCad -u putanju direktorija da traži svaku biblioteku. Ove varijable okruženja zadane su prema stazi do biblioteka instaliranih s KiCad instalacijom; Zabilježio sam ove vrijednosti kako bih se po potrebi mogao vratiti na zadane biblioteke. KICAD_SYMBOL_DIR putanja bi trebala ukazivati na vašu biblioteku kloniranih kicad-simbola, KISYSMOD na biblioteku kloniranih kicad-footprints, a KISYS3DMOD na kloniranu biblioteku kicad-packages3d.

Kad želite ažurirati biblioteke, možete pokrenuti jednostavnu naredbu `git pull` u repou biblioteke koja će reći Gitu da provjeri 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 mnogostruk program s čitavim knjigama posvećenim savladavanju. Međutim, postoji nekoliko jednostavnih koncepata koji će vam pomoći da razumijete kako koristimo Git u svom toku rada.

Git prati promjene datoteka koristeći niz faza. Normalne promjene se dešavaju u radnom direktoriju. Kada ste zadovoljni promjenama koje ste izvršili u nizu datoteka, datoteke koje ste promijenili dodate u područje za postavljanje. Nakon što napravite sve promjene koje planirate i iscenirate sve datoteke koje želite pratiti u Gitu, urezujete te promjene u spremište. Urezivanja su u osnovi snimci 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 naših dizajnerskih datoteka KiCad -a 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 on sadrži jednostavnu datoteku README. Koristite ga za spremanje bilješki o projektu za buduće preglede.
• Proizvodnja: Ova mapa je mjesto gdje ćete pohraniti gerber datoteke koje će većina kuća 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.
• Biblioteke: 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 (posebno ako `direktorij budete` ls -a`). Direktorijum.git je mesto gde Git čini magiju, čuvajući istoriju spremišta. Datoteka.gitignore se koristi da kaže Gitu koje datoteke treba zanemariti, a ne pohraniti u izvornoj kontroli. To su uglavnom sigurnosne kopije datoteka koje generira KiCad, ili nekoliko različitih "generiranih" datoteka, poput spiskova na Internetu, koje ne bi trebale biti pohranjene u izvornoj kontroli jer su generirane iz izvora koji je shematska datoteka.

Ova struktura projekta je samo 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: Upotreba Gita za KiCad projekte

Konačno smo spremni vidjeti kako koristiti Git za praćenje vaših projekata. Ovaj Instructable nije namijenjen da vas nauči kako koristiti KiCad (iako bih to mogao učiniti 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 ove 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, izbrisane, postepene).

Trenutno ne biste trebali imati promjena u svom repo -u. Hajde da napravimo promjenu. Otvorite KiCad projekt i dodajte otpornik na shemu, a zatim spremite. Sada pokretanje `git statusa` trebalo bi pokazati da ste izmijenili datoteku sheme, ali još niste postavili te promjene za urezivanje. Ako vas zanima što je točno KiCad učinio kada 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 historiju projekata. Moramo premjestiti promjene iz našeg radnog imenika u područje za pripremu. Ovo zapravo ne pomiče datoteke u sistemu datoteka, ali je konceptualno način da se Gitu stavi do znanja da ste izvršili sve planirane promjene 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 izmjene u scensko područje. Pokrenite `git add Circuit/Circuit.sch` da izvedete promjene, a zatim` git status` da vidite šta 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 potvrditi ove promjene, pa pokrećemo `git commit -m" Dodan otpornik na shemu "`. 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 spašavanju. Počinite kad se osjećate da ste dosegli točku u kojoj su se vaše promjene donekle učvrstile. Obavezujem se nakon što završim shemu, a ne nakon svakog dodavanja komponente. Takođe ne želite da se obavezujete previše rijetko, jer pamćenje konteksta zašto ste izvršili promjene koje ste izvršili 3 sedmice kasnije može biti teško. Shvatiti kada se obvezati malo je umjetnost, ali postat ćete ugodniji ako budete koristili Git.
2. Samo izvor trgovine (uglavnom). Ovo uključuje datoteke projekta, sheme i rasporede, kao i biblioteke specifične za projekat. Ovo takođe može uključivati datoteke dokumentacije. Budite oprezni pri pohranjivanju izvedenih objekata jer se oni lako mogu sinkronizirati s izvornim izvorom, što kasnije uzrokuje glavobolje. BOM i gerber datoteke posebno lako se deinhroniziraju, pa ih je bolje izbjegavati (iako su detaljnija uputstva obrađena u koraku 9).
3. Poruke urezivanja su vrlo korisne, ali dobro strukturirane poruke predavanja su neprocjenjive. Ovaj odličan članak pruža neke smjernice za pisanje jasnih, sažetih, korisnih poruka urezivanja. To može zahtijevati korištenje uređivača teksta naredbenog retka, što može biti komplicirano za početnike (`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 izdavanje verzija za elektroniku

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

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

1. VEĆA verzija kada unesete nekompatibilne izmjene API -ja,
2. MINOR verzija kada dodate funkcije na unatrag kompatibilan način,
3. PATCH verzija kada pravite unatrag kompatibilne ispravke grešaka.

Mi u Brainbow -u 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 sa 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. PATCH verzija: koristi se za manje ispravke programskih pogrešaka koji neće promijeniti rad kola (npr.: podešavanje svilene ekrana, manje podešavanje rasporeda 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 se mijenjaju samo s izdanjima, a ne svaki pojedinac koji se posvećuje projektu). Kao rezultat 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 imate od prelaska na dobro definiran sistem imenovanja, dobivate i prednosti u kompatibilnosti firmvera i zadovoljstvu korisnika. Firmware se može pisati uzimajući u obzir verziju ploče na koju cilja, a može biti lakše otkloniti greš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 hardverskih semantičkih verzija

Da bismo koristili hardverski semver u svojim projektima, koristimo Git funkciju koja se naziva označavanje. Kada prvi put proizvodite ploču, to je 1.0.0 verzija te ploče. Uvjerite se da ste 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 detalje o proizvodnji (ko je napravio PCB, ko je sastavio ploču), što kasnije može biti korisno.

Oznaka izdanja se dodaje u povijest predavanja i pokazuje stanje datoteka pri izradi 1.0.0. Ovo može biti posebno korisno nekoliko revizija kasnije kada se trebate 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ćava vam da navedete da su te određene izvorne datoteke bile one koje su korištene u određenom proizvodnom ciklusu.

Bilješka o Gerbersu. Za neke kuće potrebne su gerber datoteke za izradu ploče, a možete ih generirati pomoću KiCada. To su izvedeni objekti, generirani iz izvorne.kicad_pcb datoteke, a mi obično ne kontroliramo verzije izvedenim datotekama. Mi u Brainbow -u ne skladištimo gerbere u kontroli verzija OSIM za označavanje izdanja. Kad smo spremni za izgradnju, generiramo gerber datoteke, pohranjujemo ih u mapu Fabrication i 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 normalni urezi pohranjuju samo izvorne datoteke, a označena izdanja također pohranjuju tačne datoteke korištene za proizvodnju ploča. Ovo se pokazalo izuzetno korisnim u praćenju grešaka u proizvodnji nekoliko sedmica kasnije.

Korak 10: Sljedeći koraci

Nadajmo 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 biblioteke koje dijele projekti ili grane funkcija. Ipak, kontrola verzija je poput jedenja 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 do nekih naprednijih funkcija našeg toka rada. Nadamo se da ćemo ga objaviti u narednih nekoliko mjeseci. Pratite nas ovdje na stranici Instructables, a mi ćemo vas svakako obavijestiti kada je možete pročitati.

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