rlab-runtime 0.2.3rc2
Platform for digital twin robotics and mechatronics systems
License: MIT
Requires Python: >=3.8
Keywords: robotics, digital-twin, ros2, mechatronics, plc

# RLab - Robotics Laboratory Platform

A comprehensive platform for digital twin robotics and mechatronics systems.

## Overview

RLab provides a complete environment for building, deploying, and managing digital twin systems. It orchestrates multiple containerized services to deliver a full-stack robotics development and simulation platform.

### Platform Components

- **Neuroid Frontend** (Port 3006): Modern React-based web UI for system management
- **Memgraph Server** (Port 3001): Graph database connection layer for digital twin state
- **RLab SDK** (Ports 8080, 9000): C++ runtime for digital twin processes with ROS2 integration
- **Terminal** (Port 3003): Web-based terminal access to rlab-runtime CLI
- **ComfyUI** (Port 8188): Visual workflow builder with Pneumatic Kit integration

## Installation

```bash
pip install rlab-runtime
```

Or install in development mode:

```bash
git clone https://github.com/rosversity/rlab.git
cd rlab
pip install -e .
```

## Quick Start

### 1. Setup the Platform

# Using production images from registry (default)

rlab platform setup

# Or using local development images

rlab platform setup --dev

````

### 2. Login to Docker Registry (if using private images)

```bash
rlab platform login --username <user> --token <ghp_token>
````

This will:

- Check Docker installation
- Create necessary directories
- Generate configuration files
- Setup Docker Compose with all services

### 2. Start the Platform

```bash
rlab platform start
```

Access the platform:

- **Frontend**: http://localhost:3006
- **Memgraph Server**: http://localhost:3001
- **Core API**: http://localhost:8080
- **SDK API**: http://localhost:9000
- **Terminal**: http://localhost:3003
- **ComfyUI**: http://localhost:8188

### 3. Load and Run a .nuero Product File

Load a `.nuero` product file and run the digital twin:

```bash
rlab platform load /path/to/pneumatic-kit.nuero --port 8080
```

This will:

- Copy the .nuero file to the rlab-sdk container
- Execute the rlab_runtime binary with the product file
- Start the digital twin server on the specified port

### 4. Manage the Platform

```bash
# View logs
rlab platform logs -f              # Follow all logs
rlab platform logs -s rlab-sdk     # View specific service logs

# Check status
rlab platform status

# Stop the platform
rlab platform stop

# Restart the platform
rlab platform restart

# Open web interface
rlab platform ui

# Clean up (removes all data)
rlab platform cleanup
```

## CLI Commands

### Platform Management

```bash
rlab platform setup [--dev]           # Setup RLab platform
rlab platform login -u -t [-r]        # Login to Docker registry
rlab platform start [-d]              # Start all services (detached)
rlab platform stop                    # Stop all services
rlab platform restart                 # Restart all services
rlab platform status                  # Show platform status
rlab platform logs [-f] [-s SERVICE]  # View logs
rlab platform load FILE [--port PORT] # Load and run .nuero file
rlab platform ui                      # Open web interface
rlab platform cleanup                 # Remove all RLab data
```

### Digital Twin Operations

```bash
rlab project     # Project management operations
rlab entity      # Entity hierarchy management
rlab process     # Process design and execution
rlab model       # Model component management
rlab twin        # Twin dashboard management
rlab shadow      # Shadow API management
rlab status      # Show complete system status
rlab sync        # Synchronize with backend server
rlab validate    # Validate project configuration
```

## .nuero File Format

A `.nuero` file is a compressed archive containing product-specific components for digital twin robotics systems:

```
pneumatic-kit.nuero
├── product.json              # Product metadata
├── implementations/          # C++ plugins (.so files)
│   ├── libproduct_impl.so
│   └── libsystem_impl.so
├── visualization/            # RViz/URDF files
│   ├── urdf/
│   │   └── robot.urdf
│   └── rviz/
│       └── config.rviz
├── configs/                  # Product configurations
│   ├── plc_config.json
│   └── physics_config.json
└── processes/                # Process definitions
    ├── main.cpp
    └── config/
```

### product.json Example

```json
{
  "name": "pneumatic-kit",
  "version": "1.0.0",
  "type": "mechatronics-station",
  "description": "Pneumatic Kit Digital Twin",
  "author": "RosVersity",
  "components": {
    "products": ["PneumaticKitProduct"],
    "systems": ["PneumaticSystem", "ElectricalSystem", "ControlSystem"],
    "assets": ["SACAsset", "SSVAsset", "DACAsset", "DSVAsset"]
  }
}
```

## Architecture

```
┌─────────────────────────────────────────────────────┐
│         RLab Platform (Docker Compose)              │
├─────────────────────────────────────────────────────┤
│                                                     │
│  ┌─────────────┐  ┌──────────────┐                  │
│  │  Frontend   │  │   Memgraph   │                  │
│  │  (React)    │  │   Server     │                  │
│  │  :3006      │  │   :3001      │                  │
│  └─────────────┘  └──────────────┘                  │
│                                                     │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────┐  │
│  │  RLab SDK   │  │   Terminal   │  │ ComfyUI  │  │
│  │  (C++/ROS2) │  │   (Node.js)  │  │ (Python) │  │
│  │  :8080,9000 │  │   :3003      │  │  :8188   │  │
│  └─────────────┘  └──────────────┘  └──────────┘  │
│                                                     │
└─────────────────────────────────────────────────────┘
                       ↓
           Load .nuero file via CLI
                       ↓
┌─────────────────────────────────────────────────────┐
│       Product-Specific Components                   │
├─────────────────────────────────────────────────────┤
│  - C++ Implementations (ROS2 plugins)               │
│  - Visualization (URDF, RViz configs)               │
│  - Configurations (PLC, Physics, etc.)              │
│  - Process Definitions                              │
└─────────────────────────────────────────────────────┘
```

## Requirements

- **Docker**: >= 20.10
- **Docker Compose**: >= 2.0
- **Python**: >= 3.8
- **OS**: Linux (Ubuntu 20.04+)

For GPU support (ComfyUI):

- NVIDIA GPU with CUDA support
- nvidia-docker2

## Development Mode

### Using Local Development Images

```bash
# Setup with local dev images
rlab platform setup --dev
```

This uses local images:

- `docker-frontend:latest`
- `docker-memgraph-server:latest`
- `docker-fastapi:latest`
- `docker-terminal:latest`
- `rosversity/rlabsdk:dev`
- `pneumatic-kit-viz:latest`

### Using Production Images

```bash
# Setup with production images from registry
rlab platform setup --prod
```

This uses registry images:

- `ghcr.io/rosversity/nueroid_frontend/dtide-frontend:latest`
- `ghcr.io/rosversity/nueroid_frontend/dtide-memgraph-server:latest`
- `ghcr.io/rosversity/rlab-terminal:sha-200955d`
- `ghcr.io/rosversity/rlabsdk:sha-16c5916-development`
- `ghcr.io/rosversity/comfyui:pavan-feature-process`

## Directory Structure

```
~/.rlab/
├── .env                    # Environment variables
├── docker-compose.yml      # Docker orchestration
├── config/                 # Configuration files
│   └── core.yml
├── data/                   # Persistent data
│   ├── core/
│   ├── uploads/
│   └── comfyui/
├── logs/                   # Application logs
├── products/               # Installed products
└── nuero_files/            # Loaded .nuero files
```

## Troubleshooting

### Docker not found

```bash
# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
```

### Services not starting

```bash
# Check logs for all services
rlab platform logs -f

# Check specific service logs
rlab platform logs -s rlab-sdk

# Check platform status
rlab platform status

# Restart services
rlab platform restart
```

### Port conflicts

Edit `~/.rlab/.env` or use environment variables:

```bash
export ROS_DOMAIN_ID=43
export MEMGRAPH_HOST=192.168.1.100  # For remote Memgraph server
rlab platform start
```

### Container keeps restarting

```bash
# View container logs
rlab platform logs -s rlab-sdk

# Check Docker container status
docker ps -a | grep rlab
```

## Integration with External Systems

### Connecting to Remote Memgraph Server

The platform supports connecting to a remote Memgraph database server:

```bash
# Set the Memgraph host before starting
export MEMGRAPH_HOST=192.168.1.100
rlab platform start
```

The memgraph-server service will connect to `bolt://${MEMGRAPH_HOST}:7687`

## License

MIT License - see LICENSE file for details

## Support

- **Documentation**: https://docs.rosversity.com
- **Issues**: https://github.com/rosversity/rlab/issues
- **Community**: https://community.rosversity.com
- **Discord**: https://discord.gg/rosversity

## Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.

## Acknowledgments

Built with:

- ROS2 Humble
- React + Vite
- Memgraph
- ComfyUI
- Docker