165 lines
11 KiB
Markdown
165 lines
11 KiB
Markdown
# Подключение публикации прошивки к новому проекту
|
||
|
||
**Дополнение:** полная независимая библиотека базы прошивок теперь реализована
|
||
в `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 в исходники или конфигурации проекта.
|