Добавить протокол Altera Logic и общие клиенты прошивки

2026-09-19 07:12:09 +03:00
parent def3eb08f3
commit 80ba17d77d
38 changed files with 3271 additions and 10 deletions
--- a/tools/firmware-publish/PORTING.md
+++ b/tools/firmware-publish/PORTING.md
@@ -0,0 +1,164 @@
+# Подключение публикации прошивки к новому проекту
+
+**Дополнение:** полная независимая библиотека базы прошивок теперь реализована
+в `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 в исходники или конфигурации проекта.