Řízení verzí hardwaru s otevřeným zdrojovým kódem: 10 kroků

2024 Autor: John Day | [email protected]. Naposledy změněno: 2024-01-30 08:22

Tým v Brainbow má za sebou řadu projektů v oblasti elektroniky a my jsme se chtěli podělit o náš proces používání správy verzí ke správě pracovního postupu při návrhu elektroniky. Tento pracovní postup byl použit pro velké i malé projekty, od jednoduchých 2vrstvých desek po komplexní 10vrstvé monstrum a je založen na open-source nástrojích. Naštěstí si ostatní mohou náš pracovní postup osvojit sami a získat výhody správy verzí pro své vlastní projekty. Jaké výhody ale může řízení verzí nabídnout projekt elektroniky?

Krok 1: Proč verze ovládá vaši elektroniku?

Správa verzí (aka kontrola zdroje nebo kontrola revizí) je dobře srozumitelný a široce přijímaný koncept v softwarovém inženýrství. Myšlenkou ovládání zdroje je systematicky sledovat změny provedené ve zdrojovém kódu programu nebo aplikace. Pokud změny přeruší aplikaci, můžete vrátit soubory zdrojového kódu do známého pracovního stavu z minulosti. V praxi vám systémy řízení zdrojů umožňují sledovat historii kolekce souborů (obvykle soubory zdrojového kódu pro počítačový program, web atd.) A vizualizovat a spravovat změny těchto souborů.

Sledování historie změn projektu se zdá být užitečné pro projekty elektroniky; pokud uděláte chybu ve schématu zapojení nebo použijete špatnou stopu součásti v rozvržení desky plošných spojů, bylo by hezké sledovat, jaké chyby byly provedeny a jaké opravy byly implementovány v různých revizích projektu. Bylo by také užitečné, aby ostatní tvůrci viděli tuto historii a porozuměli souvislostem a motivacím různých změn.

Krok 2: Nástroje: KiCad a Git

V tomto projektu používáme dva hlavní nástroje: systém pro správu verzí (VCS) a program pro automatizaci návrhu elektroniky (EDA nebo ECAD).

Existuje MNOHO systémů pro správu verzí, ale my používáme distribuovaný VCS Git. Používáme ho z mnoha důvodů, ale klíčové je, že je open-source (check!), Snadné použití (check!) A de-facto standardní VCS pro open-source software (check!). Git budeme používat jako VCS ke sledování změn v souborech, které náš program ECAD používá. Tento Instructable nevyžaduje znalost Gitu, ale předpokládá se obecné pohodlí pomocí příkazového řádku. Pokusím se podle potřeby propojit s užitečnými zdroji pro Git i příkazový řádek.

Většina systémů pro správu zdrojů funguje zvláště dobře pro textové soubory, takže program ECAD, který používá textové soubory, by byl skvělý. Zadejte KiCad, open-source „Cross Platform and Open Source Electronics Design Automation Suite“podporovaný výzkumníky z CERN. KiCad je také open-source (zkontrolujte!), Snadno použitelný (i když někteří se mnou v tom nesouhlasí) a vysoce schopný pro pokročilé práce v oblasti návrhu elektroniky.

Krok 3: Instalace

Chcete -li tyto programy nainstalovat, postupujte podle pokynů z různých níže uvedených stránek pro stahování.

• KiCad je multiplatformní (a to závratně; na jejich stránce pro stahování je uvedeno 13 podporovaných operačních systémů a nabízí stažení zdrojového kódu, pokud vám žádný z nich nevyhovuje). Použijte výchozí instalaci sjednocenou kicadem, nikoli noční vývojovou verzi. V kroku 4 najdete pokročilé volitelné podrobnosti o instalaci knihovny.
• Git je také multiplatformní. Pokud používáte Windows, doporučil bych působivý projekt Git pro Windows pro užitečnější a plně vybavený zážitek.

Instalační dokumentace dostupná na obou těchto webech bude úplnější než jakýkoli popis, který zde mohu nabídnout. Jakmile jsou oba programy staženy a nainstalovány, můžete klonovat šablonu projektu Brainbow z našeho úložiště Github. Příkaz git clone přebírá strukturu `git clone {adresář src} {cílový adresář}`; pro náš projekt použijte `git clone https://github.com/builtbybrainbow/kicad-starter.git {cílový adresář}`.

