Basic Usage Examples

This chapter provides practical examples of using the roc tool for common ROS 2 introspection tasks.

Prerequisites

Before running these examples, ensure:

ROS 2 is installed and sourced
At least one ROS 2 node is running (e.g., ros2 run demo_nodes_cpp talker)
The roc tool is built and available in your PATH

Getting Started

1. List All Topics

The most basic operation is listing all available topics in the ROS 2 graph:

roc topic list

Expected output:

/chatter
/parameter_events
/rosout

2. Get Basic Topic Information

To get basic information about a specific topic:

roc topic info /chatter

Output:

Topic: /chatter
Type: std_msgs/msg/String
Publishers: 1
Subscribers: 0

3. Get Detailed Topic Information

For comprehensive topic details including QoS profiles and endpoint information:

roc topic info /chatter --verbose

Expected verbose output:

Topic: /chatter
Type: std_msgs/msg/String
Publishers: 1
  Node: /talker
  Endpoint type: Publisher
  GID: 01.0f.xx.xx.xx.xx.xx.xx.xx.xx.xx.xx.xx.xx.xx.xx
  QoS Profile:
    Reliability: Reliable
    Durability: Volatile
    History: Keep last
    Depth: 10
    Deadline: Default
    Lifespan: Default
    Liveliness: Automatic
    Liveliness lease duration: Default
  Type hash: RIHS01_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Subscribers: 0

Common Use Cases

Debugging Communication Issues

When nodes aren't communicating properly, use verbose topic info to check QoS compatibility:

# Check publisher QoS
roc topic info /my_topic --verbose

# Compare with subscriber expectations
# Look for QoS mismatches in reliability, durability, etc.

Monitoring System Health

Check critical system topics:

# Monitor rosout for system messages
roc topic info /rosout --verbose

# Check parameter events
roc topic info /parameter_events --verbose

Network Diagnostics

Use GID information to identify nodes across the network:

# Get detailed endpoint information
roc topic info /my_topic --verbose | grep "GID"

Working with Multiple Topics

Batch Information Gathering

# Get info for all topics
for topic in $(roc topic list); do
    echo "=== $topic ==="
    roc topic info "$topic"
    echo
done

Filtering by Node

# Find topics published by a specific node
roc topic info /chatter --verbose | grep "Node:"

Integration with ROS 2 Tools

The roc tool complements existing ROS 2 CLI tools:

# Compare outputs
ros2 topic info /chatter --verbose
roc topic info /chatter --verbose

# Use roc for faster queries
time roc topic list
time ros2 topic list

Troubleshooting

No Topics Found

If roc topic list returns empty:

Check if ROS 2 nodes are running:
```
ros2 node list
```

Verify ROS 2 environment:

echo $ROS_DOMAIN_ID
printenv | grep ROS

Test with a simple publisher:
```
ros2 run demo_nodes_cpp talker
```

Permission Issues

If you encounter permission errors:

# Check RMW implementation
echo $RMW_IMPLEMENTATION

# Try with different RMW
export RMW_IMPLEMENTATION=rmw_cyclone_cpp
roc topic list

Performance Considerations

For systems with many topics:

# Use targeted queries instead of listing all topics
roc topic info /specific_topic --verbose

Next Steps

See Advanced Usage for complex scenarios
Check Command Reference for all available options
Read Integration Examples for using roc in scripts and automation

Keyboard shortcuts

roc - ROS 2 CLI Tool