Command Reference

This chapter provides a comprehensive reference for all roc tool commands, options, and usage patterns.

Global Options

All roc commands support these global options:

Environment Variables

The roc tool respects standard ROS 2 environment variables:

Command Structure

roc <COMMAND> [SUBCOMMAND] [OPTIONS] [ARGS]

Topic Commands

roc topic list

List all available topics in the ROS 2 graph.

Syntax:

roc topic list

Output:

/chatter
/parameter_events
/rosout

Exit Codes:

• 0: Success
• 1: Error (no ROS 2 system found, permission issues, etc.)

Examples:

# Basic usage
roc topic list

# Count topics
roc topic list | wc -l

# Filter topics
roc topic list | grep "chatter"

# Store topics in variable
topics=$(roc topic list)

roc topic info

Display detailed information about a specific topic.

Syntax:

roc topic info <TOPIC_NAME> [OPTIONS]

Arguments:

• <TOPIC_NAME>: The name of the topic to inspect (required)

Options:

Basic Output:

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

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

Exit Codes:

• 0: Success
• 1: Topic not found or error accessing topic information
• 2: Invalid arguments

Examples:

# Basic topic information
roc topic info /chatter

# Detailed information with QoS profiles
roc topic info /chatter --verbose
roc topic info /chatter -v

# Check if topic exists (using exit code)
if roc topic info /my_topic > /dev/null 2>&1; then
    echo "Topic exists"
else
    echo "Topic not found"
fi

# Get only publisher count
roc topic info /chatter | grep "Publishers:" | awk '{print $2}'

Output Format Details

Topic Information Fields

Verbose Information Fields

Publisher/Subscriber Details

QoS Profile Fields

Error Handling

Common Error Messages

Debugging Commands

# Check ROS 2 environment
printenv | grep ROS

# Verify RMW implementation
echo $RMW_IMPLEMENTATION

# Test basic connectivity
roc topic list

# Verbose debugging (if available)
RUST_LOG=debug roc topic info /chatter --verbose

Return Codes

All roc commands follow standard Unix conventions:

Performance Considerations

Command Performance

Optimization Tips

1. Batch Operations: Use roc topic list once, then query specific topics
2. Caching: Results are cached briefly to improve repeated queries
3. Network: Use ROS_LOCALHOST_ONLY=1 for local-only discovery
4. RMW Selection: Different RMW implementations have different performance characteristics

Comparison with ROS 2 CLI

Feature Parity

Performance Comparison

# Benchmark both tools
time ros2 topic list
time roc topic list

time ros2 topic info /chatter --verbose
time roc topic info /chatter --verbose

Typical results show roc is 2-3x faster for most operations.

Scripting and Automation

Common Patterns

# Check if specific topics exist
check_topics() {
    local required_topics=("$@")
    local missing_topics=()
    
    for topic in "${required_topics[@]}"; do
        if ! roc topic info "$topic" > /dev/null 2>&1; then
            missing_topics+=("$topic")
        fi
    done
    
    if [ ${#missing_topics[@]} -eq 0 ]; then
        echo "All required topics found"
        return 0
    else
        echo "Missing topics: ${missing_topics[*]}"
        return 1
    fi
}

# Usage
check_topics "/chatter" "/rosout" "/parameter_events"

# Get topic statistics
get_topic_stats() {
    local topics=($(roc topic list))
    local total_pubs=0
    local total_subs=0
    
    for topic in "${topics[@]}"; do
        local info=$(roc topic info "$topic")
        local pubs=$(echo "$info" | grep "Publishers:" | awk '{print $2}')
        local subs=$(echo "$info" | grep "Subscribers:" | awk '{print $2}')
        
        total_pubs=$((total_pubs + pubs))
        total_subs=$((total_subs + subs))
    done
    
    echo "Topics: ${#topics[@]}"
    echo "Total publishers: $total_pubs"
    echo "Total subscribers: $total_subs"
}

JSON Output (Future Enhancement)

While not currently supported, JSON output could be added:

# Proposed syntax (not yet implemented)
roc topic list --format json
roc topic info /chatter --format json --verbose

IDL Commands

roc idl protobuf

Bidirectional conversion between Protobuf (.proto) and ROS 2 (.msg) files with automatic direction detection.

Syntax:

roc idl protobuf [OPTIONS] <INPUT_FILES>...

Arguments:

• <INPUT_FILES>...: Input files to convert (.proto or .msg files)

Options:

Examples:

# Convert .proto files to .msg files (automatic detection)
roc idl protobuf robot.proto sensor_data.proto

# Convert .msg files to .proto files (automatic detection)  
roc idl protobuf RobotStatus.msg SensorData.msg

# Specify output directory
roc idl protobuf --output ./generated robot.proto

# Dry run to preview conversion
roc idl protobuf --dry-run --verbose robot.proto

# Convert with include directories for imports
roc idl protobuf -I ./proto_deps -I ./common robot.proto

# Convert with custom package name
roc idl protobuf --package my_robot_msgs robot.proto

Protobuf to ROS2 (.proto → .msg):

# Input: robot.proto
roc idl protobuf robot.proto

# Output: Robot.msg, RobotStatus.msg (based on message definitions)

ROS2 to Protobuf (.msg → .proto):

# Input: RobotStatus.msg
roc idl protobuf RobotStatus.msg  

# Output: robot_status.proto

Advanced Usage:

# Convert entire directory with verbose output
roc idl protobuf --verbose src/proto/*.proto --output msg/

# Mixed conversion with error handling
roc idl protobuf file1.proto file2.proto || echo "Conversion failed"

# Pipeline with other tools
find . -name "*.proto" -exec roc idl protobuf {} --output ./ros_msgs \;

Supported Protobuf Features:

• Proto3 syntax
• Nested messages (automatically flattened)
• Enums (converted to constants)
• Repeated fields (arrays)
• Maps (converted to key-value arrays)
• Oneof fields (converted to separate optional fields)
• Comments (preserved when possible)
• Import statements and dependencies

Type Mappings:

Exit Codes:

• 0: Success
• 1: Error (invalid syntax, file not found, permission issues, etc.)

Error Examples:

# Mixed file types (not allowed)
roc idl protobuf robot.proto RobotStatus.msg
# Error: Cannot mix .proto and .msg files in the same conversion

# Unsupported file extension
roc idl protobuf data.json
# Error: Unsupported file extension: .json

# File not found
roc idl protobuf nonexistent.proto
# Error: Input file does not exist: nonexistent.proto

Troubleshooting

Common Issues

1. No output from roc topic list

   • Check if ROS 2 nodes are running: ros2 node list
   • Verify ROS 2 environment: echo $ROS_DOMAIN_ID
   • Try different RMW: export RMW_IMPLEMENTATION=rmw_cyclone_cpp

2. Permission errors

   • Check user groups: groups
   • Verify ROS 2 installation permissions
   • Try running with different user

3. Slow performance

   • Check network configuration
   • Use ROS_LOCALHOST_ONLY=1 for local testing
   • Consider different RMW implementation

4. Inconsistent results

   • Allow time for discovery: sleep 2 && roc topic list
   • Check for multiple ROS 2 domains
   • Verify system clock synchronization

Debug Information

# Enable detailed logging (if built with debug support)
RUST_LOG=debug roc topic list

# Check system resources
free -h
df -h

# Network diagnostics
netstat -tuln | grep -E "(7400|7401|7411)"

This completes the comprehensive command reference for the roc tool.