Klonování git repo je speciální forma kopírování; při klonování projektu získáte kopii všech souborů zahrnutých v repo a také celou historii projektu sledovanou pomocí Git. Klonováním našeho úložiště získáte adresář projektu již strukturovaný podle našich doporučení pro používání Gitu s KiCadem. Podrobněji se budeme zabývat strukturou projektu v kroku 6, nebo můžete přeskočit na krok 7, pokud vás svědí práce.

Několik úkolů rychlého úklidu - spusťte příkaz „git remote rm origin` a odeberte odkaz na projekt Github, ze kterého jste klonovali. Také spusťte `git commit --amend --author =" John Doe "`, nahraďte parametr autora svým jménem a e -mailem. Tím se mění poslední potvrzení (což je v tomto případě také první potvrzení) a změní se autor na vás, nikoli na Brainbow.

Krok 4: Instalace Poznámka: Knihovny KiCad

Jedna rychlá poznámka o struktuře knihovny KiCad. KiCad poskytuje sadu knihoven spravovaných týmem vývojářů pro širokou škálu elektrických komponent. Existují tři hlavní knihovny:

• Schematické symboly: Symboly používané pro znázornění elektronických součástek ve schématu zapojení.
• Stopy desek plošných spojů: 2D výkresy představující skutečnou stopu (měděné podložky, text na sítotisku atd.), Které budou použity při rozložení obvodu na desce plošných spojů.
• 3D modely: 3D modely elektronických součástek.

Tyto knihovny jsou staženy spolu s programovou sadou KiCad, kterou jste právě nainstalovali. KiCad můžete používat bez dalšího úsilí. Pro „náročné uživatele“jsou však zdrojové soubory pro knihovny uloženy v úložišti git na Githubu, což uživatelům, kteří chtějí zůstat informováni o nejnovějších změnách, umožňuje klonovat repo knihovny na jejich vlastní počítač. Sledování knihoven pomocí git má řadu výhod - můžete si vybrat, kdy chcete své knihovny aktualizovat, a aktualizace musí zahrnovat pouze změny v souborech, nikoli stahovat znovu celou sadu souborů knihoven. Jste však zodpovědní za aktualizaci knihoven, na což lze snadno zapomenout.

Pokud byste chtěli klonovat knihovny, tento web podrobně popisuje různé nabídky Github repos KiCad. Git naklonujte knihovny do svého počítače (např: `git clone https:// github.com/KiCad/kicad-symbols.git`), poté otevřete KiCad, vyberte na panelu nabídek položku„ Předvolby “a klikněte na„ Konfigurovat cesty… . To vám umožní sdělit KiCadu cestu k adresáři, ve které má hledat každou knihovnu. Tyto proměnné prostředí jsou výchozí pro cestu ke knihovnám nainstalovaným pomocí instalace KiCad; Vzal jsem tyto hodnoty na vědomí, abych se mohl v případě potřeby přepnout zpět do výchozích knihoven. Cesta KICAD_SYMBOL_DIR by měla směřovat na vaši klonovanou knihovnu symbolů kicad, KISYSMOD na klonovanou knihovnu kicad-footprints a KISYS3DMOD na klonovanou knihovnu kicad-packages3d.

Chcete -li knihovny aktualizovat, můžete v repo knihovny spustit jednoduchý příkaz `git pull`, který Gitu řekne, aby zkontroloval rozdíly mezi vaší místní kopií repo knihovny a„ vzdáleným “repo Githubu a automaticky aktualizoval vaše místní kopie pro začlenění změn.

Krok 5: Základy Git

Git je komplexní a mnohostranný program, jehož zvládnutí se věnují celé knihy. Existuje však několik jednoduchých konceptů, které vám pomohou pochopit, jak používáme Git v našem pracovním postupu.

Git sleduje změny souborů pomocí řady fází. Normální změny probíhají v pracovním adresáři. Když jste spokojeni se změnami provedenými v řadě souborů, přidáte soubory, které jste změnili, do pracovní oblasti. Jakmile provedete všechny plánované změny a zinscenujete všechny soubory, které chcete sledovat v Gitu, odešlete tyto změny do úložiště. Závazky jsou v podstatě snímky stavu souborů v repo v konkrétní čas. Protože Git sleduje změny v souborech a ukládá tyto změny do revizí, můžete kdykoli vrátit projekt zpět do stavu, ve kterém byl při jakémkoli předchozím potvrzení.

