@technoculture/safeserial 0.1.1 → 0.1.2

package/core/include/safeserial/config.hpp

@@ -0,0 +1,69 @@
+#pragma once
+#include <cstdlib>
+#include <cstdint>
+#include <string>
+
+/**
+ * Configuration for SafeSerial protocol.
+ * 
+ * Parameters can be set via environment variables.
+ * If not set, defaults are used.
+ * 
+ * Environment variables:
+ *   SAFESERIAL_MAX_RETRIES      - Maximum retry attempts (default: 10)
+ *   SAFESERIAL_RETRY_TIMEOUT_MS - Timeout between retries in ms (default: 2000)
+ *   SAFESERIAL_FRAGMENT_SIZE    - Maximum fragment payload size (default: 256)
+ *   SAFESERIAL_ACK_TIMEOUT_MS   - Timeout waiting for ACK in ms (default: 500)
+ */
+
+namespace SafeSerialConfig {
+
+inline int getEnvInt(const char* name, int defaultValue) {
+    const char* val = std::getenv(name);
+    if (val == nullptr) return defaultValue;
+    try {
+        return std::stoi(val);
+    } catch (...) {
+        return defaultValue;
+    }
+}
+
+// Maximum number of retry attempts before giving up
+inline uint8_t maxRetries() {
+    static uint8_t value = static_cast<uint8_t>(
+        getEnvInt("SAFESERIAL_MAX_RETRIES", 10)
+    );
+    return value;
+}
+
+// Timeout between retries in milliseconds
+inline uint16_t retryTimeoutMs() {
+    static uint16_t value = static_cast<uint16_t>(
+        getEnvInt("SAFESERIAL_RETRY_TIMEOUT_MS", 2000)
+    );
+    return value;
+}
+
+// Maximum payload size per fragment (for large message fragmentation)
+inline uint16_t fragmentSize() {
+    static uint16_t value = static_cast<uint16_t>(
+        getEnvInt("SAFESERIAL_FRAGMENT_SIZE", 256)
+    );
+    return value;
+}
+
+// Timeout waiting for ACK before retry
+inline uint16_t ackTimeoutMs() {
+    static uint16_t value = static_cast<uint16_t>(
+        getEnvInt("SAFESERIAL_ACK_TIMEOUT_MS", 500)
+    );
+    return value;
+}
+
+// Baud rate (default for most embedded devices)
+inline int baudRate() {
+    static int value = getEnvInt("SAFESERIAL_BAUD_RATE", 115200);
+    return value;
+}
+
+} // namespace SafeSerialConfig

package/core/include/safeserial/protocol/crc32.hpp

@@ -0,0 +1,19 @@
+#pragma once
+#include <cstdint>
+#include <cstddef>
+
+class CRC32 {
+public:
+    static uint32_t calculate(const uint8_t* data, size_t length) {
+        uint32_t crc = 0xFFFFFFFF;
+        for (size_t i = 0; i < length; ++i) {
+            uint8_t byte = data[i];
+            crc = crc ^ byte;
+            for (int j = 0; j < 8; ++j) {
+                uint32_t mask = -(crc & 1);
+                crc = (crc >> 1) ^ (0xEDB88320 & mask);
+            }
+        }
+        return ~crc;
+    }
+};

package/core/include/safeserial/protocol/packet.hpp

