ROS 2 Control Ecosystem Visualizer

Real-time visualization and monitoring tool for ROS 2 Control ecosystems. Visualize controllers, hardware components, and their connections with an intuitive web-based interface powered by D3.js and WebSocket technology.

Platform: ROS 2 on Linux (Ubuntu 20.04+, Humble or later)

Overview

The ROS 2 Control Ecosystem Visualizer provides roboticists and developers with a comprehensive dashboard to monitor and manage their ROS 2 control systems in real-time. Built with modern web technologies, it offers a responsive interface that works seamlessly across different operating systems.

Key Highlights

Real-time Synchronization: Live updates via WebSocket
Interactive Graph Visualization: Force-directed D3.js graphs with drag-and-drop node repositioning
Service Integration: Direct integration with ROS 2 /controller_manager/switch_controller service
Full Controller Management: Activate/deactivate controllers from the UI or CLI
Visual Status Indicators: Color-coded status for quick system health assessment
Configuration Management: Import YAML/JSON ecosystem definitions or paste directly

Features

Feature	Description
Real-time D3.js Visualization	Force-directed graph with automatic layout and collision detection
Live Status Updates	WebSocket connection for instant state changes
Interactive Web UI	Click nodes to inspect, drag to reposition, zoom and pan
Controller Management	Activate/deactivate controllers from UI with strictness modes
Load Configurations	Import YAML/JSON ecosystem definitions from files
Paste Configurations	Load directly from clipboard for quick testing
CLI Integration	Native ROS 2 commands + npm fallback
Interface Visualization	Auto-detect and draw controller-hardware connections
ROS 2 Service Integration	Direct calls to controller manager switch service
State Persistence	Real-time ecosystem state tracking

Installation

Step 1: Clone Repository

# Create/navigate to your ROS 2 workspace source directory
cd ~/ros2_ws/src

# Clone the repository
git clone https://github.com/Vai-Man/ROS2-Visualizer.git ros2_control_visualizer

cd ros2_control_visualizer

Step 2: Install Node.js Dependencies

# Install backend dependencies
cd backend
npm install

# Install frontend dependencies
cd ../frontend
npm install

# Return to workspace root
cd ~/ros2_ws

Step 3: Build ROS 2 Package

# Build the package using colcon
colcon build --packages-select ros2_control_visualizer

# Source the setup file
source install/setup.bash

Step 4: Verify Installation

# Verify the CLI is available
ros2 run ros2_control_visualizer cli --help

# Expected output: Shows all available CLI commands

Quick Start

Terminal 1: Start Backend Server

# Source ROS 2 environment (important for service integration)
source /opt/ros/humble/setup.bash
source ~/ros2_ws/install/setup.bash

# Navigate to backend
cd ~/ros2_ws/src/ros2_control_visualizer/backend

# Start the server (runs on ws://localhost:8080)
npm start

Terminal 2: Start Frontend Development Server

# In a new terminal
cd ~/ros2_ws/src/ros2_control_visualizer/frontend

# Start the frontend (runs on http://localhost:3000)
npm start

Terminal 3: Populate Sample Ecosystem

# Source ROS 2 environment
source /opt/ros/humble/setup.bash
source ~/ros2_ws/install/setup.bash

# Add a controller
ros2 run ros2_control_visualizer cli add-node arm_controller JointTrajectoryController \
  --status inactive \
  --command-interfaces position,velocity \
  --state-interfaces position,velocity,effort

# Add hardware component
ros2 run ros2_control_visualizer cli add-node robot_arm Actuator \
  --status ok \
  --command-interfaces position,velocity \
  --state-interfaces position,velocity,effort

# Add a second controller
ros2 run ros2_control_visualizer cli add-node gripper_controller GripperController \
  --status inactive \
  --command-interfaces position,force \
  --state-interfaces position,force

# List all nodes to verify
ros2 run ros2_control_visualizer cli list-nodes

# Activate a controller
ros2 run ros2_control_visualizer cli activate arm_controller

Step 4: Open in Browser

Open your web browser and navigate to: http://localhost:3000

You should see the interactive ecosystem visualization with your added components.

Web UI Overview

The web interface provides an intuitive dashboard for managing your ROS 2 control ecosystem.

Component	Function
Center Graph Area	D3.js visualization of your ecosystem with interactive nodes
Left Sidebar	Configuration loading, node management, and controls
Right Panel	Detailed node information when a node is selected
Top Toolbar	Statistics, search/filter functionality, and view controls
Status Indicators	Real-time color-coded health status

Node Visual Indicators

🟢 Green     → Active controller / OK hardware component
🟠 Orange    → Inactive controller / Degraded hardware
🔴 Red       → Failed/Unavailable status
⭕ Circle    → Controller type
▭ Rectangle  → Hardware component type

User Actions

Click Node: View detailed information in the right panel
Drag Node: Reposition nodes in the graph
Zoom: Scroll to zoom in/out
Pan: Click and drag the background to pan
Double-click: Reset node to original position
Right-click: Context menu (planned feature)

CLI Commands Reference

All commands require the ROS 2 environment to be sourced:

source /opt/ros/humble/setup.bash

Add a New Node

ros2 run ros2_control_visualizer cli add-node <name> <type> \
  --status <status> \
  --command-interfaces <list> \
  --state-interfaces <list>

# Examples:
ros2 run ros2_control_visualizer cli add-node my_controller JointTrajectoryController \
  --status inactive --command-interfaces position,velocity --state-interfaces position,velocity

ros2 run ros2_control_visualizer cli add-node robot_hardware Actuator \
  --status ok --command-interfaces position,velocity --state-interfaces position,velocity,effort

Parameters:

<name>: Unique identifier for the node
<type>: Type of component (e.g., JointTrajectoryController, GripperController, Actuator)
--status: Initial status (active/inactive/failed for controllers, ok/degraded/unavailable for hardware)
--command-interfaces: Comma-separated list without spaces (e.g., position,velocity,force)
--state-interfaces: Comma-separated list without spaces (e.g., position,velocity,effort)

List All Nodes

ros2 run ros2_control_visualizer cli list-nodes [options]

# With filters:
ros2 run ros2_control_visualizer cli list-nodes --type controller
ros2 run ros2_control_visualizer cli list-nodes --status active
ros2 run ros2_control_visualizer cli list-nodes --type hardware --status ok

Show Node Details

ros2 run ros2_control_visualizer cli show-node <name>

# Example:
ros2 run ros2_control_visualizer cli show-node my_controller

Remove a Node

ros2 run ros2_control_visualizer cli remove-node <name>

# Example:
ros2 run ros2_control_visualizer cli remove-node my_controller

Update Node Properties

ros2 run ros2_control_visualizer cli update-node <name> \
  --status <status> \
  --command-interfaces <list> \
  --state-interfaces <list>

# Example:
ros2 run ros2_control_visualizer cli update-node my_controller \
  --status active --command-interfaces position,velocity

Controller Management

# Activate a controller
ros2 run ros2_control_visualizer cli activate <name> [--strictness strict|best_effort]

# Deactivate a controller
ros2 run ros2_control_visualizer cli deactivate <name> [--strictness strict|best_effort]

# Examples:
ros2 run ros2_control_visualizer cli activate arm_controller
ros2 run ros2_control_visualizer cli deactivate gripper_controller --strictness strict

Strictness Modes:

strict: Fails if any controller cannot be activated/deactivated
best_effort (default): Attempts to activate/deactivate all controllers, continues on failure

Ecosystem Status

# Check overall ecosystem state
ros2 run ros2_control_visualizer cli status

# Output includes:
# - Total number of controllers
# - Total number of hardware components
# - Currently active controllers
# - System timestamp

Configuration Management

Load Configuration from File

ros2 run ros2_control_visualizer cli load-config <file> [options]

# Options:
ros2 run ros2_control_visualizer cli load-config ~/ecosystem.yaml
ros2 run ros2_control_visualizer cli load-config ~/ecosystem.yaml --clear-first

Clear Ecosystem

ros2 run ros2_control_visualizer cli clear-ecosystem [--confirm]

# Example (with confirmation):
ros2 run ros2_control_visualizer cli clear-ecosystem

Configuration Format

YAML Configuration File

Create a ecosystem.yaml file to define your ROS 2 control ecosystem:

controllers:
  - name: arm_controller
    type: JointTrajectoryController
    status: inactive
    command_interfaces:
      - position
      - velocity
    state_interfaces:
      - position
      - velocity
      - effort
  
  - name: gripper_controller
    type: GripperController
    status: inactive
    command_interfaces:
      - position
      - force
    state_interfaces:
      - position
      - force

hardwareComponents:
  - name: robot_arm
    type: Actuator
    status: ok
    command_interfaces:
      - position
      - velocity
    state_interfaces:
      - position
      - velocity
      - effort
  
  - name: gripper
    type: Gripper
    status: ok
    command_interfaces:
      - position
      - force
    state_interfaces:
      - position
      - force

Load Configuration

Via CLI:

ros2 run ros2_control_visualizer cli load-config ~/ecosystem.yaml

Via Web UI:

Click "Load Configuration" button in left sidebar
Either select a YAML file or paste content
Click "Load" to apply

