Atvērtā koda aparatūras versiju kontrole: 10 soļi

2025 Autors: John Day | [email protected]. Pēdējoreiz modificēts: 2025-01-23 14:59

Brainbow komandai ir vairāki elektronikas projekti, un mēs vēlējāmies dalīties ar versiju kontroles procesu, lai pārvaldītu mūsu elektronikas dizaina darbplūsmu. Šī darbplūsma ir izmantota lieliem un maziem projektiem, sākot no vienkāršiem 2 slāņu dēļiem līdz sarežģītiem 10 slāņu behemotiem, un tā ir balstīta uz atvērtā koda rīkiem. Cerams, ka citi var pieņemt mūsu darbplūsmu paši un iegūt versiju kontroles priekšrocības saviem projektiem. Bet kādas priekšrocības versiju kontrole var piedāvāt elektronikas projektam?

1. darbība. Kāpēc versija kontrolē jūsu elektroniku?

Versiju kontrole (pazīstama arī kā avota kontrole vai pārskatīšanas kontrole) ir labi saprotama un plaši pieņemta programmatūras inženierijas koncepcija. Avota kontroles ideja ir sistemātiski izsekot izmaiņām, kas veiktas programmas vai lietojumprogrammas avota kodā. Ja izmaiņas pārtrauc lietojumprogrammu, varat atgriezt avota koda failus zināmā darba stāvoklī no pagātnes. Praksē avota kontroles sistēmas ļauj izsekot failu kolekcijas vēsturei (parasti datorprogrammas, tīmekļa vietnes uc avota koda faili), kā arī vizualizēt un pārvaldīt šo failu izmaiņas.

Projekta izmaiņu vēstures izsekošana šķiet noderīga elektronikas projektiem; ja kļūdāties shēmas shēmā vai izmantojat nepareizu komponentu nospiedumu PCB izkārtojumā, būtu jauki izsekot, kādas kļūdas tika pieļautas un kādi labojumi tika ieviesti dažādos projekta pārskatījumos. Būtu arī noderīgi citiem veidotājiem redzēt šo vēsturi un izprast dažādu izmaiņu kontekstu un motivāciju.

2. darbība: rīki: KiCad un Git

Šajā projektā mēs izmantojam divus galvenos rīkus: versiju kontroles sistēmu (VCS) un elektronikas dizaina automatizācijas programmu (EDA vai ECAD).

Ir daudz versiju kontroles sistēmu, taču mēs izmantojam izplatīto VCS Git. Mēs to izmantojam vairāku iemeslu dēļ, bet galvenais ir tas, ka tas ir atvērtā koda (pārbaudiet!), Viegli lietojams (pārbaudiet!), Un de-facto standarta VCS atvērtā pirmkoda programmatūrai (pārbaudiet!). Mēs izmantosim Git kā VCS, lai izsekotu izmaiņām failos, kurus izmanto mūsu ECAD programma. Šai pamācībai nav nepieciešama Git pārzināšana, bet tiek pieņemts vispārējs komforts, izmantojot komandrindu. Es mēģināšu pēc vajadzības izveidot saiti uz noderīgiem resursiem gan Git, gan komandrindas lietošanai.

Lielākā daļa avota vadības sistēmu īpaši labi darbojas teksta failiem, tāpēc ECAD programma, kas izmanto teksta failus, būtu lieliska. Ievadiet KiCad, atvērtā pirmkoda "Cross Platform and Open Source Electronics Design Automation Suite", ko atbalsta CERN pētnieki. KiCad ir arī atvērtā pirmkoda (pārbaudiet!), Viegli lietojams (lai gan daži man ar to nepiekristu) un ir ļoti spējīgs uzlabot elektronikas dizaina darbu.

3. darbība: uzstādīšana

Lai instalētu šīs programmas, izpildiet norādījumus no dažādām lejupielādes vietnēm, kas ir norādītas zemāk.

