Kontrola wersji sprzętu Open Source: 10 kroków

2024 Autor: John Day | [email protected]. Ostatnio zmodyfikowany: 2024-01-30 11:31

Zespół Brainbow ma za sobą wiele projektów elektronicznych i chcieliśmy podzielić się naszym procesem używania kontroli wersji do zarządzania przepływem pracy w projektowaniu elektroniki. Ten przepływ pracy był używany w dużych i małych projektach, od prostych tablic dwuwarstwowych po złożone 10-warstwowe behemoty i jest oparty na narzędziach typu open source. Mamy nadzieję, że inni będą mogli sami zaadaptować nasz przepływ pracy i zyskać korzyści płynące z kontroli wersji dla swoich własnych projektów. Ale jakie korzyści może zapewnić kontrola wersji projektom elektronicznym?

Krok 1: Dlaczego kontrola wersji w Twojej elektronice?

Kontrola wersji (inaczej kontrola źródła lub kontrola wersji) to dobrze rozumiana i szeroko stosowana koncepcja w inżynierii oprogramowania. Ideą kontroli kodu źródłowego jest systematyczne śledzenie zmian dokonywanych w kodzie źródłowym programu lub aplikacji. Jeśli zmiany spowodują uszkodzenie aplikacji, możesz przywrócić pliki kodu źródłowego do znanego stanu roboczego z przeszłości. W praktyce systemy kontroli kodu źródłowego umożliwiają śledzenie historii zbioru plików (zazwyczaj plików kodu źródłowego programu komputerowego, witryny internetowej itp.) oraz wizualizację i zarządzanie zmianami w tych plikach.

Śledzenie historii zmian w projekcie wydaje się przydatne w przypadku projektów elektronicznych; jeśli popełnisz błąd w schemacie obwodu lub użyjesz niewłaściwego śladu komponentu w układzie PCB, dobrze byłoby śledzić, jakie błędy zostały popełnione i jakie poprawki zostały wprowadzone w różnych wersjach projektu. Przydałoby się też innym twórcom zobaczyć tę historię, zrozumieć kontekst i motywacje różnych zmian.

Krok 2: Narzędzia: KiCad i Git

W tym projekcie wykorzystujemy dwa główne narzędzia: system kontroli wersji (VCS) oraz program do automatyzacji projektowania elektroniki (EDA lub ECAD).

Istnieje WIELE systemów kontroli wersji, ale używamy rozproszonego Git VCS. Używamy go z wielu powodów, ale kluczowe jest to, że jest open-source (sprawdź!), łatwy w użyciu (sprawdź!) i de facto standardowy VCS dla oprogramowania o otwartym kodzie źródłowym (sprawdź!). Będziemy używać Git jako VCS do śledzenia zmian w plikach używanych przez nasz program ECAD. Ten Instructable nie wymaga znajomości Git, ale zakłada się ogólną wygodę korzystania z wiersza poleceń. W razie potrzeby postaram się zamieścić linki do pomocnych zasobów zarówno dla Gita, jak i wiersza poleceń.

Większość systemów kontroli źródła działa szczególnie dobrze w przypadku plików tekstowych, więc program ECAD korzystający z plików tekstowych byłby świetny. Wejdź do KiCad, otwartego oprogramowania „Cross Platform and Open Source Electronics Design Automation Suite” wspieranego przez naukowców z CERN. KiCad jest również oprogramowaniem typu open source (sprawdź!), łatwym w użyciu (chociaż niektórzy by się z tym nie zgodzili) i wysoce zdolnym do zaawansowanych prac projektowych w elektronice.

Krok 3: Instalacja

Aby zainstalować te programy, postępuj zgodnie z instrukcjami z ich różnych witryn pobierania, do których łącza znajdują się poniżej.