@@ -0,0 +1,175 @@
+#pragma once
+#include <vector>
+#include <string>
+#include <cstdint>
+#include <utility>
+#include <cstring>
+#include <algorithm>
+#include <safeserial/protocol/crc32.hpp>
+#include <safeserial/config.hpp>
+
+// Cross-platform packed struct support
+#if defined(_MSC_VER)
+#define PACKED_STRUCT_BEGIN __pragma(pack(push, 1))
+#define PACKED_STRUCT_END __pragma(pack(pop))
+#define PACKED_ATTR
+#elif defined(__GNUC__) || defined(__clang__)
+#define PACKED_STRUCT_BEGIN
+#define PACKED_STRUCT_END
+#define PACKED_ATTR __attribute__((packed))
+#else
+#define PACKED_STRUCT_BEGIN
+#define PACKED_STRUCT_END
+#define PACKED_ATTR
+#endif
+
+struct Packet {
+    PACKED_STRUCT_BEGIN
+    struct Header {
+        uint8_t  type;
+        uint8_t  seq_id;
+        uint16_t fragment_id;
+        uint16_t total_frags;
+        uint16_t payload_len;
+        uint32_t crc32;
+    } PACKED_ATTR;
+    PACKED_STRUCT_END
+
+    // Packet Types
+    static constexpr uint8_t TYPE_DATA = 0x10;
+    static constexpr uint8_t TYPE_ACK  = 0x20;
+    static constexpr uint8_t TYPE_NACK = 0x30;
+    static constexpr uint8_t TYPE_SYN  = 0x40;
+    
+    // COBS delimiter
+    static constexpr uint8_t COBS_DELIMITER = 0x00;
+
+    // Configuration accessors (use env vars or defaults)
+    static uint8_t maxRetries() { return SafeSerialConfig::maxRetries(); }
+    static uint16_t retryTimeoutMs() { return SafeSerialConfig::retryTimeoutMs(); }
+    static uint16_t fragmentSize() { return SafeSerialConfig::fragmentSize(); }
+
+    struct Frame {
+        Header header;
+        std::vector<uint8_t> payload;
+        bool valid;
+    };
+    
+    // Consistent Overhead Byte Stuffing (COBS) Encoding
+    static std::vector<uint8_t> cobs_encode(const std::vector<uint8_t>& data) {
+        std::vector<uint8_t> encoded;
+        encoded.reserve(data.size() + data.size() / 254 + 2);
+
+        size_t code_idx = 0;
+        encoded.push_back(0); // Placeholder for the first code
+        uint8_t code = 1;
+
+        for (uint8_t byte : data) {
+            if (byte == 0) {
+                encoded[code_idx] = code;
+                code_idx = encoded.size();
+                encoded.push_back(0); // Placeholder for next code
+                code = 1;
+            } else {
+                encoded.push_back(byte);
+                code++;
+                if (code == 0xFF) { // Max run length reached
+                    encoded[code_idx] = code;
+                    code_idx = encoded.size();
+                    encoded.push_back(0);
+                    code = 1;
+                }
+            }
+        }
+        encoded[code_idx] = code;
+        return encoded;
+    }
+
+    // COBS Decoding
+    static std::vector<uint8_t> cobs_decode(const std::vector<uint8_t>& data) {
+        std::vector<uint8_t> decoded;
+        decoded.reserve(data.size());
+
+        size_t i = 0;
+        while (i < data.size()) {
+            uint8_t code = data[i];
+            i++;
+            if (code == 0) break; // Should not happen in valid COBS before delimiter
+
+            for (uint8_t j = 1; j < code; j++) {
+                if (i >= data.size()) return {}; // Error: truncated
+                decoded.push_back(data[i++]);
+            }
+            if (code < 0xFF && i < data.size()) {
+                decoded.push_back(0);
+            }
+        }
+        return decoded;
+    }
+
+    static std::vector<uint8_t> serialize(uint8_t type, uint8_t seq, const std::string& payload, uint16_t frag_id = 0, uint16_t total_frags = 1) {
+        Header header;
+        header.type = type;
+        header.seq_id = seq;
+        header.fragment_id = frag_id;
+        header.total_frags = total_frags;
+        header.payload_len = static_cast<uint16_t>(payload.size());
+        header.crc32 = 0; // Calculated later
+
+        std::vector<uint8_t> raw_packet;
+        raw_packet.resize(sizeof(Header) + payload.size());
+        
+        std::memcpy(raw_packet.data(), &header, sizeof(Header));
+        std::memcpy(raw_packet.data() + sizeof(Header), payload.data(), payload.size());
+
+        // Calculate CRC32 of Header + Payload (with CRC field zeroed)
+        uint32_t crc = CRC32::calculate(raw_packet.data(), raw_packet.size());
+        
+        // Update header with calculated CRC
+        header.crc32 = crc;
+        std::memcpy(raw_packet.data(), &header, sizeof(Header));
+
+        // Encode with COBS
+        std::vector<uint8_t> encoded = cobs_encode(raw_packet);
+        encoded.push_back(COBS_DELIMITER); 
+        return encoded;
+    }
+
+    static Frame deserialize(std::vector<uint8_t>& buffer) {
+        // Find delimiter
+        auto it = std::find(buffer.begin(), buffer.end(), COBS_DELIMITER);
+        if (it == buffer.end()) return {{}, {}, false}; // No complete frame yet
+
+        std::vector<uint8_t> frame_data(buffer.begin(), it);
+        buffer.erase(buffer.begin(), it + 1); // Remove processed frame + delimiter
+
+        if (frame_data.empty()) return {{}, {}, false};
+
+        std::vector<uint8_t> decoded = cobs_decode(frame_data);
+        if (decoded.size() < sizeof(Header)) return {{}, {}, false};
+
+        Header header;
+        std::memcpy(&header, decoded.data(), sizeof(Header));
+
+        // Validate Length
+        if (decoded.size() != sizeof(Header) + header.payload_len) return {{}, {}, false};
+
+        // Validate CRC
+        uint32_t received_crc = header.crc32;
+        
+        // Zero out CRC in buffer to recompute
+        Header* header_ptr = reinterpret_cast<Header*>(decoded.data());
+        header_ptr->crc32 = 0;
+        
+        uint32_t computed_crc = CRC32::calculate(decoded.data(), decoded.size());
+        
+        if (received_crc == computed_crc) {
+            std::vector<uint8_t> payload(decoded.begin() + sizeof(Header), decoded.end());
+            // Retrieve original header
+            header.crc32 = received_crc; 
+            return {header, payload, true};
+        }
+
+        return {{}, {}, false};
+    }
+};

