|
1 | 1 | # Greenwave Monitor |
| 2 | +Greenwave monitor is a tool for runtime monitoring of ROS 2 topics. |
2 | 3 |
|
3 | | -A high-performance diagnostic tool for ROS 2 that provides real-time monitoring of topic frame rates and latency metrics. The monitor node is like a more performant `ros2 topic hz` with ROS2 Diagnostics output, and services to manage topics. The dashboard is a terminal-based interface that provides a real-time view of the monitoring data, as well as displaying diagnostic data published by sensor drivers. |
| 4 | + |
4 | 5 |
|
5 | | -The diagnostics messages follow conventions from [Isaac ROS NITROS](https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_nitros), that means configured NITROS nodes can be monitored with the same tool without additional subscriber overhead. For example the drivers from [Isaac ROS NOVA](https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_nova) can be monitored with the same tool (also, did you know you can enable all NITROS nodes to publish diagnostics? see the bottom of [this](https://nvidia-isaac-ros.github.io/repositories_and_packages/isaac_ros_nitros/isaac_ros_nitros/index.html) page). |
| 6 | +1. Provides a node that behaves like C++ based ros2 topic hz. I.E. subscribes to topics to determine the frame rate and latency. compared to ro2s topic hs the greenwave node is more performant, publishes ROS2 Diagnostics, and offers services to manage topics and expected frequencies. |
6 | 7 |
|
7 | | -Finally, we provide monitoring code as a standalone C++ header, which can be integrated into your own nodes. |
| 8 | +2. Provides a terminal based dashboard that displays the topic rates, latency, and status, and allows you to add/remove topics and set expected frequencies. |
8 | 9 |
|
9 | | -## Dashboard Interfaces |
| 10 | +3. Provides a header only C++ library so you can calculate and publish compatible diagnostics directly from your own nodes for reduced overhead. |
10 | 11 |
|
11 | | -The Greenwave Monitor provides two terminal-based dashboard options: |
| 12 | +This diagram shows an overview of the architecture  |
12 | 13 |
|
13 | | -### r2s_gw Dashboard (Rich TUI) |
14 | | -Ships with a fork of [r2s](https://github.com/mjcarroll/r2s) to provide an intuitive terminal interface that displays real-time statistics for all monitored topics. Click around with your mouse and tab key, and see the bottom bar with keyboard shortcuts. |
| 14 | +## Diagnostics Messages |
15 | 15 |
|
16 | | - |
| 16 | +The diagnostics messages published by greenwave monitor are valid ROS2 Diagnostics messages, however the dashboard does rely on specific keys to associate the data with the correct topic, and to display the data in the correct format. |
17 | 17 |
|
18 | | -### ncurses Dashboard (Lightweight) |
19 | | -A lightweight ncurses-based interface focused specifically on topic monitoring with keyboard navigation. Features color-coded status indicators, interactive frequency management, and filtering options. |
| 18 | +In particular, the messages follow conventions from [Isaac ROS NITROS](https://github.com/NVIDIA-ISAAC-ROS/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](https://github.com/NVIDIA-ISAAC-ROS/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](https://nvidia-isaac-ros.github.io/repositories_and_packages/isaac_ros_nitros/isaac_ros_nitros/index.html)). |
20 | 19 |
|
21 | | -## Key Features |
| 20 | +## Compatibility |
22 | 21 |
|
23 | | -- **High Performance**: Up to 10x more CPU efficient than the built-in `ros2 topic hz` command |
24 | | -- **Multiple Dashboard Options**: Choose between rich TUI (r2s_gw) or lightweight ncurses interface |
25 | | -- **Real-time Monitoring**: Live visualization of topic rates, latency, and status with color-coded indicators |
26 | | -- **Interactive Management**: Add/remove topics and set expected frequencies directly from the interface |
27 | | -- **Universal Compatibility**: Displays diagnostics from any source that publishes a compatible `/diagnostics` topic, including NVIDIA Nova sensors and other hardware drivers |
| 22 | +Greenwave monitor is a standalone package tested on Humble, Iron, Jazzy, Kilted, and Rolling ROS2 releases, under Ubuntu 22.04 and Ubuntu 24.04. It does not depend on Isaac ROS *(but does play nicely with it)*. |
28 | 23 |
|
29 | 24 | ## Installation |
30 | | -TODO |
31 | 25 |
|
| 26 | +From source: |
32 | 27 | ```bash |
33 | 28 | cd ros_ws/src |
34 | | -git clone https://gitlab-master.nvidia.com/sgillen/ros2_monitor_node.git |
| 29 | +git clone https://github.com/NVIDIA-ISAAC-ROS/greenwave_monitor.git |
35 | 30 | cd .. |
36 | | -colcon build --symlink-install --packages-up-to r2s_gw |
37 | | -pip3 install -r requirements.txt --break-system-packages |
| 31 | +colcon build --packages-up-to greenwave_monitor |
38 | 32 | source install/setup.sh |
39 | 33 | ``` |
40 | 34 |
|
41 | 35 | ## Usage |
42 | 36 |
|
43 | | -### Monitor Dashboards |
44 | | - |
45 | | -The easiest way to use Greenwave Monitor is with one of the all-in-one dashboard commands, which provide visibility into all diagnostics, including those from drivers that publish their own diagnostic data. |
| 37 | +Greenwave monitor provides two dashboard frontends, a lightweight ncurses interface and a rich terminal interface (a fork of [r2s](https://github.com/mjcarroll/r2s)). Note we rename the fork r2s_gw to avoid conflicts with the original r2s package. |
46 | 38 |
|
47 | | -#### r2s_gw Dashboard (Rich TUI) |
48 | | - |
49 | | -```bash |
50 | | -ros2 run greenwave_monitor r2s_gw_dashboard |
51 | | -``` |
52 | | - |
53 | | -Features: |
54 | | -- Mouse and keyboard navigation |
55 | | -- Tabbed interface (Topics, Nodes, Interfaces) |
56 | | -- Rich text rendering and charts |
57 | | -- Comprehensive ROS 2 system overview |
| 39 | +We have found that the r2s dashboard gets sluggish when there are many topics, so we recommend using the ncurses dashboard for large deployments. |
58 | 40 |
|
59 | 41 | #### ncurses Dashboard (Lightweight) |
60 | 42 |
|
| 43 | +After installing, you can launch the ncurses dashboard with: |
| 44 | + |
61 | 45 | ```bash |
62 | 46 | ros2 run greenwave_monitor ncurses_dashboard |
63 | 47 | ``` |
64 | 48 |
|
65 | | -Features: |
66 | | -- Keyboard-only navigation (↑/↓ arrows, Enter, etc.) |
67 | | -- Real-time topic monitoring with color-coded status |
68 | | -- Interactive frequency management (`f` to set, `c` to clear) |
69 | | -- Topic filtering (`h` to hide unmonitored topics) |
70 | | -- Minimal resource usage |
71 | | - |
72 | | -##### ncurses Dashboard Controls |
73 | | - |
74 | | -- **↑/↓ arrows**: Navigate topics |
75 | | -- **Enter/Space**: Toggle monitoring for selected topic |
76 | | -- **f**: Set expected frequency for selected topic |
77 | | -- **c**: Clear expected frequency for selected topic |
78 | | -- **h**: Toggle between showing all topics vs monitored only |
79 | | -- **q**: Quit |
80 | | - |
81 | | -Both commands: |
82 | | -- Start the greenwave monitor node in the background |
83 | | -- Launch the respective frontend in the foreground |
84 | | -- Automatically handle cleanup when you exit |
85 | | - |
86 | | -#### Dashboard Options |
| 49 | +You can also launch the dashboard with some demo publishers to see everything in action: |
87 | 50 |
|
88 | 51 | ```bash |
89 | | -# Launch with demo publisher nodes |
90 | | -ros2 run greenwave_monitor r2s_gw_dashboard --demo |
91 | | -ros2 run greenwave_monitor ncurses_dashboard --demo |
92 | | - |
93 | | -# Enable logging to a directory |
94 | | -ros2 run greenwave_monitor r2s_gw_dashboard --log-dir /path/to/logs |
95 | | -ros2 run greenwave_monitor ncurses_dashboard --log-dir /path/to/logs |
| 52 | +ros2 run greenwave_monitor ncurses_dashboard -- --demo |
96 | 53 | ``` |
97 | 54 |
|
98 | | -### Manual Launch (ros2 topic hz mode) |
| 55 | +### r2s_gw Dashboard (Rich TUI) |
99 | 56 |
|
100 | | -If you want to use the tool as C++ based ros2 topic hz, you can do so with the following: |
| 57 | +First you need to build the r2s_gw package and some additional dependencies, r2s_gw is included in the greenwave_monitor package. |
101 | 58 |
|
102 | 59 | ```bash |
103 | | -ros2 launch greenwave_monitor hz.launch.py topics:='["/topic1", "/topic2"]' |
| 60 | +cd ros_ws/ |
| 61 | +colcon build --packages-up-to r2s_gw |
| 62 | +pip install -I textual # There is a requirements file in the r2s_gw package, but in case you installed from debian and that's not handy ... |
| 63 | +source install/setup.sh |
| 64 | +ros2 run greenwave_monitor r2s_gw_dashboard |
104 | 65 | ``` |
105 | 66 |
|
106 | | -## Services |
107 | | - |
108 | | -The Greenwave Monitor provides two services. The `ManageTopic` service dynamically adds or removes topics from monitoring. The `SetExpectedFrequency` service dynamically sets or clears expected frequencies for a specified topic, which enables additional diagnostic values and statuses. |
109 | | - |
110 | | -### Manage Topic |
111 | | - |
112 | | -The monitor node exposes a `/greenwave_monitor/manage_topic` service that follows the `greenwave_monitor_interfaces/srv/ManageTopic` service definition. |
113 | | - |
114 | | -**Usage Examples** |
| 67 | +Then you can launch the dashboard with the following. Use tab to navigate between different UI elements. |
115 | 68 |
|
116 | | -To add a topic to the monitoring list: |
117 | 69 | ```bash |
118 | | -ros2 service call /greenwave_monitor/manage_topic greenwave_monitor_interfaces/srv/ManageTopic "{topic_name: '/topic2', add_topic: true}" |
119 | | -``` |
120 | | - |
121 | | -To remove a topic from the monitoring list: |
122 | | -```bash |
123 | | -ros2 service call /greenwave_monitor/manage_topic greenwave_monitor_interfaces/srv/ManageTopic "{topic_name: '/topic2', add_topic: false}" |
| 70 | +ros2 run greenwave_monitor r2s_gw_dashboard |
124 | 71 | ``` |
125 | 72 |
|
126 | | -### Set Expected Frequency |
| 73 | +Just like before, you can also launch the dashboard with some demo publishers to see everything in action. |
127 | 74 |
|
128 | | -The monitor node exposes a `/greenwave_monitor/set_expected_frequency` service that follows the `greenwave_monitor_interfaces/srv/SetExpectedFrequency` service definition. |
129 | | - |
130 | | -**Usage Examples** |
131 | | - |
132 | | -To set the expected frequency for a topic: |
133 | | -```bash |
134 | | -ros2 service call /greenwave_monitor/set_expected_frequency greenwave_monitor_interfaces/srv/SetExpectedFrequency "{topic_name: '/topic2', expected_hz: <float>, tolerance_percent: <float>, add_topic_if_missing: true}" |
135 | | -``` |
136 | | - |
137 | | -To clear the expected frequency for a topic: |
138 | 75 | ```bash |
139 | | -ros2 service call /greenwave_monitor/set_expected_frequency greenwave_monitor_interfaces/srv/SetExpectedFrequency "{topic_name: '/topic2', clear_expected: true}" |
| 76 | +ros2 run greenwave_monitor r2s_gw_dashboard --demo |
140 | 77 | ``` |
141 | 78 |
|
142 | | -Note: The topic name must include the leading slash (e.g., '/topic2' not 'topic2'). |
| 79 | +### Manual Launch (ros2 topic hz mode) |
143 | 80 |
|
144 | | -## r2s_gw Dashboard |
| 81 | +You can of course also launch the node standalone, or incorporate it into your own launch files. |
| 82 | +If you want to use it as a command line tool, you can do so with the following launch file: |
145 | 83 |
|
146 | | -The r2s_gw dashboard displays real-time information about ROS 2 interfaces, nodes, and topics within your ROS environment. The dashboard can be navigated using key bindings or using a mouse. The full list of available key bindings for each tab can be found in the dashboard footer. |
| 84 | +```bash |
| 85 | +ros2 launch greenwave_monitor hz.launch.py topics:='["/topic1", "/topic2"]' |
| 86 | +``` |
0 commit comments