• KiCad jest wieloplatformowy (i oszałamiająco; ich strona pobierania zawiera listę 13 obsługiwanych systemów operacyjnych i oferuje pobranie kodu źródłowego, jeśli żaden z nich Ci nie odpowiada). Użyj domyślnej instalacji kicad-unified, a nie nocnej wersji rozwojowej. Zobacz Krok 4, aby zapoznać się z zaawansowanymi opcjonalnymi szczegółami dotyczącymi instalacji biblioteki.
• Git jest również wieloplatformowy. Jeśli używasz systemu Windows, poleciłbym imponujący projekt Git for Windows, aby uzyskać bardziej przydatne, w pełni funkcjonalne wrażenia.

Dokumentacja instalacji dostępna na obu tych stronach będzie bardziej kompletna niż jakikolwiek opis, który mogę tu zaoferować. Po pobraniu i zainstalowaniu obu programów możesz sklonować szablon projektu Brainbow z naszego repozytorium Github. Polecenie git clone przyjmuje strukturę `git clone {src directory} {docelowy katalog}`; dla naszego projektu użyj `git clone https://github.com/builtbybrainbow/kicad-starter.git {docelowy katalog}`.

Klonowanie repozytorium git to specjalna forma kopiowania; kiedy sklonujesz projekt, otrzymasz kopię wszystkich plików zawartych w repozytorium, a także całą historię projektu śledzoną przez Git. Klonując nasze repozytorium, otrzymujesz katalog projektów, który jest już uporządkowany zgodnie z naszymi zaleceniami dotyczącymi używania Git z programem KiCad. Więcej informacji na temat struktury projektu omówimy w kroku 6 lub możesz przejść do kroku 7, jeśli nie możesz się doczekać pracy.

Kilka szybkich zadań porządkowych - uruchom `git remote rm origin`, aby usunąć link do projektu Github, z którego sklonowałeś. Uruchom także `git commit --amend --author="Jan Kowalski "`, zastępując parametr autor swoim imieniem i adresem e-mail. Zmienia to ostatni commit (który w tym przypadku jest również pierwszym commitem) i zmienia autora na Ciebie, a nie Brainbow.

Krok 4: Instalacja Uwaga: Biblioteki KiCad

Jedna krótka uwaga na temat struktury biblioteki programu KiCad. KiCad zapewnia zestaw bibliotek utrzymywanych przez zespół programistów dla szerokiej gamy komponentów elektrycznych. Istnieją trzy główne biblioteki:

• Symbole schematyczne: Symbole używane do przedstawiania elementów elektronicznych na schemacie obwodu.
• Ślady PCB: rysunki 2D przedstawiające rzeczywisty ślad (podkładki miedziane, tekst sitodrukowy itp.) do wykorzystania podczas układania obwodu na PCB.
• Modele 3D: modele 3D elementów elektronicznych.

Te biblioteki są pobierane wraz z właśnie zainstalowanym pakietem programów KiCad. Możesz używać programu KiCad bez większego wysiłku. Jednak dla „zaawansowanych użytkowników” pliki źródłowe bibliotek są przechowywane w repozytorium git na Github, co pozwala użytkownikom, którzy chcą być na bieżąco z najnowszymi zmianami, klonować repozytorium bibliotek na własną maszynę. Śledzenie bibliotek za pomocą git ma wiele zalet - możesz wybrać, kiedy chcesz aktualizować biblioteki, a aktualizacje wymagają jedynie wprowadzenia zmian w plikach, zamiast ponownego pobierania całego zestawu plików bibliotek. Jesteś jednak odpowiedzialny za aktualizację bibliotek, o czym łatwo zapomnieć.

Jeśli chcesz sklonować biblioteki, ta strona zawiera szczegółowe informacje o różnych repozytoriach Github, które oferuje KiCad. Git sklonuj biblioteki na swój komputer (np. `git clone https://github.com/KiCad/kicad-symbols.git`), a następnie otwórz program KiCad, wybierz z paska menu element „Preferencje” i kliknij „Konfiguruj ścieżki…”. Dzięki temu możesz wskazać KiCadowi ścieżkę katalogu, w której ma szukać każdej biblioteki. Te zmienne środowiskowe domyślnie są ścieżką do bibliotek zainstalowanych wraz z instalacją programu KiCad; Zanotowałem te wartości, aby w razie potrzeby móc wrócić do domyślnych bibliotek. Ścieżka KICAD_SYMBOL_DIR powinna wskazywać na twoją sklonowaną bibliotekę kicad-symbols, KISYSMOD na sklonowaną bibliotekę kicad-footprints, a KISYS3DMOD na sklonowaną bibliotekę kicad-packages3d.

