Troubleshooting Guidelines

Gazebo Specific Issues

colcon build fails

Problem: Build process exits with errors.

Solution:

1. Ensure you're not running colcon build inside a virtual environment

2. Deactivate any active environments (including conda)

3. Open a fresh terminal and retry the build

Gazebo and RViz fail to launch

Problem: Simulation environment doesn't start properly.

Solution:

• Verify CycloneDDS is configured correctly on your system

• Check that ROS 2 middleware is properly initialized

Robot stops moving unexpectedly

Problem: Robot is unresponsive to movement commands.

Solution:

• Manually reposition the robot in Gazebo using translate or rotate mode

• Alternatively, use RViz to send a 2D Nav Goal pose to the robot

Orchestrator throws errors

Problem: API communication or initialization fails.

Solution:

1. Verify environment variables are set in your ~/.bashrc:

   export OM_API_KEY=<your_key>
   export OM_API_KEY_ID=<your_key_id>

2. Confirm your virtual environment is active with Python 3.10:

   python --version
   which python

Problem: Packages not found.

Solution:

1. Confirm your virtual environment is active with Python 3.10:

   python --version
   which python

2. Confirm you installed the dependencies using uv pip install, during the setup. If you still face issues, try deleting and creating a new virtual environment. Make sure to export PYTHONPATH to correct location.

Audio Issues

Robot doesn't respond to voice commands

Problem: Audio input/output is not working.

Solution:

• Check system audio settings

• Verify the correct microphone is selected as input

• Verify the correct speaker is selected as output

• Test audio with a simple recording to confirm functionality