205. Документация изделия: комплект, обозначения, ревизии

Плата собрана (раздел 199), проверена на линии (201) и пережила помехи (203) — но изделием её делает не пайка, а бумага: комплект документов, по которому изделие можно повторить, починить и изменить без автора. Пока плат три, документация живёт в голове; на десятой плате и втором годе жизни голова перестаёт быть надёжным носителем. Этот раздел — о минимальном порядке: какие документы входят в комплект, как их называть и нумеровать, что такое ревизия и как прошивка узнаёт, на какой ревизии платы она проснулась.

Числа раздела — арифметика _verify/docs205/doc_calc.py; чтение ревизии платы — board_rev.c, прогнан на ПК и собран для Cortex-M3 в stm-arm:1; выгрузка PDF из командной строки — kicad-cli из образа KiCad 9.0. Сверяет _verify/docs205_check.py.

Как это называется в документации

Оригинал	Перевод
engineering change order (ECO)	извещение об изменении: что, где и почему меняется
changelog, revision history	журнал изменений: история ревизий документа
assembly drawing	сборочный чертёж: вид платы с позициями деталей
title block	основная надпись: штамп с обозначением, названием и ревизией
manufacturer part number (MPN)	артикул производителя: конкретное исполнение детали
board revision (rev A, rev B…)	ревизия платы: версия железа одного изделия
form, fit and function	«форма, посадка, функция»: критерий, нужен ли новый номер
as-built	«как собрано»: документация фактического исполнения экземпляра
nameplate	шильдик: табличка с моделью, серийным номером и датой выпуска

205.1 Кто читает комплект: четыре читателя и вы через год

Документацию пишут не «для порядка», а для конкретных читателей, и ни один из них не может переспросить автора:

• завод — собирает по архиву из 199.1 ровно то, что в архиве, и ничего из переписки;
• сборщик и настройщик — ставит плату в корпус, прошивает и калибрует по инструкции, а не по памяти;
• ремонтник — через три года ищет схему, номиналы и назначение перемычек у прибора, который «не включается»;
• заказчик — читает паспорт и руководство: что это, как подключить, что оно гарантирует;
• вы через год — главный читатель. Автор забывает собственные решения быстрее, чем кончается гарантия.

Отсюда единственное правило, из которого выводится всё остальное: изделие определяется документами, а не экземпляром на столе. Если плата отличается от документации — неправа плата: либо её приводят к документам, либо документы честно меняют по 205.6. Прибор, который существует только в виде «вот эта, работающая», повторить нельзя.

205.2 Состав комплекта: что описывает изделие

Отечественная традиция сведена в систему конструкторской документации — ЕСКД; для мелкой серии важны не её формальности, а смысл: у каждой стороны изделия — свой документ со своим шифром. Минимальный комплект прибора на микроконтроллере:

Спецификация — корень: она перечисляет всё, из чего изделие состоит, включая остальные документы. К конструкторскому комплекту примыкает производственный архив из 199.1 — Gerber, сверловка, файл установки: это выгрузки из проекта платы, замороженные на конкретную ревизию, а не самостоятельные документы.

🔧 Минимум для серии в десятки штук. Схема, перечень и сборочный чертёж — PDF с датой и ревизией; спецификация — таблица; паспорт и руководство — по странице-две. Шесть файлов, вечер работы — и изделие перестаёт зависеть от вашей памяти. Всё, что меньше этого, — ещё макет.

205.3 Обозначения: децимальный номер и честная замена ему

Чтобы документы ссылались друг на друга, у изделия должно быть обозначение — имя, которое не меняется от ревизии к ревизии. Классическая схема — децимальный номер: АБВГ.123456.007 (классификационная характеристика здесь условная). Читается по полям:

• АБВГ — четырёхбуквенный код организации-разработчика;
• 123456 — шесть цифр классификационной характеристики: класс, подкласс, группа, подгруппа, вид — «что это за вещь» по классификатору;
• 007 — трёхзначный порядковый номер внутри характеристики.

Итого 13 знаков плюс две точки (прогон doc_calc.py); документы изделия получают то же обозначение с шифром на конце: АБВГ.123456.007 Э3 — схема, …СБ — сборочный чертёж. Одно изделие — один корень, и любой документ по обозначению находится без поиска по папкам.

Для мелкой серии без конструкторского отдела честнее не имитировать классификатор, которого у вас нет, а завести свою систему с теми же свойствами — уникальность, неизменность, шифр документа в конце:

ТМ10-021-Э3  rev B
ТМ10   код изделия: ваш прибор
021    номер в реестре: выдан один раз и навсегда
Э3     шифр документа: словарь тот же, что в таблице 205.2
rev B  ревизия документа

