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

**Дополнение:** полная независимая библиотека базы прошивок теперь реализована
в `python/setprotocol/firmware_database.py`, с CLI `firmware_db.py`.
Чтение, скачивание, публикация и перенос GUI описаны в [`DATABASE.md`](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` для загрузки недостаточно.

```text
проект МК → сборка .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. Выбрать раскладку

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

```text
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 и настройками загрузчика вашего устройства:

```bat
@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:

```bat
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-образа и фиксации его исходников:

```bat
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 в исходники или конфигурации проекта.