TM ROS Driver

1. Overview

Techman Robot is a state-of-the-art production tool that is highly compatible and flexible to collaboration between human and machine. The Robot Operating System (ROS) provides abundant libraries and tools which can be utilized to reduce the cost of trivial development software tool and build robot applications without struggling. Our TM ROS driver provides nodes for communication with Techman Robot controllers, data including robot states, images from the eye-in-hand camera and URDF models for various robot arms via TMflow.

2. Feature

This driver is for ROS2 Foxy version.
To use the driver, make sure your ROS PC is installed correctly.
If the user wants to know how to use the ROS1 driver, please visit the TM ROS1 driver website or directly click on the listed Github repo: TM App Release below ROS1 projects in the table.

More information: TM ROS driver support list

TMflow + TM Robot Series
ROS Distro	GitHub repo: TM App Release	TM ROS Driver	TMvision Support	GitHub Branch
ROS Melodic Morenia	TM ROS1 Melodic	◯	✕	melodic
ROS Noetic Ninjemys	TM ROS1 Noetic	◯	◯	noetic
ROS 2 Dashing Diademata	TM ROS2 Dashing	◯	◯	dashing
ROS 2 Foxy Fitzroy	TM ROS2 Foxy	◯	◯	foxy
ROS 2 Humble Hawksbill	TM ROS2 Humble	◯	◯	humble
TMflow 2 + TM AI Cobot S-Series
ROS Distro	GitHub repo: TM 2 App Release	TM ROS Driver	TMvision Support	GitHub Branch
ROS Noetic Ninjemys	TM2 ROS1 Noetic	◯	◯	noetic
ROS 2 Foxy Fitzroy	TM2 ROS2 Foxy	◯	◯	foxy
ROS 2 Humble Hawksbill	TM2 ROS2 Humble	◯	◯	humble

Note: The Github repo: TM 2 App Release applies to TMflow Version 2.14 or above and adapts to HW5.0 mainly.

ROS2 Driver

The driver for ROS2 publishes identical topics and provides identical services as TM ROS1 version.
This driver uses ROS2 composition, there are two nodes in the identical process: one node publishes topics while the other node sets up service servers.

Installation

Just clone the TM ROS driver of the git repository into your working directory and then build it.
The user can directly refer to the chapters introduced in the following text: steps 1 to 4 of § Usage with demo code & driver.

3. Usage

The TM ROS driver is designed to interface the TM Robot's operating software (TMflow) with the Robot Operating System (ROS) so that program developers and researchers can build and reuse their own programs to control the TM robot externally.

After installing the correct ROS2 version of the computer, the next step is to ensure that your hardware, control computer, and TM Robot are all properly configured to communicate with each other. See below to make sure the network settings on your computer are correct, the TM Robot's operating software (TMflow) network settings are ready and the Listen node is running.

§ TMflow Listen node setup

The Listen node: a socket server can be established and be connected with ROS by an external device to communicate according to the defined protocol. The user can make the robot communicate with the user's ROS (remote) computer equipment through a wired network when all the network parameters in the Network setting are set.

1. Create a Listen task of flow project of TMflow software, and then drag the Listen node from the nodes menu onto the project flow, as shown below.

2. Set the Network settings: mouse-click to enter the page of System ⇒ Network in order.
   Example: Set the Subnet mask: to 255.255.255.0 and IP address 192.168.10.2
   Note: Set the network mask, and the communication with the TM Robot must be in the set domain.
   

