Balsam_167/Doc/UMP_LOGGER.md

# Логгер запуска и отключения УМП: прошивка Бальзам 167 и SetGUI

## Назначение и работа оператора

В SetGUI открыть ПМ35 → Настройки, выбрать COM, скорость (обычно 115200)
и адрес контроллера (обычно 16). Затем открыть вкладку **Логгер УМП**.
Подключение используется существующее: прямой RS232/RS485 Modbus RTU.
CAN-команды от управляющего контроллера фиксируются самой платой нагрузки.

1. **Начать запись** включает только регистратор, не пуск УМП.
   Период снимков по умолчанию 20 мс, диапазон 1–1000 мс.
2. Флажки выбирают отображаемые сигналы. Аналоги рисуются линиями,
   дискретные сигналы — отдельными дорожками. Выбор не меняет состав
   записи на плате: скрытую кривую можно включить после захвата.
3. **Онлайн** подключает график к уже идущей записи, в том числе после
   восстановления соединения. Тайм-аут не посылает плате команду останова.
4. Фронт `cUMPreset` (бит 6 команды 0x7F) или спад `cUMPstart` (бит 7)
   запускает фиксацию отключения. Ещё через 1000 тиков таймера / 1 секунду
   банк становится архивом. Повторные команды внутри этой секунды
   не продлевают интервал. Другие изменения команд не служат триггером.
5. **Прочитать отключение** загружает архив, не останавливая запись на плате.
   На время чтения и просмотра архива онлайн-график приостанавливается;
   вернуться к нему можно кнопкой **Онлайн**.
6. **Остановить и прочитать** останавливает только регистратор и читает
   текущий банк. При этом существующий архив отключения остаётся доступным.
7. **Сохранить CSV** сохраняет все поля загруженного/онлайн-буфера,
   включая невидимые кривые, время и код события. История GUI ограничена
   800 последними точками; это не непрерывная запись на диск.

При разрыве связи журнал на плате продолжает работать. Архив хранится в ОЗУ
до следующей фиксации отключения либо перезагрузки/пропадания питания.
EEPROM не используется: под отключением в этой задаче понимается команда
управляющего контроллера, а не потеря питания.

## Память и точность

Использована существующая секция `.logg` по адресу 0x200000: 64000
16-битных слов. Два банка по 760 записей × 42 слова занимают 63840 слов (160 слов свободны).
Текущий банк кольцевой. При триггере сохраняются последние до 379 записей,
добавляется событие отключения, оставшаяся половина банка отведена
постинтервалу. При 20 мс это до примерно 7.6 секунды до отключения и 1 секунды
после. Дополнительные события CAN и дискретов сокращают временную глубину.

При интенсивном потоке событий или периоде 1 мс постинтервал может заполнить
свои места раньше секунды. Последнее место зарезервировано под конечный
снимок; он помечается `event & 0x200`, и GUI сообщает об усечении.
Событие отключения и предыстория при этом не вытесняются.

Время — 32-битный счётчик миллисекунд записи. Он идёт только при включённом
регистраторе и не является абсолютным временем. События в одном тике имеют
одинаковую отметку; порядок сохраняется порядком записей. На перезапуске
регистратора счётчик продолжает прежнюю шкалу, при перезагрузке платы — 0.

Онлайн-опрос возвращает две последние записи каждые 40 мс. Он не гарантирует
передачу каждого события при высоком CAN-трафике, медленном UART или паузах
GUI. Номера записей позволяют убрать дубликаты и явно показать пропуски.
Полный сохранившийся фрагмент следует читать кнопкой архива. Частота 20 мс
выбрана с учётом размера кадра; на низких скоростях нужна большая пауза
снимков и подходящий тайм-аут RS.

Все писатели и чтение одного Modbus-блока используют короткие критические
секции с восстановлением прежнего состояния IRQ. Внутри нет ожидания UART,
EEPROM, выделения памяти или копирования целого банка. Реальную задержку
прерываний и длительность критических секций нужно измерить на F28335.

