Kontrola verzií hardvéru s otvoreným zdrojovým kódom: 10 krokov

2024 Autor: John Day | [email protected]. Naposledy zmenené: 2024-01-30 11:59

Tím v Brainbow má pod pásmi niekoľko projektov v oblasti elektroniky a chceli sme sa podeliť o náš postup pri používaní správy verzií na správu pracovného toku návrhu elektroniky. Tento pracovný postup bol použitý pre veľké i malé projekty, od jednoduchých dvojvrstvových dosiek po komplexné 10-vrstvové monštrá a je založený na nástrojoch s otvoreným zdrojovým kódom. Našťastie si ostatní môžu náš pracovný postup osvojiť sami a získať výhody správy verzií pre svoje vlastné projekty. Aké výhody však môže správa verzií ponúknuť projektu elektroniky?

Krok 1: Prečo verzia ovláda vašu elektroniku?

Správa verzií (aka kontrola zdroja alebo kontrola revízií) je dobre zrozumiteľný a široko používaný koncept v softvérovom inžinierstve. Myšlienkou riadenia zdroja je systematické sledovanie zmien vykonaných v zdrojovom kóde programu alebo aplikácie. Ak zmeny narušia aplikáciu, môžete súbory zdrojového kódu vrátiť do známeho pracovného stavu z minulosti. V praxi vám systémy riadenia zdrojov umožňujú sledovať históriu zbierky súborov (zvyčajne súbory zdrojových kódov pre počítačový program, webovú stránku atď.), Vizualizovať a spravovať zmeny týchto súborov.

Sledovanie histórie zmien projektu sa zdá byť užitočné pre projekty elektroniky; Ak urobíte chybu v schéme zapojenia alebo použijete nesprávnu stopu súčiastky v rozložení DPS, bolo by pekné sledovať, aké chyby boli urobené a aké opravy boli implementované pri rôznych revíziách projektu. Pre ostatných tvorcov by bolo tiež užitočné vidieť túto históriu a porozumieť kontextu a motivácii rôznych zmien.

Krok 2: Nástroje: KiCad a Git

V tomto projekte používame dva hlavné nástroje: systém na správu verzií (VCS) a program na automatizáciu návrhu elektroniky (EDA alebo ECAD).

Existuje mnoho systémov na správu verzií, ale používame distribuovaný VCS Git. Používame ho z niekoľkých dôvodov, ale kľúčové je, že je open-source (kontrola!), Jednoduché použitie (kontrola!) A de facto štandardný VCS pre softvér s otvoreným zdrojovým kódom (kontrola!). Git budeme používať ako VCS na sledovanie zmien v súboroch, ktoré používa náš program ECAD. Tento návod nevyžaduje znalosti Gitu, ale predpokladá sa všeobecné pohodlie pomocou príkazového riadka. Pokúsim sa podľa potreby prepojiť s užitočnými zdrojmi pre Git aj pre príkazový riadok.

Väčšina systémov na správu zdrojov funguje obzvlášť dobre na textové súbory, takže program ECAD, ktorý používa textové súbory, by bol skvelý. Zadajte KiCad, open-source „Cross Platform and Open Source Electronics Design Automation Suite“, za ktorým stoja vedci z CERN. KiCad je tiež open-source (skontrolujte!), Ľahko sa používa (aj keď niektorí so mnou v tomto nesúhlasia) a je schopný pokročilých návrhárskych prác v oblasti elektroniky.

Krok 3: Inštalácia

Ak chcete nainštalovať tieto programy, postupujte podľa pokynov z ich nižšie uvedených odkazov na sťahovanie údajov.

