Versjonskontroll for åpen kildekode -maskinvare: 10 trinn

2025 Forfatter: John Day | [email protected]. Sist endret: 2025-01-13 06:58

Teamet på Brainbow har en rekke elektronikkprosjekter under beltet, og vi ønsket å dele vår prosess for bruk av versjonskontroll for å håndtere arbeidsflyten for elektronikkdesign. Denne arbeidsflyten har blitt brukt for store og små prosjekter, fra enkle 2-lags brett til komplekse 10-lags behemoths, og er basert på åpen kildekode-verktøy. Forhåpentligvis kan andre adoptere arbeidsflyten vår selv og få fordelene med versjonskontroll for sine egne prosjekter. Men hvilke fordeler kan versjonskontroll tilby et elektronikkprosjekt?

Trinn 1: Hvorfor versjonskontroll elektronikken din?

Versjonskontroll (også kjent som kildekontroll eller revisjonskontroll) er et godt forstått og vidt vedtatt konsept innen programvareteknikk. Ideen bak kildekontroll sporer systematisk endringer som er gjort i kildekoden til et program eller en applikasjon. Hvis endringer bryter programmet, kan du tilbakestille kildekodefilene til en kjent arbeidstilstand fra tidligere. I praksis lar kildekontrollsystemer deg spore historien til en samling filer (vanligvis kildekodefilene for et dataprogram, nettsted, osv.), Og visualisere og administrere endringer i disse filene.

Å spore historien til endringer i et prosjekt virker nyttig for elektronikkprosjekter; hvis du gjør en feil i kretsskjemaet, eller bruker feil komponentfotavtrykk i PCB -oppsettet, ville det være fint å holde oversikt over hvilke feil som ble gjort og hvilke reparasjoner som ble implementert i forskjellige revisjoner av et prosjekt. Det ville også være nyttig for andre beslutningstakere å se denne historien, og forstå konteksten og motivasjonene til ulike endringer.

Trinn 2: Verktøyene: KiCad og Git

Vi bruker to hovedverktøy i dette prosjektet: versjonskontrollsystemet (VCS) og elektronikkdesignautomatiseringsprogrammet (EDA eller ECAD).

Det er MANGE versjonskontrollsystemer der ute, men vi bruker den distribuerte VCS Git. Vi bruker den av en rekke årsaker, men nøkkelen er at den er åpen kildekode (sjekk!), Enkel å bruke (sjekk!) Og de-facto standard VCS for åpen kildekode-programvare (sjekk!). Vi bruker Git som VCS for å spore endringene i filene som vårt ECAD -program bruker. Denne instruksen krever ikke kjennskap til Git, men generell komfort ved bruk av kommandolinjen er forutsatt. Jeg vil prøve å koble til nyttige ressurser for både Git- og kommandolinjebruk etter behov.

De fleste kildekontrollsystemer fungerer spesielt godt for tekstbaserte filer, så et ECAD-program som bruker tekstfiler ville være flott. Skriv inn KiCad, åpen kildekode "Cross Platform and Open Source Electronics Design Automation Suite" støttet av forskere ved CERN. KiCad er også åpen kildekode (sjekk!), Lett å bruke (selv om noen er uenige med meg om det), og er meget i stand til avansert elektronisk designarbeid.

Trinn 3: Installasjon

For å installere disse programmene, følg instruksjonene fra de forskjellige nedlastningssidene som er lenket til nedenfor.

• KiCad er på tvers av plattformer (og svimlende; nedlastingssiden viser 13 støttede operativsystemer og tilbyr nedlasting av kildekode hvis ingen av dem passer deg). Bruk kicad-enhetlig standardinstallasjon, ikke den nattlige utviklingen. Se trinn 4 for avanserte valgfrie detaljer om bibliotekinstallasjon.
• Git er også plattformplattform. Hvis du bruker Windows, vil jeg anbefale det imponerende Git for Windows-prosjektet for en mer nyttig, fullt utstyrt opplevelse.

Installasjonsdokumentasjonen tilgjengelig på begge disse nettstedene vil være mer fullstendig enn noen beskrivelse jeg kan tilby her. Når begge programmene er lastet ned og installert, kan du klone Brainbows prosjektmal fra vårt Github -depot. Kommandoen git clone tar strukturen `git clone {src directory} {target directory}`; for prosjektet vårt, bruk `git clone https://github.com/builtbybrainbow/kicad-starter.git {target directory}`.

Kloning av en git repo er en spesiell kopieringsform; når du kloner et prosjekt, får du en kopi av alle filene som er inkludert i repoen, samt hele Git-sporingshistorikken til prosjektet. Ved å klone vår repo, får du en prosjektkatalog som allerede er strukturert med våre anbefalinger for bruk av Git med KiCad. Vi vil dekke mer om prosjektstrukturen i trinn 6, eller du kan hoppe til trinn 7 hvis du klør for å komme i gang.

Noen få raske husholdningsoppgaver - kjør `git remote rm origin 'for å fjerne lenken til Github -prosjektet du klonet fra. Kjør også `git commit --amend --author =" John Doe "`, og erstatt forfatterparameteren med navnet ditt og e -postadressen din. Dette endrer den siste forpliktelsen (som i dette tilfellet også er den første forpliktelsen) og endrer forfatteren til deg, i stedet for Brainbow.

Trinn 4: Installasjonsmerknad: KiCad Libraries

Et raskt notat om KiCads bibliotekstruktur. KiCad tilbyr et sett med biblioteker som vedlikeholdes av utviklerteamet for et bredt spekter av elektriske komponenter. Det er tre hovedbiblioteker:

• Skjematiske symboler: Symboler som brukes for å representere elektroniske komponenter i en kretsskjematisk tegning.
• PCB -fotavtrykk: 2D -tegninger som representerer det faktiske fotavtrykket (kobberputer, silketrykk, osv.) Som skal brukes når kretsen legges ut på en PCB.
• 3D -modeller: 3D -modeller av elektroniske komponenter.

Disse bibliotekene lastes ned sammen med KiCad -programpakken du nettopp installerte. Du kan bruke KiCad uten større innsats. For "strømbrukere" lagres imidlertid kildefilene for bibliotekene i et git -depot på Github, slik at brukere som ønsker å holde seg oppdatert med de siste endringene, kan klone bibliotekets repos til sin egen maskin. Sporing av bibliotekene med git har en rekke fordeler - du kan velge når du vil oppdatere bibliotekene dine, og oppdateringer trenger bare å inkludere endringer i filene, i stedet for å laste ned hele settet med bibliotekfiler igjen. Du er imidlertid ansvarlig for å oppdatere bibliotekene, noe som kan være lett å glemme.

Hvis du vil klone bibliotekene, beskriver dette nettstedet de forskjellige Github -reposene KiCad. Git klon bibliotekene til datamaskinen din (f.eks: `git clone https:// github.com/KiCad/kicad-symbols.git`), åpne deretter KiCad, velg menypunktet" Preferanser ", og klikk på" Konfigurer stier … ". Dette lar deg fortelle KiCad katalogbanen for å se etter hvert bibliotek i. Disse miljøvariablene er standard til banen til bibliotekene som er installert med KiCad -installasjonen; Jeg noterte meg disse verdiene, slik at jeg kunne bytte tilbake til standardbibliotekene om nødvendig. KICAD_SYMBOL_DIR-banen skal peke til det klonede kicad-symbolbiblioteket, KISYSMOD til det klonede kicad-footprints-biblioteket og KISYS3DMOD til det klonede kicad-packages3d-biblioteket.

Når du vil oppdatere bibliotekene, kan du kjøre en enkel 'git pull' -kommando i bibliotekets repo som vil fortelle Git å se etter forskjeller mellom din lokale kopi av bibliotekets repo og Github "eksterne" repo, og automatisk oppdatere din lokal kopi for å inkludere endringer.

Trinn 5: Git Fundamentals

Git er et komplekst og mangefasettert program, med hele bøker viet til å mestre det. Imidlertid er det noen få enkle konsepter som hjelper deg å forstå hvordan vi bruker Git i arbeidsflyten vår.

Git sporer endringer i filer ved hjelp av en serie etapper. Normale endringer finner sted i arbeidskatalogen. Når du er fornøyd med endringene du har gjort i en serie filer, legger du til filene du har endret i oppsettingsområdet. Når du har gjort alle endringene du planlegger og iscenesatt alle filene du vil spore i Git, overfører du disse endringene til depotet. Commits er i hovedsak øyeblikksbilder av tilstanden til filene i en repo på et bestemt tidspunkt. Siden Git sporer endringer i filer og lagrer disse endringene i commits, kan du når som helst tilbakestille et prosjekt tilbake til tilstanden det var i til enhver tidligere forpliktelse.

Det er mer komplekse temaer, som forgrening og fjernkontroller, men vi trenger ikke å bruke disse for å få fordelene med kildekontroll. Alt vi trenger er å spore endringer i våre KiCad -designfiler med en rekke forpliktelser.

Trinn 6: KiCad -prosjektstruktur

La oss se nærmere på strukturen til KiCad-Starter-prosjektet du klonet tidligere. Den er delt inn i en rekke underkataloger for enkel organisering:

• Krets: Denne mappen inneholder de faktiske KiCad -prosjektfilene (skjematisk, PCB, etc.). Jeg gir ikke nytt navn til denne mappen, men jeg gir nytt navn til alle filene inne med navnet på prosjektet (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: KiCad -prosjektfilen
  • Circuit.sch: den skjematiske filen KiCad.
  • Circuit.kicad_pcb: KiCad PCB -layoutfilen.
• Dokumentasjon: Denne mappen er for lagring av dokumentasjon angående prosjektet. Vi har planer om å forbedre denne plassen i fremtiden, men foreløpig inneholder den en enkel README -fil. Bruk den til å lagre notater om prosjektet for fremtidig gjennomgang.
• Fabrication: Denne mappen er hvor du vil lagre gerber -filene som de fleste fab -husene vil bruke til produksjon av kretskortet. Vi bruker den også til å lagre BOM -filer og andre dokumenter som kan være nødvendige for produksjon og montering.
• Biblioteker: Denne mappen er for lagring av prosjektspesifikke biblioteksfiler (vi dekker dette mer i noen få trinn).

Du har kanskje også lagt merke til noen andre filer (spesielt hvis du `ls -a` katalogen).. Git -katalogen er der Git gjør sin magi, og lagrer historien til depotet.. Gitignore -filen brukes til å fortelle Git hvilke filer den skal ignorere og ikke lagre i kildekontroll. Dette er for det meste sikkerhetskopifiler som KiCad genererer, eller noen få forskjellige "genererte" filer, for eksempel nettlister, som ikke bør lagres i kildekontroll fordi de genereres fra kilden som er den skjematiske filen.

Denne prosjektstrukturen er bare et utgangspunkt. Du bør tilpasse den til dine behov, og legge til seksjoner etter behov. I noen prosjekter har vi inkludert en programvaremappe eller kabinettmappe, hvor vi lagret modeller for 3D -utskriftskapsler for prosjektet.

Trinn 7: Bruke Git for KiCad -prosjekter

Vi er endelig klare til å se hvordan du bruker Git til å spore prosjektene dine. Denne instruksjonsboken er ikke ment å lære deg hvordan du bruker KiCad (selv om jeg kan gjøre en i fremtiden hvis det er behov for det), så vi skal gå gjennom noen trivielle eksempler for å vise deg hvordan arbeidsflyten går. Det skal være lett å forstå hvordan man tilpasser disse ideene til et ekte prosjekt.

Åpne kicad-starter-katalogen, og kjør deretter 'git log' for å vise forpliktelsesloggen. Det bør være en forpliktelse her, initialiseringen av repoen av Brainbow. Å kjøre 'git status' vil fortelle deg statusen til filene i repoen din (usporet, endret, slettet, iscenesatt).

For øyeblikket bør du ikke ha noen endringer i din repo. La oss gjøre en endring. Åpne KiCad -prosjektet og legg til en motstand i skjematikken, og lagre. Nå som kjører `git -status` skal vise at du har endret den skjematiske filen, men ikke har iscenesatt endringene for commit ennå. Hvis du er nysgjerrig på hva KiCad gjorde nøyaktig da du la til motstanden, kan du kjøre diff -kommandoen på den endrede filen `git diff Circuit/Circuit.sch`. Dette vil markere endringene mellom den nåværende versjonen av filen i arbeidskatalogen og tilstanden til filen ved den siste forpliktelsen.

Nå som vi har gjort en endring, la oss prøve å forplikte endringen til prosjekthistorikken vår. Vi må flytte endringene fra arbeidskatalogen til oppstillingsområdet. Dette flytter faktisk ikke filene i filsystemet, men er konseptuelt en måte å la Git vite at du har gjort alle de planlagte endringene for en bestemt fil og er klar til å gjøre disse endringene. Git gir noen tips når du kjører `git status 'for den neste handlingen. Legg merke til meldingen `(bruk" git add … "for å oppdatere hva som vil bli begått)` under `Endringer som ikke er iscenesatt for commit:`. Git forteller deg hvordan du skal flytte endringene til iscenesettelsesområdet. Kjør `git add Circuit/Circuit.sch` for å trinnvise endringene, deretter` git status 'for å se hva som skjedde. Nå ser vi den skjematiske filen under endringer som skal utføres. Hvis du ikke ønsker å foreta disse endringene ennå, tilbyr Git nyttig et annet tips: `(bruk" git reset HEAD … "for å unstage)`. Vi ønsker å begå disse endringene, så vi kjører `git commit -m" Lagt motstand til skjematisk "`. Dette forplikter endringene med den oppgitte meldingen. Å kjøre git -logg viser denne forpliktelsen i prosjektets forpliktelseshistorie.

Noen flere tips om forpliktelser.

1. Ikke forplikt deg for hver lagring. Forplikt deg når du føler at du har nådd et punkt der endringene dine har stivnet noe. Jeg forplikter meg etter at jeg er ferdig med en skjematisk, ikke etter hvert komponenttillegg. Du vil heller ikke forplikte deg for sjelden, for det kan være vanskelig å huske konteksten på hvorfor du gjorde de endringene du gjorde 3 uker senere. Å finne ut når du skal forplikte deg er litt av en kunst, men du vil bli mer komfortabel etter hvert som du bruker Git mer.
2. Bare butikkilde (for det meste). Dette inkluderer prosjekt-, skjematiske og layoutfiler, samt prosjektspesifikke biblioteker. Dette kan også inkludere dokumentasjonsfiler. Vær forsiktig når du lagrer avledede objekter fordi de lett kan komme ut av synkronisering med den opprinnelige kilden, og det forårsaker hodepine senere. Styrekatalog- og gerber-filer blir spesielt enkelt synkronisert, så unngås bedre (selv om mer detaljert veiledning er beskrevet i trinn 9).
3. Commit-meldinger er veldig nyttige, men godt strukturerte commit-meldinger er uvurderlige. Denne utmerkede artikkelen gir noen retningslinjer for å skrive klare, konsise og nyttige meldingsmeldinger. Dette kan kreve bruk av en tekstredigerer på kommandolinjen, noe som kan være komplisert for nybegynnere (`git commit 'uten alternativet -m melding åpner et tekstredigeringsprogram). For de fleste anbefaler jeg Nano -redaktøren. StackOverflow har en god forklaring på endring av redaktør

Trinn 8: Avansert: Semantisk versjonering for elektronikk

For eventyrlystne sjeler er følgende tips avanserte ideer, hentet fra mange timer med KiCad -utvikling. De er ikke spesielt nyttige på mindre prosjekter, men de kan virkelig spare deg for sorg da prosjektene dine vokser i kompleksitet.

I programvare er det et konsept om semantisk versjonering (semver). Semver definerer en vanlig navngivningsmetodikk for å identifisere programvareutgivelser etter "versjonsnummer", etter et mønster av "Major. Minor. Patch". For å sitere semvers spesifikasjoner, forskuddsfører du versjonsnummeret i henhold til følgende endringskategorier.

1. STOR versjon når du gjør inkompatible API -endringer,
2. Mindre versjon når du legger til funksjonalitet på en bakoverkompatibel måte,
3. PATCH-versjon når du gjør bakoverkompatible feilrettinger.

Vi i Brainbow bruker vår egen versjon av semver tilpasset behovene til maskinvareprosjekter. Våre spesifikasjoner følger det samme "Major. Minor. Patch" -mønsteret, selv om definisjonene våre på hvilke endringer som faller under hvilken kategori åpenbart er forskjellige.

1. STOR versjon: brukes til betydelige endringer i kretsens kjernefunksjonalitet (f.eks. Bytte prosessor fra ATmegaa til ESP8266).
2. Mindre versjon: brukes for komponentbytter som kan påvirke kretsdriften (f.eks. SPI-blitsbytte med pin-kompatibel del som kan ha et annet kommandosett) eller tillegg av noen mindre tilleggsfunksjoner (f.eks. Ekstra temperatursensor).
3. PATCH -versjon: brukes for mindre feilrettinger som ikke vil endre kretsoperasjonen (f.eks. Silketrykkjustering, mindre justering av sporlayout, enkle komponentbytter som 0603 kondensator til 0805).

I hardware semver oppdateres versjonsnummeret bare ved produksjon (akkurat som i programvare endres versjonsnumre bare med utgivelser, ikke hver enkelt forplikter seg til et prosjekt). Som et resultat har mange prosjekter lave versjonsnumre. Vi har ennå ikke et prosjekt som bruker mer enn 4 hovedversjoner.

Bortsett fra fordelene med konsistens og forståelighet du får ved å bytte til et veldefinert navnesystem, får du også fordeler med fastvarekompatibilitet og kundetilfredshet. Fastvare kan skrives mens du tar hensyn til hvilken versjon av brettet det er målrettet mot, og det kan være lettere å feilsøke hvorfor et bestemt program ikke fungerer på et bestemt kort ("riktig, 2.4.1 -fastvaren kjører ikke på 1.2 tavler fordi vi ikke har … "). Kunder har også tjent på maskinvaresemveren vår fordi kundeservice og feilsøking er mye enklere med en definert standard.

Trinn 9: Avansert: Bruke maskinvaresemantisk versjonering

For å bruke hardware semver i dine egne prosjekter bruker vi en Git -funksjon som kalles tagging. Når du først produserer et kort, er det 1.0.0 -versjonen av kortet. Sørg for at du har utført alle endringene i prosjektet, og kjør deretter 'git tag -a v1.0.0'. Dette åpner en redaktør slik at du kan skrive en merknadsmelding for denne taggen (veldig lik en commit -melding). Jeg inkluderer detaljer om produksjonen (hvem som laget kretskortet, som monterte brettet), som kan være nyttig informasjon senere.

Utgivelseskoden legges til forpliktelsesloggen og indikerer filens tilstand ved 1.0.0 -produksjonen. Dette kan være spesielt nyttig flere revisjoner senere når du må referere tilbake til dette punktet for feilsøking. Uten en spesifisert utgivelseslapp kan det være vanskelig å finne ut hvilken forpliktelse som var den siste på tidspunktet for produksjonen. En tagg av 1.0.0 (og 1.1, 1.1.1, etc) lar deg spesifisere at disse spesifikke kildefilene var de som ble brukt i en bestemt produksjonskjøring.

Et notat om Gerbers. Noen fab -hus krever gerber -filer for å lage brettet ditt, og du kan generere dem med KiCad. Disse er avledede objekter, generert fra kilden.kicad_pcb -filen, og vi bruker vanligvis ikke versjonskontroll avledede filer. Vi i Brainbow lagrer ikke gerber i versjonskontroll Bortsett fra når vi merker en utgivelse. Når vi er klare til å bygge, genererer vi gerberfilene, lagrer dem i Fabrication -mappen og forplikter og merker. Deretter fjerner vi gerberne og forplikter oss til å slette. Dette kan virke litt forvirrende i begynnelsen, men det sikrer at normalt bare forplikter lagring av kildefiler, og de merkede utgivelsene lagrer også de eksakte filene som ble brukt til å produsere brettene. Dette har vist seg utrolig nyttig for å spore produksjonsfeil uker senere.

Trinn 10: Neste trinn

Forhåpentligvis har denne introduksjonen lært deg nok til å begynne å bruke versjonskontroll på dine egne elektronikkprosjekter. Vi kom ikke til noen av de mer avanserte emnene, som versjonskontroll for biblioteker delt mellom prosjekter eller funksjonsgrener. Likevel er versjonskontroll som å spise grønnsakene dine: du får kanskje ikke det du synes du burde, men hver bit du får teller.

Brainbow jobber med en mer detaljert guide til noen av de mer avanserte funksjonene i arbeidsflyten vår. Vi håper å kunne publisere den en gang i løpet av de neste månedene. Følg oss her på Instructables, så gir vi deg beskjed når du kan lese den.

Takk for at du leser, og vi gleder oss til å se hva du lager!