## Состав записи v3: 42 слова

| Слова | Данные | Единицы/смысл |
|---|---|---|
| 0–1 | Время, младшее/старшее слово | мс записи |
| 2 | Событие | 1 период, 2 CAN RX, 3 изменение I/O, 4 RS-команда, 5 конец постинтервала |
| 2, бит 8 | Триггер отключения | флаг поверх причины события |
| 2, бит 9 | Усечён постинтервал | установлен в конечном снимке |
| 3 | Commands / modbus[0x7F] | все 16 бит, в том числе пуск, сброс, инициализация и калибровка ЦАП |
| 4 | Входы OMEGA, Start_1, Res_in | биты 0,1,2, активный уровень приведён к 1 |
| 5 | START_DPTB, STOP_DPTB, RES_OUT_2 | биты 0,1,2, активный уровень приведён к 1 |
| 6 | IMPowse | остаток импульса, мс |
| 7 | WAKEpowse | остаток инициализации, тики DAC_FREQ |
| 8 | modbus[0x7B] | 12-битный код, переданный функцией dSEND в ЦАП |
| 9 | modbus[0x1C] | расчётное задание в 0.1 мА; GUI/CSV переводит в мА |
| 10–13 | sens_data[0..3] | измеренные сигналы, знаковое 16-битное значение в исходном масштабе |
| 14–17 | modbus[0..3] | маски ошибок измерений |
| 18 | CAN заголовок | адрес регистра в младших 13 битах и маска трёх слов в старших |
| 19–21 | Три слова последнего принятого CAN-кадра | без преобразования |
| 22 | Счётчик записанных CAN RX | младшие 16 бит |
| 23 | CanTimeOutErrorTR | младшие 16 бит счётчика тайм-аутов CAN TX |
| 24–25 | DAC_go, DAC_stop | исходные начальная/конечная уставки, мА |
| 26–28 | DAC_min(), DAC_max(), DAC_cal() | коды калибровки и ручного задания ЦАП |
| 29–30 | DAC_04, DAC_20 | значения соответствующих регистров |
| 31–32 | count_load, time_dac | положение и длительность разгона в тиках |
| 33–34 | эффективные dac_go/dac_stop + 4 | 0.1 мА после ограничений алгоритма; GUI переводит в мА |
| 35 | kod | целочисленное положение, используемое Anal_output |
| 36–39 | ADC_table[0..3] | значения таблицы АЦП в исходном масштабе прошивки |
| 40 | ЗПТ1: U1 + U2, ПМ67 регистр 306 / индекс 305 | исходное 16-битное слово без пересчёта |
| 41 | ЗПТ2: U3 + U4, ПМ67 регистр 9 / индекс 8 | исходное 16-битное слово без пересчёта |

Напряжения принимаются из технологических CAN-кадров с нулевыми индексами
305 и 8. Учитываются все три позиции и биты маски 0x8000/0x4000/0x2000.
Они хранятся отдельно от массива modbus[0..127], обновляются и при выключенном
логгере. Запись содержит последние принятые значения; до первого приёма — 0.
При потере связи остаётся последнее значение: отдельного признака свежести нет.
Масштаб и знаковость физического напряжения не заданы исходной таблицей;
SetGUI показывает исходное беззнаковое слово, коэффициент задаётся в интерфейсе.

**Отправленный код ЦАП не является измеренным током выхода.** В этом проекте
не установлено, какой вход аппаратно измеряет ток ЦАП. При включённом
`cCalibrDac` отправляется `DAC_cal()`, а расчётное задание 0x1C остаётся
результатом алгоритма разгона. Для диагностики это различие сохранено.
ADC_table также уже обрабатывается существующим измерительным кодом;
это не обязательно необработанный регистр ADCRESULT.

Управляющая логика не исправлялась. Например, существующая строка
`if(dac_stop>16) dac_go=16;` в Load_runner сохранена; журнал показывает
фактически получившиеся эффективные уставки, чтобы выявить такое поведение.