3. Set the Ethernet Slave Data Table Setting item: mouse-click to enter the page of Setting ⇒ Connection ⇒ Ethernet Slave in order.
   We recommend one easy method ¹ to set the Ethernet Slave Data Table setting is to directly import the software package.
   ¹ See TM ROS Driver vs TMflow Software Usage: Import Data Table Setting.
   Or the previously provided method as follows: (Note: TMflow software version changes may have slightly different settings.)
   The user can manually click the Data Table Setting ² item and check the following boxes as item predefined ³ to receive/send specific data:

   • Robot_Error
   • Project_Run
   • Project_Pause
   • Safeguard_A
   • ESTOP
   • Camera_Light
   • Error_Code
   • Joint_Angle
   • Coord_Robot_Flange
   • Coord_Robot_Tool
   • TCP_Force
   • TCP_Force3D
   • TCP_Speed
   • TCP_Speed3D
   • Joint_Speed
   • Joint_Torque
   • Project_Speed
   • MA_Mode
   • Robot Light
   • Ctrl_DO0~DO7
   • Ctrl_DI0~DI7
   • Ctrl_AO0
   • Ctrl_AI0~AI1
   • END_DO0~DO3
   • END_DI0~DI2
   • END_AI0

   ² Turn off Ethernet Slave. Let "STATUS: Disable" displayed on the Ethernet Slave setting page, then click Data Table Setting to enter the next page for related settings.
   ³ The checked items listed above must all be selected for TM ROS setting.

   When you need to check more about the maximum, minimum, and average calculation properties of joint torque, the three checked items ⁴ listed below can be checked individually or all of them, please leave them unchecked when not in use.

   • Joint_Torque_Average
   • Joint_Torque_Min
   • Joint_Torque_Max

   ⁴ This function requires TMflow 1.84 or later versions to support.

4. Enable the Ethernet Slave settings: mouse-click to enable or disable TM Ethernet Slave. Once enabled, the robot establishes a Socket server to send the robot status and data to the connected clients and permissions to access specific robot data.
   Mouse-click to enable the Ethernet Slave setting and let STATUS: ⇒ Enable.

5. Press the Play/Pause Button on the Robot Stick to start running this Listen task project.

§ Remote connection to TM ROBOT

Static IP of remote connection network settings through the wired network.

1. Set the wired network of the user's (remote) Ubuntu computer by mouse-click on the top right of the desktop ⇒ Click on "Wired Settings" ⇒ Click on the gear icon ⇒ In the IPv4 feature options, click on "Manual" in order.
   
2. Set the Static IP settings: where the IP address is fixed for the first three yards same as the previous setting 192.168.10, last yards 3-254 machine numbers are available. (Because TM ROBOT, you have been set to 192.168.10.2)
   Example: Set the Netmask: 255.255.255.0 and IP address 192.168.10.30
   
3. Check Internet connection: start a terminal to test the connectivity with the target host TM ROBOT, by typing ping 192.168.10.2

💡 Tip: Remember to reconfigure the network settings due to static IP changes or replacement of the ROS control PC.
As mentioned above, a valuable debugging tool is your operating system's ping command. If nothing appears to happen or an error is thrown, the robot cannot be accessed from your computer. Please go back to the top of this chapter and re-operate in the order of instructions.
If you are an experienced user, you may just need to turn off ⇒ turn on the gear icon of "Wired Settings" on your computer or to turn off ⇒ turn on the "Ethernet Slave Data Table" setting of the robot to reconfigure the hardware settings.

§ TM ROS driver usage

ROS2 driver usage

After the user has set up the ROS2 environment (example : Debian packages for ROS 2 Foxy) and built the TM driver based on the specific workspace, please enter your workspace <workspace> by launching the terminal, and remember to make the workspace visible to ROS.

source /opt/ros/foxy/setup.bash
cd <workspace>
source ./install/setup.bash

💡 Do you prepare the TM Robot ready ? Make sure that TM Robot's operating software (TMflow) network settings are ready and the Listen node is running.

Then, run the driver to test whether the complete communication interface is properly working with TM Robot by typing

ros2 run tm_driver tm_driver robot_ip:=<robot_ip_address>

Example :ros2 run tm_driver tm_driver robot_ip:=192.168.10.2, if the <robot_ip_address> is 192.168.10.2

Now, the user can use a new terminal to run each ROS node or command, but don't forget to source the correct setup shell files as starting a new terminal. Note: When you finish executing your developed scripts or motion commands through the TM ROS driver connection, press CTRL + C in all terminal windows to shut everything down.

