[doc] add more instructions for uf850 and kinematics_suffix

utiasSTARS · Jan 4, 2024 · b37e30c · b37e30c
1 parent ffebf21
commit b37e30c
Show file tree

Hide file tree

Showing 5 changed files with 26 additions and 47 deletions.
diff --git a/ReadMe.md b/ReadMe.md
@@ -1,5 +1,5 @@
 For simplified Chinese version: [简体中文版](./ReadMe_cn.md)    
-For **UFACTORY Lite 6** users, make sure you have followed the instructions before chapter 4.7 on this page, then switch to [ReadMe for Lite6](./ReadMe_others.md).  
+For **UFACTORY Lite 6/850** users, make sure you have followed the instructions before chapter 4.7 on this page, then switch to [ReadMe for Lite6/UF850](./ReadMe_others.md).    
 For **kinetic** users, please use the [kinetic branch](https://github.com/xArm-Developer/xarm_ros/tree/kinetic).
 
 ## Important Notice:
@@ -203,7 +203,9 @@ $ roslaunch xarm_description xarm7_rviz_display.launch
 &ensp;&ensp;launch files to load xarm driver to enable direct control of real xArm hardware.  
 
 ## 5.5 xarm7_moveit_config
-Please note: xarm_moveit_config related packages will limit all joints within `[-pi, pi]`, it seems that moveit tend to generate plans involving greater joint motions if not limited within this range. This limit can be canceled by setting "limited:=false" in `...moveit_config/launch/planning_context.launch`.
+Please note: xarm_moveit_config related packages will limit all joints within `[-pi, pi]`, it seems that moveit tend to generate plans involving greater joint motions if not limited within this range. This limit can be canceled by setting "limited:=false" in `...moveit_config/launch/planning_context.launch`.   
+
+For any model which needs **kinematic calibration correction** added to the URDF, please check [uf_robot_moveit_config](uf_robot_moveit_config/Readme.md), this is a **unified** `moveit_config` package for all our models and supports new features.   
 
 &ensp;&ensp;This package is partially generated by moveit_setup_assistant, could use with Moveit Planner and Rviz visualization. If you have Moveit! installed, you can try the demo. 
    ```bash
@@ -720,6 +722,8 @@ If attaching RealSense D435i camera at tool end of xArm, with mechanical adapter
 ```bash
 $ roslaunch d435i_xarm_setup d435i_xarm_auto_calib.launch robot_dof:=your_xArm_DOF robot_ip:=your_xArm_IP
 ```
+Note: for xArm/UF850 produced **after August 2023**, kinematic calibration can be added to the URDF model, you can specify `kinematics_suffix` parameter for better accuracy, refer [here](https://github.com/xArm-Developer/xarm_ros/blob/master/uf_robot_moveit_config/Readme.md#optional-parameters) for details.   
+
 The `aruco Marker` used inside can be downloaded [here](https://chev.me/arucogen/), please remember the `marker ID` and `marker size` and modify them in the launch file accordingly. Refer to [official](https://github.com/IFL-CAMP/easy_handeye#calibration)or other usage instructions online and finish the calibration with the GUI.   
 
 If calculation result is confirmed and saved，it will appear by default under `~/.ros/easy_handeye` directory and can be used for transferring object coordinates to base frame. If the [camera_stand](https://www.ufactory.cc/products/xarm-camera-module-2020) provided by UFACTORY is used for fixing camera, a sample calibration result is stored at xarm_vision/d435i_xarm_setup/config/[xarm_realsense_handeyecalibration_eye_on_hand_sample_result.yaml](./xarm_vision/d435i_xarm_setup/config/xarm_realsense_handeyecalibration_eye_on_hand_sample_result.yaml) for this case.  

diff --git a/ReadMe_cn.md b/ReadMe_cn.md
@@ -1,4 +1,4 @@
-**UFACTORY Lite 6**用户, 确保您已经完成本篇说明中4.7节之前的部分，然后可以切换至[Lite6说明](./ReadMe_others.md).  
+**UFACTORY Lite 6/850**用户, 确保您已经完成本篇说明中4.7节之前的部分，然后可以切换至[Lite6/UF850说明](./ReadMe_others.md).  
 **kinetic**版本的用户，请使用[kinetic分支](https://github.com/xArm-Developer/xarm_ros/tree/kinetic).
 
 ## 重要提示:
@@ -197,6 +197,8 @@ $ roslaunch xarm_description xarm7_rviz_display.launch
 ## 5.5 xarm7_moveit_config
 请注意: xarm_moveit_config相关package会将所有关节限制在`[-pi, pi]`范围内, 因为如果不加限制，moveit可能会解出关节运动范围很大的轨迹。这个关节范围限制可以通过设置`...moveit_config/launch/planning_context.launch`文件中的"limited:=false"来取消。  
 
+对于任何需要将**运动学校准**参数加入URDF模型的型号, 请使用[uf_robot_moveit_config](uf_robot_moveit_config/Readme_cn.md), 这是一个**统一的**集合了全部UFACTORY机械臂型号的`moveit_config`包，并且支持一些新特性。   
+
 &ensp;&ensp;
    部分文档由moveit_setup_assistant自动生成, 用于Moveit Planner和Rviz可视化仿真。如果已安装MoveIt!,可以尝试跑demo： 
    ```bash
@@ -706,6 +708,8 @@ $ catkin_make
 ```bash
 $ roslaunch d435i_xarm_setup d435i_xarm_auto_calib.launch robot_dof:=your_xArm_DOF robot_ip:=your_xArm_IP
 ```
+注意: 对于**2023年8月之后**生产的xArm/UF850系列型号, 可以选择将运动学校准参数加入到URDF模型中, 在以上的launch命令中使用`kinematics_suffix`参数来提高标定的准确度, 详情参考[这里](https://github.com/xArm-Developer/xarm_ros/blob/master/uf_robot_moveit_config/Readme_cn.md#optional-parameters)。   
+
 标定使用的aruco二维码可以在[这里下载](https://chev.me/arucogen/)，请记住自己下载的`marker ID`和`marker size`，并在以上launch文件中修改。参考[官方](https://github.com/IFL-CAMP/easy_handeye#calibration)或其他网络教程通过图形界面进行标定，标定完成并确认保存后，默认会在 `~/.ros/easy_handeye`目录下生成`.yaml`后缀的结果文档，供后续与手臂一起进行坐标变换使用。如果固定件用的是UFACTORY提供的[camera_stand](https://www.ufactory.cc/products/xarm-camera-module-2020)，在xarm_vision/d435i_xarm_setup/config/[xarm_realsense_handeyecalibration_eye_on_hand_sample_result.yaml](./xarm_vision/d435i_xarm_setup/config/xarm_realsense_handeyecalibration_eye_on_hand_sample_result.yaml)中保存了参考的标定结果。 
 
 ### 7.2.1 关于 UFACTORY Lite6 手眼标定:

diff --git a/ReadMe_others.md b/ReadMe_others.md
@@ -1,7 +1,7 @@
 For Chinese version: [简体中文版说明](#重要说明)
 
 # Important Notice:
-This ReadMe is for new(Lite 6) and future UFACTORY product models other than xArm series. Here use "lite6" as example.  
+This ReadMe is for new(Lite 6 and UF850) and future UFACTORY product models other than xArm series. Here use "lite6" as example, for UFACTORY 850 users, please change "**lite6**" to "**uf850**" accordingly.  
 
 If you have used "xarm_ros" for xArm series before, the main differences for new UFACTROY models are:  
 
@@ -27,20 +27,7 @@ Gazebo will be launched and virtual robot will be mounted on a table, `add_gripp
 
 ## 1.3 Moveit simulation:
 
-### Without Gazebo:
-```bash
-$ roslaunch lite6_moveit_config demo.launch [add_gripper:=true] [add_vacuum_gripper:=true]
-```
-### With Gazebo:
-In the first terminal, run:
-```bash
-$ roslaunch xarm_gazebo lite6_beside_table.launch [add_gripper:=true] [add_vacuum_gripper:=true] 
-```
-Then in another terminal:
-```bash
-$ roslaunch lite6_moveit_config lite6_moveit_gazebo.launch [add_gripper:=true] [add_vacuum_gripper:=true] 
-```
-In this way, the simulated robot in gazebo can execute planned trajectory generated by Moveit. 
+Please refer to [uf_robot_moveit_config](uf_robot_moveit_config/Readme.md) package.   
 
 
 # 2. Controlling Real Robot
@@ -59,11 +46,10 @@ All the xArm services (joint/cartesian motion, velocity motion, servo motions, e
 Another difference from xArm version is the topic **`/xarm/xarm_states`** has been changed to **`/ufactory/robot_states`** (with default namespace attached).
 
 # 2.2 Moveit control:
-First make sure the robot and controller box are powered on, then execute:
-```bash
-$ roslaunch lite6_moveit_config realMove_exec.launch robot_ip:=192.168.1.xxx [add_gripper:=true] [add_vacuum_gripper:=true]
-```
-`add_gripper` and `add_vacuum_gripper` are optional available arguments if you have installed UFACTORY provided tool accessory. Only one end tool shall be installed. Below is the network diagram from `rqt_graph` output:  
+
+Please refer to [uf_robot_moveit_config](uf_robot_moveit_config/Readme.md) package.    
+
+Below is the network diagram from `rqt_graph` output:  
 
 
 ![uf_moveit_rqt_graph](./doc/uf_moveit_rqt_graph.png) 
@@ -72,7 +58,7 @@ $ roslaunch lite6_moveit_config realMove_exec.launch robot_ip:=192.168.1.xxx [ad
 
 # 重要说明:
 
-这篇ReadMe适用于UFACTORY xArm系列之外的产品(如Lite 6)，本说明使用 "lite6" 作为例子。  
+这篇ReadMe适用于UFACTORY xArm系列之外的产品(如Lite 6, UF850)，本说明使用 "lite6" 作为例子，使用UFACTORY 850的用户，请将"**lite6**"关键字替换为"**uf850**"。  
 
 如果您之前已经使用过 "xarm_ros" 开发 xArm 系列产品, 对于UFACTORY其他系列的ros开发，方法和操作大同小异，主要的区别在于:  
 
@@ -98,20 +84,7 @@ Gazebo启动后, 虚拟机械臂会放置在桌子边沿位置，`add_gripper`
 
 ## 1.3 Moveit规划仿真:
 
-### 如果不使用Gazebo:
-```bash
-$ roslaunch lite6_moveit_config demo.launch [add_gripper:=true] [add_vacuum_gripper:=true]
-```
-### 如果使用Gazebo:
-打开一个终端, 执行:
-```bash
-$ roslaunch xarm_gazebo lite6_beside_table.launch [add_gripper:=true] [add_vacuum_gripper:=true] 
-```
-然后，在另一个终端中执行:
-```bash
-$ roslaunch lite6_moveit_config lite6_moveit_gazebo.launch [add_gripper:=true] [add_vacuum_gripper:=true] 
-```
-这样，Gazebo中的虚拟手臂可以执行Moveit在Rviz界面中的规划路径。  
+请参考[uf_robot_moveit_config](uf_robot_moveit_config/Readme_cn.md)   
 
 
 # 2. 控制真实机械臂
@@ -130,11 +103,9 @@ $ rosservice call /ufactory/motion_ctrl 8 1
 另一个值得注意的变化是xArm系列使用的话题 **`/xarm/xarm_states`** 被修改为 **`/ufactory/robot_states`** (已带上默认命名空间)。
 
 # 2.2 Moveit 规划控制:
-首先确认手臂已经正确上电, 然后执行:
-```bash
-$ roslaunch lite6_moveit_config realMove_exec.launch robot_ip:=192.168.1.xxx [add_gripper:=true] [add_vacuum_gripper:=true]
-```
-`add_gripper` 和 `add_vacuum_gripper` 是另外的可选参数，可以根据需要给定`true`来加载UFACTORY官方的夹爪或吸头的配件模型，注意只能加载一款末端执行器。下图是来自`rqt_graph`输出的网络结构示意图:  
-
+
+请参考[uf_robot_moveit_config](uf_robot_moveit_config/Readme_cn.md)   
+
+下图是来自`rqt_graph`输出的网络结构示意图:  
 
 ![uf_moveit_rqt_graph](./doc/uf_moveit_rqt_graph.png) 
diff --git a/uf_robot_moveit_config/Readme.md b/uf_robot_moveit_config/Readme.md
@@ -297,7 +297,7 @@
     roslaunch uf_robot_moveit_config xarm7_moveit_fake.launch add_other_geometry:=true geometry_type:=mesh geometry_mesh_filename:=package://xarm_description/meshes/vacuum_gripper/xarm/visual/vacuum_gripper.stl geometry_mesh_tcp_xyz:='"0 0 0.126"'
     ```
   - __jnt_stat_pub_rate__: Publish frequency of joint_state_publisher, default is 10
-  - __kinematics_suffix__: Specify joint Kinematics parameter file suffix
+  - __kinematics_suffix__: Specify joint Kinematics parameter file suffix (available for xArm/UF850 produced after August 2023)  
     - Generation of Kinematics parameter file: 
       ```bash
       cd src/xarm_ros/xarm_description/config/kinematics
@@ -313,7 +313,7 @@
       #   uf850: xarm_description/config/kinematics/user/uf850_kinematics_AAA.yaml
       ```
     - Use of Kinematics parameter file: Specify this parameter when starting the launch file
-      - Note that before specifying this parameter, make sure that the corresponding configuration file exists. If it does not exist, you need to connect the robot arm through a script to generate it.
+      - Note that before specifying this parameter, make sure that the corresponding configuration file exists. If it does not exist, you need to connect the robot arm and use above-mentioned script to generate it.
 
 - ### Special parameters
   - __hw_ns__: Namespace, xarm series defaults to __xarm__, others default to __ufactory__, only valid in gazebo/realmove startup scripts, the corresponding service name is <`hw_ns`>/<service_name>

diff --git a/uf_robot_moveit_config/Readme_cn.md b/uf_robot_moveit_config/Readme_cn.md
@@ -294,7 +294,7 @@
     roslaunch uf_robot_moveit_config xarm7_moveit_fake.launch add_other_geometry:=true geometry_type:=mesh geometry_mesh_filename:=package://xarm_description/meshes/vacuum_gripper/xarm/visual/vacuum_gripper.stl geometry_mesh_tcp_xyz:='"0 0 0.126"'
     ```
   - __jnt_stat_pub_rate__: joint_state_publisher的发布频率，默认为10
-  - __kinematics_suffix__: 指定关节Kinematics参数文件后缀
+  - __kinematics_suffix__: 指定关节Kinematics参数文件后缀(适用于2023年8月之后出产的xArm/UF850系列)
     - 参数文件的生成: 
       ```bash
       cd src/xarm_ros/xarm_description/config/kinematics