## Протокол расширения Modbus

Технологические адреса 0..127 сохранены. Новая область использует полный
16-битный адрес; исходная реализация игнорировала старший байт.
Сначала GUI читает 16 слов 0x1000 и проверяет сигнатуру, версию, размер записи
и тип платы. До успешной проверки расширенные записи запрещены.
Обычный ответ расширения не содержит исторических хвостовых нулей.
Между ответом и следующим запросом GUI выдерживает паузу RTU.

FC03, 0x1000, 16 слов:

| Смещение | Значение |
|---|---|
| 0,1 | 0x554D, версия 3 |
| 2,3 | состояние и число записей выбранного источника |
| 4,5 | 42 слова в записи, 760 записей в банке |
| 6 | период периодических снимков, мс |
| 7,8 | счётчик времени, младшее/старшее слово |
| 9,10 | Desk (требуется 6 / dsk_LOAD), Mode |
| 11 | частота временной базы, 1000 Гц |
| 12 | поколение архива, mod 65536 |
| 13 | число записей архива |
| 14 | оставшиеся миллисекунды постинтервала |
| 15 | состояние текущего регистратора независимо от выбора источника |

Состояния: 0 — ещё не запущен, 1 — запись, 3 — остановлен/архив.

FC06:
- 0x1000: 1 — новый текущий журнал, 0 — остановить его;
- 0x1001: период 1..1000, менять только при остановленном журнале;
- 0x1002: хронологический индекс первой записи окна 0..759;
- 0x1003: источник окна, 0 — текущий остановленный банк, 1 — архив отключения.

FC03, 0x1010, до 120 слов: окно от установленного индекса; для целых записей v3 читать 42 или 84 слова.
CAN допускает 42/84 и прежние размеры 40/80/120; RTU допускает 1..120 слов.
Чтение текущего банка этим окном во время записи не выдаёт изменяющиеся
данные. GUI сначала останавливает его; архив можно читать при работающем
текущем банке. После всех блоков GUI повторно проверяет поколение архива;
при замене во время чтения результат не подменяет предыдущий график.

FC03, 0x1100, ровно 124 слова: онлайн-блок. Слова 0,1 — 32-битный номер
первой записи, 2 — число записей 0..2, 3 — поколение архива, далее до двух
записей по 42 слова. Неиспользованные слова равны нулю. Окно онлайн не
зависит от курсора/выбора архива. Разделение 0x1010 и 0x1100 предотвращает
пересечение двух окон.

Недопустимые диапазоны и значения возвращают исключения Modbus 2/3.
CRC и разбор стандартного ответа GUI используют существующее общее ядро.
SetGUI распознаёт v2 (40 слов, 800 записей) и v3 (42 слова, 760 записей).
Для v2 новые напряжения недоступны (NaN), для v3 доступны графики и CSV.
CAN-валидация общей библиотеки расширена размерами 42/84 слова.
Исходники протокола подключаются к прошивке из templates/c/set-protocol.

## Проверка и запуск

Полная сборка исправления: `./build_logger.ps1`. По умолчанию используется
`../newProject/SETGUI/third_party/templates`; другую копию можно указать
параметром `-TemplatesRoot`. В ней нужны `c/set-protocol/src/ump_protocol.c`
и `c/set-protocol/ports/tms320f28335/ump_tms28335.c` (порт УМП v3).
Само наличие папки templates не гарантирует наличие этого порта.
Результат — `Bin/LoggerFix/UKSSTMS320F28335_logger_fix.bin` (SCI8 boot),
рядом OUT и MAP. Старые образы в Bin не заменяются.
Скрипт использует TI C2000 22.6 COFF, оптимизацию размера и секции функций;
таблица `.cinit` размещена в RAML4 вместе с константами, код — в RAML0.
Для сборки из CCS добавьте `Source/Internal/shared_ump.c` в проект и каталоги
`<templates>/c/set-protocol`, `<templates>/c/set-protocol/ports/tms320f28335`
в include path; используйте параметры оптимизации из скрипта.