Usage with MoveIt2-foxy (2.2.3)

See MoveIt2 tutorial to install the MoveIt2 packages.

If you plan to use MoveIt, it is recommended to install and use Cyclone DDS.

sudo apt install ros-$ROS_DISTRO-rmw-cyclonedds-cpp
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp

The <MoveIt_WS> means the MoveIt2 workspace, for example ws_moveit2 .
The <TMDriver_WS> means TM driver workspace, for example tmdriver_ws .

To build MoveIt2

cd ws_moveit2
colcon build --event-handlers desktop_notification- status- --cmake-args -DCMAKE_BUILD_TYPE=Release

Assuming that the user is ready to build MoveIt2, and the user wants to apply the MoveIt by TM Robot, please do'nt forget to source the MoveIt environment, or you can add source <MoveIt_WS>/install/setup.bash to your .bashrc.
Then to build the TM driver based on the <TMDriver_WS> workspace, please enter the specific workspace tmdriver_ws by launching the terminal, and remember to make the workspace visible to ROS.

source /opt/ros/foxy/setup.bash
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
cd ~/tmdriver_ws 
source ~/ws_moveit2/install/setup.bash
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release
source ./install/setup.bash

💡 If you have built the TM driver before, it is recommended that you delete the build, install and log folders by the command rm -rf build install log, and rebuild it. For example,

source /opt/ros/foxy/setup.bash
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
cd ~/tmdriver_ws 
rm -rf build install log
source ~/ws_moveit2/install/setup.bash
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release
source ./install/setup.bash

The demo launches the RViz GUI and demonstrates planning and execution of a simple collision-free motion plan with TM Robot.
💡 Do you prepare the TM Robot ready ? Make sure that TM Robot's operating software (TMflow) network settings are ready and the Listen node is running.

• To bring up the MoveIt2 demo environment in simulation mode with the virtual TM Robot, by typing
  

ros2 launch tm_moveit_cpp_demo <tm_robot_type>_run_moveit_cpp.launch.py

The prefix <tm_robot_type> means the TM Robot type, available for tm5-900, tm5-700, tm12, and tm14 models, as well as the eyeless models tm5x-900, tm5x-700, tm12x and tm14x models.

Taking the TM5-900 robot as an example, use the commands introduced above, by typing

ros2 launch tm_moveit_cpp_demo tm5-900_run_moveit_cpp.launch.py

Note: When you are finished, press CTRL + C in all terminal windows to shut everything down.
The package tm_move_group provides a launch configuration for running a MoveGroup setup. The user can start planning and executing motions using the RViz MotionPlanning display.
💡 Do you prepare the TM Robot ready ? Make sure that TM Robot's operating software (TMflow) network settings are ready and the Listen node is running.

• To bring up the MoveIt2 - MoveGroup demo in simulation mode with the virtual TM Robot, by typing
  

ros2 launch tm_move_group <tm_robot_type>_run_move_group.launch.py

The prefix <tm_robot_type> means the TM Robot type, available for tm5-900, tm5-700, tm12, and tm14 models, as well as the eyeless models tm5x-900, tm5x-700, tm12x and tm14x models.

Taking the TM5-900 robot as an example, use the commands introduced above, by typing

ros2 launch tm_move_group tm5-900_run_move_group.launch.py

• The user can also manipulate the real TM Robot to run, by typing
  

ros2 launch tm_move_group <tm_robot_type>_run_move_group.launch.py robot_ip:=<robot_ip_address>

⚠️[CAUTION] This demo will let the real TM Robot move, please be careful. If the user are a beginner or unfamiliar with the arm movement path, it is recommended that the user place your hand on the big red emergency Stick Stop Button at any time, and press the button appropriately in the event of any accident that may occur.

Taking the TM5-900 robot as an example, use the commands introduced above, by typing

ros2 launch tm_move_group tm5-900_run_move_group.launch.py robot_ip:=<robot_ip_address>

