templates/c/set-protocol/README.md

set-protocol

Единый переносимый протокол SET для новых устройств и SETGUI. Один и тот же прикладной кадр используется для управления, чтения общей карты, потоковой телеметрии и безопасной передачи прошивки через:

• RS-232 и RS-485;
• USB CDC;
• CAN с сегментацией;
• Ethernet TCP;
• Ethernet UDP, когда нужен обмен без соединения.

Протокол не привязан к HAL, ОС или микроконтроллеру. Реализация на C99 не использует динамическую память. Все многобайтные значения little-endian.

Что уже реализовано

Файл	Назначение
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 является источником истины. Числа из него нельзя менять без выпуска следующей версии протокола.

Минимальный stream-приёмник

#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-кадр.

Сборка

cmake -B build
cmake --build build
ctest --test-dir build

Либо добавьте три файла из src/ и каталог include/ непосредственно в проект прошивки.

Версии

• GUI protocol v1 остаётся только переходным форматом старых устройств.
• Все новые устройства используют SET protocol v2 (SETP_VERSION = 2).
• v1 и v2 имеют одинаковый SOF A5 5A, поэтому номер версии проверяется до разбора остальных полей.