При загрузке `main()` вызывает `ump_log_init()` до включения прерываний.
Это обязательно для TI COFF: стартовый код не обнуляет неинициализированные
переменные `.ebss`. Без явной инициализации состояние, счётчики и номера
банков могут содержать остаточные значения RAM. Очистка `.logg` функцией
`clear_mem()` эти переменные не затрагивает. Повторный запуск записи через
FC06 не вызывает загрузочную инициализацию и сохраняет архив и шкалу времени.
Регрессия `python tests/ump_logger/run_init_test.py` (GCC в PATH) проверяет
запуск с ненулевой RAM и отрицательный контроль без инициализации;
внешняя библиотека `templates/c/set-protocol` для этого теста не нужна.

Изменены исходники прошивки и SetGUI. Готовый образ в Bin не обновлялся.
Для платы необходима сборка штатным TI C2000/CCS, проверка размещения .text,
.stack, .ebss и .logg по MAP, прошивка и испытание на стенде.

Автотест C в tests/ump_logger компилирует непосредственно log_to_mem.c
с подменой GPIO/IRQ. Проверяет кольцо, граничные адреса, обе команды
отключения, защиту триггера от переполнения, переключение банков,
сохранность архива во время дальнейшей записи и контрольные поля CAN/ЦАП.
Это проверка алгоритма на компьютере, не проверка таймингов и 16-битной ABI
TI. Отдельно выполнена синтаксическая проверка изменённых C-файлов Clang
с исходными заголовками и декларациями TI-интринсиков.

Тесты SetGUI: tests/test_ump_logger.py и tests/test_periph28335_tab.py.
Они проверяют единицы мА, битовые сигналы, временные метки, несовместимую
прошивку, порядок команд, архив при активной записи, замену поколения,
дубликаты/пропуски онлайн, потерю связи и флажки графиков.

Проверка на стенде: включить запись → подать CAN-пуск → изменить уставку →
подать откл. → через секунду прочитать архив → сверить код ЦАП, ток внешним
измерителем и физические входы/выходы; затем повторить с разрывом RS.
Период 1 мс проверить отдельно под максимальной CAN-нагрузкой.

Для сборки v3 нужен templates/main начиная с коммита c0ee7c4
(поддержка CAN-чтения 42/84 слов и порт TMS320F28335).

## Пересечение образа 34a95bc5 с параметрами EEPROM

Образ `UKSSTMS320F28335_34a95bc5.bin` имеет размер 32518 байт.
`Save_params` записывает 129 слов с адреса `0x3FFF-(128+1)`;
драйвер EEPROM умножает адрес на 2. Параметры начинаются с байта 32508.
Последние 10 байт BIN пересекаются с параметрами: два последних адреса
таблицы переходов `ump_log_read` (регистры 0x100E/0x100F) и завершающее
нулевое слово загрузочной таблицы. Сохранение параметров повреждает эту
часть образа для последующей загрузки. Это установленный дефект образа;
причину таймаута на конкретной плате нужно подтвердить повторной проверкой.

В исправлении временный снимок RS перенесён со стека в статический буфер:
обработчики RS вызываются последовательно из main, а перед возвратом
снимок полностью кодируется в собственный буфер UART. CAN имеет свой буфер.
Сборка `build_logger.ps1` использует параметры CCS Debug (-O1, speed=3)
и создаёт отдельный `Bin/LoggerEepromFix/UKSSTMS320F28335_logger_eeprom_fix.bin`.
Проверенный размер — 32494 байта, запас до параметров — 14 байт.

Оба сценария сборки вызывают `check_firmware.ps1` до публикации BIN.
Проверяются размер, формат SCI8, полнота блоков и конец загрузочной таблицы.
При превышении границы остаётся только файл `.pending`; готовый BIN
не публикуется. Проверка: `python tests/ump_logger/test_firmware_image.py`.
После перепрошивки требуется проверка на плате; проверка на ПК её не заменяет.