templates/tools/firmware-build/README.md

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

Новый 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]
}

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

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

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

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

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

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

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

Нужны оба шага. 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 также HEX и map. Повтор postcompile с теми же метаданными обновляет ту же папку. Файлы непосредственно в firmware сохраняются, поэтому существующие команды копирования продолжают работать. Добавьте generated и firmware в игнорируемые Git-каталоги. Обычно вся папка Debug уже игнорируется. Полный Rebuild обязателен для выпуска. BAT сами по себе не подтверждают, что OUT собран именно с этим заголовком.

4. Копирование папки текущей сборки в SETGUI

Передайте каталог назначения последним аргументом postcompile. Скрипт скопирует целиком только папку HASH_DATE, созданную текущим запуском: BIN, HEX, map, manifest, SHA-256 и метаданные. Он использует папку из pre-build JSON, не выбирает её по времени изменения файлов и не копирует остальные архивы или отдельные файлы из корня firmware.

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

cmd /c call "K:\git_project\newProject\newTEMPL\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"

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

K:\git_project\newProject\SETGUI\..periph_28335\firmware\
  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: .... Повтор для той же папки обновляет её файлы; другие папки назначения сохраняются. Без последнего аргумента экспорт отключён. Это локальное копирование без сетевой публикации.

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

Это подготовка метаданных сборки и файла. Чтобы версия присутствовала в программе и ответах устройства, подключите заголовок 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]
}

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

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

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

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

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

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

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

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

Будет скопирована целиком новая папка 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.