Avoimen lähdekoodin laitteiston versionhallinta: 10 vaihetta

2024 Kirjoittaja: John Day | [email protected]. Viimeksi muokattu: 2024-01-30 09:02

Brainbow -tiimillämme on useita elektroniikkahankkeita vyöhömme alla, ja halusimme jakaa prosessimme versionhallinnan käyttämiseksi elektroniikan suunnittelun työnkulun hallitsemiseksi. Tätä työnkulkua on käytetty suurissa ja pienissä projekteissa yksinkertaisista 2-kerroksisista levyistä monimutkaisiin 10-kerroksisiin behemoteihin, ja se perustuu avoimen lähdekoodin työkaluihin. Toivottavasti muut voivat omaksua työnkulun itse ja hyötyä versionhallinnan eduista omille projekteilleen. Mutta mitä etuja versionhallinta voi tarjota elektroniikkaprojektille?

Vaihe 1: Miksi versio ohjaa elektroniikkaasi?

Versionhallinta (eli lähdevalvonta tai versionhallinta) on hyvin ymmärretty ja laajalti hyväksytty konsepti ohjelmistosuunnittelussa. Lähdeohjauksen idea on seurata järjestelmällisesti ohjelman tai sovelluksen lähdekoodiin tehtyjä muutoksia. Jos muutokset rikkovat sovelluksen, voit palauttaa lähdekooditiedostot menneisyyden tunnettuun toimintatilaan. Käytännössä lähdeohjausjärjestelmien avulla voit seurata tiedostojen kokoelman historiaa (yleensä tietokoneohjelman, verkkosivuston jne. Lähdekooditiedostot) sekä visualisoida ja hallita näiden tiedostojen muutoksia.

Hankkeen muutoshistorian seuranta vaikuttaa hyödylliseltä elektroniikkaprojekteille; Jos teet virheen piirikaaviossa tai käytät väärää komponentin jalanjälkeä piirilevyasettelussa, olisi mukavaa seurata, mitä virheitä tehtiin ja mitä korjauksia toteutettiin projektin eri versioissa. Myös muiden päättäjien olisi hyödyllistä nähdä tämä historia ja ymmärtää eri muutosten konteksti ja motiivit.

Vaihe 2: Työkalut: KiCad ja Git

Käytämme tässä projektissa kahta päätyökalua: versionhallintajärjestelmää (VCS) ja elektroniikan suunnitteluautomaatio -ohjelmaa (EDA tai ECAD).

Siellä on monia versionhallintajärjestelmiä, mutta käytämme hajautettua VCS Git. Käytämme sitä useista syistä, mutta tärkeintä on, että se on avoimen lähdekoodin (tarkista!), Helppokäyttöinen (tarkista!) Ja de-facto-vakio-VCS avoimen lähdekoodin ohjelmistoille (tarkista!). Käytämme Gitiä VCS: nä seuraamaan ECAD -ohjelmamme käyttämien tiedostojen muutoksia. Tämä Instructable ei vaadi perehtymistä Gitiin, mutta yleistä mukavuutta komentorivillä käytetään. Yritän tarvittaessa linkittää hyödyllisiin resursseihin sekä Gitin että komentorivin käyttöön.

Useimmat lähdeohjausjärjestelmät toimivat erityisen hyvin tekstipohjaisille tiedostoille, joten tekstitiedostoja käyttävä ECAD-ohjelma olisi loistava. Siirry KiCadiin, avoimeen lähdekoodiin "Cross Platform and Open Source Electronics Design Automation Suite", jota CERNin tutkijat tukevat. KiCad on myös avoimen lähdekoodin (tarkista!), Helppokäyttöinen (vaikka jotkut olisivat eri mieltä kanssani tästä) ja erittäin kykenevä edistykselliseen elektroniikan suunnittelutyöhön.

Vaihe 3: Asennus

Asenna nämä ohjelmat noudattamalla alla olevien linkitettyjen lataussivustojen ohjeita.

