Skip to content

CLAUDE.md

Latest commit

 

History

History
131 lines (106 loc) · 5.12 KB

CLAUDE.md

File metadata and controls

131 lines (106 loc) · 5.12 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

miniROS-rs is a lightweight, high-performance ROS2-compatible middleware written in Rust with Python bindings, following the "Mini" Philosophy: Maximum robotics performance, minimum complexity.

Commands

Development Commands

# Setup and installation
bash scripts/setup.sh                      # Complete setup
bash scripts/setup.sh build               # Build CLIs only
bash scripts/setup.sh test                # Test installation

# Build and test
cargo build                                # Build Rust components
cargo test                                 # Run comprehensive unit tests
cd python && pip install -e .              # Install Python bindings
cd python && pytest                        # Test Python bindings

# Run examples (progressive learning from basic to advanced)
cargo run --example 01_basic_pubsub        # Basic pub/sub
cargo run --example 02_simple_service      # Services
cargo run --example 20_production_system   # Full production system

# CLI usage
cargo run --bin mini_ros -- launch <package> <launch_file>
cargo run --bin mini_ros -- pkg list
cargo run --bin mini_ros -- run <package> <executable>
mini_ros_py examples run <name>             # Python examples

# Documentation
cd docs && mdbook serve                     # Serve documentation locally

Testing Commands

cargo test                                  # Rust unit tests
cd python && pytest                        # Python tests with asyncio support
cargo run --example <example_name>         # Test specific examples

Architecture

Core Structure

  • src/core/: Node, Message, Context - fundamental building blocks
  • src/communication/: Publisher/Subscriber, Services, Actions with async support
  • src/transport/: Multiple transport layers (TCP default, DDS, Zenoh, UDP)
  • src/system/: Discovery, Launch, Packages, Parameters, ROS2 Bridge, Plugin System
  • src/types.rs: Complete ROS2-compatible message types with validation
  • packages/: Built-in message packages (std_msgs, geometry_msgs, nav_msgs, sensor_msgs, etc.)
  • python/: PyO3 bindings for Python integration

Transport Layer Architecture

  • TCP Transport: Default reliable transport
  • DDS Transport: ROS2 compatibility layer (custom implementation)
  • Zenoh Transport: High-performance alternative
  • UDP Transport: Low-latency multicast option

ROS2 Bridge Integration

  • Auto-discovery of common robotics topics (/cmd_vel, /odom, /scan)
  • Automatic message conversion between ROS2 and miniROS formats
  • QoS profile mapping (reliability, durability, history)
  • Bidirectional communication with existing ROS2 systems
  • Specialized turtlebot integration

Plugin System

Extensible architecture with Plugin trait:

  • CustomTransportPlugin: Transport implementations
  • MonitoringPlugin: Metrics and health monitoring
  • Lifecycle management (initialize, start, stop)

Message System

All messages include:

  • Validation: Range checks, safety limits, covariance validation
  • Serialization: Efficient binary format with bincode
  • Schema: Runtime type checking and metadata
  • ROS2 Compatibility: Drop-in replacement for ROS2 message types

Package System

YAML-based package manifests with:

  • Dependencies and version management
  • Python support flags
  • Executable definitions with feature flags
  • Launch file specifications

Key Design Patterns

"Mini" Philosophy Implementation

  1. Core Functionality Focus: Essential robotics primitives only
  2. Zero-Copy Optimizations: High-performance message passing
  3. Async-First: Full Tokio integration for concurrency
  4. Type Safety: Rust's type system prevents runtime errors
  5. ROS2 Compatibility: Seamless integration capability
  6. Minimal Dependencies: Lean dependency tree

Communication Patterns

  • Actor Model: Nodes as independent actors with message passing
  • Event-Driven: Async callbacks and reactive patterns
  • Schema-Driven: Runtime type checking and validation
  • Transport Abstraction: Common interface across transport layers

Development Guidelines

Code Organization

  • Follow existing patterns in src/ directory structure
  • Use async/await for all I/O operations
  • Implement comprehensive error handling with custom Error types
  • Add validation to all message types
  • Maintain ROS2 compatibility in message structures

Testing

  • Unit tests for all core functionality
  • Integration tests for communication patterns
  • Example-based testing for user-facing features
  • Performance benchmarks for critical paths

Features and Dependencies

  • Default features: ["tcp-transport", "visualization"]
  • Optional features: python, dds-transport, benchmarks
  • Core dependencies: tokio, serde, uuid, tracing, dashmap, bincode
  • Python bindings: PyO3 with asyncio support

Performance Considerations

  • Sub-millisecond message latency target

  • 1000-10000 msgs/sec throughput depending on message type

  • Zero-copy optimizations for large sensor data
  • Efficient handling of 720-point LaserScans and image data