API Reference

REST Endpoints

Method	Endpoint	Description	Parameters
GET	`/api/ecosystem-state`	Get complete ecosystem state	-
GET	`/api/controllers`	List all controllers	`?status=active`
GET	`/api/controllers/:name`	Get controller details	-
GET	`/api/hardware-components`	List all hardware	`?status=ok`
GET	`/api/hardware-components/:name`	Get hardware details	-
GET	`/api/active-controllers`	List active controllers	-
POST	`/api/add-node`	Add new controller/hardware	JSON body
POST	`/api/remove-node`	Remove a node	JSON body
PUT	`/api/update-node/:name`	Update node properties	JSON body
POST	`/api/switch-controllers`	Activate/deactivate controllers	JSON body with ROS 2 service call
POST	`/api/load-config`	Load config from file	`{ configPath }`
POST	`/api/load-config-content`	Load config from content	`{ content }`
POST	`/api/clear-ecosystem`	Clear all nodes	-

WebSocket Events

// Message Types
{
  "type": "initial_state",      // New connection gets current state
  "type": "node_added",          // Node was added to ecosystem
  "type": "node_removed",        // Node was removed
  "type": "node_updated",        // Node properties changed
  "type": "switch_request",      // Controller switched (with ROS 2 result)
  "type": "config_loaded",       // Configuration loaded
  "type": "ecosystem_cleared",   // Ecosystem was cleared
  "type": "state_updated",       // General state update
  "type": "error"                // Error message
}

Testing

Test the System

# Terminal 1: Backend
cd ~/ros2_ws/src/ros2_control_visualizer/backend
npm start

# Terminal 2: Frontend
cd ~/ros2_ws/src/ros2_control_visualizer/frontend
npm start

# Terminal 3: Add components and test
source /opt/ros/humble/setup.bash
source ~/ros2_ws/install/setup.bash

# Create test components
ros2 run ros2_control_visualizer cli add-node test_controller TestController --status inactive
ros2 run ros2_control_visualizer cli add-node test_hardware TestHW --status ok

# Verify ecosystem
ros2 run ros2_control_visualizer cli status

# Test activation (will show service integration status)
ros2 run ros2_control_visualizer cli activate test_controller

# Open browser and check visualization
# http://localhost:3000

Building from Source

# 1. Clone repository
cd ~/ros2_ws/src
git clone https://github.com/Vai-Man/ROS2-Visualizer.git ros2_control_visualizer
cd ros2_control_visualizer

# 2. Install Node dependencies
cd backend && npm install && cd ..
cd frontend && npm install && cd ..

# 3. Build TypeScript
cd backend && npm run build && cd ..
cd frontend && npm run build && cd ..

# 4. Build ROS 2 package
cd ~/ros2_ws
colcon build --packages-select ros2_control_visualizer
source install/setup.bash

Running Tests

cd backend
npm test

cd ../frontend
npm test

Code Style & Linting

# Backend
cd backend
npm run lint
npm run format

# Frontend  
cd frontend
npm run lint
npm run format

Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch: git checkout -b feature/your-feature
Make your changes and test thoroughly
Commit with clear messages: git commit -m "Add your feature"
Push to your fork: git push origin feature/your-feature
Open a Pull Request with description

Code Standards

Use TypeScript for type safety
Follow existing code style
Write meaningful commit messages
Add tests for new features
Update documentation

Reporting Issues

When reporting bugs, please include:

ROS 2 distribution and version
Node.js version
Operating system
Detailed steps to reproduce
Expected vs actual behavior
Relevant logs/error messages

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
backend		backend
frontend		frontend
.gitignore		.gitignore
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

ROS 2 Control Ecosystem Visualizer

Overview

Key Highlights

Features

Installation

Step 1: Clone Repository

Step 2: Install Node.js Dependencies

Step 3: Build ROS 2 Package

Step 4: Verify Installation

Quick Start

Terminal 1: Start Backend Server

Terminal 2: Start Frontend Development Server

Terminal 3: Populate Sample Ecosystem

Step 4: Open in Browser

Web UI Overview

Node Visual Indicators

User Actions

CLI Commands Reference

Add a New Node

List All Nodes

Show Node Details

Remove a Node

Update Node Properties

Controller Management

Ecosystem Status

Configuration Management

Load Configuration from File

Clear Ecosystem

Configuration Format

YAML Configuration File

Load Configuration

Via CLI:

Via Web UI:

API Reference

REST Endpoints

WebSocket Events

Testing

Test the System

Building from Source

Running Tests

Code Style & Linting

Contributing

Code Standards

Reporting Issues

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages