在WSL2上搞定Unitree Z1机械臂仿真：从Gazebo图形修复到ROS Noetic完整配置-平芜编程栈

在WSL2上搞定Unitree Z1机械臂仿真：从Gazebo图形修复到ROS Noetic完整配置

当你在Windows系统上通过WSL2运行Ubuntu进行机器人开发时，是否遇到过Gazebo或RViz窗口一片空白、机械臂模型无法显示的尴尬情况？这可能是许多机器人开发者转向WSL2环境时遇到的第一个"拦路虎"。本文将带你深入解决这个图形显示问题，并完整配置Unitree Z1机械臂的仿真环境。

1. WSL2图形显示问题的根源与诊断

WSL2虽然提供了接近原生Linux的性能，但在图形显示方面仍存在一些限制。Gazebo和RViz依赖OpenGL进行3D渲染，而WSL2默认的OpenGL实现存在兼容性问题。

要确认是否是这个问题，可以尝试以下诊断步骤：

在终端运行glxinfo | grep "OpenGL version"
检查输出中OpenGL版本是否低于3.3
尝试运行Gazebo，观察是否出现黑屏或模型缺失

常见症状包括：

Gazebo窗口打开但显示空白
RViz中机械臂模型无法加载
3D视图区域显示异常或闪烁

2. 解决WSL2图形显示问题

2.1 强制使用软件渲染

最直接的解决方案是强制使用CPU进行软件渲染，虽然这会牺牲一些性能，但能确保图形正常显示：

export LIBGL_ALWAYS_SOFTWARE=1 export LIBGL_ALWAYS_INDIRECT=0

可以将这两行命令添加到你的~/.bashrc文件中，这样每次打开终端都会自动设置。

2.2 安装Mesa3D库

另一种方法是安装更新的Mesa3D库来改善OpenGL支持：

sudo apt install mesa-utils libgl1-mesa-glx libgl1-mesa-dri

安装完成后，运行glxgears测试图形性能。

2.3 配置X服务器

确保你的Windows系统上安装了合适的X服务器，如VcXsrv或X410。配置时需要注意：

允许公共网络访问
禁用访问控制
启用OpenGL支持

在WSL2中设置DISPLAY环境变量：

export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0

3. Unitree Z1 SDK环境配置

3.1 安装系统依赖

首先安装基础依赖包：

sudo apt update sudo apt install -y \ libboost-all-dev \ libeigen3-dev \ liburdfdom-dev \ cmake \ git \ build-essential

创建必要的符号链接：

sudo ln -s /usr/include/eigen3/Eigen /usr/local/include/Eigen sudo ln -s /usr/include/eigen3/unsupported /usr/local/include/unsupported

3.2 安装pybind11

git clone https://github.com/pybind/pybind11.git cd pybind11 mkdir build && cd build cmake .. -DPYBIND11_TEST=OFF make -j$(nproc) sudo make install

3.3 安装ROS Noetic MoveIt

sudo apt install -y \ ros-noetic-moveit-* \ ros-noetic-joint-trajectory-controller \ ros-noetic-trac-ik-kinematics-plugin

3.4 安装Pinocchio

git clone --recursive https://github.com/stack-of-tasks/pinocchio 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

配置环境变量，将以下内容添加到~/.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

4. 获取并编译Unitree Z1 SDK

4.1 下载SDK

git clone https://github.com/Lya-M1RA/Unitree-Z1_SDK.git --recursive

SDK包含以下主要组件：

组件	功能描述
z1_controller	直接控制机械臂的源码
z1_sdk	控制机械臂的接口
unitree_ros	机械臂仿真文件
z1_ros	ROS Noetic MoveIt支持

4.2 编译z1_controller

cd Unitree-Z1_SDK/z1_controller mkdir build && cd build cmake .. make

4.3 编译z1_sdk

cd ../z1_sdk mkdir build && cd build cmake .. make

4.4 安装unitree_ros

cd ../../z1_ws catkin_make source devel/setup.bash

ARM64架构特殊处理：

cd src/unitree_ros/unitree_legged_control/lib rm libunitree_joint_control_tool.so mv libunitree_joint_control_tool_arm64.so libunitree_joint_control_tool.so

4.5 安装z1_ros

cd ../../../z1_moveit_ws rosdep install --from-paths src --ignore-src -yr --rosdistro noetic catkin_make --pkg unitree_legged_msgs catkin_make source devel/setup.bash

同样处理ARM64架构：

cd src/z1_ros/unitree_ros/unitree_legged_control/lib rm libunitree_joint_control_tool.so mv libunitree_joint_control_tool_arm64.so libunitree_joint_control_tool.so

5. 运行Unitree Z1仿真

5.1 启动Gazebo仿真

首先确保设置了软件渲染：

export LIBGL_ALWAYS_SOFTWARE=1 export LIBGL_ALWAYS_INDIRECT=0

启动Gazebo：

roslaunch unitree_gazebo z1.launch

如果不使用末端夹爪：

roslaunch unitree_gazebo z1.launch UnitreeGripperYN:=false

5.2 启动虚拟控制器

在新终端中：

cd Unitree-Z1_SDK/z1_controller/build ./sim_ctrl

5.3 运行SDK演示

在另一个新终端中：

cd Unitree-Z1_SDK/z1_sdk/build ./highcmd_basic

此时你应该能在Gazebo窗口中看到机械臂开始运动。

6. 在MoveIt中使用机械臂

6.1 启动MoveIt

对于仿真环境：

roslaunch z1_bringup sim_arm.launch rviz:=true

对于实机连接：

roslaunch z1_bringup real_arm.launch rviz:=true

6.2 启动控制器

对于仿真环境：

cd Unitree-Z1_SDK/z1_controller/build ./sim_ctrl

对于实机：

./z1_ctrl

现在你可以在RViz中使用MoveIt进行路径规划并控制机械臂运动了。

在WSL2上搞定Unitree Z1机械臂仿真：从Gazebo图形修复到ROS Noetic完整配置