Avatud lähtekoodiga riistvara versioonikontroll: 10 sammu

2024 Autor: John Day | [email protected]. Viimati modifitseeritud: 2024-01-30 08:49

Brainbow meeskonnal on meie rihma all mitmeid elektroonikaprojekte ja me tahtsime jagada oma protsessi, kuidas kasutada elektroonikakujunduse töövoo haldamiseks versioonikontrolli. Seda töövoogu on kasutatud suurte ja väikeste projektide jaoks, alates lihtsatest 2-kihilistest tahvlitest kuni keerukate 10-kihiliste behemotideni, ning see põhineb avatud lähtekoodiga tööriistadel. Loodetavasti saavad teised meie töövoo enda jaoks kasutusele võtta ja saada oma projektide jaoks versioonikontrolli eeliseid. Kuid milliseid eeliseid võib versioonikontroll pakkuda elektroonikaprojektile?

Samm: miks versioon elektroonikat kontrollib?

Versioonikontroll (teise nimega allika- või redaktsioonikontroll) on tarkvaratehnikas hästi mõistetav ja laialdaselt kasutusele võetud mõiste. Allika juhtimise idee on süstemaatiliselt jälgida programmi või rakenduse lähtekoodis tehtud muudatusi. Kui muudatused rakenduse katkestavad, saate lähtekoodi failid minevikust teadaolevasse tööolekusse tagasi viia. Praktikas võimaldavad allika juhtimissüsteemid jälgida failide kogu ajalugu (tavaliselt arvutiprogrammi, veebisaidi jne lähtekoodi failid) ning visualiseerida ja hallata nende failide muudatusi.

Projekti muudatuste ajaloo jälgimine tundub elektroonikaprojektide jaoks kasulik; kui teete skeemi skeemil vea või kasutate trükkplaadi paigutuses vale komponendi jalajälge, oleks tore jälgida, milliseid vigu tehti ja milliseid parandusi rakendati projekti erinevates muudatustes. Samuti oleks kasulik, kui teised tegijad näeksid seda ajalugu ning mõistaksid erinevate muudatuste konteksti ja ajendeid.

Samm: tööriistad: KiCad ja Git

Selles projektis kasutame kahte peamist tööriista: versioonikontrollisüsteemi (VCS) ja elektroonika disaini automatiseerimise programmi (EDA või ECAD).

Seal on palju versioonikontrollisüsteeme, kuid me kasutame hajutatud VCS Git. Me kasutame seda mitmel põhjusel, kuid peamine on see, et see on avatud lähtekoodiga (kontrollige!), Lihtne kasutada (kontrollige!) Ja avatud lähtekoodiga tarkvara de facto standardne VCS (kontrollige!). Me kasutame Git -i VCS -na, et jälgida muudatusi failides, mida meie ECAD -programm kasutab. See juhend ei nõua Giti tundmist, kuid eeldatakse käsurida kasutades üldist mugavust. Püüan vajadusel linkida abistavatele ressurssidele nii Giti kui ka käsurea kasutamiseks.

Enamik allika juhtimissüsteeme töötab tekstipõhiste failide puhul eriti hästi, seega oleks tekstifaile kasutav ECAD-programm suurepärane. Sisestage KiCad, avatud lähtekoodiga "Cross Platform ja Open Source Electronics Design Automation Suite", mida toetavad CERNi teadlased. KiCad on ka avatud lähtekoodiga (kontrollige!), Hõlpsasti kasutatav (kuigi mõned ei nõustuks minuga selles osas) ja on võimeline elektroonika täiustatud projekteerimiseks.

3. samm: paigaldamine

Nende programmide installimiseks järgige nende erinevate allalaadimissaitide juhiseid allpool.

• KiCad on platvormideülene (ja jahmatav; nende allalaadimislehel on 13 toetatud operatsioonisüsteemi ja pakutakse lähtekoodi allalaadimist, kui ükski neist teile ei sobi). Kasutage kicadiga ühendatud vaikimisi installimist, mitte öist arendusversiooni. Vaadake 4. sammu raamatukogu installimise valikuliste üksikasjade kohta.
• Git on ka platvormideülene. Kui kasutate Windowsi, soovitaksin muljetavaldavat Git for Windowsi projekti, et saada kasulikum ja täisfunktsionaalsem kogemus.

