1.0.3 Add the tm_description package and tutorials, available for the…

… TM12S Cobot model simulation.

README.md

@@ -113,6 +113,15 @@ This chapter describes a simplified GUI for displaying tm_driver connection stat
 - [Usage Guideline](./doc/tm_noetic_gui.md)
 <div> </div>
 
-## __6. Contact us / Technical support__
+## __6. Generate your TM Robot-Specific Kinematics Parameters Files__
+Real kinematic values vary from TM robot to another one as each robot is calibrated at the factory.<br/>
+This chapter describes that the user can use a script program to extract specific kinematic values from your TM robot. The Python script function automatically generates a new URDF robot file that has XML macros in it (i.e. a new Xacro robot file) using a specific set of commands.
+- [Usage Guideline](./doc/tm_noetic_description.md)
+
+**Note 1**: If the user just want to use the TM Robot nominal model to control the robot, the user can skip the rest of this chapter.<br/>
+**Note 2**: The tm_description package contains description files and meshes, available for the TM12S model, and some Cobot models will be added later.
+<div> </div>
+
+## __7. Contact us / Technical support__
 More Support & Service, please contact us. [@TECHMAN ROBOT](https://www.tm-robot.com/zh-hant/contact-us/)``[https://www.tm-robot.com/zh-hant/contact-us/] ``<br/>
 <div> </div>

doc/tm_noetic_description.md

@@ -0,0 +1,91 @@
+# __Generate your TM Robot-Specific Kinematics Parameters Files__
+Real kinematic values vary from TM robot to another one as each robot is calibrated at the factory.<br/>
+This chapter describes that the user can use a script program to extract specific kinematic values from your TM robot. The python script function automatically generates a new Xacro robot model description file using a specific set of commands.
+> If the user just wants to use the TM Robot nominal model to control the robot, the user can skip the rest of this chapter.<br/>
+
+## &sect; Corrected kinematics value description
+ > The precise kinematic parameters of a robot are useful for improving the end-point accuracy of the robot.<br/>
+ > Due to manufacturing tolerances during manufacturing and the installation error in the robot assembly process, the positioning accuracy and precision of the mechanism will be affected. The error between the reality and the nominal robot model is significantly reduced by the corrected robot description. The kinematic parameter compensated deviations of the robot can improve the absolute positioning accuracy of the robot.<br/>
+ > If the user needs to improve simulation accuracy or end effector tracking performance, it is recommended that the user import the corrected calibrated kinematic parameters from the real TM Robot to replace the nominal set of D-H parameters. Techman Robot provides the Xacro file that configures the TM Robot model with a set of nominal DH parameters, and one that uses the programming scripts to obtain calibrated kinematic parameters from a parameter server connected to your TM robot and perform a set of overrides to output a new corrected Xacro file.<br/>
+ > <br/>
+ > The common Python script is used as follows:
+ >```bash
+ > python3 <script_name> <urdf_from> <urdf_gen>
+ >```
+ > * <script_name> : Provide modify_xacro.py or modify_urdf.py two Python scripts program as options.
+ > * <urdf_from>: The first argument represents the original URDF model form of the TM Robot, and the file part naming <sup>1</sup> is <urdf_from>.<br/>
+ > <sup>1</sup> There will be several built-in TM Robot nominal robot model settings, available for TM5S, TM7S, TM12S, TM14S, and TM25S models.<br/>
+ > For example, select your real robot type as the input nominal model form. If your TM robot is TM12S, then the user can type tm12s as the <urdf_from>.<br/>
+ > * <urdf_gen>: The second argument means the newly generated URDF model form of the TM Robot, and the file <sup>2</sup> name is <urdf_gen>.<br/>
+ > <sup>2</sup> For example, if the user names it test and select modify_xacro.py as script program, a test.urdf.xacro robot description file will be generated.<br/>
+ >
+ > The Python script for more specific arguments is used as follows:
+ >```bash
+ > python3 <script_name> <urdf_from> <urdf_gen> <specific_para>
+ >```
+ > * <specific_para>: The third argument is provided for use in some special cases. Please refer to the scripting program <sup>3</sup> for details of this item.<br/>
+ > <sup>3</sup> For a simple third argument example, type the argument "-M" as follows:<br/>
+ > Example : ``python3 modify_xacro.py tm12s test -M``<br/>
+ >  &rarr; A robot description file "`macro.test.urdf.xacro`" will be generated, and the string 'macro.' is prepended to the <urdf_gen> name.<br/>
+
+
+## &sect; Create with specific kinematic parameters of the local TM Robot
+> :bulb: Do you run the driver to maintain the connection with TM Robot, make sure that TM Robot's operating software (TMflow) network settings are ready and the Listen node is running.<br/>
+> <br/>
+> * #### __Take generating a new Xacro file as an example__
+> The following steps describe how to import specific kinematic values using a real TM12S Robot following the procedure below, and select the corresponding type tm12s as an example of <urdf_from>.<br/>
+>
+> 1. Terminal 1: Startup ROS core and type<br/>
+``roscore``<br/>
+> 2. In a new terminal 2: Source setup.bash in the workspace path and run the driver to connect to TM Robot by typing<br/>
+>
+> ```bash
+> source /opt/ros/noetic/setup.bash
+> cd <workspace>
+> source ./devel/setup.bash
+> rosrun tm_driver tm_driver <robot_ip_address>
+> ```
+> The parameter `<robot_ip_address>` means the IP address of your TM Robot, the user can get it through TM Flow.<br/>
+> 
+> 3. In another new terminal: Source setup.bash in the workspace path, change the current directory to the directory path of the Python script to get the specific kinematic parameters of your TM Robot, and then enter the specified command format to generate a new name by the <urdf_gen> argument, for example, named user_defined.<br/>
+> 
+> ```bash
+> source /opt/ros/noetic/setup.bash
+> cd <workspace>
+> source ./devel/setup.bash
+> cd src/tm_description/scripts
+> python3 modify_xacro.py tm12s user_defined
+> ```
+> When this procedure is completed, the user can find that the newly generated named robot description file has been saved, e.g."``user_defined.urdf.xacro``".<br/>
+> 
+> 4. Next, the user must modify the filename part of the default pre-built nominal robot model in tm12s.urdf.xacro to a newly generated robot model description naming file.<br/>
+> ```bash
+> cd src\tm_description\xacro\
+> sudo vim tm12s.urdf.xacro
+> ```
+>>  or use ``gedit`` text editor instead of ``vim`` to edit the file contents, by typing<br/>
+> ```bash
+> sudo gedit tm12s.urdf.xacro
+> ```
+>
+> :bookmark_tabs: Note: If your real Robot is a TM25S, in the above example, you should type tm25s as an example for <urdf_from> and modify the tm25s.urdf.xacro file.<br/>
+>
+> Please refer to the following to modify the content format of the filename line:<br/>
+> ```bash
+> # Before modification : (Take the pre-built TM12S nominal robot model as an example) 
+>   <xacro:include filename="$(find tm_description)/xacro/macro.tm12s-nominal.urdf.xacro" />
+> # After modification : (Replace with your actual newly generated Xacro file)
+>   <xacro:include filename="$(find tm_description)/xacro/user_defined.urdf.xacro" />
+> ```
+> Finally, the user can launch the modified robot file "``tm12s.urdf.xacro``" to run your TM Robot or simulate the robot more accurately.<br/>
+>> :bulb: **Tip**: Remember to recompile since the code has been changed.<br/>
+>> Please go back to your specific workspace. Then you can clean the build and devel directories with `rm -r build devel` before executing `catkin_make`.<br/>
+>
+>
+## &sect; Import information available on the screen
+>    *  How can the user confirm that the data conversion process has been completed?<br/>
+> Ans: The user can find the string "``File saved with new kinematic values.``" displayed on the screen.<br/>
+>    *  How can the user find the location of the newly generated named robot description file?<br/>
+> Ans: The user can first find the displayed string "``[new save file path:] ``" on the screen, and the following string is the file save location.<br/>
+
+

tm_description/CMakeLists.txt

@@ -0,0 +1,14 @@
+cmake_minimum_required(VERSION 3.0.2)
+project(tm_description)
+
+find_package(catkin REQUIRED)
+
+catkin_package(
+#  INCLUDE_DIRS include
+#  LIBRARIES tm_description
+#  CATKIN_DEPENDS other_catkin_pkg
+#  DEPENDS system_lib
+)
+
+install(DIRECTORY launch meshes rviz xacro
+  DESTINATION ${CATKIN_PACKAGE_SHARE_DESTINATION})

tm_description/launch/tm12s_upload.launch

@@ -0,0 +1,23 @@
+<?xml version="1.0"?>
+<launch>
+  <arg name="model" default="tm12s" />
+  <arg name="ns" default="" />
+  <arg name="prefix" default="" />
+
+  <arg name="color" default="none" />
+
+  <arg name="transmission_hw_interface" default="hardware_interface/PositionJointInterface" />
+
+  <!-- Arm -->
+  <param name="robot_description" command="$(find xacro)/xacro --inorder '$(find tm_description)/xacro/$(arg model).urdf.xacro' ns:=$(arg ns)        
+  prefix:=$(arg prefix) color:=$(arg color)" />
+  transmission_hw_interface:=$(arg transmission_hw_interface)" />
+
+  <!-- to skip xacro: in-order processing became default in ROS Melodic.
+  <param name="robot_description" command="$(find xacro)/xacro '$(find tm_description)/xacro/$(arg model).urdf.xacro'
+    ns:=$(arg ns) prefix:=$(arg prefix) color:=$(arg color)
+    robot_model:=$(arg model)
+    transmission_hw_interface:=$(arg transmission_hw_interface)"
+    />
+  -->
+</launch>

tm_description/launch/view_robot.launch

@@ -0,0 +1,15 @@
+<?xml version="1.0"?>
+<!--
+   Usage: Spawn a Techman robot model in the Rviz.
+   Syntax: The prefix <tm_robot_type> means the TM Robot type
+           $ roslaunch tm_description <tm_robot_type>_upload.launch
+           $ roslaunch tm_description view_robot.launch
+   Example: TM12S Techman robot model
+   Terminal 1:  [key-in] shell cmd $ roslaunch tm_description tm12s_upload.launch
+   Terminal 2:  [key-in] shell cmd $ roslaunch tm_description view_robot.launch
+-->
+<launch>
+  <node name="joint_state_publisher_gui" pkg="joint_state_publisher_gui" type="joint_state_publisher_gui" />
+  <node name="robot_state_publisher" pkg="robot_state_publisher" type="robot_state_publisher" />
+  <node name="rviz" pkg="rviz" type="rviz" args="-d $(find tm_description)/rviz/view_robot.rviz" required="true" />
+</launch>

tm_description/meshes/tm12s/visual/tm12s-a1.mtl

@@ -0,0 +1,18 @@
+newmtl DEFAULT_MTL
+Kd 0.695 0.743 0.790
+
+newmtl MTL0 
+Kd 0.408 0.400 0.400
+
+newmtl MTL1 
+Kd 0.000 0.000 0.000
+
+newmtl MTL2 
+Kd 0.220 0.231 0.278
+
+newmtl MTL3 
+Kd 0.820 0.831 0.839
+
+newmtl MTL4 
+Kd 0.980 0.990 1.000
+