Versionskontrol til open source -hardware: 10 trin

2024 Forfatter: John Day | [email protected]. Sidst ændret: 2024-01-30 08:28

Teamet hos Brainbow har en række elektronikprojekter under vores bælter, og vi ønskede at dele vores proces med brug af versionskontrol til at styre vores elektronikdesign -arbejdsgang. Denne arbejdsgang er blevet brugt til store og små projekter, fra enkle 2-lags plader til komplekse 10-lags behemoths og er baseret på open source-værktøjer. Forhåbentlig kan andre selv adoptere vores arbejdsgang og få fordelene ved versionskontrol til deres egne projekter. Men hvilke fordele kan versionskontrol tilbyde et elektronikprojekt?

Trin 1: Hvorfor versionskontrol din elektronik?

Versionskontrol (alias kildekontrol eller revisionskontrol) er et velkendt og bredt vedtaget koncept inden for software engineering. Ideen bag kildekontrol sporer systematisk ændringer foretaget i kildekoden for et program eller en applikation. Hvis ændringer bryder applikationen, kan du vende tilbage kildekodefilerne til en kendt arbejdstilstand fra fortiden. I praksis giver kildekontrolsystemer dig mulighed for at spore historikken for en samling af filer (normalt kildekodefiler til et computerprogram, websted osv.) Og visualisere og administrere ændringer af disse filer.

Sporing af historien om ændringer i et projekt synes nyttig til elektronikprojekter; hvis du laver en fejl i kredsløbsskematikken eller bruger det forkerte komponents fodaftryk i PCB -layoutet, ville det være rart at holde styr på, hvilke fejl der blev begået, og hvilke rettelser der blev implementeret i forskellige revisioner af et projekt. Det ville også være nyttigt for andre producenter at se denne historie og forstå konteksten og motivationen for forskellige ændringer.

Trin 2: Værktøjerne: KiCad og Git

Vi bruger to hovedværktøjer i dette projekt: versionskontrolsystemet (VCS) og elektronikdesignautomatiseringsprogrammet (EDA eller ECAD).

Der er MANGE versionskontrolsystemer derude, men vi bruger den distribuerede VCS Git. Vi bruger det af en række årsager, men nøglen er, at det er open source (check!), Let at bruge (check!) Og de-facto standard VCS til open source software (check!). Vi vil bruge Git som VCS til at spore ændringerne i de filer, som vores ECAD -program bruger. Denne instrukser kræver ikke fortrolighed med Git, men det forudsættes generel komfort at bruge kommandolinjen. Jeg vil forsøge at linke til nyttige ressourcer til både Git- og kommandolinjebrug efter behov.

De fleste kildestyringssystemer fungerer særligt godt for tekstbaserede filer, så et ECAD-program, der bruger tekstfiler, ville være fantastisk. Gå ind i KiCad, open-source "Cross Platform and Open Source Electronics Design Automation Suite" bakket op af forskere ved CERN. KiCad er også open source (check!), Let at bruge (selvom nogle er uenige med mig om det) og yderst i stand til avanceret elektronisk designarbejde.

Trin 3: Installation

For at installere disse programmer skal du følge instruktionerne fra deres forskellige downloadsider, der er linket herunder.

• KiCad er tværplatform (og svimlende, deres downloadside viser 13 understøttede operativsystemer og tilbyder en download af kildekoden, hvis ingen af dem passer dig). Brug den kicad-forenede standardinstallation, ikke den natlige udviklingsopbygning. Se trin 4 for avancerede valgfrie detaljer om bibliotekinstallation.
• Git er også cross-platform. Hvis jeg bruger Windows, vil jeg anbefale det imponerende Git til Windows-projekt for en mere nyttig, fuldt udstyret oplevelse.

Installationsdokumentationen til rådighed på begge disse websteder vil være mere komplet end nogen beskrivelse, jeg kan tilbyde her. Når begge programmer er downloadet og installeret, kan du klone Brainbows projektskabelon fra vores Github -lager. Kommandoen git clone tager strukturen `git clone {src directory} {target directory}`; til vores projekt skal du bruge `git-klon https://github.com/builtbybrainbow/kicad-starter.git {target directory}`.

Kloning af en git repo er en særlig form for kopiering; når du kloner et projekt, får du en kopi af alle de filer, der er inkluderet i repoen samt hele Git-sporet historik af projektet. Ved at klone vores repo får du et projektmappe, der allerede er struktureret med vores anbefalinger til brug af Git med KiCad. Vi dækker mere om projektstrukturen i trin 6, eller du kan springe til trin 7, hvis du klør for at komme i gang.

Et par hurtige rengøringsopgaver - kør `git remote rm origin 'for at fjerne linket til Github -projektet, du klonede fra. Kør også `git commit --amend --author =" John Doe "`, og erstat forfatterparameteren med dit navn og din e -mail. Dette ændrer den sidste forpligtelse (som i dette tilfælde også er den første forpligtelse) og ændrer forfatteren til dig i stedet for Brainbow.

Trin 4: Installation Bemærk: KiCad Libraries

En hurtig note om KiCads bibliotekstruktur. KiCad leverer et sæt biblioteker, der vedligeholdes af udviklerteamet til en lang række elektriske komponenter. Der er tre hovedbiblioteker:

• Skematiske symboler: Symboler, der bruges til at repræsentere elektroniske komponenter i en kredsløbsskematisk tegning.
• PCB -fodaftryk: 2D -tegninger, der repræsenterer det faktiske fodaftryk (kobberpuder, silketryktekst osv.), Der skal bruges, når kredsløbet udlægges på et printkort.
• 3D -modeller: 3D -modeller af elektroniske komponenter.

Disse biblioteker downloades sammen med KiCad -programpakken, du lige har installeret. Du kan bruge KiCad uden større indsats. For "strømbrugere" er kildefilerne til bibliotekerne dog gemt i et git -depot på Github, så brugere, der ønsker at holde sig ajour med de seneste ændringer, kan klone bibliotekets repos til deres egen maskine. Sporing af bibliotekerne med git har en række fordele - du kan vælge, hvornår du vil opdatere dine biblioteker, og opdateringer behøver kun at inkorporere ændringer i filerne frem for at downloade hele sættet med biblioteksfiler igen. Du er dog ansvarlig for at opdatere bibliotekerne, hvilket kan være let at glemme.

Hvis du gerne vil klone bibliotekerne, beskriver dette websted de forskellige Github -repos KiCad -tilbud. Git klon bibliotekerne til din computer (f.eks: `git klon https:// github.com/KiCad/kicad-symbol.git`), åbn derefter KiCad, vælg menupunktet" Indstillinger ", og klik på" Konfigurer stier … ". Dette lader dig fortælle KiCad den bibliotekssti, der skal søges efter hvert bibliotek i. Disse miljøvariabler har som standard stien til de biblioteker, der er installeret med KiCad -installationen; Jeg tog disse værdier til efterretning, så jeg om nødvendigt kunne skifte tilbage til standardbibliotekerne. KICAD_SYMBOL_DIR-stien skal pege på dit klonede kicad-symbolbibliotek, KISYSMOD til det klonede kicad-footprints-bibliotek og KISYS3DMOD til det klonede kicad-packages3d-bibliotek.

Når du vil opdatere bibliotekerne, kan du køre en simpel 'git pull' -kommando i bibliotekets repo, som vil fortælle Git at kontrollere, om der er forskelle mellem din lokale kopi af bibliotekets repo og Github "fjern" repo, og automatisk opdatere din lokal kopi for at inkorporere ændringer.

Trin 5: Git Fundamentals

Git er et komplekst og mangefacetteret program med hele bøger afsat til at mestre det. Der er dog et par enkle koncepter, der hjælper dig med at forstå, hvordan vi bruger Git i vores arbejdsgang.

Git sporer ændringer af filer ved hjælp af en række etaper. Normale ændringer finder sted i arbejdskataloget. Når du er tilfreds med de ændringer, du har foretaget i en række filer, tilføjer du de filer, du har ændret, til iscenesættelsesområdet. Når du har foretaget alle de ændringer, du planlægger at og iscenesat alle de filer, du gerne vil spore i Git, overfører du disse ændringer til depotet. Commits er i det væsentlige øjebliksbilleder af filernes tilstand i en repo på et bestemt tidspunkt. Da Git sporer ændringer i filer og gemmer disse ændringer i commits, kan du til enhver tid tilbageføre et projekt tilbage til den tilstand, det var i, til enhver tidligere forpligtelse.

Der er mere komplekse emner, f.eks. Forgrening og fjernbetjeninger, men vi behøver ikke at bruge disse for at opnå fordelene ved kildestyring. Alt, hvad vi har brug for, er at spore ændringer i vores KiCad -designfiler med en række forpligtelser.

Trin 6: KiCad -projektstruktur

Lad os se nærmere på strukturen i KiCad-Starter-projektet, du tidligere klonede. Det er opdelt i et antal underkataloger for let organisering:

• Kredsløb: Denne mappe indeholder de faktiske KiCad -projektfiler (skematisk, PCB osv.). Jeg omdøber ikke denne mappe, men jeg omdøber alle filerne inde med projektets navn (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: KiCad -projektfilen
  • Circuit.sch: KiCad -skematisk fil.
  • Circuit.kicad_pcb: KiCad PCB -layoutfilen.
• Dokumentation: Denne mappe er til lagring af dokumentation vedrørende projektet. Vi har planer om at forbedre dette rum i fremtiden, men for nu indeholder det en simpel README -fil. Brug den til at gemme noter om projektet, så du senere kan gennemgå dem.
• Fremstilling: I denne mappe gemmes de gerber -filer, som de fleste fab -huse vil bruge til fremstilling af dit printkort. Vi bruger den også til at gemme styklistefiler og andre dokumenter, der kan være nødvendige for fremstilling og samling.
• Biblioteker: Denne mappe er til lagring af projektspecifikke biblioteksfiler (vi dækker dette mere i et par trin).

Du har muligvis også bemærket et par andre filer (især hvis du `ls -a` biblioteket).. Git -biblioteket er, hvor Git gør sin magi og lagrer arkivets historie.. Gitignore -filen bruges til at fortælle Git, hvilke filer den skal ignorere og ikke gemme i kildekontrol. Disse er for det meste backupfiler, som KiCad genererer, eller et par forskellige "genererede" filer, f.eks. Netlister, som ikke bør gemmes i kildekontrol, fordi de genereres fra den kilde, der er den skematiske fil.

Denne projektstruktur er blot et udgangspunkt. Du bør tilpasse den til dine behov og tilføje sektioner efter behov. I nogle projekter har vi inkluderet en softwaremappe eller kabinetmappe, hvor vi lagrede modeller til 3D -udskrivningskabinetter til projektet.

Trin 7: Brug af Git til KiCad -projekter

Vi er endelig klar til at se, hvordan du bruger Git til at spore dine projekter. Denne Instructable er ikke beregnet til at lære dig at bruge KiCad (selvom jeg muligvis gør en i fremtiden, hvis der er efterspørgsel efter det), så vi kører igennem nogle trivielle eksempler for at vise dig, hvordan arbejdsgangen kører. Det skal være let at forstå, hvordan man tilpasser disse ideer til et rigtigt projekt.

Åbn kicad-starter-biblioteket, og kør derefter 'git log' for at få vist forpligtelseshistorikken. Der bør være et tilsagn her, initialiseringen af repoen af Brainbow. Kørsel af 'git status' fortæller dig status for filer i din repo (usporet, ændret, slettet, iscenesat).

I øjeblikket bør du ikke have ændringer i din repo. Lad os lave en ændring. Åbn KiCad -projektet, og tilføj en modstand til skematikken, og gem derefter. Nu kører `git status` skal vise, at du har ændret den skematiske fil, men ikke har iscenesat disse ændringer til commit endnu. Hvis du er nysgerrig efter, hvad KiCad præcis gjorde, da du tilføjede modstanden, kan du køre diff -kommandoen på den ændrede fil `git diff Circuit/Circuit.sch`. Dette vil fremhæve ændringerne mellem den aktuelle version af filen i arbejdskataloget og filens tilstand ved den sidste forpligtelse.

Nu hvor vi har foretaget en ændring, lad os prøve at forpligte denne ændring til vores projekthistorie. Vi er nødt til at flytte ændringerne fra vores arbejdskatalog til iscenesættelsesområdet. Dette flytter faktisk ikke filerne i filsystemet, men er konceptuelt en måde at lade Git vide, at du har foretaget alle dine planlagte ændringer for en bestemt fil og er klar til at foretage disse ændringer. Git giver nogle gode råd, når du kører 'git -status' til den næste handling. Bemærk meddelelsen `(brug" git add … "for at opdatere, hvad der vil blive begået)` under `Ændringer, der ikke er iscenesat for commit: '. Git fortæller dig, hvordan du flytter ændringerne til iscenesættelsesområdet. Kør 'git add Circuit/Circuit.sch' for at iscenesætte ændringerne, derefter 'git status' for at se, hvad der skete. Nu ser vi den skematiske fil under ændringer, der skal foretages. Hvis du ikke ønsker at foretage disse ændringer endnu, tilbyder Git nyttigt et andet tip: '(brug "git reset HEAD …" for at afinstallere) `. Vi ønsker at begå disse ændringer, så vi kører `git commit -m" Tilføjet modstand til skematisk "`. Dette forpligter ændringerne med den medfølgende meddelelse. Kørsel af git -log viser denne forpligtelse i projektets forpligtelseshistorik.

Et par tip mere om forpligtelser.

1. Forpligt dig ikke med hver gemning. Forpligt dig, når du føler, at du har nået et punkt, hvor dine ændringer er blevet en smule størknet. Jeg forpligter mig, når jeg er færdig med en skematisk, ikke efter hver komponenttilsætning. Du vil heller ikke begå dig for sjældent, for det kan være svært at huske konteksten om, hvorfor du foretog de ændringer, du foretog 3 uger senere. At finde ud af, hvornår man skal begå sig, er lidt af en kunst, men du bliver mere komfortabel, når du bruger Git mere.
2. Kun butikskilde (for det meste). Dette inkluderer projekt-, skematiske og layoutfiler samt projektspecifikke biblioteker. Dette kan også omfatte dokumentationsfiler. Vær forsigtig, når du opbevarer afledte objekter, fordi de let kan komme ud af synkronisering med den originale kilde, og det forårsager hovedpine senere. Stykliste- og gerberfiler synkroniseres særligt let, så det undgås bedre (selvom mere detaljeret vejledning er beskrevet i trin 9).
3. Commit-beskeder er meget nyttige, men velstrukturerede commit-meddelelser er uvurderlige. Denne fremragende artikel indeholder nogle retningslinjer for at skrive klare, præcise og nyttige kommissionsmeddelelser. Hvis du gør det, kan det være nødvendigt at bruge en tekstredigeringsværktøj til kommandolinjen, hvilket kan være kompliceret for begyndere ('git commit' uden -m -meddelelsesindstillingen åbner en teksteditor). For de fleste mennesker anbefaler jeg Nano -editoren. StackOverflow har en god forklaring på, hvordan du ændrer din editor

Trin 8: Avanceret: Semantisk versionering til elektronik

For de eventyrlystne sjæle er følgende tips avancerede ideer, hentet fra mange timers KiCad -udvikling. De er ikke særlig nyttige på mindre projekter, men de kan virkelig spare dig for hjertesorg, da dine projekter vokser i kompleksitet.

I software er der et koncept om semantisk versionering (semver). Semver definerer en fælles navngivningsmetodologi til at identificere softwareudgivelser efter "versionsnummer" efter et mønster af "Major. Minor. Patch". For at citere semvers spec, forskyder du versionsnummeret i henhold til følgende ændringskategorier.

1. STOR version, når du foretager inkompatible API -ændringer,
2. Mindre version, når du tilføjer funktionalitet på en bagudkompatibel måde,
3. PATCH-version, når du laver bagudkompatible fejlrettelser.

Vi hos Brainbow bruger vores egen version af semver, der er tilpasset behovene i hardwareprojekter. Vores spec følger det samme "Major. Minor. Patch" -mønster, selvom vores definitioner af hvilke ændringer, der falder ind under, hvilken kategori naturligvis er forskellige.

1. STOR version: bruges til væsentlige ændringer af kredsløbets kernefunktionalitet (f.eks. Skift af processor fra ATmegaa til ESP8266).
2. Mindre version: bruges til komponentswaps, der kan påvirke kredsløbets drift (f.eks. SPI-flash-swap med pin-kompatibel del, der kan have et andet kommandosæt) eller tilføjelse af en mindre ekstrafunktion (f.eks. Tilføjet ekstra temperatursensor).
3. PATCH -version: bruges til mindre fejlrettelser, der ikke ændrer kredsløbets drift (f.eks. Justering af silketryk, mindre justering af sporlayout, simple komponentswaps som 0603 kondensator til 0805).

I hardware semver opdateres versionsnummeret kun ved fremstilling (ligesom i software ændres versionsnumre kun med udgivelser, ikke hver enkelt forpligter sig til et projekt). Som følge heraf har mange projekter lave versionstal. Vi har endnu ikke et projekt til at bruge mere end 4 større versioner.

Bortset fra de fordele i konsistens og forståelighed, du får ved at skifte til et veldefineret navnesystem, får du også fordele inden for firmware-kompatibilitet og kundetilfredshed. Firmware kan skrives under hensyntagen til den version af tavlen, den er målrettet mod, og det kan være lettere at fejlsøge, hvorfor et bestemt program ikke fungerer på et bestemt kort ( højre, 2.4.1 -firmwaren kører ikke på 1.2 bestyrelser, fordi vi ikke har…”). Kunderne har også nydt godt af vores hardware semver, fordi kundeservice og fejlfinding er meget lettere med en defineret standard.

Trin 9: Avanceret: Brug af hardware semantisk versionering

For at bruge hardware semver i dine egne projekter bruger vi en Git -funktion kaldet tagging. Når du først fremstiller et kort, er det 1.0.0 -versionen af dette kort. Sørg for, at du har foretaget alle ændringerne i dit projekt, og kør derefter 'git tag -a v1.0.0'. Dette åbner en editor, så du kan skrive en annotationsbesked for dette tag (ligner meget en commit -besked). Jeg medtager detaljer om fremstillingen (hvem lavede printkortet, som samlede tavlen), hvilket kan være nyttig information senere.

Release -mærket tilføjes til commit -historikken og angiver filernes tilstand ved 1.0.0 -fremstillingen. Dette kan være særligt nyttigt flere ændringer senere, når du skal henvise til dette punkt for fejlfinding. Uden et specifikt frigivelsesmærke kunne det være svært at finde ud af, hvilken forpligtelse der var den nyeste på tidspunktet for fremstillingen. Et tag på 1.0.0 (og 1.1, 1.1.1 osv.) Lader dig angive, at disse specifikke kildefiler var dem, der blev brugt i en bestemt produktionskørsel.

En note om Gerbers. Nogle fab -huse kræver gerber -filer for at lave dit bord, og du kan generere dem med KiCad. Disse er afledte objekter, genereret fra kilden.kicad_pcb -fil, og vi har normalt ikke versionskontrolafledte filer. Vi hos Brainbow gemmer ikke gerber i versionskontrol UNDTAGELSE, når vi mærker en udgivelse. Når vi er klar til at bygge, genererer vi gerber -filer, gemmer dem i Fabrication -mappen og forpligter og tagger. Derefter fjerner vi gerberne og forpligter sletningen. Dette kan virke lidt forvirrende i starten, men det sikrer, at normalt kun gemmer kildefiler, og de mærkede udgivelser gemmer også de nøjagtige filer, der bruges til at fremstille tavlerne. Dette har vist sig bemærkelsesværdigt nyttigt til at spore fremstillingsfejl uger senere.

Trin 10: Næste trin

Forhåbentlig har denne introduktion lært dig nok til at begynde at bruge versionskontrol på dine egne elektronikprojekter. Vi nåede ikke til nogle af de mere avancerede emner, f.eks. Versionskontrol til biblioteker, der deles mellem projekter eller funktionsgrener. Stadig, versionskontrol er som at spise dine grøntsager: du får muligvis ikke det, du synes, du skal, men hver bit får du tæller.

Brainbow arbejder på en mere detaljeret vejledning til nogle af de mere avancerede funktioner i vores arbejdsgang. Vi håber at kunne udgive det engang i de næste par måneder. Følg os her på Instructables, så giver vi dig besked, når du kan læse den.

Tak fordi du læste med, og vi kan ikke vente med at se, hvad du laver!