Nyílt forráskódú hardver verzióvezérlése: 10 lépés

2024 Szerző: John Day | [email protected]. Utoljára módosítva: 2024-01-30 09:42

A Brainbow csapatának számos elektronikai projektje van az övünk alatt, és meg akartuk osztani a folyamatvezérlést a verzióvezérléssel az elektronikai tervezés munkafolyamatának kezeléséhez. Ezt a munkafolyamatot nagy és kicsi projektekhez használták, az egyszerű 2 rétegű tábláktól a komplex 10 rétegű behemótokig, és nyílt forráskódú eszközökön alapul. Remélhetőleg mások maguk is átvehetik a munkafolyamatunkat, és elnyerhetik a verziókezelés előnyeit saját projektjeikhez. De milyen előnyökkel járhat a verziószabályozás egy elektronikai projekt számára?

1. lépés: Miért a verziószabályozás az elektronikát?

A verziókezelés (más néven forrásvezérlés vagy revízióvezérlés) jól ismert és széles körben elfogadott fogalom a szoftverfejlesztésben. A forrásvezérlés mögött meghúzódó ötlet a program vagy alkalmazás forráskódjában végrehajtott változtatások szisztematikus követése. Ha a változtatások megszakítják az alkalmazást, visszaállíthatja a forráskódfájlokat a múltból ismert működő állapotba. A gyakorlatban a forrásvezérlő rendszerek lehetővé teszik, hogy nyomon kövesse a fájlgyűjtemény előzményeit (általában egy számítógépes program, webhely stb. Forráskódfájljait), és megjelenítse és kezelje a fájlok változásait.

A projekt változásainak előzményeinek követése hasznosnak tűnik az elektronikai projektek számára; ha hibát követ el az áramkör vázlatában, vagy rossz alkatrész -lábnyomot használ a NYÁK -elrendezésben, jó lenne nyomon követni, hogy milyen hibákat követtek el, és milyen javításokat hajtottak végre a projekt különböző felülvizsgálatai során. Más alkotók számára is hasznos lenne látni ezt a történelmet, és megérteni a különböző változások kontextusát és motivációit.

2. lépés: Eszközök: KiCad és Git

Ebben a projektben két fő eszközt használunk: a verziókezelő rendszert (VCS) és az elektronikai tervezési automatizálási programot (EDA vagy ECAD).

Sok verziókezelő rendszer létezik, de az elosztott VCS Git -et használjuk. Számos okból használjuk, de a legfontosabb az, hogy nyílt forráskódú (ellenőrizze!), Könnyen használható (ellenőrizze!), És de-facto szabványos VCS a nyílt forráskódú szoftverekhez (ellenőrizze!). A Git -et fogjuk használni VCS -ként az ECAD programunk által használt fájlok változásainak nyomon követésére. Ez az utasítás nem igényel ismereteket a Git -ben, de általános kényelmet feltételez a parancssor használatával. Szükség esetén megpróbálok hasznos forrásokhoz linkelni mind a Git, mind a parancssori használathoz.

A legtöbb forrásvezérlő rendszer különösen jól működik a szövegalapú fájloknál, ezért a szövegfájlokat használó ECAD program nagyszerű lenne. Lépjen be a KiCadba, a nyílt forráskódú "Cross Platform és Open Source Electronics Design Automation Suite" programba, amelyet a CERN kutatói támogatnak. A KiCad szintén nyílt forráskódú (ellenőrizze!), Könnyen használható (bár egyesek nem értenének egyet velem ebben), és rendkívül alkalmas a fejlett elektronikai tervezési munkákra.

3. lépés: Telepítés

A programok telepítéséhez kövesse az alábbi linkeken található letöltési webhelyeik utasításait.

• A KiCad többplatformos (és szédítő is; a letöltési oldaluk 13 támogatott operációs rendszert tartalmaz, és forráskód letöltést kínál, ha ezek közül egyik sem felel meg Önnek). Használja a kicad-unified alapértelmezett telepítést, ne az éjszakai fejlesztést. A könyvtár telepítésével kapcsolatos további választható részletekért lásd a 4. lépést.
• A Git platformok közötti is. Ha Windows-t használ, akkor a lenyűgöző Git for Windows projektet javaslom a hasznosabb, teljes értékű élmény érdekében.