The parameter <robot_ip_address> means the IP address of the TM Robot.

Note: When you have finished, press CTRL + C in all terminal windows to shut everything down.
📑 Note1: There are several built-in TM Robot nominal robot model settings, available for TM5-900, TM5-700, TM12, and TM14 models, as well as the eyeless models TM5X-900, TM5X-700, TM12X, and TM14X models.
📑 Note2: TM Robot set the default to read the Xacro file, such as TM5-900 model, to read the file tm5-900.urdf.xacro into robot_description or such as TM12 model, to read the file tm12.urdf.xacro into robot_description. If the user wants to use the specific model parameters instead of the nominal model to control the robot, please go back to the section 6. Generate your TM Robot-Specific Kinematics Parameters Files to modify the Xacro file.
📑 Note3: Running two tm ros drivers at the same IP address is not allowed. Since the tm driver node has been written into the moveit launch file, there is no need to execute ros2 run tm_driver tm_driver robots_ip:=<robot_ip_address>.

4. Vision

§ TM ROS Vision usage

This chapter describes that the user can get image data through TMvision™ of TM Robot. (Built-in Vision System)

Dependencies

• ROS2 Foxy

• Python packages:

  1. flask
  2. waitress
  3. opencv-python==3.4.13.47 (Minimum)
  4. numpy
  5. datetime

  For example, install Python3 packages:

  • pip3 install flask
  • pip3 install waitress
  • pip3 install opencv-python
  • pip3 install datetime

Techman Robot Vision

• type: sensor_msgs::msg::Image
• message name: techman_image

Build TM ROS Vision driver node on your (remote) computer

Under the environment settings have been finished with your workspace<workspace>, then type

cd ~/<workspace> && source ./install/setup.bash
ros2 run tm_get_status image_talker

💡 The user can check whether the connection succeeds or not. When you proceed to the following steps introduced in the following text: steps 6 of § TMflow Vision node setup.

§ TMflow Vision node setup

The Vision node provides the creation of a plane with fixed-point type, servo type, and object type as well as a variety of AOI identification functions.
💡 Before going through the following steps, please build the TM ROS Vision driver node on your (remote) computer and then connect this (remote) computer to the local TM Robot computer.

1. Create a Vision task project of TMflow software, and then drag the Vision node from the nodes menu onto the project flow, as shown below.
   

2. Click the AOI -only icon, and then follow the steps below to handle some settings related to accessing TM Robot HMI.
   

   TMflow 1.76 second version only:
   If no suitable dongle is detected, warning alerts will be displayed in the window.
   TMflow 1.88 version:
   The user doesn't need a dongle to activate this function.

3. Click the Find icon.

4. In TMflow 1.76 second version, click the AI_Detection icon.
   In TMflow 1.80 version, click the External Detection icon.

5. In TMflow 1.76 second version, click the + Add Parameters button. In TMflow 1.80 version, click the Setting button.

6. To check whether the connection succeeds or not, please enter <user_pc_ip_address>:6189/api in the HTTP Parameters blank text and click the Send button to get the information of the (remote) computer for ROS.
   The <user_pc_ip_address> means the IP address of the user's (remote) ROS computer, for example, 192.168.2.12
   

   If the connection fails, a TIMEOUT error will be displayed in the window

   If the IP address of the user's (remote) ROS computer doesn't exist, ERROR_CODE_7 will be displayed in the window.

7. Enter <user_pc_ip_address>:6189/api/DET in the URL blank text and type arbitrary letters in the Value blank text; the Key will be generated automatically.

8. Assign a name to the model in the Model name blank text and click the Save button.

9. Press the Play/Pause Button on the Robot Stick to start running this Vision task project.

   Note: TMflow software version changes may have slightly different settings. (SW1.76_Rev2.00) (SW1.80_Rev2.00)
   

§ Receive image data on the user's computer from TMflow Vision node

💡 Do you prepare the TM Robot ready? Make sure that TM Robot's operating software (TMflow) relative HTTP Parameters Vision settings are ready and the Vision task project is running.

