templates/tools/firmware-build/README.md

Подключение precompile и postcompile из templates

Для проектов ПЛИС используйте шаблон Xilinx ISE, Vivado и Altera/Intel Quartus: общий сохраняемый итератор, паспорт на Verilog/VHDL, полная сборка .bit/.sof, manifest, SHA-256 и архив выпуска.

Единая подготовка C2000 для 166/167 и Публикатора SETGUI

Общая точка входа — c/firmware-info/tools/c2000_build.py с командами prepare и build. CCS и совместимые ccs/precompile.bat --identity / ccs/postcompile.bat --identity вызывают один процесс подготовки.

prepare сохраняет JSON-счётчик старых проектов 166 либо читает ручную версию из заголовка, заданного в firmware_build_profile.json проекта 167. Аппаратный профиль содержит пути C-заголовков, имена макросов EEPROM и допустимые RAM-адреса в 16-битных словах C28x. Ёмкость и размер SCI8 выражены в октетах.

build проверяет встроенный паспорт, границу EEPROM, MAP, SHA-256, полноту SCI8, Flash LOAD/RUN и точное соответствие Flash OUT ↔ Flash RS BIN до сохранения постоянного выпуска. Проектный build_flash.py остаётся аппаратным сборщиком; общих проверок или сетевых операций в нём нет.

В текущей 167 каталог результата задан как Debug/firmware/prepared либо Release/firmware/prepared; в остальных проектах он задаётся аргументом --output. В этом каталоге создаётся папка HASH_дата_UTC+3 с RAM BIN, исходным RAM OUT, *_flash.out для JTAG, *_flash_rs.bin для RS, картами, manifest и SHA-256. Flash-файлы создаются только при наличии проектного build_flash.py. latest_build.json рядом с папками указывает точную папку и основной manifest последнего успешного выпуска.

Дальнейшая публикация выполняется в SETGUI: Сервис → Прошивка → Публикатор → Из папки postbuild / manifest → Импорт папки postbuild. Выбирайте папку одной сборки, указанную в latest_build.json. Для Flash по RS выбирайте manifest *_flash_rs.bin.manifest.json; для JTAG можно выбрать основной RAM BIN manifest, поскольку полный комплект содержит подписанный Flash OUT. Публикатор выбирает Flash OUT по execution=FLASH и image_format=COFF, сохраняя соседний RAM OUT. Проверьте назначение загрузчика и предпросмотр, затем публикуйте через штатное хранилище Публикатора. Команды подготовки сами не создают сетевой выпуск.

Ниже сохранены команды подключения старых проектов. Дополнительный аргумент export остаётся совместимым локальным копированием; новые проекты могут передавать готовый комплект прямо Публикатору без этого аргумента.

Пути на этом компьютере

Самостоятельные постоянные CAN-загрузчики F28335_CAN_AB и F2812_CAN_NOR имеют собственные prebuild/postbuild в Debug и Release. Они вызывают общий c/protocan-boot/projects/build.py, проверяют Flash COFF через TI ofd2000 и автоматически копируют OUT/MAP, manifest, SHA-256 и метаданные в SETGUI/..periph_28335/firmware/periph28335/balzam167/canboot/28335/HASH_дата_UTC+3 и .../canboot/2812/HASH_дата_UTC+3 соответственно. Команды, переопределение пути и структура результата описаны в инструкции CCS-проектов ProtoCAN Boot.

Назначение	Полный путь
Корень общей библиотеки templates	K:\git_project\newProject\templates
Сценарии CCS	K:\git_project\newProject\templates\tools\firmware-build\ccs
Сценарии Keil	K:\git_project\newProject\templates\tools\firmware-build\keil
Проект Бальзам-166 / TMS320F28335	K:\git_project\28335_periph\UKSSTMS320F28335
Каталог сборок Бальзам-166 в SETGUI	K:\git_project\newProject\SETGUI\..periph_28335\firmware\periph28335\balzam166

Все команды ниже используют эту копию templates. При переносе библиотеки замените её корень в командах и в include paths компилятора. ${PROJECT_LOC}, ${BuildDirectory}, ${CG_TOOL_ROOT} и ${BuildArtifactFileBaseName} раскрывает CCS; $P и #H раскрывает Keil. Для ручного запуска замените макросы полными путями.

