A1Pro Robot Common Problem Troubleshooting Guide

1. Bottom Hardware and Serial Communication Problems

Q1.1: Startup driver reports cannot find serial port (like /dev/myserial or /dev/ttyUSB0)

• Phenomenon: Terminal error could not open port /dev/myserial: [Errno 2] No such file or directory.

• Reasons:

  1. Type-C/Micro-USB data cable is loose or has poor contact;

  2. Bottom control board is not powered on;

  3. udev serial alias rules have not taken effect.

• Troubleshooting and resolution:

  1. Check control board power switch and car battery voltage;

  2. Run ls /dev/ttyUSB* or ls /dev/ttyACM*, see if the system recognizes the bottom serial port device;

  3. If device is recognized but no /dev/myserial alias, rebind udev rules or temporarily specify serial port as actual device name in launch/parameters (such as /dev/ttyUSB0).

Q1.2: Driver reports insufficient serial port permissions (Permission denied)

• Phenomenon: [Errno 13] Permission denied: '/dev/...'.

• Solution: Grant read-write permissions to the serial port, or add current user to dialout group:

  sudo chmod 777 /dev/ttyUSB* /dev/myserial*
  # Or permanently add to group (need to logout and re-login to take effect):
  sudo usermod -aG dialout $USER
  

Q1.3: After publishing control command, chassis does not move / reports feedback unavailable

• Phenomenon: Car has no action, driver terminal prints Rejected motion: feedback unavailable or stop pending.

• Reasons:

  1. Battery undervoltage protection (chassis communication board will refuse to drive motor when voltage is too low);

  2. Chassis is in emergency stop or stop suspend state;

  3. Publishing angular velocity when linear velocity is 0 (Ackerman car does not support in-place rotation, angular velocity is invalid at zero linear velocity).

• Solution:

  1. Check battery level, plug in adapter to charge;

  2. Ensure published cmd_vel has non-zero linear.x; can print topic via ROS: ros2 topic echo /cmd_vel;

  3. Try restarting the driver node to reset status.

Q1.4: Car drifts left/right when driving straight

• Reason: There is tiny deviation in the physical mechanical center of the Ackerman front wheel servo.

• Solution: Refer to "4.A1Pro Front Wheel Servo Calibration" tutorial for center calibration.

2. Robotic Arm Control and Servo Problems (Including Robotic Arm Grasping Precautions)

Q2.1: Robotic arm droops weakly / cannot rotate via topic

• Reason: Servo is in powered-off released state (Torque OFF).

• Solution: Call service to restore servo power-on and lock:

  xxxxxxxxxx
  ros2 service call /arm_driver/set_torque std_srvs/srv/SetBool "{data: true}"
  

Q2.2: Gripper overheats or makes buzzing stall sound (emergency handling)

• Danger warning: Servo long-term stall can easily overheat or even burn out the internal motor!

• Solution and emergency handling:

  1. When stall or abnormal sound occurs, immediately run the following command to release servo torque:

     xxxxxxxxxx
     ros2 service call /arm_driver/set_torque std_srvs/srv/SetBool "{data: false}"
     

  2. When grasping items, must set gripper angle based on actual item size, never blindly send 180° closing angle.

Q2.3: Robotic Arm Grasping Item Precautions and Gripper Angle Reference Table

We have compiled a gripper angle corresponding table, recording the approximate servo angle values needed when grasping every 0.5 cm size of object. Please reasonably adjust the target angle in the grasping code according to this table:

Grasping Example Description:

• For example, the matching 3cm cube with length, width, and height all 3cm, set the servo angle to 134° in the program to firmly grasp, never set exceeding this value, otherwise it will cause motor stall.

If stall occurs during grasping larger blocks, you can also modify the grasping angle at the following path:

xxxxxxxxxx
~\yahboomcar_ros2_ws\dofbo_pro_ws\src\dofbot_pro_bringup\config\common.yaml

If stall occurs during grasping, decrease the angle (such as 140 or others); if the grip is not tight enough, you can increase it. After modification, compile to take effect:

xxxxxxxxxx
cd ~/yahboomcar_ros2_ws\dofbo_pro_ws
colcon build --packages-select dofbot_pro_bringup

3. LiDAR and Camera Vision Problems

Q3.1: Depth camera (HP60C) has no image or node crashes

• Reasons:

  1. Camera USB interface bandwidth is limited or is plugged into USB 2.0 port;

  2. Environment variable CAMERA_TYPE is not correctly specified;

  3. Another program is occupying the camera.

• Solution:

  1. Ensure it is plugged into USB 3.0 (blue) interface;

  2. Check environment variable:

     xxxxxxxxxx
     echo $CAMERA_TYPE
     # If using depth camera, ensure it is not forced to specify as usb:
     unset CAMERA_TYPE
     

  3. Confirm camera device node exists with ls /dev/video*.