Kiedy chcesz zaktualizować biblioteki, możesz uruchomić proste polecenie `git pull` w repozytorium bibliotek, które poinstruuje Git, aby sprawdził różnice między twoją lokalną kopią repozytorium bibliotek a „zdalnym” repozytorium Github i automatycznie zaktualizuje kopia lokalna, aby uwzględnić zmiany.

Krok 5: Podstawy Git

Git to złożony i wieloaspektowy program, z całymi książkami poświęconymi jego opanowaniu. Istnieje jednak kilka prostych koncepcji, które pomogą Ci zrozumieć, w jaki sposób używamy Git w naszym przepływie pracy.

Git śledzi zmiany w plikach za pomocą serii etapów. Normalne zmiany zachodzą w katalogu roboczym. Gdy jesteś zadowolony ze zmian wprowadzonych w serii plików, dodajesz zmienione pliki do obszaru przemieszczania. Po wprowadzeniu wszystkich planowanych zmian i przemieszczeniu wszystkich plików, które chcesz śledzić w Git, zatwierdzasz te zmiany w repozytorium. Commity to zasadniczo migawki stanu plików w repozytorium w określonym czasie. Ponieważ Git śledzi zmiany w plikach i przechowuje te zmiany w zatwierdzeniach, w dowolnym momencie możesz przywrócić projekt do stanu, w jakim znajdował się podczas wcześniejszego zatwierdzenia.

Istnieją bardziej złożone tematy, takie jak rozgałęzianie i zdalne, ale nie musimy ich używać, aby uzyskać korzyści z kontroli źródła. Wszystko, czego potrzebujemy, to śledzenie zmian w naszych plikach projektowych KiCad za pomocą serii zatwierdzeń.

Krok 6: Struktura projektu KiCad

Przyjrzyjmy się bliżej strukturze projektu KiCad-Starter, który sklonowałeś wcześniej. Jest podzielony na kilka podkatalogów dla łatwej organizacji:

