Добавить общие графики, декодер KONOR и порт STM32 bxCAN

c/set-protocol/docs/GUI_TRENDS.md

@@ -0,0 +1,78 @@
+# Общие тренды для 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
+
+```python
+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.