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