Versiebeheer voor open source hardware: 10 stappen

2024 Auteur: John Day | [email protected]. Laatst gewijzigd: 2024-01-30 11:17

Het team van Brainbow heeft een aantal elektronicaprojecten onder onze riem en we wilden ons proces delen voor het gebruik van versiebeheer om onze elektronica-ontwerpworkflow te beheren. Deze workflow is gebruikt voor grote en kleine projecten, van eenvoudige 2-laagse borden tot complexe 10-laagse kolossen, en is gebaseerd op open source-tools. Hopelijk kunnen anderen onze workflow voor zichzelf overnemen en profiteren van de voordelen van versiebeheer voor hun eigen projecten. Maar welke voordelen kan versiebeheer een elektronicaproject bieden?

Stap 1: Waarom versiebeheer van uw elektronica?

Versiebeheer (ook bekend als bronbeheer of revisiebeheer) is een goed begrepen en algemeen aanvaard concept in software-engineering. Het idee achter bronbeheer is het systematisch volgen van wijzigingen in de broncode van een programma of applicatie. Als wijzigingen de toepassing verbreken, kunt u de broncodebestanden terugzetten naar een bekende werkende staat uit het verleden. In de praktijk stellen broncontrolesystemen u in staat om de geschiedenis van een verzameling bestanden (meestal de broncodebestanden voor een computerprogramma, website, enz.) te volgen en wijzigingen in die bestanden te visualiseren en te beheren.

Het bijhouden van de geschiedenis van wijzigingen aan een project lijkt nuttig voor elektronicaprojecten; als je een fout maakt in het schakelschema, of de verkeerde componentvoetafdruk gebruikt in de PCB-lay-out, zou het leuk zijn om bij te houden welke fouten zijn gemaakt en welke fixes zijn geïmplementeerd in verschillende revisies van een project. Het zou ook nuttig zijn voor andere makers om die geschiedenis te zien en de context en motivaties van verschillende veranderingen te begrijpen.

Stap 2: De tools: KiCad en Git

We gebruiken in dit project twee belangrijke tools: het versiebeheersysteem (VCS) en het automatiseringsprogramma voor elektronica-ontwerp (EDA of ECAD).

Er zijn VEEL versiecontrolesystemen, maar we gebruiken de gedistribueerde VCS Git. We gebruiken het om een aantal redenen, maar het belangrijkste is dat het open-source is (check!), makkelijk te gebruiken (check!), en de de-facto standaard VCS voor open-source software (check!). We zullen Git gebruiken als de VCS om de wijzigingen bij te houden in de bestanden die ons ECAD-programma gebruikt. Deze Instructable vereist geen bekendheid met Git, maar algemeen comfort bij het gebruik van de opdrachtregel wordt verondersteld. Ik zal proberen te linken naar nuttige bronnen voor zowel Git- als opdrachtregelgebruik, indien nodig.

De meeste broncontrolesystemen werken bijzonder goed voor op tekst gebaseerde bestanden, dus een ECAD-programma dat gebruikmaakt van tekstbestanden zou geweldig zijn. Betreed KiCad, de open-source "Cross Platform and Open Source Electronics Design Automation Suite", ondersteund door onderzoekers van CERN. KiCad is ook open-source (check!), gebruiksvriendelijk (hoewel sommigen het daar niet mee eens zijn), en zeer geschikt voor geavanceerd elektronica-ontwerpwerk.

Stap 3: Installatie

Om deze programma's te installeren, volgt u de instructies van hun verschillende downloadsites waarnaar hieronder wordt verwezen.

• KiCad is platformonafhankelijk (en duizelingwekkend; hun downloadpagina bevat 13 ondersteunde besturingssystemen en biedt een broncodedownload als geen van deze bij u past). Gebruik de met kicad verenigde standaardinstallatie, niet de nachtelijke ontwikkelingsbuild. Zie stap 4 voor geavanceerde optionele details over bibliotheekinstallatie.
• Git is ook platformonafhankelijk. Als je Windows gebruikt, zou ik het indrukwekkende Git voor Windows-project aanbevelen voor een meer bruikbare, volledig uitgeruste ervaring.

De installatiedocumentatie die op beide sites beschikbaar is, zal completer zijn dan welke beschrijving dan ook die ik hier kan bieden. Zodra beide programma's zijn gedownload en geïnstalleerd, kunt u de projectsjabloon van Brainbow klonen vanuit onze Github-repository. Het git clone commando heeft de structuur `git clone {src directory} {target directory}`; gebruik voor ons project `git clone https://github.com/builtbybrainbow/kicad-starter.git {target directory}`.

Het klonen van een git-repo is een speciale vorm van kopiëren; wanneer je een project kloont, krijg je een kopie van alle bestanden in de repo, evenals de volledige Git-tracked geschiedenis van het project. Door onze repo te klonen, krijgt u een projectdirectory die al is gestructureerd met onze aanbevelingen voor het gebruik van Git met KiCad. We bespreken meer over de projectstructuur in stap 6, of je kunt doorgaan naar stap 7 als je jeukt om aan het werk te gaan.

Een paar snelle huishoudelijke taken - voer `git remote rm origin` uit om de link naar het Github-project waarvan je gekloond hebt te verwijderen. Voer ook `git commit --amend --author="John Doe "` uit, waarbij u de parameter auteur vervangt door uw naam en e-mailadres. Dit wijzigt de laatste commit (wat in dit geval ook de eerste commit is) en verandert de auteur in jou, in plaats van Brainbow.

Stap 4: Installatie Opmerking: KiCad-bibliotheken

Een korte opmerking over de bibliotheekstructuur van KiCad. KiCad biedt een reeks bibliotheken die door het ontwikkelteam worden onderhouden voor een breed scala aan elektrische componenten. Er zijn drie hoofdbibliotheken:

• Schematische symbolen: symbolen die worden gebruikt voor het weergeven van elektronische componenten in een schematische tekening van een circuit.
• PCB-voetafdrukken: 2D-tekeningen die de werkelijke voetafdruk weergeven (koperen pads, zeefdruktekst, enz.) Die moeten worden gebruikt bij het leggen van het circuit op een PCB.
• 3D-modellen: 3D-modellen van elektronische componenten.

Deze bibliotheken worden gedownload samen met de KiCad-programmasuite die u zojuist hebt geïnstalleerd. U kunt KiCad zonder enige moeite gebruiken. Voor "hoofdgebruikers" worden de bronbestanden voor de bibliotheken echter opgeslagen in een git-repository op Github, zodat gebruikers die op de hoogte willen blijven van de laatste wijzigingen, de bibliotheekrepo's naar hun eigen machine kunnen klonen. Het volgen van de bibliotheken met git heeft een aantal voordelen - je kunt kiezen wanneer je je bibliotheken wilt bijwerken, en updates hoeven alleen wijzigingen in de bestanden op te nemen, in plaats van de hele set bibliotheekbestanden opnieuw te downloaden. U bent echter verantwoordelijk voor het bijwerken van de bibliotheken, wat gemakkelijk kan worden vergeten.

Als u de bibliotheken wilt klonen, geeft deze site informatie over de verschillende Github-repo's die KiCad biedt. Git kloon de bibliotheken naar uw computer (bijv. `git clone https://github.com/KiCad/kicad-symbols.git`), open vervolgens KiCad, selecteer het menubalk "Voorkeuren"-item en klik op "Paden configureren… ". Hiermee kunt u KiCad het directorypad vertellen waarin naar elke bibliotheek moet worden gezocht. Deze omgevingsvariabelen zijn standaard het pad naar de bibliotheken die met de KiCad-installatie zijn geïnstalleerd; Ik heb nota genomen van deze waarden, zodat ik indien nodig terug kon schakelen naar de standaardbibliotheken. Het pad KICAD_SYMBOL_DIR moet verwijzen naar uw gekloonde kicad-symbols-bibliotheek, KISYSMOD naar de gekloonde kicad-footprints-bibliotheek en KISYS3DMOD naar de gekloonde kicad-packages3d-bibliotheek.

Als je de bibliotheken wilt updaten, kun je een eenvoudig `git pull`-commando uitvoeren in de bibliotheekrepo die Git zal vertellen om te controleren op verschillen tussen je lokale kopie van de bibliotheekrepo en de Github "remote" repo, en automatisch je lokale kopie om wijzigingen op te nemen.

Stap 5: Git Fundamentals

Git is een complex en veelzijdig programma, met hele boeken gewijd aan het beheersen ervan. Er zijn echter een paar eenvoudige concepten die je zullen helpen begrijpen hoe we Git in onze workflow gebruiken.

Git houdt wijzigingen in bestanden bij met behulp van een reeks fasen. Normale wijzigingen vinden plaats in de werkdirectory. Als u tevreden bent met de wijzigingen die u in een reeks bestanden hebt aangebracht, voegt u de bestanden die u hebt gewijzigd toe aan het staging-gebied. Zodra je alle wijzigingen hebt aangebracht die je van plan bent en alle bestanden die je wilt bijhouden in Git hebt gestaged, leg je die wijzigingen vast in de repository. Commits zijn in wezen momentopnamen van de status van de bestanden in een repo op een bepaald tijdstip. Aangezien Git wijzigingen in bestanden bijhoudt en deze wijzigingen opslaat in commits, kun je op elk moment een project terugzetten naar de staat waarin het zich bevond bij een eerdere commit.

