rpclpy 1.0.0

Python client library for building distributed node-based systems with communication, events, and knowledge management

RoboSapiens Client Libraries

A collection of high-performance client libraries for building distributed node-based systems with communication, events, and knowledge management capabilities. Available in Python, C++, and Rust with consistent APIs and Redis-based backend.

🌟 Features

All libraries provide:

• Node Communication: Publish/subscribe messaging and events with automatic metadata
• Knowledge Management: Distributed key-value storage with object serialization
• Redis Integration: Fast, reliable backend for all operations across multiple databases
• Multi-language Support: Consistent APIs across Python, C++, and Rust
• Real-time Communication: Event-driven architecture with thread-safe operations
• Type Safety: Strong typing and serialization (JSON, Pickle, Serde)
• Logging & Monitoring: Built-in structured logging with configurable levels
• UUID & Timestamps: Automatic message identification and timestamping
• Error Handling: Comprehensive error management and recovery

📁 Repository Structure

robosapiens-clientlibraries/
├── rpclpy/                    # Python library
│   ├── __init__.py           # Library initialization
│   ├── node.py               # Main Node class
│   ├── CommunicationManager.py # Redis pub/sub handling
│   ├── KnowledgeManager.py   # Knowledge storage
│   ├── LoggingAndTracking.py # Logging infrastructure
│   └── examples/             # Python examples
│       ├── sensor_node.py   # Temperature sensor simulation
│       ├── monitor_node.py  # Data monitoring and analysis
│       ├── data_models.py   # Shared data structures
│       ├── config.yaml      # Configuration example
│       └── README.md        # Examples documentation
├── rpclcpp/                  # C++ library
│   ├── include/              # Header files
│   │   ├── node.hpp         # Main Node interface
│   │   ├── communication_manager.hpp
│   │   ├── knowledge_manager.hpp
│   │   └── logger.hpp
│   ├── src/                  # Implementation files
│   ├── examples/             # C++ examples
│   └── CMakeLists.txt        # Build configuration
├── rpclrs/                   # Rust library
│   ├── src/                  # Rust source code
│   │   ├── lib.rs           # Library entry point
│   │   ├── node.rs          # Main Node implementation
│   │   ├── communication_manager.rs
│   │   └── knowledge_manager.rs
│   ├── examples/             # Rust examples
│   └── Cargo.toml           # Package configuration
├── .gitignore               # Git ignore patterns
└── README.md                # This file

🚀 Quick Start

Python (rpclpy)

from rpclpy.node import Node
import yaml

# Load config and create node
with open('config.yaml', 'r') as f:
    config = yaml.safe_load(f)

node = Node(config)
node.start()

# Publish event
node.publish_event("sensor/data", {"temperature": 22.5})

# Subscribe to events
node.register_event_callback("alerts/high", handle_alert)

C++ (rpclcpp)

#include "node.hpp"
using namespace rpclcpp;

Node node("MyNode");
node.start();

// Publish event
json data = {{"temperature", 22.5}};
node.publish_event("sensor/data", data);

// Subscribe to events
node.register_event_callback("alerts/high", [](const std::string& topic, const std::string& msg) {
    // Handle alert
});

Rust (rpclrs)

use rpclrs::Node;
use serde_json::json;

let mut node = Node::new("MyNode", "localhost", 6379)?;
node.start()?;

// Publish event
let data = json!({"temperature": 22.5});
node.publish_event("sensor/data", data)?;

// Subscribe to events
node.register_event_callback("alerts/high", |topic, message| {
    println!("Alert: {}", message);
})?;

🛠️ Installation & Setup

Prerequisites

• Redis Server: Version 6.0+ running on localhost:6379 (or configured host)
• Operating System: Linux, macOS, or Windows
• Language-specific dependencies (see individual library READMEs)

Redis Installation

Ubuntu/Debian:

sudo apt update && sudo apt install redis-server
sudo systemctl start redis-server

macOS:

brew install redis
brew services start redis

Docker:

docker run --name redis-server -p 6379:6379 -d redis

Python Setup (rpclpy)

cd rpclpy
pip install redis paho-mqtt PyYAML  # Install dependencies

C++ Setup (rpclcpp)

Ubuntu/Debian:

sudo apt install cmake build-essential libhiredis-dev nlohmann-json3-dev
cd rpclcpp
mkdir build && cd build
cmake ..
make -j$(nproc)
sudo make install  # Optional: system-wide installation

