factor out r2s

Author: sgillen

.github/workflows/ros-tests.yml

@@ -74,22 +74,11 @@ jobs:
       env:
         DEBIAN_FRONTEND: noninteractive
 
-    - name: Install Python dependencies
-      run: |
-        if [[ "${{ matrix.ros_distro }}" == "jazzy" || \
-              "${{ matrix.ros_distro }}" == "kilted" || \
-              "${{ matrix.ros_distro }}" == "rolling" ]]; then
-          pip3 install --break-system-packages -I pygments textual
-        else
-          pip3 install textual
-        fi
-      shell: bash
-
     - name: Build packages
       run: |
         source /opt/ros/${{ matrix.ros_distro }}/setup.bash
         echo "Building and testing on ROS2 ${{ matrix.ros_distro }}"
-        colcon build --packages-up-to r2s_gw
+        colcon build --packages-up-to greenwave_monitor
       shell: bash
 
     - name: Smoke test README commands
@@ -98,14 +87,13 @@ jobs:
         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
-        colcon test --event-handlers console_direct+ --return-code-on-test-failure --packages-up-to r2s_gw
+        colcon test --event-handlers console_direct+ --return-code-on-test-failure --packages-up-to greenwave_monitor
       shell: bash
 
     - name: Upload test results

CLAUDE.md

@@ -0,0 +1,138 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+Greenwave Monitor is a ROS 2 diagnostic tool for runtime monitoring of topic frame rates and latency. The project consists of two packages:
+
+1. **greenwave_monitor** - Core C++ monitoring node, ncurses dashboard frontend, and header-only library
+2. **greenwave_monitor_interfaces** - ROS service definitions (ManageTopic, SetExpectedFrequency)
+
+## Build Commands
+
+```bash
+# Build all packages
+cd <ros_workspace>
+colcon build --packages-up-to greenwave_monitor
+
+# Build individual packages
+colcon build --packages-select greenwave_monitor
+colcon build --packages-select greenwave_monitor_interfaces
+```
+
+## Testing
+
+```bash
+# Run all tests for greenwave_monitor
+colcon test --packages-select greenwave_monitor
+colcon test-result --verbose
+
+# Run specific test types
+colcon test --packages-select greenwave_monitor --pytest-args -k test_greenwave_monitor
+colcon test --packages-select greenwave_monitor --pytest-args -k test_topic_monitoring_integration
+
+# C++ unit tests (gtest) are run automatically with colcon test
+# - test_message_diagnostics.cpp - Tests MessageDiagnostics header-only library
+# - test_minimal_publisher.cpp - Tests example publisher node
+
+# Python linting tests
+colcon test --packages-select greenwave_monitor --pytest-args -k test_flake8
+colcon test --packages-select greenwave_monitor --pytest-args -k test_pep257
+colcon test --packages-select greenwave_monitor --pytest-args -k test_copyright
+```
+
+## Architecture
+
+### Core Components
+
+**GreenwaveMonitor Node** (`greenwave_monitor.cpp`):
+- Subscribes to topics using generic subscriptions (rclcpp::GenericSubscription)
+- Extracts timestamps from serialized messages for latency calculation
+- Uses MessageDiagnostics to track frame rates and latency per topic
+- Publishes diagnostics to `/diagnostics` topic (diagnostic_msgs/DiagnosticArray)
+- Exposes services at `~/manage_topic` and `~/set_expected_frequency`
+- Timer callback (1Hz) triggers diagnostics publishing for all monitored topics
+
+**MessageDiagnostics Library** (`message_diagnostics.hpp`):
+- Header-only C++ library for calculating and publishing diagnostics
+- Tracks frame rate using both node clock and message timestamps
+- Uses rolling window filtering (default 300 messages) for smoothing
+- Calculates jitter, dropped frames, and latency metrics
+- Can be integrated directly into custom nodes to avoid subscription overhead
+- Thread-safe with mutex protection for updateDiagnostics() and publishDiagnostics()
+
+**UI Adaptor**:
+- `ncurses_frontend.py` - Lightweight terminal dashboard
+- Subscribes to `/diagnostics` topic and calls services to manage monitoring
+- `ui_adaptor.py` provides GreenwaveUiAdaptor class for building custom UIs
+
+Third-party UIs (like r2s_gw, available as a separate package) can integrate by subscribing to the `/diagnostics` topic and using the ManageTopic and SetExpectedFrequency services.
+
+### Diagnostics Message Format
+
+Greenwave follows Isaac ROS NITROS diagnostic conventions with these KeyValue fields:
+- `frame_rate_node` - Hz calculated from node clock
+- `frame_rate_msg` - Hz calculated from message timestamps
+- `current_delay_from_realtime_ms` - Latency (or "N/A" if unavailable)
+- `num_jitter_outliers_node/msg` - Count of deadline misses
+- `max_abs_jitter_node/msg` - Maximum jitter observed (µs)
+- `mean_abs_jitter_node/msg` - Average jitter (µs)
+- `total_dropped_frames` - Total frames dropped
+
+This format allows NITROS-enabled nodes to be monitored without greenwave_monitor subscribing (when `ENABLE_GLOBAL_NITROS_DIAGNOSTICS=1` is set).
+
+### Latency Calculation
+
+Latency is computed as: `current_time - message.header.stamp`
+
+**Important constraints:**
+- Message type must have a `std_msgs/Header` field
+- Message type must be registered in `known_header_types` map in greenwave_monitor.cpp:has_header_from_type()
+- Header timestamp must use epoch time (not boottime)
+
+If conditions aren't met, latency shows as "N/A". Commonly supported types include sensor_msgs/Image, sensor_msgs/CameraInfo, etc.
+
+**To add support for new message types:**
+1. Edit `greenwave_monitor.cpp::has_header_from_type()`
+2. Add entry to `known_header_types` map with type name and header offset
+3. Example: `{"sensor_msgs/msg/Image", {0, true}}`
+
+## Service API
+
+**ManageTopic.srv** - Add/remove topics from monitoring:
+```
+string topic_name
+bool add_topic  # true=add, false=remove
+---
+bool success
+string message
+```
+
+**SetExpectedFrequency.srv** - Configure expected rate and tolerances:
+```
+string topic_name
+float64 expected_hz
+float64 tolerance_percent  # e.g., 5.0 = 5%
+bool clear_expected        # reset to no expectation
+bool add_topic_if_missing  # auto-add topic if not monitored
+---
+bool success
+string message
+```
+
+## Contributing
+
+All commits must be signed off using `git commit -s` to certify the Developer Certificate of Origin (DCO). This indicates you have rights to submit the contribution under the Apache 2.0 license.
+
+CI automatically runs on PRs. For local testing across ROS distributions, use:
+```bash
+scripts/docker-test.sh
+```
+
+## Code Style
+
+- C++17 standard (enforced in CMakeLists.txt)
+- Python code must pass flake8, pep257, and copyright tests
+- Use ament_lint_auto for automatic style checking
+- Copyright header required: Apache 2.0 license with NVIDIA CORPORATION & AFFILIATES