• KiCad ir vairāku platformu (un tik reibinošs; to lejupielādes lapā ir uzskaitītas 13 atbalstītās OS un tiek piedāvāta avota koda lejupielāde, ja neviens no tiem jums nav piemērots). Izmantojiet vienoto kicad noklusējuma instalēšanu, nevis nakts izstrādes versiju. Papildinformāciju par bibliotēkas instalēšanu skatiet 4. darbībā.
• Git ir arī starpplatformu. Ja izmantojat Windows, es ieteiktu iespaidīgo Git for Windows projektu, lai iegūtu noderīgāku, pilnībā aprīkotu pieredzi.

Abās šajās vietnēs pieejamā instalācijas dokumentācija būs pilnīgāka nekā jebkurš apraksts, ko es šeit varu piedāvāt. Kad abas programmas ir lejupielādētas un instalētas, jūs varat klonēt Brainbow projekta veidni no mūsu Github krātuves. Komanda git clone iegūst struktūru `git clone {src directory} {mērķa direktorijs}`; mūsu projektam izmantojiet "git clone https://github.com/builtbybrainbow/kicad-starter.git {target directory}".

Git repo klonēšana ir īpašs kopēšanas veids; klonējot projektu, jūs saņemat visu repo iekļauto failu kopiju, kā arī visu Git izsekoto projekta vēsturi. Klonējot mūsu repo, jūs iegūstat projektu direktoriju, kas jau ir strukturēts ar mūsu ieteikumiem par Git izmantošanu kopā ar KiCad. Sīkāk par projekta struktūru mēs runāsim 6. darbībā, vai arī varat pāriet uz 7. darbību, ja vēlaties sākt darbu.

Daži ātri mājsaimniecības uzdevumi - palaidiet “git remote rm origin”, lai noņemtu saiti uz Github projektu, no kura klonējāt. Tāpat palaidiet `git pühend --amend --author =" John Doe "", aizstājot autora parametru ar savu vārdu un e -pasta adresi. Tas groza pēdējo saistību (kas šajā gadījumā ir arī pirmā saistība) un maina autoru uz jums, nevis Brainbow.

4. darbība: instalēšana Piezīme: KiCad bibliotēkas

Viena ātra piezīme par KiCad bibliotēkas struktūru. KiCad nodrošina bibliotēku kopumu, ko uztur izstrādātāju komanda plašam elektrisko komponentu klāstam. Ir trīs galvenās bibliotēkas:

• Shematiskie simboli: simboli, ko izmanto elektronisko komponentu attēlošanai shēmas shematiskajā zīmējumā.
• PCB pēdas: 2D rasējumi, kas atspoguļo faktisko nospiedumu (vara spilventiņi, sietspiedes teksts utt.), Kas jāizmanto, izvietojot shēmu uz PCB.
• 3D modeļi: elektronisko komponentu 3D modeļi.

Šīs bibliotēkas tiek lejupielādētas kopā ar tikko instalēto KiCad programmu komplektu. Jūs varat izmantot KiCad bez lielām pūlēm. Tomēr "jaudīgiem lietotājiem" bibliotēku avota faili tiek glabāti Gitub git krātuvē, ļaujot lietotājiem, kuri vēlas būt informēti par jaunākajām izmaiņām, klonēt bibliotēkas repo savā datorā. Bibliotēku izsekošanai ar git ir vairākas priekšrocības - jūs varat izvēlēties, kad vēlaties atjaunināt savas bibliotēkas, un atjauninājumos ir jāiekļauj tikai failu izmaiņas, nevis vēlreiz jālejupielādē viss bibliotēkas failu kopums. Tomēr jūs esat atbildīgs par bibliotēku atjaunināšanu, par ko var viegli aizmirst.

Ja vēlaties klonēt bibliotēkas, šajā vietnē ir sīki aprakstīti dažādi Github repo KiCad piedāvājumi. Git klonējiet bibliotēkas savā datorā (piemēram: `git clone https:// github.com/KiCad/kicad-symbol.git`), pēc tam atveriet KiCad, atlasiet vienumu" Preferences "un noklikšķiniet uz" Configure Paths … ". Tas ļauj norādīt KiCad direktorija ceļu, kurā meklēt katru bibliotēku. Šie vides mainīgie pēc noklusējuma ir ceļš uz bibliotēkām, kas instalētas ar KiCad instalāciju; Es ņēmu vērā šīs vērtības, lai vajadzības gadījumā varētu atgriezties pie noklusējuma bibliotēkām. Ceļam KICAD_SYMBOL_DIR jānorāda uz jūsu klonēto kicad-simbolu bibliotēku, KISYSMOD uz klonēto kicad-footprints bibliotēku un KISYS3DMOD uz klonēto kicad-package3d bibliotēku.

