В статье затронута важность разработки стандартов в команде hardware разработчиков, а также приведен пример одного из стандартов для ведения репозитория на сборку.
Для прочтения необходимо иметь базовые представления о конструировании.
Немного истории
До 2020 года я работал конструктором (разрабатывал электронику и электрику). Сейчас я сменил сферу деятельности, но считаю важным поднять вопрос, который возник в свое время, пока он совсем не выветрился из головы.
Команда наша была небольшая, внутренние регламенты еще не были сформированы, поэтому мне представилась возможность для творчества в части организации разработки своих узлов. Единственное ограничение - мнение требование заказчика. А заказчик - военный завод с бумажным документооборотом, нормоконтролем и всякими такими заморочками. В мои задачи входила разработка, сборка, наладка электроники и электрики (PCB проекты, чертежи, схемы, спецификации, ИИ - это были мои брат, жена,сестра и все такое). Ввиду того, что бумажный документооборот уже не соответствует темпам развития инструментов разработки, он принял вид некоторого формального рудимента. И все мы плевались на это требование, но смирялись, так как они ”заказывали музыку”.
Таким образом были файлы проекта, которые по сути нужны и достаточны и были спецификации, чертежи, схемы, перечни, которые нужны были в части узлов лишь формально. Мышление “самодельщика” быстро сформировало структуру проекта: папка с файлами.
Но как только посыпались ошибки и последующие исправления, количество папок выросло.
И это еще порядок. То что я видел в некоторых проектах удручает сильнее (см. ниже).
Каждая версия была важна, осмысленное именование могло бы помочь, но к счастью электроника и программирование часто идут бок о бок. Моя работа не была исключением. Так или иначе я познакомился с git, который был для меня “чудом чудесным” в хорошем смысле. Все файлы проектов сразу были подвергнуты версифицированию (корявый, но ценный log внизу).
Огорчило только то, что не было таких важных функций системы контроля версий как merge, diff, compare, ведь файлы для того же печатного узла для системы контроля версий - бинарники (за редким исключением, о чем ниже), а как известно данные инструменты в нативном гите не работают. Но осмысленное хранение уже было достаточно. К сожалению проект закрылся и наработки в области использования git для hardware так и остались “на полке”. Но именно поэтому я пишу здесь, чтобы привлечь внимание к проблеме и по возможности разработать регламент-образец для нашего сообщества. Я спрашивал других разработчиков из других городов о том как они организуют файлы проектов и у каждого был свой рецепт. Если мы поделимся своими рецептами, то увидим в них слабые и сильные стороны. Мы сможем сформировать свой, продуманный механизм. В данной статье я делюсь своим.
Стандартизация в конторе
Что то более серьезное всегда делается сообща. Наш коллектив не исключение. Были штатные сотрудники, были просто “туристы”, были люди, задействованные на outsource. Каждый делал так как ему казалось правильным. Итоговые документы pdf-ок с чертежами формально подходили для нормоконтроля и производства, но поддерживать это было очень сложно. Ситуация приближалась к важному вопросу: вопросу стандартизации. Да, мы молодой подвижный коллектив и противопоставляли себя излишне бюрократическому заводу. Главное - результат, документация потом. Но порой за этим прячется лень и неграмотность. Хочу подчеркнуть, что все зависит от уровня проекта и готовности самих людей. Если это реально просто поделка, то ничего не надо, но если работают несколько людей, а по результатам испытаний возникает куча правок, то стоит иметь порядок и однозначность в документации.
Таким образом мы столкнулись с необходимостью обговорить то как мы называем имена файлов, то как мы присваиваем обозначения сборкам и деталям, то как мы вносим изменения. Часть из соглашений было прописано, а часть была негласной. Здесь содержится мой первый призыв к сообществу:
“Разработайте хотя бы простенькие стандарты о том как вы оформляете структуру файлов в проекте”.
Это упускается даже в крупных конторах как оборонные заводы, где казалось бы есть целый отдел стандартизации. Отношение к группе ЕСКД как к дарам свыше, к которым нельзя ничего прибавить и убавить, порождает отвлеченность этих стандартов от реального процесса разработки. В каждом отделе формируется свой подход к организации хранения исходников. Доходит до того, что при внесении изменений в конструкцию заново формируется файл проекта от отдела к отделу. Я не говорю уже о хранении баз данных библиотек компонентов и footprint. Но, внимание, сам ГОСТ призывает его дополнять. В 2013 году в ГОСТ 2.001 добавлен пункт:
8.5 В КД допускается указывать ссылки на другие КД, стандарты и технические условия на материалы (вещества). Допускается указывать ссылки на стандарты организаций при условии, что они однозначно определяют соответствующие требования к изделию. Допускается указывать ссылки на технологические инструкции, выполненные по стандартам Единой системы технологической документации, когда требования, установленные этими инструкциями, являются единственными, гарантирующими требуемое качество изделий.
Не ленитесь, то что очевидно для вас, не является очевидным для всех. Пропишите или проговорите принципы, по которым организуете проект.
Есть ли у вас в команде/предприятии регламент на структуру файлов проекта?
Также существует "секретный" документ Д33, значение которого должна установить сама организация. И это выход для нас, друзья. Д33 - это электронный документ. Он содержит данные проектирования для печатной платы. В него вы можете поместить файлы проекта и узаконить его ответственное хранение. В него вы можете обязать вносить так же и bom, столь любимый нами. Подробнее см. РД 107.460640.020-88.
Стандарты очень нужны нам, только важно их вовремя обновлять и поддерживать. Да, нужна некая дисциплина для подчинения им, но они просто необходимы для повышения качества разработки.
Обзор систем контроля версий для hardware
Некоторый САПР поддерживает системы контроля версий нативно. К таким относится Altium Designer с SVN. Но с Altium у меня не сложилось из за цены в 500 кр. Но по сути это прекрасно. Это то что нужно, но для меня мимо. К тому же приходится использовать не только Altium, ведь существует механика и электрика (жгуты, блоки). Хотя если вы используете Altium стоит использовать SVN для всего.
Так же в сети есть примеры использования git хуков для KiCAD, для формирования diff. И это здорово, если вы используете KiCAD - это может вам помочь. Но мы использовали DipTrace в связке с КОМПАС и это не подходило. Но с глобальной точки зрения - это важный инструмент.
Eagle, столь популярный на западе тоже имеет костыли для интеграции с git.
Интересный ресурс CADLAB.io. Это что то типа github, но для проектов в Eagle, KiCAD, Altium. И ребята планируют расширять форматы. Это здорово, не проходите мимо, если вы используете данный САПР.
Уже сейчас я познакомился с EasyEDA. Ведь нужно порой до сих пор что-то накидать, но ставить серьезный САПР для дома как то не охота. Тем не менее он тоже имеет вкладки системы контроля версий. В общем движение в эту сторону имеется. Поделись тем, что известно тебе.
Но нашего инструмента так и не было. Да, его можно создать, да можно мигрировать на другой САПР. И если бы проект продолжился, то мы бы обязательно пошли дальше. Но важно дать общее положение. Общий регламент того как вести репозиторий независимо от САПР. Данный регламент стоит дополнять под тонкости конкретного САПР.
Есть ли у вас в команде/предприятии регламент на использование систем контроля версий?
Мой стандарт по ведению репозитория
Данный стандарт я писал около года. Я пытался дать почитать людям, но каких то правок от них я не дождался. Поэтому приглашаю на обсуждение. Полный текст помещен в конце по ссылке. Ниже текст разбит на блоки, дополненные обоснованием.
Стандарт назван “Обозначение версий для hardware”. И это не спроста. Очень важно иметь соответствие между коммитом и между реальным образцом (будь то макет или какая то ревизия тестового образца). Это решается обозначением номера версии как на самом изделии так и в документе, так и в логе git (такое требование и содержится в требовании на конструкцию на печатную плату).
1 Общие положения
1.1 За основу обозначений принята система внесения изменений ЕСКД. Если вы читаете этот документ впервые, то советую прочитать хотя бы второй раздел ГОСТ 2.503.
И я перепробовал всякое, но остановился на ЕСКДшном подходе указания версий потому что:
Это идеально клеилось с взаимодействием с заказчиком;
Все тонкости продуманы и опробованы годами до тебя;
Любой мало мальский инженер в теме и поймет интуитивно эти литеры.
1.2 Внесение изменений это не создание следующей версии железа, которая не совместимо с изделиями выпущенными до этого (п. 4.2 ГОСТ 2.503).
В этом случае необходимо присвоить изделию новое обозначение. На изделия единичного производства и на опытный образец (опытную партию) допускается не выпускать конструкторские документы с новыми обозначениями, если их применяют не более чем в одном документе.
Это очень важно. Каждый PartNumber (децимальный номер) должен быть уникальным. И важно присваивать обозначения, а не просто давать имена сборкам. Просто назвать энкодер “Энкодер”, но не дать обозначение - это значит внести путаницу, если вы будете делать уже другой энкодер. Ведь вы его назовете “Энкодер 2.0”, но у него своя история версий. Обозначение всех деталей и узлов можно производить по тому же классификатору ЕСКД с занесением в базу данных (у нас это был табличка в Excel на локальном диске) порядкового номера. Опять же причины:
Это идеально клеилось с взаимодействием с заказчиком;
Все тонкости продуманы и опробованы годами до тебя;
Любой мало мальский инженер в теме и поймет интуитивно эти литеры.
1.3 Под релизом подразумевается изготовление узла.
Это важно, так как я использую тег релиза (см. далее). К тому же важно вести отдельную релизную ветку с запретом fast forward.
Что нужно улучшить
Вообще бы надо отдельным стандартом прописать стратегию ветвления по типу Gitflow.
2 Внесение изменений и ведение репозитория
2.1 Log git представляет из себя журнал изменений до литеры O1.
По возможности стоит пользоваться Log git в течении всего жизненного цикла изделия.
Это важная концепция. Если вы не в теме, то важно знать, что для опытных образцов для упрощения документооборота допускается проводить изменения в документации просто по журналу изменений. Причем этот журнал составляется на более или менее самостоятельную сборку. Узел, блок или шкаф - подойдет. А Log git идеально выполняет его функции.
2.2 Репозиторий необходимо создавать для каждой самостоятельной сборочной единицы.
Это важно, так как вышестоящая сборка зависит от нижестоящих сборок. И важно, чтобы на сборку выше уходили только стабильные коммиты (со стабильной ветки).
Допускается не заводить репозиторий до тех пор, пока изменение не нагрянет.
Бывают сборки очень простые. В них изменений скорее всего не будет (жгут, две платы сцепленные вместе, плата с напаянными проводами). Ну ни не надо плодить сущности.
2.3 Коммит в стабильную ветку должен содержать корректировку всех документов (всех схем, перечней и т. п.).
К примеру вы решили поменять транзистор в сборке. Для этого надо:
поменять его в файле схемы;
обновить файл платы по схеме;
поменять его в bom;
поменять его в перечнях, спецификации и чертежах (при необходимости).
сделать коммит с версией = версия + 1.
2.4 Литеру изменения при релизе надо проставить во всех КД (в pdf, в исходник САПРа, на шеклографию и медь).
Если указание версии с поясняющей надписью "Версия", "version", "V" затруднительна, то следует указать её хотя бы в квадратных скобках.
Это спорно, и нет такого в ГОСТ, и скорее помогает отнести распечатанный чертеж с Log git. Но если бумага не ходит, то это не нужно.
2.5 Если изменение допускает доработку задела, то изменения по электрике нужно внести в файл схемы.
Если формирование файлов для производства не планируется, то доработка отражается в файле проекта в отдельном слое (см. табл. ниже). Если же планируется релиз. А доработка просто использует задел в дополнение, то для каждого дорабатываемого задела необходимо создать свой pcb файл с именем "Доработка N", где N - номер задела. В отдельном слое проекта (см. табл. ниже) необходимо внести пометки, касающиеся доработки (в том числе и место наклейки/надписи с новым номером литеры изменения). На изделие стоит поместить новый номер.
САПР | Слой доработки снизу | Слой доработки сверху |
DipTrace | Нижняя графика | Верхняя графика |
Altium | Mechanical 3 (Revision Back (orange)) | Mechanical 4 (Revision Front (orange)) |
Однако, если доработка несущественная, то достаточно сделать фотографии доработки, поместить их каталог "Доработка N" и выполнить коммит.
Если делать это сверх сил, то хотя бы в комментарию к коммиту нужно описать действия, которые необходимо произвести с изделием из предыдущего коммита, чтобы получилась новая версия. Например "Связи выполнить проводом сечением не менее 0.22 мм²"
Есть изменения, который мы вносим в железо доработкой (перемычки, перерезания дорожек). Таки доработки тоже нуждаются в описании для их повторения и для истории. При этом возможны две ситуации:
Изменение затронет только доработку;
Планируется отдать на производство изделие с изменениями, но параллельно планируется доработать имеющейся задел.
В первом случае необходимо прямо в проекте прописать изменение в отдельном слое. А во втором случае стоит создать отдельную папку с описанием доработки.
Упрощения важны, так как никто не будет проводить огромную работу из за мелочи, и репозиторий будет не актуальным.
2.6 Допускается указывать номер версии на изделии в новом месте (при этом старый номер необходимо подчистить или хотя бы изуродовать).
Это важно, чтобы сопоставить версию файлов и версию конкретной железки. Не оставляйте старые номера версий, ведь можно заметить сначала его, и ошибиться.
2.4 Изменения касающиеся вторичных КД (README файл, опечатки в ПЭ3 и т. п.) тоже закрепляются коммитом.
Казалось бы зачем? Но так мы исполняем требование ЕСКД. Отличить такой коммит можно по выводу его сравнения с родителем. Таким образом, чтобы иметь актуальные файлы по конкретной версии железа, нужно не просто найти номер в Log git, но и просмотреть коммиты выше на предмет изменений вторичных документов.
2.5 Тег релиза стоит размещать для изделий, отданных на производство. Тэг имеет следующий вид:
release_ММ.YY,где release - просто строка;
ММ.YY - год и месяц изготовления.
Подобное требование мы находим в требования на конструкцию печатных плат.
2.6 При отдаче в производство файл проекта стоит переименовать добавив к нему номер версии (для СКВ контрактника).
Это важно, чтобы платы были изготовлены именно по новой документации. Был один прокол с резонитом, который по имени файла нашел старые фотошаблоны.
3 Обозначение версий узла
3.1 HW версия представляет из себя номер последнего изменения.
Ну и итог стандарта - смысл версии железа.
Вот ссылка на стандарт.
Что дальше?
Для работы нужны и другие стандарты. Например применение Gitflow.
Хорошо бы работать хуки для проверки требований стандарта, или хотя бы косвенные проверки в виде проверки даты изменения gerber файлов и т. п.
Но это детали. К тому же большое количество стандартов тоже плохо. Важно иметь основные требования, а в тонкостях должна быть свобода.
Пишите ваши замечания в комментариях, так мы сделаем конструкторский мир чуточку лучше.