В пути SETGUI ..periph_28335 — существующее имя папки с двумя точками в начале. Переход к родителю записывается отдельным компонентом ..\.

Текущий проект 28335_periph: вызов через firmware_build.bat

Для проекта K:\git_project\28335_periph\UKSSTMS320F28335 используйте локальную обвязку. Она вызывает общие BAT из templates; общий генератор увеличивает версию в проектном JSON. Перед публикацией обвязка дополнительно проверяет встроенный паспорт SCI8 и предел EEPROM.

В CCS → Project Properties → Build → Steps задайте для Debug и Release следующие команды, каждую одной строкой.

Pre-build:

cmd /c call "${PROJECT_LOC}/firmware_build.bat" prepare --build-dir "${BuildDirectory}"

Post-build:

cmd /c call "${PROJECT_LOC}/firmware_build.bat" build --compiler "${CG_TOOL_ROOT}" --build-dir "${BuildDirectory}" --artifact "${BuildArtifactFileBaseName}"

Настройки находятся в K:\git_project\28335_periph\UKSSTMS320F28335\firmware_identity.json:

Поле	Рабочее значение и смысл
templates	../../newProject/templates; разрешается относительно папки JSON в K:\git_project\newProject\templates. Абсолютный эквивалент: K:/git_project/newProject/templates.
copy_to	../Bin; копирует проверенные BIN, manifest, SHA-256, HEX и карту в K:\git_project\28335_periph\Bin.
increment_version	true; каждый pre-build резервирует следующий номер в поле version.
max_image_bytes	32508; предельный размер SCI8 BIN в байтах для этой платы.

В JSON используйте / либо удваивайте обратные слеши. copy_to принимает также абсолютный путь, например K:/git_project/newProject/SETGUI/..periph_28335/firmware/periph28335/balzam166. Эта настройка копирует отдельные файлы комплекта. Архивные папки остаются в ${BuildDirectory}/firmware.

firmware_build.bat build принимает именованные параметры. Дописывание каталога после --artifact вызывает unrecognized arguments; для этой обвязки каталог копирования задаётся полем copy_to.

Include paths компилятора для текущего проекта:

Запись в CCS	Реальный каталог для Debug
${SRC_ROOT}/../newProject/templates/c/firmware-info/include	K:\git_project\newProject\templates\c\firmware-info\include
${SRC_ROOT}/../newProject/templates/c/set-protocol	K:\git_project\newProject\templates\c\set-protocol
${BuildDirectory}/generated	K:\git_project\28335_periph\UKSSTMS320F28335\Debug\generated

${SRC_ROOT} в этом проекте равен K:\git_project\28335_periph. При переносе templates обновите и JSON, и include paths в CCS. Подробная инструкция проекта: README Бальзам-166.

Готовый BIN ищите по строке [firmware-build] Verified BIN: .... Постоянный каталог Debug: K:\git_project\28335_periph\UKSSTMS320F28335\Debug\firmware. Папки .identity-release-... временные и удаляются после проверки.

Прямое подключение общих BAT к новому CCS-проекту

Следующие разделы описывают прямые вызовы ccs/precompile.bat и ccs/postcompile.bat. В этом варианте дополнительный последний аргумент postcompile поддерживается и экспортирует целиком папку текущей сборки. Общий генератор увеличивает версию прямо при вызове precompile, если в JSON задано "increment_version": true. Отсутствующий флаг или false сохраняет ручной режим.

Итератор общий для CCS, Keil и CLI; проектная обёртка не должна увеличивать номер повторно.

Каждый pre-build атомарно сохраняет следующий номер до генерации паспорта, включая попытки с последующей ошибкой. После patch 999 увеличивается minor, после minor 255 — major; младшие поля обнуляются. После 255.255.999 сборка останавливается. Clean не сбрасывает JSON; одновременные сборки с одним JSON не поддерживаются. Выберите одну схему подключения: её pre-build и post-build должны использовать один набор метаданных.