package/core/include/safeserial/protocol/reassembler.hpp

@@ -0,0 +1,80 @@
+#pragma once
+#include <safeserial/protocol/packet.hpp>
+#include <vector>
+#include <iostream>
+
+class Reassembler {
+public:
+    struct Result {
+        bool complete;
+        std::vector<uint8_t> payload;
+    };
+
+    Reassembler() : current_seq_id_(255), expected_frag_(0), active_(false) {}
+
+    // Returns true if fragment was accepted (in sequence).
+    // Caller should send ACK if this returns true.
+    // If returns false, caller might ignore or send NACK/ACK-of-last-good.
+    bool process_fragment(const Packet::Frame& frame) {
+        if (!frame.valid) return false;
+        
+        uint8_t seq = frame.header.seq_id;
+        uint16_t frag = frame.header.fragment_id;
+        
+        // New Sequence ?
+        if (seq != current_seq_id_) {
+             // Accept if it's a new message (logic can be more complex for strict strictness, 
+             // e.g. only seq+1, but for now accept any new seq as new message start)
+             if (frag == 0) {
+                 reset(seq);
+             } else {
+                 return false; // Received middle of new message without start?
+             }
+        }
+
+        if (frag != expected_frag_) {
+            // Out of order fragment
+            return false;
+        }
+
+        // Valid fragment
+        buffer_.insert(buffer_.end(), frame.payload.begin(), frame.payload.end());
+        expected_frag_++;
+        return true;
+    }
+
+    bool is_complete(const Packet::Frame& last_frame) const {
+         if (!active_) return false;
+         return expected_frag_ == last_frame.header.total_frags;
+    }
+
+    bool is_duplicate(const Packet::Frame& frame) const {
+         if (!active_) return false;
+         uint8_t seq = frame.header.seq_id;
+         uint16_t frag = frame.header.fragment_id;
+         return (seq == current_seq_id_ && frag < expected_frag_);
+    }
+
+    std::vector<uint8_t> get_data() const {
+        return buffer_;
+    }
+
+    size_t get_buffered_size() const {
+        return buffer_.size();
+    }
+
+    uint8_t get_current_seq() const { return current_seq_id_; }
+
+private:
+    void reset(uint8_t seq) {
+        buffer_.clear();
+        current_seq_id_ = seq;
+        expected_frag_ = 0;
+        active_ = true;
+    }
+
+    uint8_t current_seq_id_;
+    uint16_t expected_frag_;
+    std::vector<uint8_t> buffer_;
+    bool active_;
+};

package/core/include/safeserial/resilient_bridge.hpp

