Greenwave Monitor

Greenwave monitor is a tool for runtime monitoring of ROS 2 topics.

It provides the following features:

1. A node similar to a C++ based ros2 topic hz. i.e. subscribes to topics to determine the frame rate and latency. Compared to ros2 topic hz the greenwave node is more performant, publishes Diagnostics, and offers services to manage topics and expected frequencies.

2. A terminal based dashboard that displays the topic rates, latency, and status, and allows you to add/remove topics and set expected frequencies.

3. A header only C++ library so you can calculate and publish compatible diagnostics directly from your own nodes for reduced overhead.

This diagram shows an overview of the architecture:

Diagnostic messages

The diagnostics messages published by greenwave monitor are valid ROS 2 Diagnostics messages, however the dashboard does rely on specific keys to associate the data with the correct topic, and to find frequency and latency data.

In particular, the messages follow conventions from Isaac ROS NITROS, which means configured NITROS nodes can be monitored by greenwave monitor frontends without any additional subscriber overhead. For example the drivers from Isaac ROS NOVA can be monitored out of the box. Furthermore, you can set ENABLE_GLOBAL_NITROS_DIAGNOSTICS=1 to configure all NITROS nodes to publish diagnostics (more info here).

## Latency Measurements

Latency is calculated as the difference between the current system time and the timestamp in the message header. For this calculation to work correctly:

• The message type must have a std_msgs/Header field
• The message type must be in the recognized types list (see has_header_from_type() in greenwave_monitor.cpp)
• The header timestamp must be in epoch time (not boottime)

If any of these conditions are not met, the latency will be reported as “N/A” in the dashboard. This typically occurs when:

• The message type doesn’t have a header (e.g., std_msgs/String, geometry_msgs/Twist)
• The message type is not recognized by greenwave monitor
• The header timestamp is in boottime format instead of epoch time

Currently, message types with headers must be manually registered in the known_header_types map in greenwave_monitor.cpp. Support for automatic detection of arbitrary message types may be added in the future. In the meantime, if you need support for a commonly used message type, please submit an issue or pull request to add it to the registry.

Compatibility

Greenwave monitor is a standalone package tested on Humble, Iron, Jazzy, Kilted, and Rolling ROS 2 releases, under Ubuntu 22.04 and Ubuntu 24.04. It does not depend on Isaac ROS.

Installation

From source:

cd ros_ws/src
git clone https://github.com/NVIDIA-ISAAC-ROS/greenwave_monitor.git
cd ..
colcon build --packages-up-to greenwave_monitor
source install/setup.bash

Usage

Greenwave monitor provides two dashboard frontends, a lightweight ncurses interface and a rich terminal interface (a fork of r2s). Note we rename the fork r2s_gw to avoid conflicts with the original r2s package.

We have found that the r2s dashboard gets sluggish when there are many topics, so we recommend using the ncurses dashboard for large deployments.

ncurses Dashboard (Lightweight)

After installing, you can launch the ncurses dashboard with:

ros2 run greenwave_monitor ncurses_dashboard

You can also launch the dashboard with some demo publishers to see everything in action:

ros2 run greenwave_monitor ncurses_dashboard --demo

r2s_gw Dashboard (Rich TUI)

First you need to build the r2s_gw package and some additional dependencies, r2s_gw is included in the greenwave_monitor package.

cd ros_ws/
colcon build --packages-up-to r2s_gw
pip install -I textual # There is a requirements.txt file in the r2s_gw package, but in case you installed from debian and that's not handy ...
source install/setup.bash

Then you can launch the dashboard with the following. Use tab to navigate between different UI elements.

ros2 run greenwave_monitor r2s_gw_dashboard

Just like before, you can also launch the dashboard with some demo publishers to see everything in action.

ros2 run greenwave_monitor r2s_gw_dashboard -- --demo

Manual Launch (ros2 topic hz mode)

You can of course also launch the node standalone, or incorporate it into your own launch files. If you want to use it as a command line tool, you can do so with the following launch file:

File truncated at 100 lines see the full file