Новый CCS-проект C2000: локальные версия и SCI8 BIN

Используйте обновлённую папку templates целиком. Режим --identity добавлен для нового проекта: Windows, Python 3.8+ в PATH и TI C2000 compiler с hex2000.exe. Git в PATH нужен для хеша коммита. Без Git либо без commit в проекте или templates используется NOGIT000; сборка и локальная конвертация разрешены. Это явно видно в manifest. SETGUI и доступ к серверу не требуются.

1. Создайте конфигурацию версии

При первом запуске pre-build автоматически копирует ccs/firmware_identity.example.json в путь конфигурации из команды (обычно ${PROJECT_LOC}/firmware_identity.json, рядом с .project), если файла ещё нет. Существующий JSON не заменяется примером; при включённом итераторе в нём обновляется версия. После первого запуска откройте его, задайте свои product, target и version и пересоберите проект. Исходные значения примера перед первым запуском:

{
  "product": "MY_CONTROLLER",
  "target": "TMS320F28335",
  "version": [0, 1, 0],
  "increment_version": true
}

Задайте своё изделие, настоящий контроллер и нужную версию. Для TMS320F2812 замените target. Начальный счётчик примера — 0.1.0; при включённом итераторе первый pre-build выдаёт 0.1.1. Этот JSON — единственное вручную редактируемое место версии в данной схеме.

2. Добавьте команды в CCS

Project Properties → Build → Steps, для нужной конфигурации. Пример предполагает templates в K:\git_project\newProject\templates. Замените только этот путь своим; макросы CCS оставьте как есть.

Pre-build steps → Command, одной строкой:

cmd /c call "K:\git_project\newProject\templates\tools\firmware-build\ccs\precompile.bat" --identity "${PROJECT_LOC}" "${PROJECT_LOC}\firmware_identity.json" "${BuildDirectory}\generated"

Post-build steps → Command, одной строкой:

cmd /c call "K:\git_project\newProject\templates\tools\firmware-build\ccs\postcompile.bat" --identity "${CG_TOOL_ROOT}" "${BuildDirectory}" "${BuildArtifactFileBaseName}" "${BuildDirectory}\generated\firmware_identity.json" "${BuildDirectory}\firmware"

Позиционные аргументы общего ccs/postcompile.bat после --identity:

Позиция	Значение	Источник в CCS
1	Корень TI C2000 compiler, содержащий bin/hex2000.exe	${CG_TOOL_ROOT}
2	Каталог текущей конфигурации сборки	${BuildDirectory}
3	Имя или путь OUT без расширения .out	${BuildArtifactFileBaseName}
4	Метаданные, созданные pre-build	${BuildDirectory}\generated\firmware_identity.json
5	Постоянный каталог результатов	${BuildDirectory}\firmware
6, необязательно	Каталог экспорта архивной папки текущей сборки	Полный путь назначения

Здесь templates определяется расположением вызываемого общего BAT. Для прямой схемы поле templates в JSON не заменяет путь в команде CCS. Добавьте ${BuildDirectory}/generated в include paths; при подключении общего порта firmware-info добавьте K:/git_project/newProject/templates/c/firmware-info/include.

Нужны оба шага. Precompile создаёт версию, UTC-время и Git-метаданные до компиляции. Postcompile преобразует OUT в SCI8 HEX/BIN, создаёт manifest и SHA-256 для точного BIN. Он не повторяет запрос Git после компиляции. В этом режиме firmware-release.cmd не нужен.

BuildArtifactFileBaseName передаётся без изменения и без расширения .out: допускается простое имя, абсолютный путь или путь относительно BuildDirectory. Postcompile находит OUT по этому пути, а для имён BIN/HEX использует только имя файла. Поэтому отдельная выходная папка проекта (например, ../bin) не требует правки общей команды. Метаданные и результаты остаются в указанных каталогах generated и firmware.

3. Выполните полную сборку

Apply and Close → Clean → Build Project. Настройте шаги отдельно для Debug/Release; их generated и firmware находятся внутри своих BuildDirectory.

Результаты:

Debug/
  generated/
    firmware_identity.h
    firmware_identity.json
  firmware/
    MyFirmware.hex
    MyFirmware_BUILDID.bin
    MyFirmware_BUILDID.bin.manifest.json
    MyFirmware_BUILDID.bin.sha256
    HASH_YYYY-MM-DD_HH-MM-SS_UTC+3/
      MyFirmware.hex
      MyFirmware_BUILDID.bin
      MyFirmware_BUILDID.bin.manifest.json
      MyFirmware_BUILDID.bin.sha256
      firmware_identity.json

Postcompile автоматически создаёт папку HASH_YYYY-MM-DD_HH-MM-SS_UTC+3 для каждой сборки. HASH — первые 8 символов commit прошивки из pre-build JSON; при незакоммиченных изменениях добавляется +. Дата и время берутся из built_at_utc и переводятся в UTC+3 для имени папки. В JSON и заголовке сохраняется UTC. Если commit исходников неизвестен, используется build ID или NOGIT000. Например: f5c3654e+_2026-10-08_15-30-00_UTC+3. Сохраняются точные байты образа, manifest, SHA-256 и firmware_identity.json; в CCS также исходный OUT, HEX и map. Повтор postcompile с теми же метаданными обновляет ту же папку. Файлы непосредственно в firmware сохраняются, поэтому существующие команды копирования продолжают работать. Добавьте generated и firmware в игнорируемые Git-каталоги. Обычно вся папка Debug уже игнорируется. Полный Rebuild обязателен для выпуска. BAT сами по себе не подтверждают, что OUT собран именно с этим заголовком.

4. Прямой postcompile: копирование папки текущей сборки в SETGUI

При прямом вызове общего ccs/postcompile.bat передайте каталог назначения последним аргументом после output-dir. Это правило относится к общему BAT; проектный firmware_build.bat использует copy_to из JSON. Скрипт скопирует целиком только папку HASH_DATE, созданную текущим запуском: исходный OUT (для CCS), BIN, HEX, map, manifest, SHA-256 и метаданные. OUT сохраняется с исходным именем для выбора и загрузки через JTAG в GUI. Скрипт использует папку из pre-build JSON, не выбирает её по времени изменения файлов и не копирует остальные архивы или отдельные файлы из корня firmware.

Полная команда Post-build для templates в K:\git_project\newProject\templates, одной строкой:

cmd /c call "K:\git_project\newProject\templates\tools\firmware-build\ccs\postcompile.bat" --identity "${CG_TOOL_ROOT}" "${BuildDirectory}" "${BuildArtifactFileBaseName}" "${BuildDirectory}\generated\firmware_identity.json" "${BuildDirectory}\firmware" "K:\git_project\newProject\SETGUI\..periph_28335\firmware\periph28335\balzam166"

Старые суффиксы && copy ... и && xcopy ... удалите. Папка назначения создаётся автоматически. В ней появится, например:

K:\git_project\newProject\SETGUI\..periph_28335\firmware\periph28335\balzam166\
  f5c3654e+_2026-10-08_15-30-00_UTC+3\
    MyFirmware.hex
    MyFirmware_BUILDID.bin
    MyFirmware_BUILDID.bin.manifest.json
    MyFirmware_BUILDID.bin.sha256
    firmware_identity.json

Копирование выполняется после успешного архивирования; SHA-256 копии проверяется. Console покажет [firmware-build] Exported folder: .... Повтор для той же папки обновляет её файлы; другие папки назначения сохраняются. Без последнего аргумента экспорт отключён. Это локальное копирование без сетевой публикации.

Дополнительный Flash OUT из postbuild CCS

Если рядом с CCS-проектом, на уровень выше BuildDirectory, есть build_flash.py, общий postbuild автоматически вызывает его с --postbuild, --compiler, --build-dir и --output. Команда postcompile в настройках CCS остаётся прежней. Сценарий проекта должен использовать уже готовые объекты, не запускать Make и создать непустые <имя>_flash.out и <имя>_flash.map по переданному пути. Адреса секций, отдельный linker-файл и необходимые определения препроцессора задаёт проектный сборщик, а не общий templates.

