Troubleshooting Guide

Common issues and their solutions when working with xTerra robots.

Connection Issues

Cannot Connect to Robot via SSH

Symptoms: Connection timeout or "Connection refused" error

Solutions:

  1. Verify robot is powered on (check LED status)
  2. Check network connectivity: ping 192.168.1.100
  3. Ensure you're on the same network as the robot
  4. Verify firewall settings aren't blocking SSH (port 22)
  5. Try resetting the robot's network interface

ROS2 Topics Not Visible

# Check ROS_DOMAIN_ID matches robot
echo $ROS_DOMAIN_ID  # Should be 42 (or your configured value)
export ROS_DOMAIN_ID=42

# Verify ROS2 daemon is running
ros2 daemon status
ros2 daemon stop
ros2 daemon start

# List topics
ros2 topic list

# Check network multicast
ros2 multicast receive
ros2 multicast send

Movement Issues

Robot Not Responding to Commands

Check these items:

  • Battery level (minimum 20% required)
  • Emergency stop not engaged
  • Robot is in correct mode (walk/stand)
  • Commands are being published: ros2 topic echo /cmd_vel
  • Controller node is running: ros2 node list

Erratic or Unstable Movement

Possible causes:

  • IMU calibration needed
  • Loose leg joints
  • Uneven surface
  • Low battery (below 30%)
  • High payload exceeding specifications

Solution:

# Recalibrate IMU
ros2 service call /calibrate_imu std_srvs/srv/Trigger

# Check joint status
ros2 topic echo /diagnostics

Sensor Issues

Camera Not Publishing Images

# Check camera node status
ros2 node list | grep camera

# Restart camera node
ros2 lifecycle set /camera configure
ros2 lifecycle set /camera activate

# Verify camera device
ls /dev/video*

# Check camera permissions
sudo usermod -aG video $USER

IMU Data Appears Incorrect

# View raw IMU data
ros2 topic echo /imu/data_raw

# Recalibrate (robot must be stationary)
ros2 run imu_calibration calibrate_imu

# Check for magnetic interference
# Move robot away from metal objects or motors

Software Issues

Build Errors

# Clean workspace
cd ~/xterra_ws
rm -rf build/ install/ log/

# Update dependencies
rosdep update
rosdep install --from-paths src --ignore-src -r -y

# Rebuild
colcon build --symlink-install

# If issues persist, check for conflicting packages
colcon list --packages-above-and-dependencies <package_name>

Runtime Errors

# Enable debug logging
ros2 run <package> <executable> --ros-args --log-level debug

# Check system resources
top
free -h
df -h

# View system logs
journalctl -u xterra-robot -f

Hardware Issues

Battery Won't Charge

  1. Check charger LED indicator (should be red while charging)
  2. Verify charger voltage output (19V nominal)
  3. Ensure battery connector is fully inserted
  4. Try a different power outlet
  5. If battery is deeply discharged, charging may take 30+ minutes to show activity
  6. Contact support if battery doesn't charge after 2 hours

Overheating

Warning signs: Hot to touch, thermal warning LED, automatic shutdown

Actions:

  • Power off and allow to cool for 30 minutes
  • Check for blocked air vents
  • Reduce continuous operation time
  • Operate in cooler environment (below 35°C)
  • Reduce payload if operating at high duty cycle

Performance Issues

High Latency

# Check network latency
ping 192.168.1.100

# Monitor topic rates
ros2 topic hz /cmd_vel
ros2 topic hz /camera/color/image_raw

# Check CPU usage on robot
ssh xterra@192.168.1.100 'top -b -n 1'

# Reduce camera resolution if needed
ros2 param set /camera image_width 640
ros2 param set /camera image_height 480

Getting Help

If you can't resolve the issue:

  • Check the FAQ for common questions
  • Search the community forums
  • Contact technical support with:
    • Robot serial number
    • Software version: ros2 pkg list | grep xterra
    • Error messages and logs
    • Steps to reproduce the issue
← Best Practices