Now, in a new terminal of your (remote) ROS computer: Source setup.bash in the workspace path and run to get image data from TMvision™ by typing

source ./install/setup.bash
ros2 run custom_package sub_img

Then, the viewer will display image data from TMflow.
Note: When you have finished, press CTRL + C in all terminal windows to shut everything down.

5. Program script demonstration

§ Demo package description

This chapter describes the demo package and the code used as a C++ programming example, showing how to program robot scripts (TM Robot Expressions) through the TM ROS driver connection.

• demo_send_script:
  In this demo code, it shows how to send a Listen node script to control the TM Robot.
  The user can use a service named "send_script" to send the script.
  "id" → The transaction number expressed in any alphanumeric ¹ characters.
  "script" → the script that the user wants to send.
  "ok" → the correctness of the script.
  ¹ If a non-alphanumeric byte is encountered, a CPERR 04 error is reported. When used as a communication packet response, it is a transaction number and identifies which group of commands to respond.
  

• demo_ask_item:
  In this demo code, the user can use this service to send TMSVR ² cmd.
  ² For more detailed information, please refer to defined protocol: TM Expression Editor and Listen Node.pdf (Chapter 9.6 TMSVR)
  

• demo_ask_sta:
  In this demo code, the user can use this service to send TMSTA ³ cmd.
  ³ For more detailed information, please refer to defined protocol (Chapter7.5 TMSTA)
  

• demo_connect_tm:
  In this demo code, the user can set the connection type.
  If the user sets reconnect to true, every time the driver disconnects from the Listen node, it will try to reconnect.
  There are two kinds of connection settings the user can select, one is "connect_tmsvr" for Ethernet server connection, and the other is "connect_tmsct" for TMflow connection.
  

• demo_set_event:
  In this demo code, six event types can be selected.
  func → TAG, WAIT_TAG, STOP, PAUSE, RESUME and EXIT
  arg0 → if func is TAG or WAIT_TAG, arg0 is the tag number
  arg1 → if func is TAG or WAIT_TAG, arg1 is timeout in ms
  

• demo_set_io:
  In this demo code, the user should set the module, type, pin, and state. ⁴
  module → MODULE_CONTROLBOX or MODULE_ENDEFFECTOR
  type → TYPE_DIGITAL_IN, TYPE_DIGITAL_OUT, TYPE_INSTANT_DO, TYPE_ANALOG_IN, TYPE_ANALOG_OUT, TYPE_INSTANT_AO
  pin → pin number
  state → STATE_OFF or STATE_ON value, or other value (if type expressed in a specific control module)
  ⁴ For more detailed information, please refer to defined protocol (Chapter6.5 IO)
  

• demo_set_positions:
  In this demo code, the user should pay attention to the parameter definition of the data format setting ⁵ and the parameter unit to be operated.
  motion_type → PTP_J , PTP_T , LINE_J , LINE_T , CIRC_J ,CIRC_T , PLINE_J ,PLINE_T
  positions → motion target position: If expressed in Cartesian coordinate (unit: m), if expressed in joint angles (unit: rad)
  velocity → motion velocity: if expressed in Cartesian coordinate (unit: m/s) ⁶, if expressed in joint velocity (unit: rad/s, and the maximum value is limited to π ) ⁶
  acc_time → time to reach maximum speed (unit: ms)
  blend_percentage → blending value: expressed as a percentage (unit: %, and the minimum value of 0 means no blending)
  fine_goal → precise position mode: If activated, the amount of error in the final position will converge more, but it will take a few more milliseconds.
  ⁵ For more detailed information, please refer to defined protocol (Chapter8 PTP, Line, Circle, Pline, Move_PTP, Move_Line, Move_PLine)
  ⁶ The unit of the parameters are different, the user can find the conversion in the program of TM ROS driver.
  

