Troubleshooting

Common Issues

1. Connection Failed

Error: RuntimeError: Failed to connect to robot

Diagnosis and Solutions:

• Check network connectivity: ping 172.16.0.20
• Verify ROS_DOMAIN_ID: echo $ROS_DOMAIN_ID
• Ensure the robot system is running
• Confirm the host IP is in the 172.16.0.x subnet

# Test network connectivity
ping 172.16.0.20

# Check ROS2 communication
ros2 topic list
ros2 node list

2. Camera Initialization Failed

Error: Camera-related errors

Solutions:

• Test camera connection: realsense-viewer
• Use test mode: no_camera=True
• Verify camera serial numbers
• Ensure USB 3.0 connection

# Test without camera
config = MOZ1RobotConfig(
    no_camera=True,
    structure="dualarm"
)

3. ROS2 Environment Issues

Error: ROS2 import errors

Solutions:

# Reset ROS2 environment
source /opt/ros/humble/setup.bash
export ROS_DOMAIN_ID=33

# Verify ROS2 installation
ros2 --version

4. Python Dependency Issues

Error: Module import errors

Solutions:

# Reinstall dependencies
pip install -r requirements.txt

# Test key dependencies
python3 -c "import torch, numpy, cv2, pyrealsense2, rclpy"

5. Unstable ROS2 Communication

Error: Robot jitter when executing actions due to unstable ROS2 communication caused by network issues.

Problem Identification:

1. ros2 topic hz /cart_states observes that the ROS2 efficiency frequency is unstable with abnormal fluctuations.

Solutions:

Note: The configuration file provided below assumes your IP address is 172.16.0.30. Please modify according to your actual situation.

Create a new fastdds configuration file /path/to/fastdds_config.xml:

<?xml version="1.0" encoding="UTF-8" ?>
<dds xmlns="http://www.eprosima.com">
    <profiles>
        <transport_descriptors>
            <transport_descriptor>
                <transport_id>udp_transport</transport_id>
                <type>UDPv4</type>
                <interfaceWhiteList>
                    <address>172.16.0.20</address>
                    <address>172.16.0.30</address>
                    <address>127.0.0.1</address>
                </interfaceWhiteList>
            </transport_descriptor>
        </transport_descriptors>

        <participant profile_name="UDPParticipant" is_default_profile="true">
            <rtps>
                <userTransports>
                    <transport_id>udp_transport</transport_id>
                </userTransports>
                <useBuiltinTransports>false</useBuiltinTransports>
            </rtps>
        </participant>
    </profiles>
</dds>

Execute before running the program each time:

export FASTRTPS_DEFAULT_PROFILES_FILE=/path/to/fastdds_config.xml

6. Python Interpreter and ROS2 Compatibility Issues

Error: Python module import errors, rclpy initialization failures or version conflicts

Problem Description: ROS2 has compatibility issues with Python virtual environments (such as conda, venv). Main reasons include:

• ROS2 binary files are bound to the system default Python version
• conda environments modify the default Python interpreter path
• Python package path conflicts prevent ROS2 modules like rclpy from being imported correctly

Solutions:

Solution 1: Use System Python (Recommended)

# Confirm using system Python
which python3
# Output should be: /usr/bin/python3

# Install Python dependencies to system environment
sudo apt install python3-pip
pip3 install --user [required package name]

# Avoid activating conda base environment
conda config --set auto_activate_base false

Solution 2: conda Environment Isolation Configuration

# Configure environment variable order correctly in ~/.bashrc
# Load ROS2 environment first, then initialize conda
source /opt/ros/humble/setup.bash
export ROS_DOMAIN_ID=33
# conda initialize block should be at the end

# Create dedicated conda environment (matching system Python version)
conda create -n ros2_mozrobot python=3.x  # 3.x is the system Python version
conda activate ros2_mozrobot

Best Practices:

1. Prioritize using system Python environment for ROS2 development to avoid complex compatibility issues
2. If conda must be used, ensure the Python version matches the system

Reference Resources:

• ROS2 Official Python Packages Guide