Package Examples

🤖 TurtleBot Control System

The TurtleBot package demonstrates a complete robotics system implementation using miniROS, showcasing package structure, multi-node communication, and real-world control patterns.

📁 Package Structure

packages/turtlebot/
├── package.yaml           # Package metadata and dependencies
├── config/               # Configuration files
├── launch/               # Launch configurations
│   ├── full_system.yaml # Complete system launch
│   ├── simulation.yaml  # Simulation mode
│   └── teleop.yaml      # Teleoperation mode
├── scripts/             # Python utilities
│   └── controller.py    # Python controller implementation
├── src/                 # Rust source code
│   ├── controller.rs    # Main controller logic
│   └── teleop.rs        # Teleoperation interface
└── README.md            # Package documentation

🎯 System Architecture

The TurtleBot system demonstrates a modular robotics architecture:

graph TD
    A[TurtleBot Controller] --> B[Motor Control]
    A --> C[Sensor Processing]
    D[Teleop Interface] --> A
    E[Simulation Engine] --> A
    A --> F[Status Publisher]
    G[Parameter Server] --> A
    A --> H[Action Server]

🔧 Core Components

1. Controller Node (controller.rs)

#![allow(unused)]
fn main() {
// High-performance control loop with configurable parameters
pub struct TurtleBotController {
    linear_speed: f64,
    angular_speed: f64,
    safety_enabled: bool,
    control_frequency: f64,
}

impl TurtleBotController {
    pub fn new() -> Self {
        Self {
            linear_speed: 0.2,      // m/s - safe default speed
            angular_speed: 0.5,     // rad/s - turning rate
            safety_enabled: true,   // collision avoidance
            control_frequency: 50.0, // Hz - control loop rate
        }
    }

    pub async fn run_control_loop(&mut self) -> Result<(), Box<dyn std::error::Error>> {
        // Main control implementation
        // - Subscribe to velocity commands
        // - Process sensor data
        // - Publish motor commands
        // - Handle emergency stops
        Ok(())
    }
}
}

2. Teleoperation Interface (teleop.rs)

#![allow(unused)]
fn main() {
// Keyboard/joystick input processing
pub struct TeleopInterface {
    max_linear: f64,
    max_angular: f64,
    input_source: InputSource,
}

#[derive(Debug)]
pub enum InputSource {
    Keyboard,
    Joystick,
    WebInterface,
}
}

3. Python Integration (controller.py)

#!/usr/bin/env python3
"""
TurtleBot Python Controller - High-level coordination and monitoring
Demonstrates seamless Rust-Python integration in miniROS
"""

import mini_ros
import asyncio
from typing import Dict, Any

class TurtleBotMonitor:
    """High-level system monitor and coordinator"""
    
    def __init__(self):
        self.node = mini_ros.Node("turtlebot_monitor")
        self.system_status = {}
        self.alert_threshold = 0.95
    
    async def monitor_system(self):
        """Monitor system health and performance"""
        while True:
            # Check battery level
            # Monitor CPU usage
            # Validate sensor data
            # Report system status
            await asyncio.sleep(1.0)
    
    def handle_emergency(self, alert_type: str):
        """Emergency response coordination"""
        print(f"🚨 Emergency: {alert_type}")
        # Send stop commands
        # Activate safety protocols
        # Log incident

🚀 Launch Configurations

Full System Launch (launch/full_system.yaml)

name: "TurtleBot Full System"
description: "Complete TurtleBot control system with all components"

nodes:
  - name: "controller"
    package: "turtlebot"
    executable: "controller"
    parameters:
      linear_speed: 0.3
      angular_speed: 0.8
      safety_enabled: true
      
  - name: "teleop"
    package: "turtlebot"
    executable: "teleop"
    parameters:
      input_source: "keyboard"
      
  - name: "monitor"
    package: "turtlebot"
    executable: "python"
    script: "scripts/controller.py"

remappings:
  - from: "/cmd_vel"
    to: "/turtlebot/cmd_vel"
  - from: "/status"
    to: "/turtlebot/status"

Simulation Mode (launch/simulation.yaml)

name: "TurtleBot Simulation"
description: "TurtleBot in simulation environment"

parameters:
  simulation_mode: true
  physics_enabled: true
  visualization: true

nodes:
  - name: "simulator"
    package: "turtlebot"
    executable: "simulator"
    
  - name: "controller"
    package: "turtlebot"
    executable: "controller"
    parameters:
      simulation: true

📋 Usage Examples

1. Launch Complete System

# Start full TurtleBot system
mini_ros launch turtlebot full_system

# Start in simulation mode
mini_ros launch turtlebot simulation

# Teleoperation only
mini_ros launch turtlebot teleop

2. Run Individual Nodes

# Run controller with custom parameters
mini_ros run turtlebot controller --args --speed 0.5 --safety false

# Run Python monitor
mini_ros_py run turtlebot_controller

# Run teleop interface
mini_ros run turtlebot teleop --args --input joystick

3. Parameter Management

# List available parameters
mini_ros pkg info turtlebot

# Set runtime parameters
mini_ros param set /turtlebot/linear_speed 0.4
mini_ros param set /turtlebot/safety_enabled true

# Save parameter configuration
mini_ros param dump turtlebot_config.yaml

🧪 Testing and Validation

Unit Tests

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;
    
    #[test]
    fn test_controller_initialization() {
        let controller = TurtleBotController::new();
        assert_eq!(controller.linear_speed, 0.2);
        assert!(controller.safety_enabled);
    }
    
    #[test]
    fn test_speed_limits() {
        let mut controller = TurtleBotController::new();
        controller.set_linear_speed(10.0); // Should be clamped
        assert!(controller.linear_speed <= controller.max_linear_speed);
    }
}
}

Integration Tests

#!/usr/bin/env python3
"""Integration tests for TurtleBot system"""

import pytest
import mini_ros
import asyncio

class TestTurtleBotSystem:
    
    @pytest.mark.asyncio
    async def test_full_system_startup(self):
        """Test complete system startup sequence"""
        # Launch system
        # Verify all nodes are running
        # Check communication between nodes
        # Validate parameter settings
        pass
    
    @pytest.mark.asyncio
    async def test_emergency_stop(self):
        """Test emergency stop functionality"""
        # Send emergency stop command
        # Verify immediate response
        # Check safety protocols activated
        pass

📊 Performance Metrics

The TurtleBot package demonstrates miniROS performance characteristics:

🎯 Best Practices Demonstrated

1. Modular Design

• Separate nodes for different responsibilities
• Clear interfaces between components
• Configurable behavior via parameters

2. Language Integration

• Rust for performance-critical control loops
• Python for high-level coordination
• Seamless cross-language communication

3. Configuration Management

• YAML-based launch files
• Runtime parameter adjustment
• Environment-specific configurations

4. Safety and Reliability

• Emergency stop mechanisms
• Input validation and bounds checking
• System health monitoring

5. Testing Strategy

• Unit tests for individual components
• Integration tests for system behavior
• Performance benchmarking

🔍 Other Package Examples

Basic Publisher-Subscriber Package

packages/basic_pubsub/
├── package.yaml
├── src/
│   ├── publisher.rs    # High-frequency data publisher
│   └── subscriber.rs   # Real-time data consumer
└── examples/
    └── demo.rs         # Usage demonstration

Service-Based Calculator Package

packages/calculator/
├── package.yaml
├── src/
│   ├── server.rs      # Math service implementation
│   └── client.rs      # Service consumer
└── services/
    └── math.rs        # Custom service definitions

Multi-Language Integration Package

packages/integration/
├── package.yaml
├── src/
│   └── rust_node.rs   # Rust performance node
├── scripts/
│   └── python_node.py # Python AI/ML node
└── launch/
    └── mixed.yaml     # Cross-language system

Philosophy: Real-world robotics complexity, miniROS simplicity 🤖🎯