Перенести улучшения прошивки в ветку 166

Добавить CAN heartbeat и передачу по изменению с повтором через 1,3 с,
компактный логгер v4, паспорт прошивки и блочное чтение EEPROM.
Подключить автоматическую версию и проверяемую сборку BIN.
Сохранить локальные исправления стробов и защиты Timer1.
Обновить тесты, документацию, UTF-8 и исключения временных файлов.

Проверки: CAN, R3, EEPROM, паспорт, TESTLAMP, логгер, START/STOP;
9 сценариев сборки, включая реальную конверсию TI.
Все 17 внутренних модулей скомпилированы TI C2000 без ошибок.

UKSSTMS320F28335/README.md

@@ -1,35 +1,258 @@
-# Проект 166 для CCS 12
+# Сборка прошивки Бальзам-166 / TMS320F28335
 
-Настройки перенесены из проекта 167. Имя проекта в CCS: `Balsam_166`.
+Проект CCS называется `28335_periph`. Файл настроек проекта:
+`K:\git_project\28335_periph\UKSSTMS320F28335\.cproject`.
+Для рабочей сборки используйте конфигурацию **Debug**.
 
-## Импорт и сборка
+В локальную ветку `166` перенесены функции из `current_firmware_166`:
+телеметрия CAN по изменению с heartbeat, логгер v4, паспорт прошивки,
+блочное чтение EEPROM и проверяемый выпуск BIN. Сохранены локальные
+настройки таймингов DATA/CLOCK в `kanal.c`, запрет повторного входа Timer1
+в `pulto.c` и отключение контроля CAN timeout до первой передачи.
+Выбор `BALSAM=165`, существовавший в обеих ветках, сохранён: перенос
+функций не меняет аппаратные калибровки и порядок индикаторов.
 
-1. В CCS выберите **Project → Import CCS Projects** и укажите эту папку
-   (`166/UKSSTMS320F28335`).
-2. Импортируйте проект без **Copy projects into workspace**: исходники и
-   библиотеки подключены из родительской папки по относительным путям.
-3. Выберите конфигурацию **Debug** и выполните **Build Project**.
+Образы в `Bin` при переносе исходников не заменялись. Перед прошивкой
+платы нужна новая полная сборка: прежние HEX/OUT не содержат этого переноса.
 
-Используется TI C2000 Compiler **22.6.1.LTS**, TMS320F28335, FPU32 и COFF ABI.
-Сохранены настройки компиляции, линковки и преобразования прошивки из 167.
-Исходники берутся из `166/Source`, linker-файл — `166/F28335.cmd`.
-Файл `28335_RAM_lnk.cmd`, как и в 167, исключён из сборки.
+## Реальные пути на этом компьютере
 
-Результаты сборки находятся в `166/Bin`: `UKSSTMS320F28335.out`,
-`UKSSTMS320F28335.hex` (Intel HEX) и `UKSSTMS320F28335_<commit>.bin`,
-где `<commit>` — короткий хеш текущего коммита Git (не менее 8 символов).
-BIN создаётся скриптом `build_bin.bat`; Git должен быть доступен в `PATH`
-процесса CCS. Если определить коммит не удалось, сборка завершается ошибкой.
-При наличии незакоммиченных правок хеш обозначает HEAD и не описывает эти правки.
-Post-build использует имеющийся `166/Bin/hex2000.exe` с параметрами
-`-boot -sci8`, как в 167. Карта линковки находится в корне 166, карта
-преобразования загрузочного образа — в `166/Bin`.
+| Назначение | Полный путь |
+|---|---|
+| Корень исходников, макрос CCS `${SRC_ROOT}` | `K:\git_project\28335_periph` |
+| Каталог проекта, макрос CCS `${PROJECT_LOC}` | `K:\git_project\28335_periph\UKSSTMS320F28335` |
+| Общая библиотека templates, используемая этой сборкой | `K:\git_project\newProject\templates` |
+| Компилятор, макрос CCS `${CG_TOOL_ROOT}` | `C:\ti\ccs1230\ccs\tools\compiler\ti-cgt-c2000_22.6.0.LTS` |
+| Каталог Debug, макрос CCS `${BuildDirectory}` | `K:\git_project\28335_periph\UKSSTMS320F28335\Debug` |
+| Настройки версии и путей | `K:\git_project\28335_periph\UKSSTMS320F28335\firmware_identity.json` |
+| Постоянный каталог готовых образов Debug | `K:\git_project\28335_periph\UKSSTMS320F28335\Debug\firmware` |
+| Дополнительная копия готовых файлов | `K:\git_project\28335_periph\Bin` |
 