A telepítési dokumentáció, amely mindkét oldalon elérhető, teljesebb lesz, mint bármely leírás, amelyet itt fel tudok ajánlani. Miután mindkét programot letöltötte és telepítette, klónozhatja a Brainbow projekt sablonját a Github tárházunkból. A git clone parancs felveszi a `git clone {src könyvtár} {célkönyvtár}` struktúrát; a projektünkhöz használja a `git clone https://github.com/builtbybrainbow/kicad-starter.git {target directory} 'parancsot.

A git repó klónozása a másolás különleges formája; amikor klónoz egy projektet, megkapja a repó összes fájljának másolatát, valamint a projekt teljes Git-nyomon követett történetét. A repó klónozásával kap egy projektkönyvtárat, amely már strukturált a Git és a KiCad alkalmazásával kapcsolatos ajánlásaink alapján. A 6. lépésben részletesebben foglalkozunk a projekt struktúrájával, vagy átugorhat a 7. lépésre, ha viszket a munkához.

Néhány gyors háztartási feladat - futtassa a "git remote rm origin" parancsot, hogy eltávolítsa a linket a Github projekthez, amelyből klónozott. Ezenkívül futtassa a `git bind --amend --author =" John Doe "" parancsot, és írja le a szerző paramétert az Ön nevére és e -mail címére. Ez módosítja az utolsó elkötelezettséget (amely ebben az esetben egyben az első véglegesítés is), és a szerző helyett Ön helyett a Brainbow -t változtatja meg.

4. lépés: Telepítés Megjegyzés: KiCad Libraries

Egy gyors megjegyzés a KiCad könyvtárszerkezetéről. A KiCad a fejlesztői csapat által fenntartott könyvtárakat biztosít az elektromos alkatrészek széles köréhez. Három fő könyvtár van:

• Vázlatos szimbólumok: Az elektronikus alkatrészek ábrázolásához használt szimbólumok az áramkör sematikus rajzán.
• NYÁK -lábnyomok: 2D -s rajzok, amelyek a tényleges lábnyomot ábrázolják (rézpárnák, selyemnyomatos szöveg stb.), Amelyeket az áramkör NYÁK -on történő elhelyezésekor kell használni.
• 3D modellek: elektronikus alkatrészek 3D modelljei.

Ezeket a könyvtárakat az éppen telepített KiCad programcsomaggal együtt töltik le. A KiCad minden további erőfeszítés nélkül használható. Az "erős felhasználók" számára azonban a könyvtárak forrásfájljai a Gitub git tárházában vannak tárolva, így a felhasználók, akik naprakészek akarnak maradni a legújabb változásokkal, klónozhatják a könyvtári repót saját gépükre. A könyvtárak git segítségével történő nyomon követése számos előnnyel jár - kiválaszthatja, hogy mikor szeretné frissíteni a könyvtárait, és a frissítéseknek csak a fájlok módosításait kell tartalmazniuk, ahelyett, hogy újra letöltenék a teljes könyvtári fájlkészletet. Ön azonban felelős a könyvtárak frissítéséért, amiről könnyen megfeledkezhet.

Ha klónozni szeretné a könyvtárakat, ez az oldal a különböző Github repók KiCad ajánlatait részletezi. Git klónozza a könyvtárakat a számítógépére (pl.: `git clone https:// github.com/KiCad/kicad-symbol.git`), majd nyissa meg a KiCad programot, válassza ki a menüsor" Beállítások "elemét, majd kattintson az" Útvonalak konfigurálása … "gombra. ". Ez lehetővé teszi a KiCad számára, hogy a könyvtár elérési útját keressen minden könyvtárban. Ezek a környezeti változók alapértelmezés szerint a KiCad telepítéssel telepített könyvtárak elérési útvonala; Megjegyeztem ezeket az értékeket, hogy szükség esetén visszatérhessek az alapértelmezett könyvtárakra. A KICAD_SYMBOL_DIR útvonalnak a klónozott kicad-szimbólumok könyvtárára, a KISYSMOD-ra a klónozott kicad-footprints könyvtárra, a KISYS3DMOD-nak pedig a klónozott kicad-package3d könyvtárra kell mutatnia.

