ROS2 Topic Monitor

A real-time command-line utility for monitoring ROS2 topic message rates with visual progress bars and counters.

Features

• Multi-topic monitoring: Monitor multiple ROS2 topics simultaneously
• Dynamic progress bars: Visual progress bars that scale automatically (10 → 100 → 1,000 → 10,000 → 100,000 messages)
• Real-time display: Live updates showing message counts and elapsed time
• Subscription status: Visual indicators showing which topics are successfully subscribed
• Final summary: Comprehensive report when exiting with Ctrl+C
• Robust initialization: Automatic retry mechanism for reliable topic discovery
• Type-agnostic: Works with any ROS2 message type automatically

Requirements

• ROS2 (tested with ROS2 Jazzy)
• Python 3.6+
• rclpy
• rosidl_runtime_py

Installation

1. Make sure you have ROS2 properly installed and sourced:

   source /opt/ros/jazzy/setup.bash  # or your ROS2 distribution

2. Download the script:

   wget https://your-repo/ros2_topic_monitor.py
   chmod +x ros2_topic_monitor.py

Usage

Basic Usage

Monitor a single topic:

python3 ros2_topic_monitor.py /topic_name

Monitor multiple topics:

python3 ros2_topic_monitor.py /topic1 /topic2 /topic3

Advanced Usage

Adjust initialization wait time (useful for slow networks or systems):

python3 ros2_topic_monitor.py /topic_name --wait 5.0

Short form:

python3 ros2_topic_monitor.py /topic_name -w 3.0

Examples

Monitor camera and robot control topics:

python3 ros2_topic_monitor.py /camera/image_raw /cmd_vel /odom

Monitor with extended initialization time:

python3 ros2_topic_monitor.py /sensor/imu /camera/compressed --wait 4.0

Display Format

The monitor shows a real-time display with the following information:

Measurement start: 14:30:15
Elapsed time: 0:02:45
--------------------------------------------------------------------------------
Active subscriptions: 3/3
--------------------------------------------------------------------------------
✓ /camera/image_raw                      [████████████████████████████████] 1000    1256
✓ /robot/cmd_vel                         [████████░░░░░░░░░░░░░░░░░░░░░░░░░░] 100      45
✓ /sensor/imu                            [██████████████████░░░░░░░░░░░░░░░░] 1000     892
--------------------------------------------------------------------------------
Press CTRL+C to exit

Display Elements

• ✓/✗ Indicators: Shows subscription status for each topic
• Topic Name: The ROS2 topic being monitored
• Progress Bar: Visual representation of message count within current scale
• Scale Number: Current maximum scale (10, 100, 1000, 10000, or 100000)
• Message Count: Total number of messages received for that topic

Progress Bar Scaling

The progress bars automatically scale based on message count:

• 1-10 messages: Bar represents progress from 1 to 10
• 11-100 messages: Bar represents progress from 1 to 100
• 101-1,000 messages: Bar represents progress from 1 to 1,000
• 1,001-10,000 messages: Bar represents progress from 1 to 10,000
• 10,001-100,000 messages: Bar represents progress from 1 to 100,000

Exit and Summary

Press Ctrl+C to stop monitoring. The tool will display a clean summary:

============================================================
MONITORING SUMMARY
============================================================
/camera/image_raw                           1256 messages
/robot/cmd_vel                                45 messages
/sensor/imu                                  892 messages
------------------------------------------------------------
Total messages received: 2193
Total monitoring time: 0:03:42
============================================================

Command Line Options

Option	Short	Description	Default
topics	-	One or more ROS2 topic names to monitor	Required
--wait	-w	Wait time for ROS2 initialization (seconds)	2.0
--help	-h	Show help message and exit	-

Troubleshooting

No messages appearing

If topics don't show messages on first launch:

1. Increase wait time: Use --wait 5.0 to allow more time for ROS2 initialization
2. Check topic names: Verify topics exist with ros2 topic list
3. Verify publishers: Ensure publishers are active with ros2 topic hz /topic_name
4. Check QoS compatibility: Some topics may have specific QoS requirements

Topics not found

• Ensure ROS2 environment is properly sourced
• Verify topic names are correct (case-sensitive)
• Check if publishers are running: ros2 topic info /topic_name

Permission issues

Make sure the script has execution permissions:

chmod +x ros2_topic_monitor.py

Technical Details

• QoS Policy: Uses BEST_EFFORT reliability for maximum compatibility
• Update Rate: Display refreshes at 10 Hz for smooth real-time monitoring
• Memory Efficient: Stores only message counts, not message data
• Thread Safe: Uses separate threads for message reception and display updates
• Signal Handling: Graceful shutdown with Ctrl+C

License

MIT License

Copyright (c) 2025 Group of Electronic Technology and Communications. University of A Coruna.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE