Единое ядро форматов
Windows, Android и MCU больше не реализуют CRC, порядок байт и ресинхронизацию каждый по-своему.
Что такое ядро
SETProtocol — не драйвер адаптера и не GUI framework. Это детерминированная протокольная часть, одинаковая для каждой программы и платы.
ПриложениеSETGUI · Android · CLI · firmware
→
SETProtocolSET v2 · ProtoCAN · GUI v1 · GAS
→
ПортCOM · SLCAN · SocketCAN · USB · HAL
Узкая платформенная граница
Смена COM на SocketCAN заменяет адаптер ввода-вывода, но не декодер протокола и не тестовые векторы.
Контролируемая совместимость
FFI использует публичный setprotocol_abi.h версии 1; внутренние C-структуры наружу не протекают.
Про скорость: значение
500000 у COM — скорость последовательного интерфейса адаптера. CAN bitrate на линии задаётся отдельно в адаптере/драйвере. SETProtocol получает уже доставленные байты или CAN-кадры.Про сниферы: SLCAN, SocketCAN, CANable и vendor-адаптеры должны нормализовать вход в
can_id + flags + data. После этого таблица, фильтры и ProtoCAN-декодер общие.Слои и модули
Нижний слой не знает, кто его вызвал. Верхний слой не должен знать внутреннюю раскладку parser context.
Идентификатор
pcan_id упаковывает Priority, Route, DeviceType, DeviceID, MsgType и Body в Extended ID без непереносимых bit-fields.
Полевой поток
pcan_frame кодирует и разбирает AA55; pcan_crc даёт CRC16; pcan_link ведёт SEQ и статистику.
GUI-поток
gui_frame реализует отдельный A55A transport с payload до 512 байт и CRC32.
Данные прибора
pcan_gas входит в shared core и отображает данные в 16-битное пространство. gui_catalog — опциональный C-модуль вне DLL.
Буферизация
pcan_ring — SPSC-кольцо с непрерывным участком, удобным для DMA. Размер буфера — степень двойки.
Граница языков
pcan_abi экспортирует только скалярные значения и буферы известных размеров для ctypes/JNI/Swift.
Что намеренно не входит
| Вне ядра | Почему | Где реализовать |
|---|---|---|
| COM/SLCAN/SocketCAN | ОС и конкретный адаптер | desktop/android port |
| CAN bitrate и UART baud | Настройка физического интерфейса | driver/config UI |
| HAL, IRQ, DMA | Зависят от MCU и SDK | ports/<platform> |
| Вкладки и графики | Представление, не протокол | SETGUI / Android GUI |
| Firmware A/B flow | Отдельная предметная библиотека | protocan-boot |
Три wire format
SET v2 — основной протокол новых устройств. ProtoCAN bridge и GUI v1 остаются для совместимости на время перехода.
SET protocol v2 · A5 5A 02
A5 5A02 FLAGSTYPE LESOURCE/DEST LESEQ/SIZE LEPAYLOAD 0..512CRC32 LE
Единый кадр для управления, телеметрии и firmware flow поверх serial, USB, Ethernet и сегментированного CAN.
CAN bridge · AA 55
AA 55LENSEQFLAGSCAN_ID LEDATA 0..8CRC16 LE
LEN = 6 + DLC, максимум 19 байт. CRC-16/CCITT-FALSE считается от LEN до DATA.
GUI transport · A5 5A
A5 5AVERTYPESEQ BESIZE BEPAYLOAD 0..512CRC32 LE
Версия 1. CRC32 IEEE как у zlib. Это самостоятельный протокол, не CAN DLC.
Chunk-safe
Parser принимает один байт, половину кадра или несколько кадров подряд. Граница read() не имеет протокольного смысла.
Самосинхронизация
После шума parser снова ищет SOF, отбрасывает неверную длину/CRC и продолжает поток, сохраняя диагностические счётчики.
29-битный ProtoCAN ID
Priority 1Route 1DeviceType 3DeviceID 4MsgType 4MsgBody 16
Биты 28…0 упаковываются масками и сдвигами. Это исключает зависимость от реализации C bit-fields.
Стабильный C ABI v1
Приложение сначала проверяет версию, затем работает через функции из pcan_abi.h. Внутренние структуры можно менять, сохраняя ABI.
| Группа | Функции | Контракт |
|---|---|---|
| Версия и ID | version, id_pack, id_unpack | Скалярные аргументы, 29-битный результат |
| CAN frame | crc16, frame_encode | Caller-owned input/output buffers |
| CAN parser | parser_size/init/push/stats | Opaque caller-owned context |
| GUI frame | gui_crc32, gui_frame_encode | Payload не более 512 байт |
| GUI parser | gui_parser_size/init/push/stats | Opaque caller-owned context |
Без malloc
Ядро не выделяет память. Python использует create_string_buffer, MCU — static/stack, JNI хранит allocation только в адаптере.
Без global parser
Каждая линия имеет собственный context. Можно одновременно держать COM bridge, GUI transport и несколько устройств.
Явное владение
Один context — один владелец потока. Если владельцев несколько, блокировку добавляет приложение.
size_t bytes = pcan_abi_parser_size();
void *context = allocate_on_host_or_static_storage(bytes);
pcan_abi_parser_init(context, bytes);
if (pcan_abi_parser_push(context, next_byte, &frame) == 1) {
/* frame полностью проверен */
}Матрица переносимости
Переносимость ядра и готовность полной упаковки приложения — разные вещи. Здесь они разделены честно.
| Цель | Библиотека | Адаптер | Статус |
|---|---|---|---|
| Windows | setprotocol.dll | Python ctypes / COM | проверено |
| Android | libsetprotocol.so | JNI + Kotlin | 4 ABI |
| Linux | libsetprotocol.so | ctypes; нужен pyserial/SocketCAN port | ядро готово |
| macOS | libsetprotocol.dylib | ctypes/FFI | исходники готовы |
| STM32F4 | статический C99 | UART + DMA | порт есть |
| Другой MCU | статический C99 | I/O callbacks | нужен порт |
| iOS | C ABI | Swift wrapper | не добавлен |
Linux-путь: собрать
libsetprotocol.so, указать SETPROTOCOL_LIBRARY, затем добавить backend физической линии. Для прямого CAN логичен SocketCAN; для USB-COM моста — pyserial.Сборка и подключение
CMake создаёт static core, shared ABI и тесты из одного набора C99-файлов.
Зафиксировать templates
Подключить репозиторий как Git submodule и зафиксировать проверенный commit.
Собрать ядро
На host — CMake или build_host.py; на Android — NDK; на MCU — добавить исходники в проект.
Подключить порт
COM, SLCAN, SocketCAN, USB или HAL только доставляет данные через узкую границу.
Прогнать quality gate
C tests, ABI vectors, Python native tests, Android build и smoke-test реальной линии.
CMake
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-failureLinux host tool
python3 c/set-protocol/tools/build_host.py \
--output native/libsetprotocol.so
export SETPROTOCOL_LIBRARY="$PWD/native/libsetprotocol.so"Python
from protocan.native import NativeProtocol
core = NativeProtocol()
wire = core.encode(1, 1, 0x1234567, b"\xAA\xBB")
frames = core.parser().feed(wire)Полный справочник
Этот раздел генерируется из канонического c/set-protocol/docs/SETPROTOCOL.md. Редактировать нужно Markdown, затем запускать doc/build-setprotocol-html.ps1.
SETProtocol — переносимое протокольное ядро
SETProtocol — общее C99-ядро для SETGUI, Android GUI, прошивок и утилит.
Оно объединяет основной SET protocol v2 и поддерживаемые форматы переходного
периода: ProtoCAN bridge и SETGUI transport v1. Windows, Linux, Android и
микроконтроллер используют одинаковые правила кадра, CRC, адресации,
телеметрии, обновления и потокового разбора.
Ядро не открывает COM-порт, CAN-адаптер или сокет. COM, SLCAN, SocketCAN, USB CDC, TCP и аппаратный CAN относятся к портам. Они доставляют байты или CAN-кадры, а SETProtocol проверяет и интерпретирует их одинаково на всех платформах.
1. Граница ответственности
SETGUI / Android GUI / CLI / firmware
│ прикладные команды и события
▼
Python facade / JNI / прямой C API
│ стабильный ABI или C99 API
▼
┌──────────────────────── SETProtocol ────────────────────────┐
│ SET v2 │ ProtoCAN ID │ v1 parsers │ CRC │ GAS │ telemetry │
└─────────────────────────────────────────────────────────────┘
│ байты или нормализованный CAN frame
▼
COM │ SLCAN │ SocketCAN │ USB CDC │ TCP │ STM32 UART/CAN
В ядре находятся:
- форматы проводных кадров и порядок байт;
- SET protocol v2: команды, адресация, подписки и firmware state machines;
- проверка длины, версии, DLC и контрольной суммы;
- восстановление синхронизации после мусора или оборванного кадра;
- упаковка и разбор ProtoCAN Extended ID;
- счётчики качества входного потока;
- общее адресное пространство регистров (GAS);
- стабильная C ABI-граница для
ctypes, JNI и будущего Swift/FFI.
За пределами ядра остаются:
- поиск устройств и выбор
COM6,can0или Bluetooth/USB endpoint; - скорость UART и CAN bitrate;
- драйверы SLCAN, SocketCAN, PCAN, CANable и vendor SDK;
- разрешения Android USB и жизненный цикл приложения;
- виджеты, вкладки, таблицы, графики и хранение настроек;
- HAL, IRQ, DMA, RTOS, Flash и распиновка платы.
Отсюда следует важное правило: 500000 на экране COM — это baud rate последовательного моста, а 500 kbit/s в CAN-настройках — bitrate самой CAN-шины. Ядро не подменяет одно другим и не выбирает эти значения автоматически.
2. Состав исходников
| Модуль | Роль | Платформенные зависимости |
|---|---|---|
set_protocol |
SET v2 frame, CRC32, stream/datagram parser | нет |
set_can |
CAN segmentation, flow control и reassembly | доставка CAN frame и время |
set_telemetry |
подписки и типизированные PUBLISH-пакеты | часы/callbacks приложения |
set_firmware |
BEGIN/DATA/END/STATUS и resume state machine | Flash/verify/reboot backend |
pcan_id |
Упаковка/разбор 29-битного ProtoCAN ID | нет |
pcan_crc |
CRC-16/CCITT-FALSE | нет |
pcan_frame |
Формат AA 55, encode и потоковый parser |
нет |
gui_frame |
Формат A5 5A, CRC32, encode, parser и link |
нет |
pcan_link |
Экземпляр канала, SEQ, RX/TX и статистика | два callback порта |
pcan_ring |
SPSC-кольцо и непрерывный участок для DMA | нет |
pcan_gas |
Карта 16-битных регистров и bridge к кадрам | callbacks региона |
gui_catalog |
C-каталог публикуемых GUI-полей | нет; входит в общий shared build |
pcan_abi |
Экспорт скалярного ABI для FFI | ABI компилятора C |
Общая точка включения для C-кода — include/setprotocol.h.
Иностранные runtimes должны использовать include/setprotocol_abi.h, а не
повторять внутреннюю раскладку pcan_parser_t или gui_parser_t.
Shared-библиотека setprotocol содержит SET v2 и совместимые legacy-модули.
ABI v1 пока экспортирует функции pcan_abi_*: имена намеренно сохранены для
бинарной совместимости SETGUI/Android. Расширение ABI для прямого SET v2 FFI
должно быть совместимым добавлением или новой версией ABI.
3. Три поддерживаемых wire format
SETProtocol поддерживает основной v2 и два legacy-формата. После первого корректного ответа формат соединения фиксируется до отключения.
3.1. CAN bridge: AA 55
AA 55 | LEN | SEQ | FLAGS | CAN_ID[4] LE | DATA[0..8] | CRC16 LE
LEN = 6 + DLC, поэтому допустимый диапазон — 6..14. CRC-16/CCITT-FALSE
считается по участку от LEN до последнего байта DATA. Максимальный размер
кадра — 19 байт. Формат переносит один classic CAN 2.0 кадр через COM, USB CDC,
RS-232, RS-485 или TCP byte stream.
Флаги:
| Бит | Имя | Значение |
|---|---|---|
| 0 | IDE |
расширенный 29-битный CAN ID |
| 1 | RTR |
remote frame |
| 2 | DIR |
0 из CAN в host, 1 из host в CAN |
| 3 | ERR |
служебный кадр диагностики моста |
3.2. GUI transport: A5 5A
A5 5A | VER | TYPE | SEQ[2] BE | SIZE[2] BE | PAYLOAD[0..512] | CRC32 LE
Версия сейчас равна 1. Заголовочные SEQ и SIZE идут big-endian, CRC32
IEEE — little-endian. Payload до 512 байт нужен для каталога, чтения/записи
регистров, диагностики и потока значений. Это не CAN-кадр и у него нет DLC.
Оба parser принимают произвольные chunks: один вызов может содержать половину
кадра, несколько кадров или мусор между ними. Границы read() не считаются
границами протокольных сообщений.
3.3. SET protocol v2: A5 5A 02
A5 5A | VER=02 | FLAGS | TYPE u16 LE | SOURCE u16 LE | DEST u16 LE |
SEQ u16 LE | SIZE u16 LE | PAYLOAD[0..512] | CRC32 LE
Это основной формат новых устройств. Он одинаков поверх RS-232/485, USB CDC,
TCP и UDP; CAN переносит байты полного v2-кадра через сегментацию. В v2
объединены запросы/ответы, события телеметрии и firmware flow. Нормативный
контракт находится в PROTOCOL.md.
4. ProtoCAN Extended ID
28 27 26..24 23..20 19..16 15..0
Priority | Route | DeviceType | DeviceID | MsgType | MsgBody
Для переносимости используются маски и сдвиги, а не C bit-fields. ABI-функции
pcan_abi_id_pack() и pcan_abi_id_unpack() дают одинаковую раскладку при
MSVC, GCC и Clang.
5. Стабильный ABI v1
pcan_abi.h экспортирует простые числа, указатели и явно ограниченные буферы.
Текущая версия возвращается pcan_abi_version() и равна 1.
CAN bridge API
| Функция | Назначение |
|---|---|
pcan_abi_version |
Проверить совместимость загруженной библиотеки |
pcan_abi_id_pack/unpack |
Преобразовать поля ProtoCAN ID |
pcan_abi_crc16 |
Рассчитать CRC-16/CCITT-FALSE |
pcan_abi_frame_encode |
Собрать целый AA55 кадр |
pcan_abi_parser_size |
Узнать размер opaque parser context |
pcan_abi_parser_init |
Инициализировать память, принадлежащую вызывающему |
pcan_abi_parser_push |
Передать один байт; 1 означает готовый кадр |
pcan_abi_parser_stats |
Получить frames/CRC/bad length/stray bytes |
GUI API
| Функция | Назначение |
|---|---|
pcan_abi_gui_crc32 |
Рассчитать CRC32 IEEE |
pcan_abi_gui_frame_encode |
Собрать целый A55A кадр |
pcan_abi_gui_parser_size/init/push |
Управлять opaque GUI parser context |
pcan_abi_gui_parser_stats |
Получить frames/CRC/version/length/stray bytes |
Возврат 0 из encode означает неверные аргументы или недостаточный output
buffer. Parser API возвращает отрицательное значение при неверном context,
0 пока кадр не собран и 1 при готовом кадре.
6. Память, состояние и многопоточность
В переносимом C-слое нет malloc, singleton и скрытого глобального parser.
Каждый канал имеет собственное состояние. В ABI вызывающий сначала спрашивает
его размер, выделяет байтовый блок и передаёт его в init.
size_t size = pcan_abi_parser_size();
void *storage = /* память вызывающей стороны размером size */;
pcan_abi_parser_init(storage, size);
Это позволяет:
- держать память статически на MCU;
- использовать
ctypes.create_string_buffer()в Python; - выделять handle только в JNI-адаптере;
- одновременно разбирать несколько независимых линий.
Один parser context нельзя одновременно изменять из нескольких потоков. Правильная модель — один владелец на канал или внешняя блокировка. Кольцевой буфер рассчитан на одного писателя и одного читателя (SPSC). Для нескольких писателей синхронизацию обеспечивает порт/приложение.
7. Порты и адаптеры
| Среда | Артефакт | Состояние |
|---|---|---|
| Windows desktop | setprotocol.dll + Python ctypes |
используется SETGUI, проверено тестами |
| Android | libsetprotocol.so + JNI + Kotlin facade |
сборка ABI arm64-v8a, armeabi-v7a, x86, x86_64 проверяется Android build |
| Linux desktop | libsetprotocol.so + тот же ABI |
ядро и сборщик готовы; нужен Linux CI/smoke-test приложения |
| macOS | libsetprotocol.dylib + тот же ABI |
исходники совместимы; отдельная упаковка не проверена |
| STM32F4 | прямой C99 + UART/DMA port | готовый порт в ports/stm32f4 |
| Другой MCU | прямой C99 | реализуются только callbacks I/O/времени/памяти |
| iOS/Swift | C ABI | ABI подходит, Swift wrapper пока не добавлен |
Linux
Само ядро не содержит WinAPI, поэтому собирается GCC или Clang. Для SETGUI под
Linux остаются две отдельные задачи: упаковать libsetprotocol.so с приложением и
подключить нужный физический backend (pyserial для USB-COM или SocketCAN для
can0). Правила кадра, CRC и ID менять не потребуется.
SLCAN и SocketCAN — порты снифера, а не новая реализация протокола:
SLCAN text / struct can_frame
│ adapter
▼
can_id + flags + data
│
▼
общий decoder/UI
8. Сборка
CMake: Windows, Linux, macOS
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
Результат shared-сборки называется setprotocol.dll, libsetprotocol.so или
libsetprotocol.dylib. Статическая цель называется setprotocol_static;
совместимое имя CMake-цели SET v2 — set_protocol.
Упрощённая 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
На Windows tool использует MSVC, на Unix ищет cc, clang или gcc.
Python
from protocan.native import NativeProtocol
core = NativeProtocol()
raw = core.encode(sequence=1, flags=1, can_id=0x1234567, data=b"\xAA\xBB")
frames = core.parser().feed(raw)
Если библиотека лежит вне стандартного дерева:
export SETPROTOCOL_LIBRARY=/opt/set/lib/libsetprotocol.so
В PowerShell:
$env:SETPROTOCOL_LIBRARY = 'C:\set\native\setprotocol.dll'
Android
ports/android/Android.mk компилирует те же C-файлы. Kotlin-класс
ru.setcorp.setprotocol.NativeSetProtocol отвечает только за удобный API, а JNI — за
преобразование типов и время жизни parser handle.
Микроконтроллер
Добавьте нужные src/*.c и каталог include/ в проект. Порт STM32F4 не входит
автоматически в host CMake, потому что ему нужен CMSIS. Для другой платы
реализуйте pcan_io_t.write и pcan_io_t.tx_space; ISR/DMA лишь складывает
байты, а pcan_link_feed() вызывается в безопасном контексте приложения.
9. Пример прямого ABI
#include "pcan_abi.h"
uint8_t output[19];
const uint8_t data[] = {0xAA, 0xBB};
const uint8_t flags = 0x01U; /* IDE */
uint32_t id = pcan_abi_id_pack(1, 0, 2, 3, 4, 0x1234);
size_t written = pcan_abi_frame_encode(
7, flags, id, data, sizeof(data), output, sizeof(output));
Для firmware удобнее полный C API из protocan_transport.h: он даёт link,
callbacks, ring и GAS без FFI-обёртки.
10. Диагностика
| Симптом | Что проверить |
|---|---|
crc_errors растёт |
bitrate/baud, ground, termination, порядок байт, потерю chunks |
bad_len/length_errors |
выбран ли правильный формат AA55 или A55A |
version_errors |
версия GUI transport должна быть 1 |
много stray_bytes |
начало чтения посреди пакета допустимо; постоянный рост означает неверный порт |
| DLL/SO не найдена | путь, архитектуру процесса и SETPROTOCOL_LIBRARY |
Android UnsatisfiedLinkError |
имя setprotocol, ABI устройства и упаковку jniLibs/NDK |
| CAN пустой, но COM открыт | COM baud не равен CAN bitrate; проверьте настройку самого адаптера |
11. Совместимость и ограничения
- ABI v1 изменяется только совместимым добавлением функций. Ломающее изменение
требует нового значения
PCAN_ABI_VERSION. - Wire format нельзя менять без версии/миграционного документа и тестовых векторов для C, Python и Android.
- CAN bridge сейчас рассчитан на classic CAN:
DLC <= 8; CAN FD не включён. - GUI payload ограничен 512 байтами; на MCU
GUI_RX_PAYLOAD_MAXможно уменьшить. - В ядре нет готового SocketCAN/SLCAN/vendor backend: это следующий слой портов.
- В ядро не входят виджеты GUI, настройки COM/CAN и обновление прошивки целиком.
Для firmware flow существует отдельная библиотека
protocan-boot.
12. Проверка изменений
Минимальный quality gate:
- CMake build и
ctestдляtest_transportиtest_abi. - Сверка машинных векторов
tests/vectors/test-vectors.json. - Python-тесты с обязательной загрузкой native core.
- Android unit tests и
assembleDebug, если менялись ABI/JNI/Kotlin. - Smoke-test целевого порта на реальной линии.
Канонический код находится в templates/c/set-protocol. Проекты должны
получать его как Git submodule и фиксировать конкретный commit, а не хранить
разошедшиеся копии.