CommRaT

CommRaT - Modern C++ Real-Time Communication Framework

A modern C++20 communication framework that combines RACK's TiMS IPC message service with SeRTial's zero-allocation serialization, providing compile-time safe, real-time capable messaging with templated message types and a powerful mailbox interface for efficient type dispatch.

Full Documentation | Getting Started | Examples

Features

• Timestamp Metadata Accessors: Access input timestamps, sequence numbers, freshness/validity flags
• Multi-Input Synchronization: Fuse multiple sensor streams with time-aligned getData
• Multi-Output Modules: Produce multiple message types simultaneously with type-specific delivery
• Ultra-Clean User Interface: Define messages ONCE, use payload types everywhere
• Payload-Only API: CommRaT<Messages...> template with Module<OutputSpec, InputSpec> base class
• Auto-Subscription: Input<PayloadT> automatically handles subscription protocol with type filtering
• Variadic Commands: Module<..., Cmd1, Cmd2, Cmd3> with type-safe on_command() handlers
• System Messages Auto-Included: CombinedRegistry automatically adds subscription protocol messages
• Compile-Time Message IDs: 0xPSMM format (Prefix, SubPrefix, Message ID) with auto-increment
• Modern C++20: Full template metaprogramming with concepts, std::span, and type safety
• Zero-Allocation Serialization: Stack-allocated std::byte buffers via SeRTial with compile-time size computation
• Compile-Time Type Safety: Templated message types with static validation and collision detection
• Module Framework: RAII-based Module<> with PeriodicInput/LoopInput/Input<T> modes
• Message Registry: Compile-time type registry for zero-overhead message dispatch
• Runtime Visitor Pattern: Efficient runtime dispatch without virtual functions (receive_any)
• SeRTial Integration: Automatic serialization using fixed_vector, fixed_string, and buffer_type
• TiMS IPC Backend: Socket-based real-time messaging from RACK (casting at C API boundary only)
• RT-Capable: No dynamic allocation in message paths, deterministic behavior
• Clean Interfaces: std::span<std::byte> throughout, pointer+size only at TiMS boundary

Documentation

• Getting Started Guide - Build your first CommRaT application
• User Guide - Comprehensive framework documentation
• API Reference - Complete API documentation
• Architecture & Concepts - Design decisions and current status
• Doxygen API Docs - Generated API documentation
• Examples - Working examples demonstrating all features

Quick Start

Installation

Prerequisites:

• SeRTial: Install from SeRTial repository
• RACK: Install from RACK repository (provides TiMS messaging system)

# Clone the repository
git clone https://github.com/mattih11/CommRaT.git
cd CommRaT
 
# Build and install
mkdir -p build && cd build
cmake ..
make -j$(nproc)
sudo make install

Your First CommRaT Application

Step 1: Define Messages

#include <commrat/commrat.hpp>
 
struct TemperatureData {
    float temperature_celsius;
    uint64_t timestamp_ms;
};
 
struct StatusData {
    int status_code;
    float average_temp;
};
 
// Define your application with message types
using MyApp = commrat::CommRaT<
    commrat::Message::Data<TemperatureData>,
    commrat::Message::Data<StatusData>
>;

Step 2: Create Modules

// Producer: publishes temperature every 500ms
class SensorModule : public MyApp::Module<
    commrat::Output<TemperatureData>,
    commrat::PeriodicInput
> {
protected:
    void process(TemperatureData& output) override {
        output = {.temperature_celsius = read_sensor()};
    }
};
 
// Consumer: processes incoming temperature data
class MonitorModule : public MyApp::Module<
    commrat::Output<StatusData>,
    commrat::Input<TemperatureData>
> {
protected:
    void process(const TemperatureData& input, StatusData& output) override {
        std::cout << "Temperature: " << input.temperature_celsius << "°C\n";
        output = calculate_status(input);
    }
};
 
// Multi-Output Producer: generates multiple message types simultaneously
struct RawData { /* ... */ };
struct FilteredData { /* ... */ };
struct Diagnostics { /* ... */ };
 
class SensorFusion : public MyApp::Module<
    commrat::Outputs<RawData, FilteredData, Diagnostics>,
    commrat::PeriodicInput
> {
protected:
    void process(RawData& raw, FilteredData& filtered, Diagnostics& diag) override {
        raw = read_sensors();
        filtered = apply_filter(raw);
        diag = compute_diagnostics(raw, filtered);
        // Each subscriber receives ONLY their type (type-specific filtering)
    }
};

Step 3: Run

int main() {
    
    commrat::ModuleConfig sensor_config{
        .name = "Sensor",
        .system_id = 10,
        .instance_id = 1,
        .period = commrat::Milliseconds(500)
    };
    
    commrat::ModuleConfig monitor_config{
        .name = "Monitor",
        .system_id = 20,
        .instance_id = 1,
        .source_system_id = 10,
        .source_instance_id = 1
    };
    
    SensorModule sensor(sensor_config);
    MonitorModule monitor(monitor_config);
    
    sensor.start();
    monitor.start();  // Auto-subscribes to sensor
    
    std::this_thread::sleep_for(std::chrono::seconds(10));
    
    monitor.stop();
    sensor.stop();
}

See Getting Started Guide for complete tutorial.

Running Examples

All examples demonstrate the framework's features with clean, professional output:

cd build
 
# Producer→Consumer with auto-subscription
./example_continuous_input
 
# Minimal boilerplate example
./example_clean_interface
 
# Type-safe command handling
./example_commands
 
# Maximum throughput demo (~200K-400K iter/sec)
./example_loop_mode
 
# Multi-output with 2 types
./example_multi_output_runtime
 
# Advanced sensor fusion with 3 outputs
./example_sensor_fusion

See examples/ directory for source code.

Building Documentation

Generate API documentation locally:

cd build
make docs

Documentation will be generated in docs/api/html/index.html. Open in your browser or view online at mattih11.github.io/CommRaT.

Architecture Highlights

• MailboxSet per Output: Each output type gets 3 mailboxes (CMD/WORK/PUBLISH) + shared DATA for inputs
• Blocking Receives: 0% CPU when idle, immediate response when active
• Compile-Time IDs: Message IDs calculated at compile time with collision detection
• Auto-Subscription: Input<T> automatically handles subscription protocol
• Type-Safe Dispatch: Visitor pattern for runtime dispatch without virtual functions
• Real-Time Safe: No dynamic allocation in hot paths, deterministic behavior
• Multi-Output Scalable: N output types = 3N mailboxes for independent subscription

Read Full Architecture Documentation →

License

See LICENSE file for details.

References

• RACK Project - Robotics Application Construction Kit (provides TiMS messaging system)
• SeRTial Library - Reflective C++ serialization