作者： Herman Ye @Galbot @Auromix
版本： V1.0
测试环境： Ubuntu20.04 VMWARE
更新日期： 2023/08/04
注₁： 本文内容中的硬件由 @Galbot 提供支持。
注₂： @Auromix 是一个机器人爱好者开源组织。
注₃： 本文在更新日期经过测试，确认有效。

宇树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的使用。