Правила, которые делают систему системой: реестр номеров — один файл в репозитории (таблица «номер — что это — кто выдал — когда»); номер выдаётся один раз и не переиспользуется, даже если изделие умерло; трёх цифр хватает на 999 позиций — исчерпать реестр мелкой серией не получится (прогон doc_calc.py).

⚠️ Имя файла — не обозначение. Файлы переименовывают, копируют в final_v2_new, теряют при переезде на другой диск. Обозначение и ревизия живут в самом документе — в основной надписи (штампе) чертежа, в шапке таблицы, на шелкографии платы — и только копией в имени файла.

205.4 Ревизии платы и изделия

Ревизия — состояние изделия под тем же обозначением. Правило границы: пока экземпляры взаимозаменяемы по «форме, посадке и функции», это ревизии одного изделия; как только старый и новый экземпляр нельзя менять местами — это новое изделие с новым номером, а не «rev F».

Что считать новой ревизией платы — любое изменение, после которого завод изготовит другую плату: правка меди, сверловки, контура, посадочных мест. Замена номинала или артикула без правки меди — ревизия перечня (вариант сборки): плата та же, состав другой. Отсюда три независимых счётчика — у платы, у перечня, у прошивки, — и все три записываются в журнал выпуска экземпляра (201.7).

Метку ревизии наносят на саму плату — шелкографией в свободном углу: обозначение платы и rev B. Плата без метки через год неотличима от соседней; класть рядом две «одинаковые» платы разных ревизий — способ потерять день на «у меня другая распиновка». Правила совместимости ревизий пишут в журнал изменений явно: «rev C взаимозаменяема с rev B; rev A требует прошивку не выше 1.х».

⚠️ Ревизия платы и ревизия изделия — разные оси. Прибор rev 2 может собираться на плате rev C с перечнем rev D и прошивкой 2.3.1. Попытка свести всё к одному номеру кончается тем, что номер перестаёт значить что-либо. Оси связывает журнал выпуска: серийный номер экземпляра → какие ревизии в нём стоят.

205.5 Версия прошивки и ревизия платы

Прошивка — тоже часть изделия, и у неё те же вопросы совместимости. Пока плата одна, версия прошивки просто растёт; со второй ревизии платы появляется матрица «прошивка × плата», и её надо вести явно:

Матрица живёт в журнале изменений прошивки, но полагаться на людей нельзя: прошивка должна сама узнавать ревизию платы. Дешевле всего — перемычками: три свободных входа с внутренней подтяжкой вверх и три места под резисторы 0 Ом на землю. На rev A не запаяно ничего, дальше каждая ревизия получает свой код: пустое место читается единицей, запаянное — нулём.

🔧 Чтение ревизии и проверка совместимости (board_rev.c; REV_IDR на F1 — это GPIOB->IDR, в прогоне на ПК вместо порта — переменная):

enum { REV_SHIFT = 12 };                   /* PB12, PB13, PB14: подтяжка вверх */

uint32_t board_rev(void)                   /* 0 = rev A, 1 = rev B, ... 7 = rev H */
{
    uint32_t raw = (REV_IDR >> REV_SHIFT) & 7u;
    return ~raw & 7u;                      /* запаянная перемычка тянет вход в 0 */
}

enum { FW_REV_MIN = 1, FW_REV_MAX = 3 };   /* эта сборка прошивки знает rev B..D */

int rev_supported(uint32_t rev)            /* при отказе — безопасный режим + журнал */
{
    return rev >= FW_REV_MIN && rev <= FW_REV_MAX;
}

Прогон перебирает все восемь кодов; крайние строки:

входы PB14..PB12 = 111 -> rev 0 (A) НЕ поддерживается: стоп
входы PB14..PB12 = 101 -> rev 2 (C) поддерживается
входы PB14..PB12 = 000 -> rev 7 (H) НЕ поддерживается: стоп

Для Cortex-M3 весь механизм — 32 байта кода и ни байта ОЗУ (сборка в stm-arm:1, прогон board_rev_host.txt). Три перемычки дают 2³ = 8 ревизий, четыре — 16; если жалко трёх выводов, ту же работу делает один вход АЦП с резистивным делителем: при шаге уровней 0,3 В помещается 12 кодов, а худший уход делителя из резисторов ±1 % — ±16,5 мВ, в девять раз меньше полушага (прогон doc_calc.py). Читают код один раз при старте; чужая ревизия — это безопасный режим и запись в журнал, а не попытка угадать распиновку.

Версию прошивки, ревизию платы и серийный номер (201.5) полезно отдавать наружу — в стартовую строку UART, в регистр телеметрии, в ответ на команду «кто ты»: половина «полевых чудес» решается, когда прибор сам говорит, что в нём стоит.

205.6 Изменения: журнал и извещение