• demo_write_item:
  In this demo code, the user can use this service to send TMSVR ⁷ cmd.
  ⁷ For more detailed information, please refer to defined protocol (Chapter9.3 svr_write())
  

• demo_leave_listen_node:
  In this demo code, the user can use send_script service sending a script to leave the Listen node.
  💡 If the user has sent the demo_leave_listen_node script to leave the Listen node, and you want to run the TM Robot again, please remember that the Listen task project should be resumed to run. You can press the Stop Button on the Robot Stick and then press the Play/Pause Button to resume operation.
  

§ Usage with demo code & driver

Note: If the user has even successfully built a specific code(tmr_ros2), the user only needs to change to the TM driver workspace path cd ~/tmdriver_ws, and then directly refer to steps 5~6 below.

1. Type to create a root workspace directory by starting a terminal: For example, tmdriver_ws or catkin_ws, then type to change the current directory into the workspace directory path.
   mkdir ~/tmdriver_ws
cd ~/tmdriver_ws
   
2. Clone the TM driver of the git repository into the current directory by typing
   git clone https://github.com/TechmanRobotInc/tmr_ros2.git
   
3. After the download done, rename the download folder tmr_ros2(or tmr_ros2-foxy) to src by typing
   mv tmr_ros2 src
   (or right-click on the download folder, select "Rename...")
   
4. At the workspace directory to build the download packages and source 'setup.bash' in this workspace to make the workspace visible to ROS.
   Note: Do you set source /opt/ros/foxy/setup.bash ready? Make sure to obtain the correct setup file according to your workspace hierarchy, and then type the following below to compile.
   colcon build
source ./install/setup.bash
   
5. In a new terminal: Source setup.bash in the workspace path and run the driver to connect to TM Robot by typing
   source ./install/setup.bash
ros2 run tm_driver tm_driver robot_ip:=<robot_ip_address>
   The <robot_ip_address> is the IP address of the TM Robot, the user can get it through TM Flow, for example, 192.168.10.2
   
6. In another new terminal: Source setup.bash in the workspace path and type the specific demo node function that the user wants to study for applications. For example: the user select to run demo_set_io, the user can type
   source ./install/setup.bash
ros2 run demo demo_set_io
   ⚠️[CAUTION] Some demos will let the TM Robot move, please be careful.
   Note: When you have finished, press CTRL + C in all terminal windows to shut everything down.
   

6. TM GUI debugging and demonstration

This chapter describes a simplified GUI for displaying tm_driver connection status, sct, sta, svr messages, and robot status. The user can optionally install the ui_for_debug_and_demo package to aid in viewing messages between the driver and the robot through the GUI display. If the driver connection fails, the user can also try to send a reconnect command on this GUI for debugging.

§ GUI Debugging description

• If the user forgets to run the TM ROS driver, the user will see all the controlled label items of the GUI displayed as "NaN".
  
• The user can click the"Quit_GUI" button or click the "x" close button in the upper right corner to close this GUI.
  
• If "Ethernet" and "Listen Node" connection displays are "on", it means that ROS SvrClient and SctClient are successfully connected.
  
• If the"Ethernet" connection display is "off", the user should check whether the TM Robot has been started or whether the network settings are correct.
  
• If the"Listen Node" connection is "off", the user should check whether the task project is running.
  💡 If "Listen Node" connection is interrupted as "Project_Run" is stopped, the "Listen Node" connection will be "off".
  
• If both "Ethernet" and "Listen Node" connection displays are "on", but the "Robot_Link" is false or "Robot_Error" is true; this means the robot is working abnormally, or maybe the ESTOP button was pressed or some kind of protection or error ¹ occurred. Therefore, when the user sends a move script command at this time, it will not work.
  ¹ For more detailed information, please refer to the TM Robot User Guide.
  
• The user can use the self-developed script to read/write project data through communication protocols to control the TM Robot. If it does not work properly, the user can quickly determine whether there is a communication error code by viewing the "Response ROS Node Status" display.
  