Flash OUT и карта сохраняются рядом с обычным OUT. Копии, отдельный manifest и SHA-256 попадают в firmware и ту же папку HASH_DATE, что и EEPROM BIN, а затем копируются в GUI при настроенном export. Обычный BIN по-прежнему создаётся из основного OUT; Flash OUT не преобразуется в EEPROM SCI8 BIN. Ошибка сборщика или отсутствие любого результата завершает postcompile с ненулевым кодом до архивирования и экспорта. Существующий Flash OUT не считается результатом нового вызова: сборщик работает во временном каталоге. Без build_flash.py дополнительные действия отключены.

Дополнительно hex2000 преобразует Flash OUT в отдельный <имя>_flash_rs.bin с адресной таблицей SCI8, картой .bin.map, manifest и SHA-256. Эти файлы сохраняются рядом с OUT, в firmware и в экспортируемой папке HASH_DATE. Flash RS BIN содержит адреса внутренней Flash и предназначен для совместимого проектного CMD_TFLASH; его нельзя выбирать как обычный EEPROM BIN. Проект сам должен реализовать проверку адресов и алгоритм программирования из RAM. Общий postbuild только формирует транспортный файл.

Версия внутри устройства

Это подготовка метаданных сборки и файла. Чтобы версия присутствовала в программе и ответах устройства, подключите заголовок firmware_identity.h к модулю версии и обработчику запроса. Include path: ${BuildDirectory}/generated. Для C2000 с 16-битным char нужна адаптация байтового контракта; обычный 8-битный порт нельзя считать готовым. Смотрите PORTING.md.

Keil: тот же JSON, заголовок и SHA-256

Keil использует firmware_identity.json и режим --identity, как CCS. Дополнительный CMD-файл конфигурации и SETGUI для этой схемы не нужны. Требуется Python 3.8+ в PATH; Git нужен для commit. HEX создаётся штатным компилятором Keil, а BAT создаёт и проверяет manifest и SHA-256 точного HEX/BIN.

1. Создайте конфигурацию версии

Пример расположения:

project/
  firmware_identity.json
  mdk/
    Firmware.uvprojx
    Generated/

Скопируйте keil/firmware_identity.example.json в корень project под именем firmware_identity.json. Исправьте product, target и version:

{
  "product": "MY_CONTROLLER",
  "target": "STM32F407",
  "version": [0, 1, 0],
  "increment_version": true
}

2. Настройте Before/After Build

В Options for Target → Output включите Create HEX File. Затем откройте User и включите выполнение команд Before Build/Rebuild и After Build/Rebuild. Для обеих команд задайте Stop on Exit Code >=1, чтобы ошибка скрипта останавливала сборку. Пример предполагает templates в K:\git_project\newProject\templates; замените этот путь своим.

Before Build/Rebuild, одной строкой:

cmd /c call "K:\git_project\newProject\templates\tools\firmware-build\keil\precompile.bat" --identity "$P.." "$P..\firmware_identity.json" "$PGenerated"

After Build/Rebuild, одной строкой:

cmd /c call "K:\git_project\newProject\templates\tools\firmware-build\keil\postcompile.bat" --identity "#H" "$PGenerated\firmware_identity.json"

Для копирования только папки текущей сборки добавьте каталог назначения последним аргументом:

cmd /c call "K:\git_project\newProject\templates\tools\firmware-build\keil\postcompile.bat" --identity "#H" "$PGenerated\firmware_identity.json" "K:\git_project\newProject\SETGUI\..periph_28335\firmware\periph28335\balzam166"

Будет скопирована целиком новая папка HASH_DATE с HEX/BIN, manifest, SHA-256 и метаданными. Старые команды copy/xcopy в этой строке не нужны. В Console появится [firmware-build] Exported folder. В Keil $P обозначает каталог проекта с завершающим разделителем, а #H — полный путь к выходному HEX. Официальное описание макросов: Keil User commands. Макросы раскрываются в IDE; при ручном запуске BAT замените их реальными путями.

В примере файл uvprojx находится в mdk, поэтому $P.. указывает на корень исходников. Если JSON и uvprojx находятся в одном каталоге, используйте "$P." для repository и "$Pfirmware_identity.json" для config; третий аргумент Generated сохраните.

Добавьте Generated в include path и подключите firmware_identity.h в модуле версии прошивки. Для параллельных или разных target задавайте отдельные Generated и согласуйте путь во второй команде. Перенос версии в ответ устройства требует подключения модуля и обработчика, как описано в PORTING.md.

3. Выполните Rebuild

Перед выпуском измените только исходный firmware_identity.json и выполните Rebuild. Precompile создаст заголовок и метаданные в Generated. Postcompile создаст рядом с HEX:

Firmware.hex
Firmware.hex.manifest.json
Firmware.hex.sha256
firmware/
  HASH_YYYY-MM-DD_HH-MM-SS_UTC+3/
    Firmware.hex
    Firmware.hex.manifest.json
    Firmware.hex.sha256
    firmware_identity.json

Папка HASH_DATE создаётся в firmware рядом с исходным HEX/BIN. Для неё используются commit и время precompile, переведённое в UTC+3, как в CCS. При успехе Console содержит строки [firmware-build] Folder, Image, Manifest, SHA-256. Для готового BIN вместо #H передайте его фактический путь; конвертацию AXF в BIN нужно выполнить до postcompile. Сгенерированные файлы исключите через .gitignore.

Совместимость со старыми проектами

Вызовы BAT без --identity сохранены для уже настроенных проектов: прежний precompile генерирует только build ID, прежний postcompile запускает SETGUI preflight по release-конфигурации. Эта отдельная схема описана в инструкции публикатора. Для новых CCS и Keil используйте приведённые выше команды с --identity.

Автоматический CAN BIN вместе с Flash

Защищённый c/firmware-info/tools/c2000_build.py build, вызываемый из CCS postbuild и postcompile.bat --identity, дополнительно создаёт CAN-вариант, если проект явно задаёт can_boot_profile равным f28335-m95m02-ab в firmware_build_profile.json и выбрана EEPROM M95M02. Для AT25256B этот A/B-профиль отключён. Старые проекты без поля сохраняют прежний состав выпуска. Изменение CAN-профиля требует нового prebuild и сборки.

В одном выпуске сохраняются:

Файл	Назначение
eeprom/<artifact>_<build_id>.bin	Основной SCI8 RAM/EEPROM-образ
can/<artifact>_<build_id>_can.bin	ProtoCAN Boot, M95M02 A/B, RAM-приложение
flash/<artifact>_flash.out	Внутренняя Flash через JTAG, если проект имеет build_flash.py
rs/<artifact>_flash_rs.bin	Обновление внутренней Flash по RS из того же Flash OUT

CAN BIN содержит точные байты проверенного RAM SCI8. Отдельно проверяются предел 130560 октетов, максимум 64 секции, адреса RAM [0x8000,0xE000), entry, встроенный паспорт и экспортированные CAN hooks Init/Ready/Service/RxISR в загружаемом payload. Flash-таблица не допускается как CAN BIN. Каждый вариант получает собственные manifest и SHA-256. CAN-файл и оба sidecar добавляются в тот же архив сборки и проходят штатный экспорт в GUI. При отказе проверки CAN или обязательного Flash-варианта новая попытка не копируется в постоянный output/export. Сетевая публикация и запись платы этой командой не выполняются.

Защищённый C2000 postbuild располагает образы, их manifest, SHA-256 и карты в папках eeprom, flash, can, rs как непосредственно в --output, так и внутри архива HASH_дата_UTC+3. При --export весь архив переносится в SETGUI с той же структурой. Общий firmware_identity.json остаётся в корне архива; latest_build.json указывает manifest с относительным путём eeprom/<artifact>_<build_id>.bin.manifest.json. Папка неподдержанного варианта не создаётся. Низкоуровневые конверторы и другие семейства MCU сохраняют прежний контракт своих результатов.

В SETGUI можно импортировать корень одной сборки или выбрать её папку eeprom, can, rs. Основной BIN определяется выбранным паспортом, а ZIP сохраняет все назначения этой компиляции. Для JTAG выберите совместимый загрузчик полного комплекта: он возьмёт подписанный OUT из flash. Старые плоские комплекты также поддерживаются.