• KiCad on monialustainen (ja huimaava; sen lataussivulla on 13 tuettua käyttöjärjestelmää ja se tarjoaa lähdekoodin latauksen, jos mikään niistä ei sovi sinulle). Käytä kicad-unified-oletusasennusta, älä öistä kehitystä. Katso vaihe 4, jos haluat lisätietoja kirjaston asennuksesta.
• Git on myös monialustainen. Jos käytät Windowsia, suosittelen vaikuttavaa Git for Windows -projektia hyödyllisemmän, monipuolisen kokemuksen saamiseksi.

Molemmilla sivustoilla saatavilla olevat asennusohjeet ovat täydellisempiä kuin mikään kuvaus, jonka voin tarjota täällä. Kun molemmat ohjelmat on ladattu ja asennettu, voit kloonata Brainbowin projektimallin Github -arkistostamme. Git clone -komento ottaa rakenteen "git clone {src directory} {kohdehakemisto}"; Käytä projektissamme "git klooni https://github.com/builtbybrainbow/kicad-starter.git {kohdehakemisto}".

Git -repon kloonaaminen on erityinen kopiointimuoto; kun kloonaat projektin, saat kopion kaikista repoon sisältyvistä tiedostoista sekä koko Git-seuratun projektin historian. Kloonaamalla repoamme saat projektiluettelon, joka on jo rakennettu suosituksillamme Gitin käyttämisestä KiCadin kanssa. Käsittelemme lisää projektin rakenteesta vaiheessa 6, tai voit siirtyä vaiheeseen 7, jos haluat saada töitä.

Muutama nopea siivoustehtävä - suorita "git remote rm origin" poistaaksesi linkin Github -projektiin, josta olet kloonannut. Suorita myös `git bind --amend --author =" John Doe "" ja korvaa kirjoittajaparametri nimesi ja sähköpostiosoitteesi. Tämä muuttaa viimeistä sitoumusta (joka tässä tapauksessa on myös ensimmäinen sitoumus) ja muuttaa tekijän sinulle, eikä Brainbowiksi.

Vaihe 4: Asennus Huomautus: KiCad Libraries

Yksi nopea huomautus KiCadin kirjastorakenteesta. KiCad tarjoaa kehittäjätiimin ylläpitämiä kirjastoja useille sähkökomponenteille. Pääkirjastoja on kolme:

• Kaavamerkit: Symbolit, joita käytetään elektronisten komponenttien esittämiseen piirikaaviossa.
• PCB -jalanjäljet: 2D -piirustukset, jotka edustavat todellista jalanjälkeä (kuparityynyjä, silkkipainoa jne.), Joita käytetään piirilevyn asettamisessa piirilevylle.
• 3D -mallit: elektronisten komponenttien 3D -mallit.

Nämä kirjastot ladataan juuri asentamasi KiCad -ohjelmapaketin kanssa. Voit käyttää KiCadia ilman vaivaa. "Tehokäyttäjille" kirjastojen lähdetiedostot on kuitenkin tallennettu GitHubin git -arkistoon, jolloin käyttäjät, jotka haluavat pysyä ajan tasalla uusimmista muutoksista, voivat kloonata kirjaston repot omalle koneelleen. Kirjastojen seurannalla gitin avulla on useita etuja - voit valita, milloin haluat päivittää kirjastojasi, ja päivitysten on sisällettävä vain muutokset tiedostoihin sen sijaan, että lataisit koko kirjastotiedostot uudelleen. Olet kuitenkin vastuussa kirjastojen päivittämisestä, mikä voi olla helppo unohtaa.

Jos haluat kloonata kirjastoja, tällä sivustolla kerrotaan eri Github -repojen KiCad -tarjouksista. Kloonaa kirjastot tietokoneellesi (esim: `git klooni https:// github.com/KiCad/kicad-symbol.git`), avaa sitten KiCad, valitse valikkorivin" Asetukset "-kohde ja napsauta" Määritä polut … ". Tämän avulla voit kertoa KiCadille hakemistopolun etsimään kutakin kirjastoa. Nämä ympäristömuuttujat ovat oletuksena KiCad -asennuksen yhteydessä asennettujen kirjastojen polku; Huomasin nämä arvot, jotta voisin tarvittaessa palata oletuskirjastoihin. KICAD_SYMBOL_DIR-polun pitäisi osoittaa kloonattuun kicad-symbolikirjastoon, KISYSMOD kloonattuun kicad-footprints-kirjastoon ja KISYS3DMOD kloonattuun kicad-package3d-kirjastoon.