• When the user sends a command or clicks DO0 Ctrl "H/L" button of Control_Box, the user also can see the response message ² embedded in the "Robot Response" item view.
  ² For details of this item, please refer to SctResponse.msg, StaResponse.msg and SvrResponse.msg of TM ROS driver code.
  
• The user can click "clear" button to clear the old response message.
  💡 If the"Ethernet" connection is interrupted, the display of most controlled label items in the GUI will be displayed as "NaN" and the robot feedback state will remain the last state and become invalid.
  

§ Usage with GUI debugging on the external Linux PC

Note: If the user has even successfully built a specific code(tmr_ros2), the user only needs to change to the TM driver workspace path cd ~/tmdriver_ws, and then directly refer to steps 5~6 below.

1. Type to create a root workspace directory by starting a terminal: For example, tmdriver_ws or catkin_ws, then type to change the current directory into the workspace directory path.
   mkdir ~/tmdriver_ws
cd ~/tmdriver_ws
   
2. Clone the TM driver of the git repository into the current directory by typing
   git clone https://github.com/TechmanRobotInc/tmr_ros2.git
   
3. After the download done, rename the download folder tmr_ros2(or tmr_ros2-foxy) to src by typing
   mv tmr_ros2 src
   (or right-click on the download folder, select "Rename...")
   
4. At the workspace directory to build the download packages and source 'setup.bash' in this workspace to make the workspace visible to ROS.
   Note: Do you set source /opt/ros/foxy/setup.bash ready? Make sure to obtain the correct setup file according to your workspace hierarchy, and then type the following below to compile.
   colcon build
source ./install/setup.bash
   
5. In a new terminal: Source setup.bash in the workspace path and run the driver to connect to TM Robot by typing
   source ./install/setup.bash
ros2 run tm_driver tm_driver robot_ip:=<robot_ip_address>
   The <robot_ip_address> is the IP address of the TM Robot, the user can get it through TM Flow, for example, 192.168.10.2
   
6. In another new terminal: Source setup.bash in the workspace path and start GUI debug by typing
   source ./install/setup.bash
ros2 run ui_for_debug_and_demo robot_ui
   Note: When you have finished, press CTRL + C in all terminal windows to shut everything down.
   

7. TM Robot corrected kinematics value loading and robot description file generation

Real kinematic values vary from TM robot to another one as each robot is calibrated at the factory.
The user can use the tm_mod_urdf package to extract specific kinematic values from your TM robot, which are taken into account by a Python script function using a specific set of commands to automatically generate a new URDF or Xacro robot model description file.

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.

§ Corrected kinematics value description

The precise kinematic parameters of a robot are useful for improving the end-point accuracy of the robot.
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.
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 a URDF 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 URDF file.

The common Python script is used as follows:

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 ¹ is <urdf_from>.
  ¹ There are several built-in TM Robot nominal robot model settings, available for tm5-900, tm5-700, tm12, and tm14 models, as well as the eyeless models tm5x-900, tm5x-700, tm12x and tm14x models.
  For example, select the tm12 nominal robot model as the input model form, the user can type tm12 as the <urdf_from>. For details of this item, please refer to the modify_urdf.py or modify_xacro.py code.
  
• <urdf_gen>: The second argument means the newly generated URDF model form of the TM Robot, and the file ² name is <urdf_gen>.
  ² 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.
  

The Python script for more specific arguments is used as follows:

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 ³ for details of this item.
  ³ For a simple third argument example, type the argument "-M" as follows:
  Example : python3 modify_xacro.py tm5-900 test -M
  → A robot description file "macro.test.urdf.xacro" will be generated, and the string 'macro.' is prepended to the <urdf_gen> name.
  

§ Create with specific kinematic parameters of the local TM Robot

💡 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.

• Take generating a new Xacro file as an example

The following steps describe how to import specific kinematic values using a real TM5-900 Robot following the procedure below, and select the corresponding type tm5-900 as an example of <urdf_from>.

1. In a terminal: Source setup.bash in the workspace path and run the driver to connect to TM Robot by typing
   

