# Публикация прошивки из 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` и поддерживаемый выбранным устройством транспорт. |