Atviro kodo aparatinės įrangos versijų valdymas: 10 žingsnių

2024 Autorius: John Day | [email protected]. Paskutinį kartą keistas: 2024-01-30 10:48

„Brainbow“komanda turi daug elektronikos projektų pagal mūsų diržus, ir mes norėjome pasidalinti savo procesu, kaip naudoti versijų valdymą mūsų elektronikos projektavimo darbui valdyti. Ši darbo eiga buvo naudojama dideliems ir mažiems projektams-nuo paprastų 2 sluoksnių plokščių iki sudėtingų 10 sluoksnių behemotų ir yra pagrįsta atvirojo kodo įrankiais. Tikimės, kad kiti galės patys pritaikyti mūsų darbo eigą ir pasinaudoti versijų valdymo pranašumais savo projektams. Bet kokią naudą versijų valdymas gali pasiūlyti elektronikos projektui?

1 žingsnis: Kodėl versija valdo jūsų elektroniką?

Versijų valdymas (dar žinomas kaip šaltinio valdymas arba peržiūros valdymas) yra gerai suprantama ir plačiai pritaikyta programinės įrangos inžinerijos sąvoka. Šaltinio valdymo idėja yra sistemingai sekti programos ar programos šaltinio kodo pakeitimus. Jei pakeitimai sugadina programą, galite grąžinti šaltinio kodo failus į žinomą darbo būseną iš praeities. Praktiškai šaltinio valdymo sistemos leidžia stebėti failų rinkinio istoriją (dažniausiai kompiuterinės programos, svetainės ir tt šaltinio kodo failus) ir vizualizuoti bei valdyti tų failų pakeitimus.

Projekto pakeitimų istorijos stebėjimas atrodo naudingas elektronikos projektams; jei padarysite klaidą grandinės schemoje arba naudosite neteisingą komponentų pėdsaką PCB išdėstyme, būtų malonu sekti, kokios klaidos buvo padarytos ir kokie pataisymai buvo įgyvendinti įvairiose projekto peržiūrose. Taip pat kitiems kūrėjams būtų naudinga pamatyti tą istoriją ir suprasti įvairių pokyčių kontekstą bei motyvus.

2 žingsnis: įrankiai: „KiCad“ir „Git“

Šiame projekte naudojame du pagrindinius įrankius: versijų valdymo sistemą (VCS) ir elektronikos projektavimo automatizavimo programą (EDA arba ECAD).

Yra daug versijų valdymo sistemų, tačiau mes naudojame paskirstytą „VCS Git“. Mes jį naudojame dėl kelių priežasčių, tačiau svarbiausia yra tai, kad jis yra atvirojo kodo (patikrinkite!), Lengvai naudojamas (patikrinkite!) Ir de-facto standartinis atviro kodo programinės įrangos VCS (patikrinkite!). Mes naudosime „Git“kaip VCS, kad galėtume stebėti failų, kuriuos naudoja mūsų ECAD programa, pakeitimus. Šiam „Instructable“nereikia susipažinti su „Git“, tačiau daromas bendras patogumas naudojant komandinę eilutę. Jei reikia, bandysiu susieti su naudingais „Git“ir komandinės eilutės ištekliais.

Dauguma šaltinio valdymo sistemų ypač gerai veikia teksto failams, todėl puikiai tiktų ECAD programa, kuri naudoja tekstinius failus. Įeikite į „KiCad“, atvirojo kodo „Cross Platform and Open Source Electronics Design Automation Suite“, kurį palaiko CERN tyrėjai. „KiCad“taip pat yra atvirojo kodo (patikrinkite!), Paprasta naudoti (nors kai kurie su manimi dėl to nesutiktų) ir labai geba atlikti pažangius elektronikos projektavimo darbus.

3 žingsnis: diegimas

Norėdami įdiegti šias programas, vadovaukitės instrukcijomis iš įvairių jų atsisiuntimo svetainių, nurodytų žemiau.