-Проверено: импорт и полная сборка **Debug** в CCS **12.7.1** с компилятором
-**22.6.1.LTS**, включая генерацию HEX/BIN, завершились без ошибок.
-Есть шесть предупреждений в существующих `peripher.c` и `measure.c`
-(преобразование знака, выход результата за диапазон и отсутствие перевода
-строки в конце файла). Проверка на устройстве не выполнялась.
+## Как правильно указать templates
 
-Конфигурация **Release** перенесена из 167 без изменений и не проверялась;
-для сборки прошивки используйте **Debug**.
+Откройте `K:\git_project\28335_periph\UKSSTMS320F28335\firmware_identity.json`.
+Поле `templates` уже содержит рабочее значение:
+
+`"templates": "../../newProject/templates"`
+
+Путь отсчитывается **от папки файла firmware_identity.json**:
+два перехода `..` приводят в `K:\git_project`, затем `newProject/templates`
+приводит в `K:\git_project\newProject\templates`.
+Рабочая папка терминала и каталог Debug на этот расчёт не влияют.
+
+Для этой машины допустима и абсолютная запись того же пути:
+
+`"templates": "K:/git_project/newProject/templates"`
+
+В JSON удобнее использовать `/`: обратный слеш пришлось бы удваивать.
+Указывайте корень полной библиотеки templates. Внутри должны существовать:
+
+| Что использует сборка | Полный путь |
+|---|---|
+| Генерация паспорта до компиляции | `K:\git_project\newProject\templates\tools\firmware-build\ccs\precompile.bat` |
+| Конверсия после компиляции | `K:\git_project\newProject\templates\tools\firmware-build\ccs\postcompile.bat` |
+| Заголовки firmware-info | `K:\git_project\newProject\templates\c\firmware-info\include` |
+| Общий протокол | `K:\git_project\newProject\templates\c\set-protocol` |
+
+В CCS → **Project Properties → Build → C2000 Compiler → Include Options**
+для Debug и Release используются следующие записи:
+
+| Запись в CCS | Какой каталог она открывает |
+|---|---|
+| `${SRC_ROOT}/../newProject/templates/c/firmware-info/include` | `K:\git_project\newProject\templates\c\firmware-info\include` |
+| `${SRC_ROOT}/../newProject/templates/c/set-protocol` | `K:\git_project\newProject\templates\c\set-protocol` |
+| `${BuildDirectory}/generated` | `K:\git_project\28335_periph\UKSSTMS320F28335\Debug\generated` для Debug |
+
+Если перенесли templates, измените **и поле JSON, и два include path в CCS**.
+Настройка JSON управляет сборочными сценариями; include paths компилятора
+сохраняются отдельно в `.cproject`.
+
+## Импорт и запуск сборки в CCS
+
+1. Выберите **Project → Import CCS Projects**.
+2. Укажите `K:\git_project\28335_periph\UKSSTMS320F28335`.
+3. Оставьте **Copy projects into workspace** выключенным: исходники и
+   библиотеки подключены из соседних каталогов.
+4. Проверьте компилятор TI C2000 **22.6.0.LTS**, контроллер
+   **TMS320F28335**, **FPU32**, **COFF ABI**. Python должен быть доступен
+   командой `python`; Git используется для определения ревизии.
+5. Включите конфигурацию **Debug** и выполните **Build Project**.
+
+Исходники находятся в `K:\git_project\28335_periph\Source`, linker-файл —
+`K:\git_project\28335_periph\F28335.cmd`. `28335_RAM_lnk.cmd` исключён
+из сборки. Debug создаёт OUT в `K:\git_project\28335_periph\Bin`.
+
+## Команды Build Steps
+
+В **Project Properties → Build → Steps** задайте команды для Debug и
+Release. Каждую команду вставляйте в соответствующее поле одной строкой.
+Макросы `${...}` подставляет CCS; вручную в обычном cmd они не раскрываются.
+
+**Pre-build** — резервирует версию и создаёт заголовок и метаданные
+в `${BuildDirectory}/generated`:
+
+`cmd /c call "${PROJECT_LOC}/firmware_build.bat" prepare --build-dir "${BuildDirectory}"`
+
+**Post-build** — конвертирует OUT, проверяет встроенный паспорт,
+размер образа и SHA-256, затем сохраняет готовый комплект:
+
+`cmd /c call "${PROJECT_LOC}/firmware_build.bat" build --compiler "${CG_TOOL_ROOT}" --build-dir "${BuildDirectory}" --artifact "${BuildArtifactFileBaseName}"`
+
+После `--artifact` должен стоять только путь к OUT **без расширения .out**.
+Дополнительный путь последним аргументом вызовет `unrecognized arguments`.
+Каталог templates и каталог копирования задаются в JSON.
+
+Для отдельного JSON добавьте `--config "полный/путь/firmware_identity.json"`
+в обе команды. Тогда относительные пути будут отсчитываться от этого JSON.
+
+После изменения `.cproject` вне IDE закройте и снова откройте проект в CCS,
+проверьте Build Steps и запустите сборку. Файл
+`K:\git_project\28335_periph\UKSSTMS320F28335\Debug\makefile`
+генерируется CCS; постоянные исправления вносятся в настройки проекта.
+
+## Где искать готовую прошивку
+
+Основной каталог:
+
+`K:\git_project\28335_periph\UKSSTMS320F28335\Debug\firmware`
+
+В нём находятся `UKSSTMS320F28335_<build_id>.bin`, файл
+`<имя>.bin.manifest.json`, файл `<имя>.bin.sha256`, HEX, карты конверсии
+и архивные папки с ревизией и временем сборки.
+
+Например, проверенный в этой сессии файл:
+
+`K:\git_project\28335_periph\UKSSTMS320F28335\Debug\firmware\UKSSTMS320F28335_13f1a2c+.bin`
+
+В окне выбора прошивки можно вставить полный путь в поле **«Имя файла»**.
+Для актуальной сборки берите путь из последней строки журнала
+`[firmware-build] Verified BIN: ...`.
+
+Каталоги `.identity-release-...` из промежуточных строк журнала временные:
+после проверки их содержимое переносится в `Debug\firmware`, а временная
+папка удаляется.
+
+Поле `"copy_to": "../Bin"` в JSON дополнительно копирует проверенные BIN,
+manifest, SHA-256, HEX и карту конверсии в `K:\git_project\28335_periph\Bin`.
+Для другого назначения укажите в `copy_to` реальный полный путь через `/`
+или путь относительно JSON. Если дополнительная копия не нужна, удалите
+это поле. Архивные папки остаются в `Debug\firmware`.
+
+## Версия и проверки перед выпуском
+
+| Поле в firmware_identity.json | Назначение |
+|---|---|
+| `product` | Идентификатор изделия, сейчас `Balsam-166-PM35`. |
+| `target` | Контроллер, сейчас `TMS320F28335`. |
+| `version` | Последний занятый номер `[major, minor, patch]`. |
+| `increment_version` | `true` увеличивает версию перед компиляцией; `false` оставляет ручную версию. |
+| `templates` | Корень общей библиотеки; путь относительно JSON или абсолютный. |
+| `max_image_bytes` | Предел полного SCI8 BIN, сейчас 32508 байт. |
+| `copy_to` | Необязательный дополнительный каталог проверенных файлов. |
+
+При включённом итераторе каждый pre-build занимает следующий номер,
+включая попытки, после которых компиляция завершилась ошибкой. После patch
+999 увеличивается minor, после minor 255 — major; младшие поля обнуляются.
+После 255.255.999 сценарий выдаёт ошибку. Clean номер не сбрасывает.
+Одновременные сборки с одним JSON запускать нельзя.
+
+Итератор реализован в общем `templates/c/firmware-info/tools/identity.py`.
+Он работает и при прямом вызове `templates/tools/firmware-build/ccs/precompile.bat
+--identity`, который настроен в Debug, и через `firmware_build.bat prepare`.
+Проектная обёртка передаёт настройки в templates без повторного увеличения.
+Без поля `increment_version` либо при `false` сохраняется ручная версия.
+
+Build ID состоит из восьми символов: восемь символов ревизии либо семь
+символов и `+` при изменениях исходников или templates. При недоступном Git
+используется `NOGIT000`; ревизии `source` и `templates` проверяйте в manifest.
+Время паспорта хранится в UTC.
+
+Post-build требует совпадения OUT с метаданными pre-build, ровно одного
+12-словного паспорта в SCI8, корректных manifest и SHA-256. Ограничение
+32508 байт рассчитано как `(0x3FFF - 129) * 2`: это граница области
+параметров EEPROM данной платы. Неверный комплект проверку не проходит.
+
+## Повторная конверсия готового OUT без компиляции
+
+Запустите следующую команду в **cmd.exe**. Она использует существующие
+OUT и generated от одной компиляции и повторно проверяет их соответствие.
+Номер версии при этом не увеличивается.
+
+```bat
+rem Конвертирует готовый Debug OUT штатным hex2000 из указанного компилятора, сохраняя проверки паспорта и SHA-256.
+call "K:\git_project\28335_periph\build_bin.bat" --compiler "C:/ti/ccs1230/ccs/tools/compiler/ti-cgt-c2000_22.6.0.LTS"
+```
+
+Если изменены исходники, версия или паспорт, выполните обычную сборку
+в CCS, чтобы OUT и generated соответствовали друг другу.
+
+## Перенос в другой проект C2000
+
+Скопируйте `firmware_build.bat`, `build_identity.py` и
+`firmware_identity.json` из
+`K:\git_project\28335_periph\UKSSTMS320F28335` в каталог нового CCS-проекта.
+В JSON задайте изделие, контроллер, версию, реальный путь к полной
+библиотеке templates, предел памяти платы и при необходимости `copy_to`.
+Добавьте Build Steps из этой инструкции и include paths к выбранной
+библиотеке и `${BuildDirectory}/generated` в обе конфигурации CCS.
+
+BAT и Python менять для переноса путей не требуется. BAT хранится в UTF-8
+без BOM с окончаниями CRLF. Подключение сборочных шагов не заменяет
+интеграцию firmware-info в код устройства; для C28x нужен порт с учётом
+16-битного `char`.
+
+## Проверка прошивки в SetGUI
+
+Из 167 точечно перенесён контракт firmware-info v1: FC03, адрес **0x1200**,
+**12 регистров**, версия, дата UTC и Build ID. Чтение доступно также через
+существующий служебный CAN; запись в паспорт запрещена. Технологическая
+карта, логгер v4 с записью 12 слов, управление и CAN ID не меняются.
+
+В GUI выберите модель **«Бальзам-166 · ПМ35»**, новый BIN и оставьте рядом
+его `.bin.manifest.json`. После записи EEPROM перезапустите плату и нажмите
+чтение версии: продолжающая работать старая прошивка ещё не имеет окна
+0x1200 и отвечает `Modbus 2`. Надпись CRC OK при записи подтверждает запись
+EEPROM, а версия начнёт читаться после запуска нового образа. Сравнение
+версий и SHA-256 манифеста не является измерением SHA всей памяти платы.
+
+`python tests/firmware_identity/run_test.py` проверяет реальные обработчики
+RS/CAN, все слова паспорта, CRC, частичные чтения, границы, запрет записи,
+сохранность старой карты и логгера. Отдельно проверяются устаревшие и
+повреждённые SCI8, предел EEPROM и действующий анализатор манифеста SetGUI.
+`python tests/firmware_identity/test_build_steps.py` проверяет перенос трёх
+файлов в другое изделие, увеличение версии в JSON, перенос разрядов,
+настоящий вызов BAT и общего precompile из постороннего рабочего каталога,
+пути с пробелами, копирование и остановку до публикации при неверном BIN
+или SHA-256.
+При заданной переменной окружения `C2000_COMPILER` (корень toolchain)
+этот же тест дополнительно компилирует минимальный C28x COFF и проходит
+настоящий postbuild через BAT, `hex2000`, проверку паспорта и копирование.
+Проверка 17.10.2026: post-build готового OUT выполнен с TI C2000 22.6.0.LTS;
+проверки встроенного паспорта и SHA-256 пройдены, комплект скопирован в Bin.
+SHA-256 основной и дополнительной копий BIN совпадает. Тест подключения
+BAT в конфигурациях Debug и Release пройден. Полная компиляция и проверка
+на физической плате в рамках этой проверки не выполнялись.
+
+Для рабочей сборки используйте Debug; Release требует отдельной проверки.
+
+## Телеметрия CAN: heartbeat, изменения и повтор 1,3 с
+
+Для всех Mode технологические пакеты выбранных масками регистров R0–R127
+передаются при первом снимке, изменении любого из трёх слов или через 1300 мс
+после последнего успешного CAN ACK этого пакета. Неудачная попытка не обновляет
+подтверждённый снимок. Конечные пакеты карты дополняются нулями за R127.
+Сканирование изменений идёт по Timer1 с шагом 20 мс; готовая очередь выдаётся
+по мере освобождения mailbox, без ожидания нового периода между её кадрами.
+Фактическую отправку могут задержать занятая шина, ошибки и работа main.
+
+Heartbeat отправляется независимо раз в секунду: адрес `0x0100`, затем три
+16-битных слова — счётчик секунд, Mode, Desk. После задержки main отправляется
+последнее значение, без очереди пропущенных секундных кадров.
+
+Ноль в `Cancount[0]` или `Cancount[1]` по-прежнему отключает данные соответствующей
+маски. Любое ненулевое значение включает новый режим изменения/1300 мс;
+прежний числовой делитель периода больше не используется. Heartbeat остаётся
+включённым при отключённых потоках данных. Параметры EEPROM не переносятся.
+После ошибки TX новая попытка разрешается через секунду без ожидания в цикле.
+
+Проверка без CAN-адаптера: `python tests/can_telemetry/run_test.py`.