• Obwód: Ten folder zawiera aktualne pliki projektu KiCad (schemat, PCB itp.). Nie zmieniam nazwy tego folderu, ale zmieniam nazwy wszystkich plików w środku na nazwę projektu (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: plik projektu KiCad
  • Circuit.sch: plik schematu programu KiCad.
  • Circuit.kicad_pcb: plik układu PCB programu KiCad.
• Dokumentacja: Ten folder służy do przechowywania dokumentacji dotyczącej projektu. Planujemy ulepszyć tę przestrzeń w przyszłości, ale na razie zawiera ona prosty plik README. Użyj go do przechowywania notatek o projekcie do późniejszego przeglądania.
• Fabrykacja: W tym folderze będziesz przechowywać pliki gerber, których większość wytwornych domów użyje do produkcji płytki drukowanej. Używamy go również do przechowywania plików BOM i innych dokumentów, które mogą być potrzebne do produkcji i montażu.
• Biblioteki: Ten folder służy do przechowywania plików bibliotek specyficznych dla projektu (omówimy to więcej w kilku krokach).

Być może zauważyłeś także kilka innych plików (szczególnie jeśli `ls -a` katalog). Katalog.git to miejsce, w którym Git robi swoją magię, przechowując historię repozytorium. Plik.gitignore służy do informowania Git, które pliki powinien zignorować i nie przechowywać w kontroli źródła. Są to głównie pliki kopii zapasowych, które generuje program KiCad, lub kilka różnych "wygenerowanych" plików, takich jak listy sieci, które nie powinny być przechowywane w kontroli źródła, ponieważ są generowane ze źródła, którym jest plik schematyczny.

Ta struktura projektu to tylko punkt wyjścia. Powinieneś dostosować go do swoich potrzeb i w razie potrzeby dodać sekcje. W niektórych projektach dołączyliśmy folder oprogramowania lub folder obudowy, w którym przechowywaliśmy modele do obudów do druku 3d dla projektu.

Krok 7: Używanie Gita w projektach KiCad

Jesteśmy w końcu gotowi, aby zobaczyć, jak używać Git do śledzenia swoich projektów. Ten Instructable nie ma na celu nauczenia Cię, jak korzystać z programu KiCad (chociaż mogę to zrobić w przyszłości, jeśli będzie na to zapotrzebowanie), więc omówimy kilka trywialnych przykładów, aby pokazać, jak działa przepływ pracy. Powinno być łatwe do zrozumienia, jak dostosować te pomysły do prawdziwego projektu.

Otwórz katalog kicad-starter, a następnie uruchom `git log`, aby wyświetlić historię zmian. Powinien być tutaj jeden commit, inicjalizacja repozytorium przez Brainbow. Uruchomienie `git status` poinformuje Cię o statusie plików w repozytorium (nieśledzone, zmodyfikowane, usunięte, umieszczone w poczekalni).

W tej chwili nie powinieneś mieć żadnych zmian w swoim repozytorium. Zróbmy zmianę. Otwórz projekt KiCad i dodaj rezystor do schematu, a następnie zapisz. Teraz uruchomienie `git status` powinno pokazać, że zmodyfikowałeś plik schematu, ale nie przemieściłeś jeszcze tych zmian do zatwierdzenia. Jeśli jesteś ciekawy, co dokładnie zrobił program KiCad po dodaniu rezystora, możesz uruchomić polecenie diff w zmodyfikowanym pliku `git diff Circuit/Circuit.sch`. Spowoduje to podświetlenie zmian między bieżącą wersją pliku w katalogu roboczym a stanem pliku przy ostatnim zatwierdzeniu.

Teraz, gdy wprowadziliśmy zmianę, spróbujmy wprowadzić tę zmianę do historii naszego projektu. Musimy przenieść zmiany z naszego katalogu roboczego do obszaru pomostowego. W rzeczywistości nie przenosi to plików w systemie plików, ale jest koncepcyjnie sposobem na poinformowanie Git, że wykonałeś wszystkie zaplanowane zmiany dla konkretnego pliku i jesteś gotowy do ich zatwierdzenia. Pomocne, Git dostarcza wskazówek, gdy uruchamiasz `git status` dla następnej akcji. Zwróć uwagę na komunikat „(użyj „git add…”, aby zaktualizować to, co zostanie zatwierdzone)” w sekcji „Zmiany nie przygotowane do zatwierdzenia:”. Git mówi ci, jak przenieść zmiany do obszaru pomostowego. Uruchom `git add Circuit/Circuit.sch`, aby przygotować zmiany, a następnie `git status`, aby zobaczyć, co się stało. Teraz widzimy plik schematu pod zmianami do zatwierdzenia. Jeśli nie chcesz jeszcze zatwierdzać tych zmian, Git oferuje kolejną wskazówkę: `(użyj „git reset HEAD…”, aby usunąć ze sceny)`. Chcemy zatwierdzić te zmiany, więc uruchamiamy `git commit -m "Dodano rezystor do schematu"`. To zatwierdza zmiany z dostarczoną wiadomością. Uruchomienie git log pokaże to zatwierdzenie w historii zatwierdzeń projektu.

Jeszcze kilka wskazówek dotyczących zatwierdzeń.

1. Nie angażuj się przy każdym obronie. Zobowiąż się, gdy poczujesz, że osiągnąłeś punkt, w którym twoje zmiany nieco się utrwaliły. Zatwierdzam po skończeniu schematu, a nie po każdym dodaniu komponentu. Nie chcesz też zbyt rzadko angażować się, ponieważ zapamiętanie kontekstu, dla którego wprowadziłeś zmiany, które wprowadziłeś 3 tygodnie później, może być trudne. Ustalenie, kiedy wykonać zatwierdzenie, jest trochę sztuką, ale staniesz się bardziej komfortowy, gdy będziesz częściej używać Git.
2. Tylko źródło sklepu (głównie). Obejmuje to pliki projektów, schematów i układów, a także biblioteki specyficzne dla projektu. Może to również obejmować pliki dokumentacji. Zachowaj ostrożność podczas przechowywania obiektów pochodnych, ponieważ mogą one łatwo stracić synchronizację z oryginalnym źródłem, co później powoduje bóle głowy. Pliki BOM i gerber są szczególnie łatwo desynchronizowane, więc lepiej ich unikać (chociaż bardziej szczegółowe wskazówki są omówione w kroku 9).
3. Komunikaty o zatwierdzeniu są bardzo przydatne, ale dobrze skonstruowane komunikaty o zatwierdzeniu są nieocenione. Ten doskonały artykuł zawiera wskazówki dotyczące pisania jasnych, zwięzłych i użytecznych komunikatów dotyczących zatwierdzenia. Może to wymagać użycia edytora tekstu wiersza poleceń, co może być skomplikowane dla początkujących (`git commit` bez opcji -m message otworzy edytor tekstu). Większości ludzi polecam edytor Nano. StackOverflow ma dobre wyjaśnienie zmiany edytora

Krok 8: Zaawansowane: Wersjonowanie semantyczne dla elektroniki

Dla żądnych przygód dusz, poniższe wskazówki są zaawansowanymi pomysłami, zebranymi z wielu godzin rozwoju programu KiCad. Nie są one szczególnie przydatne w mniejszych projektach, ale mogą naprawdę oszczędzić Ci bólu serca, gdy Twoje projekty stają się coraz bardziej złożone.

W oprogramowaniu istnieje koncepcja wersjonowania semantycznego (semver). Semver definiuje wspólną metodologię nazewnictwa w celu identyfikacji wydań oprogramowania według „numeru wersji”, zgodnie ze wzorcem „Major. Minor. Patch”. Aby zacytować specyfikację serwera, przesuwasz numer wersji zgodnie z następującymi kategoriami zmian.

1. GŁÓWNA wersja, gdy dokonujesz niezgodnych zmian w API,
2. Wersja MINOR po dodaniu funkcjonalności w sposób zgodny z poprzednimi wersjami,
3. Wersja PATCH, gdy dokonujesz poprawek błędów zgodnych z poprzednimi wersjami.

W Brainbow używamy własnej wersji serwera dostosowanej do potrzeb projektów sprzętowych. Nasza specyfikacja jest zgodna z tym samym wzorcem „Major. Minor. Patch”, chociaż nasze definicje tego, jakie zmiany należą do której kategorii, oczywiście się różnią.

1. Wersja MAJOR: używana do znaczących zmian w podstawowej funkcjonalności układu (np. przełączanie procesora z ATmegaa na ESP8266).
2. Wersja MINOR: używana do zamiany komponentów, które mogą mieć wpływ na działanie obwodu (np. zamiana flash SPI z częścią kompatybilną z pinami, która może mieć inny zestaw poleceń) lub dodanie jakiejś drobnej dodatkowej funkcji (np. dodanie dodatkowego czujnika temperatury).
3. Wersja PATCH: używana do drobnych poprawek, które nie zmieniają działania obwodu (np.: dostosowanie sitodruku, drobne dostosowanie układu śladów, proste zamiany komponentów, takie jak kondensator 0603 na 0805).

W serwerze sprzętowym numer wersji jest aktualizowany tylko podczas produkcji (podobnie jak w oprogramowaniu, numery wersji zmieniają się tylko wraz z wydaniami, a nie przy każdym indywidualnym zaangażowaniu w projekt). W rezultacie wiele projektów ma niskie numery wersji. Nie mamy jeszcze projektu wykorzystującego więcej niż 4 główne wersje.

Oprócz korzyści związanych ze spójnością i zrozumiałością, jakie daje przejście na dobrze zdefiniowany system nazewnictwa, zyskujesz również korzyści w zakresie kompatybilności oprogramowania układowego i zadowolenia klienta. Oprogramowanie układowe można napisać biorąc pod uwagę wersję płyty, na którą jest przeznaczony, i może być łatwiej debugować, dlaczego określony program nie działa na określonej płycie ("tak, oprogramowanie układowe 2.4.1 nie działa w wersji 1.2 tablice bo nie mamy …."). Klienci skorzystali również z naszego serwera sprzętowego, ponieważ obsługa klienta i rozwiązywanie problemów są znacznie łatwiejsze dzięki zdefiniowanemu standardowi.

Krok 9: Zaawansowane: używanie sprzętowej wersji semantycznej

Aby używać serwera sprzętowego we własnych projektach, wykorzystujemy funkcję Git o nazwie tagowanie. Kiedy po raz pierwszy produkujesz płytę, jest to wersja 1.0.0 tej płyty. Upewnij się, że zatwierdziłeś wszystkie zmiany w swoim projekcie, a następnie uruchom `git tag -a v1.0.0`. Spowoduje to otwarcie edytora, dzięki czemu będziesz mógł napisać adnotację dla tego znacznika (bardzo podobnego do komunikatu zatwierdzenia). Załączam szczegóły dotyczące producenta (kto wykonał PCB, kto zmontował płytkę), które mogą być później użyteczną informacją.

Znacznik wydania jest dodawany do historii zatwierdzenia i wskazuje stan plików w produkcji 1.0.0. Może to być szczególnie przydatne kilka wersji później, gdy musisz wrócić do tego punktu w celu rozwiązania problemu. Bez określonego tagu wydania może być trudno ustalić, które zatwierdzenie było najnowsze w momencie produkcji. Znacznik 1.0.0 (oraz 1.1, 1.1.1 itd.) pozwala określić, że te konkretne pliki źródłowe były używane w określonym przebiegu produkcyjnym.

Notatka o Gerberach. Niektóre bajeczne domy wymagają plików gerber do stworzenia tablicy, które można wygenerować za pomocą programu KiCad. Są to obiekty pochodne, wygenerowane ze źródłowego pliku.kicad_pcb i zwykle nie kontrolujemy plików pochodnych kontroli wersji. W Brainbow nie przechowujemy gerberów w kontroli wersji, Z WYJĄTKIEM sytuacji, gdy oznaczamy wydanie. Kiedy jesteśmy gotowi do budowania, generujemy pliki gerber, przechowujemy je w folderze Fabrication, zatwierdzamy i tagujemy. Następnie usuwamy gerbery i dokonujemy usunięcia. Na początku może się to wydawać nieco mylące, ale zapewnia, że normalne zatwierdzenia przechowują tylko pliki źródłowe, a otagowane wydania przechowują również dokładnie te pliki, które zostały użyte do wyprodukowania płyt. Okazało się to niezwykle przydatne w śledzeniu błędów produkcyjnych kilka tygodni później.

Krok 10: Kolejne kroki

Mam nadzieję, że to wprowadzenie nauczyło Cię wystarczająco dużo, aby zacząć używać kontroli wersji we własnych projektach elektronicznych. Nie dotarliśmy do niektórych bardziej zaawansowanych tematów, takich jak kontrola wersji bibliotek współdzielonych między projektami lub gałęzie funkcji. Mimo to kontrola wersji jest jak jedzenie warzyw: możesz nie dostać tego, co uważasz, że powinieneś, ale liczy się każdy kawałek.

Brainbow pracuje nad bardziej szczegółowym przewodnikiem po niektórych z bardziej zaawansowanych funkcji naszego przepływu pracy. Mamy nadzieję, że opublikujemy go w ciągu najbliższych kilku miesięcy. Śledź nas tutaj w Instructables, a na pewno damy Ci znać, kiedy będziesz mógł je przeczytać.

Dziękujemy za przeczytanie i nie możemy się doczekać, aby zobaczyć, co robisz!