rlab-runtime 0.1.0

Platform for digital twin robotics and mechatronics systems

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
• FastAPI (Port 8005): Backend API services
• 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

pip install rlab-runtime

Or install in development mode:

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

Quick Start

1. Setup the Platform

# Using local development images (default)
rlab platform setup --dev

# Or using production images from registry
rlab platform setup --prod

This will:

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

2. Start the Platform

rlab platform start

Access the platform:

• Frontend: http://localhost:3006
• Memgraph Server: http://localhost:3001
• FastAPI: http://localhost:8005
• 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:

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

# 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

rlab platform setup [--dev|--prod]    # Setup RLab platform
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

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

{
  "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   │  │ FastAPI  │  │
│  │  (React)    │  │   Server     │  │          │  │
│  │  :3006      │  │   :3001      │  │  :8005   │  │
│  └─────────────┘  └──────────────┘  └──────────┘  │
│                                                     │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────┐  │
│  │  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

# 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

# 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
• rosversity/fastapi:latest
• rosversity/terminal:latest
• rosversity/rlabsdk:latest
• rosversity/comfyui:latest

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

# 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

# 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:

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

Container keeps restarting

# 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:

# 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
• FastAPI
• Memgraph
• ComfyUI
• Docker