Update README (#4)

Update README to simplify things.
Add smoke checks to CI for the use cases outlined in the README.

Author: sgillen

.github/workflows/debian-packages.yml

@@ -145,7 +145,7 @@ jobs:
         # Run ncurses frontend with simulated terminal and quit command
         # Exit code 0 means clean exit (not 11 for SIGSEGV or 134 for SIGABRT)
         set +e
-        timeout 10s script -qfec 'python3 -m greenwave_monitor.ncurses_frontend' /dev/null <<< $'q'
+        timeout 10s script -qfec 'ros2 run greenwave_monitor ncurses_dashboard' /dev/null <<< $'q'
         EXIT_CODE=$?
         set -e
 
@@ -190,6 +190,7 @@ jobs:
       run: |
         source /opt/ros/${{ matrix.ros_distro }}/setup.bash
         timeout 10s bash -lc "script -qfec 'ros2 run r2s_gw r2s_gw' /dev/null <<< \$'q'" || true
+        timeout 10s bash -lc "script -qfec 'ros2 run greenwave_monitor r2s_gw_dashboard' /dev/null <<< \$'q'" || true
       shell: bash
 
     - name: Test greenwave_monitor execution

.github/workflows/ros-tests.yml

@@ -61,6 +61,16 @@ jobs:
         colcon build --packages-up-to r2s_gw
       shell: bash
 
+    - name: Smoke test README commands
+      run: |
+        source /opt/ros/${{ matrix.ros_distro }}/setup.bash
+        source install/setup.bash
+        set -e
+        timeout 10s bash -lc "script -qfec 'ros2 run greenwave_monitor ncurses_dashboard' /dev/null <<< \$'q'" || true
+        timeout 10s bash -lc "script -qfec 'ros2 run greenwave_monitor r2s_gw_dashboard' /dev/null <<< \$'q'" || true
+        timeout 5s ros2 launch greenwave_monitor hz.launch.py topics:='["/topic1"]' || true
+      shell: bash
+
     - name: Run tests
       run: |
         source /opt/ros/${{ matrix.ros_distro }}/setup.bash

README.md

@@ -1,146 +1,87 @@
 # Greenwave Monitor
+Greenwave monitor is a tool for runtime monitoring of ROS 2 topics.
 
-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.
+![Greenwave Monitor](docs/images/greenwave_r2s_dashboard.png)
 
-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).
+It provides the following features:
 
-Finally, we provide monitoring code as a standalone C++ header, which can be integrated into your own nodes.
+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.
 
-## Dashboard Interfaces
+2. A terminal based dashboard that displays the topic rates, latency, and status, and allows you to add/remove topics and set expected frequencies.
 
-The Greenwave Monitor provides two terminal-based dashboard options:
+3. A header only C++ library so you can calculate and publish compatible diagnostics directly from your own nodes for reduced overhead.
 
-### r2s_gw Dashboard (Rich TUI)
-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.
+This diagram shows an overview of the ![architecture](docs/images/greenwave_diagram.png)
 
-![r2s_gw + Greenwave Monitor Dashboard](docs/images/greenwave_r2s_dashboard.png)
+## Diagnostic messages
 
-### ncurses Dashboard (Lightweight)
-A lightweight ncurses-based interface focused specifically on topic monitoring with keyboard navigation. Features color-coded status indicators, interactive frequency management, and filtering options.
+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](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)).
 
-## Key Features
+## Compatibility
 
-- **High Performance**: Up to 10x more CPU efficient than the built-in `ros2 topic hz` command
-- **Multiple Dashboard Options**: Choose between rich TUI (r2s_gw) or lightweight ncurses interface
-- **Real-time Monitoring**: Live visualization of topic rates, latency, and status with color-coded indicators
-- **Interactive Management**: Add/remove topics and set expected frequencies directly from the interface
-- **Universal Compatibility**: Displays diagnostics from any source that publishes a compatible `/diagnostics` topic, including NVIDIA Nova sensors and other hardware drivers
+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
-TODO
 
+From source:
 ```bash
 cd ros_ws/src
-git clone https://gitlab-master.nvidia.com/sgillen/ros2_monitor_node.git
+git clone https://github.com/NVIDIA-ISAAC-ROS/greenwave_monitor.git
 cd ..
-colcon build --symlink-install --packages-up-to r2s_gw
-pip3 install -r requirements.txt --break-system-packages
-source install/setup.sh
+colcon build --packages-up-to greenwave_monitor
+source install/setup.bash
 ```
 
 ## Usage
 
-### Monitor Dashboards
+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.
 
-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.
+We have found that the r2s dashboard gets sluggish when there are many topics, so we recommend using the ncurses dashboard for large deployments.
 
-#### r2s_gw Dashboard (Rich TUI)
-
-```bash
-ros2 run greenwave_monitor r2s_gw_dashboard
-```
-
-Features:
-- Mouse and keyboard navigation
-- Tabbed interface (Topics, Nodes, Interfaces)
-- Rich text rendering and charts
-- Comprehensive ROS 2 system overview
+### ncurses Dashboard (Lightweight)
 
-#### ncurses Dashboard (Lightweight)
+After installing, you can launch the ncurses dashboard with:
 
 ```bash
 ros2 run greenwave_monitor ncurses_dashboard
 ```
 
-Features:
-- Keyboard-only navigation (↑/↓ arrows, Enter, etc.)
-- Real-time topic monitoring with color-coded status
-- Interactive frequency management (`f` to set, `c` to clear)
-- Topic filtering (`h` to hide unmonitored topics)
-- Minimal resource usage
-
-##### ncurses Dashboard Controls
-
-- **↑/↓ arrows**: Navigate topics
-- **Enter/Space**: Toggle monitoring for selected topic
-- **f**: Set expected frequency for selected topic
-- **c**: Clear expected frequency for selected topic
-- **h**: Toggle between showing all topics vs monitored only
-- **q**: Quit
-
-Both commands:
-- Start the greenwave monitor node in the background
-- Launch the respective frontend in the foreground
-- Automatically handle cleanup when you exit
-
-#### Dashboard Options
+You can also launch the dashboard with some demo publishers to see everything in action:
 
 ```bash
-# Launch with demo publisher nodes
-ros2 run greenwave_monitor r2s_gw_dashboard --demo
 ros2 run greenwave_monitor ncurses_dashboard --demo
-
-# Enable logging to a directory
-ros2 run greenwave_monitor r2s_gw_dashboard --log-dir /path/to/logs
-ros2 run greenwave_monitor ncurses_dashboard --log-dir /path/to/logs
 ```
 
-### Manual Launch (ros2 topic hz mode)
+### r2s_gw Dashboard (Rich TUI)
 
-If you want to use the tool as C++ based ros2 topic hz, you can do so with the following:
+First you need to build the r2s_gw package and some additional dependencies, r2s_gw is included in the greenwave_monitor package.
 
 ```bash
-ros2 launch greenwave_monitor hz.launch.py topics:='["/topic1", "/topic2"]'
+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
 ```
 
-## Services
+Then you can launch the dashboard with the following. Use tab to navigate between different UI elements.
 
-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.
-
-### Manage Topic
-
-The monitor node exposes a `/greenwave_monitor/manage_topic` service that follows the `greenwave_monitor_interfaces/srv/ManageTopic` service definition.
-
-**Usage Examples**
-
-To add a topic to the monitoring list:
 ```bash
-ros2 service call /greenwave_monitor/manage_topic greenwave_monitor_interfaces/srv/ManageTopic "{topic_name: '/topic2', add_topic: true}"
-```
-
-To remove a topic from the monitoring list:
-```bash
-ros2 service call /greenwave_monitor/manage_topic greenwave_monitor_interfaces/srv/ManageTopic "{topic_name: '/topic2', add_topic: false}"
+ros2 run greenwave_monitor r2s_gw_dashboard
 ```
 
-### Set Expected Frequency
+Just like before, you can also launch the dashboard with some demo publishers to see everything in action.
 
-The monitor node exposes a `/greenwave_monitor/set_expected_frequency` service that follows the `greenwave_monitor_interfaces/srv/SetExpectedFrequency` service definition.
-
-**Usage Examples**
-
-To set the expected frequency for a topic:
-```bash
-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}"
-```
-
-To clear the expected frequency for a topic:
 ```bash
-ros2 service call /greenwave_monitor/set_expected_frequency greenwave_monitor_interfaces/srv/SetExpectedFrequency "{topic_name: '/topic2', clear_expected: true}"
+ros2 run greenwave_monitor r2s_gw_dashboard -- --demo
 ```
 
-Note: The topic name must include the leading slash (e.g., '/topic2' not 'topic2').
+### Manual Launch (ros2 topic hz mode)
 
-## r2s_gw Dashboard
+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:
 
-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.
+```bash
+ros2 launch greenwave_monitor hz.launch.py topics:='["/topic1", "/topic2"]'
+```

docs/images/SERVICES.md

@@ -0,0 +1,37 @@
+# Services
+
+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.
+
+## Manage Topic
+
+The monitor node exposes a `/greenwave_monitor/manage_topic` service that follows the `greenwave_monitor_interfaces/srv/ManageTopic` service definition.
+
+**Usage Examples**
+
+To add a topic to the monitoring list:
+```bash
+ros2 service call /greenwave_monitor/manage_topic greenwave_monitor_interfaces/srv/ManageTopic "{topic_name: '/topic2', add_topic: true}"
+```
+
+To remove a topic from the monitoring list:
+```bash
+ros2 service call /greenwave_monitor/manage_topic greenwave_monitor_interfaces/srv/ManageTopic "{topic_name: '/topic2', add_topic: false}"
+```
+
+## Set Expected Frequency
+
+The monitor node exposes a `/greenwave_monitor/set_expected_frequency` service that follows the `greenwave_monitor_interfaces/srv/SetExpectedFrequency` service definition.
+
+**Usage Examples**
+
+To set the expected frequency for a topic:
+```bash
+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}"
+```
+
+To clear the expected frequency for a topic:
+```bash
+ros2 service call /greenwave_monitor/set_expected_frequency greenwave_monitor_interfaces/srv/SetExpectedFrequency "{topic_name: '/topic2', clear_expected: true}"
+```
+
+Note: The topic name must include the leading slash (e.g., '/topic2' not 'topic2').