Каждый документ несёт журнал изменений — таблицу в самом документе:

Одно изменение почти никогда не трогает один документ: поменяли номинал — правится схема, перечень и, возможно, калибровка; передвинули разъём — сборочный чертёж, гербер и корпус. Связку фиксирует извещение об изменении — по смыслу ЕСКД: короткий документ «что меняем, почему, какие документы и с какой ревизии затронуты, что делать с заделом» — с плат старой ревизии на складе: дорабатывать, ставить со старой прошивкой или списать. Номер извещения (И-012) появляется в журнале каждого затронутого документа — по нему изменение прослеживается целиком.

⚠️ «Тихих» правок не бывает. Подпаять резистор на плате и не записать — значит породить экземпляр, которого нет в документации: следующая партия уедет на завод без правки, а ремонтник будет чинить прибор по схеме, которой прибор не соответствует. Любое отличие железа от документов — либо брак железа, либо новая ревизия документов; третьего состояния нет. Для единичной доработки экземпляра честный выход — запись «как собрано» в журнале выпуска этого серийника.

205.7 Паспорт и руководство

Паспорт — документ конкретного экземпляра, и минимум в нём такой: модель и обозначение; заводской серийный номер — тот же, что в журнале выпуска (201.7) и в памяти камня (201.5); дата выпуска; основные параметры (питание, потребление, диапазоны); комплектность; условия эксплуатации и хранения; гарантия и отметка контроля. Одной-двух страниц достаточно, но серийный номер и дата обязательны: без них прибор из ремонта нельзя связать ни с партией, ни с калибровкой (202.5).

Руководство — документ модели: как подключить (разъёмы и распиновка глазами пользователя), как включить и что означает индикация, режимы работы, характеристики, что делать при типовых отказах и чего делать нельзя. Пишется для читателя из 205.1, который не может переспросить: проверка качества руководства — дать прибор и текст человеку со стороны и молчать, пока он подключает.

Шильдик на корпусе — младший брат паспорта: модель, серийный номер, дата, питание. Прибор, переживший паспорт, — норма жизни; шильдик остаётся единственной ниточкой к журналу выпуска, поэтому серийник на корпусе дублирует паспортный всегда.

205.8 Хранение: git для железа и выгрузки с датой

Исходники изделия — проект схемы и платы, прошивка, тексты документов, реестр обозначений — живут в git так же, как код (35б — та же философия: всё из командной строки, всё повторяемо). Выпуск ревизии — это тег: TM10-rev-B на состоянии репозитория, из которого сделаны файлы для завода. Вопрос «из чего собрана партия марта?» превращается в git checkout вместо археологии по папкам final_v2.

Но git хранит исходники, а читатели из 205.1 работают с выгрузками: завод — с гербером, ремонтник — с PDF схемы. Поэтому рядом с тегом замораживают каталог выпуска: архив производства из 199.1 плюс PDF схемы и чертежа, у каждого в штампе — обозначение, ревизия и дата. Выгрузку делает та же командная строка, что в 132в и 199:

kicad-cli sch export pdf -o out/TM10-021-E3-revB.pdf board.kicad_sch

🔧 Ревизия в штамп — из скрипта. У kicad-cli есть ключ --define-var KEY=VALUE, подставляющий переменные проекта при выгрузке: скрипт выпуска пишет в штамп ревизию и дату сам, и в PDF не бывает «забыл поправить рамку» (ключи — в kicad_pdf_host.txt).

PDF с датой в штампе — это и страховка формата: проект CAD десятилетней давности может не открыться новой версией программы, а PDF и Gerber останутся читаемыми. Правило простое: исходники — в git с тегами, на каждый выпуск — замороженные выгрузки, которые читаются без CAD.

205.9 Грабли

На складе две платы с меткой «rev B» — ведут себя по-разному. Тихая правка: медь перегенерили, метку не сменили. Любое изменение геометрии платы — новая ревизия с новой шелкографией; правка без записи в журнал запрещена самой дешёвой ценой — привычкой.

Обновление прошивки положило половину парка приборов. Версия 2.0 молча предположила плату rev C, а в поле половина парка — rev B. Прошивка обязана читать ревизию сама: три перемычки, 32 байта кода (205.5) — и чужое железо встречает безопасный режим, а не угадывание.

Завод собрал партию по перечню на одну правку старше схемы. Изменение внесли в схему, перечень забыли: извещение перечисляет все затронутые документы, а на завод уходит один архив одной ревизии (199.1), а не файлы «из переписки».

Обозначение переиспользовали — под одним именем живут два изделия. Старый прибор умер, номер отдали новому, и теперь в ремонте, на складе и в переписке 021 — это два разных устройства. Номер выдаётся один раз и навсегда; реестр — один файл, выдача — только через него.