Build Examples:

make sensor_node monitor_node

Rust Setup (rpclrs)

cd rpclrs
cargo build --release

Build Examples:

cargo build --examples

📋 Examples

Sensor Monitoring System

All three libraries include a complete real-time sensor monitoring system that demonstrates:

• Sensor Node:

  • Simulates realistic temperature sensors with drift and noise
  • Publishes readings as events with automatic timestamping
  • Generates alerts for abnormal conditions
  • Stores data in knowledge base for persistence

• Monitor Node:

  • Subscribes to sensor events in real-time
  • Processes and analyzes readings for patterns
  • Maintains system statistics and health metrics
  • Responds to alerts with configurable severity levels
  • Provides comprehensive monitoring dashboard

• Data Models:

  • SensorReading: Temperature data with metadata
  • Alert: Alert notifications with severity levels
  • SystemStatus: Overall system health metrics

What You'll See

SENSOR MONITORING STATUS
============================================================
Active Sensors: 1
Total Readings: 47
Alert Count: 3
Average Temperature: 23.2°C

Sensor Details:
  TEMP_001: 24.1°C [normal] at Lab Room A

Recent Alerts (2):
  [HIGH] Temperature too high: 31.2°C at Lab Room A
  [MEDIUM] Temperature outside normal range: 27.8°C at Lab Room A
------------------------------------------------------------

Running the Examples

Python (Recommended for beginners):

cd rpclpy/examples
# Terminal 1 - Start monitoring first
python monitor_node.py

# Terminal 2 - Start sensor
python sensor_node.py

# Alternative: Run automated test
python test_example.py

C++:

cd rpclcpp/build
# Terminal 1
./monitor_node

# Terminal 2
./sensor_node

Rust:

cd rpclrs
# Terminal 1
cargo run --example monitor_node

# Terminal 2
cargo run --example sensor_node

Testing All Features

Each library includes a comprehensive test script:

Python:

cd rpclpy/examples
python run_tests.py  # Automated test suite with Redis setup check

The test validates:

• ✅ Node initialization and startup
• ✅ Event publishing and subscription
• ✅ Message passing between nodes
• ✅ Knowledge base read/write operations
• ✅ Object serialization/deserialization
• ✅ Alert generation and handling
• ✅ Real-time data processing

🏗️ Architecture

System Overview

┌─────────────┐    Events/Messages    ┌─────────────┐
│ Sensor Node │◄─────────────────────►│Monitor Node │
└─────────────┘       Real-time       └─────────────┘
       │              Communication           │
       ▼                                     ▼
┌─────────────────────────────────────────────────────┐
│                    Redis Backend                    │
│  ┌─────────┐  ┌─────────┐  ┌─────────────────────┐  │
│  │ Events  │  │Messages │  │   Knowledge Base    │  │
│  │ (DB 0)  │  │ (DB 1)  │  │      (DB 2)         │  │
│  │ Pub/Sub │  │ Pub/Sub │  │    Key-Value        │  │
│  └─────────┘  └─────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────┘

Communication Flow

1. Events: Structured data with automatic metadata (UUID, timestamp)
2. Messages: Direct point-to-point communication
3. Knowledge: Persistent storage with object serialization

Thread Safety

All libraries implement thread-safe operations:

• Python: Threading locks and atomic operations
• C++: Mutexes and RAII patterns
• Rust: Arc/Mutex for shared state management

🔧 Configuration

All libraries use Redis with separated databases:

• DB 0: Events (pub/sub)
• DB 1: Messages (pub/sub)
• DB 2: Knowledge (key-value storage)

Example configuration (Python):

Event_Manager_Config:
  protocol: "redis"
  host: "localhost"
  port: 6379
  db: 0

Message_Manager_Config:
  protocol: "redis"
  host: "localhost"
  port: 6379
  db: 1

Knowledge_Config:
  knowledge_type: "redis"
  host: "localhost"
  port: 6379
  db: 2

🌐 API Consistency

All three libraries provide the same core functionality:

Operation	Python	C++	Rust
Create Node	Node(config)	Node("name")	Node::new("name", host, port)
Start	node.start()	node.start()	node.start()
Publish Event	publish_event(topic, data)	publish_event(topic, json)	publish_event(topic, value)
Subscribe	register_event_callback(topic, fn)	register_event_callback(topic, fn)	register_event_callback(topic, fn)
Write Knowledge	write_knowledge(key, value)	write_knowledge(key, value)	write_knowledge(key, value)
Read Knowledge	read_knowledge(key)	read_knowledge(key)	read_knowledge(key)

