Обновлено описание

Author: KirillHit

README.md

@@ -1,5 +1,114 @@
-# object314_low_level_protocol
-Протокол связи нижнего уровня управления проекта "Объект 314"
+# CSUP
 
-Возможные доработки:
-- nibble-wise CRC
+**CSUP (Cross-platform Safe UART Protocol)** - лёгкий, надёжный, кроссплатформенный протокол обмена данными поверх UART, предназначенный для встраиваемых систем.
+
+Протокол обеспечивает безопасную передачу данных между устройствами, защищая сообщения от потерь, искажений и коллизий с помощью подтверждений и проверки целостности.
+
+## Основные функции
+
+* **Проверка целостности данных** - CRC-16 (алгоритм *CCITT-FALSE*).
+* **Подтверждение доставки (ACK)** - гарантирует успешную передачу сообщений.
+* **Обнаружение и разрешение коллизий** - если оба устройства отправляют данные одновременно.
+* **Системное сообщение HEARTBEAT** - проверка активности соединения и синхронизация передачи.
+* **Фиксированный внутренний буфер** - исключает динамическое выделение памяти.
+* **Минимальный накладной размер** - протокол увеличивает длину сообщения на 6 байт.
+
+Полное описание структуры сообщений, типов системных сообщений и кодов результата доступно в файле: [`docs/protocol.md`](./docs/protocol.md).
+
+## Структура библиотеки
+
+| Папка                  | Описание                                                        |
+| ---------------------- | --------------------------------------------------------------- |
+| `csup/hal/`            | Абстракции аппаратного слоя (UART, таймеры, типы)               |
+| `csup/hal/<platform>/` | Реализация HAL для конкретной платформы (Arduino, Linux и т.д.) |
+| `csup/protocol/`       | Реализация протокола CSUP, включая COBS и структуру сообщений   |
+| `csup/utils/`          | Утилиты для работы с буферами и проверки целостности            |
+| `csup/definitions.hpp` | Общие определения                                               |
+| `csup/csup.hpp`        | Основной заголовочный файл библиотеки                           |
+
+## Кроссплатформенность
+
+Вся логика протокола CSUP построена на интерфейсах, определяемых через **HAL (Hardware Abstraction Layer)**. Это позволяет использовать протокол на любой платформе, для которой реализована HAL-обёртка.
+
+На данный момент поддерживаются **Arduino** и **Linux**.
+
+Пользователь может создавать собственные обёртки для UART и таймера, а затем выбирать их при создании экземпляра протокола:
+
+```cpp
+template <typename Uart = hal::DefaultUart,
+          typename Time = hal::DefaultTime,
+          typename Crc = CRC16_CCITT_FALSE,
+          CollisionBehavior Collision = CollisionBehavior::BALANCED,
+          types::size MaxMsgSize = 256>
+class Protocol;
+```
+
+Таким образом один и тот же код протокола может работать на разных платформах без изменений, используя соответствующие реализации HAL.
+
+## Установка
+
+CSUP — это **заголовочная библиотека**, не требующая сборки.
+
+Для установки достаточно скопировать папку `csup` в каталог с заголовочными файлами вашего проекта или в стандартный путь поиска компилятора.
+
+После этого вы сможете подключать библиотеку в коде:
+
+```cpp
+#include <csup/csup.hpp>
+```
+
+## Примеры использования
+
+В папке `examples/` содержатся готовые примеры работы протокола CSUP для различных платформ.
+
+Простой пример для Linux:
+
+```cpp
+#include "csup/csup.hpp"
+#include <iostream>
+#include <thread>
+
+int main()
+{
+    csup::hal::UartConfig cfg;
+    cfg.device = "/dev/ttyUSB0";
+
+    csup::Result result;
+    
+    csup::Protocol<> csup;
+
+    result = csup.start(cfg);
+    if (result != csup::Result::SUCCESS)
+    {
+        std::cerr << "Failed to start CSUP\n";
+        return -1;
+    }
+
+    // Send a simple message with ACK
+    uint8_t data[10] = {0,1,2,3,4,5,6,7,8,9};
+    csup::BufferView buf(data, sizeof(data));
+    result = csup.send(0x10, buf, true);
+    if (result != csup::Result::SUCCESS)
+    {
+        std::cerr << "Send error\n";
+        return -1;
+    }
+
+    // Receive a response
+    csup::BufferView recv;
+    uint8_t type;
+    result = csup.receive(type, recv);
+    if (result != csup::Result::SUCCESS)
+    {
+        std::cerr << "Receive error\n";
+        return -1;
+    }
+    
+    std::cout << "Received message of type " << int(type) << "\n";
+
+    // Check connection
+    csup.heartbeat();
+
+    csup.stop();
+}
+```

csup/definitions.hpp

@@ -9,24 +9,33 @@ namespace csup {
 
 enum class Result : types::u8
 {
-    SUCCESS = 0x00,
-    UART_ERROR = 0x01,
-    COBS_ERROR = 0x02,
-    TIMEOUT = 0x03,
-    OVERFLOW = 0x04,
-    EMPTY_MSG = 0x05,
-    CRC_ERROR = 0x06,
-    WRONG_MSG_TYPE = 0x07,
-    WRONG_MSG_SIZE = 0x08,
-    MSG_COLLISION = 0x09,
-    MAX_ATTEMPT = 0x0A,
+    // 0x0X — Success
+    SUCCESS = 0x00,  // Operation completed successfully
+
+    // 0x1X — Transport / Hardware errors
+    UART_ERROR = 0x10,  // UART communication failure
+    TIMEOUT = 0x11,  // Response timeout
+    OVERFLOW = 0x12,  // Buffer overflow
+
+    // 0x2X — Message format / integrity errors
+    COBS_ERROR = 0x20,  // COBS decoding error
+    CRC_ERROR = 0x21,  // CRC check failed
+    EMPTY_MSG = 0x22,  // Received empty message
+    WRONG_MSG_TYPE = 0x23,  // Message type mismatch
+    WRONG_MSG_SIZE = 0x24,  // Message size mismatch
+    SYS_MSG_HANDLED = 0x25,  // System message processed
+    DUPLICATE_MSG = 0x26,  // Duplicate message received
+
+    // 0x3X — Protocol / logical errors
+    MSG_COLLISION = 0x30,  // Message collision detected
+    MAX_ATTEMPT = 0x31,  // Maximum retransmission attempts reached
 };
 
 enum class SystemMsgType : types::u8
 {
     ACK = 0xE0,
-    VERSION_CHECK = 0xE1,
-    HEARTBEAT = 0xE2,
+    HEARTBEAT = 0xE1,
+    VERSION_CHECK = 0xE2,
 };
 
 /**

csup/protocol/protocol.hpp

@@ -106,14 +106,14 @@ class Protocol
             // Skip HEARTBEAT frames
             if (frame.header.type.value == static_cast<types::u8>(SystemMsgType::HEARTBEAT))
             {
-                result = Result::WRONG_MSG_TYPE;
+                result = Result::SYS_MSG_HANDLED;
                 continue;
             }
 
             // Skip duplicate
             if (frame.header.ack.frame_id == last_received_frame_id_)
             {
-                result = Result::WRONG_MSG_TYPE;
+                result = Result::DUPLICATE_MSG;
                 continue;
             }
 
@@ -148,6 +148,9 @@ class Protocol
                 const types::u8& retries = 3,
                 const types::u32& timeout = 200)
     {
+        if (type >= 0xE0)
+            return Result::WRONG_MSG_TYPE;
+
         tp::DataFrame frame;
         frame.header.type = type;
         frame.header.ack.ack_required = ack;
@@ -182,6 +185,17 @@ class Protocol
     /**
      * @brief Sends a heartbeat message.
      * 
+     * This message can be used to synchronize transmission, since all messages
+     * sent before a successful acknowledgment are skipped until confirmed.
+     *
+     * @note If the remote side currently has a message transmission that requires
+     * acknowledgment, sending a heartbeat will not break it. The pending data
+     * will simply be retransmitted if retries remain.
+     *
+     * @note To receive acknowledgment for this heartbeat on the remote side, the
+     * receiver must call `receive()`, `send()` with acknowledgment, or another
+     * `heartbeat()`.
+     * 
      * @return Result::SUCCESS if successful, otherwise error code.
      */
     Result heartbeat()
@@ -252,7 +266,7 @@ class Protocol
                 send_ack(data_header.ack.frame_id);
                 if (type == static_cast<types::u8>(SystemMsgType::HEARTBEAT))
                     continue;
-                return Result::WRONG_MSG_TYPE;
+                return Result::SYS_MSG_HANDLED;
             }
             else if (data_header.ack.ack_required)  // Collision
             {