AUBO (ARCS) Standard Interface Commands
This section describes standard interface commands used in TCP communications between a AUBO (ARCS) robot and Mech-Mind Vision System. The robot (the client) sends commands to Mech-Mind Vision System (the server), and Mech-Mind Vision System returns the processed data to the robot.
Command Overview
Commands related to Mech-Vision |
Commands related to Mech-Viz |
|
Establish TCP Communication Connection |
Establish TCP Communication Connection |
Precautions
-
Notes for AUBO (ARCS) robot commands:
-
g_mm_statusis a global variable used to store the command execution status code. After calling a command, you can check its value to determine whether the command succeeds or to handle exceptions. -
For the command names described below, the name outside the parentheses is the short name and the name inside the parentheses is the full name. For example, in
initSocket(mm_init_socket),initSocketis the short name andmm_init_socketis the full name.
-
-
Unit of data:
-
The unit of joint positions is degree (°).
-
A robot’s flange pose or TCP consists of the position and pose. The position is represented in XYZ coordinates and is measured in millimeters (mm); the pose is represented in Euler angles and is measured in degrees (°).
-
-
Vision point and waypoint:
-
Vision point: An object recognized by Mech-Vision. A vision point has information including the object pose, label, dimensions, and custom data.
-
Waypoint: Each point that the robot reaches when moving along the planned path. A waypoint has information including the robot pose, label, and motion type. Waypoints can be divided into two categories:
-
Vision Move waypoint: Waypoint corresponding to the Vision Move Step.
-
Non-Vision Move waypoints, which refer to the waypoints corresponding to Move-type Steps other than the Vision Move Step.
-
-
Communication Initialization
Function Description
This command is used to set the IPC IP address and port number for communication with the robot.
Calling Sequence
-
This command must be called in Add before start.
-
After calling this command, you must call openSkt to establish a TCP communication connection between the robot and the vision system.
Command Name
initSocket(mm_init_socket)Input Parameters
IP
This parameter is the IP address of the IPC and is represented as a string.
Port
This parameter indicates the port number used for communication between the IPC and the robot. Its value must be consistent with the host port number set in Robot Communication Configuration in the toolbar of Mech-Vision.
TimeOut
This parameter indicates the communication timeout. It is a built-in parameter and does not need to be configured manually.
Establish TCP Communication Connection
This command is used to establish the TCP communication connection between the robot and the vision system.
Calling Sequence
This command must be called after initSocket.
Close TCP Communication Connection
This command is used to disconnect the TCP communication connection between the robot and the vision system.
Run Mech-Vision Project
Function Description
This command is used to trigger the Mech-Vision project to run. While the Mech-Vision project is running, the vision system captures images and performs a series of vision algorithms on the image data, finally obtaining a series of vision points or path points.
|
Calling Sequence
-
Step parameters in the project need to be set before the Mech-Vision project runs. Therefore, addFunc (select
mm_set_model) or addFunc (selectmm_set_boxsize) must be called before startVis. -
The vision system obtains vision points or path points only after the Mech-Vision project runs. Therefore, startVis must be called before getData.
Command Name
startVis(mm_start_vision)Input Parameters
Project ID
Mech-Vision project ID. You can view the project ID of a Mech-Vision project in the Project List section of Mech-Vision. The project ID is the number before the project name.
PosNumberNeed
This parameter indicates the number of vision points or path points expected from the Mech-Vision project. The value can be 0 or a positive integer.
| If the Mech-Vision project contains a Path Planning Step, this parameter indicates the expected number of path points. Otherwise, it indicates the expected number of vision points. |
-
0: Obtain all vision points or path points from the Mech-Vision project. -
Positive integer: Obtain the specified number of vision points or path points from the Mech-Vision project.
-
If the total number of output vision points or path points is smaller than the specified value, all output vision points or path points are obtained.
-
If the total number of output vision points or path points is greater than or equal to the specified value, the specified number of vision points or path points is obtained.
-
|
Type of robot pose to send
This parameter specifies how the pose of the real robot is passed into the Mech-Vision project. Valid values are None, Current Position, Current Flange Pose, and Predefined Jps, as shown below.
| Type of robot pose to send | Description | Applicable scenario |
|---|---|---|
None |
This command does not need to pass the robot pose into the Mech-Vision project. If the Mech-Vision project uses a Path Planning Step, the start point of path planning is the Home point set in the path-planning tool. |
Use this setting when the camera is mounted in Eye To Hand mode and the project does not require image capture in advance. |
Current Position |
This command passes the robot’s current joint positions and flange pose into the Mech-Vision project. |
This setting must be used when the camera is mounted in Eye In Hand mode. This setting is recommended for most scenarios except those using gantry robots. |
Current Flange Pose |
This command passes the robot’s current flange pose into the Mech-Vision project. |
This setting is recommended when a gantry robot is used. |
Predefined Jps |
This command passes user-defined joint positions into the Mech-Vision project. These joint positions are sent to the Path Planning Step in Mech-Vision as the start point, that is, the robot moves from this start point to the first planned path point. |
Use this setting when the camera is mounted in Eye To Hand mode and the project requires image capture in advance. |
Predefined Jps
This parameter indicates user-defined joint-position data.
-
If the value of Type of robot pose to send is Predefined Jps, these joint positions are sent to the Path Planning Step in Mech-Vision as the start point.
-
If the value of Type of robot pose to send is not Predefined Jps,
Predefined Jpsis filled with a default value automatically and does not need to be set manually.
Get Data
Command Name
getData(mm_get_data)Parameter Description
None (Do not obtain data)
This option means that no data output by Mech-Vision or Mech-Viz is obtained.
From Vision (Obtain data output by Mech-Vision)
mm_get_vis_data (Obtain vision results)
Description
Selecting mm_get_vis_data means obtaining the vision results output by Mech-Vision (a series of vision points), including the pose, label, and end tool of each vision point. The object pose of a vision point, namely the poses port data of the Output Step, is automatically converted by the vision system into the corresponding robot tool pose, as shown below.
| If the first input port of the Output Step is Object Center Point, the Output Step converts the Object Center Point into the corresponding Pick Point. Therefore, the pose obtained through this command is actually the pose of the pick point rather than the pose of the object center point. |
-
Convert the object pose from a quaternion to Euler angles.
-
Rotate the object’s pose around the X-axis by 180° to orient its Z-axis downward.
Calling sequence
The execution result of this command is temporarily stored in robot memory. You must then call getPosejps (select mm_get_pos) to transfer the data before it can be accessed.
Input parameters
- Project ID
-
Mech-Vision project ID. You can view the project ID of a Mech-Vision project in the Project List section of Mech-Vision. The project ID is the number before the project name.
Output parameters
- Pose Num
-
This parameter specifies a variable name used to store the number of vision points returned by Mech-Vision.
- g_mm_status
-
This parameter stores the command execution status code. If the command executes normally, the status code is 1100. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.
mm_get_dy_data (Obtain custom data from Mech-Vision)
Description
Selecting mm_get_dy_data means that, in addition to the pose and label of a vision point, custom-port data of the Output Step is also obtained.
Select the Output Step, set Port Type to Custom, and then click Open the editor to go to the custom port configuration window. The Customized Keys section of the window displays custom port names, such as customeData1 and customeData2 as shown in the following figure.
|
Calling sequence
The execution result of this command is temporarily stored in robot memory. You must then call getPosejps (select mm_get_dypos) to transfer the data before it can be accessed.
Input parameters
- Project ID
-
Mech-Vision project ID. You can view the project ID of a Mech-Vision project in the Project List section of Mech-Vision. The project ID is the number before the project name.
Output parameters
- Pose Num
-
This parameter specifies a variable name used to store the number of vision points returned by Mech-Vision.
- g_mm_status
-
This parameter stores the command execution status code. If the command executes normally, the status code is 1100. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.
mm_get_vis_path (Obtain the path planned by Mech-Vision)
Description
Selecting mm_get_vis_path means obtaining the path planned by Mech-Vision (a series of path points), including the pose, label, and end tool of each path point. This path is planned by the Path Planning Tool entered from the Configuration Wizard shown below. For details about the Path Planning Step, refer to Path Planning.
| The Port Type parameter of the Output Step in Mech-Vision must be set to Predefined (Robot Path). |
Calling sequence
The execution result of this command is temporarily stored in robot memory. You must then call getPosejps to transfer the data before it can be accessed. Choose one of the following parameters according to the pose form:
-
mm_get_pos: The pose form is tool pose. -
mm_get_jps: The pose form is joint positions.
Input parameters
- Project ID
-
Mech-Vision project ID. You can view the project ID of a Mech-Vision project in the Project List section of Mech-Vision. The project ID is the number before the project name.
- Pose Type
-
This parameter specifies the pose form of the path points to obtain. The value is 1 or 2.
-
1: Joint positions. -
2: Tool pose.
-
Output parameters
- Pose Num
-
This parameter specifies a variable name used to store the number of path points returned by Mech-Vision.
- Vision Pose Index
-
This parameter specifies a variable name used to store the position index of the path point corresponding to the Vision Move Step in the Path Planning Tool. If there is no Vision Move path point in the path, the variable value is 0.
For example, if the planned path consists of the following path points:
Fixed-Point Move_1,Fixed-Point Move_2,Vision Move, andFixed-Point Move_3, the position index of the Vision Move path point is 3. - g_mm_status
-
This parameter stores the command execution status code. If the command executes normally, the status code is 1103. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.
mm_get_plan_data (Obtain Vision Move planning data from Mech-Vision)
Description
Selecting mm_get_plan_data means that, in addition to the path planned by Mech-Vision, Vision Move planning data is also obtained. Here, Vision Move planning data refers to the data planned by the Vision Move Step in the Path Planning Tool, including the label of the picked workpiece, the total number of picked workpieces, the number of workpieces picked this time, suction-cup corner ID, TCP offset, workpiece-group orientation, single-workpiece orientation, and workpiece-group dimensions.
Calling sequence
The execution result of this command is temporarily stored in robot memory. You must then call getPosejps (select mm_get_plan_pos) to transfer the data before it can be accessed.
Input parameters
- Project ID
-
Mech-Vision project ID. You can view the project ID of a Mech-Vision project in the Project List section of Mech-Vision. The project ID is the number before the project name.
- Pose Type
-
This parameter specifies the pose form of the path points to obtain. The value is 1 or 2.
-
1: Joint positions. -
2: Tool pose.
-
Output parameters
- Pose Num
-
This parameter specifies a variable name used to store the number of path points returned by Mech-Vision.
- Vision Pose Index
-
This parameter specifies a variable name used to store the position index of the path point corresponding to the Vision Move Step in the Path Planning Tool. If there is no Vision Move path point in the path, the variable value is 0.
For example, if the planned path consists of the following path points:
Fixed-Point Move_1,Fixed-Point Move_2,Vision Move, andFixed-Point Move_3, the position index of the Vision Move path point is 3. - g_mm_status
-
This parameter stores the command execution status code. If the command executes normally, the status code is 1103. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.
From Viz (Obtain data output by Mech-Viz)
mm_get_viz_data (Obtain the path planned by Mech-Viz)
Description
Selecting mm_get_viz_data means obtaining the motion path planned by Mech-Viz (a series of path points), including the pose, label, and end tool of each path point.
Calling sequence
The execution result of this command is temporarily stored in robot memory. You must then call getPosejps to transfer the data before it can be accessed. Choose one of the following parameters according to the pose form:
-
mm_get_pos: The pose form is tool pose. -
mm_get_jps: The pose form is joint positions.
Input parameters
- Pose Type
-
This parameter specifies the pose form of the path points to obtain. The value is 1 or 2.
-
1: Joint positions. -
2: Tool pose.
-
Output parameters
- Pose Num
-
This parameter specifies a variable name used to store the number of path points returned by Mech-Viz.
- Vision Pose Index
-
This parameter specifies a variable name used to store the position index of the path point corresponding to the Vision Move Step in the Mech-Viz project. If there is no Vision Move path point in the path, the variable value is 0.
For example, if the planned path consists of the following path points:
Fixed-Point Move_1,Fixed-Point Move_2,Vision Move, andFixed-Point Move_3, the position index of the Vision Move path point is 3. - g_mm_status
-
This parameter stores the command execution status code. If the command executes normally, the status code is 2100. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.
mm_get_plan_data (Obtain the path planned by Mech-Viz, Vision Move planning data, or custom data)
Description
Selecting mm_get_plan_data means that, in addition to the path planned by Mech-Viz, Vision Move planning data or custom data is also obtained.
-
Vision Move planning data: Data planned by the Vision Move Step in Mech-Viz, including the label of the picked workpiece, the total number of picked workpieces, the number of workpieces picked this time, suction-cup corner ID, TCP offset, workpiece-group orientation, single-workpiece orientation, and workpiece-group dimensions.
-
Custom data: Data output by custom ports in Mech-Vision and then forwarded by Mech-Viz.
Select the Output Step, set Port Type to Custom, and then click Open the editor to go to the custom port configuration window. The Customized Keys section of the window displays custom port names, such as customeData1 and customeData2 as shown in the following figure.
-
Data output from Predefined Keys, such as poses, labels, sizes, offsets, is not custom data.
-
You must set Port Type of the Output Step to Custom and select the poses port in the Predefined Keys section in Mech-Vision.
-
Calling sequence
The execution result of this command is temporarily stored in robot memory. You must then call getPosejps to transfer the data before it can be accessed. Choose one of the following parameters according to the pose form:
-
mm_get_plan_pos: The pose form is tool pose. -
mm_get_plan_jps: The pose form is joint positions.
Input parameters
- Project ID
-
This parameter must be set to 0.
- Pose Type
-
This parameter specifies the data format returned by Mech-Viz. The value is 1, 2, 3, or 4.
Pose Type
Description of returned data (see below for details of each field; if the Mech-Vision project has no custom ports, there is no Custom Data Item)
Path-point type
Data information
1
Non-Vision Move path point
Pose (joint positions), move type, end-tool ID, speed
Vision Move path point
Pose (joint positions), move type, end-tool ID, speed, custom data item 1, …, custom data item N
2
Non-Vision Move path point
Pose (tool pose), move type, end-tool ID, speed
Vision Move path point
Pose (tool pose), move type, end-tool ID, speed, custom data item 1, …, custom data item N
3
Non-Vision Move path point
Pose (joint positions), move type, end-tool ID, speed
Vision Move path point
Pose (joint positions), move type, end-tool ID, speed, Vision Move planning data, custom data item 1, …, custom data item N
4
Non-Vision Move path point
Pose (tool pose), move type, end-tool ID, speed
Vision Move path point
Pose (tool pose), move type, end-tool ID, speed, Vision Move planning data, custom data item 1, …, custom data item N
- Pose
-
The pose of a path point can be robot joint positions or tool pose, depending on the value of the Pose Type parameter specified when the command is sent.
- Move type
-
-
1: Joint motion. -
2: Linear motion.
-
- End-tool ID
-
The end-tool ID of a path point. If the value is -1, no end tool is used.
- Speed
-
The speed parameter of the move-type step multiplied by the global speed set in Mech-Viz, expressed as a percentage.
- Vision Move planning data
-
Data planned by the Vision Move Step in Mech-Viz, including the label of the picked workpiece, the total number of picked workpieces, the number of workpieces picked this time, suction-cup corner ID, TCP offset, workpiece-group orientation, single-workpiece orientation, and workpiece-group dimensions.
Name Description Dimension Label of the picked workpiece
Composed of 10 integers and defaults to 10 zeros
10
Total number of picked workpieces
Cumulative number of picked workpieces
1
Number of workpieces picked this time
Number of workpieces picked this time
1
Suction-cup corner ID
Corner ID used by the suction cup this time
1
TCP offset
XYZ offset of the center of the workpiece group relative to the center of the end tool
3
Workpiece-group orientation
Orientation relationship between the workpiece group and the long side of the suction cup. 0 means parallel and 1 means perpendicular.
1
Single-workpiece orientation
Orientation relationship between the long side of a single workpiece and the long side of the suction cup. 0 means parallel and 1 means perpendicular.
1
Workpiece-group dimensions
Length, width, and height of the workpiece group picked this time
3
- Custom Data Item
-
All custom-port data of a single path point. For example, if the data of each port in the Output Step is as shown in the table below, the Custom Data Items of the first path point are
[0,0,1]and[0,0], and the Custom Data Items of the second path point are[1,0,0]and[1,1].Port Name
poses
labels
customData1
customData2
Port Data
[
[0, 0, 0, 1, 0, 0, 0],
[0, 0, 0, 1, 0, 0, 0]
]
[
"0",
"1"
]
[
[0, 0, 1],
[1, 0, 0]
]
[
[0, 0],
[1, 1]
]
First path point
[0, 0, 0, 1, 0, 0, 0]
0
[0, 0, 1]
[0, 0]
Second path point
[0, 0, 0, 1, 0, 0, 0]
1
[1, 0, 0]
[1, 1]
Output parameters
- Pose Num
-
This parameter specifies a variable name used to store the number of path points returned by Mech-Viz.
- Vision Pose Index
-
This parameter specifies a variable name used to store the position index of the path point corresponding to the Vision Move Step in the Mech-Viz project. If there is no Vision Move path point in the path, the variable value is 0.
For example, if the planned path consists of the following path points:
Fixed-Point Move_1,Fixed-Point Move_2,Vision Move, andFixed-Point Move_3, the position index of the Vision Move path point is 3. - g_mm_status
-
This parameter stores the command execution status code. If the command executes normally, the status code is 2100. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.
Transfer Data
Function Description
This command is used to save data related to a vision point or path point into specified variables.
Calling Sequence
This command must be called after getData.
Command Name
getPosejps(mm_get_posjps)Parameter Description
None (Do not transfer data)
This option means that no data is transferred.
mm_get_pos (Transfer vision result or planned path in tool-pose form)
Description
Selecting mm_get_pos means transferring the tool pose, label, and end-tool ID of a vision point or path point to specified variables.
Input parameters
- Index
-
This parameter specifies the index of a vision point or path point. The tool pose, label, and end-tool ID of the corresponding vision point or path point are transferred to specified variables. Indexes start from 1.
Output parameters
- Pose
-
This parameter specifies a variable name used to store the tool pose of the vision point or path point corresponding to the specified index.
- Tool ID
-
This parameter specifies a variable name used to store the end-tool ID of the vision point or path point corresponding to the specified index.
- Label
-
This parameter specifies a variable name used to store the label of the vision point or path point corresponding to the specified index.
mm_get_jps (Transfer planned path in joint-position form)
Description
Selecting mm_get_jps means transferring the joint positions, label, and end-tool ID of a path point to specified variables.
Input parameters
- Index
-
This parameter specifies the index of a path point. The joint positions, label, and end-tool ID of the corresponding path point are transferred to specified variables. Indexes start from 1.
Output parameters
- Jps
-
This parameter specifies a variable name used to store the joint positions of the path point corresponding to the specified index.
- Tool ID
-
This parameter specifies a variable name used to store the end-tool ID of the path point corresponding to the specified index.
- Label
-
This parameter specifies a variable name used to store the label of the path point corresponding to the specified index.
mm_get_dypos (Transfer custom data from Mech-Vision)
Description
Selecting mm_get_dypos means transferring the tool pose, label, and custom data of a vision point to specified variables.
Input parameters
- Index
-
This parameter specifies the index of a vision point. The custom data of the corresponding vision point is transferred to specified variables. Indexes start from 1.
Output parameters
- Pose
-
This parameter specifies a variable name used to store the tool pose of the vision point corresponding to the specified index.
- Label
-
This parameter specifies a variable name used to store the label of the vision point corresponding to the specified index. If there is no label information, the label value defaults to 0.
- Custom Data
-
This parameter specifies a variable name used to store the custom data of the vision point corresponding to the specified index. For example, if the data of each port in the Output Step is as shown below, the Custom Data Items of the first vision point are
[0,0,1]and[0,0], and the Custom Data Items of the second vision point are[1,0,0]and[1,1].Port Name
poses
labels
customData1
customData2
Port Data
[
[0, 0, 0, 1, 0, 0, 0],
[0, 0, 0, 1, 0, 0, 0]
]
[
"0",
"1"
]
[
[0, 0, 1],
[1, 0, 0]
]
[
[0, 0],
[1, 1]
]
First vision point
[0, 0, 0, 1, 0, 0, 0]
0
[0, 0, 1]
[0, 0]
Second vision point
[0, 0, 0, 1, 0, 0, 0]
1
[1, 0, 0]
[1, 1]
mm_get_plan_pos (Transfer Vision Move planning data in tool-pose form)
Description
Selecting mm_get_plan_pos means transferring the tool pose, move type, end-tool ID, speed, custom data, and Vision Move planning data of a path point to specified variables.
Input parameters
- Index
-
This parameter specifies the index of a path point. The tool pose, move type, end-tool ID, speed, custom data, and Vision Move planning data of the corresponding path point are transferred to specified variables. Indexes start from 1.
Output parameters
- Pose
-
This parameter specifies a variable name used to store the tool pose of the path point corresponding to the specified index.
- Move Type
-
This parameter specifies a variable name used to store the move type of the path point corresponding to the specified index. The value is 1 or 2.
-
1: Joint motion. -
2: Linear motion.
-
- Tool ID
-
This parameter specifies a variable name used to store the end-tool ID of the path point corresponding to the specified index. If the value is -1, no end tool is used.
- Speed
-
This parameter specifies a variable name used to store the speed of the path point corresponding to the specified index. The meaning of speed depends on the project type, as follows.
-
For a Mech-Vision project: speed refers to the simulation speed set in the path-planning tool and is expressed as a percentage.
-
For a Mech-Viz project: speed refers to the speed parameter set in a move-type step multiplied by the global speed set in Mech-Viz, expressed as a percentage.
-
- Custom Data
-
This parameter specifies a variable name used to store the custom data of the path point corresponding to the specified index. For example, if the data of each port in the Output Step is as shown below, the Custom Data Items of the first path point are
[0,0,1]and[0,0], and the Custom Data Items of the second path point are[1,0,0]and[1,1].Port Name
poses
labels
customData1
customData2
Port Data
[
[0, 0, 0, 1, 0, 0, 0],
[0, 0, 0, 1, 0, 0, 0]
]
[
"0",
"1"
]
[
[0, 0, 1],
[1, 0, 0]
]
[
[0, 0],
[1, 1]
]
First path point
[0, 0, 0, 1, 0, 0, 0]
0
[0, 0, 1]
[0, 0]
Second path point
[0, 0, 0, 1, 0, 0, 0]
1
[1, 0, 0]
[1, 1]
- Plan Data
-
This parameter specifies a variable name used to store the Vision Move planning data of the path point corresponding to the specified index. Detailed Vision Move planning data is shown in the following table.
Name Description Dimension Label of the picked workpiece
Composed of 10 integers and defaults to 10 zeros
10
Total number of picked workpieces
Cumulative number of picked workpieces
1
Number of workpieces picked this time
Number of workpieces picked this time
1
Suction-cup corner ID
Corner ID used by the suction cup this time
1
TCP offset
XYZ offset of the center of the workpiece group relative to the center of the end tool
3
Workpiece-group orientation
Orientation relationship between the workpiece group and the long side of the suction cup. 0 means parallel and 1 means perpendicular.
1
Single-workpiece orientation
Orientation relationship between the long side of a single workpiece and the long side of the suction cup. 0 means parallel and 1 means perpendicular.
1
Workpiece-group dimensions
Length, width, and height of the workpiece group picked this time
3
mm_get_plan_jps (Transfer Vision Move planning data in joint-position form)
Description
Selecting mm_get_plan_jps means transferring the joint positions, move type, end-tool ID, speed, custom data, and Vision Move planning data of a path point to specified variables.
Input parameters
- Index
-
This parameter specifies the index of a path point. The joint positions, move type, end-tool ID, speed, custom data, and Vision Move planning data of the corresponding path point are transferred to specified variables. Indexes start from 1.
Output parameters
- Pose
-
This parameter specifies a variable name used to store the joint positions of the path point corresponding to the specified index.
- Move Type
-
This parameter specifies a variable name used to store the move type of the path point corresponding to the specified index. The value is 1 or 2.
-
1: Joint motion. -
2: Linear motion.
-
- Tool ID
-
This parameter specifies a variable name used to store the end-tool ID of the path point corresponding to the specified index. If the value is -1, no end tool is used.
- Speed
-
This parameter specifies a variable name used to store the speed of the path point corresponding to the specified index. The meaning of speed depends on the project type, as follows.
-
For a Mech-Vision project: speed refers to the simulation speed set in the path-planning tool and is expressed as a percentage.
-
For a Mech-Viz project: speed refers to the speed parameter set in a move-type step multiplied by the global speed set in Mech-Viz, expressed as a percentage.
-
- Custom Data
-
This parameter specifies a variable name used to store the custom data of the path point corresponding to the specified index. For example, if the data of each port in the Output Step is as shown below, the Custom Data Items of the first path point are
[0,0,1]and[0,0], and the Custom Data Items of the second path point are[1,0,0]and[1,1].Port Name
poses
labels
customData1
customData2
Port Data
[
[0, 0, 0, 1, 0, 0, 0],
[0, 0, 0, 1, 0, 0, 0]
]
[
"0",
"1"
]
[
[0, 0, 1],
[1, 0, 0]
]
[
[0, 0],
[1, 1]
]
First path point
[0, 0, 0, 1, 0, 0, 0]
0
[0, 0, 1]
[0, 0]
Second path point
[0, 0, 0, 1, 0, 0, 0]
1
[1, 0, 0]
[1, 1]
- Plan Data
-
This parameter specifies a variable name used to store the Vision Move planning data of the path point corresponding to the specified index. Detailed Vision Move planning data is shown in the following table.
Name Description Dimension Label of the picked workpiece
Composed of 10 integers and defaults to 10 zeros
10
Total number of picked workpieces
Cumulative number of picked workpieces
1
Number of workpieces picked this time
Number of workpieces picked this time
1
Suction-cup corner ID
Corner ID used by the suction cup this time
1
TCP offset
XYZ offset of the center of the workpiece group relative to the center of the end tool
3
Workpiece-group orientation
Orientation relationship between the workpiece group and the long side of the suction cup. 0 means parallel and 1 means perpendicular.
1
Single-workpiece orientation
Orientation relationship between the long side of a single workpiece and the long side of the suction cup. 0 means parallel and 1 means perpendicular.
1
Workpiece-group dimensions
Length, width, and height of the workpiece group picked this time
3
Run Mech-Viz Project
Function Description
This command is used to trigger the Mech-Viz project to run. Mech-Viz plans the robot motion path based on the vision result output by Mech-Vision.
| In the Resource panel of the Mech-Viz project, right-click the project name and select Set to Auto Load. |
Calling Sequence
Step parameters in the project need to be set before the Mech-Viz project runs. Therefore, addFunc (select mm_set_property) or addFunc (select mm_get_property) must be called before startViz.
Command Name
startViz(mm_start_viz)Input Parameters
Type of robot pose to send
This parameter specifies how the pose of the real robot is passed into the Mech-Viz project. Valid values are None, Current Position, or Predefined Jps.
| Type of robot pose to send | Description | Applicable scenario |
|---|---|---|
None |
This command does not need to pass the robot pose into the Mech-Viz project. The simulated robot in Mech-Viz moves from the configured Home point to the first path point. |
The camera is mounted in Eye To Hand mode. |
Current Position |
This command passes the robot’s current joint positions and flange pose into the Mech-Viz project. The simulated robot in Mech-Viz moves from the passed joint positions to the first path point. |
The camera is mounted in Eye In Hand mode. This setting is recommended. |
Predefined Jps |
This command passes a taught point of the robot, namely custom joint positions rather than the current joint positions, into the Mech-Viz project. This is used to trigger the next round of path planning in advance when the robot is outside the image-capturing area. The simulated robot in Mech-Viz moves from the passed taught point to the first path point. |
The camera is mounted in Eye To Hand mode. This setting is recommended. |
Predefined Jps
This parameter indicates user-defined joint-position data.
-
If the value of Type of robot pose to send is Predefined Jps, these joint positions are sent to the Mech-Viz project as the start point.
-
If the value of Type of robot pose to send is not Predefined Jps,
Predefined Jpsis filled with a default value automatically and does not need to be set manually.
Stop Mech-Viz Project
Output Parameters
g_mm_status
This parameter stores the command execution status code. If the command executes normally, the status code is 2104. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.
Additional Functions
Command Name
addFunc(mm_additional_function)Parameter Description
None (Do not add functions)
This option means that no additional function is added.
mm_set_branch (Set the message-branch exit of Mech-Viz)
Description
Selecting mm_set_branch means setting the exit of a Message Branch Step in Mech-Viz. When the Mech-Viz project runs to the Message Branch Step, it waits for this command to specify the exit.
Calling sequence
This command must be called after startViz.
Input parameters
- Branch ID
-
This parameter specifies the step ID of the Message Branch Step. The value is a positive integer. The step ID can be viewed in step parameters. For example, the step ID in the figure above is 1.
- Branch Port
-
This parameter specifies the exit number of the Message Branch Step. The value is a positive integer. If this parameter is set to N, the Mech-Viz project continues from exit N-1 of the Message Branch Step.
mm_set_index (Set the current index of Mech-Viz)
Description
Selecting mm_set_index means setting the current index value of an index-type step in Mech-Viz. Index-type steps are steps that contain an Index parameter, such as Move by Array, Move by Sequence, Custom Pallet Pattern, and Preset Pallet Pattern.
Calling sequence
Usually there is a Message Branch Step before an index-type step. On the robot side, first call startViz, then addFunc (select mm_set_index), and finally addFunc (select mm_set_branch). In this way, Mech-Viz has sufficient time to set the current index value.
Input parameters
- Skill Num
-
This parameter specifies the step ID of the index-type step. The value is a positive integer. The step ID can be viewed in step parameters. For example, the step ID in the figure above is 3.
- Index Num
-
This parameter specifies the current index value of the index-type step. The value is a positive integer. If this parameter is set to N, the current index value of the corresponding step is N-1.
mm_set_model (Switch the parameter recipe of Mech-Vision)
Description
Selecting mm_set_model means switching the parameter recipe used by a Mech-Vision project. The following figure shows manually switching recipe A or recipe B for a Mech-Vision project. For knowledge about parameter recipes, refer to Parameter Recipe.
Calling sequence
This command must be called before startVis.
Input parameters
- Project ID
-
Mech-Vision project ID. You can view the project ID of a Mech-Vision project in the Project List section of Mech-Vision. The project ID is the number before the project name.
- Model ID
-
This parameter indicates the parameter-recipe ID in the Mech-Vision project. For how to view the parameter-recipe ID, refer to View the Parameter Recipe ID.
mm_set_boxsize (Pass object dimensions into Mech-Vision)
Description
Selecting mm_set_boxsize means passing object dimensions into a Mech-Vision project. The passed dimensions are the values of the Box Dimension Settings parameter of the Read Object Dimensions Step, as shown below.
| When using this command, there can be only one Read Object Dimensions Step in the Mech-Vision project. Otherwise, the vision system returns an error. |
Calling sequence
This command must be called before startVis.
Input parameters
- Project ID
-
Mech-Vision project ID. You can view the project ID of a Mech-Vision project in the Project List section of Mech-Vision. The project ID is the number before the project name.
- Length, Width, Height
-
These three parameters indicate the object dimensions passed into the Mech-Vision project, namely length, width, and height in millimeters. The dimension values are read by the Read Object Dimensions Step and written into Length Along X-axis, Length Along Y-axis, and Length Along Z-axis respectively.
mm_set_property (Set step parameter values of Mech-Viz)
Description
Selecting mm_set_property means setting the parameter values of a specified step in the Mech-Viz project.
Calling sequence
This command must be called before startViz.
Input parameters
- ID
-
This parameter is the Configuration ID field specified in the
property_configfile.From the toolbar of Mech-Vision, go to . Click Property Configuration to open the property_config file.
Before sending this command, you should define a Config ID and its corresponding Step ID, parameter key name and parameter value in the following format in the property_config file.
write, Config ID, Step ID, parameter key name, parameter value
write
Indicates that this line is used to set the parameter value of a Step.
Config ID
Specifies an ID, which is a positive integer and can be used repeatedly.
Step ID
Specifies the Step whose parameter value the robot requires to read.
parameter key name
Specifies the key name of the parameter whose value the robot requires to set.
parameter value
Specifies the value that the robot sets for the parameter.
-
The property_config file can contain more than one “write” command, and these commands can use a Config ID repeatedly. That is, one Config ID can be used to set values for multiple parameters.
-
You can check the parameter key name in the Key Query Tool. In Mech-Viz, click File in the menu bar. In the lower-left corner, click Options. Click Developer mode, click OK, and then restart the software. In the menu bar of the software, select to open the tool. Click a Step icon, and all key names of the Step will be displayed in the middle column. Each key name corresponds to a Step parameter name displayed in the parameter panel. You can also click a key name and check its corresponding parameter name in the “Details” panel.
-
In the property_config file, lines starting with “#” are comments, which will not be executed by the program.
-
Remember to save the file after editing, and then restart the interface service on the toolbar of Mech-Vision.
-
Output parameters
- g_mm_status
-
This parameter stores the command execution status code. If the command executes normally, the status code is 2108. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.
mm_get_property (Read step parameter values of Mech-Viz)
Description
Selecting mm_get_property means reading the parameter values of a specified step in the Mech-Viz project.
Calling sequence
This command must be called before startViz.
Input parameters
- ID
-
This parameter is the Configuration ID field specified in the
property_configfile.From the toolbar of Mech-Vision, go to . Click Property Configuration to open the property_config file.
Before calling this function, you should define a Config ID and its corresponding Step ID and parameter key name in the following format in the property_config file.
read, Config ID, Step ID, parameter key name
read
Indicates that this line is used to read the parameter value of a Step.
Config ID
Specifies a unique ID, which is a positive integer. One Config ID corresponds to only one parameter value of a Step. To read multiple parameter values, you should set different Config IDs.
Step ID
The Step ID of the Step whose parameter is to be read.
parameter key name
Specifies the key name of the parameter whose value the robot requires to read.
-
You can check the parameter key name in the Key Query Tool. In Mech-Viz, click File in the menu bar. In the lower-left corner, click Options. Click Developer mode, click OK, and then restart the software. In the menu bar of the software, select to open the tool. Click a Step icon, and all key names of the Step will be displayed in the middle column. Each key name corresponds to a Step parameter name displayed in the parameter panel. You can also click a key name and check its corresponding parameter name in the “Details” panel.
-
In the property_config file, lines starting with “#” are comments, which will not be executed by the program.
-
Remember to save the file after editing, and then restart the interface service on the toolbar of Mech-Vision.
The property_config file can have multiple read commands. The Config ID in these commands must be different.
-
Output parameters
- dataValue
-
This parameter stores the returned parameter value of the specified step.
- g_mm_status
-
This parameter stores the command execution status code. If the command executes normally, the status code is 2109. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.
mm_get_notify (Obtain notification messages)
Description
Selecting mm_get_notify means obtaining a notification message. When a Mech-Vision or Mech-Viz project runs to a Notify Step, the vision system returns the message preset in that step.
Before using this command, the Notify Step must meet the following settings.
-
Notify Step in a Mech-Vision project
-
Connect the Notify Step to the right side of another step, using the Output Step as an example.
-
In the step parameters of the Output Step, select Trigger Control Flow When Output Exists.
-
In the step parameters of the Notify Step, set the service name to Standard Interface Notify and the message to 1001. The message can be adjusted according to actual needs, but it must be a positive integer.
-
-
Notify Step in a Mech-Viz project
-
Connect the Notify Step at an appropriate position in the workflow.
-
In the step parameters of the Notify Step, select Standard Interface and set the message to 1000. The message can be adjusted according to actual needs, but it must be a positive integer.
-
Calling sequence
Output parameters
- dataValue
-
This parameter stores the notification message and currently supports only positive integers.
mm_get_dolist (Obtain suction-cup DO signals)
Description
Selecting mm_get_dolist means obtaining the control signals of a multi-zone suction cup planned by Mech-Vision or Mech-Viz.
Before using this command, complete the following configuration in Mech-Vision or Mech-Viz.
-
Configure a Mech-Vision project
-
In the step parameters of Path Planning, click Configuration Wizard. In Global Settings, turn on Plan All Vision Results.
-
In the step parameters of Path Planning, click Configuration Wizard, double-click the end-tool name, select Depalletizing Suction Cup for Tool Type, click Depalletizing Suction Cup Configuration, and configure DO signals as required.
-
-
Configure a Mech-Viz project
-
In Mech-Viz, set Grasp Technique of the Vision Move Step to Box Depalletizing.
-
In Mech-Viz, double-click the end-tool name, select Depalletizing Suction Cup for Tool Type, click Depalletizing Suction Cup Configuration, and configure DO signals as required.
-
Calling sequence
This command must be called after getData. That is, the robot first obtains the motion path and then obtains the suction-cup DO signals corresponding to the Vision Move path point.
Input parameters
- Project ID
-
This parameter specifies the source of the DO signal list. The value is 0 or a positive integer.
-
0: Obtain the DO signal list from Mech-Viz. -
Positive integer: Obtain the DO signal list from Mech-Vision. The positive integer here is the Mech-Vision project ID.
-
- Block Num
-
This parameter is the number of suction-cup zones set in the Suction Cup Configurator. For example, the number of suction-cup zones in the preceding figure is 3.
Output parameters
- Do List
-
This parameter specifies a variable name used to store the obtained DO signals. Depending on the project type, the returned DO signals differ, as follows.
-
Suction-cup DO signals planned by a Mech-Vision project
-
If Plan All Vision Results is turned off in the global settings of path planning, this command returns 64 DO signals representing the suction-cup DO signals of the current planning cycle. Valid DO signals are non-negative integers in the range 0 to 999. Invalid DO signals are -1 placeholders.
For example, in the following table, the valid DO signals returned are 1, 3, 5, and 6, which means the robot needs to set the corresponding DO signals to ON.
1st
2nd
3rd
4th
5th
6th
7th
8th
…
63rd
64th
1
3
5
6
-1
-1
-1
-1
…
-1
-1
-
If Plan All Vision Results is turned on in the global settings of path planning, Mech-Vision can perform multiple rounds of planning based on the same vision result. The 64 DO signals returned by this command are the suction-cup DO signals of all planning rounds. In this case, use the number of suction-cup zones to distinguish the DO signals of each planning round.
For example, if the number of suction-cup zones is 4, this command returns 64 DO signals in total, where every 4 DO signals correspond to the multi-zone suction-cup control signals of one planning round.
Planning round 1
Planning round 2
…
Planning round 16
1st
2nd
3rd
4th
5th
6th
7th
8th
…
61st
62nd
63rd
64th
1
3
4
-1
1
4
-1
-1
…
-1
-1
-1
-1
-
-
Suction-cup DO signals planned by a Mech-Viz project
-
If Reuse Vision Results is not selected in the Vision Move Step, this command returns 64 DO signals representing the suction-cup DO signals of the current planning cycle. Valid DO signals are non-negative integers in the range 0 to 999, and invalid DO signals are -1 placeholders.
For example, in the following table, the valid DO signals returned are 1, 3, 5, and 6, which means the robot needs to set the corresponding DO signals to ON.
1st
2nd
3rd
4th
5th
6th
7th
8th
…
63rd
64th
1
3
5
6
-1
-1
-1
-1
…
-1
-1
-
If Reuse Vision Results is selected in the Vision Move Step and the Vision Move Step is inside a loop process, Mech-Viz can perform multiple rounds of planning based on the same vision result. The 64 DO signals returned by this command are the suction-cup DO signals of all planning rounds. In this case, use the number of suction-cup zones to distinguish the DO signals of each planning round.
For example, if the number of suction-cup zones is 4, this command returns 64 DO signals in total, where every 4 DO signals correspond to the multi-zone suction-cup control signals of one planning round.
Planning round 1
Planning round 2
…
Planning round 16
1st
2nd
3rd
4th
5th
6th
7th
8th
…
61st
62nd
63rd
64th
1
3
4
-1
1
4
-1
-1
…
-1
-1
-1
-1
-
-
Calibration
Function Description
This command is used for hand-eye calibration (extrinsic calibration) of the robot. It must be used together with Camera Calibration in the toolbar of Mech-Vision to realize automatic calibration. For details, refer to AUBO (ARCS) Automatic Calibration.
Command Name
autoCalib(mm_auto_calib)Input Parameters
Move Type
This parameter indicates the robot move type. The value is 1 or 2.
-
1: Linear motion. -
2: Joint motion.
Wait Time
This parameter indicates the waiting time after the robot moves to a calibration point to prevent robot vibration. The unit is second, and the default value is 2 seconds.