Er zijn complexere onderwerpen, zoals vertakkingen en remotes, maar we hoeven deze niet te gebruiken om de voordelen van bronbeheer te benutten. Het enige dat we nodig hebben, is om wijzigingen in onze KiCad-ontwerpbestanden bij te houden met een reeks commits.

Stap 6: KiCad-projectstructuur

Laten we de structuur van het KiCad-Starter-project dat u eerder hebt gekloond eens nader bekijken. Het is verdeeld in een aantal submappen voor eenvoudige organisatie:

• Circuit: Deze map bevat de actuele KiCad-projectbestanden (schema, PCB, etc). Ik hernoem deze map niet, maar ik hernoem alle bestanden erin met de naam van het project (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: het KiCad-projectbestand
  • Circuit.sch: het KiCad-schemabestand.
  • Circuit.kicad_pcb: het KiCad PCB-layoutbestand.
• Documentatie: Deze map is voor het opslaan van documentatie over het project. We hebben plannen om deze ruimte in de toekomst te verbeteren, maar voorlopig bevat het een eenvoudig README-bestand. Gebruik het om notities over het project op te slaan zodat u het later kunt bekijken.
• Fabricage: In deze map bewaart u de gerber-bestanden die de meeste fab-huizen zullen gebruiken voor het vervaardigen van uw printplaat. We gebruiken het ook om stuklijstbestanden en andere documenten op te slaan die nodig kunnen zijn voor productie en montage.
• Bibliotheken: deze map is voor het opslaan van projectspecifieke bibliotheekbestanden (we zullen hier in een paar stappen meer over doen).

Je hebt misschien ook een paar andere bestanden opgemerkt (vooral als je de directory `ls -a`). De.git directory is waar Git zijn magie doet, het opslaan van de geschiedenis van de repository. Het.gitignore-bestand wordt gebruikt om Git te vertellen welke bestanden het moet negeren en niet moet opslaan in broncodebeheer. Dit zijn meestal back-upbestanden die KiCad genereert, of een paar verschillende "gegenereerde" bestanden, zoals netlijsten, die niet in broncodebeheer moeten worden opgeslagen omdat ze worden gegenereerd vanuit de bron die het schematische bestand is.

Deze projectstructuur is slechts een startpunt. U moet het aanpassen aan uw behoeften en indien nodig secties toevoegen. In sommige projecten hebben we een softwaremap of bijlagenmap opgenomen, waar we modellen voor 3D-printbehuizingen voor het project hebben opgeslagen.

Stap 7: Git gebruiken voor KiCad-projecten

We zijn eindelijk klaar om te zien hoe we Git kunnen gebruiken voor het volgen van je projecten. Deze Instructable is niet bedoeld om je te leren hoe je KiCad moet gebruiken (hoewel ik er in de toekomst misschien een zal doen als er vraag naar is), dus we zullen enkele triviale voorbeelden doornemen om je te laten zien hoe de workflow werkt. Het moet gemakkelijk te begrijpen zijn hoe deze ideeën kunnen worden aangepast aan een echt project.

Open de map kicad-starter en voer dan `git log` uit om de commit-geschiedenis weer te geven. Er zou hier één commit moeten zijn, de initialisatie van de repo door Brainbow. Het uitvoeren van `git status` zal u de status van bestanden in uw repo vertellen (niet-gevolgd, gewijzigd, verwijderd, gefaseerd).

Op dit moment zou u geen wijzigingen in uw repo moeten hebben. Laten we een verandering aanbrengen. Open het KiCad-project, voeg een weerstand toe aan het schema en sla het op. Nu het uitvoeren van `git status` zou moeten laten zien dat je het schematische bestand hebt gewijzigd, maar deze wijzigingen nog niet hebt gestaged voor commit. Als je nieuwsgierig bent naar wat KiCad precies deed toen je de weerstand toevoegde, kun je het diff-commando uitvoeren op het aangepaste bestand `git diff Circuit/Circuit.sch`. Dit markeert de veranderingen tussen de huidige versie van het bestand in de werkdirectory en de status van het bestand bij de laatste vastlegging.

Nu we een wijziging hebben aangebracht, gaan we proberen die wijziging door te voeren in onze projectgeschiedenis. We moeten de wijzigingen van onze werkdirectory naar het staging-gebied verplaatsen. Dit verplaatst de bestanden niet echt in het bestandssysteem, maar is conceptueel een manier om Git te laten weten dat je al je geplande wijzigingen voor een bepaald bestand hebt gemaakt en klaar bent om die wijzigingen door te voeren. Het is handig dat Git enkele hints geeft wanneer je `git status` uitvoert voor de volgende actie. Let op het bericht `(gebruik "git add …" om bij te werken wat zal worden vastgelegd)` onder `Wijzigingen die niet zijn geënsceneerd voor vastlegging:`. Git vertelt je hoe je de wijzigingen naar het staging-gebied kunt verplaatsen. Voer `git add Circuit/Circuit.sch` uit om de wijzigingen te stagen en vervolgens `git status` om te zien wat er is gebeurd. Nu zien we het schematische bestand onder wijzigingen die moeten worden doorgevoerd. Als je deze wijzigingen nog niet wilt vastleggen, biedt Git nog een handige tip: `(gebruik "git reset HEAD …" om te unstagen)`. We willen deze wijzigingen wel vastleggen, dus we voeren `git commit -m "Weerstand toegevoegd aan schema"` uit. Hiermee worden de wijzigingen vastgelegd met het opgegeven bericht. Het uitvoeren van git log zal deze commit tonen in de project commit-geschiedenis.

Nog een paar tips over commits.

1. Leg je niet vast bij elke save. Leg je vast wanneer je het gevoel hebt dat je een punt hebt bereikt waarop je veranderingen enigszins zijn gestold. Ik bega nadat ik een schema heb voltooid, niet na elke toevoeging van componenten. Je wilt je ook niet te weinig committen, omdat het moeilijk kan zijn om de context te onthouden waarom je de wijzigingen hebt aangebracht die je 3 weken later hebt aangebracht. Uitzoeken wanneer je moet committen is een beetje een kunst, maar je zult je meer op je gemak voelen naarmate je Git meer gebruikt.
2. Alleen bron opslaan (meestal). Dit omvat de project-, schema- en lay-outbestanden, evenals projectspecifieke bibliotheken. Dit kunnen ook documentatiebestanden zijn. Wees voorzichtig bij het opslaan van afgeleide objecten, omdat ze gemakkelijk niet meer synchroon kunnen lopen met de oorspronkelijke bron, en dat veroorzaakt later hoofdpijn. Stuklijst- en gerber-bestanden worden bijzonder gemakkelijk gedesynchroniseerd en kunnen daarom beter worden vermeden (hoewel meer gedetailleerde richtlijnen worden behandeld in stap 9).
3. Commit-berichten zijn erg handig, maar goed gestructureerde commit-berichten zijn van onschatbare waarde. Dit uitstekende artikel geeft enkele richtlijnen voor het schrijven van duidelijke, beknopte, nuttige commit-berichten. Hiervoor kan het nodig zijn om een teksteditor op de opdrachtregel te gebruiken, wat voor beginners ingewikkeld kan zijn (`git commit` zonder de -m berichtoptie zal een teksteditor openen). Voor de meeste mensen raad ik de Nano-editor aan. StackOverflow heeft een goede uitleg over het wijzigen van je editor

Stap 8: Geavanceerd: semantische versiebeheer voor elektronica

Voor de avontuurlijke zielen zijn de volgende tips geavanceerde ideeën, verkregen uit vele uren KiCad-ontwikkeling. Ze zijn niet bijzonder handig bij kleinere projecten, maar ze kunnen u echt hartzeer besparen als uw projecten complexer worden.

In software is er een concept van Semantic Versioning (semver). Semver definieert een algemene naamgevingsmethode om softwarereleases te identificeren op "versienummer", volgens een patroon van "Major. Minor. Patch". Om de specificaties van semver te citeren, voert u het versienummer naar voren volgens de volgende wijzigingscategorieën.

1. MAJOR-versie wanneer u incompatibele API-wijzigingen aanbrengt,
2. MINOR-versie wanneer u functionaliteit op een achterwaarts compatibele manier toevoegt,
3. PATCH-versie wanneer u achterwaarts compatibele bugfixes aanbrengt.

Wij bij Brainbow gebruiken onze eigen versie van semver die is aangepast aan de behoeften van hardwareprojecten. Onze specificatie volgt hetzelfde patroon van "Major. Minor. Patch", hoewel onze definities van welke wijzigingen onder welke categorie vallen duidelijk verschillen.

1. BELANGRIJKE versie: wordt gebruikt voor significante wijzigingen in de kernfunctionaliteit van het circuit (bijvoorbeeld: overschakelen van processor van ATmegaa naar ESP8266).
2. MINOR-versie: gebruikt voor het verwisselen van componenten die de werking van het circuit kunnen beïnvloeden (bijv. SPI-flash-swap met pin-compatibel onderdeel dat mogelijk een andere commandoset heeft) of toevoeging van een kleine extra functie (bijv. toegevoegde extra temperatuursensor).
3. PATCH-versie: gebruikt voor kleine bugfixes die de werking van het circuit niet zullen veranderen (bijv. zeefdrukaanpassing, kleine aanpassing van de trace-lay-out, eenvoudige vervanging van componenten zoals 0603-condensator naar 0805).

In hardware semver wordt het versienummer alleen bijgewerkt bij de fabricage (net als bij software veranderen versienummers alleen met releases, niet elke individuele commit aan een project). Als gevolg hiervan hebben veel projecten lage versienummers. We moeten nog een project hebben dat meer dan 4 hoofdversies gebruikt.

Afgezien van de voordelen in consistentie en begrijpelijkheid die u krijgt door over te schakelen naar een goed gedefinieerd naamgevingssysteem, profiteert u ook van firmwarecompatibiliteit en klanttevredenheid. Firmware kan worden geschreven terwijl rekening wordt gehouden met de versie van het bord waarop het is gericht, en het kan gemakkelijker zijn om te debuggen waarom een bepaald programma niet werkt op een bepaald bord ("juist, de 2.4.1-firmware werkt niet op 1.2 borden omdat we geen …") hebben. Klanten hebben ook geprofiteerd van onze hardware-semver omdat klantenservice en probleemoplossing veel eenvoudiger is met een gedefinieerde standaard.

Stap 9: Geavanceerd: semantische hardwareversies gebruiken

Om hardware-semver in uw eigen projecten te gebruiken, gebruiken we een Git-functie genaamd tagging. Wanneer u voor het eerst een bord maakt, is dat de 1.0.0-versie van dat bord. Zorg ervoor dat je alle wijzigingen in je project hebt doorgevoerd en voer dan `git tag -a v1.0.0` uit. Dit opent een editor zodat je een annotatiebericht voor deze tag kunt schrijven (zeer vergelijkbaar met een commit-bericht). Ik voeg details toe over de fabricage (wie heeft de PCB gemaakt, wie de print heeft geassembleerd), wat later nuttige informatie kan zijn.

De release-tag wordt toegevoegd aan de commit-geschiedenis en geeft de status van de bestanden aan bij de productie van 1.0.0. Dit kan met name nuttig zijn meerdere revisies later wanneer u naar dit punt moet verwijzen voor het oplossen van problemen. Zonder een gespecificeerde release-tag kan het moeilijk zijn om erachter te komen welke commit de meest recente was op het moment van productie. Een 1.0.0 (en 1.1, 1.1.1, etc) tag laat je specificeren dat deze specifieke bronbestanden degene waren die in een bepaalde productierun werden gebruikt.

Een opmerking over Gerbers. Sommige fantastische huizen hebben gerber-bestanden nodig om je bord te maken, en je kunt ze genereren met KiCad. Dit zijn afgeleide objecten, gegenereerd uit het bronbestand.kicad_pcb, en normaal gesproken hebben we geen versiebeheer van afgeleide bestanden. Wij bij Brainbow slaan geen gerbers op in versiebeheer BEHALVE voor wanneer we een release taggen. Wanneer we klaar zijn om te bouwen, genereren we de gerber-bestanden, slaan ze op in de map Fabrication en commit en tag. Dan verwijderen we de gerbers en plegen de verwijdering. Dit lijkt in het begin misschien een beetje verwarrend, maar het zorgt ervoor dat normale commits alleen bronbestanden opslaan, en de getagde releases slaan ook de exacte bestanden op die zijn gebruikt om de boards te maken. Dit is opmerkelijk nuttig gebleken bij het opsporen van fabricagefouten weken later.

Stap 10: Volgende stappen

Hopelijk heeft deze introductie je genoeg geleerd om versiebeheer te gaan gebruiken op je eigen elektronicaprojecten. We kwamen niet bij enkele van de meer geavanceerde onderwerpen, zoals versiebeheer voor bibliotheken die worden gedeeld tussen projecten of functievertakkingen. Toch is versiebeheer als het eten van je groenten: je krijgt misschien niet wat je denkt te moeten, maar elk beetje dat je krijgt, telt.

Brainbow werkt aan een meer gedetailleerde gids voor enkele van de meer geavanceerde functies van onze workflow. We hopen het ergens in de komende maanden te publiceren. Volg ons hier op Instructables, en we zullen je zeker laten weten wanneer je het kunt lezen.

Bedankt voor het lezen, en we kunnen niet wachten om te zien wat je maakt!