@@ -0,0 +1,106 @@
+#pragma once
+
+#include <atomic>
+#include <condition_variable>
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <random>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include <safeserial/safeserial.hpp>
+
+class ResilientDataBridge {
+public:
+    struct Options {
+        DataBridge::Options bridge;
+        bool reconnect;
+        uint32_t reconnect_delay_ms;
+        uint32_t max_reconnect_delay_ms;
+        size_t max_queue_size;
+
+        static Options Defaults() {
+            Options options{};
+            options.bridge = DataBridge::Options::Defaults();
+            options.reconnect = true;
+            options.reconnect_delay_ms = 1000;
+            options.max_reconnect_delay_ms = 30000;
+            options.max_queue_size = 1000;
+            return options;
+        }
+    };
+
+    ResilientDataBridge();
+    explicit ResilientDataBridge(const Options& options);
+    ResilientDataBridge(const Options& options,
+                        std::function<std::shared_ptr<ISerialPort>()> serial_factory);
+    ~ResilientDataBridge();
+
+    ResilientDataBridge(const ResilientDataBridge&) = delete;
+    ResilientDataBridge& operator=(const ResilientDataBridge&) = delete;
+
+    bool open(const std::string& port);
+    void close();
+
+    int send(const std::vector<uint8_t>& data);
+
+    bool is_connected() const;
+    size_t queue_length() const;
+
+    void set_on_data(std::function<void(const std::vector<uint8_t>&)> callback);
+    void set_on_error(std::function<void(const std::string&)> callback);
+    void set_on_disconnect(std::function<void()> callback);
+    void set_on_reconnecting(std::function<void(uint32_t, uint32_t)> callback);
+    void set_on_reconnected(std::function<void()> callback);
+    void set_on_close(std::function<void()> callback);
+
+private:
+    struct QueuedMessage {
+        explicit QueuedMessage(std::vector<uint8_t> payload)
+            : data(std::move(payload)) {}
+
+        std::vector<uint8_t> data;
+        int bytes_written = 0;
+        bool done = false;
+        bool failed = false;
+        std::string error;
+        std::mutex mutex;
+        std::condition_variable cv;
+    };
+
+    bool connect();
+    void handle_disconnect(const std::string& reason);
+    void start_reconnect_thread();
+    void reconnect_loop();
+    void flush_queue();
+    void notify_error(const std::string& message);
+
+    std::string port_;
+    Options options_;
+    std::function<std::shared_ptr<ISerialPort>()> serial_factory_;
+
+    std::unique_ptr<DataBridge> bridge_;
+    std::atomic<bool> connected_{false};
+    std::atomic<bool> stop_{false};
+
+    std::mutex state_mutex_;
+    mutable std::mutex queue_mutex_;
+    std::vector<std::shared_ptr<QueuedMessage>> queue_;
+
+    std::thread reconnect_thread_;
+    std::atomic<bool> reconnect_thread_running_{false};
+    uint32_t reconnect_attempt_ = 0;
+    std::mt19937 rng_{std::random_device{}()};
+
+    std::mutex callback_mutex_;
+    std::function<void(const std::vector<uint8_t>&)> on_data_;
+    std::function<void(const std::string&)> on_error_;
+    std::function<void()> on_disconnect_;
+    std::function<void(uint32_t, uint32_t)> on_reconnecting_;
+    std::function<void()> on_reconnected_;
+    std::function<void()> on_close_;
+};

package/core/include/safeserial/safeserial.hpp