Kun haluat päivittää kirjastot, voit suorittaa kirjaston repossa yksinkertaisen `git pull` -komennon, joka kehottaa Gitiä tarkistamaan eroja paikallisen kirjaston repon ja Githubin" etä "repon välillä ja päivittämään automaattisesti paikallinen kopio sisällyttääksesi muutokset.

Vaihe 5: Git -perusteet

Git on monimutkainen ja monipuolinen ohjelma, jonka hallintaan on omistettu kokonaisia kirjoja. On kuitenkin olemassa muutamia yksinkertaisia käsitteitä, jotka auttavat sinua ymmärtämään, miten käytämme Gitiä työnkulussa.

Git seuraa tiedostojen muutoksia käyttämällä vaiheita. Normaalit muutokset tapahtuvat työhakemistossa. Kun olet tyytyväinen sarjaan tekemiisi muutoksiin, lisäät muuttamasi tiedostot pysähdysalueelle. Kun olet tehnyt kaikki suunnitellut muutokset ja järjestänyt kaikki tiedostot, joita haluat seurata Gitissä, teet muutokset arkistoon. Sitoumukset ovat lähinnä tilannekuvia repon tiedostojen tilasta tiettynä ajankohtana. Koska Git seuraa tiedostoihin tehtyjä muutoksia ja tallentaa nämä muutokset sitoumuksiin, voit milloin tahansa palauttaa projektin takaisin tilaan, jossa se oli aiemmalla sitoutumisella.

On olemassa monimutkaisempia aiheita, kuten haarautumista ja kaukosäätimiä, mutta meidän ei tarvitse käyttää niitä saadaksemme lähteen hallinnan etuja. Tarvitsemme vain seurata muutoksia KiCad -suunnittelutiedostoihimme useilla sitoumuksilla.

Vaihe 6: KiCad -projektin rakenne

Katsotaanpa tarkemmin aiemmin kloonatun KiCad-Starter-projektin rakennetta. Se on jaettu useisiin alihakemistoihin organisoinnin helpottamiseksi:

• Piiri: Tämä kansio sisältää todelliset KiCad -projektitiedostot (kaavio, piirilevy jne.). En nimeä tätä kansiota uudelleen, mutta nimeän kaikki sisällä olevat tiedostot projektin nimellä (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: KiCad -projektitiedosto
  • Circuit.sch: KiCad -kaaviotiedosto.
  • Circuit.kicad_pcb: KiCad PCB -asettelutiedosto.
• Dokumentaatio: Tämä kansio on tarkoitettu projektia koskevien asiakirjojen tallentamiseen. Meillä on suunnitelmia parantaa tätä tilaa tulevaisuudessa, mutta toistaiseksi se sisältää yksinkertaisen README -tiedoston. Käytä sitä muistiinpanojen tallentamiseen projektista tulevaa tarkasteltavaa varten.
• Valmistus: Tähän kansioon tallennat gerber -tiedostot, joita useimmat fab talot käyttävät piirilevyn valmistukseen. Käytämme sitä myös BOM -tiedostojen ja muiden valmistukseen ja kokoonpanoon tarvittavien asiakirjojen tallentamiseen.
• Kirjastot: Tämä kansio on tarkoitettu projektikohtaisten kirjastotiedostojen tallentamiseen (katamme tämän muutamassa vaiheessa).

Olet ehkä huomannut myös muutamia muita tiedostoja (varsinkin jos valitset hakemiston "l --a").. Git -hakemisto on paikka, jossa Git tekee taikuuttaan ja tallentaa arkiston historian.. Gitignore -tiedostoa käytetään kertomaan Gitille, mitkä tiedostot sen tulisi jättää huomiotta eikä tallentaa lähdeohjaukseen. Nämä ovat enimmäkseen KiCadin luomia varmuuskopiotiedostoja tai muutamia erilaisia "luotuja" tiedostoja, kuten verkkolistoja, joita ei pitäisi tallentaa lähdeohjaukseen, koska ne on luotu skemaattisesta tiedostosta.

Tämä projektirakenne on vasta lähtökohta. Sinun on mukautettava se tarpeisiisi ja lisättävä osioita tarpeen mukaan. Joissakin projekteissa olemme sisällyttäneet ohjelmistokansion tai kotelokansion, johon olemme tallentaneet projektin 3D -tulostuskoteloiden malleja.

Vaihe 7: Gitin käyttäminen KiCad -projekteissa

Olemme vihdoin valmiita näkemään, miten Gitin avulla voidaan seurata projektejasi. Tämän Instructable -ohjelman ei ole tarkoitus opettaa sinulle KiCadin käyttöä (vaikka voin tehdä sellaisen myös tulevaisuudessa, jos sille on kysyntää), joten käymme läpi joitain triviaaleja esimerkkejä, jotta voimme näyttää sinulle, miten työnkulku toimii. Pitäisi olla helppo ymmärtää, miten nämä ideat mukautetaan todelliseen projektiin.

Avaa kicad-starter-hakemisto ja suorita "git log" näyttääksesi vahvistushistorian. Tässä pitäisi olla yksi sitoumus, Brainbowin tekemä repo. Git -tilan suorittaminen kertoo reposi tiedostojen tilan (jäljittämätön, muokattu, poistettu, vaiheitettu).

Tällä hetkellä sinun ei pitäisi tehdä muutoksia repossasi. Tehdään muutos. Avaa KiCad -projekti ja lisää kaavioon vastus ja tallenna. Nyt käynnissä olevan "git status" pitäisi osoittaa, että olet muokannut kaaviotiedostoa, mutta et ole vielä tehnyt niitä muutoksia sitoaksesi. Jos olet utelias siitä, mitä KiCad tarkasti teki, kun lisäsit vastuksen, voit suorittaa diff -komennon muokatussa tiedostossa "git diff Circuit/Circuit.sch". Tämä korostaa muutoksia työhakemistossa olevan tiedoston nykyisen version ja tiedoston tilan välillä viimeisen suorituksen yhteydessä.

Nyt kun olemme tehneet muutoksen, yritämme sitoa muutos projektihistoriaamme. Meidän on siirrettävä muutokset työhakemistostamme pysähdysalueelle. Tämä ei itse asiassa siirrä tiedostoja tiedostojärjestelmässä, mutta on käsitteellisesti tapa kertoa Gitille, että olet tehnyt kaikki suunnitellut muutokset tiettyyn tiedostoon ja olet valmis tekemään muutokset. Hyödyllisesti, Git antaa joitain vihjeitä, kun suoritat "git status" seuraavaa toimintoa varten. Huomaa viesti "(käytä" git add… "päivittääksesi mitä tehdään)" kohdassa "Muutokset, joita ei ole järjestetty sitoviksi:". Git kertoo, miten muutokset siirretään pysähdysalueelle. Suorita "git add Circuit/Circuit.sch" vaiheiden muuttamiseksi ja sitten "git status" nähdäksesi mitä tapahtui. Nyt näemme kaaviotiedoston muutettavien muutosten alla. Jos et halua vielä tehdä näitä muutoksia, Git tarjoaa avuliaasti toisen vihjeen: `(käytä" git reset HEAD… "unstage)". Haluamme tehdä nämä muutokset, joten suoritamme `git skirt -m" Lisätty vastus kaavioon "`. Tämä sitoo muutokset annetulla viestillä. Käynnissä oleva git -loki näyttää tämän sitoutumisen projektin sitoutumishistoriassa.

Vielä muutama vinkki sitoutumisesta.

1. Älä sitoudu jokaiseen säästöön. Sitoudu, kun sinusta tuntuu, että olet saavuttanut pisteen, jossa muutokset ovat jonkin verran vahvistuneet. Sitoudun sen jälkeen, kun olen suorittanut kaavion, en jokaisen komponentin lisäyksen jälkeen. Et myöskään halua sitoutua liian harvoin, koska muistaa kontekstisi, miksi teit muutokset, jotka teit 3 viikkoa myöhemmin, voi olla vaikeaa. Sitoutumisen selvittäminen on vähän taidetta, mutta tulet mukavammaksi, kun käytät Gitiä enemmän.
2. Vain tallentaa lähde (enimmäkseen). Tämä sisältää projekti-, kaavio- ja asettelutiedostot sekä projektikohtaiset kirjastot. Tämä voi sisältää myös dokumentaatiotiedostoja. Ole varovainen, kun tallennat johdettuja kohteita, koska ne voivat poistua synkronoinnista alkuperäisen lähteen kanssa helposti ja aiheuttaa päänsärkyä myöhemmin. BOM- ja gerber-tiedostot synkronoidaan erityisen helposti, joten niitä on parempi välttää (vaikka tarkemmat ohjeet on esitetty vaiheessa 9).
3. Sitoutumisviestit ovat erittäin hyödyllisiä, mutta hyvin jäsennellyt sitoutumisviestit ovat korvaamattomia. Tämä erinomainen artikkeli sisältää joitain ohjeita selkeiden, ytimekkäiden, hyödyllisten sitoutumisviestien kirjoittamiseen. Tämä voi vaatia komentorivin tekstieditorin käyttöä, mikä voi olla monimutkaista aloittelijoille (`git sitoutua` ilman -m -viesti -vaihtoehtoa avaa tekstieditorin). Useimmille suosittelen Nano -editoria. StackOverflow tarjoaa hyvän selityksen editorin vaihtamisesta

Vaihe 8: Edistynyt: Semanttinen versiointi elektroniikalle

Seuraavat vinkit ovat seikkailunhaluisille sieluille edistyneitä ideoita, jotka on kerätty KiCadin useiden tuntien kehityksestä. Ne eivät ole erityisen hyödyllisiä pienemmissä projekteissa, mutta ne voivat todella säästää sydämensärkyä, kun projektisi monimutkaistuvat.

Ohjelmistossa on käsite Semantic Versioning (semver). Semver määrittelee yhteisen nimeämismenetelmän ohjelmistojulkaisujen tunnistamiseksi "versionumerolla" mallin "Major. Minor. Patch" mukaisesti. Lainataksesi Semverin teknisiä tietoja, siirrät versionumeron seuraavien muutosluokkien mukaisesti.

1. MAJOR -versio, kun teet yhteensopimattomia sovellusliittymämuutoksia,
2. MINOR-versio, kun lisäät toimintoja taaksepäin yhteensopivalla tavalla,
3. PATCH-versio, kun teet taaksepäin yhteensopivia virheenkorjauksia.

Me Brainbow käyttää omaa versiota semverista, joka on sovitettu laitteistohankkeiden tarpeisiin. Tekniset tiedot noudattavat samaa "Major. Minor. Patch" -mallia, vaikka määritelmämme siitä, mitä muutoksia luokkaan kuuluu, eroavat ilmeisesti.

1. MAJOR -versio: käytetään merkittäviin muutoksiin piirin ydintoimintoihin (esim. Prosessorin vaihtaminen ATmegaasta ESP8266: een).
2. PIENI versio: käytetään komponenttien vaihtamiseen, jotka voivat vaikuttaa piirin toimintaan (esim. SPI-salamavaihto ja nastayhteensopiva osa, jolla voi olla erilainen komentojoukko) tai jonkin pienen lisäominaisuuden lisääminen (esim. Lisätty lämpötila-anturi).
3. PATCH -versio: käytetään pieniin virhekorjauksiin, jotka eivät muuta piirin toimintaa (esim. Silkkipainan säätö, vähäinen jäljen asettelun säätö, yksinkertaiset komponentinvaihdot, kuten 0603 -kondensaattori 0805: ksi).

Laitteistosemverissa versionumero päivitetään vain valmistuksen yhteydessä (aivan kuten ohjelmistossa, versionumerot muuttuvat vain julkaisujen myötä, eivät kaikki yksittäiset sitoutuvat projektiin). Tämän seurauksena monien projektien versiot ovat pieniä. Meillä ei ole vielä ollut projektissa yli 4 pääversiota.

Sen lisäksi, että saat johdonmukaisuuden ja ymmärrettävyyden edut, jotka saat siirtymällä hyvin määriteltyyn nimitysjärjestelmään, saat hyötyä myös laiteohjelmiston yhteensopivuudesta ja asiakastyytyväisyydestä. Laiteohjelmisto voidaan kirjoittaa ottaen huomioon sen kohdelevyn versio, ja voi olla helpompaa selvittää, miksi tietty ohjelma ei toimi tietyllä levyllä ("oikein, 2.4.1 -laiteohjelmisto ei toimi 1.2: ssa tauluja, koska meillä ei ole … "). Asiakkaat ovat hyötyneet myös laitteistopuoliskostamme, koska asiakaspalvelu ja vianmääritys on paljon helpompaa määritellyllä standardilla.

Vaihe 9: Lisäasetukset: Laitteistosemanttisen version käyttö

Jos haluat käyttää laitteistosemveria omissa projekteissasi, käytämme Git -ominaisuutta nimeltä tagging. Kun valmistat levyn ensimmäisen kerran, se on kyseisen levyn 1.0.0 -versio. Varmista, että olet tehnyt kaikki projektisi muutokset, ja suorita sitten `git tag -a v1.0.0`. Tämä avaa editorin, jotta voit kirjoittaa tälle tunnisteelle huomautusviestin (hyvin samanlainen kuin sitoutumisviesti). Sisällytän valmistukseen liittyviä tietoja (kuka teki piirilevyn, kuka kokosi levyn), mikä voi olla hyödyllistä tietoa myöhemmin.

Julkaisutunniste lisätään vahvistushistoriaan ja ilmaisee tiedostojen tilan 1.0.0 valmistusvaiheessa. Tämä voi olla erityisen hyödyllistä useita tarkistuksia myöhemmin, kun sinun on palattava tähän kohtaan vianmääritystä varten. Ilman määritettyä julkaisutunnistetta voi olla vaikeaa selvittää, mikä sitoumus oli viimeisin valmistushetkellä. Tunnisteen 1.0.0 (ja 1.1, 1.1.1 jne.) Avulla voit määrittää, että nämä tietyt lähdetiedostot olivat niitä, joita käytettiin tietyllä valmistuskerralla.

Huomautus Gerbersistä. Jotkut upeat talot vaativat levyn tekemiseen gerber -tiedostoja, ja voit luoda ne KiCadilla. Nämä ovat johdettuja objekteja, jotka on luotu.kicad_pcb -lähdetiedostosta, emmekä normaalisti versiokontrolloi johdettuja tiedostoja. Me Brainbowlla emme säilytä gerbereitä versionhallinnassa PAITSI julkaisun merkitsemisen yhteydessä. Kun olemme valmiita rakentamaan, luomme gerber -tiedostot, tallennamme ne Fabrication -kansioon ja sitomme ja merkitsemme. Sitten poistamme gerberit ja suoritamme poistamisen. Tämä saattaa tuntua aluksi hieman hämmentävältä, mutta se varmistaa, että normaalit sitoumukset tallentavat vain lähdetiedostot, ja merkityt julkaisut tallentavat myös tarkat levyt valmistuksessa käytetyt tiedostot. Tämä on osoittautunut erittäin hyödylliseksi valmistusvirheiden jäljittämisessä viikkoja myöhemmin.

Vaihe 10: Seuraavat vaiheet

Toivottavasti tämä johdanto on opettanut sinulle tarpeeksi aloittaaksesi versionhallinnan käytön omissa elektroniikkaprojekteissasi. Emme päässeet joihinkin edistyneempiin aiheisiin, kuten projektien tai ominaisuushaarojen välillä jaettujen kirjastojen versionhallintaan. Versionhallinta on kuitenkin kuin vihannesten syöminen: et ehkä saa sitä, mitä luulet tarvitsevasi, mutta jokainen saamasi osa laskee.

Brainbow työskentelee yksityiskohtaisemman oppaan parissa työnkulun kehittyneemmistä ominaisuuksista. Toivomme, että julkaisemme sen joskus seuraavien kuukausien aikana. Seuraa meitä täällä Instructablesissa, niin ilmoitamme sinulle varmasti, kun voit lukea sen.

Kiitos, että luit, emmekä malta odottaa, mitä teet!