Existují složitější témata, jako jsou větvení a dálkové ovladače, ale nemusíme je používat, abychom získali výhody řízení zdrojů. Vše, co potřebujeme, je sledovat změny v našich konstrukčních souborech KiCad pomocí řady potvrzení.

Krok 6: Struktura projektu KiCad

Podívejme se blíže na strukturu projektu KiCad-Starter, který jste klonovali dříve. Je rozdělena do několika podadresářů pro snadnou organizaci:

• Okruh: Tato složka obsahuje skutečné soubory projektu KiCad (schémata, PCB atd.). Tuto složku nepřejmenovávám, ale přejmenuji všechny soubory uvnitř s názvem projektu (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: soubor projektu KiCad
  • Circuit.sch: schematický soubor KiCad.
  • Circuit.kicad_pcb: soubor rozvržení desky plošných spojů KiCad.
• Dokumentace: Tato složka slouží k ukládání dokumentace týkající se projektu. Máme v plánu do budoucna tento prostor vylepšit, ale prozatím obsahuje jednoduchý soubor README. Použijte jej k uložení poznámek k projektu pro budoucí kontrolu.
• Výroba: V této složce budete ukládat soubory gerberů, které většina fabových domů použije k výrobě vaší desky plošných spojů. Používáme jej také k ukládání souborů kusovníků a dalších dokumentů, které mohou být potřebné pro výrobu a montáž.
• Knihovny: Tato složka slouží k ukládání souborů knihoven specifických pro daný projekt (více si o tom povíme v několika krocích).

Možná jste si také všimli několika dalších souborů (zvláště pokud adresář `ls -a`). Adresář.git je místo, kde Git dělá své kouzlo a ukládá historii úložiště. Soubor.gitignore se používá k informování Gitu o tom, které soubory má ignorovat a ne ukládat do správy zdrojů. Většinou se jedná o záložní soubory, které KiCad generuje, nebo o několik různých „generovaných“souborů, jako jsou seznamy sítí, které by neměly být uloženy v řízení zdroje, protože jsou generovány ze zdroje, který je schematickým souborem.

Tato struktura projektu je jen výchozím bodem. Měli byste jej upravit tak, aby vyhovoval vašim potřebám, a podle potřeby přidat oddíly. V některých projektech jsme zahrnuli složku se softwarem nebo složku s přílohami, kde jsme pro projekt uložili modely pro přílohy pro 3D tisk.

Krok 7: Použití Git pro projekty KiCad

Konečně jsme připraveni zjistit, jak používat Git ke sledování vašich projektů. Tento Instructable není určen k tomu, aby vás naučil používat KiCad (i když ho v budoucnu možná budu dělat, pokud po něm bude poptávka), proto si projdeme několik triviálních příkladů, abychom vám ukázali, jak běží pracovní postup. Mělo by být snadné pochopit, jak tyto nápady přizpůsobit skutečnému projektu.

Otevřete adresář kicad-starter, poté spusťte `git log` a zobrazte historii potvrzení. Zde by mělo dojít k jednomu potvrzení, inicializaci repo Brainbow. Spuštěním `git status` se dozvíte stav souborů ve vašem repo (nesledovaném, upraveném, odstraněném, uspořádaném).

V tuto chvíli byste ve svém repo neměli mít žádné změny. Pojďme udělat změnu. Otevřete projekt KiCad a přidejte do schématu odpor a poté uložte. Nyní spuštěný `git status` by měl ukázat, že jste upravili schematický soubor, ale tyto změny jste zatím nezavedli pro potvrzení. Pokud vás zajímá, co přesně KiCad udělal, když jste přidali odpor, můžete spustit příkaz diff na upraveném souboru `git diff Circuit/Circuit.sch`. Tím se zvýrazní změny mezi aktuální verzí souboru v pracovním adresáři a stavem souboru při posledním potvrzení.

Nyní, když jsme provedli změnu, zkusme tuto změnu potvrdit v historii našeho projektu. Změny musíme přesunout z pracovního adresáře do pracovní oblasti. To ve skutečnosti nepřesouvá soubory v systému souborů, ale je to koncepčně způsob, jak dát Gitu vědět, že jste provedli všechny plánované změny pro konkrétní soubor a jste připraveni tyto změny potvrdit. Užitečné je, že Git poskytuje několik rad, když spustíte `git status` pro další akci. Všimněte si zprávy `(pomocí„ git add … “aktualizujte, co bude potvrzeno)` v části `Změny nebyly připraveny pro potvrzení:`. Git vám říká, jak přesunout změny do pracovní oblasti. Chcete -li provést změny, spusťte příkaz „git add Circuit/Circuit.sch`, poté pomocí příkazu„ git status` zobrazte, co se stalo. Nyní vidíme schematický soubor pod změnami, které mají být potvrzeny. Pokud tyto změny ještě nechcete provést, Git užitečně nabízí další tip: `(pro zrušení fáze použijte" git reset HEAD … ")`. Chceme provést tyto změny, takže spustíme `git commit -m" Přidaný odpor do schématu "`. To potvrdí změny s poskytnutou zprávou. Spuštěním protokolu git se zobrazí toto potvrzení v historii potvrzení projektu.

Několik dalších tipů o spáchání.

1. Nespouštějte se při každém uložení. Zavažte se, když máte pocit, že jste dosáhli bodu, kdy se vaše změny poněkud zpevnily. Potvrzuji po dokončení schématu, ne po každém přidání komponenty. Také se nechcete zavázat příliš zřídka, protože zapamatovat si kontext, proč jste provedli změny, které jste provedli o 3 týdny později, může být obtížné. Zjistit, kdy se zavázat, je trochu umění, ale při používání Gitu budete pohodlnější.
2. Uložit pouze zdroj (většinou). To zahrnuje soubory projektu, schématu a rozvržení a také knihovny specifické pro projekt. To může také zahrnovat soubory dokumentace. Při ukládání odvozených objektů buďte opatrní, protože se mohou snadno synchronizovat s původním zdrojem, což později způsobuje bolesti hlavy. Soubory kusovníku a Gerberu se synchronizují obzvláště snadno, takže je lepší se jim vyhnout (ačkoli podrobnější pokyny jsou popsány v kroku 9).
3. Zprávy o potvrzení jsou velmi užitečné, ale dobře strukturované zprávy o potvrzení jsou neocenitelné. Tento vynikající článek poskytuje několik pokynů pro psaní jasných, stručných a užitečných zpráv o potvrzení. To může vyžadovat použití textového editoru příkazového řádku, což může být pro začátečníky komplikované (`git commit` bez možnosti -m message otevře textový editor). Pro většinu lidí doporučuji editor Nano. StackOverflow má dobré vysvětlení změny editoru

Krok 8: Pokročilé: Sémantické vytváření verzí pro elektroniku

Pro dobrodružné duše jsou následující tipy pokročilými nápady, nasbíranými z mnoha hodin vývoje KiCad. Nejsou zvláště užitečné pro menší projekty, ale mohou vám opravdu ušetřit bolest, protože vaše projekty rostou ve složitosti.

V softwaru existuje koncept sémantického verzování (semver). Semver definuje společnou metodiku pojmenování pro identifikaci verzí softwaru podle „čísla verze“podle vzoru „Major. Minor. Patch“. Chcete -li citovat specifikace semveru, posunete číslo verze podle následujících kategorií změn.

1. HLAVNÍ verze při provádění nekompatibilních změn API,
2. MINOR verze, když přidáte funkce zpětně kompatibilním způsobem,
3. Verze PATCH při provádění zpětně kompatibilních oprav chyb.

My v Brainbow používáme vlastní verzi semveru přizpůsobenou potřebám hardwarových projektů. Naše specifikace se řídí stejným vzorem „Major. Minor. Patch“, i když naše definice změn spadajících do které kategorie se evidentně liší.

1. Verze MAJOR: slouží k významným změnám základní funkce obvodu (např. Přepnutí procesoru z ATmegaa na ESP8266).
2. Verze MINOR: používá se pro výměnu součástek, které by mohly ovlivnit provoz obvodu (např.: SPI flash swap s částí kompatibilní s kolíky, která může mít jinou sadu příkazů) nebo přidání nějaké menší doplňkové funkce (např: přidané další teplotní čidlo).
3. Verze PATCH: používá se pro drobné opravy chyb, které nezmění provoz obvodu (např. Úprava silkscreenu, drobné úpravy rozložení stopy, jednoduché výměny komponent jako kondenzátor 0603 na 0805).

V hardwarovém semveru se číslo verze aktualizuje pouze při výrobě (stejně jako v softwaru se čísla verzí mění pouze s vydáním, ne každý jednotlivec se zavazuje k projektu). V důsledku toho má mnoho projektů nízké počty verzí. Ještě máme projekt, který používá více než 4 hlavní verze.

Kromě výhod konzistence a srozumitelnosti, které získáte přechodem na dobře definovaný systém pojmenování, získáte také výhody v oblasti kompatibility firmwaru a spokojenosti zákazníků. Firmware lze zapisovat s přihlédnutím k verzi desky, na kterou cílí, a může být jednodušší ladit, proč konkrétní program na konkrétní desce nefunguje („správně, firmware 2.4.1 neběží na 1.2 desky, protože nemáme … “). Zákazníci také těžili z našeho hardwarového semveru, protože zákaznický servis a řešení problémů je s definovaným standardem mnohem jednodušší.

Krok 9: Pokročilé: Používání sémantického verzování hardwaru

Chcete -li používat hardwarový semver ve vašich vlastních projektech, používáme funkci Git nazývanou tagování. Při první výrobě desky je to verze 1.0.0 této desky. Ujistěte se, že jste provedli všechny změny ve svém projektu, poté spusťte `git tag -a v1.0.0`. Tím se otevře editor, takže můžete pro tuto značku napsat anotační zprávu (velmi podobnou zprávě o potvrzení). Zahrnuji podrobnosti o výrobě (kdo vyrobil desku plošných spojů, kdo sestavil desku), což mohou být užitečné informace později.

Značka vydání je přidána do historie potvrzení a indikuje stav souborů při výrobě 1.0.0. To může být zvláště užitečné o několik revizí později, když se potřebujete vrátit k tomuto bodu při řešení potíží. Bez specifikované značky vydání by mohlo být obtížné zjistit, které potvrzení bylo v době výroby nejnovější. Značka 1.0.0 (a 1.1, 1.1.1 atd.) Vám umožňuje určit, že tyto konkrétní zdrojové soubory byly použity v konkrétním výrobním cyklu.

Poznámka k Gerbersovi. Některé fab fabry vyžadují k vytvoření vaší desky soubory Gerber a vy je můžete vygenerovat pomocí KiCad. Jedná se o odvozené objekty generované ze zdrojového souboru.kicad_pcb a odvozené soubory běžně neřídíme. My v Brainbow neukládáme gerbery v řízení verzí VÝJIMKY, když označujeme vydání. Když jsme připraveni k sestavení, vygenerujeme soubory gerber, uložíme je do složky Fabrication a potvrdíme a označíme. Poté odstraníme gerbery a provedeme vymazání. Zpočátku se to může zdát trochu matoucí, ale zajišťuje, že normální commit ukládá pouze zdrojové soubory a označená vydání také ukládají přesné soubory použité k výrobě desek. To se ukázalo jako pozoruhodně užitečné při sledování výrobních chyb o několik týdnů později.

Krok 10: Další kroky

Naštěstí vás tento úvod dostatečně naučil začít používat správu verzí ve vašich vlastních projektech v oblasti elektroniky. K některým pokročilejším tématům, jako je správa verzí pro knihovny sdílené mezi projekty nebo větve funkcí, jsme se nedostali. Kontrola verzí je však jako jíst zeleninu: možná nedostanete to, co si myslíte, že byste měli, ale každý kousek se počítá.

Brainbow pracuje na podrobnějším průvodci některými pokročilejšími funkcemi našeho pracovního postupu. Doufáme, že ji zveřejníme někdy v příštích několika měsících. Sledujte nás zde na Instructables a my vám určitě dáme vědět, až si ji budete moci přečíst.

Děkujeme za přečtení a nemůžeme se dočkat, až uvidíte, co vyrobíte!