@@ -0,0 +1,87 @@
+#pragma once
+
+#include <atomic>
+#include <condition_variable>
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include <safeserial/config.hpp>
+#include <safeserial/protocol/packet.hpp>
+#include <safeserial/protocol/reassembler.hpp>
+#include <safeserial/transport/iserial_port.hpp>
+#include <safeserial/transport/serial_port.hpp>
+
+class DataBridge {
+public:
+    struct Options {
+        int baud_rate;
+        uint8_t max_retries;
+        uint16_t ack_timeout_ms;
+        uint16_t fragment_size;
+
+        static Options Defaults() {
+            return Options{
+                SafeSerialConfig::baudRate(),
+                SafeSerialConfig::maxRetries(),
+                SafeSerialConfig::ackTimeoutMs(),
+                SafeSerialConfig::fragmentSize(),
+            };
+        }
+    };
+
+    DataBridge();
+    explicit DataBridge(const Options& options);
+    DataBridge(std::shared_ptr<ISerialPort> serial, const Options& options);
+    ~DataBridge();
+
+    DataBridge(const DataBridge&) = delete;
+    DataBridge& operator=(const DataBridge&) = delete;
+
+    bool open(const std::string& port, int baud_rate_override = -1);
+    void close();
+    bool is_open() const;
+
+    int send(const std::vector<uint8_t>& data,
+             uint16_t ack_timeout_ms_override = 0,
+             uint8_t max_retries_override = 0,
+             uint16_t fragment_size_override = 0);
+
+    void set_on_data(std::function<void(const std::vector<uint8_t>&)> callback);
+    size_t get_buffered_size() const;
+
+private:
+    void receive_loop();
+    void handle_frame(const Packet::Frame& frame);
+    void send_ack(const Packet::Frame& frame);
+
+    std::shared_ptr<ISerialPort> serial_;
+    Options options_;
+
+    std::atomic<bool> stop_{false};
+    std::atomic<bool> is_open_{false};
+    std::thread receive_thread_;
+
+    std::vector<uint8_t> rx_buffer_;
+    Reassembler reassembler_;
+
+    std::mutex seq_mutex_;
+    uint8_t next_seq_{0};
+
+    std::mutex send_mutex_;
+    std::mutex write_mutex_;
+
+    std::mutex ack_mutex_;
+    std::condition_variable ack_cv_;
+    bool waiting_for_ack_{false};
+    bool acked_{false};
+    uint8_t waiting_seq_{0};
+    uint16_t waiting_frag_{0};
+
+    std::mutex callback_mutex_;
+    std::function<void(const std::vector<uint8_t>&)> on_data_;
+};

package/core/include/safeserial/transport/iserial_port.hpp

@@ -0,0 +1,15 @@
+#pragma once
+#include <vector>
+#include <string>
+#include <cstdint>
+
+class ISerialPort {
+public:
+    virtual ~ISerialPort() = default;
+
+    virtual bool open(const std::string& port_name, int baud_rate) = 0;
+    virtual void close() = 0;
+    
+    virtual int write(const std::vector<uint8_t>& data) = 0;
+    virtual int read(uint8_t* buffer, size_t size) = 0;
+};

package/core/include/safeserial/transport/serial_port.hpp

@@ -0,0 +1,28 @@
+#pragma once
+#include <memory>
+#include <vector>
+#include <string>
+
+#include <safeserial/transport/iserial_port.hpp>
+
+class SerialPort : public ISerialPort {
+
+public:
+    SerialPort();
+    ~SerialPort();
+
+    // Prevent copying (Serial ports are unique resources)
+    SerialPort(const SerialPort&) = delete;
+    SerialPort& operator=(const SerialPort&) = delete;
+
+    bool open(const std::string& port_name, int baud_rate) override;
+    void close() override;
+    
+    int write(const std::vector<uint8_t>& data) override;
+    int read(uint8_t* buffer, size_t size) override;
+
+private:
+    // The "Pimpl" - This struct is defined only in the .cpp files
+    struct Impl;
+    std::unique_ptr<Impl> pimpl;
+};

package/core/src/CMakeLists.txt

@@ -0,0 +1,21 @@
+add_library(safeserial STATIC
+    safeserial.cpp
+    resilient_bridge.cpp
+)
+
+safeserial_apply_sanitizers(safeserial)
+
+# Platform specific sources
+if(WIN32)
+    target_sources(safeserial PRIVATE transport/platform/windows/windows_serial.cpp)
+else()
+    target_sources(safeserial PRIVATE transport/platform/linux/linux_serial.cpp)
+endif()
+
+target_include_directories(safeserial PUBLIC
+    $<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/include>
+    $<INSTALL_INTERFACE:include>
+)
+
+# Export the library name for other subdirectories
+set(SAFESERIAL_LIB safeserial PARENT_SCOPE)

package/core/src/protocol/packet.cpp

@@ -0,0 +1 @@
+#include "protocol/packet.hpp"