• KiCad je multiplatformový (a je to závratné; na stránke sťahovania je uvedených 13 podporovaných operačných systémov a ponúka stiahnutie zdrojového kódu, ak vám žiadny z nich nevyhovuje). Použite predvolenú inštaláciu zjednotenú kicadom, nie nočnú vývojovú zostavu. V kroku 4 nájdete rozšírené voliteľné podrobnosti o inštalácii knižnice.
• Git je tiež multiplatformový. Ak používate Windows, odporučil by som pôsobivý projekt Git pre Windows ako užitočnejší a plne vybavený zážitok.

Inštalačná dokumentácia dostupná na oboch týchto serveroch bude úplnejšia než akýkoľvek popis, ktorý tu môžem ponúknuť. Po stiahnutí a inštalácii oboch programov môžete klonovať šablónu projektu Brainbow z nášho úložiska Github. Príkaz git clone má štruktúru `git clone {adresár src} {cieľový adresár}`; pre náš projekt použite `git clone https://github.com/builtbybrainbow/kicad-starter.git {cieľový adresár}`.

Klonovanie git repo je špeciálna forma kopírovania; pri klonovaní projektu získate kópiu všetkých súborov zahrnutých v repo, ako aj celú históriu projektu sledovanú pomocou Git. Klonovaním nášho repo získate adresár projektu, ktorý je už štruktúrovaný podľa našich odporúčaní na používanie Gitu s KiCadom. V štruktúre projektu sa budeme podrobnejšie zaoberať v kroku 6, alebo môžete prejsť na krok 7, ak vás už začne svrbieť práca.

Niekoľko úloh rýchleho upratovania - spustením príkazu „git remote rm origin` odstráňte odkaz na projekt Github, z ktorého ste klonovali. Tiež spustite `git commit --amend --author =" John Doe "`, pričom parameter autora nahraďte svojim menom a e -mailom. Tým sa mení a dopĺňa posledný záväzok (ktorý je v tomto prípade zároveň prvým potvrdením) a zmení sa autor na vás, nie na Brainbow.

Krok 4: Inštalácia Poznámka: Knižnice KiCad

Jedna rýchla poznámka o štruktúre knižnice KiCad. KiCad poskytuje sadu knižníc spravovaných vývojovým tímom pre široký sortiment elektrických komponentov. Existujú tri hlavné knižnice:

• Schematické symboly: Symboly používané na znázornenie elektronických súčiastok na schematickom výkrese obvodu.
• Stopy plošných spojov: 2D výkresy predstavujúce skutočnú stopu (medené podložky, text na sieťotlači atď.), Ktoré sa majú použiť pri rozložení obvodu na doske plošných spojov.
• 3D modely: 3D modely elektronických súčiastok.

Tieto knižnice sa stiahnu spolu s programovým balíkom KiCad, ktorý ste práve nainštalovali. KiCad môžete používať bez väčšieho úsilia. Pre „náročných používateľov“sú však zdrojové súbory pre knižnice uložené v úložisku git na Githube, čo umožňuje používateľom, ktorí chcú zostať v obraze o najnovších zmenách, klonovať repo knižnice na vlastný počítač. Sledovanie knižníc pomocou git má množstvo výhod - môžete si vybrať, kedy chcete aktualizovať svoje knižnice, a aktualizácie musia zahŕňať iba zmeny súborov, a nie znova sťahovať celú sadu súborov knižníc. Ste však zodpovední za aktualizáciu knižníc, na ktorú môžete ľahko zabudnúť.

Ak by ste chceli klonovať knižnice, táto stránka podrobne popisuje rôzne ponuky Github repos KiCad. Git naklonujte knižnice do svojho počítača (napr. `Git clone https:// github.com/KiCad/kicad-symbols.git`), potom otvorte KiCad, v paneli s ponukami zvoľte položku„ Predvoľby “a kliknite na„ Konfigurovať cesty … “. Vďaka tomu môžete KiCadu oznámiť cestu k adresáru, v ktorom má hľadať každú knižnicu. Tieto premenné prostredia sú predvolene určené pre cestu ku knižniciam nainštalovaným pomocou inštalácie KiCad; Zaznamenal som tieto hodnoty, aby som sa v prípade potreby mohol vrátiť späť k predvoleným knižniciam. Cesta KICAD_SYMBOL_DIR by mala smerovať na vašu klonovanú knižnicu symbolov kicad, KISYSMOD na klonovanú knižnicu kicad-footprints a KISYS3DMOD na klonovanú knižnicu kicad-packages3d.

