宇树Unitree Z1机械臂使用教程
作者： Herman Ye @Galbot @Auromix
版本： V1.0
测试环境： Ubuntu20.04 VMWARE
更新日期： 2023/08/04
注1： 本文内容中的硬件由 @Galbot 提供支持。
注2： @Auromix 是一个机器人爱好者开源组织。
注3： 本文在更新日期经过测试，确认有效。
宇树Unitree Z1机械臂使用教程
以下内容参考宇树官方的Z1 Docs。
由宇树官方材料提供的图片、文字等版权归宇树所有。
部分示意图片源于网络，侵删。
一、建立机械臂通信
1.配置PC端IP
直接在系统网络设置的如下界面更改： Settings -> Network -> PCI/USB Ethernet (点击需要使用的网口后面的齿轮图标)
图源自宇树Unitree Z1机械臂 Docs
2.连接网线
注意： Z1机械臂存在两个网口，如图所示，所连网口应当为主网口。
3.尝试Ping通机械臂
ping 192.168.123.110
二、基本运行demo
注意： Z1硬件特性，上电前先将机械臂手动回至零位。
1.安装依赖
# Install libboost-dev libeigen3-dev
sudo apt install -y libboost-dev libeigen3-dev
sudo ln -s /usr/include/eigen3/Eigen /usr/local/include/Eigen
sudo ln -s /usr/include/eigen3/unsupported /usr/local/include/unsupported
# Install pybind11
git clone https://github.com/pybind/pybind11.git
cd pybind11
mkdir build && cd build
cmake .. -DPYBIND11_TEST=OFF
make -j
sudo make install
2.配置z1_controller
- 下载z1_controller
cd ~
mkdir -p test_ws/src
cd test_ws/src
git clone https://github.com/unitreerobotics/z1_controller.git
- 编译z1_controller
cd z1_controller
mkdir build & cd build
cmake ..
make
3.下载z1_sdk
- 下载z1_sdk
git clone https://github.com/unitreerobotics/z1_sdk.git
- 编译z1_sdk
cd z1_sdk
mkdir build & cd build
cmake ..
make
4.运行demo
警告： 运行demo前请注意机械臂当前的工作空间环境，警惕安全风险。
# Terminal 1
cd z1_controller/build
./z1_ctrl
# Terminal 2
cd z1_sdk/build
./highcmd_basic
三、ROS Gazebo仿真demo
0.配置环境
注意： 创建单独的工作空间，避免z1_controller和z1_sdk与以下其他包共同编译失败。
cd ~
mkdir -p unitree_ws/src
cd unitree_ws/src
1.下载 unitree_legged_msgs
前往unitree_ros_to_real下载unitree_legged_msgs或者直接git clone。
git clone https://github.com/unitreerobotics/unitree_ros_to_real.git
2.获取 unitree_legged_msgs
手动摘取该文件夹放置于test_ws/src
3.下载unitree_ros
git clone https://github.com/unitreerobotics/unitree_ros.git
4.编译
注意： z1_controller和z1_sdk使用catkin_make无法正确编译，因为不能放在同一工作空间中。
cd ~/unitree_ws #打开该文件夹
catkin_make #初始化ROS工作空间
echo "source ~/unitree_ws/devel/setup.bash">>~/.bashrc #将ros路径添加到环境变量，可由pwd命令获取当前路径替换该路径
source ~/.bashrc #更新环境变量
5.运行demo
警告： 运行demo前请注意机械臂当前的工作空间环境，警惕安全风险。
- 运行demo
# Try demo with gripper
roslaunch unitree_gazebo z1.launch
# Try demo without gripper
roslaunch unitree_gazebo z1.launch UnitreeGripperYN:=false
- 运行虚拟控制器
cd ~/test_ws/src
cd z1_controller/build
./sim_ctrl
- 运行sdk
cd ~/test_ws/src
cd z1_sdk/build
./highcmd_basic
注意： 在虚拟机环境下可能出现图形驱动问题
四、键盘控制demo
1.运行z1_ctrl k
具体的操控方式参考Unitree Z1 Keyboard demo
cd ~/test_ws/src
cd z1_controller/build
./z1_ctrl k # Keyboard control mode
| State | KeySwitch | Switchable |
|---|---|---|
| BACKTOSTART | ~ | 1 2 |
| PASSIVE | 1 | ~ 2 3 |
| JOINTCTRL | 2 | ~ 1 3 4 5 6 7 8 9 0 - |
| CARTESIAN | 3 | ~ 1 2 4 5 6 9 |
| MoveJ | 4 | ~ 1 2 3 5 6 9 |
| MoveL | 5 | ~ 1 2 3 4 6 9 |
| MoveC | 6 | ~ 1 2 3 4 5 9 |
| TEACH | 7 | ~ 1 2 |
| TEACHREPEAT | 8 | automatically switched to 2 |
| SAVESTATE | 9 | automatically switched to 2 |
| TOSTATE | 0 | automatically switched to 2 |
| CALIBRATION | = | automatically switched to 1 |
五、手柄控制demo
手柄没电，不测了，参考Unitree Z1 Joypad demo。
六、moveit 真实机械臂demo
宇树的z1_ros包中提供了moveit的使用demo，但是，这个包的兼容性较差，属于历史遗留问题。
注意：
z1_ros包中的z1_controller和https://github.com/unitreerobotics/z1_controller中的 z1_controller不同，并且https://github.com/unitreerobotics/z1_sdk与z1_ros不兼容。
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.moveit和其他相关包安装
使用一键安装moveit脚本进行安装和测试，随后再执行以下命令：
sudo apt install -y ros-noetic-moveit-*
sudo apt install -y ros-noetic-joint-trajectory-controller ros-noetic-trac-ik-kinematics-plugin
3.安装其他依赖
- 安装pinocchio
# Install pinocchio
cd ~
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
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
LD_LIBRARY_PATH：
LD_LIBRARY_PATH是用来指定共享库（动态链接库）的搜索路径。- 当你运行一个可执行文件时，操作系统会搜索
LD_LIBRARY_PATH中指定的路径来查找该可执行文件所需的共享库文件。 - 这个环境变量通常用于解决在运行程序时遇到缺少共享库的问题。通过将共享库的路径添加到
LD_LIBRARY_PATH中，可以确保程序能够找到并正确加载所需的共享库。
CMAKE_PREFIX_PATH：
CMAKE_PREFIX_PATH是用来指定 CMake 在搜索依赖库和包时的基本路径。- 在 CMake 构建项目时，通常需要找到依赖库和包的位置。通过设置
CMAKE_PREFIX_PATH，可以告诉 CMake 在这些路径下搜索依赖项。 - 这个环境变量通常用于帮助 CMake 找到非标准的安装路径下的依赖库和包。
PKG_CONFIG_PATH：
-
PKG_CONFIG_PATH是用来指定pkg-config工具搜索 .pc 文件的路径。 -
pkg-config是一个用于检查和获取依赖库信息的工具，它通常用于帮助编译时找到依赖库的头文件和链接选项。 -
通过将
.pc文件所在的路径添加到PKG_CONFIG_PATH中，可以让pkg-config找到正确的依赖库信息，从而在编译时顺利链接和编译代码。 -
安装pybind11
# Install pybind11
git clone https://github.com/pybind/pybind11.git
cd pybind11
mkdir build && cd build
cmake .. -DPYBIND11_TEST=OFF
make -j
sudo make install
4.下载编译安装包
- 下载 unitree_legged_msgs
前往unitree_ros_to_real下载unitree_legged_msgs或者直接git clone。
git clone https://github.com/unitreerobotics/unitree_ros_to_real.git
-
获取 unitree_legged_msgs
手动摘取该文件夹放置于z1_ws/src -
安装配置z1_ros包
mkdir -p ~/z1_ws/src
cd ~/z1_ws/src
git clone --recursive https://github.com/unitreerobotics/z1_ros.git
cd ..
rosdep install --from-paths src --ignore-src -yr --rosdistro noetic
# compile unitree_legged_msgs first
catkin_make --pkg unitree_legged_msgs
catkin_make
source devel/setup.bash
注意： 对于虚拟机，如果性能有限，可以尝试 catkin_make -j2
4.开始测试
- 设置环境
source /opt/ros/noetic/setup.bash
source ~/z1_ws/devel/setup.bash
- 启动demo
roslaunch z1_bringup real_arm.launch rviz:=true
七、其他demo
其他诸如UDP控制电机等的demo，参考Unitree Z1的使用。