Q3.2: LiDAR does not rotate or no point cloud data (/scan topic has no message)

• Binding port: /dev/rplidar

• Reasons:

  1. Radar wiring is loose, power supply insufficient;

  2. Radar serial port /dev/rplidar has insufficient permissions or device not recognized;

  3. Multiple nodes simultaneously grabbing radar serial port.

• Solution:

  1. Check if serial device exists: ls -l /dev/rplidar, if not, check wiring or rebind udev rules;

  2. Check serial port permissions: sudo chmod 777 /dev/rplidar;

  3. Execute ros2 topic hz /scan to check if there is point cloud data frame rate;

  4. Check for residual radar nodes in background: ps aux | grep lidar, kill extra processes and restart.

4. ROS 2 Communication and Environment Configuration Problems

Q4.1: Terminal command execution reports Package '...' not found

• Reason: New terminal has not loaded ROS 2 and workspace environment variables.

• Solution: Run in each new terminal (or write to ~/.bashrc):

  xxxxxxxxxx
  source /opt/ros/humble/setup.bash
  source ~/yahboomcar_ros2_ws/yahboomcar_ws/install/setup.bash
  source ~/yahboomcar_ros2_ws/dofbot_pro_ws/install/setup.bash
  

Q4.2: PC cannot receive/display car's topics (cross-machine communication failure)

• Troubleshooting steps:

  1. Check same LAN: Car and PC must be connected to the same router/WiFi, try ping each other's IP addresses;

  2. Check Domain ID: ROS_DOMAIN_ID on both machines must be exactly the same:

     xxxxxxxxxx
     echo $ROS_DOMAIN_ID
     # If inconsistent, set both to the same value (such as 20):
     export ROS_DOMAIN_ID=20
     

  3. Firewall: Turn off PC system firewall or allow ROS 2 DDS UDP ports.

Q4.3: Starting node reports error Address already in use or serial port already occupied

• Reason: Previous driver node was Ctrl+C in foreground, but background still has sub-threads or zombie processes that did not exit.

• Solution: Directly clean up residual processes before starting:

  xxxxxxxxxx
  pkill -f ros
  

5. Dify & OpenClaw Large Model and Voice Interaction Troubleshooting

Q5.1: Voice interaction module cannot find device / cannot wake up (binding port: /dev/myspeech)

• Binding port: /dev/myspeech

• Phenomenon: Starting llm_agent_control.launch.py reports error cannot open serial port or not detected recording device.

• Troubleshooting and solution:

  1. Check if serial is recognized: ls -l /dev/myspeech, if does not exist, unplug and replug voice module to reconnect;

  2. Check serial port permissions: sudo chmod 777 /dev/myspeech;

  3. Wake-up test: Speaker should be about 0.5 meters from the car, clearly say wake-up word "Hi, yahboomm", after hearing "I'm here" then give control commands.

Q5.2: Microphone recording is overly sensitive (VAD fails to truncate) or insensitive (premature truncation)

• Reason: Microphone input gain is too large or too small, ambient noise floor affects VAD (Voice Activity Detection).

• Solution:

  • Open system audio settings, appropriately lower or raise the microphone input volume slider;

  • Avoid voice control in high-noise environment.

Q5.3: Dify local large model no response / connection timeout

• Troubleshooting steps:

  1. Confirm if Dify is started: Enter in host terminal sh ~/bringup_dify.sh to start;

  2. Check Docker container running status: docker ps, confirm dify-related containers are all in Up running state;

  3. Check network connection and API Key configuration are valid.

Q5.4: OpenClaw agent service exception / dialogue no reply

• Troubleshooting commands:

  1. Check gateway running status: openclaw gateway status;

  2. Restart gateway service: openclaw gateway restart;

  3. Check model access status: openclaw models status; if prompted unauthorized or key expired, execute openclaw configure to reconfigure API Key;

  4. View enabled skills: openclaw skills list.

Q5.5: Dify, too many incorrect password attempts, need to wait 24 hours before trying correct password again to login to Dify

Q5.6: If OpenClaw or Dify voice synthesis reports the error shown below, it is because the official has taken the model offline. You can solve this by changing the voice synthesis model.

Go to this path to modify the voice synthesis model and voice,

xxxxxxxxxx
~\yahboomcar_ros2_ws\dofbo_pro_ws\src\dofbot_pro_bringup\config\common.yaml

Scroll to the end, find the highlighted area and modify according to the reference.

After modification, compile to take effect,

xxxxxxxxxx
cd ~/yahboomcar_ros2_ws\dofbo_pro_ws
colcon build --packages-select dofbot_pro_bringup

Q5.7: If Dify shows voice module busy, check if there is a background process occupying the sound card

xxxxxxxxxx
pgrep -af common_service

If you see residual processes, use the command kill -9 pid to delete them. PID is the corresponding process number.

6. High-Frequency Troubleshooting "Three Board Axe" Quick Reference Commands