templates/c/set-protocol/docs/GUI_TRENDS.md

Общие тренды для Android GUI и SETGUI

Модуль задаёт совместимые настройки и числовые источники графиков. Он не рисует экран, не открывает файлы или порты и не управляет прошивкой устройства.

Слои: GUI → Kotlin/Python adapter → set_trends.c → уже разобранные кадры. Транспорт, таймер опроса, выбор файла, хранение настроек и Canvas/Qt остаются в приложении. У ядра нет callbacks, динамической памяти или глобального состояния.

Файл	Назначение и зависимости
include/set_trends.h, src/set_trends.c	C99: фильтрация GAS/raw CAN, signed/unsigned word, payload подписки SET GUI; использует pcan_id и ABI export macro
ports/android/kotlin/ru/setcorp/setprotocol/trends/	Модель, валидация JSON, ограниченная история, GAS_WATCH; JVM + org.json, без Android/Compose
ports/android/setprotocol_jni.c	Только преобразование JNI-аргументов
python/protocan/trends.py	Модель, JSON, история и NativeTrends; Python 3.9+, stdlib, без Qt
tests/fixtures/trends-v1.json	Один образец для тестов обоих GUI и обмена настройками

Формат файла

UTF-8 JSON: format = "setflash-trends", version = 1, profiles — словарь. Ключи профилей стабильны: TMS2812, SET_V1, CAN_BRIDGE, GS_USB_CAN, SLCAN, CANGAROO_SLCAN, BALZAM_CAN. Приложение явно сопоставляет своё подключение с этим ключом; импорт не меняет подключение.

Поля сигнала обязательны: id, order, name, source, address, color, visible, valueType, deviceType, device, byteOffset, extended. id уникален во всём файле. order — 1…9999, уникален внутри профиля. name — непустое изменяемое имя (до 100 символов), color — #RRGGBB. visible управляет только отрисовкой, не сбором. История и соединение в файл не входят. Максимум 64 сигнала на профиль и 1 МиБ на файл. Неизвестные версии, профили, источники и неверные значения отклоняются до замены настроек.

Профиль / источник	Адрес и значение
TMS2812 / TMS_MEMORY	32-битный адрес слова, CMD_PEEK; контроллер из подключения
SET_V1 / SET_GAS	16-битный GAS; GAS_WATCH_SET 0x12, DATA 0x13
SET_V1 / SET_SENSOR	ROM DS18B20, 16 HEX-цифр (дефисы допустимы), °C
Современные CAN / CAN_GAS	GAS 0…65535, DeviceType 0…7, DeviceID 0…15
Все CAN / CAN_RAW	CAN ID, STD/EXT, byteOffset 0…6; слово Little-endian

Числовые адреса — десятичные либо HEX с 0x. Регистры трактуются как UINT16 или INT16. Для RAW/CAN_GAS C-функция возвращает значение либо SET_TREND_NO_VALUE, никогда не подставляет ноль вместо отсутствующего кадра.

CAN — пассивный приём, без записи GAS и автоматической отправки запросов. GAS принимает только входящие FROM_DEVICE; TX/RTR/ошибки исключены. SET GUI оформляет подписку в порядке адресов. ACK должен подтвердить весь список: при частичном принятии нельзя определить пропущенные адреса, поэтому строить график по смещённым индексам запрещено. При паузе порт приложения отправляет подписку с периодом 0, когда транспорт доступен и не занят прошивкой.

Быстрый старт SETGUI

from protocan.native import NativeProtocol
from protocan.trends import TrendSignal, NativeTrends, encode_settings

core = NativeProtocol()  # библиотека, пересобранная с set_trends.c
decoder = NativeTrends(core.lib)
signal = TrendSignal("current", source="CAN_GAS", address="0x1235")
text = encode_settings({"CAN_BRIDGE": [signal]})
value = decoder.can_value(signal, 0x1FD31234, 1, bytes([1, 0, 254, 255]))
assert value == 65534.0
# GUI сохраняет text выбранным способом и передаёт value своему графику.

Android подключает Kotlin-каталог напрямую через Gradle и C-файлы через NDK. Приложение SETGUI может импортировать модуль через уже используемый путь third_party/templates/python; в этом изменении его экран не изменяется. После публикации новой ревизии templates оба проекта должны обновить сабмодуль и пересобрать собственные native-библиотеки — вручную копировать реализации не нужно.

Проверки

• CMake/CTest: shared_trends, плюс существующие protocol/ABI тесты.
• JVM: TrendSettingsJsonTest, GuiGasWatchTest; один JSON fixture с Python.
• Python: PYTHONPATH=python python -m unittest discover -s python/tests. Для проверки настоящего C-декодера задайте SETPROTOCOL_LIBRARY путём DLL/SO.