ROS 2 Control Ecosystem Visualization

Visualize Nodes in a intutive Directed Acyclic Graph format - Get realtime updates
Try Demo

Demo: Real-time visualization of ROS 2 control system

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

This project is a ROS 2-based Directed Acyclic Graph (DAG) visualizer that subscribes to a custom topic, processes incoming messages, and updates a graph dynamically. The graph is interactive, displays metadata, and distinguishes edges based on the message attributes.

System Architecture: How the ROS 2 nodes interact with the web interface

Built With

• 
• 
• 
• 
• 
• 
• 

Features

• ROS 2 Subscription & Service Call: A ROS 2 node subscribes to a topic and sends a service request.
• Custom Message Definition: Implements a custom message format for defining directed edges.
• TypeScript-based Graph Visualization: The DAG is displayed using TypeScript, earning extra points for interactivity and metadata display.
• Dynamic Graph Updates: Graph updates in real-time based on received ROS messages.
• Metadata Display: Each node contains metadata information for better visualization.
• Edge Coloring Rules:
  • Command interface (command_interface = true): Edge is shown in a specific color.
  • State interface (state_interface = true): Another distinct color.
  • Hardware-based (is_hardware = true): Highlighted accordingly.

Visualization Features: Node metadata, edge coloring, and interactive elements

Custom Message Definition

This project defines a custom ROS 2 message type:

string start
string end
bool command_interface
bool state_interface
bool is_hardware
string metadata

(back to top)

Getting Started

Prerequisites

• For ROS package

  • Install ROS2 - Jazzy (Documentation)
  • Clone and Setup ROS2 Workspace - ros2-control-viz

• For Web Interface

  • Node.js (LTS recommended)
  • npm or yarn
  • Clone and Setup Web Interface - ros2_control_web
  • TurtleSim package (for the TurtleSim example)

Setup Instructions for the web interface

1. Clone the repository

   git clone https://github.com/Malay-dev/ros2_control_web.git
   cd ros2_control_web

2. Install dependencies

   npm install

3. Start the development server

   npm run dev

4. Access the web interface

   • Open your browser and navigate to http://localhost:3000
   • The interface will show "Disconnected" status initially

Connect to ROS2

1. Set up the ROS2 backend

   • Make sure you have installed and configured ros2_control_viz
   • Follow the instructions in the ROS2 Package Setup section to start the backend

2. Verify connection

   • When the ROS2 backend is properly running, the web interface will automatically connect
   • Connection status will change to "Connected"
   • Control values will begin populating in real-time

Setup Instructions for the ROS Package

Installing Dependencies

First, ensure you have all necessary dependencies:

# Install ROS 2 dependencies
sudo apt update
sudo apt install -y ros-jazzy-turtlesim

# Install Python dependencies
pip3 install websockets asyncio

Setting Up the Workspace

1. Create a new ROS 2 workspace or use an existing one:

# Create a new workspace (if needed)
mkdir -p ~/ros2_ws/src
cd ~/ros2_ws/src

# Clone the repository
git clone https://github.com/Malay-dev/ros2_control_viz.git

2. Build the workspace:

cd ~/ros2_ws
colcon build --symlink-install

3. Source the workspace:

source ~/ros2_ws/install/setup.bash

Tip: Add this line to your ~/.bashrc file to automatically source the workspace in every new terminal:

echo "source ~/ros2_ws/install/setup.bash" >> ~/.bashrc

Running Examples

Basic Example

This example demonstrates the core functionality of publishing and subscribing to graph updates:

1. In one terminal, run the graph subscriber:

ros2 run ros2_control_viz graph_subscriber

2. In another terminal, run the graph publisher:

ros2 run ros2_control_viz graph_publisher

You should see output in the subscriber terminal showing the connections being published:

[INFO] [graph_subscriber]: Received: A -> B | Metadata: {"type": "controller", "priority": 1, "rate": "100Hz"}
[INFO] [graph_subscriber]: Received: B -> C | Metadata: {"type": "state_handler", "priority": 2, "status": "active"}
...

Terminal Output: Subscriber (Left) receiving graph updates from publisher (Right)

Basic Example with Web Interface Visualization

This setup connects the graph publisher to a web interface for visual representation:

1. Start the WebSocket bridge server:

ros2 run ros2_control_viz web_socket_graph

2. In another terminal, run the graph publisher:

ros2 run ros2_control_viz graph_publisher

3. In a web browser, navigate to the web interface:
   • If using the hosted demo: https://ros-control-viz.vercel.app/
   • If running locally: http://localhost:3000

You should see a live visualization of the graph with color-coded edges indicating command interfaces, state interfaces, and hardware components.

Live Graph: Dynamic visualization with color-coded edges and nodes

Visualization Legend:

• Controller
• Hardware/Actuator
• Joint
• Other
• Command Interface
• State Interface
• Other Connection
• Solid Line for edge
• Dashed Line for edge update

TurtleSim Integration Example

This example visualizes the data flow between TurtleSim and teleop controls:

1. Start the WebSocket bridge server:

ros2 run ros2_control_viz web_socket_graph

2. In another terminal, start the TurtleSim node:

ros2 run turtlesim turtlesim_node

3. In another terminal, start the TurtleSim teleop:

ros2 run turtlesim turtle_teleop_key

4. In a fourth terminal, start the turtle graph publisher:

ros2 run ros2_control_viz turtle_graph_publisher

5. Open the web interface at http://localhost:3000 (or the hosted demo)

6. Use the arrow keys in the teleop terminal to control the turtle

TurtleSim Integration: Real-time visualization of turtle movement and control flow

The visualization will update in real-time, showing:

• Commands flowing from the teleop to the turtle
• State information flowing from the turtle
• Metadata including position and velocity

Troubleshooting

Common Issues

1. "Package 'ros2_control_viz' not found":

   • Make sure you've built the workspace: cd ~/ros2_ws && colcon build
   • Ensure you've sourced the workspace: source ~/ros2_ws/install/setup.bash

2. WebSocket connection issues:

   • Check that the WebSocket server is running
   • Verify that port 8765 is not blocked by a firewall
   • Check the server logs for any connection errors

3. No visualization in the web interface:

   • Ensure the WebSocket server shows a "connected" status in the web interface
   • Verify that graph updates are being published (check the publisher terminal)
   • Try refreshing the web interface

Publishing Custom Graph Updates

You can publish your own graph updates from the command line:

ros2 topic pub /graph_update ros2_control_viz_interfaces/msg/GraphUpdate '{start: "Custom1", end: "Custom2", command_interface: true, state_interface: false, is_hardware: true, metadata: "{\"description\": \"My custom connection\"}"}'

Note: Checkout turtle_connector.py for more info on how to translate your custom package msgs to GraphUpdate.msg

Roadmap

• Add Readme
• Stricter Type Checks
• User Interface/User Experience
• Dynamic Layout lags
• Research for better graph simulations
• Add More Example Connectors

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star⭐! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Maintainer

Malay Kumar - Twitter (X) @void_MalayK | LinkedIn @malayk

(back to top)