refactor: merge protocol cores as SETProtocol

c/set-protocol/README.md

@@ -1,75 +1,81 @@
-# set-protocol
+# SETProtocol
 
-Единый переносимый протокол SET для новых устройств и SETGUI. Один и тот же
-прикладной кадр используется для управления, чтения общей карты, потоковой
-телеметрии и безопасной передачи прошивки через:
+Единое переносимое протокольное ядро SET для `SETGUI`, Android GUI, устройств
+и сервисных утилит. В одном C99-проекте собраны:
 
-- RS-232 и RS-485;
-- USB CDC;
-- CAN с сегментацией;
-- Ethernet TCP;
-- Ethernet UDP, когда нужен обмен без соединения.
+- SET protocol v2 для управления, карты данных, телеметрии и firmware flow;
+- совместимый ProtoCAN transport для существующих CAN-мостов;
+- SETGUI transport v1 для приборов переходного периода;
+- стабильный host ABI для Python/JNI/других FFI;
+- GAS, кольцевые буферы, CRC и потоковые parser.
 
-Протокол не привязан к HAL, ОС или микроконтроллеру. Реализация на C99 не
-использует динамическую память. Все многобайтные значения little-endian.
+Ядро не зависит от HAL, ОС или конкретного адаптера, не использует
+динамическую память и не открывает COM/CAN само. SLCAN, SocketCAN, USB CDC,
+TCP, UART/DMA и аппаратный CAN подключаются портами.
 
-## Что уже реализовано
+## Структура
 
-| Файл | Назначение |
+| Каталог | Назначение |
 |---|---|
-| `set_protocol.*` | кадр v2, CRC32, потоковый parser, статусы ответов |
-| `set_can.*` | extended CAN ID, сегментация, flow-control и reassembly timeout |
-| `set_firmware.*` | BEGIN/DATA/END/STATUS, resume, CRC блока, SHA-256 и подпись |
-| `set_telemetry.*` | подписки и типизированные push-пакеты с timestamp |
-| `PROTOCOL.md` | обязательный wire-контракт и привязки к носителям |
-| `MIGRATION.md` | порядок перехода SETGUI и существующих прошивок с v1 |
-| `PORTING.md` | подключение UART, CAN, USB и Ethernet |
-| `tests/` | host-тесты и фиксированный эталонный кадр |
-
-Файл [`PROTOCOL.md`](PROTOCOL.md) является источником истины. Числа из него
-нельзя менять без выпуска следующей версии протокола.
-
-## Минимальный stream-приёмник
-
-```c
-#include "set_protocol.h"
-
-static setp_parser_t parser;
-
-static void on_frame(const setp_frame_t *frame, void *user)
-{
-    (void)user;
-    /* frame->payload действует только до возврата из callback. */
-}
-
-void protocol_init(void)
-{
-    setp_parser_init(&parser);
-}
-
-void protocol_feed(const uint8_t *data, uint16_t length)
-{
-    (void)setp_parser_feed(&parser, data, length, on_frame, NULL);
-}
-```
-
-Для RS-232, RS-485, USB CDC и TCP в parser передаются любые принятые chunks.
-Для UDP один UDP payload должен содержать ровно один полный SETP-кадр.
+| `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` | подключение новых транспортов и платформ |
 
 ## Сборка
 
-```text
-cmake -B build
-cmake --build build
-ctest --test-dir build
+```bash
+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
 ```
 
-Либо добавьте три файла из `src/` и каталог `include/` непосредственно в
-проект прошивки.
+CMake создаёт:
 
-## Версии
+- `setprotocol_static` — статическое C99-ядро;
+- совместимую CMake-цель `set_protocol`;
+- `setprotocol.dll`, `libsetprotocol.so` или `libsetprotocol.dylib`;
+- тесты SET v2, ProtoCAN transport, GUI v1 и ABI.
 
-- GUI protocol v1 остаётся только переходным форматом старых устройств.
-- Все новые устройства используют SET protocol v2 (`SETP_VERSION = 2`).
-- v1 и v2 имеют одинаковый SOF `A5 5A`, поэтому номер версии проверяется до
-  разбора остальных полей.
+Упрощённая host-сборка:
+
+```powershell
+python c/set-protocol/tools/build_host.py --output native/setprotocol.dll
+```
+
+```bash
+python3 c/set-protocol/tools/build_host.py --output native/libsetprotocol.so
+```
+
+## Подключение в C
+
+Для всего ядра:
+
+```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`](../../doc/setprotocol.html).