由于机械臂通信格式修改, 建议在2019年6月前发货的xArm 早期用户尽早 升级 控制器固件程序，这样才能在以后的更新中正常驱动机械臂运动以及使用最新开发的各种功能。请联系我们获得升级的详细指示。 当前ROS库主要的分支已不支持旧版本，先前版本的ROS驱动包还保留在 'legacy' 分支中, 但不会再有更新。
在使用xarm_ros之前，请务必按照第3节准备工作的指示安装必要的第三方支持库，否则使用时会出现错误。
- 1. 简介
- 2. 更新记录
- 3. 准备工作(必须)
- 4. 开始使用'xarm_ros'
- 5. 代码库介绍及使用说明
- 6. 模式切换(new)
- 7. 其他示例(new)
此代码库包含xArm模型文件以及相关的控制、规划等示例开发包。开发及测试使用的环境为 Ubuntu 16.04 + ROS Kinetic Kame。 以下的指令说明是基于xArm7, 其他型号用户可以在对应位置将'xarm7'替换成'xarm6'或'xarm5'
此代码库仍然处在开发阶段，新的功能支持、示例代码，bug修复等等会保持更新。
- 添加xArm 7 描述文档，3D图形文件以及controller示例，用于进行ROS可视化仿真模拟。
- 添加MoveIt!规划器支持，用于控制Gazebo/RViz模型或者xArm真机，但二者不可同时启动。
- 添加 ROS直接控制xArm真机的相关支持，用户使用时应尽量小心。
- 添加 xArm hardware interface 并在驱动真实机械臂时使用 ROS position_controllers/JointTrajectoryController。
- 添加 xArm6 和 xArm5 仿真和真机控制支持。
- 添加 xArm 机械爪仿真模型。
- 添加 xArm6 双臂控制示例。
- 添加 xArm Gripper action 控制。
- 添加 xArm-with-gripper Moveit 开发包。
gazebo_ros_pkgs: http://gazebosim.org/tutorials?tut=ros_installing （如果使用Gazebo模拟器）
ros_control: http://wiki.ros.org/ros_control (记得选择您使用的 ROS 版本)
moveit_core: https://moveit.ros.org/install/
ROS Wiki: http://wiki.ros.org/
Gazebo Tutorial: http://gazebosim.org/tutorials
Gazebo ROS Control: http://gazebosim.org/tutorials/?tut=ros_control
Moveit tutorial: http://docs.ros.org/kinetic/api/moveit_tutorials/html/
这个模型在Gazebo demo中会用到。在Gazebo仿真环境中, 在model database列表里寻找 'table', 并将此模型拖入旁边的3D环境中. 通过这个操作，桌子的模型就会自动下载到本地。
如果xArm Gripper需要在Gazebo环境中仿真, 为了使物理引擎中的 mimic joints 并联机构可以正常运作，需要安装来自Konstantinos Chatzilygeroudis (@costashatz) 的 mimic_joint_plugin。关于这个插件的使用参考了@mintar的这个教程 。
如果您已经有了自己的catkin工作区，请跳过此步往下进行。 按照这里的教程生成catkin_ws。 请留意本文档已假设用户继续沿用 '~/catkin_ws' 作为默认的catkin工作区地址。
$ cd ~/catkin_ws/src
$ git clone https://github.com/xArm-Developer/xarm_ros.git$ rosdep update
$ rosdep check --from-paths . --ignore-src --rosdistro kinetic请将 'kinetic' 修改为您在使用的ROS版本。如有任何未安装的依赖包列出，请执行以下命令自动安装:
$ rosdep install --from-paths . --ignore-src --rosdistro kinetic -y同样的，请将 'kinetic' 修改为您在使用的ROS版本。
$ cd ~/catkin_ws
$ catkin_make$ echo "source ~/catkin_ws/devel/setup.bash" >> ~/.bashrc如果在您的 ~/.bashrc中已经有了以上语句，直接运行:
$ source ~/.bashrc$ roslaunch xarm_description xarm7_rviz_display.launch$ roslaunch xarm_gazebo xarm7_beside_table.launch [run_demo:=true] [add_gripper:=true] 指定'run_demo'为true时Gazebo环境启动后机械臂会自动执行一套编好的循环动作。 这套简单的command trajectory写在xarm_controller\src\sample_motion.cpp. 这个demo加载的控制器使用position interface（纯位置控制）。
指定'add_gripper'为true时, 会加载带有xarm 夹爪的模型。
包含xArm描述文档, mesh文件和gazebo plugin配置等等。 不推荐用户去修改urdf描述因为其他ros package对其都有依赖。
Gazebo world 描述文档以及仿真launch启动文档。用户可以在world中修改添加自己需要的模型与环境。
xarm使用的Controller配置, 硬件接口，轨迹指令源文件, 脚本以及launch文件。 用户可以基于这个包开发或者使用自己的package。注意 xarm_controller/config里面定义好的position/effort控制器仅用作仿真的示例, 当控制真实机械臂时只提供position_controllers/JointTrajectoryController接口。用户可以根据需要添加自己的controller, 参考: http://wiki.ros.org/ros_control (controllers)
内含加载xarm driver的启动文件，用来控制真实机械臂。
部分文档由moveit_setup_assistant自动生成, 用于Moveit Planner和Rviz可视化仿真。如果已安装MoveIt!,可以尝试跑demo：
$ roslaunch xarm7_moveit_config demo.launch- 如果不需要带有xArm Gripper，首先执行:
$ roslaunch xarm_gazebo xarm7_beside_table.launch然后在另一个终端运行:
$ roslaunch xarm7_moveit_config xarm7_moveit_gazebo.launch- 如果需要带有xArm Gripper，首先执行:
$ roslaunch xarm_gazebo xarm7_beside_table.launch add_gripper:=true然后在另一个终端运行:
$ roslaunch xarm7_gripper_moveit_config xarm7_gripper_moveit_gazebo.launch如果您在Moveit界面中规划了一条满意的轨迹, 点按"Execute"会使Gazebo中的虚拟机械臂同步执行此轨迹。
首先, 检查并确认xArm电源和控制器已上电开启, 然后运行:
$ roslaunch xarm7_moveit_config realMove_exec.launch robot_ip:=<控制盒的局域网IP地址>检查terminal中的输出看看有无错误信息。如果启动无误，您可以将RViz中通过Moveit规划好的轨迹通过'Execute'按钮下发给机械臂执行。但一定确保它不会与周围环境发生碰撞！
首先, 检查并确认xArm电源和控制器已上电开启, 然后运行:
$ roslaunch xarm7_gripper_moveit_config realMove_exec.launch robot_ip:=<your controller box LAN IP address>如果使用了我们配套的机械爪(xArm gripper), 最好可以使用这个package，因为其中的配置会让Moveit在规划无碰撞轨迹时将机械爪考虑在内。
这个简单包装实现的规划器接口是基于 Moveit!中的 move_group interface, 可以使用户通过service指定目标位置进行规划和执行。 这部分的详细使用方法请阅读xarm_planner包的文档。
$ roslaunch xarm_planner xarm_planner_realHW.launch robot_ip:=<控制盒的局域网IP地址> robot_dof:=<7|6|5>'robot_dof'参数指的是xArm的关节数目 (默认值为7)。
这两个package提供给用户封装了xArm SDK功能的ros服务, xarm自带的控制盒会进行轨迹规划。当前支持六种运动命令（ros service同名）:
-
move_joint: 关节空间的点到点运动, 用户仅需要给定目标关节位置，运动过程最大关节速度/加速度即可， 对应SDK里的set_servo_angle()函数。
-
move_line: 笛卡尔空间的直线轨迹运动，用户需要给定工具中心点（TCP）目标位置以及笛卡尔速度、加速度，对应SDK里的set_position()函数【不指定交融半径】。
-
move_lineb: 圆弧交融的直线运动，给定一系列中间点以及目标位置。 每两个中间点间为直线轨迹，但在中间点处做一个圆弧过渡（需给定半径）来保证速度连续，对应SDK里的set_position()函数【指定了交融半径】。
-
move_line_tool: 基于工具坐标系（而不是基坐标系）的直线运动。对应SDK里的set_tool_position()函数。
另外需要 注意 的是，使用以上4种service之前，需要通过service依次将机械臂模式(mode)设置为0，然后状态(state)设置为0。这些运动指令的意义和详情可以参考产品使用指南。除此之外还提供了其他xarm编程API支持的service调用, 对于相关ros service的定义在 xarm_msgs目录中。 -
move_servo_cart/move_servoj: （固定）高频率的笛卡尔或关节轨迹指令，分别对应SDK里的set_servo_cartesian()和set_servo_angle_j()，需要机械臂工作在模式1，可以间接实现速度控制。在使用这两个服务功能之前，务必做好风险评估并且仔细阅读第7.2-7.3节的使用方法。
首先启动xarm7 service server, 以下ip地址只是举例:
$ roslaunch xarm_bringup xarm7_server.launch robot_ip:=192.168.1.128然后确保每个关节的控制已经使能, 参考SetAxis.srv:
$ rosservice call /xarm/motion_ctrl 8 1在传递任何运动指令前，先依次设置正确的机械臂模式(0: POSE)和状态(0: READY), 参考SetInt16.srv:
$ rosservice call /xarm/set_mode 0
$ rosservice call /xarm/set_state 0请注意角度应全部使用radian作为单位。以下运动命令都使用同类型的srv request: Move.srv。
调用关节运动命令，最大速度 0.35 rad/s，加速度 7 rad/s^2:
$ rosservice call /xarm/move_joint [0,0,0,0,0,0,0] 0.35 7 0 0调用回原点服务 (各关节回到0角度)，最大角速度 0.35 rad/s，角加速度 7 rad/s^2:
$ rosservice call /xarm/go_home [] 0.35 7 0 0调用笛卡尔空间指令，目标位置表示在机械臂基坐标系中，最大线速度 200 mm/s，加速度为 2000 mm/s^2:
$ rosservice call /xarm/move_line [250,100,300,3.14,0,0] 200 2000 0 0调用笛卡尔空间指令，目标位置表示在机械臂当前工具坐标系中，最大线速度 200 mm/s，加速度为 2000 mm/s^2，以下指令将基于当前工具坐标系做相对移动(delta_x=50mm, delta_y=100mm, delta_z=100mm), 没有姿态的相对变化：
$ rosservice call /xarm/move_line_tool [50,100,100,0,0,0] 200 2000 0 0请注意以上的运动服务调用在默认情况下会立刻返回，如果希望等待运动结束之后再返回, 需要提前设置 ros parameter "/xarm/wait_for_finish" 为 true. 即:
$ rosparam set /xarm/wait_for_finish true如果成功会返回 0，发生错误则会返回1.
我们在机械臂末端提供了两路数字、两路模拟输入信号接口，以及两路数字输出信号接口。
$ rosservice call /xarm/get_digital_in$ rosservice call /xarm/get_analog_in 1 (最后一个参数：端口号，只能是1或者2)$ rosservice call /xarm/set_digital_out 2 1 (设定输出端口2的逻辑为1)注意检查这些service返回的"ret"值为0，来确保操作成功。
我们在控制盒外侧提供了八路数字输入和八路数字输出信号接口。
$ $ rosservice call /xarm/get_controller_din io_num (注意：从1到8, 对应CI0到CI7) $ rosservice /xarm/set_controller_dout io_num (注意：从1到8, 对应CO0到CO7) logic (0或1) 例如:
$ rosservice call /xarm/set_controller_dout 5 1 (设定输出端口5的逻辑为1)注意检查这些service返回的"ret"值为0，来确保操作成功。
如果通过运行'xarm7_server.launch'连接了一台xArm机械臂，用户可以通过订阅 "xarm/xarm_states" topic 获得机械臂当前的各种状态信息， 包括关节角度、工具坐标点的位置、错误、警告信息等等。具体的信息列表请参考RobotMsg.msg.
另一种选择是订阅 "/joint_states" topic, 它是以JointState.msg格式发布数据的, 但是当前 只有 "position" 是有效数据; "velocity" 是没有经过任何滤波的基于相邻两组位置数据进行的数值微分, 因而只能作为参考，我们目前还不提供 "effort" 的反馈数据.
基于运行时性能考虑，目前以上两个topic的数据更新率固定为 10Hz.
末端工具的偏移量可以也通过'/xarm/set_tcp_offset'服务来设定,参考下图，请注意这一坐标偏移量是基于 原始工具坐标系 (坐标系B)描述的，它位于末端法兰中心，并且相对基坐标系(坐标系A)有（PI, 0, 0)的RPY旋转偏移。
例如：
$ rosservice call /xarm/set_tcp_offset 0 0 20 0 0 0这条命令设置了基于原始工具坐标系(x = 0 mm, y = 0 mm, z = 20 mm)的位置偏移量，还有（0 rad, 0 rad, 0 rad)的RPY姿态偏移量。如果需要请在每次重新启动/上电控制盒时设定一次正确的偏移量，因为此设定会掉电丢失。
有时控制器会因为掉电、位置或速度超限、规划失败等原因汇报错误，遇到这一状态需要手动解除。具体的错误代码可以在topic "xarm/xarm_states" 的信息中找到。
$ rostopic echo /xarm/xarm_states如果'err'字段数据为非零，需要对照用户手册找到原因并设法解决问题。之后，这一错误状态可以通过调用服务 "/xarm/clear_err" 清除：
$ rosservice call /xarm/clear_err如果正在使用 Moveit!, 可以调用 "/xarm/moveit_clear_err", 这样可以省去再次手动设置模式1.
$ rosservice call /xarm/moveit_clear_err调用此服务之后 务必再次确认err状态信息 , 如果它变成了0, 说明问题清除成功，否则请再次确认问题是否成功解决。清除成功之后， 记得 将robot state设置为0 以便使机械臂可以执行后续指令。
如果已将xArm Gripper (UFACTORY出品) 安装至机械臂末端，则可以使用如下的service或action来操作和检视机械爪:
(1) 首先使能xArm机械爪并设置抓取速度, 如果成功，'ret'返回值为0。正确的速度范围是在1到5000之间，以1500为例:
$ rosservice call /xarm/gripper_config 1500(2) 给定xArm机械爪位置（打开幅度）指令执行，如果成功，'ret'返回值为0。正确的位置范围是0到850之间, 0为关闭，850为完全打开，以500为例:
$ rosservice call /xarm/gripper_move 500(3) 获取当前xArm机械爪的状态（位置和错误码）:
$ rosservice call /xarm/gripper_state如果错误码不为0，请参考使用说明书查询错误原因，清除错误同样可使用上一节的clear_err service。
gripper move action 定义在 Move.action. 目标包括期望的机械爪脉冲位置和脉冲速度. 可以通过设置xarm_bringup/launch/xarm7_server.launch 文件中的 "use_gripper_action" 参数来启动 action 服务器. Gripper action 可以这样调用:
$ rostopic pub -1 /xarm/gripper_move/goal xarm_gripper/MoveActionGoal "header:
seq: 0
stamp:
secs: 0
nsecs: 0
frame_id: ''
goal_id:
stamp:
secs: 0
nsecs: 0
id: ''
goal:
target_pulse: 500.0
pulse_speed: 1500.0"
或者通过以下方法调用:
$ rosrun xarm_gripper gripper_client 500 1500 如果需要与末端工具进行modbus通讯, 需要先通过"xarm/config_tool_modbus"服务设置正确的通信波特率和超时时间 (ms) (参考 ConfigToolModbus.srv). 例如:
$ rosservice call /xarm/config_tool_modbus 115200 20以上命令会设置末端modbus通信波特率为 115200 bps，接收超时时间为 20毫秒。 如果之后这些参数没有改变就不需要重新设置。 请注意 设置一个新的波特率可能会返回1（报错误码28）而不是0, 实际上如果设备已正确连接且没有其他导致通信错误的因素，设置是已经正确执行的。您可以清除错误后重新调用一次这个服务确定是否返回0。当前仅支持如下波特率设置 (单位bps): [4800, 9600, 19200, 38400, 57600, 115200, 230400, 460800, 921600, 1000000, 1500000, 2000000, 2500000].
设置完成后，modbus通信可以这样通过rosservice进行 (参考 SetToolModbus.srv):
$ rosservice call /xarm/set_tool_modbus [0x01,0x06,0x00,0x0A,0x00,0x03] 7第一个参数是要发送的通讯字节序列, 第二个参数是需要接收的回复字节数量. 这个数字应该是期望收到的数据字节数+1 (不含CRC校验字符). 来自末端modbus返回的数据会在最前面添加值为0x09的一个字节, 剩余的即为设备返回的数据。 举例来说，对于某个测试设备，上面的指令可能返回:
ret: 0
respond_data: [9, 1, 6, 0, 10, 0, 3]其中实际收到的数据帧为: [0x01, 0x06, 0x00, 0x0A, 0x00, 0x03]，长度为6.
xArm 在不同的控制方式下可能会工作在不同的模式中，当前的模式可以通过topic "xarm/xarm_states" 的内容查看。在某些情况下，需要用户主动切换模式以达到继续正常工作的目的。
Mode 0 : 基于xArm controller规划的位置模式；
Mode 1 : 基于外部轨迹规划器的位置模式；
Mode 2 : 自由拖动(零重力)模式。
Mode 0 是系统初始化的默认模式，当机械臂发生错误(碰撞、过载、超速等等),系统也会自动切换到模式0。并且对于xarm_api包和SDK中提供的运动指令都要求xArm工作在模式0来执行。Mode 1 是为了方便像 Moveit! 一样的第三方规划器绕过xArm控制器的规划去执行轨迹。 Mode 2 可以打开自由拖动模式, 机械臂会进入零重力状态方便拖动示教, 但需注意在进入模式2之前确保机械臂安装方式和负载均已正确设置。
如果在执行Moveit!规划的轨迹期间发生碰撞等错误, 为了安全考虑，当前模式将被自动从1切换到0, 同时robot state将变为 4 (错误状态)。这时即使碰撞已经解除，机械臂在重新回到模式1之前也无法执行任何Moveit!或者servoj指令。请依次按照下列指示切换模式:
(1) 确认引发碰撞的物体已经被移除；
(2) 清除错误:
$ rosservice call /xarm/clear_err(3) 切换回想要的模式 (以Mode 2为例), 之后 set state 为0（Ready状态）:
$ rosservice call /xarm/set_mode 2
$ rosservice call /xarm/set_state 0以上操作同样可用相关的xArm SDK函数实现.
在examples路径下会陆续更新一些其他应用的demo例程，欢迎前去探索研究。