# Общие тренды для 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.