# ROS2Top
A real-time monitor for ROS2 nodes showing CPU, RAM, and GPU usage - like `htop` but for ROS2 nodes.
<!-- ![ROS2Top Demo]() -->
## Features
- 🔍 **Real-time monitoring** of all ROS2 nodes
- 💻 **CPU usage** tracking per node
- 🧠 **RAM usage** monitoring
- 🎮 **GPU usage** tracking (NVIDIA GPUs via NVML)
- 🖥️ **Terminal-based interface** using curses
- 🔄 **Auto-refresh** with configurable intervals
- 🏷️ **Process tree awareness** (includes child processes)
- 📝 **Node registration API** for reliable node-to-monitor communication
## Installation
### From PyPI (when published)
```bash
pip install ros2top
```
### From Source
```bash
git clone https://github.com/AhmedARadwan/ros2top.git
cd ros2top
pip install -e .
```
## Requirements
- Python 3.8+
- NVIDIA drivers (for GPU monitoring)
### Python Dependencies
- `psutil>=5.8.0`
- `pynvml>=11.0.0`
### CPP Dependencies
- [nlohmann json](https://github.com/nlohmann/json) installed from source.
## Usage
### Examples
- **[Python Example](examples/python/README.md)**: Complete ROS2 Python node with ros2top integration
- **[C++ Example](examples/cpp/README.md)**: Complete ROS2 C++ package with ros2top integration
### Basic Usage
```bash
# Run ros2top
ros2top
```
### Command Line Options
```bash
ros2top --help # Show help
ros2top --refresh 2 # Refresh every 2 seconds (default: 5)
ros2top --version # Show version
```
### Interactive Controls
The enhanced terminal UI provides responsive and interactive controls:
| Key | Action |
| ---------- | ----------------------------- |
| `q` or `Q` | Quit application |
| `h` or `H` | Show help dialog |
| `r` or `R` | Force refresh node list |
| `p` or `P` | Pause/resume monitoring |
| `+` or `=` | Increase refresh rate |
| `-` | Decrease refresh rate |
| `↑` / `↓` | Navigate through nodes |
| `Tab` | Cycle focus between UI panels |
| `Space` | Force immediate update |
| `Home/End` | Jump to first/last node |
## Terminal UI
### Visual Features
- **Color-coded usage bars**: Green (low), Yellow (medium), Red (high)
- **Real-time progress bars** for CPU, memory, and GPU
- **Interactive navigation** with keyboard shortcuts
- **Adaptive refresh rates** for optimal performance
### System Overview Panel
The top panel shows real-time system information:
- CPU usage (per-core or summary based on terminal size)
- Memory usage with progress bar
- GPU utilization and memory (if available)
- ROS2 status and active node count
## Display Columns
| Column | Description |
| ----------- | ----------------------------------------------- |
| **Node** | ROS2 node name |
| **PID** | Process ID |
| **%CPU** | CPU usage percentage (normalized by core count) |
| **RAM(MB)** | RAM usage in megabytes |
| **GPU#** | GPU device number (if using GPU) |
| **GPU%** | GPU utilization percentage |
| **GMEM** | GPU memory usage in MB |
## Examples
### Monitor nodes with 2-second refresh
```bash
ros2top --refresh 2
```
## How It Works
1. **Node Registartion**: Every node registers its name and PID at startup with ros2top.
2. **Resource Monitoring**: Uses `psutil` for CPU/RAM and `pynvml` for GPU metrics.
3. **Display**: Curses-based terminal interface for real-time updates.
## Troubleshooting
### No GPU monitoring
- Install NVIDIA drivers
- Install pynvml: `pip install pynvml`
### Nodes not showing up
- Verify nodes are running: `ros2 node list`
- Check node info: `ros2 node info /your_node`
- Some nodes might not have detectable PIDs
## Development
### Setup Development Environment
```bash
git clone https://github.com/AhmedARadwan/ros2top.git
cd ros2top
pip install -e .
```
### Running Tests
```bash
python -m pytest tests/
```
### Code Style
```bash
black ros2top/
flake8 ros2top/
mypy ros2top/
```
## Architecture
```text
ros2top/
├── ros2top/ # Python package
│ ├── __init__.py # Package initialization and public API
│ ├── main.py # CLI entry point
│ ├── node_monitor.py # Core monitoring logic
│ ├── node_registry.py # Node registration system
│ ├── gpu_monitor.py # GPU monitoring
│ ├── ros2_utils.py # ROS2 utilities
│ └── ui/ # User interface components
│ ├── __init__.py
│ ├── terminal_ui.py # Main curses interface
│ ├── components.py # UI components
│ └── layout.py # UI layout management
├── include/ # C++ headers
│ └── ros2top/
│ └── ros2top.hpp # C++ API for node registration
├── examples/ # Example integrations
│ ├── python/ # Python examples
│ │ ├── README.md
│ │ └── example_node.py
│ └── cpp/ # C++ examples
│ ├── README.md
│ └── example_monitored_node/ # Complete ROS2 package
├── tests/ # Test suite
│ ├── __init__.py
│ └── test_ros2top.py
├── cmake/ # CMake configuration
├── pyproject.toml # Python build configuration
├── requirements.txt # Python dependencies
├── LICENSE # MIT license
└── README.md # This file
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Changelog
### v0.1.3
- Remove dependency on ROS2 to start ros2top.
### v0.1.2
- Enhance README
### v0.1.1
- Add example usage
- Enhance README
### v0.1.0
- Initial release
- Basic node monitoring with CPU, RAM, GPU usage
- Terminal interface with curses
- Command line options
- Node registration and process mapping
## Similar Tools
- `htop` - System process monitor
- `nvtop` - GPU process monitor
- `ros2 node list` - Basic ROS2 node listing
## Acknowledgments
- Inspired by `htop` and `nvtop`
- Built for the ROS2 community
- Uses `psutil` for system monitoring and `pynvml` for GPU monitoring
## Node Registration API
For the most reliable monitoring, ROS2 nodes can register themselves with `ros2top`. This is especially useful for:
- Multiple nodes running in the same Python process
- Complex applications where automatic detection might miss some nodes
- Getting additional metadata about nodes
### Basic Registration
```python
import ros2top
# Register your node (call this once when your node starts)
ros2top.register_node('/my_node_name')
# Send periodic heartbeats (optional, but recommended)
ros2top.heartbeat('/my_node_name')
# Unregister when shutting down (optional, automatic cleanup on process exit)
ros2top.unregister_node('/my_node_name')
```
### Advanced Registration with Metadata
```python
import ros2top
# Register with additional information
ros2top.register_node('/camera_processor', {
'description': 'Processes camera feed for object detection',
'type': 'vision_processor',
'input_topics': ['/camera/image_raw'],
'output_topics': ['/detected_objects'],
'framerate': 30
})
# In your main loop, send heartbeats every few seconds
ros2top.heartbeat('/camera_processor')
```
## Node Detection
`ros2top` uses a **node registration system** for reliable node detection:
### Primary Method: Node Registration API
The most reliable way is for ROS2 nodes to explicitly register themselves:
```python
import ros2top
# Register your node
ros2top.register_node('/my_node', {'description': 'My awesome node'})
# Send periodic heartbeats (recommended)
ros2top.heartbeat('/my_node')
# Unregister when shutting down (optional - automatic cleanup on exit)
ros2top.unregister_node('/my_node')
```
### Automatic Cleanup
- Nodes are automatically unregistered when the process exits
- Stale registrations are cleaned up periodically
- Registry is stored in `~/.ros2top/registry/`
### Benefits of Registration API
- **Reliable**: No dependency on tracing or process matching
- **Fast**: Instant node detection without scanning
- **Accurate**: Direct PID mapping from the registering process
- **Simple**: Works with any ROS2 node type (Python, C++, etc.)
Raw data
{
"_id": null,
"home_page": null,
"name": "ros2top",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "monitoring, process, ros2, gpu, cpu, memory, nodes, system",
"author": null,
"author_email": "Ahmed Radwan <ahmed.ali.radwan94@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c5/c3/14ea42f82317f414a9b114787f9d2ef297d27a5374bb0354aaab3af05cdc/ros2top-0.1.3.tar.gz",
"platform": null,
"description": "# ROS2Top\n\nA real-time monitor for ROS2 nodes showing CPU, RAM, and GPU usage - like `htop` but for ROS2 nodes.\n\n<!-- ![ROS2Top Demo]() -->\n\n## Features\n\n- \ud83d\udd0d **Real-time monitoring** of all ROS2 nodes\n- \ud83d\udcbb **CPU usage** tracking per node\n- \ud83e\udde0 **RAM usage** monitoring\n- \ud83c\udfae **GPU usage** tracking (NVIDIA GPUs via NVML)\n- \ud83d\udda5\ufe0f **Terminal-based interface** using curses\n- \ud83d\udd04 **Auto-refresh** with configurable intervals\n- \ud83c\udff7\ufe0f **Process tree awareness** (includes child processes)\n- \ud83d\udcdd **Node registration API** for reliable node-to-monitor communication\n\n## Installation\n\n### From PyPI (when published)\n\n```bash\npip install ros2top\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/AhmedARadwan/ros2top.git\ncd ros2top\npip install -e .\n```\n\n## Requirements\n\n- Python 3.8+\n- NVIDIA drivers (for GPU monitoring)\n\n### Python Dependencies\n\n- `psutil>=5.8.0`\n- `pynvml>=11.0.0`\n\n### CPP Dependencies\n\n- [nlohmann json](https://github.com/nlohmann/json) installed from source.\n\n## Usage\n\n### Examples\n\n- **[Python Example](examples/python/README.md)**: Complete ROS2 Python node with ros2top integration\n- **[C++ Example](examples/cpp/README.md)**: Complete ROS2 C++ package with ros2top integration\n\n### Basic Usage\n\n```bash\n# Run ros2top\nros2top\n```\n\n### Command Line Options\n\n```bash\nros2top --help # Show help\nros2top --refresh 2 # Refresh every 2 seconds (default: 5)\nros2top --version # Show version\n```\n\n### Interactive Controls\n\nThe enhanced terminal UI provides responsive and interactive controls:\n\n| Key | Action |\n| ---------- | ----------------------------- |\n| `q` or `Q` | Quit application |\n| `h` or `H` | Show help dialog |\n| `r` or `R` | Force refresh node list |\n| `p` or `P` | Pause/resume monitoring |\n| `+` or `=` | Increase refresh rate |\n| `-` | Decrease refresh rate |\n| `\u2191` / `\u2193` | Navigate through nodes |\n| `Tab` | Cycle focus between UI panels |\n| `Space` | Force immediate update |\n| `Home/End` | Jump to first/last node |\n\n## Terminal UI\n\n### Visual Features\n\n- **Color-coded usage bars**: Green (low), Yellow (medium), Red (high)\n- **Real-time progress bars** for CPU, memory, and GPU\n- **Interactive navigation** with keyboard shortcuts\n- **Adaptive refresh rates** for optimal performance\n\n### System Overview Panel\n\nThe top panel shows real-time system information:\n\n- CPU usage (per-core or summary based on terminal size)\n- Memory usage with progress bar\n- GPU utilization and memory (if available)\n- ROS2 status and active node count\n\n## Display Columns\n\n| Column | Description |\n| ----------- | ----------------------------------------------- |\n| **Node** | ROS2 node name |\n| **PID** | Process ID |\n| **%CPU** | CPU usage percentage (normalized by core count) |\n| **RAM(MB)** | RAM usage in megabytes |\n| **GPU#** | GPU device number (if using GPU) |\n| **GPU%** | GPU utilization percentage |\n| **GMEM** | GPU memory usage in MB |\n\n## Examples\n\n### Monitor nodes with 2-second refresh\n\n```bash\nros2top --refresh 2\n```\n\n## How It Works\n\n1. **Node Registartion**: Every node registers its name and PID at startup with ros2top.\n2. **Resource Monitoring**: Uses `psutil` for CPU/RAM and `pynvml` for GPU metrics.\n3. **Display**: Curses-based terminal interface for real-time updates.\n\n## Troubleshooting\n\n### No GPU monitoring\n\n- Install NVIDIA drivers\n- Install pynvml: `pip install pynvml`\n\n### Nodes not showing up\n\n- Verify nodes are running: `ros2 node list`\n- Check node info: `ros2 node info /your_node`\n- Some nodes might not have detectable PIDs\n\n## Development\n\n### Setup Development Environment\n\n```bash\ngit clone https://github.com/AhmedARadwan/ros2top.git\ncd ros2top\npip install -e .\n```\n\n### Running Tests\n\n```bash\npython -m pytest tests/\n```\n\n### Code Style\n\n```bash\nblack ros2top/\nflake8 ros2top/\nmypy ros2top/\n```\n\n## Architecture\n\n```text\nros2top/\n\u251c\u2500\u2500 ros2top/ # Python package\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization and public API\n\u2502 \u251c\u2500\u2500 main.py # CLI entry point\n\u2502 \u251c\u2500\u2500 node_monitor.py # Core monitoring logic\n\u2502 \u251c\u2500\u2500 node_registry.py # Node registration system\n\u2502 \u251c\u2500\u2500 gpu_monitor.py # GPU monitoring\n\u2502 \u251c\u2500\u2500 ros2_utils.py # ROS2 utilities\n\u2502 \u2514\u2500\u2500 ui/ # User interface components\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 terminal_ui.py # Main curses interface\n\u2502 \u251c\u2500\u2500 components.py # UI components\n\u2502 \u2514\u2500\u2500 layout.py # UI layout management\n\u251c\u2500\u2500 include/ # C++ headers\n\u2502 \u2514\u2500\u2500 ros2top/\n\u2502 \u2514\u2500\u2500 ros2top.hpp # C++ API for node registration\n\u251c\u2500\u2500 examples/ # Example integrations\n\u2502 \u251c\u2500\u2500 python/ # Python examples\n\u2502 \u2502 \u251c\u2500\u2500 README.md\n\u2502 \u2502 \u2514\u2500\u2500 example_node.py\n\u2502 \u2514\u2500\u2500 cpp/ # C++ examples\n\u2502 \u251c\u2500\u2500 README.md\n\u2502 \u2514\u2500\u2500 example_monitored_node/ # Complete ROS2 package\n\u251c\u2500\u2500 tests/ # Test suite\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 test_ros2top.py\n\u251c\u2500\u2500 cmake/ # CMake configuration\n\u251c\u2500\u2500 pyproject.toml # Python build configuration\n\u251c\u2500\u2500 requirements.txt # Python dependencies\n\u251c\u2500\u2500 LICENSE # MIT license\n\u2514\u2500\u2500 README.md # This file\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Changelog\n\n### v0.1.3\n\n- Remove dependency on ROS2 to start ros2top.\n\n### v0.1.2\n\n- Enhance README\n\n### v0.1.1\n\n- Add example usage\n- Enhance README\n\n### v0.1.0\n\n- Initial release\n- Basic node monitoring with CPU, RAM, GPU usage\n- Terminal interface with curses\n- Command line options\n- Node registration and process mapping\n\n## Similar Tools\n\n- `htop` - System process monitor\n- `nvtop` - GPU process monitor\n- `ros2 node list` - Basic ROS2 node listing\n\n## Acknowledgments\n\n- Inspired by `htop` and `nvtop`\n- Built for the ROS2 community\n- Uses `psutil` for system monitoring and `pynvml` for GPU monitoring\n\n## Node Registration API\n\nFor the most reliable monitoring, ROS2 nodes can register themselves with `ros2top`. This is especially useful for:\n\n- Multiple nodes running in the same Python process\n- Complex applications where automatic detection might miss some nodes\n- Getting additional metadata about nodes\n\n### Basic Registration\n\n```python\nimport ros2top\n\n# Register your node (call this once when your node starts)\nros2top.register_node('/my_node_name')\n\n# Send periodic heartbeats (optional, but recommended)\nros2top.heartbeat('/my_node_name')\n\n# Unregister when shutting down (optional, automatic cleanup on process exit)\nros2top.unregister_node('/my_node_name')\n```\n\n### Advanced Registration with Metadata\n\n```python\nimport ros2top\n\n# Register with additional information\nros2top.register_node('/camera_processor', {\n 'description': 'Processes camera feed for object detection',\n 'type': 'vision_processor',\n 'input_topics': ['/camera/image_raw'],\n 'output_topics': ['/detected_objects'],\n 'framerate': 30\n})\n\n# In your main loop, send heartbeats every few seconds\nros2top.heartbeat('/camera_processor')\n```\n\n## Node Detection\n\n`ros2top` uses a **node registration system** for reliable node detection:\n\n### Primary Method: Node Registration API\n\nThe most reliable way is for ROS2 nodes to explicitly register themselves:\n\n```python\nimport ros2top\n\n# Register your node\nros2top.register_node('/my_node', {'description': 'My awesome node'})\n\n# Send periodic heartbeats (recommended)\nros2top.heartbeat('/my_node')\n\n# Unregister when shutting down (optional - automatic cleanup on exit)\nros2top.unregister_node('/my_node')\n```\n\n### Automatic Cleanup\n\n- Nodes are automatically unregistered when the process exits\n- Stale registrations are cleaned up periodically\n- Registry is stored in `~/.ros2top/registry/`\n\n### Benefits of Registration API\n\n- **Reliable**: No dependency on tracing or process matching\n- **Fast**: Instant node detection without scanning\n- **Accurate**: Direct PID mapping from the registering process\n- **Simple**: Works with any ROS2 node type (Python, C++, etc.)\n",
"bugtrack_url": null,
"license": null,
"summary": "A real-time process monitor with support for ROS2 nodes, showing CPU, RAM, and GPU usage",
"version": "0.1.3",
"project_urls": {
"Bug Reports": "https://github.com/AhmedARadwan/ros2top/issues",
"Homepage": "https://github.com/AhmedARadwan/ros2top",
"Source": "https://github.com/AhmedARadwan/ros2top"
},
"split_keywords": [
"monitoring",
" process",
" ros2",
" gpu",
" cpu",
" memory",
" nodes",
" system"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8f5e709aab609d45f1b7898bf265653bfee9e8a8af28fcef7d0c85cf4e044e3e",
"md5": "8445272d16e10467556eec769a404c58",
"sha256": "f02f1b0792864cf6fa0f1bbad853b275ef3798d06a1e5f0e8f6e6aebaf8d7fbc"
},
"downloads": -1,
"filename": "ros2top-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8445272d16e10467556eec769a404c58",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 32222,
"upload_time": "2025-07-13T17:15:38",
"upload_time_iso_8601": "2025-07-13T17:15:38.403245Z",
"url": "https://files.pythonhosted.org/packages/8f/5e/709aab609d45f1b7898bf265653bfee9e8a8af28fcef7d0c85cf4e044e3e/ros2top-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c5c314ea42f82317f414a9b114787f9d2ef297d27a5374bb0354aaab3af05cdc",
"md5": "b716782595bbbfdfac26c2016df08528",
"sha256": "ace65a8f145acaca4ea2dd0773c4bdf09fbe6a3918930cdd91e9c1ae8ec1166a"
},
"downloads": -1,
"filename": "ros2top-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "b716782595bbbfdfac26c2016df08528",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 34003,
"upload_time": "2025-07-13T17:15:40",
"upload_time_iso_8601": "2025-07-13T17:15:40.592442Z",
"url": "https://files.pythonhosted.org/packages/c5/c3/14ea42f82317f414a9b114787f9d2ef297d27a5374bb0354aaab3af05cdc/ros2top-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-13 17:15:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AhmedARadwan",
"github_project": "ros2top",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "psutil",
"specs": [
[
">=",
"5.8.0"
]
]
},
{
"name": "pynvml",
"specs": [
[
">=",
"11.0.0"
]
]
}
],
"lcname": "ros2top"
}
JSON
