在Ubuntu 20.04上从零搭建宇树Z1机械臂仿真环境（ROS Noetic + Gazebo）保姆级避坑指南

在Ubuntu 20.04上从零搭建宇树Z1机械臂仿真环境（ROS Noetic + Gazebo）保姆级避坑指南

宇树Z1作为一款轻量级协作机械臂，其ROS仿真环境的搭建是开发者进行算法验证和功能测试的关键第一步。本文将手把手带你完成从裸机到完整仿真环境的配置过程，重点解决那些官方文档未提及的"坑点"——包括依赖冲突、编译报错、环境变量配置等典型问题。无论你是刚接触ROS的开发者，还是需要快速搭建Z1测试环境的工程师，都能通过本文避开90%的常见错误。

1. 基础环境准备

在开始之前，请确保你的Ubuntu 20.04系统已经完成基础配置。建议使用全新的系统环境，避免已有ROS安装导致的版本冲突。首先更新软件源并升级现有包：

sudo apt update && sudo apt upgrade -y

接下来安装ROS Noetic完整版。这里有个细节需要注意：官方推荐使用ros-noetic-desktop-full，但实际开发中建议额外安装ros-noetic-moveit和ros-noetic-gazebo-ros-control：

sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list' sudo apt-key adv --keyserver 'hkp://keyserver.ubuntu.com:80' --recv-key C1CF6E31E6BADE8868B172B4F42ED6FBAB17C654 sudo apt update sudo apt install -y ros-noetic-desktop-full ros-noetic-moveit ros-noetic-gazebo-ros-control

安装完成后，初始化rosdep时经常会遇到网络问题。这里提供两种解决方案：

1. 使用国内镜像源：

   sudo rosdep init rosdep update --include-eol-distros --rosdistro noetic

2. 手动修改sources.list（当上述方法失效时）：

   sudo sed -i "s|http://packages.ros.org|https://mirrors.tuna.tsinghua.edu.cn/ros|g" /etc/ros/rosdep/sources.list.d/20-default.list

提示：如果遇到"rosdep command not found"，需要先安装python3-rosdep包

2. 关键依赖安装与配置

宇树Z1的仿真环境依赖几个关键库，其中最容易出问题的是pinocchio的编译安装。以下是经过验证的安装流程：

2.1 基础依赖

sudo apt install -y libboost-all-dev libeigen3-dev liburdfdom-dev sudo ln -s /usr/include/eigen3/Eigen /usr/local/include/Eigen sudo ln -s /usr/include/eigen3/unsupported /usr/local/include/unsupported

2.2 Pinocchio编译安装

官方文档的安装命令可能会因为网络问题导致子模块下载失败。这里使用国内镜像源加速：

git clone --recursive https://gitee.com/mirrors/pinocchio.git cd pinocchio && mkdir build && cd build cmake .. \ -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_INSTALL_PREFIX=/usr/local \ -DBUILD_PYTHON_INTERFACE=OFF \ -DBUILD_TESTING=OFF make -j$(nproc) sudo make install

编译过程中可能遇到的典型错误及解决方案：

2.3 环境变量配置

将以下内容添加到~/.bashrc文件末尾：

export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH export CMAKE_PREFIX_PATH=/usr/local:$CMAKE_PREFIX_PATH export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH source /opt/ros/noetic/setup.bash

执行source ~/.bashrc使配置生效。验证安装是否成功：

pkg-config --modversion pinocchio

3. Z1 SDK与控制器安装

宇树官方提供了两个关键仓库：z1_sdk和z1_controller。建议按照以下顺序编译：

3.1 下载源码

mkdir -p ~/unitree_ws/src cd ~/unitree_ws/src git clone https://github.com/unitreerobotics/z1_controller.git git clone https://github.com/unitreerobotics/z1_sdk.git

3.2 编译z1_controller

cd z1_controller mkdir build && cd build cmake .. -DCMAKE_BUILD_TYPE=Release make -j$(nproc)

常见编译问题排查：

• 缺少pybind11：通过git clone https://github.com/pybind/pybind11.git安装
• 链接错误：检查LD_LIBRARY_PATH是否包含/usr/local/lib
• C++标准不匹配：在CMakeLists.txt中添加set(CMAKE_CXX_STANDARD 14)

3.3 编译z1_sdk

cd ~/unitree_ws/src/z1_sdk mkdir build && cd build cmake .. -DCMAKE_BUILD_TYPE=Release make -j$(nproc)

编译完成后，建议运行测试程序验证：

./highcmd_basic

4. ROS工作空间配置

创建一个独立的ROS工作空间管理Z1相关功能包：

cd ~/unitree_ws/src git clone --recursive https://github.com/unitreerobotics/unitree_ros.git cd .. rosdep install --from-paths src --ignore-src -y --rosdistro noetic

注意：如果rosdep失败，可以尝试手动安装缺失依赖：

sudo apt install -y ros-noetic-ros-control ros-noetic-ros-controllers

分步编译ROS包以避免依赖问题：

catkin_make --pkg unitree_legged_msgs catkin_make

将工作空间添加到环境变量：

echo "source ~/unitree_ws/devel/setup.bash" >> ~/.bashrc source ~/.bashrc

5. Gazebo仿真与调试

启动Gazebo仿真环境：

roslaunch unitree_gazebo z1.launch

常见问题及解决方案：

1. 模型加载失败：

   • 检查GAZEBO_MODEL_PATH是否包含~/unitree_ws/src/unitree_ros/unitree_description/models
   • 手动复制模型文件到~/.gazebo/models

2. 控制器启动失败：

   • 确认z1_controller/build/sim_ctrl有可执行权限
   • 检查ROS master是否正常运行(roscore)

3. 关节抖动问题：

   • 修改unitree_ros/unitree_controller/config/z1_controller.yaml中的PID参数
   • 降低max_velocity值

6. 键盘控制与示例动作

启动键盘控制需要两个终端：

终端1运行仿真：

roslaunch unitree_gazebo z1.launch

终端2启动控制器：

cd ~/unitree_ws/src/z1_controller/build ./sim_ctrl k

控制键位说明：

运行示例动作：

# 终端1 ./sim_ctrl # 终端2 cd ~/unitree_ws/src/z1_sdk/build ./highcmd_basic

7. ROS集成开发指南

将Z1 SDK集成到自定义ROS包时，需要注意以下关键点：

1. 库文件链接：
   • 将libZ1_SDK_x86_64.so复制到/usr/local/lib和你的ROS包的lib目录
   • 在CMakeLists中添加链接：

target_link_libraries(your_node ${catkin_LIBRARIES} libZ1_SDK_x86_64.so )

2. 头文件包含：
   • 复制z1_sdk/include/unitree_arm_sdk到你的ROS包的include目录
   • 设置包含路径：

include_directories( ${catkin_INCLUDE_DIRS} /usr/local/include ${CMAKE_CURRENT_SOURCE_DIR}/include )

3. 架构适配： 使用uname -m检查系统架构，对应修改：
   • x86_64:libZ1_SDK_x86_64.so
   • aarch64:libZ1_SDK_aarch64.so

8. 高级功能开发

利用Z1提供的接口函数可以实现复杂控制逻辑。以下是几个实用示例：

8.1 关节空间运动控制

#include "unitree_arm_sdk/control/unitreeArm.h" UnitreeArm arm; arm.setFsm(ArmFSMState::JOINTCTRL); Vec6 q = arm.lowstate->getQ(); // 获取当前关节角度 q(0) += 0.1; // 修改第一个关节角度 arm.setArmCmd(q, Vec6::Zero()); // 发送命令

8.2 笛卡尔空间运动

Vec6 targetPose; targetPose << 0.1, 0.2, 0.3, 0, 0, 0; // x,y,z,roll,pitch,yaw arm.MoveJ(targetPose, 0.5); // 以最大0.5rad/s速度移动

8.3 轨迹录制与回放

arm.teach("demo_traj"); // 开始录制轨迹 // ...执行手动操作... arm.teachRepeat("demo_traj"); // 回放录制的轨迹

9. 性能优化技巧

1. 实时性优化：

   • 使用sudo apt install linux-rt安装实时内核
   • 设置线程优先级：

     #include <pthread.h> pthread_t this_thread = pthread_self(); struct sched_param params; params.sched_priority = sched_get_priority_max(SCHED_FIFO); pthread_setschedparam(this_thread, SCHED_FIFO, &params);

2. 通信延迟优化：

   • 修改UDP通信参数：

     arm._ctrlComp->udp.SetRecvTimeout(1); // 1ms超时 arm._ctrlComp->udp.SetSendTimeout(1);

3. Gazebo加速：

   • 启动时添加参数：

     roslaunch unitree_gazebo z1.launch gui:=false verbose:=false

   • 修改world文件使用ode物理引擎

10. 故障排查手册

以下是开发者常见问题速查表：

对于更复杂的问题，建议按以下流程排查：

1. 检查ROS拓扑：

   rqt_graph

2. 查看TF树：

   rosrun tf view_frames

3. 分析Gazebo日志：

   gz log -d 1

4. 启用调试输出：

   arm._ctrlComp->SetDebug(true);