• „KiCad“yra kelių platformų (ir svaiginantis; jų atsisiuntimo puslapyje pateikiamos 13 palaikomų OS ir siūlomas šaltinio kodo atsisiuntimas, jei nė vienas iš jų jums netinka). Naudokite numatytąjį „kicad“vieningą diegimą, o ne naktinį kūrimą. Žr. 4 veiksmą, jei reikia išsamesnės informacijos apie bibliotekos diegimą.
• „Git“taip pat yra kelių platformų. Jei naudojate „Windows“, aš rekomenduočiau įspūdingą „Git for Windows“projektą, kad gautumėte daugiau naudingos ir pilnos funkcijos.

Abiejose svetainėse esanti diegimo dokumentacija bus išsamesnė nei bet koks aprašymas, kurį galiu pasiūlyti čia. Atsisiuntę ir įdiegę abi programas, galite klonuoti „Brainbow“projekto šabloną iš mūsų „Github“saugyklos. Komanda „git clone“turi struktūrą „git clone {src directory} {target directory}“; mūsų projektui naudokite „git clone https://github.com/builtbybrainbow/kicad-starter.git {target directory}“.

Git repo klonavimas yra ypatinga kopijavimo forma; klonuojant projektą, jūs gaunate visų į repą įtrauktų failų kopiją, taip pat visą „Git“sekamą projekto istoriją. Klonuodami mūsų repo, gausite projektų katalogą, jau sudarytą pagal mūsų rekomendacijas, kaip naudoti „Git“su „KiCad“. Daugiau apie projekto struktūrą aptarsime 6 veiksme, arba galite pereiti prie 7 veiksmo, jei norite pradėti dirbti.

Keletas greitų namų tvarkymo užduočių - paleiskite „git remote rm origin“, kad pašalintumėte nuorodą į „Github“projektą, iš kurio klonavote. Taip pat paleiskite `git įsipareigoti -amend --author =" John Doe "", pakeisdami autoriaus parametrą savo vardu ir el. Pašto adresu. Tai pakeičia paskutinį įsipareigojimą (kuris šiuo atveju taip pat yra pirmasis įsipareigojimas) ir pakeičia autorių į jus, o ne „Brainbow“.

4 veiksmas: diegimas Pastaba: „KiCad“bibliotekos

Viena greita pastaba apie „KiCad“bibliotekos struktūrą. „KiCad“teikia bibliotekų rinkinį, kurį tvarko kūrėjų komanda įvairiems elektros komponentams. Yra trys pagrindinės bibliotekos:

• Scheminiai simboliai: Simboliai, naudojami elektroniniams komponentams pavaizduoti grandinės schemoje.
• PCB pėdsakai: 2D brėžiniai, vaizduojantys tikrąjį pėdsaką (vario pagalvėlės, šilkografinis tekstas ir kt.), Kurie turi būti naudojami išdėstant grandinę ant PCB.
• 3D modeliai: 3D elektroninių komponentų modeliai.

Šios bibliotekos atsisiunčiamos kartu su ką tik įdiegtu „KiCad“programų paketu. „KiCad“galite naudoti be jokių papildomų pastangų. Tačiau „galingiems vartotojams“bibliotekų šaltinio failai saugomi „Gitub“„git“saugykloje, todėl vartotojai, norintys nuolat sekti naujausius pakeitimus, gali klonuoti bibliotekos repą į savo kompiuterį. Bibliotekų sekimas naudojant „git“turi daug privalumų - galite pasirinkti, kada norite atnaujinti savo bibliotekas, o atnaujinimuose reikia tik įtraukti failų pakeitimus, o ne vėl atsisiųsti visą bibliotekos failų rinkinį. Tačiau jūs esate atsakingi už bibliotekų atnaujinimą, kurį galima lengvai pamiršti.

Jei norite klonuoti bibliotekas, šioje svetainėje pateikiama išsami informacija apie įvairius „Github“repos „KiCad“pasiūlymus. Git klonuoti bibliotekas į savo kompiuterį (pvz.: `git clone https:// github.com/KiCad/kicad-symbol.git`), tada atidarykite„ KiCad “, pasirinkite meniu juostos elementą„ Parinktys “ir spustelėkite„ Konfigūruoti kelius… . Tai leidžia nurodyti „KiCad“katalogo keliui ieškoti kiekvienos bibliotekos. Šie aplinkos kintamieji pagal numatytuosius nustatymus nurodo kelią į bibliotekas, įdiegtas su „KiCad“diegimu; Aš atkreipiau dėmesį į šias vertes, kad prireikus galėčiau grįžti prie numatytųjų bibliotekų. KICAD_SYMBOL_DIR kelias turėtų nukreipti į jūsų klonuotų kicad simbolių biblioteką, KISYSMOD į klonuotų kicad-footprints biblioteką ir KISYS3DMOD į klonuotą kicad-package3d biblioteką.

Kai norite atnaujinti bibliotekas, bibliotekos repo galite paleisti paprastą komandą „git pull“, kuri nurodys „Git“patikrinti, ar nėra skirtumų tarp vietinės bibliotekos repos ir „Github“nuotolinio repo, ir automatiškai atnaujinti vietinė kopija, kad būtų įtraukti pakeitimai.

5 žingsnis: „Git“pagrindai

„Git“yra sudėtinga ir daugialypė programa, kuriai įvaldyti skirta visa knyga. Tačiau yra keletas paprastų sąvokų, kurios padės suprasti, kaip mes naudojame „Git“savo darbo eigoje.

„Git“stebi failų pakeitimus naudodami keletą etapų. Įprasti pakeitimai vyksta darbo kataloge. Kai esate patenkinti failų serijos pakeitimais, pridedate pakeistus failus į sustojimo sritį. Atlikę visus planuojamus pakeitimus ir sukomponavę visus failus, kuriuos norėtumėte stebėti „Git“, atlikite šiuos pakeitimus saugykloje. Įsipareigojimai iš esmės yra repo failų būklės momentinės nuotraukos tam tikru laiku. Kadangi „Git“stebi failų pakeitimus ir išsaugo šiuos pakeitimus įsipareigojimuose, bet kuriuo metu galite grąžinti projektą į būseną, kurioje jis buvo bet kuriuo ankstesniu įsipareigojimu.

Yra sudėtingesnių temų, tokių kaip šakos ir nuotolinio valdymo pultai, tačiau mums nereikia jų naudoti, kad gautume šaltinio valdymo pranašumus. Viskas, ko mums reikia, yra sekti „KiCad“dizaino failų pakeitimus atlikus daugybę įsipareigojimų.

6 žingsnis: „KiCad“projekto struktūra

Pažvelkime atidžiau į anksčiau klonuoto projekto „KiCad-Starter“struktūrą. Kad būtų lengviau organizuoti, jis suskirstytas į keletą pakatalogių:

• Grandinė: Šiame aplanke yra tikri „KiCad“projekto failai (schema, PCB ir kt.). Nepervadinu šio aplanko, bet pervadinu visus viduje esančius failus projekto pavadinimu (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: KiCad projekto failas
  • Circuit.sch: „KiCad“scheminis failas.
  • Circuit.kicad_pcb: „KiCad“PCB išdėstymo failas.
• Dokumentacija: Šis aplankas skirtas projekto dokumentacijai saugoti. Ateityje planuojame tobulinti šią erdvę, tačiau kol kas joje yra paprastas README failas. Naudokite jį, kad išsaugotumėte užrašus apie projektą, kad galėtumėte ateityje juos peržiūrėti.
• Gamyba: Šiame aplanke saugosite gerber failus, kuriuos dauguma fab namų naudos jūsų plokštės gamybai. Mes taip pat naudojame jį saugoti BOM failus ir kitus dokumentus, kurių gali prireikti gamybai ir surinkimui.
• Bibliotekos: Šis aplankas skirtas konkrečių projektų bibliotekos failams saugoti (daugiau tai aptarsime atlikdami kelis veiksmus).

Galbūt pastebėjote ir keletą kitų failų (ypač jei katalogą „ls -a“).. Git kataloge Git daro stebuklą ir saugo saugyklos istoriją. Failas.gitignore naudojamas „Git“nurodyti, kuriuos failus jis turėtų ignoruoti, o ne saugoti šaltinio valdyme. Dažniausiai tai yra atsarginės kopijos, kurias sukuria „KiCad“, arba keli skirtingi „sugeneruoti“failai, pvz., Tinklų sąrašai, kurie neturėtų būti saugomi šaltinio valdyme, nes jie yra generuojami iš šaltinio, kuris yra scheminis failas.

Ši projekto struktūra yra tik pradinis taškas. Turėtumėte jį pritaikyti pagal savo poreikius ir prireikus pridėti skyrius. Kai kuriuose projektuose mes įtraukėme programinės įrangos aplanką arba aplanko aplanką, kuriame saugojome projekto 3D spausdinimo korpusų modelius.

7 veiksmas: „Git“naudojimas „KiCad“projektams

Pagaliau esame pasiruošę pamatyti, kaip naudoti „Git“jūsų projektams stebėti. Ši instrukcija nėra skirta išmokyti jus naudotis „KiCad“(nors ateityje galiu tai padaryti, jei yra poreikis), todėl pateiksime keletą nereikšmingų pavyzdžių, kurie parodys, kaip veikia darbo eiga. Turėtų būti nesunku suprasti, kaip šias idėjas pritaikyti realiam projektui.

Atidarykite „kicad-starter“katalogą, tada paleiskite „git log“, kad būtų rodoma įvykdymo istorija. Čia turėtų būti vienas įsipareigojimas - „Brainbow“inicijavo atpirkimą. Vykdydami „git statusą“, pamatysite savo repo failų būseną (nesekama, modifikuota, ištrinta, pakopinė).

Šiuo metu neturėtumėte jokių pakeitimų savo repo. Padarykime pakeitimą. Atidarykite „KiCad“projektą ir pridėkite rezistorių prie schemos, tada išsaugokite. Dabar paleidus „git statusą“turėtų pasirodyti, kad pakeitėte scheminį failą, bet dar neįvykdėte šių pakeitimų. Jei jums įdomu, ką tiksliai padarė „KiCad“, kai pridėjote rezistorių, galite paleisti „diff“komandą pakeistame faile „git diff Circuit/Circuit.sch“. Tai paryškins pokyčius tarp dabartinės failo versijos darbo kataloge ir failo būsenos paskutinio įvykdymo metu.

Dabar, kai padarėme pakeitimą, pabandykime tą pakeitimą įtraukti į savo projekto istoriją. Turime perkelti pakeitimus iš savo darbo katalogo į sustojimo zoną. Tai iš tikrųjų neperkelia failų į failų sistemą, bet konceptualiai yra būdas pranešti „Git“, kad atlikote visus planuojamus konkretaus failo pakeitimus ir esate pasirengę atlikti šiuos pakeitimus. Naudinga, kad „Git“pateikia keletą patarimų, kai vykdote kitą veiksmą „git status“. Atkreipkite dėmesį į pranešimą „(naudokite„ git add… “, kad atnaujintumėte, kas bus įvykdyta)“skiltyje „Pakeitimai nepastovūs įsipareigojimui:“. „Git“jums pasakys, kaip perkelti pakeitimus į sustojimo zoną. Norėdami atlikti pakeitimus, paleiskite „git add Circuit/Circuit.sch“, tada „git status“, kad pamatytumėte, kas atsitiko. Dabar matome scheminį failą pagal pakeitimus, kuriuos reikia atlikti. Jei dar nenorite atlikti šių pakeitimų, „Git“paslaugiai siūlo kitą patarimą: „(naudokite„ git reset HEAD… “, kad pašalintumėte). Mes norime atlikti šiuos pakeitimus, todėl paleidžiame `git įsipareigoti -m" Pridėtas rezistorius prie schemos "". Tai patvirtina pakeitimus pateiktu pranešimu. Vykdydamas „git“žurnalą, šis įsipareigojimas bus rodomas projekto įsipareigojimų istorijoje.

Dar keletas patarimų apie įsipareigojimus.

1. Neprisiimkite įsipareigojimų kiekvieną kartą taupydami. Įsipareigokite, kai manote, kad pasiekėte tašką, kuriame jūsų pokyčiai šiek tiek sustiprėjo. Aš įsipareigoju, kai baigiu schemą, o ne po kiekvieno komponento pridėjimo. Taip pat nenorite įsipareigoti per retai, nes prisiminti kontekstą, kodėl atlikote pakeitimus, kuriuos padarėte po 3 savaičių, gali būti sunku. Išsiaiškinti, kada įsipareigoti, yra šiek tiek menas, tačiau, kai naudosite „Git“, tapsite patogesni.
2. Tik parduotuvės šaltinis (dažniausiai). Tai apima projekto, schemos ir maketo failus, taip pat konkretaus projekto bibliotekas. Tai taip pat gali apimti dokumentacijos failus. Saugodami išvestinius objektus, būkite atsargūs, nes jie gali nesuderinti su pirminiu šaltiniu, o tai vėliau sukelia galvos skausmą. BOM ir gerber failai yra ypač lengvai dezinchronizuojami, todėl geriau jų išvengti (nors išsamesnės gairės aprašytos 9 veiksme).
3. Įsipareigojimo pranešimai yra labai naudingi, tačiau gerai suplanuoti įsipareigojimo pranešimai yra neįkainojami. Šiame puikiame straipsnyje pateikiamos gairės, kaip rašyti aiškius, glaustus, naudingus įsipareigojimo pranešimus. Norėdami tai padaryti, gali prireikti naudoti komandinės eilutės teksto redaktorių, o tai gali būti sudėtinga pradedantiesiems („git įsipareigoti“be parinkties -m message atvers teksto redaktorių). Daugumai žmonių rekomenduoju „Nano“redaktorių. „StackOverflow“turi gerą paaiškinimą, kaip pakeisti redaktorių

8 žingsnis: Išplėstinė: semantinis elektronikos versijų kūrimas

Nuotykių ieškančioms sieloms šie patarimai yra pažangios idėjos, surinktos iš daugelio „KiCad“kūrimo valandų. Jie nėra ypač naudingi mažesniems projektams, tačiau jie tikrai gali sutaupyti jūsų širdies skausmo, nes jūsų projektai tampa vis sudėtingesni.

Programinėje įrangoje yra semantinio versijos (semver) koncepcija. Semveris apibrėžia bendrą pavadinimo metodiką, leidžiančią identifikuoti programinės įrangos leidimus pagal „versijos numerį“pagal „Major. Minor. Patch“modelį. Norėdami cituoti „Semver“specifikacijas, iš anksto pakeisite versijos numerį pagal šias pakeitimų kategorijas.

1. MAJOR versija, kai atliekate nesuderinamus API pakeitimus,
2. MINOR versija, kai funkcionalumą pridedate atgal suderinamu būdu,
3. PATCH versija, kai atliekate atgal suderinamus klaidų pataisymus.

Mes, „Brainbow“, naudojame savo versiją „semver“, pritaikytą techninės įrangos projektų poreikiams. Mūsų specifikacijos atitinka tą patį „Major. Minor. Patch“modelį, nors mūsų apibrėžimai, kokie pokyčiai patenka į kurią kategoriją, akivaizdžiai skiriasi.

1. MAJOR versija: naudojama esminiams grandinės funkcijų pakeitimams (pvz., Procesoriaus perjungimas iš ATmegaa į ESP8266).
2. MINOR versija: naudojama komponentų apsikeitimui, kuris gali turėti įtakos grandinės veikimui (pvz., SPI blykstės keitimas su kaiščiu suderinama dalimi, kuri gali turėti skirtingą komandų rinkinį) arba papildoma papildoma funkcija (pvz., Pridėtas papildomas temperatūros jutiklis).
3. PATCH versija: naudojama smulkiems klaidų pataisymams, kurie nepakeis grandinės veikimo (pvz., Šilkografijos koregavimas, nedidelis pėdsakų išdėstymo koregavimas, paprastas komponentų keitimas, pvz., 0603 kondensatorius į 0805).

Aparatinės įrangos pusiau versijos numeris atnaujinamas tik gaminant (kaip ir programinės įrangos atveju, versijų numeriai keičiasi tik su leidimais, o ne kiekvienas asmuo įsipareigoja projektui). Todėl daugelio projektų versijų numeriai yra maži. Dar neturime projekto, kuriame būtų naudojamos daugiau nei 4 pagrindinės versijos.

Be nuoseklumo ir suprantamumo naudos, kurią gaunate perėję prie gerai apibrėžtos pavadinimo sistemos, taip pat gaunate naudos iš programinės įrangos suderinamumo ir klientų pasitenkinimo. Firmware gali būti parašyta atsižvelgiant į plokštės versiją, į kurią ji nukreipta, ir lengviau išsiaiškinti, kodėl tam tikra programa neveikia tam tikroje plokštėje ("tiesa, 2.4.1 programinė įranga neveikia naudojant 1.2 lentos, nes mes neturime … "). Klientai taip pat gavo naudos iš mūsų techninės įrangos, nes klientų aptarnavimas ir trikčių šalinimas yra daug lengvesni, kai yra nustatytas standartas.

9 veiksmas: Išplėstinė: techninės įrangos semantinio versijos naudojimas

Norėdami naudoti aparatūros semverį savo projektuose, naudojame „Git“funkciją, vadinamą žymėjimu. Kai pirmą kartą gaminate plokštę, tai yra tos plokštės 1.0.0 versija. Įsitikinkite, kad atlikote visus projekto pakeitimus, tada paleiskite „git tag -a v1.0.0“. Bus atidarytas redaktorius, kad galėtumėte parašyti šios žymos komentarų pranešimą (labai panašų į įsipareigojimo pranešimą). Įtraukiu išsamią informaciją apie gamybą (kas pagamino PCB, kas surinko plokštę), kuri vėliau gali būti naudinga informacija.

Išleidimo žyma pridedama prie įsipareigojimų istorijos ir nurodo failų būseną 1.0.0 gamybos metu. Tai gali būti ypač naudinga po kelių pakeitimų vėliau, kai reikia grįžti prie šio punkto, kad būtų pašalintas trikčių šalinimas. Be nurodytos išleidimo žymos gali būti sunku išsiaiškinti, kuris įsipareigojimas buvo paskutinis gamybos metu. Naudodami žymą 1.0.0 (ir 1.1, 1.1.1 ir tt) galite nurodyti, kad šie konkretūs šaltinio failai buvo naudojami tam tikrame gamybos etape.

Pastaba apie Gerberą. Kai kuriems nuostabiems namams reikia gerber failų, kad galėtumėte sukurti lentą, ir jūs galite juos sukurti naudodami „KiCad“. Tai yra išvestiniai objektai, sugeneruoti iš šaltinio.kicad_pcb failo, ir mes paprastai nekontroliuojame išvestinių failų versijų. Mes, „Brainbow“, nelaikome gerberių versijų valdyme, IŠSKYRUS, kai pažymime leidimą. Kai būsime pasirengę kurti, sugeneruosime gerber failus, išsaugosime juos aplanke Fabrication ir padarysime bei pažymėsime. Tada pašaliname gerberius ir įsipareigojame juos ištrinti. Iš pradžių tai gali atrodyti šiek tiek painu, tačiau tai užtikrina, kad įprasti įsipareigojimai saugo tik šaltinio failus, o pažymėtos versijos taip pat saugo tikslius failus, naudojamus plokštėms gaminti. Tai pasirodė nepaprastai naudinga sekant gamybos klaidas po kelių savaičių.

10 veiksmas: kiti veiksmai

Tikimės, kad ši įžanga išmokė jus pakankamai pradėti naudoti versijos valdymą savo elektronikos projektuose. Mes nepasiekėme kai kurių sudėtingesnių temų, pvz., Bibliotekų, bendrinamų tarp projektų ar funkcijų šakų, versijų valdymo. Vis dėlto versijų kontrolė yra panaši į jūsų daržovių valgymą: galbūt negausite to, ką, jūsų manymu, turėtumėte gauti, tačiau kiekviena gauta suma yra svarbi.

„Brainbow“rengia išsamesnį kai kurių pažangesnių mūsų darbo eigos funkcijų vadovą. Tikimės jį paskelbti per kelis ateinančius mėnesius. Sekite mus čia „Instructables“ir mes būtinai pranešime, kai galėsite ją perskaityti.

Dėkojame, kad skaitote, ir nekantraujame pamatyti, ką padarėte!