Добавлено сообщение version_check

Author: KirillHit

README.md

@@ -47,7 +47,7 @@ class Protocol;
 
 ## Установка
 
-CSUP — это **заголовочная библиотека**, не требующая сборки.
+CSUP - это **заголовочная библиотека**, не требующая сборки.
 
 Для установки достаточно скопировать папку `csup` в каталог с заголовочными файлами вашего проекта или в стандартный путь поиска компилятора.
 

csup/definitions.hpp

@@ -7,6 +7,20 @@
 
 namespace csup {
 
+/**
+ * @brief CSUP protocol version definition.
+ *
+ * Semantic versioning format: MAJOR.MINOR.PATCH
+ *
+ * | Component  | Description                                     |
+ * |------------|-------------------------------------------------|
+ * | MAJOR      | Incompatible protocol changes.                  |
+ * | MINOR      | Backward-compatible feature additions.          |
+ * | PATCH      | Backward-compatible bug fixes and refinements.  |
+ */
+static constexpr types::u8 VERSION[3] = {1, 0, 0};
+
+/** @brief Result codes returned by CSUP protocol operations. */
 enum class Result : types::u8
 {
     // 0x0X — Success
@@ -29,8 +43,21 @@ enum class Result : types::u8
     // 0x3X — Protocol / logical errors
     MSG_COLLISION = 0x30,  // Message collision detected
     MAX_ATTEMPT = 0x31,  // Maximum retransmission attempts reached
+    VERSION_MISMATCH = 0x32,  // Protocol version mismatch
 };
 
+
+/**
+ * @brief Identifiers for system-level messages used by CSUP.
+ *
+ * Reserved range: 0xE0–0xEF.
+ *
+ * | Type           | Value  | Description                                                 |
+ * |----------------|--------|-------------------------------------------------------------|
+ * | ACK            | 0xE0   | Confirms successful frame reception.                        |
+ * | HEARTBEAT      | 0xE1   | Keep-alive signal indicating active connection.             |
+ * | VERSION_CHECK  | 0xE2   | Used to exchange and verify protocol version compatibility. |
+ */
 enum class SystemMsgType : types::u8
 {
     ACK = 0xE0,
@@ -44,18 +71,11 @@ enum class SystemMsgType : types::u8
  * Used when two nodes send frames simultaneously and both require acknowledgment.
  * Determines which side should resend or yield based on the selected policy.
  *
- * | Mode              | Description                                                      |
- * |-------------------|------------------------------------------------------------------|
- * | BALANCED          | Both sides decide based on frame ID (lower ID has priority).     |
- * | PRIORITY_SEND     | Always prioritizes sending; ignores incoming conflicting frame.  |
- * | NON_PRIORITY_SEND | Yields to the other sender when a collision is detected.         |
- * 
- * @note Compatibility Table:
- * | Mode              | Compatible with Modes  |
- * |-------------------|------------------------|
- * | BALANCED          | BALANCED               |
- * | PRIORITY_SEND     | NON_PRIORITY_SEND      |
- * | NON_PRIORITY_SEND | PRIORITY_SEND          |
+ * | Mode              | Compatible mode   | Description                                                      |
+ * |-------------------|-------------------|------------------------------------------------------------------|
+ * | BALANCED          | BALANCED          | Both sides decide based on frame ID (lower ID has priority).     |
+ * | PRIORITY_SEND     | NON_PRIORITY_SEND | Always prioritizes sending; ignores incoming conflicting frame.  |
+ * | NON_PRIORITY_SEND | PRIORITY_SEND     | Yields to the other sender when a collision is detected.         |
  */
 enum class CollisionBehavior : uint8_t
 {

csup/protocol/protocol.hpp

@@ -39,6 +39,8 @@ template <typename Uart = hal::DefaultUart,
           types::size MaxMsgSize = 256>
 class Protocol
 {
+    static_assert(MaxMsgSize >= sizeof(VERSION), "MaxMsgSize must be >= VERSION size");
+
 public:
     Protocol() = default;
     ~Protocol() = default;
@@ -100,11 +102,13 @@ class Protocol
             if (result != Result::SUCCESS)
                 continue;
 
+            const SystemMsgType msg_type = static_cast<SystemMsgType>(frame.header.type.value);
+
             if (frame.header.ack.ack_required)
-                send_ack(frame.header.ack.frame_id);
+                send_ack(frame.header.ack.frame_id, msg_type == SystemMsgType::VERSION_CHECK);
 
-            // Skip HEARTBEAT frames
-            if (frame.header.type.value == static_cast<types::u8>(SystemMsgType::HEARTBEAT))
+            // Skip HEARTBEAT and VERSION_CHECK frames
+            if (msg_type == SystemMsgType::HEARTBEAT || msg_type == SystemMsgType::VERSION_CHECK)
             {
                 result = Result::SYS_MSG_HANDLED;
                 continue;
@@ -148,9 +152,6 @@ 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;
@@ -203,24 +204,51 @@ class Protocol
         return send(static_cast<types::u8>(SystemMsgType::HEARTBEAT), BufferView(), true);
     }
 
+    /**
+     * @brief Checks protocol version compatibility.
+     * 
+     * @return Result::SUCCESS if compatible, otherwise error code.
+     */
+    Result version_check()
+    {
+        Result result;
+        result = send(static_cast<types::u8>(SystemMsgType::VERSION_CHECK), BufferView(), true);
+        if (result != Result::SUCCESS)
+            return result;
+
+        tp::DataFrame frame;
+        result = frame.unpack(buffer_.subview(0, tp::FieldHeader::SIZE + sizeof(VERSION)));
+        if (result != Result::SUCCESS)
+            return result;
+
+        if (frame.data[0] != VERSION[0])
+            return Result::VERSION_MISMATCH;
+
+        return Result::SUCCESS;
+    }
+
 private:
     /**
      * @brief Sends an acknowledgment frame for the specified message ID.
      * 
      * @param frame_id Identifier of the frame being acknowledged.
+     * @param version  Whether to include protocol version info in the acknowledgment.
      * @return Result::SUCCESS if acknowledgment received, otherwise error code. 
      */
-    Result send_ack(const tp::FieldID& frame_id)
+    Result send_ack(const tp::FieldID& frame_id, bool version = false)
     {
-        Result result;
+        tp::DataFrame ack_frame;
+        ack_frame.header.type = static_cast<types::u8>(SystemMsgType::ACK);
+        ack_frame.header.ack.ack_required = false;
+        ack_frame.header.ack.frame_id = frame_id;
 
-        tp::FieldHeader ack_frame;
-        ack_frame.type = static_cast<types::u8>(SystemMsgType::ACK);
-        ack_frame.ack.ack_required = false;
-        ack_frame.ack.frame_id = frame_id;
+        if (version)
+        {
+            ack_frame.data = BufferView(const_cast<types::u8*>(VERSION), sizeof(VERSION));
+        }
 
-        BufferHandler<tp::FieldHeader::SIZE + Crc::SIZE> ack_buf;
-        result = ack_frame.pack(ack_buf);
+        BufferHandler<tp::FieldHeader::SIZE + Crc::SIZE + sizeof(VERSION)> ack_buf;
+        Result result = ack_frame.pack(ack_buf);
         if (result != Result::SUCCESS)
             return result;
 
@@ -236,7 +264,7 @@ class Protocol
      *
      * @param frame_id  ID of the sent frame awaiting acknowledgment.
      * @param type      Type of the sent frame (used for collision handling).
-     * @param timeout    Maximum waiting time for acknowledgment, in milliseconds.
+     * @param timeout   Maximum waiting time for acknowledgment, in milliseconds.
      * @return Result::SUCCESS if acknowledgment received, otherwise error code. 
      */
     Result wait_ack(const tp::FieldID& frame_id, types::u8 type, const types::u32& timeout)
@@ -256,23 +284,29 @@ class Protocol
             if (result != Result::SUCCESS)
                 return result;
 
-            if (data_header.type.value == static_cast<types::u8>(SystemMsgType::ACK) &&
-                data_header.ack.frame_id == frame_id)
+            const SystemMsgType rcv_type = static_cast<SystemMsgType>(data_header.type.value);
+
+            if (rcv_type == SystemMsgType::ACK && data_header.ack.frame_id == frame_id)
             {
                 return Result::SUCCESS;
             }
-            else if (data_header.type.value == static_cast<types::u8>(SystemMsgType::HEARTBEAT))
+
+            const bool send_sys_msg = type == static_cast<types::u8>(SystemMsgType::HEARTBEAT) ||
+                                      type == static_cast<types::u8>(SystemMsgType::VERSION_CHECK);
+
+            if (rcv_type == SystemMsgType::HEARTBEAT || rcv_type == SystemMsgType::VERSION_CHECK)
             {
-                send_ack(data_header.ack.frame_id);
-                if (type == static_cast<types::u8>(SystemMsgType::HEARTBEAT))
+                send_ack(data_header.ack.frame_id, rcv_type == SystemMsgType::VERSION_CHECK);
+                if (send_sys_msg)
                     continue;
                 return Result::SYS_MSG_HANDLED;
             }
-            else if (data_header.ack.ack_required)  // Collision
-            {
-                if (type == static_cast<types::u8>(SystemMsgType::HEARTBEAT))
-                    continue;
 
+            if (send_sys_msg)
+                continue;
+
+            if (data_header.ack.ack_required)  // Collision
+            {
                 switch (Collision)
                 {
                     case CollisionBehavior::PRIORITY_SEND:

examples/linux/src/main.cpp

@@ -190,6 +190,14 @@ void test_heartbeat(csup::Protocol<>& csup)
                       << ", code=" << static_cast<int>(res) << "\n";
             ++err_count;
         }
+
+        res = csup.version_check();
+        if (res != csup::Result::SUCCESS)
+        {
+            std::cerr << "[ERROR] Version check failed at message " << i
+                      << ", code=" << static_cast<int>(res) << "\n";
+            ++err_count;
+        }
     }
 
     auto end = std::chrono::steady_clock::now();