🧪 Testing

Comprehensive Test Coverage

Each library includes comprehensive examples that test:

• ✅ Node Communication: Event and message passing between nodes
• ✅ Event Publishing/Subscribing: Real-time event distribution
• ✅ Message Passing: Direct point-to-point communication
• ✅ Knowledge Management: Persistent data storage and retrieval
• ✅ Object Serialization: Type-safe data exchange
• ✅ Alert Generation: Automated alert creation and handling
• ✅ Real-time Data Processing: Stream processing capabilities
• ✅ Error Handling: Graceful error recovery and logging
• ✅ Thread Safety: Concurrent operations validation
• ✅ Memory Management: Resource cleanup and leak prevention

Performance Characteristics

• Latency: Sub-millisecond message delivery
• Throughput: 10,000+ messages/second per node
• Memory: Efficient circular buffers for data retention
• Scalability: Horizontal scaling through Redis clustering

Monitoring & Observability

• Structured Logging: JSON-formatted logs with context
• Metrics: Built-in counters for messages, errors, and performance
• Health Checks: Node status and connectivity monitoring
• Debug Mode: Detailed tracing for development and troubleshooting

📖 Documentation

• Python Library (rpclpy)
• C++ Library (rpclcpp)
• Rust Library (rpclrs)
• Python Examples

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Setup

1. Fork the repository

2. Clone your fork: git clone https://github.com/yourusername/robosapiens-clientlibraries.git

3. Create a feature branch: git checkout -b feature/amazing-feature

4. Set up development environment:

   # Install Redis
   docker run --name redis-dev -p 6379:6379 -d redis
   
   # Setup Python environment
   cd rpclpy && pip install -e .
   
   # Setup C++ environment
   cd rpclcpp && mkdir build && cd build && cmake ..
   
   # Setup Rust environment
   cd rpclrs && cargo build
   

Contribution Guidelines

• Code Style: Follow language-specific conventions (PEP 8 for Python, Google Style for C++, Rustfmt for Rust)
• Testing: Add tests for new features and ensure existing tests pass
• Documentation: Update READMEs and inline documentation
• Commit Messages: Use conventional commits format
• API Consistency: Maintain consistent APIs across all three languages

Areas for Contribution

• 🐛 Bug Fixes: Issues and bug reports
• ✨ New Features: Additional communication protocols, storage backends
• 📚 Documentation: Tutorials, examples, API documentation
• 🔧 Performance: Optimizations and benchmarks
• 🧪 Testing: Additional test cases and integration tests
• 🌐 Internationalization: Multi-language support

Pull Request Process

1. Make your changes
2. Add/update tests
3. Update documentation
4. Ensure all tests pass
5. Submit a pull request with detailed description

🐛 Troubleshooting

Common Issues

Redis Connection Failed:

# Check if Redis is running
redis-cli ping
# Should return "PONG"

# Start Redis if not running
sudo systemctl start redis-server  # Linux
brew services start redis          # macOS

Import Errors (Python):

# Make sure rpclpy is in your Python path
export PYTHONPATH="${PYTHONPATH}:/path/to/robosapiens-clientlibraries"

Build Errors (C++):

# Install missing dependencies
sudo apt install cmake build-essential libhiredis-dev nlohmann-json3-dev

Getting Help

• 📖 Check individual library READMEs for detailed setup instructions
• 🐛 Open an issue for bug reports
• 💬 Start a discussion for questions and feature requests
• 📧 Contact maintainers for urgent issues

📄 License

MIT License - see individual library directories for details.

🏷️ Version

Current version: 1.0.0

All libraries maintain API compatibility and feature parity across languages.

Changelog

• v1.0.0 (2025-07-31): Initial release with Python, C++, and Rust libraries
  • Core node communication functionality
  • Redis-based backend with multi-database support
  • Comprehensive sensor monitoring examples
  • Thread-safe operations across all languages
  • Object serialization and knowledge management
  • Structured logging and error handling

🌟 Acknowledgments

• Redis Team: For the excellent in-memory data structure store
• Open Source Communities: Python, C++, and Rust ecosystems
• Contributors: Everyone who helped make this project possible

---

Built with ❤️ by the RoboSapiens Team

For questions, support, or contributions, please visit our GitHub repository.