Ha frissíteni szeretné a könyvtárakat, akkor futtasson egy egyszerű `git pull` parancsot a könyvtár repójában, amely arra utasítja a Git -et, hogy ellenőrizze a különbségeket a könyvtári repó helyi példánya és a Github" távoli "repó között, és automatikusan frissítse a helyi másolat a változtatások beépítéséhez.

5. lépés: A Git alapjai

A Git összetett és sokoldalú program, amelynek elsajátítására egész könyveket szentelnek. Van azonban néhány egyszerű fogalom, amelyek segítenek megérteni, hogyan használjuk a Git -et a munkafolyamatunkban.

A Git számos lépésben követi a fájlok változásait. A normál változások a munkakönyvtárban történnek. Ha elégedett a fájlsorozaton végrehajtott módosításokkal, akkor hozzáadja a módosított fájlokat az átmeneti területhez. Miután elvégezte az összes tervezett módosítást, és a Gitben követni kívánt összes fájlt rendezte, ezeket a módosításokat véglegesíti a lerakatban. A kötelezettségvállalások lényegében pillanatképek a repó fájljainak állapotáról egy adott időpontban. Mivel a Git nyomon követi a fájlok változásait, és eltárolja ezeket a változtatásokat, bármikor visszaállíthatja a projektet arra az állapotra, amelyben az előző kötelezettségvállaláskor volt.

Vannak bonyolultabb témák is, például az elágazás és a távvezérlők, de ezeket nem kell használnunk, hogy kihasználjuk a forrásvezérlés előnyeit. Nincs más dolgunk, mint követni a KiCad tervezési fájljainkban bekövetkezett változásokat egy sor kötelezettségvállalással.

6. lépés: KiCad projektstruktúra

Nézzük meg közelebbről a korábban klónozott KiCad-Starter projekt felépítését. A könnyű szervezés érdekében számos alkönyvtárra oszlik:

• Áramkör: Ez a mappa tartalmazza a tényleges KiCad projektfájlokat (sematikus, NYÁK stb.). Ezt a mappát nem nevezem át, de a benne található összes fájlt átnevezem a projekt nevével (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: a KiCad projektfájl
  • Circuit.sch: a KiCad sematikus fájlja.
  • Circuit.kicad_pcb: a KiCad PCB elrendezési fájl.
• Dokumentáció: Ez a mappa a projekt dokumentációjának tárolására szolgál. Terveink vannak a jövőben ezen a területen, de jelenleg egy egyszerű README fájlt tartalmaz. Használja a projektre vonatkozó megjegyzések tárolására a későbbi áttekintéshez.
• Gyártás: Ebben a mappában tárolhatja azokat a gerber fájlokat, amelyeket a legtöbb fab ház használ az áramköri lap gyártásához. BOM fájlok és egyéb dokumentumok tárolására is használjuk, amelyekre a gyártáshoz és összeszereléshez szükség lehet.
• Könyvtárak: Ez a mappa a projekt-specifikus könyvtári fájlok tárolására szolgál (erről néhány lépésben részletesebben szólunk).

Lehet, hogy észrevett néhány más fájlt is (különösen, ha a könyvtárat `l --a`). A.git könyvtár az, ahol a Git varázslatos, tárolja a lerakat történetét. A.gitignore fájl arra szolgál, hogy megmondja a Gitnek, hogy mely fájlokat kell figyelmen kívül hagynia, és ne tárolja a forrásvezérlésben. Ezek többnyire a KiCad által létrehozott biztonsági mentési fájlok, vagy néhány különböző "generált" fájl, például a netlisták, amelyeket nem szabad a forrásvezérlésben tárolni, mert a sematikus fájlból származó forrásból származnak.

Ez a projektstruktúra csak egy kiindulópont. Ezt az igényeinek megfelelően kell alakítania, és szükség esetén szakaszokat kell hozzáadnia. Bizonyos projektekhez szoftvermappát vagy mellékelt mappát is beépítettünk, ahol a projekt 3D nyomtatási burkolatainak modelljeit tároltuk.

7. lépés: A Git használata KiCad projektekhez

Végre készen állunk arra, hogy megtudjuk, hogyan használhatjuk a Git -et a projektek nyomon követésére. Ez az utasítás nem célja, hogy megtanítsa a KiCad használatára (bár a jövőben is megteszek egyet, ha igény van rá), ezért néhány triviális példán keresztül bemutatjuk, hogyan működik a munkafolyamat. Könnyűnek kell lennie ahhoz, hogy megértsük, hogyan lehet ezeket az ötleteket egy valódi projekthez igazítani.

Nyissa meg a kicad-starter könyvtárat, majd futtassa a "git log" parancsot a véglegesítési előzmények megjelenítéséhez. Itt egyetlen kötelezettségvállalásnak kell lennie, a repó Brainbow általi inicializálására. A "git állapot" futtatása megmondja a repó fájljainak állapotát (nem követett, módosított, törölt, szakaszos).

Jelenleg nem szabad változtatnia a repóban. Változtassunk. Nyissa meg a KiCad projektet, és adjon hozzá egy ellenállást a rajzhoz, majd mentse. A "git status" futtatása azt mutatja, hogy módosította a sematikus fájlt, de még nem hajtotta végre ezeket a módosításokat a véglegesítéshez. Ha kíváncsi arra, hogy pontosan mit csinált a KiCad, amikor hozzáadta az ellenállást, futtathatja a diff parancsot a módosított "git diff Circuit/Circuit.sch" fájlon. Ez kiemeli a változásokat a fájl aktuális verziója között a munkakönyvtárban és a fájl állapota között az utolsó véglegesítéskor.

Most, hogy változtatást hajtottunk végre, próbáljuk meg ezt a változtatást a projekttörténetünkben végrehajtani. Át kell helyeznünk a módosításokat a munkakönyvtárunkból az átmeneti területre. Ez valójában nem mozgatja a fájlokat a fájlrendszerben, de fogalmilag egy módja annak, hogy tudatja a Git -el, hogy minden tervezett módosítást végrehajtott egy adott fájlon, és készen áll ezek végrehajtására. Hasznos, hogy a Git néhány tippet ad, amikor a "git status" parancsot futtatja a következő művelethez. Figyelje meg az üzenetet "(használja a" git add… "-ot a véglegesítés frissítéséhez)" a "Változások nem szakaszosak a kötelezettségvállaláshoz:" alatt. A Git elmondja, hogyan kell áthelyezni a módosításokat az átmeneti területre. Futtassa a `git add Circuit/Circuit.sch` parancsot a módosítások végrehajtásához, majd a` git status` gombot, hogy megnézze, mi történt. Most látjuk a sematikus fájlt a végrehajtandó változtatások alatt. Ha még nem akarja elvégezni ezeket a módosításokat, a Git segítőkészen kínál egy másik tippet: `(használja a" git reset HEAD… "lehetőséget az instabáláshoz). Ezeket a változtatásokat el akarjuk végezni, ezért futtatjuk a `git committ -m" Added ellenállás a sematikushoz "` parancsot. Ez véglegesíti a módosításokat a megadott üzenettel. A git napló futtatása megmutatja ezt a véglegesítést a projekt véglegesítési előzményeiben.

Még néhány tipp az elkötelezettséggel kapcsolatban.

1. Ne kövess el minden mentést. Kötelezze el magát, ha úgy érzi, hogy elérte azt a pontot, amikor a változások valamelyest megszilárdultak. A vázlat befejezése után vállalom, nem minden összetevő hozzáadása után. Ön sem szeretne túl ritkán elköteleződni, mert nehéz emlékezni arra a kontextusra, hogy miért hajtotta végre a módosításokat, amelyeket 3 héttel később tett. Kitalálni, hogy mikor kell elköteleződni, egy kis művészet, de a Git használatával egyre kényelmesebb lesz.
2. Csak tárolja a forrást (többnyire). Ez magában foglalja a projekt-, sematikus és elrendezési fájlokat, valamint a projekt-specifikus könyvtárakat. Ez dokumentációs fájlokat is tartalmazhat. Legyen óvatos a származtatott objektumok tárolásakor, mert azok könnyen kieshetnek az eredeti forrásból, és ez később fejfájást okoz. A BOM és a gerber fájlok különösen könnyen szinkronizálhatók, ezért jobb elkerülni őket (bár részletesebb útmutatást a 9. lépés tartalmaz).
3. Az elkötelezett üzenetek nagyon hasznosak, de a jól felépített végleges üzenetek felbecsülhetetlen értékűek. Ez a kiváló cikk ad néhány útmutatást a világos, tömör, hasznos elkötelezett üzenetek írásához. Ehhez szükség lehet egy parancssori szövegszerkesztő használatára, ami bonyolult lehet a kezdők számára (a "git bind" az -m üzenet opció nélkül megnyit egy szövegszerkesztőt). A legtöbb embernek a Nano szerkesztőt ajánlom. A StackOverflow jó magyarázatot ad a szerkesztő megváltoztatására

8. lépés: Haladó: szemantikai verziószámítás az elektronikához

A kalandvágyó lelkek számára az alábbi tippek fejlett ötletek, amelyek a KiCad fejlesztésének sok órájából származnak. Ezek nem különösebben hasznosak kisebb projekteknél, de valóban megkímélhetik Önt a szívfájdalomtól, mivel a projektek egyre összetettebbé válnak.

A szoftverekben létezik a szemantikus változat (semver) fogalma. A Semver közös elnevezési módszert határoz meg a szoftverkiadások "verziószám" szerinti azonosítására, a "Major. Minor. Patch" mintát követve. A Semver specifikációinak idézése érdekében a verziószámot a következő változási kategóriák szerint kell előrevinni.

1. MAJOR verzió, ha inkompatibilis API -módosításokat hajt végre,
2. MINOR verzió, ha visszafelé kompatibilis módon ad hozzá funkciókat,
3. PATCH verzió, ha visszafelé kompatibilis hibajavításokat végez.

Mi a Brainbow -nál a semver saját verzióját használjuk, amely megfelel a hardverprojektek igényeinek. Specifikációink ugyanazt a "Major. Minor. Patch" mintát követik, bár a definícióink arra vonatkozóan, hogy milyen változások melyik kategóriába tartoznak, nyilvánvalóan eltérnek.

1. MAJOR verzió: az áramkör alapvető funkcióinak jelentős megváltoztatására szolgál (például: a processzor váltása ATmegaa -ról ESP8266 -ra).
2. MINOR verzió: olyan alkatrészcserékhez használják, amelyek befolyásolhatják az áramkör működését (például: SPI vakucsere csapokkal kompatibilis alkatrésszel, amely eltérő parancskészlettel rendelkezhet), vagy néhány kisebb kiegészítő funkció hozzáadásával (például: kiegészítő hőmérséklet-érzékelő).
3. PATCH verzió: kisebb hibajavításokhoz használják, amelyek nem változtatják meg az áramkör működését (például: selyemszitanyomás, kisebb nyomkövetési elrendezés, egyszerű alkatrészcserék, például 0603 kondenzátor 0805 -re).

A hardver félévben a verziószám csak a gyártáskor frissül (mint a szoftverben, a verziószámok is csak a kiadásokkal változnak, nem minden egyes személy vállalja a projektet). Ennek eredményeként sok projekt alacsony verziószámmal rendelkezik. Egy projektünk még nem használ több mint 4 fő verziót.

A jól definiált elnevezési rendszerre való áttérés által nyújtott következetesség és érthetőség előnyein kívül a firmware-kompatibilitás és az ügyfelek elégedettsége is előnyt jelent. A firmware írható, miközben figyelembe vesszük az alaplap verzióját, amelyet megcéloz, és könnyebb lehet a hibakeresés, hogy miért nem működik egy adott program egy adott táblán ("igaz, a 2.4.1 -es firmware nem fut 1.2 -n táblák, mert nincsenek … "). Az ügyfelek is profitáltak a hardver félévünkből, mert az ügyfélszolgálat és a hibaelhárítás sokkal könnyebb egy meghatározott szabvány mellett.

9. lépés: Haladó: A hardver szemantikai verziójának használata

A hardver szemver saját projektjeiben való használatához használjuk a címkézés nevű Git szolgáltatást. Amikor először gyárt egy táblát, az a kártya 1.0.0 verziója. Győződjön meg arról, hogy elvégezte a projekt összes módosítását, majd futtassa a `git tag -a v1.0.0` fájlt. Ekkor megnyílik egy szerkesztő, így megjegyzést írhat ehhez a címkéhez (nagyon hasonlít a véglegesítési üzenethez). Bemutatom a gyártás részleteit (ki készítette a NYÁK -t, ki szerelte össze a táblát), ami később hasznos információ lehet.

A kiadási címke hozzáadódik a véglegesítési előzményekhez, és jelzi a fájlok állapotát az 1.0.0 gyártáskor. Ez különösen hasznos lehet számos módosítás után, amikor vissza kell térnie erre a pontra a hibaelhárításhoz. Meghatározott kiadási címke nélkül nehéz lehet kitalálni, hogy melyik véglegesítés történt a gyártás idején. Az 1.0.0 (és 1.1, 1.1.1 stb.) Címke lehetővé teszi, hogy megadja, hogy ezeket a specifikus forrásfájlokat használták egy adott gyártási futtatás során.

Egy megjegyzés Gerbersről. Egyes fab házakhoz gerber fájlok szükségesek a tábla elkészítéséhez, és ezeket KiCad segítségével is létrehozhatja. Ezek származtatott objektumok, amelyek a.kicad_pcb forrásfájlból származnak, és rendszerint nem irányítjuk a származtatott fájlokat. Mi a Brainbow -nál nem tároljuk a gerber -eket a verzióvezérlésben, kivéve a kiadás címkézésekor. Amikor készen állunk az építésre, előállítjuk a gerber fájlokat, tároljuk őket a Fabrication mappában, majd véglegesítjük és címkézzük. Ezután eltávolítjuk a gerbert, és véglegesítjük a törlést. Ez elsőre kissé zavarónak tűnhet, de biztosítja, hogy a normál kötelezettségvállalások csak a forrásfájlokat tárolják, és a címkézett kiadások a táblák gyártásához használt fájlokat is tárolják. Ez rendkívül hasznosnak bizonyult a gyártási hibák nyomon követésében hetekkel később.

10. lépés: Következő lépések

Remélhetőleg ez a bevezető eleget tanított ahhoz, hogy elkezdje használni a verziószabályozást saját elektronikai projektjeiben. Nem jutottunk el néhány fejlettebb témához, például a projektek vagy szolgáltatáságak között megosztott könyvtárak verziókezeléséhez. Ennek ellenére a verziószabályozás olyan, mint a zöldségek elfogyasztása: lehet, hogy nem azt kapja, amiről azt gondolja, hogy kellene, de minden egyes rész számít.

A Brainbow részletesebb útmutatót dolgoz ki a munkafolyamatunk néhány fejlettebb funkciójához. Reméljük, hogy a következő hónapokban valamikor közzétesszük. Kövessen minket itt az Instructables oldalon, és biztosan értesítjük, ha el tudja olvasni.

Köszönjük, hogy elolvasta, és alig várjuk, hogy lássuk, mit készített!