Ak chcete aktualizovať knižnice, môžete v repo knižnice spustiť jednoduchý príkaz „git pull“, ktorý Gitovi povie, aby skontroloval rozdiely medzi vašou lokálnou kópiou repo knižnice a „vzdialeným“repo Githubu a automaticky aktualizoval lokálna kópia na začlenenie zmien.

Krok 5: Základy Git

Git je komplexný a mnohostranný program, ktorého zvládnutím sa zaoberajú celé knihy. Existuje však niekoľko jednoduchých konceptov, ktoré vám pomôžu pochopiť, ako používame Git v našom pracovnom toku.

Git sleduje zmeny súborov pomocou série fáz. K normálnym zmenám dochádza v pracovnom adresári. Keď ste spokojní so zmenami, ktoré ste urobili v sérii súborov, pridáte súbory, ktoré ste zmenili, do pracovnej oblasti. Keď vykonáte všetky plánované zmeny a zinscenujete všetky súbory, ktoré chcete sledovať v Gite, tieto zmeny odošlete do úložiska. Záväzky sú v podstate snímky stavu súborov v repo v konkrétnom čase. Pretože Git sleduje zmeny v súboroch a ukladá tieto zmeny do potvrdení, v ktoromkoľvek bode môžete projekt vrátiť späť do stavu, v akom bol pri akomkoľvek predchádzajúcom potvrdení.

Existujú zložitejšie témy, ako napríklad vetvenie a diaľkové ovládače, ale nepotrebujeme ich používať na získanie výhod riadenia zdrojov. Všetko, čo potrebujeme, je sledovať zmeny v našich súboroch návrhu KiCad pomocou série potvrdení.

Krok 6: Štruktúra projektu KiCad

Pozrime sa podrobnejšie na štruktúru projektu KiCad-Starter, ktorý ste klonovali skôr. Pre jednoduchú organizáciu je rozdelený do niekoľkých podadresárov:

• Okruh: Tento priečinok obsahuje skutočné súbory projektu KiCad (schematický, PCB atď.). Tento priečinok nepremenujem, ale premenujem všetky súbory vo vnútri s názvom projektu (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: súbor projektu KiCad
  • Circuit.sch: schematický súbor KiCad.
  • Circuit.kicad_pcb: súbor rozloženia DPS KiCad.
• Dokumentácia: Tento priečinok slúži na ukladanie dokumentácie týkajúcej sa projektu. Máme v pláne v budúcnosti tento priestor vylepšiť, ale zatiaľ obsahuje jednoduchý súbor README. Použite ho na uloženie poznámok k projektu, ktoré si v budúcnosti môžete pozrieť.
• Výroba: V tomto priečinku budete ukladať súbory Gerber, ktoré väčšina fabových domov použije na výrobu obvodovej dosky. Používame ho aj na ukladanie súborov kusovníkov a ďalších dokumentov, ktoré môžu byť potrebné pre výrobu a montáž.
• Knižnice: Tento priečinok je na ukladanie súborov knižníc špecifických pre projekt (týmto sa budeme podrobnejšie venovať v niekoľkých krokoch).

Možno ste si tiež všimli niekoľko ďalších súborov (najmä ak máte priečinok „ls -a`). Adresár.git je miesto, kde Git čaruje a ukladá históriu úložiska. Súbor.gitignore sa používa na to, aby povedal Gitu, ktoré súbory má ignorovať a neukladať do správy zdrojov. Väčšinou sa jedná o záložné súbory, ktoré generuje KiCad, alebo niekoľko rôznych „generovaných“súborov, ako sú napríklad zoznamy netov, ktoré by nemali byť uložené v zdrojovom riadení, pretože sú generované zo zdroja, ktorý je schematickým súborom.

Táto štruktúra projektu je len východiskovým bodom. Mali by ste ho prispôsobiť svojim požiadavkám a podľa potreby pridať sekcie. V niektorých projektoch sme zahrnuli priečinok so softvérom alebo priečinok s prílohami, kde sme pre projekt uložili modely pre kryty s 3D tlačou.

Krok 7: Použitie Gitu pre projekty KiCad

Konečne sme pripravení zistiť, ako používať Git na sledovanie vašich projektov. Tento návod nie je určený na to, aby vás naučil používať KiCad (aj keď ho môžem v budúcnosti urobiť, ak bude po ňom dopyt), preto si ukážeme niekoľko triviálnych príkladov, ktoré vám ukážu, ako beží pracovný postup. Malo by byť ľahké pochopiť, ako prispôsobiť tieto nápady skutočnému projektu.

Otvorte adresár kicad-starter a potom spustením príkazu `git log` zobrazte históriu potvrdení. Malo by tu dôjsť k jednému potvrdeniu, inicializácii repa spoločnosťou Brainbow. Spustenie `git status` vám oznámi stav súborov vo vašom repo (nesledovanom, upravenom, odstránenom, usporiadanom).

V tejto chvíli by ste vo svojom repo nemali robiť žiadne zmeny. Urobme zmenu. Otvorte projekt KiCad a do schémy pridajte odpor a potom uložte. Teraz spustený príkaz „git status“by mal ukázať, že ste upravili schematický súbor, ale tieto zmeny ste zatiaľ nezaviedli. Ak vás zaujíma, čo presne KiCad urobil, keď ste pridali odpor, môžete spustiť príkaz diff v upravenom súbore `git diff Circuit/Circuit.sch`. Tým sa zvýraznia zmeny medzi aktuálnou verziou súboru v pracovnom adresári a stavom súboru pri poslednom potvrdení.

Teraz, keď sme urobili zmenu, skúsme túto zmenu zapísať do histórie nášho projektu. Zmeny musíme presunúť z nášho pracovného adresára do pracovnej oblasti. V skutočnosti sa súbory v systéme súborov nepresúvajú, ale ide o koncepčný spôsob, ako informovať Git, že ste vykonali všetky plánované zmeny pre konkrétny súbor a ste pripravení tieto zmeny vykonať. Užitočné je, že Git poskytuje niekoľko tipov, keď spustíte `git status` pre ďalšiu akciu. Všimnite si správy `(pomocou„ git add … “aktualizujte, čo sa bude potvrdzovať)` v časti `Zmeny nie sú usporiadané pre potvrdenie:`. Git vám hovorí, ako presunúť zmeny do pracovnej oblasti. Spustite `git add Circuit/Circuit.sch`, aby ste vykonali zmeny, a potom` git status`, aby ste zistili, čo sa stalo. Teraz vidíme schematický súbor pod zmenami, ktoré sa majú potvrdiť. Ak tieto zmeny ešte nechcete vykonať, Git užitočne ponúka ďalší tip: `(na„ unstage “použite„ git reset HEAD … “Chceme vykonať tieto zmeny, preto spustíme `git commit -m" Pridaný odpor do schémy "". Tým sa zmeny prejavia s poskytnutou správou. Spustený protokol git zobrazí toto potvrdenie v histórii potvrdenia projektu.

Niekoľko ďalších tipov o záväzkoch.

1. Nezaväzujte sa pri každom uložení. Odhodlajte sa, keď máte pocit, že ste dosiahli bod, v ktorom sa vaše zmeny akosi spevnili. Potvrdzujem, keď dokončím schému, nie po každom pridaní komponentu. Tiež sa nechcete zaväzovať príliš zriedkavo, pretože zapamätať si súvislosti, prečo ste vykonali zmeny, ktoré ste urobili o 3 týždne neskôr, môže byť náročné. Zistiť, kedy sa zaviazať, je trochu umenie, ale s ďalším používaním Gitu sa budete cítiť pohodlnejšie.
2. Uložiť iba zdroj (väčšinou). Patria sem súbory projektu, schémy a rozloženia, ako aj knižnice špecifické pre projekt. To môže zahŕňať aj súbory dokumentácie. Buďte opatrní pri ukladaní odvodených predmetov, pretože sa môžu ľahko synchronizovať s pôvodným zdrojom a to spôsobuje neskôr bolesti hlavy. Súbory kusovníka a gerbera sa dajú obzvlášť ľahko synchronizovať, takže sa im dá lepšie vyhnúť (aj keď v kroku 9 je podrobnejší návod).
3. Správy o potvrdení sú veľmi užitočné, ale dobre štruktúrované správy o potvrdení sú neoceniteľné. Tento vynikajúci článok poskytuje niekoľko pokynov na písanie jasných, stručných a užitočných správ o potvrdení. To môže vyžadovať použitie textového editora príkazového riadka, čo môže byť pre začiatočníkov komplikované („git commit“bez možnosti -m textový editor otvorí). Pre väčšinu ľudí odporúčam editor Nano. StackOverflow má dobré vysvetlenie zmeny editora

Krok 8: Rozšírené: sémantické vytváranie verzií pre elektroniku

Nasledujúce tipy pre dobrodružné duše sú pokročilé nápady, ktoré vyplynuli z mnohých hodín vývoja KiCad. Nie sú obzvlášť užitočné pri menších projektoch, ale môžu vám skutočne ušetriť bolesť, pretože vaše projekty rastú komplexne.

V softvéri existuje koncept sémantického verzovania (semver). Semver definuje spoločnú metodiku pomenovania na identifikáciu vydaní softvéru podľa „čísla verzie“podľa vzoru „Major. Minor. Patch“. Aby ste citovali špecifikácie Semveru, posuniete číslo verzie podľa nasledujúcich kategórií zmien.

1. HLAVNÁ verzia, keď vykonáte nekompatibilné zmeny API,
2. Verzia MINOR, keď pridáte funkcie spätne kompatibilným spôsobom,
3. Verzia PATCH, keď robíte spätne kompatibilné opravy chýb.

V spoločnosti Brainbow používame vlastnú verziu semveru prispôsobenú potrebám hardvérových projektov. Naše špecifikácie sa riadia rovnakým vzorom „Major. Minor. Patch“, aj keď sa naše definície, ktoré zmeny spadajú do ktorej kategórie, evidentne líšia.

1. Verzia MAJOR: používa sa na významné zmeny v základnej funkcii obvodu (napr.: prepnutie procesora z ATmegaa na ESP8266).
2. Verzia MINOR: používa sa na výmenu súčiastok, ktoré by mohli ovplyvniť činnosť obvodu (napr.: výmena blesku SPI s časťou kompatibilnou s kolíkom, ktorá môže mať inú sadu príkazov) alebo pridanie niektorých ďalších drobných funkcií (napríklad: pridaný dodatočný snímač teploty).
3. Verzia PATCH: používa sa na drobné opravy chýb, ktoré nezmenia činnosť obvodu (napríklad: úprava sieťotlače, drobné úpravy rozloženia stopy, jednoduché výmeny komponentov, ako je kondenzátor 0603 až 0805).

V hardvérovom semveri sa číslo verzie aktualizuje iba pri výrobe (rovnako ako v softvéri sa čísla verzií menia iba s vydaniami, nie každý jednotlivec sa zaväzuje k projektu). Výsledkom je, že mnoho projektov má nízky počet verzií. Projekt zatiaľ nebude používať viac ako 4 hlavné verzie.

Okrem výhod konzistentnosti a zrozumiteľnosti, ktoré získate prechodom na dobre definovaný systém pomenovania, získate výhody aj v oblasti kompatibility firmvéru a spokojnosti zákazníkov. Firmvér je možné písať, pričom sa berie do úvahy verzia dosky, na ktorú je zacielená, a môže byť jednoduchšie ladiť, prečo konkrétny program na konkrétnej doske nefunguje („správne, firmvér 2.4.1 nebeží na 1.2. dosky, pretože nemáme … “). Zákazníci tiež ťažili z nášho hardvérového semveru, pretože zákaznícky servis a riešenie problémov je s definovaným štandardom oveľa jednoduchšie.

Krok 9: Rozšírené: Použitie sémantického verzovania hardvéru

Na používanie hardvérového semvera vo vašich vlastných projektoch používame funkciu Git nazývanú značkovanie. Pri prvej výrobe dosky je to verzia 1.0.0 tejto dosky. Uistite sa, že ste vo svojom projekte vykonali všetky zmeny, a potom spustite `git tag -a v1.0.0`. Otvorí sa editor, v ktorom môžete napísať poznámku k tejto značke (veľmi podobnú správe o potvrdení). Uvádzam podrobnosti o výrobe (kto vyrobil DPS, kto zostavil dosku), čo môže byť užitočná informácia neskôr.

Značka vydania je pridaná do histórie potvrdenia a indikuje stav súborov pri výrobe 1.0.0. To môže byť obzvlášť užitočné neskôr, keď sa budete musieť vrátiť k tomuto bodu pri riešení problémov. Bez špecifikovanej značky na uvoľnenie by bolo ťažké zistiť, ktorý záväzok bol v čase výroby najnovší. Značka 1.0.0 (a 1.1, 1.1.1 atď.) Vám umožňuje určiť, že tieto konkrétne zdrojové súbory boli súbory použité v konkrétnom výrobnom cykle.

Poznámka o Gerbersovi. Niektoré fab domy vyžadujú na výrobu dosky súbory Gerber, ktoré môžete vygenerovať pomocou KiCad. Sú to odvodené objekty generované zo zdrojového súboru.kicad_pcb a odvodené súbory, ktoré riadime verziou, bežne nemáme. My v spoločnosti Brainbow neukladáme gerbery v rámci správy verzií S VÝJIMKOU, keď označujeme vydanie. Keď sme pripravení stavať, vygenerujeme súbory gerber, uložíme ich do priečinka Fabrication a potvrdíme a označíme. Potom odstránime gerbery a vykonáme vymazanie. Na prvý pohľad sa to môže zdať trochu mätúce, ale zaisťuje to, že štandardné ukladanie ukladá iba zdrojové súbory a označené vydania tiež ukladajú presné súbory použité na výrobu dosiek. To sa ukázalo ako mimoriadne užitočné pri sledovaní výrobných chýb o niekoľko týždňov neskôr.

Krok 10: Ďalšie kroky

Našťastie vás tento úvod dostatočne naučil začať používať správu verzií vo vašich vlastných projektoch elektroniky. K niektorým pokročilejším témam, ako je napríklad kontrola verzií pre knižnice zdieľané medzi projektmi alebo pobočky funkcií, sme sa nedostali. Kontrola verzií je však ako jesť zeleninu: možno nedostanete to, čo si myslíte, že by ste mali, ale každý kúsok, ktorý urobíte, sa počíta.

Brainbow pracuje na podrobnejšom sprievodcovi niektorými pokročilejšími funkciami nášho pracovného toku. Dúfame, že ho zverejníme niekedy v priebehu niekoľkých nasledujúcich mesiacov. Sledujte nás tu na stránke Instructables a my vám určite dáme vedieť, keď si ju budete môcť prečítať.

Ďakujeme za prečítanie a nemôžeme sa dočkať, až uvidíte, čo vyrobíte!