Mõlema saidi installidokumentatsioon on täielikum kui ükski kirjeldus, mida ma siin pakkuda saan. Kui mõlemad programmid on alla laaditud ja installitud, saate kloonida Brainbow projekti malli meie Githubi hoidlast. Käsk git kloon võtab struktuuri `git kloon {src kataloog} {sihtkataloog}`; kasutage meie projekti jaoks "git klooni https://github.com/builtbybrainbow/kicad-starter.git {sihtkataloog}".

Git repo kloonimine on kopeerimise erivorm; projekti kloonimisel saate koopia kõigist repos sisalduvatest failidest ja kogu projekti Git-jälgitud ajaloost. Meie repot kloonides saate projekti kataloogi, mis on juba struktureeritud meie soovitustega Giti kasutamiseks koos KiCadiga. Projekti ülesehituse kohta käsitleme lähemalt 6. etapis või võite minna edasi 7. sammu juurde, kui teil tekib sügelus tööle asuda.

Paar kiiret majapidamistööd - käivitage "git remote rm origin", et eemaldada link Githubi projektile, kust te kloonisite. Käivitage ka `git pühend --amend --author =" John Doe "", asendades autori parameetri teie nime ja e -posti aadressiga. See muudab viimast kohustust (mis on antud juhul ühtlasi esimene) ja muudab autori teie asemel Brainbow'iks.

Samm 4: installimine Märkus: KiCadi teegid

Üks kiire märkus KiCadi raamatukogu struktuuri kohta. KiCad pakub arendajate meeskonna poolt hooldatavate teekide komplekti paljude elektriliste komponentide jaoks. Seal on kolm peamist raamatukogu:

• Skemaatilised sümbolid: sümbolid, mida kasutatakse elektrooniliste komponentide kujutamiseks vooluahela skemaatilisel joonisel.
• PCB jalajäljed: 2D joonised, mis kujutavad tegelikku jalajälge (vaskpadjad, siiditrükk jne), mida kasutatakse vooluahela paigutamisel trükkplaadile.
• 3D -mudelid: elektrooniliste komponentide 3D -mudelid.

Need teegid laaditakse alla koos äsja installitud KiCadi programmikomplektiga. KiCadi saate kasutada ilma suurema vaevata. Kuid "võimsate kasutajate" jaoks on raamatukogude lähtefailid salvestatud Githubi git -hoidlasse, mis võimaldab kasutajatel, kes soovivad olla kursis viimaste muudatustega, kloonida raamatukogu reposid oma masinasse. Raamatukogude jälgimisel gitiga on mitmeid eeliseid - saate valida, millal soovite oma raamatukogusid värskendada, ja värskendused peavad ainult failidesse muudatusi lisama, mitte kogu raamatukogufailide uuesti alla laadima. Siiski vastutate teekide uuendamise eest, mille võib kergesti unustada.

Kui soovite raamatukogusid kloonida, kirjeldab see sait erinevaid Githubi reposid KiCad. Kloonige teegid oma arvutisse (nt: git kloon https:// github.com/KiCad/kicad-symbol.git`), seejärel avage KiCad, valige menüüriba "Eelistused" ja klõpsake "Tee seadistamine … ". See võimaldab teil öelda KiCadile kataloogitee, kust iga raamatukogu otsida. Need keskkonnamuutujad vaikimisi on tee KiCadi installimisega installitud teekidesse; Võtsin need väärtused teadmiseks, et saaksin vajadusel tagasi vaikimisi raamatukogudele minna. Tee KICAD_SYMBOL_DIR peaks viitama teie kloonitud kicad-sümboliteekile, KISYSMOD kloonitud kicad-footprints raamatukogule ja KISYS3DMOD kloonitud kicad-package3d teekile.

Kui soovite raamatukogusid värskendada, saate raamatukogu repos käivitada lihtsa käsu `git pull`, mis käsib Gitil kontrollida erinevusi raamatukogu kohaliku koopia ja Githubi kaugrepo vahel ning värskendab automaatselt muudatuste lisamiseks kohalik koopia.

Samm: Giti põhialused

Git on keeruline ja mitmetahuline programm, mille valdamiseks on pühendatud terveid raamatuid. Siiski on mõned lihtsad mõisted, mis aitavad teil mõista, kuidas me Gitit oma töövoos kasutame.

Git jälgib failide muudatusi, kasutades mitmeid etappe. Tavalised muudatused toimuvad töökataloogis. Kui olete failide seerias tehtud muudatustega rahul, lisate muudetud failid peatamisalale. Kui olete teinud kõik plaanitud muudatused ja lavastanud kõik failid, mida soovite Gitis jälgida, viite need muudatused hoidlasse. Kohustused on sisuliselt hetkepildid repos olevate failide olekust kindlal ajal. Kuna Git jälgib failide muudatusi ja salvestab need muudatused kohustustesse, saate igal ajal projekti tagasi viia olekusse, milles see oli mis tahes eelneva kohustuse korral.