source /opt/ros/foxy/setup.bash
cd <workspace>
source ./install/setup.bash
ros2 run tm_driver tm_driver robot_ip:=<robot_ip_address>

The parameter <robot_ip_address> means the IP address of your TM Robot, the user can get it through TM Flow.

2. 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.
   

source /opt/ros/foxy/setup.bash
cd <workspace>
source ./install/setup.bash
cd src/tm_mod_urdf/tm_mod_urdf
python3 modify_xacro.py tm5-900 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".
📑 Note: In the previous chapter, we renamed the download folder tmr_ros2 (or tmr_ros2-foxy) to src. If the user misses this step, they will encounter such an error "[Error] [modify_xacro]: workspace directory not find " on the screen when executing the above command.

3. Next, the user must modify the filename part of the default pre-built nominal robot model in tm5-900.urdf.xacro to a newly generated robot model description naming file.
   

cd src\tm_description\xacro\
sudo vim tm5-900.urdf.xacro

or use gedit text editor instead of vim to edit the file contents, by typing

sudo gedit tm5-900.urdf.xacro

📑 Note1: If your real Robot is a TM5-700, in the above example, you should type tm5-700 as an example for <urdf_from> and modify the tm5-700.urdf.xacro file.
📑 Note2: If your real Robot is the eyeless model as a TM5X-700, in the above example, you should type tm5x-700 as an example for <urdf_from> and modify the tm5x-700.urdf.xacro file.

Please refer to the following to modify the content format of the filename line:

# Before modification : (Take the pre-built TM5-900 nominal robot model as an example) 
  <xacro:include filename="$(find tm_description)/xacro/macro.tm5-900-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 "tm5-900.urdf.xacro" to run your TM Robot or simulate the robot more accurately.

💡 Tip: Remember to recompile since the code has been changed.
Please go back to your specific workspace. Then you can choose colcon build --cmake-clean-cache to rebuild, or you can clean the build, install and log directories with rm -r build install log before executing colcon build.

• Take generating a new URDF file as an example

The following steps describe how to import specific kinematic values using a real TM5-900 Robot following the procedure below and select the corresponding type tm5-900 as an example of <urdf_from>.

1. In a terminal: Source setup.bash in the workspace path and run the driver to connect to TM Robot by typing
   

source /opt/ros/foxy/setup.bash
cd <workspace>
source ./install/setup.bash
ros2 run tm_driver tm_driver robot_ip:=<robot_ip_address>

The parameter <robot_ip_address> means the IP address of your TM Robot, the user can get it through TM Flow.

2. In another new terminal: source setup.bash in the workspace path, change the current directory to the directory path of the python script to correct urdf, and then enter the specified command format to generate a new named URDF with arguments, for example, named user_defined.
   

source /opt/ros/foxy/setup.bash
cd <workspace>
source ./install/setup.bash
cd src/tm_mod_urdf/tm_mod_urdf
python3 modify_urdf.py tm5-900 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".

📑 Note1: If your real Robot is a TM12, in the above example, you should type tm12 as an example for <urdf_from>.
📑 Note2: If your real Robot is the eyeless model as a TM12X, in the above example, you should type tm12x as an example for <urdf_from>.

Finally, the user can use the new robot file, such as "user_defined.urdf", instead of the default nominal URDF model to run your TM Robot or simulate the robot more accurately.

💡 Tip: Remember to recompile since the code has been changed.
Please go back to your specific workspace. Then you can choose colcon build --cmake-clean-cache to rebuild, or you can clean the build, install and log directories with rm -r build install log before executing colcon build.

§ Import information available on the screen

• How can the user confirm that the data conversion process has been completed?
  Ans: The user can find the string "File saved with new kinematic values." displayed on the screen.
  
• How can the user find the location of the newly generated named robot description file?
  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.
  

8. Contact us / Technical support

More Support & Service, please contact us. @TECHMAN ROBOT[https://www.tm-robot.com/zh-hant/contact-us/]