templates/c/set-protocol/README.md

SETProtocol

Единое переносимое протокольное ядро SET для SETGUI, Android GUI, устройств и сервисных утилит. В одном C99-проекте собраны:

• SET protocol v2 для управления, карты данных, телеметрии и firmware flow;
• совместимый ProtoCAN transport для существующих CAN-мостов;
• SETGUI transport v1 для приборов переходного периода;
• стабильный host ABI для Python/JNI/других FFI;
• GAS, кольцевые буферы, CRC и потоковые parser.

Ядро не зависит от HAL, ОС или конкретного адаптера, не использует динамическую память и не открывает COM/CAN само. SLCAN, SocketCAN, USB CDC, TCP, UART/DMA и аппаратный CAN подключаются портами.

Структура

Каталог	Назначение
include/set_*.h	публичный SET protocol v2
include/pcan_*.h, gui_*.h	совместимые ProtoCAN/GUI v1 модули
include/setprotocol.h	единая C99-точка включения
include/setprotocol_abi.h	стабильная FFI-точка включения ABI v1
src/	общая реализация всех протокольных модулей
ports/android	JNI и Kotlin facade
ports/stm32f4	UART/DMA port для legacy byte stream
docs/SETPROTOCOL.md	архитектура, ABI, память и переносимость
docs/legacy	нормативные документы ProtoCAN/SETGUI v1
PROTOCOL.md	нормативный wire contract SET protocol v2
MIGRATION.md	переход с v1/ProtoCAN на v2
PORTING.md	подключение новых транспортов и платформ

Сборка

cmake -S c/set-protocol -B build/setprotocol -DSETP_BUILD_TESTS=ON
cmake --build build/setprotocol --config Release
ctest --test-dir build/setprotocol -C Release --output-on-failure

CMake создаёт:

• setprotocol_static — статическое C99-ядро;
• совместимую CMake-цель set_protocol;
• setprotocol.dll, libsetprotocol.so или libsetprotocol.dylib;
• тесты SET v2, ProtoCAN transport, GUI v1 и ABI.

Упрощённая host-сборка:

python c/set-protocol/tools/build_host.py --output native/setprotocol.dll

python3 c/set-protocol/tools/build_host.py --output native/libsetprotocol.so

Подключение в C

Для всего ядра:

#include "setprotocol.h"

Для минимальной прошивки можно подключать только нужные заголовки и исходники. Например, новый v2 stream parser использует set_protocol.*, а legacy CAN-мост — pcan_frame.*, pcan_crc.* и pcan_id.*.

FFI-клиенты подключают setprotocol_abi.h. Имена функций pcan_abi_* сохраняются в ABI v1 для бинарной совместимости; переименование символов без повышения версии ABI запрещено.

Версии wire format

• SET protocol v2 — основной формат новых устройств.
• SETGUI v1 и ProtoCAN bridge остаются поддерживаемыми на время миграции.
• Одинаковый SOF A5 5A у GUI v1 и SET v2 различается полем версии.
• Изменение wire contract требует новой версии и тестовых векторов.

Полная интерактивная документация: ../../doc/setprotocol.html.