Контрол на версиите за хардуер с отворен код: 10 стъпки

2024 Автор: John Day | [email protected]. Последно модифициран: 2024-01-30 07:53

Екипът на Brainbow има редица проекти за електроника под коланите си и ние искахме да споделим нашия процес за използване на контрол на версиите за управление на нашия работен процес по проектиране на електроника. Този работен процес е използван за големи и малки проекти, от прости двуслойни дъски до сложни 10 слоеви гиганти и се основава на инструменти с отворен код. Надяваме се, че други могат да приемат нашия работен процес за себе си и да получат предимствата на контрола на версиите за собствените си проекти. Но какви предимства може да предложи електронният проект за контрол на версиите?

Стъпка 1: Защо версията контролира вашата електроника?

Контролът на версиите (известен още като контрол на източника или контрол на ревизии) е добре разбрана и широко възприета концепция в софтуерното инженерство. Идеята зад контрола на източника е систематично проследяване на промените, направени в изходния код на програма или приложение. Ако промените прекъснат приложението, можете да върнете файловете с изходния код в известно работно състояние от миналото. На практика системите за управление на източника ви позволяват да проследявате историята на колекция от файлове (обикновено файловете с изходния код за компютърна програма, уебсайт и т.н.), както и да визуализирате и управлявате промените в тези файлове.

Проследяването на историята на промените в даден проект изглежда полезно за проекти по електроника; ако направите грешка в схемата на веригата или използвате грешен отпечатък на компонент в оформлението на печатната платка, би било хубаво да следите какви грешки са допуснати и какви поправки са внедрени в различни ревизии на проект. Също така би било полезно другите производители да видят тази история и да разберат контекста и мотивацията на различните промени.

Стъпка 2: Инструментите: KiCad и Git

В този проект използваме два основни инструмента: система за контрол на версиите (VCS) и програма за автоматизация на проектирането на електроника (EDA или ECAD).

Има МНОГО системи за контрол на версиите, но ние използваме разпределения VCS Git. Използваме го по редица причини, но ключовото е, че е с отворен код (проверете!), Лесен за използване (проверете!) И де факто стандартния VCS за софтуер с отворен код (проверете!). Ще използваме Git като VCS за проследяване на промените във файловете, които използва нашата програма ECAD. Този Instructable не изисква запознаване с Git, но се предполага общ комфорт при използване на командния ред. Ще се опитам да се свържа с полезни ресурси както за Git, така и за използване на командния ред, ако е необходимо.

Повечето системи за управление на източници работят особено добре за текстови файлове, така че програма ECAD, която използва текстови файлове, би била чудесна. Влезте в KiCad, отворен код "Cross Platform and Open Source Electronics Design Automation Suite", подкрепен от изследователи от CERN. KiCad също е с отворен код (проверете!), Лесен за използване (въпреки че някои не биха се съгласили с мен по този въпрос) и много способен за усъвършенствана работа по проектиране на електроника.

Стъпка 3: Инсталиране

За да инсталирате тези програми, следвайте инструкциите от техните различни сайтове за изтегляне, свързани по -долу.

• KiCad е междуплатформен (и главозамайващо; тяхната страница за изтегляне изброява 13 поддържани операционни системи и предлага изтегляне на изходен код, ако никой от тях не ви подхожда). Използвайте унифицираната по подразбиране kicad инсталация, а не нощната разработка. Вижте Стъпка 4 за разширени незадължителни подробности относно инсталирането на библиотеката.
• Git също е кросплатформен. Ако използвате Windows, бих препоръчал впечатляващия проект Git за Windows за по-полезно, пълнофункционално изживяване.

Документацията за инсталиране, налична на двата сайта, ще бъде по -пълна от всяко описание, което мога да предложа тук. След като и двете програми бъдат изтеглени и инсталирани, можете да клонирате шаблона на проекта на Brainbow от нашето хранилище на Github. Командата git clone приема структурата `git clone {src directory} {target directory}`; за нашия проект използвайте `git clone https://github.com/builtbybrainbow/kicad-starter.git {целевата директория}`.