On keerukamaid teemasid, nagu hargnemine ja kaugjuhtimispuldid, kuid me ei pea neid allikakontrolli eeliste saamiseks kasutama. Kõik, mida vajame, on meie KiCadi disainifailide muudatuste jälgimine mitmete kohustustega.

6. samm: KiCadi projekti struktuur

Vaatame lähemalt varem kloonitud projekti KiCad-Starter struktuuri. Lihtsaks korraldamiseks on see jagatud mitmeks alamkataloogiks:

• Vooluring: see kaust sisaldab tegelikke KiCadi projekti faile (skeem, trükkplaat jne). Ma ei nimeta seda kausta ümber, küll aga nimetan kõik sees olevad failid ümber projekti nimega (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: KiCadi projektifail
  • Circuit.sch: KiCadi skemaatiline fail.
  • Circuit.kicad_pcb: KiCad PCB paigutusfail.
• Dokumentatsioon: see kaust on mõeldud projektiga seotud dokumentide säilitamiseks. Meil on plaan seda ruumi tulevikus parandada, kuid praegu sisaldab see lihtsat README -faili. Kasutage seda projekti kohta märkmete salvestamiseks, et saaksite neid tulevikus üle vaadata.
• Valmistamine: sellesse kausta saate salvestada gerber -failid, mida enamik fab -maju kasutab teie trükkplaadi tootmiseks. Kasutame seda ka BOM -failide ja muude tootmiseks ja kokkupanekuks vajalike dokumentide salvestamiseks.
• Raamatukogud: see kaust on mõeldud projektipõhiste raamatukogufailide salvestamiseks (käsitleme seda mõne sammuga lähemalt).

Võimalik, et olete märganud ka mõnda muud faili (eriti kui kataloogi ls -a). Kataloog.git on koht, kus Git teeb maagiat, salvestades hoidla ajaloo. Faili.gitignore kasutatakse Gitile teatamiseks, milliseid faile ta peaks ignoreerima ja mitte allikakontrolli salvestama. Need on enamasti varufailid, mille KiCad genereerib, või mõned erinevad "genereeritud" failid, näiteks võrgunimekirjad, mida ei tohiks allikakontrollis salvestada, kuna need on loodud skemaatilise faili allikast.

See projekti struktuur on alles alguspunkt. Peaksite seda kohandama vastavalt oma vajadustele ja vajadusel lisama jaotisi. Mõne projekti puhul oleme lisanud tarkvara kausta või ümbrise kausta, kuhu salvestasime projekti jaoks 3D -printimiskorpuste mudeleid.

Samm: Giti kasutamine KiCadi projektide jaoks

Oleme lõpuks valmis nägema, kuidas kasutada Gitit oma projektide jälgimiseks. See juhend ei ole mõeldud teile KiCadi kasutamise õpetamiseks (kuigi ma võin seda tulevikus teha, kui selleks on nõudlus), seega vaatame läbi mõned tühised näited, et näidata teile, kuidas töövoog töötab. Peaks olema lihtne mõista, kuidas neid ideid reaalse projekti jaoks kohandada.

Avage kicad-starter kataloog, seejärel käivitage "git log", et kuvada kohustuste ajalugu. Siin peaks olema üks kohustus, repo initsialiseerimine Brainbow poolt. Käivitamine "git status" näitab teile teie repos olevate failide olekut (jälgimata, muudetud, kustutatud, etapiviisiline).

Praegu ei tohiks teie repos muudatusi teha. Teeme muudatuse. Avage KiCadi projekt ja lisage skeemile takisti, seejärel salvestage. Nüüd käivitamine "git status" peaks näitama, et olete skemaatilist faili muutnud, kuid pole neid muudatusi veel sidumiseks teinud. Kui olete huvitatud sellest, mida KiCad täpselt takisti lisamisel tegi, saate käivitada käsu diff muudetud failil „git diff Circuit/Circuit.sch“. See tõstab esile muudatused töökataloogis oleva faili praeguse versiooni ja faili viimase oleku vahel.

Nüüd, kui oleme muudatuse teinud, proovime selle muudatuse oma projekti ajalukku siduda. Peame muudatused teisaldama oma töökataloogist peatuspiirkonda. See ei teisalda faile tegelikult failisüsteemis, vaid on kontseptuaalselt viis Gitile teada anda, et olete teinud konkreetse faili jaoks kõik kavandatud muudatused ja olete valmis neid muudatusi tegema. Abiks on see, et Git annab mõned näpunäited, kui käivitate järgmise toimingu jaoks "git status". Pange tähele sõnumit `(kasutage" git add … ", et värskendada, mida kohustatakse)" jaotises "Muudatused, mida ei ole kohustuslikuks tehtud:". Git räägib teile, kuidas muudatused peatuspiirkonda teisaldada. Muutuste käivitamiseks käivitage käsk "git add Circuit/Circuit.sch", seejärel "git status", et näha, mis juhtus. Nüüd näeme skemaatilist faili muudetavate muudatuste all. Kui te ei soovi neid muudatusi veel teha, pakub Git abivalmilt veel ühte näpunäidet: "(kasutage" git reset HEAD … ", et unstage)". Me tahame neid muudatusi teha, nii et käivitame käsu `git pühendus -m" Lisatud takisti skeemile "`. See paneb muudatused ette antud sõnumiga. Git logi käitamine näitab seda kohustust projekti kohustuste ajaloos.

Veel mõned näpunäited kohustuste kohta.

1. Ärge pühenduge iga päästmisega. Pühenduge, kui tunnete, et olete jõudnud punkti, kus teie muudatused on mõnevõrra tahkunud. Kohustun pärast skeemi lõpetamist, mitte pärast iga komponendi lisamist. Samuti ei taha te liiga harva pühenduda, sest 3 nädala pärast tehtud muudatuste konteksti meeldejätmine võib olla keeruline. Pühendumise väljamõtlemine on natuke kunst, kuid Giti rohkem kasutades muutute end mugavamaks.
2. Ainult poeallikas (enamasti). See hõlmab projekti-, skemaatilisi ja paigutusfaile, samuti projektipõhiseid teeke. See võib sisaldada ka dokumentatsiooni faile. Olge tuletatud objektide salvestamisel ettevaatlik, sest need võivad algse allikaga kergesti sünkroonida ja see tekitab hiljem peavalu. BOM- ja gerber-failid sünkroonitakse eriti lihtsalt, nii et neid on parem vältida (kuigi üksikasjalikumad juhised on esitatud 9. etapis).
3. Kohustussõnumid on väga kasulikud, kuid hästi struktureeritud kohustusteated on hindamatud. See suurepärane artikkel pakub mõningaid juhiseid selgete, lühikeste ja kasulike sidumissõnumite kirjutamiseks. See võib nõuda käsurea tekstiredaktori kasutamist, mis võib algajatele keeruliseks muutuda (tekstitaredikaatori avamine ilma sõnumita -m avab tekstiredaktori). Enamiku inimeste jaoks soovitan Nano redaktorit. StackOverflow -l on hea selgitus redaktori muutmise kohta

8. samm: edasijõudnud: elektroonika semantiline versioonimine

Seiklushimuliste hingede jaoks on järgmised näpunäited täiustatud ideed, mis on kogutud KiCadi mitmetunnisest arendamisest. Need ei ole eriti kasulikud väiksemate projektide puhul, kuid võivad tõesti säästa teie südamevalu, kuna teie projektid muutuvad keerukamaks.

Tarkvaras on olemas mõiste Semantic Versioning (semver). Semver määratleb ühise nimetamismetoodika tarkvaraversioonide tuvastamiseks "versiooninumbri" järgi, järgides mustrit "Major. Minor. Patch". Semveri spetsifikatsiooni tsiteerimiseks edendate versiooni numbrit vastavalt järgmistele muudatuste kategooriatele.

1. MAJOR versioon, kui teete ühildumatuid API muudatusi,
2. MINOR versioon, kui lisate funktsioone tagurpidi ühilduval viisil,
3. PATCH versioon, kui teete tagurpidi ühilduvaid veaparandusi.

Me Brainbow'is kasutame oma versiooni semverist, mis on kohandatud riistvaraprojektide vajadustele. Meie spetsifikatsioonid järgivad sama mustrit "Major. Minor. Patch", kuigi meie määratlused selle kohta, millised muudatused millise kategooria alla kuuluvad, erinevad ilmselgelt.

1. MAJOR versioon: kasutatakse ahela põhifunktsioonide oluliste muudatuste tegemiseks (nt protsessori vahetamine ATmegaalt ESP8266 -le).
2. MINOR versioon: kasutatakse komponentide vahetamiseks, mis võivad mõjutada vooluringi tööd (nt: SPI välklambi vahetus tihvtiga ühilduva osaga, millel võib olla erinev käsukomplekt) või mõne väikese lisafunktsiooni lisamine (nt lisatud täiendav temperatuuriandur).
3. PATCH -versioon: kasutatakse väikeste veaparanduste jaoks, mis ei muuda vooluahela toimimist (nt siiditrüki reguleerimine, väike jäljendite paigutuse reguleerimine, lihtsad komponentide vahetused, näiteks 0603 kondensaator 0805 -ks).

Riistvara semveris uuendatakse versiooninumbrit ainult tootmisel (nagu tarkvara puhul, muutuvad versiooninumbrid ainult koos väljaannetega, mitte igaüks ei pühendu projektile). Seetõttu on paljude projektide versiooninumbrid madalad. Meil pole veel projekti kasutatud rohkem kui 4 peamist versiooni.

Lisaks järjepidevuse ja arusaadavuse eelistele, mida saate täpselt määratletud nimesüsteemile üleminekul, saate kasu ka püsivara ühilduvusest ja klientide rahulolust. Püsivara saab kirjutada, võttes arvesse tahvli versiooni, millele see on suunatud, ja võib olla lihtsam siluda, miks konkreetne programm konkreetsel tahvlil ei tööta ("õige, 2.4.1 püsivara ei tööta versioonis 1.2 lauad, sest meil pole … "). Kliendid on meie riistvaralisest semverist ka kasu saanud, sest klienditeenindus ja tõrkeotsing on määratletud standardiga palju lihtsam.

Samm 9: Täpsem: riistvara semantilise versioonimise kasutamine

Riistvara semveri kasutamiseks oma projektides kasutame Giti funktsiooni, mida nimetatakse märgistamiseks. Kui valmistate tahvlit esmakordselt, on see selle plaadi versioon 1.0.0. Veenduge, et olete oma projektis kõik muudatused sooritanud, seejärel käivitage käsk "git tag -a v1.0.0". See avab redaktori, et saaksite selle märgendi kohta märkusteate kirjutada (väga sarnane kinnituskirjaga). Lisan üksikasjad tootmise kohta (kes valmistas trükkplaadi, kes pani plaadi kokku), millest võib hiljem kasu olla.

Väljalaskesilt lisatakse kohustuste ajalukku ja näitab failide olekut 1.0.0 tootmisel. See võib olla eriti kasulik mitu korda hiljem, kui peate tõrkeotsinguks selle punkti juurde tagasi pöörduma. Ilma täpsustatud vabastamismärgendita võib olla raske välja selgitada, milline kohustus oli tootmise ajal viimane. Märgend 1.0.0 (ja 1.1, 1.1.1 jne) võimaldab teil määrata, et neid konkreetseid lähtefaile kasutati konkreetses tootmistsüklis.

Märkus Gerbersi kohta. Mõni suurepärane maja nõuab teie tahvli valmistamiseks gerber -faile ja saate neid KiCadiga genereerida. Need on tuletatud objektid, mis on loodud lähtekoodi failist.kicad_pcb ja tavaliselt ei kontrolli me tuletatud faile. Meie Brainbow'is ei salvesta gerbereid versioonikontrollis, välja arvatud väljalaske sildistamisel. Kui oleme valmis ehitama, genereerime gerberifailid, salvestame need kausta Fabrication ning seome ja sildistame. Seejärel eemaldame gerberid ja teeme kustutamise. See võib esialgu tunduda pisut segane, kuid see tagab, et tavalised kohustused salvestavad ainult lähtefailid ja märgistatud väljaanded salvestavad ka plaatide valmistamiseks kasutatud täpsed failid. See on osutunud märkimisväärselt kasulikuks tootmisvigade jälgimisel nädalaid hiljem.

Samm: järgmised sammud

Loodetavasti on see sissejuhatus teile piisavalt õpetanud, et hakata oma elektroonikaprojektides kasutama versioonikontrolli. Me ei jõudnud mõne täpsema teema juurde, näiteks projektide või funktsioonide harude vahel jagatud teekide versioonikontroll. Sellegipoolest on versioonikontroll nagu köögiviljade söömine: te ei pruugi saada seda, mida arvate, et peaksite saama, kuid iga osa, mida saate, loeb.

Brainbow töötab välja üksikasjalikuma juhendi meie töövoo mõnede täiustatud funktsioonide kohta. Loodame selle avaldada mõne järgmise kuu jooksul. Jälgige meid siin Instructablesis ja anname teile kindlasti teada, kui saate seda lugeda.

Täname, et lugesite ja me ei jõua ära oodata, mida näete!