TCP/IP¶
Mech-Mind Software Suite can communicate with the following robots through TCP/IP:
ABB
YASKAWA
FANUC
KUKA
Kawasaki
For setup instructions and other information specific to each robot, please refer to Robot Integrations - Standard Interface.
The commands are as follows:
Command 101: Start Mech-Vision Project¶
This command starts the running of the Mech-Vision project, which executes image capturing and performs vision recognition.
If the project works in the eye-in-hand mode, the robot pose for image capturing will be transmitted by this command into the project.
This command is for scenarios using only Mech-Vision.
Command Sent¶
101, project number, number of vision points, robot pose type, robot pose
Project number
The integer ID number of the Mech-Vision project in Mech-Center, i.e., the number shown on the left of the project path in in Mech-Center.
Number of vision points
The number of vision points (i.e., vision poses and their corresponding point clouds, labels, indices, etc.) to expect Mech-Vision to output.
0Get all the vision points from the Mech-Vision project’s recognition results.
integers > 0Get the specified number of vision points.
If the total number of vision points is smaller than the parameter value, all the available vision points will be returned.
If the total number of vision points is greater than or equal to the parameter value, vision points in the quantity of the parameter value will be returned.
Note
The command to obtain the vision points is command 102. In TCP/IP, due to the limit that a maximum of 20 vision points can be obtained by executing command 102 at a time, after executing command 102 for the first time, one of the parameters returned will indicate whether all the vision points requested have been returned; if not, please repeat executing command 102.
Robot pose type
This parameter indicates the type of the current pose of the real robot to input to Mech-Vision.
0No robot pose needs to be transmitted by this command.
If the project works in the eye-to-hand mode, then image capturing has nothing to do with the robot’s pose, so no robot image capturing pose is needed by Mech-Vision.
1The robot pose transmitted by this command is JPS.
2The robot pose transmitted by this command is a flange pose.
Robot pose
This parameter is the robot pose needed when the project works in the eye-in-hand mode.
The robot pose is either JPS or flange pose, according to the setting of the parameter robot pose type.
Data Returned¶
101, status code
Status code
If there is no error, status code 1102 will be returned. Otherwise, the corresponding error code will be returned.
Test Samples¶
Command 101 is normally executed without error.
TCP send string = 101, 1, 10, 1, 0, -20.63239, -107.81205, 0, -92.81818, 0.00307
TCP received string = 101, 1102
Error: project ID number does not exist.
TCP send string = 101, 2, 10, 1, 0, -20.63239, -107.81205, 0, -92.81818, 0.00307
TCP received string = 101, 1011, 1
Command 102: Get Vision Result¶
This command gets the vision result, i.e., vision points, after executing command 101.
Note
In TCP/IP, by default, command 102 can only fetch at most 20 vision points at a time. So, command 102 may need to be repeatedly executed until all the vision points required are obtained.
Command Sent¶
102, project number
Project number
The integer ID number of the Mech-Vision project in Mech-Center, i.e., the number shown on the left of the project path in in Mech-Center.
Data Returned¶
102, status code, sending completion status, number of vision points, reserved field, vision point, vision point, ...
Note
The vision points (up to 20 vision points by default) are located at the tail of the data returned.
Status code
If there is no error, status code 1100 will be returned. Otherwise, the corresponding error code will be returned.
After executing this command, if the results from Mech-Vision have not been returned, Mech-Center will wait before sending the results to the robot. The default wait time is 10 seconds. If a timeout occurs, the timeout error status code will be returned.
Sending completion status
This parameter indicates whether all the vision points requested have been obtained.
0Not all the vision points requested have been obtained. Please repeat executing command 102 until this parameter turns 1.
1All the vision points requested have been obtained.
Note
If not all the vision points requested have been obtained and command 101 is executed at this time, the rest of the vision points that are not obtained will be cleared.
Number of vision points
The number of vision points returned from the Mech-Vision project by executing this command this time.
Reserved field
This field is not used.
The value defaults to 0.
Vision point
pose, label, velocityPose
A pose includes the Cartesian coordinates (XYZ) and Euler angles (ABC).
Label
The integer label assigned to the pose. If in the Mech-Vision project, the labels are strings, they need to be mapped to integers before outputting from the Mech-Vision project. If there are no labels in the Mech-Vision project, the label defaults to 0.
Velocity
The parameter defaults to 0 for command 102 because Mech-Vision does not provide the planning on velocity.
Test Samples¶
Test samples of normal execution and execution error
Command 102 is normally executed without errors.
TCP send string = 102, 1
TCP received string = 102, 1100, 1, 1, 0, 95.7806085592122, 644.5677779910724, 401.1013614123109, 91.12068316085427, -171.13014981284968, 180.0, 0, 0
Error: no vision results.
TCP send string = 102, 1
TCP received string = 102, 1002, 1
Test Sample of requesting vision points
The test sample below is obtaining 22 vision points by sending commands 101, 102, and 102 sequentially. Details are as follows:
TCP/IP sends command 101, with content
101, 1, 0, 1, …, expecting to obtain all the available vision points.TCP/IP sends command 102 to obtain the vision results.
TCP/IP receives the data returned by executing command 102. The content is
102, 1100, 0, 20, …, indicating 20 vision points have been obtained and not all vision points have been obtained.TCP/IP sends command 102 again to fetch the remaining vision points.
TCP/IP receives the data returned by executing command 102 again. The content is
102, 1100, 1, 2, ..., which includes 2 vision points and indicates all the vision points have been obtained.
TCP send string = 101, 1, 0, 1, -0, -20.63239, -107.81205, -0, -92.81818, 0.0016
TCP received string = 101, 1102
TCP send string = 102, 1
TCP received string = 102, 1100, 0, 20, 0, 95.7806085592122, 644.5677779910724, 401.1013614123108, 31.12068316085427, ...
TCP received string = 78549940546, -179.99999999999991.0.0, 329.228345202334.712.7061697180302.400.9702665047771, ...
TCP received string =39546, -83.62567351596952, -170.87955974536686, -179.99999999999937, 0, 0, 223.37118373658322, ...
TCP received string = 005627, 710.1004355953408, 400.82227273918835, -43.89328326393665, -171.30845207792612, ...
TCP received string = 20.86318821742358, 838.7634193547805, 400.79807564314797, -102.03947940869523, -171.149261231 ...
TCP received string = 390299920645, -179.99999999999994, 0, 0, 303.0722145720921, 785.3254917220695, 400.75827437080, ...
TCP received string = 99668287.77.78291612041707, -171.53941633937786, 179.99999999899997, 0.0, 171.47819668864432, ...
TCP received string = 332193785, 400.6472716208158, -94.3418019038759, -171.10001228964776, -179.39999999999994, ...
TCP received string = 92388542936, 807.5641001485708, 400.6021999602664, - 167.9834797197932.-171.39671274951826, ...
TCP received string = 278.3198007132188, 780.5325992145735, 400.4924381003066, -174.72728396633053, -171.422604771 ...
TCP recelved string = 3.99999999999994, 0, 0, 183.82195326381233, 862.5171519967056.400.422966515846.-154. 17801945 ...
TCP received string = 173.34301974982765, -180.0, 0, 0
TCP send string = 102, 1
TCP received string = 102, 1100, 1, 2, 0, 315.2017788478321, 592.1261793743445, 399.60526335590957, 126.19602189220371, ...
TCP received string = 686127, -171.44430002882129, -1.3381805753922965e-15, 0, 0
Command 103: Switch Mech-Vision Recipe¶
This command switches the parameter recipe used in Mech-Vision.
In Mech-Vision, what parameter settings a Step has can be modified by switching the parameter recipe.
Parameters involved in recipe switching usually include point cloud matching model, image matching template, ROI, confidence threshold, etc.
This command needs to be used before executing command 101 which starts the Mech-Vision project.
Command Sent¶
103, project number, recipe number
Project number
The integer ID number of the Mech-Vision project in Mech-Center, i.e., the number shown on the left of the project path in in Mech-Center.
Recipe number
The identification number of the parameter recipe to switch to, i.e., the number on the left of the parameter recipe name in in Mech-Vision.
Data Returned¶
103, status code
Status code
If there is no error, status code 1107 will be returned. Otherwise, the corresponding error code will be returned.
Test Samples¶
Command 103 is executed normally without errors.
TCP send string = 103, 1, 2
TCP received string = 103, 1107
Error: invalid recipe number.
TCP send string = 103, 1, 2
TCP received string = 103, 1102
Command 201: Start Mech-Viz Project¶
This command is for scenarios using both Mech-Vision and Mech-Viz.
This command starts the running of the Mech-Viz project, calls the corresponding Mech-Vision project, and lets the Mech-Viz project plan the robot path based on the vision points from Mech-Vision.
For the Mech-Viz project that needs starting, the option Autoload needs to be checked in Mech-Viz’s interface.
Please see Example Mech-Viz Projects for Standard Interface for the description of example Mech-Viz projects.
Command Sent¶
201, pose type, robot pose
Pose type
0The current pose of the robot is not needed by Mech-Viz and no pose will be sent.
If the project works in the eye-to-hand mode, no robot image capturing pose will be needed by the project.
In Mech-Viz, the simulated robot will move from the initial pose JPS = [0, 0, 0, 0, 0, 0] to the first target point in the planned path.
1The robot pose will be sent to Mech-Viz and the pose sent is in JPS.
In Mech-Viz, the simulated robot will move from the input initial pose (i.e., the pose sent by this command) to the first target point in the planned path.
TCP is not supported at present.
Note
If in the scene, there are barriers that stand in the way from the initial pose JPS = [0, 0, 0, 0, 0, 0] to the first target point in the planned path, the pose type must be set to 1.
Robot pose
The current JPS of the real robot (if pose type is set to 1).
Data Returned¶
201, status code
Status code
If there is no error, status code 2103 will be returned. Otherwise, the corresponding error code will be returned.
Test Samples¶
Command 201 is normally executed without errors.
TCP send string = 201, 1, 0, -20.63239, -107.81205, 0, -92.81818, 0.00307
TCP received string = 201, 2103
Error: Mech-Viz does not support robot pose in TCP.
TCP send string = 201, 2, -0, 682.70355, 665.22266, 90, 179.99785, -89.99693
TCP received string = 201, 2015, 1
Command 202: Stop Mech-Viz Project¶
Stop the running of the Mech-Viz project. This command is not needed when the Mech-Viz project does not fall into an infinite loop or can be stopped normally.
Command Sent¶
202
Data Returned¶
202, status code
Status code
If there is no error, status code 2104 will be returned. Otherwise, the corresponding error code will be returned.
Test Sample¶
Command 202 is normally executed.
TCP send string = 202
TCP received string = 202, 2104
Command 203: Select Mech-Viz Branch¶
This command specifies which branch the project should run along. For this command, the branching is implemented by a branch_by_service_message Task, and this command selects the branch by specifying an out port of the Task.
Before executing this command, the Mech-Viz project needs to be started by executing command 201.
When the Mech-Viz project runs to the branch_by_service_message Task, it will wait for command 203 to specify which out port of the Task, i.e., the branch, the project should run along.
Command Sent¶
203, branching Task name, out port number
Branching Task name
This parameter is for specifying which branch_by_service_message Task the branch selection should apply to.
The value should be an integer ([1, N])., and before running the project, the Task involved in this command should be named as an integer ([1, N]). The name should be unique in the project.
Out port number
This parameter is for specifying which out port of the specified Task, i.e., the branch, the project should run along. The value should be an integer ([1, N]).
Note
Out port number is the 1-based index of the specified out port on the Task. For example, if the specified out port is the second out port of the Task from left to right, the out port number is 2.
Data Returned¶
203, status code
Status code
If there is no error, status code 2105 will be returned. Otherwise, the corresponding error code will be returned.
Test Samples¶
Command 203 is executed normally without errors.
TOP send string = 203, 1, 1
TCP received string = 203, 2105
Error: invalid out port number.
TCP send string = 203, 1, 3
TCP received string = 203, 2018, 1
Command 204: Set Move Index¶
This command is for setting the index parameter of a Task that involves sequential or separate motions or operations.
Tasks with index parameters include move_list, move_grid, custom_pallet_pattern, smart_pallet_pattern, etc.
Before executing this command, command 201 needs to be executed to start the Mech-Viz project.
Command Sent¶
204, Task name, index value
Task name
This parameter specifies which Task the index setting should apply to.
The value should be an integer ([1, N]), and the Task that needs index parameter setting by this command should be named as an integer ([1, N]). The name should be unique in the project.
Index value
The index parameter of the specified Task will be set to this value.
Data Returned¶
204, status code
Status code
If there is no error, status code 2106 will be returned. Otherwise, the corresponding error code will be returned.
Test Samples¶
Command 204 is executed normally without errors.
TCP send string = 204, 2, 6
TCP received string = 204, 2106
Error: Failed to set the index.
TCP send string = 204, 3, 6
TCP received string = 204, 2028, 1
Command 205: Get Planned Path¶
This command gets the robot motion path planned by Mech-Viz after command 201 is executed to start the Mech-Viz project.
Note
InTCP/IP, by default, command 205 can only fetch at most 20 target points of the planned path at a time. So, command 205 may need to be executed repeatedly until all the target points required are obtained.
Note
If one of the target points in the path is not supposed to be sent to the robot, please rename the corresponding move Task by adding “_internal” to the end of the name (with an underscore; case insensitive).
Command Sent¶
205, target point type
Target point type
This parameter specifies the type of path target points to return from Mech-Viz.
1The target points returned should be in JPS.
2The target points returned should be in TCP.
Data Returned¶
205, status code, sending completion status, number of points, position of "visual_move", target point, target point, ...
Status code
If there is no error, status code 2100 will be returned. Otherwise, the corresponding error code will be returned.
Note
When executing this command, if Mech-Viz has not yet had the planned robot motion path (the project is still running), Mech-Center will wait. The default wait time is 10 seconds. If a timeout occurs, a timeout error code will be returned.
Sending completion status
0Not all the target points of the planned path have been obtained. Please repeat executing this command until this parameter’s value is 1.
1All the target points of the planned path have been obtained.
Note
If the expected number of target points to transmit is greater than 20 (20 is the default setting), please execute command 205 multiple times until the returned value of this parameter is 1.
Number of points
This parameter indicates the number of path target points ([pose, label, velocity]) sent by executing this command this time.
Range: 0 to 20.
Position of “visual_move”
The position of the visual_move Task, i.e., the move to the vision pose (usually the pose for picking the object) in the entire robot motion path.
For example, if the path is composed of Tasks move_1, move_2, visual_move, move_3 sequentially, the position of visual_move is 3.
If in the path there is no visual_move Task, the returned value will be 0.
Target point
[pose, label, velocity]
Pose
Cartesian coordinates (XYZ) and Euler angles (ABC), or JPS, according to the pose type set by command 205.
Label
Label is the integer label assigned to the pose. If in the Mech-Vision project, the labels are strings, they need to be mapped to integers before outputting from the Mech-Vision project. If there are no labels in the Mech-Vision project, the label defaults to 0.
Velocity
The non-zero velocity parameter percentage value for the move Task set in Mech-Viz.
Test Samples¶
Command 205 is normally executed without error.
TCP send string = 205, 1
TCP received string =205, 2100, 1. 2, 2, 8.307755332057372, 15.163476541700463, -142.1778810972881, -2.7756047848536745, -31.44046012182799, -96.94907235126934, 0, 64, 8.2 42574265592342, 12.130080796661591, -141.75872288706663-2.513533225987894, -34.8905853 039525, -97.19108378871277, 0, 32
Error: Mech-Vision runtime error.
TCP send string = 205, 1
TCP received string = 205, 2008, 1
Command 206: Get DO List¶
This command gets the planned DO signal list when there are multiple grippers, such as suction cup sections, to control.
For using this command:
The Mech-Viz project’s name must be set to “suction_zone”.
The set_do_list Task must be named to “set_do_list_1”.
The set_do_list Task’s parameter “Get DO List from VisualMove” must be set to True.
The set_do_list Task must immediately follow a “visual_move” Task.
The name of the visual_move Task followed by the set_do_list Task must be selected in the lower part of the parameter panel of set_do_list.
Before calling this command, command 205 needs to be executed to obtain the planned motion path by Mech-Viz.
Please deploy the Mech-Viz project based on the template project at /Mech-Center/tool/viz_project/suction_zone, and set the suction cup configuration file in the Mech-Viz project.
Data Returned¶
206, status code, DO signal value, DO signal value, ..., DO signal value
Status code
If there are no errors, status code 2102 will be returned. Otherwise, the corresponding error code will be returned.
DO signal value
There are 64 DO signal values, in integers, located at the tail of the data returned.
Range of valid DO values: [0, 999]. Placeholder value: -1.
Test Samples¶
Command 206 is normally executed. The obtained DO signal values: 11, 12.
TCP send string: 206
TCP receive string: 206, 2102, 11, 12, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1
Error: Mech-Viz did not provide a valid DO signal list.
TCP send string: 206
TCP receive string: 206, 2011, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1
Command 501: Input Object Dimensions to Mech-Vision¶
This command is for dynamically inputting object dimensions into the Mech-Vision project.
Please confirm the actual object dimensions before running the Mech-Vision project.
The Mech-Vision project should have the Read Object Dimensions Step, and the Step’s parameter Read Object Dimensions from Parameters should be set to True.
Command Sent¶
501, project number, length, height, width
Project number
The integer ID number of the Mech-Vision project in Mech-Center, i.e., the number shown on the left of the project path in in Mech-Center.
Length, height, width
The object dimensions to input to the Mech-Vision project.
These values will be read by the Read Object Dimensions Step.
Unit: mm
Data Returned¶
501, status code
Status code
If there is no error, status code 1108 will be returned. Otherwise, the corresponding error code will be returned.
Test Samples¶
Command 501 is normally executed without errors.
TCP send string: 501, 1, 100, 200, 300
TCP receive string: 501, 1108
Error: Error code 3002, missing height value.
TCP send string: 501, 1, 100, 200
TCP receive string: 501, 3002
Command 502: Input TCP to Mech-Viz¶
This command is for dynamically inputting robot TCP into the Mech-Viz project.
The Task that receives the robot TCP is outer_move.
Please deploy the Mech-Viz project based on the template project at /Mech-Center/tool/viz_project/outer_move, and put the outer_move Task to a proper position in the workflow.
This command needs to be executed before executing command 201.
Command Sent¶
502, TCP
Data Returned¶
502, status code
Status code
If there is no error, status code 2107 will be returned. Otherwise, the corresponding error code will be returned.
Test Samples¶
Command 502 is normally executed without errors.
TCP send string: 502, 0, 10, 10, 20, 0, 0
TCP received string: 502, 2107
Command 601: Notify¶
The user does not need to initiate this command.
When the Mech-Viz/Mech-Vision project runs to the Notify Task/Step, Mech-Center will send the custom notification message defined in the Notify Task/Step.
The Notify Task/Step must be named “Standard Interface Notify”.
Command Sent¶
None
Data Returned¶
601, custom notification message
Custom notification message
The notification message defined in the Notify Task/Step. The message must be an integer.
Test Sample¶
When the notification message defined in the Notify Task/Step is set to integer 1000, the project will return 1000 when running through the Notify Task/Step.
TCP receive string = 601, 1000
Command 701: Calibration¶
This command is for hand-eye calibration (camera extrinsic parameter calibration).
This command syncs the calibration status with Mech-Vision and fetches each calibration point that the robot needs to reach.
This command needs to be executed multiple times to complete the calibration.
Command Sent¶
701, calibration status, flange pose, JPS
Calibration status
0Tell Mech-Vision to initiate the calibration.
1The previous calibration point has been received by the robot.
2The previous calibration point failed to be received by the robot.
Flange pose
The current flange pose of the robot.
JPS
The current JPS of the robot.
Data Returned¶
701, status code, calibration status, next calibration point's flange pose, next calibration point's JPS
Status code
This status code is for indicating the status of receiving the calibration point. If the calibration point is transmitted normally, status code 7101 will be returned. Otherwise, the corresponding error code will be returned.
Calibration status
1Calibration is in progress.
0Calibration finished.
Next calibration point’s flange pose
The flange pose of the next calibration point the robot should move to.
Next calibration point’s JPS
The JPS of the next calibration point the robot should move to.
Test Samples¶
Initiate the calibration.
TCP send string = 701, 0, 1371.62147, 25.6, 1334.3529, 148.58471, -179.24347, 88.75702, 88.86102, -7.11107, -28.82309, -0.44014, -67.6509, 31.4764
TCP received string = 701, 7101, 0, 1271.6969, -743374, 1334.34094, -3128422, 1792412, -91.11236, 93.28109, -12.0273, -32.8811, -0.37183, -68.41364, 27.02411
Obtain the calibration point (this process needs to be repeated to obtain multiple calibration points).
TCP send string = 701, 1, 1271.6969. -74.3374. 1334.34094. -3128422, 1792412 -91.11236, 93.28109, -12.0273, -32.8811, -0.37183, -68.41364, 27.02411
TCP received string = 701, 7101, 0, 1471.62226, -74.40452, 1334.34235. 148.56924, -179.24432, 88.74148, 92.8367, -2.14999, -24.25433, -0.39222, -67.23261, 27.485225
Finish the calibration.
TCP send string = 701, 1, 1371.60876, 25.53615, 1384.45532. -20.82704. 179.22026, -72.77879, 88.88467, -7.42242.-26.68142, -0.2991, -69.95593, 39.26262
TCP received string = 701 7101, 1, 1371.62147.25.6, 1334.3529. 148, 58471. -179 24347, 88.75702, 88.86102, -7.11107, -28.82309. -0.44014, -67.6509, 31.4764
Command 901: Get Software Status¶
This command is designed for checking the software running status of Mech-Vision, Mech-Viz, and Mech-Center. At present, this command only supports checking whether Mech-Vision is ready for running the project.
Test Samples¶
Mech-Vision is ready for running the project.
TCP send string = 901
TCP received string = 901, 1101
Mech-Vision is not ready for running the project. Please open the project in Mech-Vision, right-click on the project in Projects List, and check Autoload Project.
TCP send string = 901
TCP received string = 901, 1001, 1