Клонирането на git repo е специална форма на копиране; когато клонирате проект, получавате копие на всички файлове, включени в репото, както и цялата проследена от Git история на проекта. Чрез клониране на нашето репо получавате директория на проект, вече структурирана с нашите препоръки за използване на Git с KiCad. Ще разгледаме повече за структурата на проекта в Стъпка 6 или можете да преминете към Стъпка 7, ако сърбите, за да започнете работа.

Няколко бързи домакински задачи - стартирайте `git remote rm origin`, за да премахнете връзката към проекта Github, от който сте клонирали. Също така стартирайте `git commit --amend --author =" John Doe "`, като замените параметъра на автора с вашето име и имейл. Това изменя последния коммит (който в този случай е и първият коммит) и променя автора вместо вас, а не Brainbow.

Стъпка 4: Инсталация Бележка: KiCad библиотеки

Една бърза бележка за библиотечната структура на KiCad. KiCad предоставя набор от библиотеки, поддържани от екипа на разработчиците за широк спектър от електрически компоненти. Има три основни библиотеки:

• Схематични символи: Символи, използвани за представяне на електронни компоненти в схематичен чертеж.
• Отпечатъци от печатни платки: 2D чертежи, представящи действителния отпечатък (медни подложки, текст от копринен печат и т.н.), които да се използват при полагане на веригата върху печатна платка.
• 3D модели: 3D модели на електронни компоненти.

Тези библиотеки се изтеглят заедно с току -що инсталирания пакет от програми на KiCad. Можете да използвате KiCad без повече усилия. Въпреки това, за „мощни потребители“, изходните файлове за библиотеките се съхраняват в git хранилище на Github, което позволява на потребителите, които искат да бъдат в крак с последните промени, да клонират репо на библиотеката на собствената си машина. Проследяването на библиотеките с git има редица предимства - можете да изберете кога искате да актуализирате библиотеките си, а актуализациите трябва само да включват промени във файловете, вместо да изтеглят отново целия набор от библиотечни файлове. Вие обаче сте отговорни за актуализирането на библиотеките, за което може лесно да се забрави.

Ако искате да клонирате библиотеките, този сайт описва различните предложения за Github repos KiCad. Git клонира библиотеките към вашия компютър (напр.: `git clone https:// github.com/KiCad/kicad-symbols.git`), след това отворете KiCad, изберете елемента от лентата с менюта„ Предпочитания “и щракнете върху„ Конфигуриране на пътища … . Това ви позволява да кажете на KiCad пътя на директорията да търси всяка библиотека. Тези променливи на средата по подразбиране са пътя към библиотеките, инсталирани с инсталацията на KiCad; Забелязах тези стойности, за да мога да се върна към библиотеките по подразбиране, ако е необходимо. Пътят KICAD_SYMBOL_DIR трябва да сочи към вашата библиотека за клонирани kicad-символи, KISYSMOD към библиотеката за клонирани kicad-footprints и KISYS3DMOD към клонираната библиотека kicad-packages3d.

Когато искате да актуализирате библиотеките, можете да изпълните проста команда „git pull“в репо библиотеката, която ще каже на Git да провери за разлики между вашето локално копие на репо библиотеката и „отдалеченото“репо на Github и автоматично да актуализира вашия локално копие за включване на промени.

Стъпка 5: Основи на Git

Git е сложна и многостранна програма, с цели книги, посветени на овладяването й. Има обаче няколко прости концепции, които ще ви помогнат да разберете как използваме Git в нашия работен поток.

Git проследява промените във файловете, използвайки поредица от етапи. Нормалните промени се извършват в работната директория. Когато сте доволни от промените, които сте направили в поредица от файлове, добавяте променените файлове в зоната за постановка. След като направите всички промени, които планирате, и поставите всички файлове, които искате да проследявате в Git, записвате тези промени в хранилището. Коммитите са по същество моментни снимки на състоянието на файловете в репо в определен момент. Тъй като Git проследява промените във файловете и съхранява тези промени в ангажименти, във всеки момент можете да върнете проект обратно в състоянието, в което е бил при всяко предишно ангажиране.

Има по -сложни теми, като разклоняване и дистанционни, но не е нужно да ги използваме, за да извлечем ползите от контрола на източника. Всичко, от което се нуждаем, е да проследим промените в нашите дизайнерски файлове на KiCad с поредица от ангажименти.

Стъпка 6: Структура на проекта на KiCad

Нека разгледаме по-отблизо структурата на проекта KiCad-Starter, който сте клонирали по-рано. Той е разделен на няколко поддиректории за лесна организация:

• Схема: Тази папка съдържа действителните файлове на проекта KiCad (схеми, печатни платки и т.н.). Не преименувам тази папка, но преименувам всички файлове вътре с името на проекта (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: файлът на проекта KiCad
  • Circuit.sch: схематичният файл на KiCad.
  • Circuit.kicad_pcb: файлът за оформление на PCB на KiCad.
• Документация: Тази папка е за съхранение на документация относно проекта. Имаме планове за подобряване на това пространство в бъдеще, но засега то съдържа прост README файл. Използвайте го, за да съхранявате бележки по проекта за бъдещи прегледи.
• Изработка: Тази папка е мястото, където ще съхранявате гербер файловете, които повечето фабрични къщи ще използват за производството на вашата платка. Използваме го и за съхраняване на BOM файлове и други документи, които може да са необходими за производството и сглобяването.
• Библиотеки: Тази папка е за съхранение на специфични за проекта библиотечни файлове (ще разгледаме това в няколко стъпки).

Може да сте забелязали и няколко други файла (особено ако `ls -a` директорията). Директорията.git е мястото, където Git прави магията си, съхранявайки историята на хранилището. Файлът.gitignore се използва, за да каже на Git кои файлове трябва да игнорира и да не ги съхранява в контрола на източника. Това са предимно архивни файлове, които KiCad генерира, или няколко различни „генерирани“файла, като например списъци с мрежи, които не трябва да се съхраняват в контрола на източника, защото са генерирани от източника, който е схематичният файл.

Тази структура на проекта е само отправна точка. Трябва да го адаптирате според вашите нужди и да добавите раздели, ако е необходимо. В някои проекти сме включили софтуерна папка или папка на кутия, където съхранявахме модели за кутии за 3D печат за проекта.

Стъпка 7: Използване на Git за KiCad проекти

Най -накрая сме готови да видим как да използваме Git за проследяване на вашите проекти. Този Instructable не е предназначен да ви научи как да използвате KiCad (въпреки че може да го направя в бъдеще, ако има търсене за него), така че ще преминем през някои тривиални примери, за да ви покажем как работи работният процес. Трябва да е лесно да се разбере как да се адаптират тези идеи към истински проект.

Отворете директорията kicad-starter, след това стартирайте `git log`, за да се покаже историята на коммитите. Тук трябва да има един коммит, инициализирането на репо от Brainbow. Изпълнението на „git status“ще ви покаже състоянието на файловете във вашето репо (непроследени, променени, изтрити, поетапни).

В момента не трябва да имате промени във вашето репо. Нека направим промяна. Отворете проекта KiCad и добавете резистор към схемата, след което запишете. Сега изпълнението на „git status“трябва да покаже, че сте променили схематичния файл, но все още не сте поставили тези промени за коммитиране. Ако сте любопитни какво точно е направил KiCad, когато сте добавили резистора, можете да изпълните командата diff на модифицирания файл `git diff Circuit/Circuit.sch`. Това ще подчертае промените между текущата версия на файла в работната директория и състоянието на файла при последното записване.

Сега, след като направихме промяна, нека се опитаме да извършим тази промяна в историята на нашия проект. Трябва да преместим промените от работната ни директория в зоната за постановка. Това всъщност не премества файловете във файловата система, но концептуално е начин да уведомите Git, че сте направили всички планирани промени за конкретен файл и сте готови да извършите тези промени. Полезно е, че Git предоставя някои съвети, когато стартирате `git status` за следващото действие. Обърнете внимание на съобщението `(използвайте„ git add… “, за да актуализирате какво ще бъде ангажирано)„ под „Промени, които не са поетапни за извършване:“. Git ви казва как да преместите промените в зоната за постановка. Стартирайте `git add Circuit/Circuit.sch`, за да промените промените, след това` git status`, за да видите какво се е случило. Сега виждаме схематичния файл под промените, които трябва да бъдат извършени. Ако все още не искате да извършвате тези промени, Git услужливо предлага още един съвет: `(използвайте" git reset HEAD … "за дестабиране)`. Искаме да извършим тези промени, затова изпълняваме `git commit -m" Добавен резистор към схемата "`. Това потвърждава промените с предоставеното съобщение. Изпълнението на git log ще покаже този коммит в историята на ангажиментите на проекта.

Още няколко съвета относно ангажиментите.

1. Не се ангажирайте с всяко спасяване. Ангажирайте се, когато почувствате, че сте достигнали точка, в която промените ви са донякъде втвърдени. Аз се ангажирам, след като завърша схемата, а не след всяко добавяне на компонент. Вие също не искате да се ангажирате твърде рядко, защото запомнянето на контекста защо сте направили промените, които сте направили 3 седмици по -късно, може да бъде трудно. Разбирането кога да се ангажирате е малко изкуство, но ще станете по -удобни, когато използвате Git повече.
2. Съхранявайте само източника (предимно). Това включва файлове с проекти, схеми и оформление, както и библиотеки, специфични за проекта. Това може да включва и файлове с документация. Бъдете внимателни, когато съхранявате производни обекти, тъй като те могат лесно да се синхронизират с оригиналния източник и това причинява главоболие по -късно. BOM и gerber файловете се десинхронизират особено лесно, така че се избягват по-добре (въпреки че по-подробни указания са обхванати в Стъпка 9).
3. Съобщенията за ангажименти са много полезни, но добре структурираните съобщения за ангажимент са безценни. Тази отлична статия предоставя някои насоки за писане на ясни, кратки, полезни съобщения за ангажименти. Това може да изисква използването на текстов редактор от командния ред, което може да ме усложни за начинаещи (`git commit` без опцията -m съобщение ще отвори текстов редактор). За повечето хора препоръчвам редактора Nano. StackOverflow има добро обяснение за промяна на редактора

Стъпка 8: Разширени: Семантични версии за електроника

За авантюристичните души следните съвети са напреднали идеи, събрани от много часове разработка на KiCad. Те не са особено полезни за по -малки проекти, но наистина могат да ви спестят сърдечни болки, тъй като вашите проекти стават все по -сложни.

В софтуера съществува концепция за семантична версия (semver). Semver дефинира обща методология за именуване за идентифициране на софтуерните версии по "номер на версията", следвайки модел на "Major. Minor. Patch". За да цитирате спецификациите на semver, напредвате номера на версията според следните категории промени.

1. ОСНОВНА версия, когато правите несъвместими промени в API,
2. МАЛКА версия, когато добавяте функционалност по обратен начин,
3. PATCH версия, когато правите обратно съвместими корекции на грешки.

Ние от Brainbow използваме собствена версия на semver, адаптирана да отговаря на нуждите на хардуерни проекти. Нашите спецификации следват същия модел "Major. Minor. Patch", въпреки че нашите определения за това какви промени попадат в коя категория очевидно се различават.

1. ОСНОВНА версия: използва се за значителни промени в основната функционалност на веригата (напр.: превключване на процесор от ATmegaa към ESP8266).
2. MINOR версия: използва се за подмяна на компоненти, която може да повлияе на работата на веригата (напр.: SPI флаш подмяна със съвместима с щифтове част, която може да има различен набор от команди) или добавяне на някаква малка допълнителна функция (напр.: добавен допълнителен температурен сензор).
3. Версия на PATCH: използва се за незначителни корекции на грешки, които няма да променят работата на веригата (напр.: настройка на копринено сито, малка настройка на оформлението на следи, прости смени на компоненти като кондензатор от 0603 до 0805).

В хардуерния semver номерът на версията се актуализира само при производството (точно както в софтуера, номерата на версиите се променят само с версии, а не всеки отделен ангажимент към проект). В резултат на това много проекти имат нисък брой версии. Все още имаме проект, който да използва повече от 4 основни версии.

Освен ползите в последователността и разбираемостта, които получавате от преминаването към добре дефинирана система за именуване, получавате и предимства в съвместимостта на фърмуера и удовлетвореността на клиентите. Фърмуерът може да бъде написан, като се вземе предвид версията на таблото, към която е насочен, и може да бъде по -лесно да се отстранят грешките, поради които определена програма не работи на определена платка („правилно, фърмуерът 2.4.1 не работи на 1.2 дъски, защото нямаме … ). Клиентите също са се възползвали от нашия хардуерен semver, тъй като обслужването на клиенти и отстраняването на проблеми е много по -лесно с дефиниран стандарт.

Стъпка 9: Разширени: Използване на хардуерни семантични версии

За да използваме хардуерен semver във вашите собствени проекти, използваме функция Git, наречена маркиране. Когато за първи път произвеждате дъска, това е версията 1.0.0 на тази дъска. Уверете се, че сте извършили всички промени във вашия проект, след това стартирайте `git tag -a v1.0.0`. Това ще отвори редактор, така че можете да напишете съобщение с анотация за този маркер (много подобно на съобщение за ангажиране). Включвам подробности за производството (кой е направил печатната платка, кой е сглобил платката), което може да бъде полезна информация по -късно.

Етикетът за освобождаване се добавя към историята на ангажименти и показва състоянието на файловете при производството на 1.0.0. Това може да бъде особено полезно няколко ревизии по -късно, когато трябва да се върнете към тази точка за отстраняване на неизправности. Без определен етикет за освобождаване може да бъде трудно да се разбере кой ангажимент е най -новият по време на производството. Етикет 1.0.0 (и 1.1, 1.1.1 и т.н.) ви позволява да посочите, че тези специфични изходни файлове са тези, използвани в конкретен производствен цикъл.

Бележка за Герберс. Някои фабрични къщи изискват гербер файлове, за да направят вашата дъска, и можете да ги генерирате с KiCad. Това са производни обекти, генерирани от изходния.kicad_pcb файл и обикновено не контролираме версиите производни файлове. Ние от Brainbow не съхраняваме герберите в контрола на версиите ОСВЕН, когато маркираме издание. Когато сме готови за изграждане, генерираме гербер файлове, съхраняваме ги в папката Fabrication и ангажираме и маркираме. След това премахваме герберите и извършваме изтриването. Това може да изглежда малко объркващо в началото, но гарантира, че нормалните ангажименти съхраняват само изходни файлове, а маркираните версии също съхраняват точните файлове, използвани за производството на дъските. Това се оказа изключително полезно за проследяване на производствени грешки седмици по -късно.

Стъпка 10: Следващи стъпки

Надяваме се, че това въведение ви е научило достатъчно, за да започнете да използвате контрол на версиите за вашите собствени проекти по електроника. Не стигнахме до някои от по -напредналите теми, като например контрол на версиите за библиотеки, споделени между проекти или клонове на функции. И все пак контролът на версиите е като яденето на зеленчуци: може да не получите това, което смятате, че трябва, но всяко малко, което правите, се брои.

Brainbow работи по по -подробно ръководство за някои от по -напредналите функции на нашия работен процес. Надяваме се да го публикуваме някъде през следващите няколко месеца. Следвайте ни тук на Instructables и ние със сигурност ще ви уведомим, когато можете да го прочетете.

Благодаря за четенето и нямаме търпение да видим какво правите!