Добавить выпуск прошивок из Keil и CCS

tools/firmware-publish/README.md

@@ -0,0 +1,159 @@
+# Публикация прошивки из Keil и CCS 12
+
+Этот комплект связывает проект прошивки с каталогом SETGUI. IDE по-прежнему
+собирает штатный загрузочный файл, а `PUBLISH_FIRMWARE.bat`:
+
+1. читает метаданные выпуска из `firmware-release.cmd`;
+2. проверяет наличие и формат `.hex` или `.bin`;
+3. запускает локальную проверку SETGUI (`--preflight`) либо публикацию
+   (`--publish`);
+4. для каждого транспорта загружает образ в Gitea, скачивает его обратно,
+   сверяет SHA-256 и только после этого обновляет `update.json`.
+
+Пароль в проекте не хранится. Публикатор использует учётные данные Gitea,
+которые сохранены в SETGUI через окно «Версия и обновление».
+
+## Один раз на рабочем компьютере
+
+1. Соберите или запустите SETGUI и сохраните в нём логин и пароль (либо токен
+   вместо пароля) Gitea.
+2. Убедитесь, что у SETGUI создано Python-окружение `.venv`.
+3. Подключите `templates` как сабмодуль проекта либо используйте уже общий
+   checkout. Не делайте отдельные исправленные копии скрипта в каждом проекте.
+4. Скопируйте подходящий файл из [`examples`](examples) в корень проекта под
+   именем `firmware-release.cmd` и исправьте значения.
+
+`firmware-release.cmd` содержит только метаданные:
+
+```bat
+set "FW_PROJECT_ROOT=%~dp0"
+set "FW_SETGUI_ROOT=%~dp0..\SETGUI"
+set "FW_PRODUCT=F103DS18"
+set "FW_VERSION=1.1.0"
+set "FW_VERSION_CODE=0x00010100"
+set "FW_TRANSPORTS=can rs485"
+set "FW_BASE_ADDRESS=0x08003000"
+set "FW_IMAGE=mdk\build\ds18b20_f103.hex"
+set "FW_NOTES=Краткое описание выпуска"
+```
+
+Пути считаются относительно каталога `firmware-release.cmd`. Если SETGUI не
+лежит рядом с проектом, укажите абсолютный `FW_SETGUI_ROOT` или системную
+переменную с тем же именем.
+
+### Обязательные поля
+
+| Поле | Значение |
+|---|---|
+| `FW_PRODUCT` | Стабильный идентификатор изделия. Не меняйте регистр/написание между версиями. |
+| `FW_VERSION` | Читаемая версия SemVer, например `1.1.0`. |
+| `FW_VERSION_CODE` | Число для сравнения версий. Рекомендуется `(major << 16) + (minor << 8) + patch`: `1.1.0` = `0x00010100`. |
+| `FW_TRANSPORTS` | Один или несколько транспортов через пробел: `can`, `rs485`, `tms`. |
+| `FW_IMAGE` | Готовый файл `.hex` или `.bin`. `.axf` и `.out` публиковать нельзя. |
+
+`FW_BASE_ADDRESS` нужен для обычного бинарного образа STM32. Для Intel HEX
+адрес уже записан в файле, но поле каталога всё равно лучше заполнить адресом
+приложения. Для загрузочной таблицы TMS SCI8 оставьте поле пустым.
+
+## Keil MDK / Arm Compiler 6
+
+1. В **Options for Target → Output** включите **Create HEX File**.
+2. Укажите в `FW_IMAGE` реальный выходной файл, например
+   `mdk\build\ds18b20_f103.hex`.
+3. Запустите полную сборку и локальную проверку. В `KONOR_ds18b20`, где
+   сабмодуль `templates` подключён как `lib`, команда выглядит так:
+
+```bat
+call "lib\tools\firmware-publish\PUBLISH_FIRMWARE.bat" --config "firmware-release.cmd" --preflight
+```
+
+В **Options for Target → User → After Build/Rebuild** можно добавить эту же
+команду с `--preflight`. Если Keil запускает её из каталога `mdk`, передайте
+явный путь к конфигурации, например `--config "..\firmware-release.cmd"`.
+
+Не ставьте `--publish` в post-build: иначе обычная сборка станет внешней
+операцией и сможет перезаписать опубликованную версию.
+
+## Code Composer Studio 12 / C2000
+
+SETGUI не преобразует `.out`. Для активной конфигурации **Debug и/или Release**
+включите **C2000 Hex Utility** и сформируйте загрузочный `.bin`. Для SCI8 boot
+TMS320F2812 используются параметры проекта:
+
+```text
+--binary
+--boot
+--sci8
+```
+
+Выход удобно складывать в `bin\${BuildArtifactFileBaseName}.bin`. Затем укажите
+этот путь в `FW_IMAGE`, `tms` в `FW_TRANSPORTS`, а `FW_BASE_ADDRESS` оставьте
+пустым.
+
+После Build выполните:
+
+```bat
+call "..\newProject\templates\tools\firmware-publish\PUBLISH_FIRMWARE.bat" --config "firmware-release.cmd" --preflight
+```
+
+Команда выше соответствует текущей раскладке `SETGIT\BALZAM_ALL` и
+`SETGIT\newProject\templates`. Если `templates` подключён в сам проект как
+`lib\templates`, используйте `lib\templates\tools\firmware-publish\...`.
+
+При желании ту же команду можно добавить в **Project Properties → Build →
+Steps → Post-build steps**. В конфигурации CCS, где Hex Utility не включён,
+файл `.bin` не обновится — это особенно важно отдельно проверить для Release.
+
+## Выпуск
+
+Рабочая последовательность одинакова для обеих IDE:
+
+```bat
+rem 1. Собрать Release в IDE.
+
+rem 2. Проверить метаданные, размер, имя, SHA-256 и запись каталога без сети.
+call "lib\tools\firmware-publish\PUBLISH_FIRMWARE.bat" --config "firmware-release.cmd" --preflight
+
+rem 3. Закоммитить исходники выпуска и опубликовать.
+call "lib\tools\firmware-publish\PUBLISH_FIRMWARE.bat" --config "firmware-release.cmd" --publish
+```
+
+Перед публикацией скрипт показывает все параметры, проверяет tracked-файлы
+Git и просит подтверждение. `--allow-dirty` осознанно разрешает публикацию из
+изменённого worktree, а `--yes` отключает только интерактивное подтверждение
+для доверенного CI:
+
+```bat
+call PUBLISH_FIRMWARE.bat --publish --yes --allow-dirty
+```
+
+Повторная публикация той же комбинации `product + versionCode + transport`
+заменяет запись каталога. Новый `versionCode` добавляет новую версию. Если при
+нескольких транспортах сеть оборвалась посередине, исправьте причину и повторите
+ту же команду: уже опубликованные записи будут безопасно заменены теми же
+данными.
+
+## Контроль после публикации
+
+Успешное завершение означает, что образ:
+
+- загружен как asset выпуска;
+- скачан обратно и совпал по SHA-256;
+- записан в `firmware.releases` файла `update.json`;
+- повторно прочитан и разобран тем же кодом, который использует SETGUI.
+
+После этого откройте в SETGUI **Версия и обновление → База прошивок → Обновить
+каталог** и проверьте изделие, версию и транспорт. Для окончательной проверки
+выполните загрузку на тестовое устройство именно тем транспортом, который
+указан в записи.
+
+## Частые ошибки
+
+| Сообщение | Что проверить |
+|---|---|
+| `firmware image not found` | Сборка завершилась успешно, `FW_IMAGE` задан относительно конфигурации, нужная конфигурация IDE создаёт `.hex/.bin`. |
+| `SETGUI was not found` | Исправьте `FW_SETGUI_ROOT`. |
+| `Missing build environment: .venv` | Создайте окружение SETGUI и установите зависимости проекта. |
+| Ошибка авторизации Gitea | Заново сохраните логин и токен в SETGUI; не записывайте токен в `.cmd`. |
+| `tracked project files differ from HEAD` | Закоммитьте точные исходники выпуска либо осознанно добавьте `--allow-dirty`. |
+| Версия не видна в SETGUI | Нажмите «Обновить каталог» и проверьте точное значение `FW_PRODUCT` и поддерживаемый выбранным устройством транспорт. |