Ja vēlaties atjaunināt bibliotēkas, bibliotēkas repo varat izpildīt vienkāršu komandu "git pull", kas Gitam liks pārbaudīt atšķirības starp jūsu vietējo bibliotēkas repo kopiju un Github "attālo" repo un automātiski atjaunināt vietējā kopija, lai iekļautu izmaiņas.

5. solis: Git pamati

Git ir sarežģīta un daudzšķautņaina programma, kuras apgūšanai ir veltītas veselas grāmatas. Tomēr ir daži vienkārši jēdzieni, kas palīdzēs jums saprast, kā mēs darbplūsmā izmantojam Git.

Git izseko failu izmaiņas, izmantojot virkni posmu. Parastās izmaiņas notiek darba direktorijā. Kad esat apmierināts ar izmaiņām, ko esat veicis virknē failu, jūs pievienojat mainītos failus apstāšanās apgabalam. Kad esat veicis visas plānotās izmaiņas un iestudējis visus failus, kurus vēlaties izsekot Git, jūs veicat šīs izmaiņas repozitorijā. Saistības būtībā ir momentuzņēmumi par repo failu stāvokli noteiktā laikā. Tā kā Git izseko failu izmaiņas un saglabā šīs izmaiņas saistībās, jebkurā brīdī varat atgriezt projektu tādā stāvoklī, kādā tas bija jebkurā iepriekšējā apņemšanās reizē.

Ir sarežģītākas tēmas, piemēram, sazarošanās un tālvadības pultis, taču mums tās nav jāizmanto, lai iegūtu avota kontroles priekšrocības. Viss, kas mums nepieciešams, ir izsekot izmaiņām mūsu KiCad dizaina failos, veicot vairākas saistības.

6. darbība: KiCad projekta struktūra

Sīkāk apskatīsim KiCad-Starter projekta struktūru, kuru jūs klonējāt agrāk. Vienkāršai organizēšanai tas ir sadalīts vairākos apakšdirektorijos:

• Ķēde: Šī mape satur faktiskos KiCad projekta failus (shematisks, PCB utt.). Es nepārdēvēju šo mapi, bet pārdēvēju visus iekšējos failus ar projekta nosaukumu (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: KiCad projekta fails
  • Circuit.sch: KiCad shematiskais fails.
  • Circuit.kicad_pcb: KiCad PCB izkārtojuma fails.
• Dokumentācija: Šī mape ir paredzēta projekta dokumentācijas glabāšanai. Mums ir plāni šīs telpas uzlabošanai nākotnē, bet pagaidām tajā ir vienkāršs README fails. Izmantojiet to, lai saglabātu piezīmes par projektu turpmākai pārskatīšanai.
• Izgatavošana: šajā mapē jūs glabāsit gerber failus, kurus lielākā daļa fab māju izmantos shēmas plates ražošanai. Mēs to izmantojam arī, lai uzglabātu BOM failus un citus dokumentus, kas var būt nepieciešami ražošanai un montāžai.
• Bibliotēkas: šī mape ir paredzēta projektam specifisku bibliotēkas failu glabāšanai (mēs to sīkāk apskatīsim, veicot dažas darbības).

Jūs, iespējams, pamanījāt arī dažus citus failus (īpaši, ja direktoriju "ls -a"). Katalogs.git ir tas, kur Git dara savu burvību, saglabājot krātuves vēsturi. Fails.gitignore tiek izmantots, lai norādītu Git, kurus failus tam vajadzētu ignorēt un neglabāt avota vadībā. Tie pārsvarā ir KiCad ģenerēti rezerves faili vai daži dažādi "ģenerēti" faili, piemēram, tīkla saraksti, kurus nevajadzētu uzglabāt avota vadībā, jo tie tiek ģenerēti no avota, kas ir shematiskais fails.

Šī projekta struktūra ir tikai sākumpunkts. Jums tas jāpielāgo savām vajadzībām un pēc vajadzības jāpievieno sadaļas. Dažos projektos esam iekļāvuši programmatūras mapi vai iežogojuma mapi, kurā projektam glabājām 3D drukas korpusu modeļus.

7. darbība: Git izmantošana KiCad projektiem

Mēs beidzot esam gatavi redzēt, kā izmantot Git jūsu projektu izsekošanai. Šī pamācība nav paredzēta, lai iemācītu jums izmantot KiCad (lai gan nākotnē es to varētu darīt, ja būs pieprasījums), tāpēc mēs izskatīsim dažus triviālus piemērus, lai parādītu, kā darbojas darbplūsma. Būtu viegli saprast, kā šīs idejas pielāgot reālam projektam.

Atveriet kicad-starter direktoriju, pēc tam palaidiet "git log", lai parādītu saistību vēsturi. Šeit vajadzētu būt vienai saistībai - Brainbow inicializēja repo. Palaižot "git statusu", tiks parādīts jūsu repo failu statuss (nesekots, modificēts, dzēsts, pakāpenisks).

Pašlaik jūsu repo nevajadzētu mainīt. Veiksim izmaiņas. Atveriet KiCad projektu un pievienojiet shēmai rezistoru, pēc tam saglabājiet. Tagad, palaižot "git statusu", jāparāda, ka esat mainījis shematisko failu, bet vēl neesat veicis šīs izmaiņas saistīšanai. Ja jūs interesē, ko tieši KiCad darīja, pievienojot rezistoru, varat palaist komandu diff modificētajā failā `git diff Circuit/Circuit.sch`. Tas iezīmēs izmaiņas starp pašreizējo darba versijas faila versiju un faila stāvokli pēdējā izpildes laikā.

Tagad, kad esam veikuši izmaiņas, mēģināsim veikt šīs izmaiņas mūsu projektu vēsturē. Mums ir jāpārvieto izmaiņas no mūsu darba direktorija uz pieturvietu. Tas faktiski nepārvieto failus failu sistēmā, bet konceptuāli ir veids, kā informēt Gitu, ka esat veicis visas plānotās izmaiņas konkrētam failam un esat gatavs veikt šīs izmaiņas. Lietderīgi, ka Git sniedz dažus padomus, kad palaižat "git status" nākamajai darbībai. Ievērojiet ziņojumu "(izmantojiet" git add… ", lai atjauninātu, kas tiks izdarīts)" sadaļā "Izmaiņas, kas nav iestrādātas saistībām:". Git stāsta, kā pārvietot izmaiņas uz apstāšanās zonu. Palaidiet "git add Circuit/Circuit.sch", lai ieviestu izmaiņas, pēc tam "git status", lai redzētu, kas noticis. Tagad mēs redzam shematisko failu zem izmaiņām, kas jāveic. Ja jūs vēl nevēlaties veikt šīs izmaiņas, Git izpalīdzīgi piedāvā vēl vienu padomu: `(izmantojiet" git reset HEAD… ", lai atinstalētu). Mēs vēlamies veikt šīs izmaiņas, tāpēc palaižam `git bind -m" Pievienots shematisks rezistors ". Tas apņemas veikt izmaiņas ar sniegto ziņojumu. Darbojoties git žurnālā, šī saistība tiks parādīta projekta saistību vēsturē.

Vēl daži padomi par saistībām.

1. Neuzņemieties saistības ar katru ietaupījumu. Apņemieties, kad jūtat, ka esat sasniedzis punktu, kurā izmaiņas ir nedaudz nostiprinājušās. Es apņemos pēc shēmas pabeigšanas, nevis pēc katra komponenta pievienošanas. Jūs arī nevēlaties apņemties pārāk reti, jo atcerēties kontekstu, kāpēc veicāt izmaiņas, ko veicāt 3 nedēļas vēlāk, var būt grūti. Izdomāt, kad apņemties, ir mazliet māksla, taču, lietojot Git, jūs kļūsit ērtāk.
2. Tikai veikala avots (galvenokārt). Tas ietver projekta, shematiskos un izkārtojuma failus, kā arī projektam raksturīgās bibliotēkas. Tas var ietvert arī dokumentācijas failus. Esiet piesardzīgs, uzglabājot atvasinātos objektus, jo tie var viegli izkļūt no sinhronizācijas ar sākotnējo avotu, un tas vēlāk rada galvassāpes. Īpaši viegli tiek sinhronizēti BOM un Gerber faili, tāpēc labāk tos izvairīties (lai gan detalizētākas norādes ir sniegtas 9. solī).
3. Saistību ziņojumi ir ļoti noderīgi, bet labi strukturēti apņemšanās ziņojumi ir nenovērtējami. Šajā lieliskajā rakstā ir sniegtas dažas vadlīnijas skaidru, kodolīgu, noderīgu saistīto ziņojumu rakstīšanai. Lai to izdarītu, var būt nepieciešams izmantot komandrindas teksta redaktoru, kas iesācējiem var būt sarežģīti (teksta redaktors tiks atvērts, ja netiks izmantota opcija -m ziņojums git Lielākajai daļai cilvēku es iesaku Nano redaktoru. StackOverflow ir labs skaidrojums par redaktora maiņu

8. darbība. Papildu: semantiskā versiju izstrāde elektronikai

Piedzīvojumu pilnām dvēselēm šādi padomi ir uzlabotas idejas, kas iegūtas no daudzu stundu KiCad izstrādes. Tie nav īpaši noderīgi mazākos projektos, taču var patiešām ietaupīt sirdssāpes, jo jūsu projekti kļūst arvien sarežģītāki.

Programmatūrā ir semantiskās versijas (semver) jēdziens. Semvers definē kopēju nosaukšanas metodoloģiju, lai identificētu programmatūras laidienus pēc "versijas numura", ievērojot paraugu "Major. Minor. Patch". Lai citētu semver specifikāciju, jūs virzāt versijas numuru atbilstoši šādām izmaiņu kategorijām.

1. MAJOR versija, kad veicat nesaderīgas API izmaiņas,
2. MINOR versija, ja pievienojat funkcionalitāti atpakaļejošā veidā,
3. PATCH versija, kad veicat atpakaļsaderīgus kļūdu labojumus.

Mēs, Brainbow, izmantojam savu semver versiju, kas pielāgota aparatūras projektu vajadzībām. Mūsu specifikācijas seko tam pašam "Major. Minor. Patch" modelim, lai gan mūsu definīcijas par to, kādas izmaiņas ietilpst šajā kategorijā, acīmredzami atšķiras.

1. MAJOR versija: izmanto būtiskām ķēdes pamatfunkciju izmaiņām (piemēram: procesora pārslēgšana no ATmegaa uz ESP8266).
2. MINOR versija: tiek izmantota komponentu maiņai, kas var ietekmēt ķēdes darbību (piemēram: SPI zibspuldzes maiņa ar tapu saderīgu daļu, kurai var būt atšķirīgs komandu kopums) vai dažas papildu papildu funkcijas pievienošana (piemēram: pievienots papildu temperatūras sensors).
3. PATCH versija: izmanto nelieliem kļūdu labojumiem, kas nemainīs ķēdes darbību (piemēram: sietspiedes pielāgošana, neliela izsekošanas izkārtojuma pielāgošana, vienkārša komponentu maiņa, piemēram, 0603 kondensators uz 0805).

Aparatūras semverī versijas numurs tiek atjaunināts tikai pēc izgatavošanas (tāpat kā programmatūrā, versiju numuri mainās tikai ar izlaidumiem, nevis katrs indivīds uzņemas projektu). Tā rezultātā daudziem projektiem ir zems versiju skaits. Mēs vēl neesam projektā izmantojuši vairāk nekā 4 galvenās versijas.

Papildus konsekvences un saprotamības priekšrocībām, ko iegūstat, pārejot uz precīzi definētu nosaukumu sistēmu, jūs gūstat priekšrocības arī no programmaparatūras saderības un klientu apmierinātības. Programmaparatūru var uzrakstīt, ņemot vērā tā mērķauditorijas versiju, un var būt vieglāk atkļūdot, kāpēc konkrēta programma nedarbojas uz konkrētas plates ("labi, 2.4.1 programmaparatūra nedarbojas uz 1.2. dēļi, jo mums to nav … "). Klienti ir guvuši labumu arī no mūsu aparatūras pusgada, jo klientu apkalpošana un problēmu novēršana ir daudz vienkāršāka, izmantojot noteiktu standartu.

9. darbība. Papildu: aparatūras semantiskās versijas izmantošana

Lai izmantotu aparatūras semveru savos projektos, mēs izmantojam Git funkciju, ko sauc par marķēšanu. Kad pirmo reizi ražojat dēli, tā ir šīs plates 1.0.0 versija. Pārliecinieties, ka esat veicis visas izmaiņas savā projektā, un pēc tam palaidiet "git tag -a v1.0.0". Tiks atvērts redaktors, lai jūs varētu uzrakstīt šim tagam anotācijas ziņojumu (ļoti līdzīgs saistīšanas ziņojumam). Es iekļauju informāciju par ražošanu (kas izgatavoja PCB, kurš samontēja plāksni), kas vēlāk var būt noderīga informācija.

Izlaiduma tags tiek pievienots saistību vēsturei un norāda failu stāvokli 1.0.0 izgatavošanas laikā. Tas var būt īpaši noderīgi vairākas pārskatīšanas vēlāk, kad jums ir jāatgriežas pie šī punkta problēmu novēršanai. Ja nav noteikta izlaišanas birkas, var būt grūti saprast, kura saistība bija pēdējā ražošanas laikā. Izmantojot tagu 1.0.0 (un 1.1, 1.1.1 utt.), Varat norādīt, ka šie konkrētie avota faili tika izmantoti konkrētā ražošanas laikā.

Piezīme par Gerberu. Dažām lieliskām mājām ir nepieciešami gerber faili, lai izveidotu dēli, un jūs varat tos ģenerēt, izmantojot KiCad. Tie ir atvasināti objekti, kas ģenerēti no avota.kicad_pcb faila, un mēs parasti neizmantojam versiju kontroli no atvasinātajiem failiem. Mēs, Brainbow, neuzglabājam gerberus versiju kontrolē, IZŅEMOT, kad mēs atzīmējam izlaidumu. Kad esam gatavi būvniecībai, mēs ģenerējam Gerber failus, saglabājam tos mapē Fabrication un veicam un atzīmējam. Tad mēs noņemam spārnus un veicam dzēšanu. Sākumā tas var šķist nedaudz mulsinoši, taču tas nodrošina, ka parastās saistības saglabā tikai avota failus, un iezīmētajos laidienos tiek saglabāti arī precīzi faili, kas izmantoti dēļu izgatavošanai. Tas ir izrādījies ļoti noderīgi, lai izsekotu ražošanas kļūdas nedēļas vēlāk.

10. darbība. Nākamās darbības

Cerams, ka šis ievads jums ir iemācījis pietiekami daudz, lai sāktu izmantot versiju kontroli savos elektronikas projektos. Mēs nenonācām pie dažām sarežģītākām tēmām, piemēram, versiju kontrole bibliotēkās, kas tiek koplietotas starp projektiem vai funkciju filiālēm. Tomēr versiju kontrole ir tāda pati kā jūsu dārzeņu ēšana: iespējams, ka nesaņemat to, kas, jūsuprāt, vajadzētu, bet katrs jūsu iegūtais sīkums ir svarīgs.

Brainbow strādā pie detalizētāka ceļveža par dažām mūsu darbplūsmas uzlabotajām funkcijām. Mēs ceram to publicēt dažu nākamo mēnešu laikā. Sekojiet mums šeit vietnē Instructables, un mēs noteikti informēsim jūs, kad varēsit to izlasīt.

Paldies, ka lasījāt, un mēs nevaram gaidīt, lai redzētu, ko jūs darāt!