README.md

@@ -53,11 +53,9 @@ source install/setup.bash
 
 ## Usage
 
-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.
+Greenwave monitor provides a lightweight ncurses dashboard for monitoring topics. An optional rich TUI (r2s integration) with additional features is also available as a separate 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)
+### ncurses Dashboard
 
 After installing, you can launch the ncurses dashboard with:
 
@@ -71,27 +69,36 @@ You can also launch the dashboard with some demo publishers to see everything in
 ros2 run greenwave_monitor ncurses_dashboard --demo
 ```
 
-### r2s_gw Dashboard (Rich TUI)
+### Rich TUI (r2s integration) - Optional
+
+For users who want a more feature-rich terminal interface, **r2s_gw** is available as a separate package. This is a fork of [r2s](https://github.com/mjcarroll/r2s) designed to integrate with Greenwave Monitor.
+
+**Note:** The r2s integration requires additional dependencies (specifically the `textual` Python package) and can slow down when monitoring many topics. For large deployments or minimal dependencies, we recommend using the ncurses dashboard above.
 
-First you need to build the r2s_gw package and some additional dependencies, r2s_gw is included in the greenwave_monitor package.
+To use r2s_gw:
 
+1. Clone the r2s_gw repository into your workspace:
 ```bash
-cd ros_ws/
+cd ros_ws/src
+git clone https://github.com/NVIDIA-ISAAC-ROS/r2s_gw.git
+cd ../..
+```
+
+2. Install dependencies and build:
+```bash
+pip install textual
 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.
-
+3. Launch the dashboard (use tab to navigate between UI elements):
 ```bash
-ros2 run greenwave_monitor r2s_gw_dashboard
+ros2 run r2s_gw r2s_gw_dashboard
 ```
 
-Just like before, you can also launch the dashboard with some demo publishers to see everything in action.
-
+4. Or launch with demo publishers:
 ```bash
-ros2 run greenwave_monitor r2s_gw_dashboard -- --demo
+ros2 run r2s_gw r2s_gw_dashboard -- --demo
 ```
 
 ### Manual Launch (ros2 topic hz mode)

greenwave_monitor/CMakeLists.txt

@@ -67,7 +67,6 @@ install(
 # Install Python scripts
 install(
   PROGRAMS
-    scripts/r2s_gw_dashboard
     scripts/ncurses_dashboard
   DESTINATION lib/${PROJECT_NAME}
 )

greenwave_monitor/package.xml

@@ -50,8 +50,6 @@
   <test_depend>launch_testing</test_depend>
   <test_depend>launch_testing_ros</test_depend>
 
-  <!-- TODO add textual as dependency (need to host rosdep)-->
-
   <build_depend>rosidl_default_generators</build_depend>
   <exec_depend>rosidl_default_runtime</exec_depend>
   <member_of_group>rosidl_interface_packages</member_of_group>