Через два года исходник платы не открывается. Формат CAD ушёл вперёд, плагин умер, лицензия кончилась. Спасают замороженные выгрузки выпуска: Gerber, PDF схемы и чертежа с датой и ревизией в штампе — они читаются без CAD и через десять лет (205.8).

Паспорт есть, а серийного номера в нём нет. Прибор вернулся из поля — и его не связать ни с журналом выпуска (201.7), ни с партией плат, ни с калибровкой (202.5): ремонт начинается с «а что это у нас». Серийник — в паспорте, на шильдике и в камне (201.5), и это один и тот же номер.

205.10 Итоги

• Изделие определяется документами, а не экземпляром: минимальный комплект — схема Э3, перечень ПЭ3, сборочный чертёж СБ, спецификация, паспорт, руководство — шесть документов плюс производственный архив из 199.1.
• Обозначение — неизменное имя: децимальный номер — 4 буквы + 6 цифр + 3 цифры, 13 знаков; своя система для мелкой серии обязана дать то же: уникальность, реестр в одном файле, номер один раз и навсегда, 999 позиций на трёхзначный счётчик.
• Ревизия — состояние под тем же обозначением, граница — «форма, посадка, функция»; у платы, перечня и прошивки счётчики независимые, связывает их журнал выпуска по серийному номеру.
• Прошивка читает ревизию платы сама: три перемычки = 8 кодов, 32 байта кода и 0 байт ОЗУ на Cortex-M3; делитель на один вход АЦП — 12 уровней при шаге 0,3 В против худшего ухода ±16,5 мВ.
• Изменение — это запись: журнал в каждом документе, извещение связывает документы одной правки, «тихих» правок не бывает.
• Исходники — в git с тегом на выпуск, рядом — замороженные выгрузки: Gerber и PDF с ревизией и датой в штампе (kicad-cli sch export pdf с --define-var — прямо из скрипта выпуска).

Полные исходники

board_rev.c — как прошивка узнаёт ревизию платы.

/* Раздел 205.5: как прошивка узнаёт ревизию платы.
 *
 * На плате: три свободных входа с внутренней подтяжкой вверх и три
 * места под резисторы-перемычки 0 Ом на землю. На rev A не запаяно
 * ничего, на каждой следующей ревизии запаивается свой код. Не
 * запаяно — вход читается единицей, запаяно — нулём.
 *
 * Здесь, на компьютере, вместо порта — переменная fake_idr, и прогон
 * перебирает все восемь кодов.
 *
 * Сборка на ПК:  gcc -O2 -Wall -Wextra -o board_rev board_rev.c && ./board_rev
 * Для кристалла: arm-none-eabi-gcc -mcpu=cortex-m3 -mthumb -O2 -DNO_HOST_TEST -c board_rev.c
 */
#include <stdint.h>
#ifndef NO_HOST_TEST
#include <stdio.h>
static uint32_t fake_idr;
#define REV_IDR fake_idr
#else
#define REV_IDR (*(volatile uint32_t *)0x40010C08u)  /* GPIOB->IDR на F1 */
#endif

enum { REV_SHIFT = 12 };                   /* PB12, PB13, PB14: подтяжка вверх */

uint32_t board_rev(void)                   /* 0 = rev A, 1 = rev B, ... 7 = rev H */
{
    uint32_t raw = (REV_IDR >> REV_SHIFT) & 7u;
    return ~raw & 7u;                      /* запаянная перемычка тянет вход в 0 */
}

enum { FW_REV_MIN = 1, FW_REV_MAX = 3 };   /* эта сборка прошивки знает rev B..D */

int rev_supported(uint32_t rev)            /* при отказе — безопасный режим + журнал */
{
    return rev >= FW_REV_MIN && rev <= FW_REV_MAX;
}

#ifndef NO_HOST_TEST
int main(void)
{
    printf("== сборка на ПК: без предупреждений\n");
    printf("прошивка объявляет: знаю rev %d..%d (B..D)\n", FW_REV_MIN, FW_REV_MAX);
    for (uint32_t raw = 7;; raw--) {       /* от «ничего не запаяно» к «запаяны все» */
        fake_idr = raw << REV_SHIFT;
        uint32_t rev = board_rev();
        printf("входы PB14..PB12 = %u%u%u -> rev %u (%c) %s\n",
               (raw >> 2) & 1u, (raw >> 1) & 1u, raw & 1u, rev, 'A' + (int)rev,
               rev_supported(rev) ? "поддерживается" : "НЕ поддерживается: стоп");
        if (raw == 0)
            break;
    }
    return 0;
}
#endif

Дальше: раздел 205а «Документы по ЕСКД на прибор» — коды документов, схема Э3 и перечень элементов ПЭ3 из KiCad.