IB-Robot故障排查指南常见问题与解决方案大全【免费下载链接】IB_RobotSave the code of IB-Robot, an AI robot execution framework developed by openEuler Embedded for embodied intelligence scenarios. It includes references to the forked version of tensormsg, references to lerobot fork, code references to the lerobot_ros2:ros2_ws branch, as well as some code related to development usability.项目地址: https://gitcode.com/openeuler/IB_Robot前往项目官网免费下载https://ar.openeuler.org/ar/IB-Robot作为融合LeRobot机器学习生态与ROS 2的智能具身机器人开发框架在实际使用中可能会遇到各种技术问题。本指南将为您提供全面的故障排查方案帮助您快速定位并解决IB-Robot开发中的常见问题。无论您是初学者还是资深开发者这份指南都能帮助您快速恢复项目正常运行。 环境与构建类问题1. 环境初始化失败问题现象执行source .shrc_local时出现 No such file or directory 错误。解决方案# 确保在项目根目录执行 cd /path/to/IB_Robot ./scripts/setup.sh关键检查点确认当前目录是IB_Robot项目根目录确保scripts/setup.sh脚本有执行权限检查ROS 2 Humble是否已正确安装2. 模块导入错误问题现象出现ModuleNotFoundError: No module named lerobot或类似导入错误。解决方案# 正确方式在同一shell调用中完成环境设置 source .shrc_local python3 -c import lerobot; print(导入成功)错误示范# 错误分开调用会导致环境变量丢失 source .shrc_local python3 -c import lerobot # 这里会失败3. 编译错误问题现象执行./scripts/build.sh时出现各种编译错误。解决方案步骤清理构建目录source .shrc_local rm -rf build install log完整重新构建source .shrc_local ./scripts/build.sh --clean构建特定包source .shrc_local colcon build --symlink-install --merge-install --packages-select robot_config常见编译错误及修复install directory was created with the layout merged添加--merge-install参数No module named colcon检查PYTHONNOUSERSITE1环境变量设置C编译错误确保已安装所有系统依赖 ROS 2运行时问题4. ROS_DOMAIN_ID配置错误问题现象控制器无法启动、节点无法发现彼此、话题和服务不可见。解决方案# 必须设置唯一的ROS_DOMAIN_ID source .shrc_local export ROS_DOMAIN_ID42 ros2 launch robot_config robot.launch.py重要规则所有参与通信的机器必须使用相同的ROS_DOMAIN_ID每次新开终端都需要重新设置默认使用ROS_DOMAIN_ID42避免冲突5. 共享内存错误问题现象出现RTPS_TRANSPORT_SHM Error相关错误。解决方案# 清理共享内存缓存 sudo rm -rf /dev/shm/fastrtps_* sudo rm -rf /dev/shm/ros2_humble_* sudo rm -rf /dev/shm/ros_humble_* # 设置本地主机模式 export ROS_LOCALHOST_ONLY16. 控制器残留问题问题现象控制器无法启动或端口被占用。解决方案使用清理脚本./scripts/cleanup_ros.sh这个脚本会优雅停止所有ROS 2进程强制终止残留进程清理共享内存可选清理ROS日志 机器人控制问题7. 仿真窗口无法显示问题现象启动仿真后没有出现Gazebo/MuJoCo可视化窗口。解决方案# 检查DISPLAY环境变量 echo $DISPLAY # 手动设置DISPLAY通常在:0或:1 export DISPLAY:1 # 对于远程连接可能需要设置 export LIBGL_ALWAYS_INDIRECT18. MoveIt规划失败问题现象MoveIt无法规划路径或出现碰撞检测错误。排查步骤检查URDF配置# 验证机器人描述文件 ros2 launch robot_description display.launch.py检查关节限制# 查看关节状态 ros2 topic echo /joint_states验证碰撞矩阵# 检查SRDF配置 cat src/robot_description/config/so101_single_arm.srdf9. 推理服务启动失败问题现象inference_service无法启动或无法加载模型。解决方案# 检查模型路径 ros2 param list /inference_service # 验证模型文件存在 ls -la /path/to/model.pt # 检查依赖项 source .shrc_local python3 -c import torch; import lerobot; print(依赖正常)常见模型问题模型路径错误检查policy_path参数PyTorch版本不兼容确保使用正确的torch版本内存不足检查GPU/系统内存使用情况 板端部署问题10. BQ3588HM板端连接问题问题现象无法通过HDC连接开发板。排查流程检查驱动安装# 验证USB连接 lsusb | grep -i rockchip配置HDC环境# 设置HDC路径 export PATHsdk-root/toolchains:$PATH hdc list targetsTCP模式连接# 切换到TCP调试模式 hdc tmode port 8710 hdc tconn board-ip:871011. OpenHarmony板端Python问题问题现象出现ImportError: symbol not found或类似动态链接错误。解决方案# 设置LD_PRELOAD解决Python符号可见性问题 export LD_PRELOAD/sys_prod/robot/out/lib/libpython3.12.so.1.0 # 重命名RKNN库文件 cp /vendor/lib64/librknnrt-gnu.so /usr/lib/librknnrt-ohos.so12. RKNN NPU推理问题问题现象NPU推理失败或性能异常。排查步骤验证NPU驱动# 检查NPU设备 ls /dev/rknpu*检查模型转换# 验证RKNN模型格式 python3 scripts/rknn_verify.py --model model.rknn性能调优# 设置NPU核心数 export RKNN_NPU_CORE_NUM3 分布式部署问题13. 分布式推理通信失败问题现象Ubuntu主机与板端无法通信推理结果无法传递。解决方案# 验证网络连接 ping board-ip # 检查ROS 2发现 source .shrc_local export ROS_DOMAIN_ID42 ros2 node list source .shrc_local export ROS_DOMAIN_ID42 ros2 topic list关键检查点确认两端使用相同的ROS_DOMAIN_ID检查防火墙设置验证网络带宽和延迟14. 图像话题不可见问题现象Ubuntu侧RViz显示No image但板端日志显示正常。排查步骤# 1. 检查话题发布 ros2 topic echo /camera/top/image_raw --once # 2. 验证图像编码 ros2 topic info /camera/top/image_raw # 3. 检查RMW实现 export RMW_IMPLEMENTATIONrmw_cyclonedds_cpp 数据采集与训练问题15. 数据集录制失败问题现象record_cli无法启动或录制数据损坏。解决方案# 检查录制服务状态 ros2 service list | grep record # 验证存储空间 df -h /path/to/rosbag # 检查权限 ls -la ~/.ros/16. 数据格式转换错误问题现象bag_to_lerobot转换失败。排查步骤# 验证输入数据 ros2 bag info episode.bag # 检查配置文件 python3 -m dataset_tools.validate_config --config robot_config.yaml # 查看转换日志 ros2 run dataset_tools bag_to_lerobot --bags-dir ./episodes --verbose️ 系统级问题17. 内存泄漏检测问题现象系统运行一段时间后内存占用持续增加。监控工具# 实时监控内存使用 top -p $(pgrep -f ros2\|python3) # 检查Python内存 python3 -m memory_profiler your_script.py # 清理ROS缓存 rm -rf ~/.ros/log/*18. 性能优化建议优化配置# robot_config配置优化 robot_config: performance: inference_fps: 30 control_hz: 100 image_compress: true topic_qos: best_effort 调试技巧与工具19. 日志分析技巧关键日志位置ROS日志~/.ros/log/latest/应用日志log/目录系统日志journalctl -u ros2日志级别调整# 设置详细日志 export RCUTILS_CONSOLE_OUTPUT_FORMAT[{severity}] [{time}] [{name}]: {message} export RCUTILS_LOGGING_SEVERITYDEBUG20. 可视化调试工具推荐工具RQTROS图形化工具套件PlotJuggler数据可视化Rerun3D场景可视化rqt_graph节点关系图 快速问题排查表问题类别症状首要检查点解决方案环境问题ModuleNotFoundErrorPYTHONPATH设置source .shrc_local 通信问题节点无法发现ROS_DOMAIN_ID设置唯一ID并重启控制问题控制器失败共享内存运行清理脚本仿真问题无显示窗口DISPLAY变量设置正确的DISPLAY板端问题HDC连接失败USB驱动重新安装驱动推理问题模型加载失败模型路径验证路径和权限数据问题录制失败存储空间检查磁盘空间性能问题系统卡顿内存使用监控并优化配置 预防性维护建议定期维护任务每周清理# 清理构建缓存 rm -rf build/ install/ log/ # 清理ROS日志 rm -rf ~/.ros/log/* # 清理共享内存 sudo rm -rf /dev/shm/ros*环境验证# 验证完整环境链 ./scripts/setup.sh --skip-verify source .shrc_local python3 -c import lerobot, torch, rclpy; print(环境正常)系统更新# 更新子模块 git submodule update --init --recursive # 更新Python依赖 pip install -r requirements/base.txt --upgrade备份策略重要配置文件备份src/robot_config/config/- 机器人配置models/- 训练好的模型scripts/- 自定义脚本.shrc_local- 环境配置 紧急恢复步骤当遇到无法解决的严重问题时按以下步骤恢复停止所有进程./scripts/cleanup_ros.sh pkill -9 -f ros2\|gz\|ign重置环境# 回到项目根目录 cd /path/to/IB_Robot # 重新设置环境 source .shrc_local export ROS_DOMAIN_ID42最小化测试# 测试基础功能 ros2 launch robot_config robot.launch.py \ robot_config:so101_single_arm \ use_sim:true \ with_inference:false逐步添加功能先验证仿真再添加推理最后测试分布式 资源与支持官方文档架构文档 - 系统架构详解BQ3588HM使用指南 - 板端部署指南OpenHarmony ROS集成 - 鸿蒙系统集成社区支持查看项目 README 中的FAQ部分参考各模块的独立文档使用AI Agent技能库中的故障排查技能调试技能IB-Robot内置了专门的故障排查AI技能可通过以下方式调用ibrobot-build- 构建相关问题ibrobot-env- 环境配置问题ibrobot-launch- 启动运行问题 最佳实践总结始终从项目根目录操作环境变量必须在同一shell中设置ROS_DOMAIN_ID是通信的关键定期清理避免残留问题使用提供的脚本而不是手动操作板端部署前充分测试仿真环境保持子模块和依赖项更新重要修改前备份配置文件通过本指南您应该能够解决IB-Robot开发中遇到的大部分常见问题。如果问题仍然存在建议按照紧急恢复步骤重新开始并逐步添加功能以定位问题根源。记住耐心和系统性的排查是解决复杂机器人系统问题的关键。祝您在IB-Robot开发中取得成功【免费下载链接】IB_RobotSave the code of IB-Robot, an AI robot execution framework developed by openEuler Embedded for embodied intelligence scenarios. It includes references to the forked version of tensormsg, references to lerobot fork, code references to the lerobot_ros2:ros2_ws branch, as well as some code related to development usability.项目地址: https://gitcode.com/openeuler/IB_Robot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考