templates/tools/firmware-publish/PORTING.md

Подключение публикации прошивки к новому проекту

Дополнение: полная независимая библиотека базы прошивок теперь реализована в python/setprotocol/firmware_database.py, с CLI firmware_db.py. Чтение, скачивание, публикация и перенос GUI описаны в DATABASE.md. Ниже сохранено описание интеграции через прежний BAT и SETGUI.

Что уже реализовано

По локальным исходникам на 19 сентября 2026 года общий механизм уже есть. Создавать вторую библиотеку для той же схемы SETGUI не требуется:

Компонент	Назначение	Зависимость
c/firmware-info	Версия реально запущенного образа, 12 слов / 24 байта	C-config проекта, без сети
python/setprotocol/firmware_publish.py	Проверка параметров файла, SHA-256, release tag, запись и обновление каталога	Python stdlib, firmware_catalog.py
python/setprotocol/firmware_catalog.py	Модель и чтение firmware.releases	Python stdlib
tools/firmware-publish/PUBLISH_FIRMWARE.bat	Конфигурация IDE, транспорты, проверка Git, запуск выпуска	Windows, checkout SETGUI и его .venv
SETGUI/scripts/publish_firmware.py	Загрузка в Gitea, скачивание и проверка SHA-256, запись и повторное чтение update.json	Общие Python-модули, API и учётные данные SETGUI

Модуль firmware_publish.py сам не выполняет HTTP-запросы. Старый общий BAT использует сетевой публикатор SETGUI. Для автономного CI без SETGUI теперь используйте GiteaFirmwarePublisher из firmware_database.py или CLI firmware_db.py; одного firmware_publish.py для загрузки недостаточно.

проект МК → сборка .hex/.bin → общий BAT → SETGUI/scripts/publish_firmware.py
                                              ↓
                              setprotocol.firmware_publish
                                              ↓
                         Gitea release asset → SHA-256 → update.json

проект МК → firmware-info → обработчик версии → транспорт → клиент

Эти две цепочки не синхронизируют версии автоматически. Bootloader и запись Flash — отдельные компоненты (rs485-boot, protocan-boot, set-protocol); публикация файла не добавляет поддержку обновления в устройство.

Фактические подключения в этой рабочей папке

• KONOR_ds18b20/src/main.c: app_send_firmware_info() и команда 0x03. mdk/SETGUI_DS18B20.uvprojx подключает оба C-файла через ..\lib\c, config через ..\inc, generated через mdk/Generated, генератор — Before Build.
• В текущем checkout KONOR_ds18b20/lib/c является Windows junction на общий newProject/templates/c. Это локальная связь; её нельзя считать переносимым путём для другого компьютера. .gitmodules при этом декларирует templates в lib: перед переносом нужно сверить реальную раскладку, а не копировать пути из Keil вслепую. Корневой firmware-release.cmd у KONOR при проверке отсутствует.
• SETGUI импортирует модули публикации из SETGUI/third_party/templates/python. Изменение соседнего newProject/templates/python само по себе эту копию не обновляет. Версию зависимости в SETGUI обновляют отдельно.
• SETGUI/src/gui_desktop/firmware_update.py читает каталог через общий parser. Поиск по текущему SETGUI/src не обнаружил обработчика FIRMWARE_INFO / firmware_info: упаковка совместимого ответа ещё не означает, что эта версия клиента запрашивает и показывает расширенный контракт KONOR.
• В исходниках сетевого публикатора задан Gitea https://git.rd12.ru, владелец setcorp, репозиторий SETRD12-Releases, ветка main, файл update.json. Это настройки кода, а не результат проверки доступности сервера.

1. Выбрать раскладку

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

workspace/
  SETGUI/
    PUBLISH_FIRMWARE.bat
    .venv/Scripts/python.exe
  MyFirmware/
    firmware-release.cmd
    lib/templates/tools/firmware-publish/PUBLISH_FIRMWARE.bat
    mdk/build/application.hex

Подключите templates принятой в проекте системой зависимостей. Скопируйте только конфигурацию из examples/keil-firmware-release.cmd или examples/ccs12-firmware-release.cmd в корень прошивки. Общий BAT оставьте в зависимости.

2. Заполнить firmware-release.cmd

Пример для приложения STM32 с bootloader; адрес 0x08003000 является примером и должен совпасть с linker script и настройками загрузчика вашего устройства:

@echo off
set "FW_PROJECT_ROOT=%~dp0"
set "FW_SETGUI_ROOT=%~dp0..\SETGUI"
set "FW_PRODUCT=MY_DEVICE"
set "FW_VERSION=1.2.3"
set "FW_VERSION_CODE=0x00010203"
set "FW_TRANSPORTS=can rs485"
set "FW_BASE_ADDRESS=0x08003000"
set "FW_IMAGE=mdk\build\application.hex"
set "FW_NOTES=Firmware 1.2.3"

FW_PRODUCT должен соответствовать идентификатору изделия, с которым клиент выбирает прошивку. Сверьте FW_VERSION с C-config; при упаковке версии в три 8-битных поля используйте части 0–255. Укажите только реально реализованные транспорты. Parser допускает can, rs485, stm32, tms; для их применения нужна соответствующая поддержка клиента и загрузчика.

Все транспорты одного запуска используют один и тот же файл. Если образы для CAN и RS-485 отличаются, заведите разные конфигурации с разными именами файлов и запускайте их отдельно. Одинаковое имя asset в одном release tag нельзя использовать для разных образов.

Для CCS 12 создайте SCI8 boot .bin через C2000 Hex Utility (--binary --boot --sci8), задайте FW_TRANSPORTS=tms и очистите адрес: set "FW_BASE_ADDRESS=". .out и .axf публикатор не преобразует.

3. Проверить и выпустить

Подготовьте окружение SETGUI по документации этого проекта. Учётные данные Gitea сохраняются через окно SETGUI «Версия и обновление»; в .cmd они не нужны.

Из корня MyFirmware в cmd.exe:

call "lib\templates\tools\firmware-publish\PUBLISH_FIRMWARE.bat" --config "firmware-release.cmd" --preflight

Для post-build в mdk используйте пути ..\lib\templates\... и --config "..\firmware-release.cmd". В post-build оставляйте --preflight.

Preflight проверяет существование, расширение, размер, метаданные, SHA-256 и схему записи каталога. Он не разбирает содержимое Intel HEX/SCI8, не сверяет версию с C-config, адреса с linker script и файл с текущими исходниками. Успех preflight не заменяет Rebuild и загрузку на тестовое устройство.

После проверки конкретного Release-образа и фиксации его исходников:

call "lib\templates\tools\firmware-publish\PUBLISH_FIRMWARE.bat" --config "firmware-release.cmd" --publish

Скрипт запросит подтверждение. Успех означает загрузку asset, проверку скачанных байтов, обновление каталога и его повторное чтение. Несколько транспортов публикуются последовательно, общей транзакции для всего запуска нет. Откройте базу прошивок SETGUI, обновите каталог и проверьте загрузку на тестовое устройство.

4. Другой сервер или собственный инструмент

FW_SETGUI_ROOT выбирает checkout SETGUI, а не адрес Gitea. Переменная SETGUI_UPDATE_MANIFEST_URL меняет URL чтения каталога, но не перенастраивает WEB_ROOT, OWNER, RELEASE_REPO сетевого публикатора. Для другого сервера нужно согласованно перенести сетевой адаптер, адреса чтения и авторизацию.

Для собственного Python-инструмента добавьте templates/python в import path и используйте FirmwarePublication, sha256_file, firmware_release_tag, firmware_release_entry, update_firmware_manifest из setprotocol.firmware_publish. Вызывайте publication.validate() до создания записи. Сетевой адаптер должен обеспечить тот же порядок, что SETGUI:

1. Загрузить образ в release и скачать его обратно, сверить SHA-256.
2. Прочитать актуальный manifest, объединить через update_firmware_manifest.
3. Записать manifest с проверкой исходной ревизии, чтобы не затереть чужое параллельное изменение; конфликт требует повторного чтения и объединения.
4. Перечитать каталог через parse_firmware_catalog и проверить запись выпуска.

Не переносите пароли из профиля SETGUI в исходники или конфигурации проекта.