Quick Start Guide#

Complete the installation before proceeding.

Easiest Way — Interactive Launcher#

The quickstart script provides a guided menu that handles ROS2 environment setup automatically:

Jazzy

cd /opt/ros/jazzy/benchmarking
./quickstart

Humble

cd /opt/ros/humble/benchmarking
./quickstart

The menu guides you through:

Monitoring your ROS2 application
Running Wandering, Pick-n-Place, and FastMapping simulations with rosbag recording
Offline bag-replay benchmarking
Analyzing rosbag results
Quick health checks
Starting Grafana dashboards

The ./quickstart script is the recommended entry point.

Common Tasks#

Monitor All Nodes#

Jazzy

source /opt/ros/jazzy/setup.bash
export ROS_DOMAIN_ID=0

Humble

source /opt/ros/humble/setup.bash
export ROS_DOMAIN_ID=0

# Quick 30-second check
uv run src/monitor_stack.py --duration 30

# Full 60-second session
uv run src/monitor_stack.py --duration 60

# Extended session (5 minutes)
uv run src/monitor_stack.py --duration 300

Monitor a Specific Node#

uv run src/monitor_stack.py --node /slam_toolbox --session my_session --duration 120

Remote Monitoring#

# Basic remote session
uv run src/monitor_stack.py --remote-ip 192.168.1.100

# With specific node and user
uv run src/monitor_stack.py --remote-ip 192.168.1.100 --remote-user ubuntu --node /slam_toolbox

Note: Allow 30–60 seconds for DDS discovery to complete before topic data starts flowing on remote sessions. Use --duration ≥ 90s for remote monitoring.

Results#

All output is saved in monitoring_sessions/ under a timestamped folder. When --algorithm is used, sessions are grouped by label:

monitoring_sessions/
└── <algorithm>/                  # optional: set by --algorithm
    └── 20260306_154140/
        ├── session_info.txt      # Test configuration
        ├── graph_timing.csv      # Topic timing data
        ├── resource_usage.log    # CPU/memory usage
        ├── gpu_usage.log         # GPU metrics (if --gpu)
        ├── npu_usage.log         # NPU metrics (if --npu)
        ├── kpi.json              # KPI summary
        └── visualizations/       # Auto-generated PNG plots
            ├── timing_delays.png
            ├── message_frequencies.png
            ├── cpu_usage_timeline.png
            └── cpu_heatmap.png

Useful session commands:

uv run src/monitor_stack.py --list-sessions   # List all previous sessions
uv run src/visualize_timing.py <session>/graph_timing.csv --show   # Re-visualize
uv run src/analyze_trigger_latency.py         # Analyze trigger latency

Advanced Usage#

Benchmarking#

# Single run with recording and plots (default)
bash src/wandering_run.sh

# Single run + auto-open HTML report in browser
bash src/wandering_run.sh --show

# Run Wandering benchmark (5 runs, 180s each)
make wandering-benchmark RUNS=5 TIMEOUT=180

# Run Pick-n-Place benchmark (5 runs)
make picknplace-benchmark RUNS=5

Grafana Dashboard#

make grafana-start              # Start Grafana + Prometheus
make grafana-export SESSION=20260306_154140   # Export session metrics
make grafana-open               # Open http://localhost:30000
make grafana-stop               # Stop the stack

See Grafana Dashboard for the full setup guide.

Troubleshooting#

Problem	Fix
ROS2 not found	Source your ROS2 environment — see Set Up ROS2
No nodes detected	Ensure your ROS2 application is running first
`permission denied` on scripts	`chmod +x quickstart auto-setup.sh`
`uv` not found	`curl -LsSf https://astral.sh/uv/install.sh \|sh && source ~/.bashrc`
Remote: no data	Verify SSH key auth and matching `ROS_DOMAIN_ID` on both machines

For auto-setup of the ROS2 environment:

source ./auto-setup.sh