UR e-Series (PolyScope X 10.4 or Above) Standard Interface Commands

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.

Initialize Communication

Description

This command sets the IP address of the IPC, port number, and timeout period for robot communication.

Calling Sequence

To establish the communication between the robot and the vision system, call Establish TCP Communication after this command.

Command

MMInitSocket

default

Parameters

ipAddress

This parameter specifies the IP address of the IPC.

port

This parameter specifies the port number used by the IPC to establish the communication between the IPC and the robot. This port number must be consistent with the host port number that is specified for robot communication in the toolbar of Mech-Vision.

TimeOut

This parameter specifies the communication timeout period. Unit: seconds.

Establish TCP Communication

This command establishes the TCP communication between the robot and the vision system.

Command

MMOpenSocket

default

Close TCP Communication

This command closes the TCP communication between the robot and the vision system.

Calling Sequence

After you receive the result of the Mech-Vision or Mech-Viz project, you can call this command to close the communication and then process the obtained result.

Command

MMCloseSocket

default

Run Mech-Vision Project

Description

This command triggers the Mech-Vision project to run. When the Mech-Vision project is running, the vision system triggers the camera to capture images and then process the returned images with algorithms to produce a series of vision points or waypoints.

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.

Calling Sequence

You should set Step parameters before starting a Mech-Vision project. Therefore, call Switch Mech-Vision Parameter Recipe or Input Object Dimensions to Mech-Vision Project before calling Run Mech-Vision Project.
Vision system gets vision points and waypoints only after a Mech-Vision project runs. Therefore, call Run Mech-Vision Project before calling Get Mech-Vision Data.

Command

MMStartVis

default

Input Parameters

ProjectId

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 specifies the number of vision points or waypoints expected to be returned by the Mech-Vision project. Valid values: 0 to the largest positive integer.

If the Mech-Vision project has a Path Planning Step, this parameter indicates the expected number of waypoints. Otherwise, it indicates the expected number of vision points.

0: Obtain all vision points or waypoints from the Mech-Vision project.
A positive integer: Obtain the specific number of vision points or waypoints from the Mech-Vision project.
- If the total amount of vision points or waypoints output by the Mech-Vision project is smaller than the parameter value, this command will obtain the number of all vision points or waypoints.
- If the total amount of vision points or waypoints output by the Mech-Vision project is larger than or equal to the parameter value, this command will obtain the number of vision points or waypoints as specified by this parameter.

Vision points or waypoints will not be returned after Run Mech-Vision Project is called. To obtain vision points or waypoints, call Get Mech-Vision Data.
The default maximum number of vision points or waypoints that the vision system sends at a time is 15.

Type of robot pose to send

This parameter specifies the pose type of the real robot to send to the Mech-Vision project. Valid values: None, Current position, and Predefined Jps. The following table describes the details.

Type of robot pose to send	Description	Application scenario
None	The command does not send the robot pose to the Mech-Vision project. If the Path Planning Step is used in the Mech-Vision project, the start point of the planned path will be the Home point set in the path planning tool.	This setting should be used if the camera is mounted in eye to hand mode and the project does not require images to be captured beforehand.
Current position	The robot joint positions and flange pose must be input to the Mech-Vision project. The joint positions and flange pose are set in the Current position variable.	This setting should be used when the camera is mounted in eye in hand mode. This setting is recommended for most scenarios except those involving gantry robots.
Predefined Jps	This command sends custom joint positions to the Mech-Vision project. These joint positions will be sent to the Path Planning Step in the Mech-Vision project as the start point, where the robot will move from this start point to the first waypoint of the planned path. The custom joint positions are set in the Predefined Jps variable.	This setting should be used if the camera is mounted in eye to hand mode and the project requires images to be captured beforehand.

Type of robot pose to send

Description

Application scenario

None

The command does not send the robot pose to the Mech-Vision project.

If the Path Planning Step is used in the Mech-Vision project, the start point of the planned path will be the Home point set in the path planning tool.

This setting should be used if the camera is mounted in eye to hand mode and the project does not require images to be captured beforehand.

Current position

The robot joint positions and flange pose must be input to the Mech-Vision project.

The joint positions and flange pose are set in the Current position variable.

This setting should be used when the camera is mounted in eye in hand mode.

This setting is recommended for most scenarios except those involving gantry robots.

Predefined Jps

This command sends custom joint positions to the Mech-Vision project. These joint positions will be sent to the Path Planning Step in the Mech-Vision project as the start point, where the robot will move from this start point to the first waypoint of the planned path.
The custom joint positions are set in the Predefined Jps variable.

This setting should be used if the camera is mounted in eye to hand mode and the project requires images to be captured beforehand.

Get Mech-Vision Data

Description

This command obtains data exported by Mech-Vision.

Calling Sequence

This command should be called after Run Mech-Vision Project.

Command

MMGetVisData

default

Parameters

Result Type: Basic (get vision result)

Input Parameters

ProjectId

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.

Result Type

Set Result Type to Basic to indicate that the vision result exported by Mech-Vision is obtained as a series of vision points.

Starting at ID

This parameter specifies the starting index for vision points. Starting from the specified index, the poses and labels of all subsequent vision points will be saved sequentially to specific variables. For example, if the parameter is set to 1, the data corresponding to each vision point will be saved starting from the first vision point.

Output Parameters

Pose

This parameter stores the poses of all vision points. The object pose of the vision point (namely, the output of the poses port of the Output Step) will be automatically converted to the robot’s TCP by the vision system. The process is as follows.

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.

Label

This parameter stores the labels (i.e., data from the "labels" port of the "Output" step) of all obtained vision points.

Last Data

This parameter specifies whether all vision points are obtained. The value is 0 or 1.

0: Not all vision points are obtained.
1: All vision points are obtained.

Total Received

This parameter indicates the number of obtained vision points. By default, the vision system sends no more than 15 vision points at a time. Therefore, the maximum default value of this parameter is 15.

Status_Code

This parameter indicates the name of the variable for storing the command execution status code. Status code 1100 is returned for a successful command execution. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.

Result Type: Custom (get custom data from Mech-Vision)

Input Parameters

ProjectId

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.

Result Type

Set Result Type to Custom to indicate that, in addition to obtaining data from the poses and labels ports of the Output Step in the Mech-Vision project, data is also obtained from the custom ports of the Step.

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.

Starting at ID

This parameter specifies the starting index for vision points. Starting from the specified index, the poses, labels, and custom data of all subsequent vision points will be saved sequentially to specific variables. For example, if the parameter is set to 1, the data corresponding to each vision point will be saved starting from the first vision point.

Output Parameters

Pose

This parameter stores the poses of all vision points. The object pose of the vision point (namely, the output of the poses port of the Output Step) will be automatically converted to the robot’s TCP by the vision system. The process is as follows.

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.

Label

This parameter stores the labels (i.e., data from the "labels" port of the "Output" step) of all obtained vision points.

Last Data

This parameter specifies whether all vision points are obtained. The value is 0 or 1.

0: Not all vision points are obtained.
1: All vision points are obtained.

Total Received

This parameter indicates the number of obtained vision points. By default, the vision system sends no more than 15 vision points at a time. Therefore, the maximum default value of this parameter is 15.

Status_Code

This parameter indicates the name of the variable for storing the command execution status code. Status code 1100 is returned for a successful command execution. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.

Custom Data

This parameter stores the custom data of all vision points. This parameter value is a two-dimensional matrix, where Custom Data[0,0] represents the total number of custom elements, Custom Data[1,0] indicates the number of custom elements for the first vision point, Custom Data[1,1] represents the first custom element of the first vision point, Custom Data[1,2] represents the second custom element of the first vision point, and so on.

Result Type: Planned path (get planned path from Mech-Vision)

Input Parameters

ProjectId

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.

Result Type

Set Result Type to Planned path to indicate that the planned path is obtained from Mech-Vision as a series of waypoints. The path is planned by the path planning tool, which you may enter by clicking Config wizard as shown in the image below. For details about Path Planning, see Path Planning.

Set the Port Type parameter of the Output Step in Mech-Vision to Predefined (robot path).

Starting at ID

This parameter specifies the starting index for waypoints. Starting from the specified index, the poses, labels, and tool IDs of all subsequent waypoints will be saved sequentially to specific variables. For example, if the parameter is set to 1, the data corresponding to each waypoint will be saved starting from the first waypoint.

Return Type

This parameter specifies the type of waypoint poses to be obtained. Valid values: Jps and Tcp.

Jps: joint positions.
Tcp: TCP.

Output Parameters

Pose

This parameter stores the poses of all waypoints.

The Pose parameter is displayed only if the Return Type parameter is set to Tcp. Tcp indicates the TCP of the waypoint.
The Pose parameter is not displayed only if the Return Type parameter is set to Jps. To obtain the joint positions of waypoints, you must call Get Joint Positions.

Label

This parameter stores the labels of all waypoints.

Last Data

This parameter specifies whether all waypoints are obtained. The value is 0 or 1.

0: Not all waypoints are obtained.
1: All waypoints are obtained.

Total Received

This parameter indicates the number of obtained waypoints. By default, the vision system sends no more than 15 waypoints at a time. Therefore, the maximum default value of this parameter is 15.

Status_Code

This parameter indicates the name of the variable for storing the command execution status code. Status code 1103 is returned for a successful command execution. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.

Tool Id

This parameter stores the tool IDs of all waypoints.

Picking Point Index

This parameter indicates the sequence number of the Vision Move waypoint corresponding to the “Vision Move” Step of the path planning tool in the entire path. If the path does not contain a “Vision Move” waypoint, the value of this parameter is 0.

If the planned path consists of the following waypoints in sequence: Fixed-Point Move_1, Fixed-Point Move_2, Vision Move, and Fixed-Point Move_3, the sequence number of the Vision Move waypoint is 3.

Get Joint Positions

Description

This command stores the joint positions of the waypoint in the variables.

Command

MMGetJps

default

Input Parameters

Starting at ID

This parameter specifies the index of the waypoint. The joint positions of the waypoint that corresponds to the index are stored in the variables. Indexes start from 1.

Output Parameters

Jps Point

This parameter stores the joint positions of the waypoint that corresponds to the index.

Switch Mech-Vision Parameter Recipe

Description

This command triggers Mech-Vision to switch the parameter recipe used by the project. The image below shows how to manually switch the parameter recipe for a Mech-Vision project. For details about parameter recipes, see the parameter recipe guide.

Calling Sequence

This command should be called before Run Mech-Vision Project.

Command

MMSwitchModel

default

Input Parameters

ProjectId

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.

RecipeId

This parameter indicates the parameter recipe ID in the Mech-Vision project. For details on how to check the parameter recipe ID, see View the Parameter Recipe ID.

Input Object Dimensions to Mech-Vision Project

Description

This command dynamically inputs object dimensions into the Mech-Vision project. The object dimensions are the values of the Box Size Settings parameters in the Read Object Dimensions Step.

When you use this command, only one Read Object Dimensions Step is allowed in the Mech-Vision project. Otherwise, the vision system will return an error.

Calling Sequence

This command should be called before Run Mech-Vision Project.

Command

MMSetBoxSize

default

Input Parameters

ProjectId

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

The preceding three parameters sequentially input the length, width, and height of the object to the Mech-Vision project. The length, width, and height are measured in millimeters (mm). These values are read by the Read Object Dimensions Step and set for the parameters Length on X-axis, Length on Y-axis and Length on Z-axis.

Run Mech-Viz Project

Description

This command triggers the Mech-Viz project to run. Mech-Viz plans the robot’s motion path based on the vision result output by Mech-Vision.

Right-click the project name in the project resource panel in Mech-Viz and select Autoload Project.

Calling Sequence

You should set Step parameters before starting a Mech-Viz project. Therefore, call Read Mech-Viz Step Parameter or Set Mech-Viz Step Parameter before calling Run Mech-Viz Project.

Command

MMStartViz

default

Input Parameters

Type of robot pose to send

This parameter specifies the way in which the pose of the real robot is sent to the Mech-Viz project. Valid values: None, Current position, and Predefined Jps. The following table describes the details.

Type of robot pose to send	Description	Application scenario
None	This command does not need to send the robot pose to Mech-Viz. The simulated robot in the Mech-Viz project will move from the set home position to the first waypoint.	This setting is recommended when the camera is mounted in eye to hand mode.
Current position	In this command, the robot sends its current joint positions and flange pose to the Mech-Viz project. The simulated robot in Mech-Viz moves from the input joint positions to the first waypoint. The joint positions and flange pose are set in the Current position variable.	This setting is recommended when the camera is mounted in eye in hand mode.
Predefined Jps	In this command, the robot sends the joint positions of a teach point (the custom joint positions, instead of the current joint positions, which is set by using Predefined Jps) to the Mech-Viz project. The Mech-Viz project uses the input joint positions to plan the next path in advance while the robot is not in the camera capture region. The simulated robot in Mech-Viz moves from the input joint positions to the first waypoint.	This setting is recommended when the camera is mounted in eye to hand mode.

Type of robot pose to send

Description

Application scenario

None

This command does not need to send the robot pose to Mech-Viz. The simulated robot in the Mech-Viz project will move from the set home position to the first waypoint.

This setting is recommended when the camera is mounted in eye to hand mode.

Current position

In this command, the robot sends its current joint positions and flange pose to the Mech-Viz project. The simulated robot in Mech-Viz moves from the input joint positions to the first waypoint. The joint positions and flange pose are set in the Current position variable.

This setting is recommended when the camera is mounted in eye in hand mode.

Predefined Jps

In this command, the robot sends the joint positions of a teach point (the custom joint positions, instead of the current joint positions, which is set by using Predefined Jps) to the Mech-Viz project. The Mech-Viz project uses the input joint positions to plan the next path in advance while the robot is not in the camera capture region. The simulated robot in Mech-Viz moves from the input joint positions to the first waypoint.

This setting is recommended when the camera is mounted in eye to hand mode.

Stop Mech-Viz Project

Description

This command stops the Mech-Viz project.

Calling Sequence

This command should be called after Run Mech-Viz Project.

Command

MMStopViz

default

Set the Exit Port for the Branch by Msg Step in Mech-Viz

Description

This command sets the exit port for the Branch by Msg Step. When the next Step is a Branch by Msg Step, the Mech-Viz project will wait for this command to specify the exit port.

Calling Sequence

This command should be called after Run Mech-Viz Project.

Command

MMSetBranch

default

Input Parameters

BranchNum

This parameter specifies the “Branch by Msg” Step by its ID. Valid values: positive integers. The Step ID is displayed in the Step parameter panel. For example, the Step ID of the Step in the image above is 1.

PortNum

This parameter indicates the exit port of the Branch by Msg Step. Valid values: positive integers. When the parameter value is set to N, the Mech-Viz project exits from the port with an ID of N-1 of the Branch by Msg Step.

Set Current Index in Mech-Viz

Description

This command sets the value of the Current Index parameter of index-type Steps. Index-type Steps are Steps that include the Index section, which include Move by Grid, Move by List, Custom Pallet Pattern, and Predefined Pallet Pattern.

Calling Sequence

Index-type Steps are often preceded by a Branch by Msg Step. The robot should call commands in this order: Run Mech-Viz Project, Set Current Index in Mech-Viz, and Set the Exit Port for the Branch by Msg Step in Mech-Viz. This is to ensure that Mech-Viz has enough time to set the Current Index value.

Command

MMSetIndex

default

Input Parameters

SkillNum

This parameter specifies the Step ID of the Index-type Step. Valid values: positive integers. The Step ID is displayed in the Step parameter panel. For example, the Step ID of the Step in the image above is 3.

IndexNum

This parameter sets the value of the Current Index parameter of index-type Steps. Valid values: positive integers. When this parameter value is set to N, the current index of the corresponding Step is N-1.

Get Mech-Viz Data

Description

This command obtains the path planned by the Mech-Viz project as a series of waypoints.

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.

Calling Sequence

This command should be called after Run Mech-Viz Project.

Command

MMGetVizData

default

Parameters

Result Type: Basic Path (get planned path from Mech-Viz)

Input Parameters

Result Type

Set Result Type to Basic path to indicate that the motion path is obtained from the Mech-Viz project as a series of waypoints.

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.

Starting at ID

This parameter specifies the starting index for waypoints. Starting from the specified index, the poses, labels, and tool IDs of all subsequent waypoints will be saved sequentially to specific variables. For example, if the parameter is set to 1, the data corresponding to each waypoint will be saved starting from the first waypoint.

Return Type

This parameter specifies the type of waypoint poses to be obtained. Valid values: Jps and Tcp.

Jps: joint positions.
Tcp: TCP.

Output Parameters

Pose

This parameter stores the poses of all waypoints.

The Pose parameter is displayed only if the Return Type parameter is set to Tcp. Tcp indicates the TCP of the waypoint.
The Pose parameter is not displayed only if the Return Type parameter is set to Jps. To obtain the joint positions of waypoints, you must call Get Joint Positions.

Label

This parameter stores the labels of all waypoints.

Last Data

This parameter specifies whether all waypoints are obtained. The value is 0 or 1.

0: Not all waypoints are obtained.
1: All waypoints are obtained.

Total Received

This parameter indicates the number of obtained waypoints. By default, the vision system sends no more than 15 waypoints at a time. Therefore, the maximum default value of this parameter is 15.

Status Code

This parameter indicates the name of the variable for storing the command execution status code. Status code 2100 is returned for a successful command execution. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.

Tool Id

This parameter stores the tool IDs of all waypoints.

Picking Point Index

This parameter specifies the sequence number of the Vision Move waypoint (i.e., the waypoint corresponding to the “Vision Move” Step in the Mech-Viz project) in the planned path. If the path does not contain a “Vision Move” waypoint, the value of this parameter is 0.

If the planned path consists of the following waypoints in sequence: Fixed-Point Move_1, Fixed-Point Move_2, Vision Move, and Fixed-Point Move_3, the sequence number of the Vision Move waypoint is 3.

Result Type: Planning Data (get planned path, Vision Move planned path or custom data from Mech-Viz)

Input Parameters

Result Type

Set Result Type to Planned Data to indicate that, in addition to obtaining the planned path from the Mech-Viz project, Vision Move data or custom data is also obtained.

Vision Move data refers to data output by the Vision Move Step in Mech-Viz, including the labels of picked workobjects, number of picked workobjects, number of workobjects to be picked this time, edge or corner ID of vacuum gripper, TCP offset, orientation of workobject group, orientation of workobject, and dimensions of workobject group.

Custom data refers to data output by the custom port(s) of the Output Step 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.

Starting at ID

This parameter specifies the starting index for waypoints. Starting from the specified index, the poses, tool IDs, and Vision Move or custom data of all subsequent waypoints will be saved sequentially to specific variables. For example, if the parameter is set to 1, the data corresponding to each waypoint will be saved starting from the first waypoint.

Return Type

This parameter specifies the type of waypoint poses to be obtained. Valid values: Jps and Tcp.

Jps: joint positions.
Tcp: TCP.

Output Parameters

Pose

This parameter stores the poses of all waypoints.

The Pose parameter is displayed only if the Return Type parameter is set to Tcp. Tcp indicates the TCP of the waypoint.
The Pose parameter is not displayed only if the Return Type parameter is set to Jps. To obtain the joint positions of waypoints, you must call Get Joint Positions.

Last Data

This parameter specifies whether all waypoints are obtained. The value is 0 or 1.

0: Not all waypoints are obtained.
1: All waypoints are obtained.

Visual Move Or Not

This parameter indicates the type of the waypoint. Valid values: 0 and 1.

Visual Move Or Not

Waypoint type

Data

0

Non-Vision Move waypoint

Pose and tool ID

1

Vision Move waypoint

pose, tool ID, Vision Move data, custom output data (which will not be returned if the Mech-Vision project does not have a custom port)

Picking Point Index

This parameter specifies the sequence number of the Vision Move waypoint (i.e., the waypoint corresponding to the “Vision Move” Step in the Mech-Viz project) in the planned path. If the path does not contain a “Vision Move” waypoint, the value of this parameter is 0.

If the planned path consists of the following waypoints in sequence: Fixed-Point Move_1, Fixed-Point Move_2, Vision Move, and Fixed-Point Move_3, the sequence number of the Vision Move waypoint is 3.

Total Received

This parameter indicates the number of obtained waypoints. By default, the vision system sends no more than 15 waypoints at a time. Therefore, the maximum default value of this parameter is 15.

Status Code

This parameter indicates the name of the variable for storing the command execution status code. Status code 2100 is returned for a successful command execution. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.

Tool Id

This parameter stores the tool IDs of all waypoints.

Plan Data

This parameter stores the obtained Vision Move planned data. Among them, the variables Plan Data[0,0] to Plan Data[0,21] and Plan Data[N,0] are meaningless. The Vision Move data for the first waypoint will be stored in Plan Data[1,1] to Plan Data[1,21], and so on.

If the waypoint is a non-Vision Move waypoint, Plan Data[N,1] to Plan Data[N,21] will be 0 and have no actual meaning.

If the first waypoint is a Vision Move waypoint, the Vision Move data corresponding to the waypoint is described in the table below.

Data	Description	Variable
Labels of picked workobjects	A label consists of 10 integers. The default value is ten 0s.	Plan Data[1,1]~Plan Data[1,10]
Number of picked workobjects	The total number of picked workobjects.	Plan Data[1,11]
Number of workobjects to be picked this time	Number of workobjects to be picked this time	Plan Data[1,12]
Edge or corner ID of vacuum gripper	The ID of the edge or corner used to pick workobjects this time.	Plan Data[1,13]
TCP offset	The XYZ offset between the center of the workobject group and the tool pose center.	Plan Data[1,14]~Plan Data[1,16]
Orientation of workobject group	The relative position between the workobject group and the length of the vacuum gripper. The value is 0 or 1, where 0 stands for parallel and 1 for vertical.	Plan Data[1,17]
Orientation of workobject	The relative position between the length of a workobject and that of the vacuum gripper. The value is 0 or 1, where 0 stands for parallel and 1 for vertical.	Plan Data[1,18]
Dimensions of workobject group	The length, width, and height of the workobject group to be picked this time.	Plan Data[1,19]~Plan Data[1,21]

Data

Description

Variable

Labels of picked workobjects

A label consists of 10 integers. The default value is ten 0s.

Plan Data[1,1]~Plan Data[1,10]

Number of picked workobjects

The total number of picked workobjects.

Plan Data[1,11]

Number of workobjects to be picked this time

Plan Data[1,12]

Edge or corner ID of vacuum gripper

The ID of the edge or corner used to pick workobjects this time.

Plan Data[1,13]

TCP offset

The XYZ offset between the center of the workobject group and the tool pose center.

Plan Data[1,14]~Plan Data[1,16]

Orientation of workobject group

The relative position between the workobject group and the length of the vacuum gripper. The value is 0 or 1, where 0 stands for parallel and 1 for vertical.

Plan Data[1,17]

Orientation of workobject

The relative position between the length of a workobject and that of the vacuum gripper. The value is 0 or 1, where 0 stands for parallel and 1 for vertical.

Plan Data[1,18]

Dimensions of workobject group

The length, width, and height of the workobject group to be picked this time.

Plan Data[1,19]~Plan Data[1,21]

Custom Data

This parameter stores the custom data of all waypoints. This parameter value is a two-dimensional matrix, where Custom Data[0,0] represents the total number of custom elements, Custom Data[1,0] indicates the number of custom elements for the first waypoint, Custom Data[1,1] represents the first custom element of the first waypoint, Custom Data[1,2] represents the second custom element of the first waypoint, and so on.

Result Type: Custom (get planned path and custom data from Mech-Viz)

Input Parameters

Result Type

Set Result Type to Custom Data to indicate that, in addition to obtaining the planned path from the Mech-Viz project, custom data is also obtained. Custom data refers to data output by the custom port(s) of the Output Step 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.

Starting at ID

This parameter specifies the starting index for waypoints. Starting from the specified index, the poses, tool IDs, and custom data of all subsequent waypoints will be saved sequentially to specific variables. For example, if the parameter is set to 1, the data corresponding to each waypoint will be saved starting from the first waypoint.

Return Type

This parameter specifies the type of waypoint poses to be obtained. Valid values: Jps and Tcp.

Jps: joint positions.
Tcp: TCP.

Output Parameters

Pose

This parameter stores the poses of all waypoints.

The Pose parameter is displayed only if the Return Type parameter is set to Tcp. Tcp indicates the TCP of the waypoint.
The Pose parameter is not displayed only if the Return Type parameter is set to Jps. To obtain the joint positions of waypoints, you must call Get Joint Positions.

Last Data

This parameter specifies whether all waypoints are obtained. The value is 0 or 1.

0: Not all waypoints are obtained.
1: All waypoints are obtained.

Visual Move Or Not

This parameter indicates the type of the waypoint. Valid values: 0 and 1.

Visual Move Or Not

Waypoint type

Data

0

Non-Vision Move waypoint

Pose and tool ID

1

Vision Move waypoint

Poses, tool IDs, and custom data (custom ports must exist in the Mech-Vision project)

Total Received

This parameter indicates the number of obtained waypoints. By default, the vision system sends no more than 15 waypoints at a time. Therefore, the maximum default value of this parameter is 15.

Status Code

This parameter indicates the name of the variable for storing the command execution status code. Status code 2100 is returned for a successful command execution. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.

Tool Id

This parameter stores the tool IDs of all waypoints.

Custom Data

This parameter stores the custom data of all waypoints. This parameter value is a two-dimensional matrix, where Custom Data[0,0] represents the total number of custom elements, Custom Data[1,0] indicates the number of custom elements for the first waypoint, Custom Data[1,1] represents the first custom element of the first waypoint, Custom Data[1,2] represents the second custom element of the first waypoint, and so on.

Read Mech-Viz Step Parameter

Description

This command reads the parameter value of a specific Step in the Mech-Viz project.

Calling Sequence

This command should be called before Run Mech-Viz Project.

Command

MMReadProperty

default

Input Parameters

ID

This parameter corresponds to the Config ID field defined in the property_config file.

From the toolbar of Mech-Vision, go to Robot Communication Configuration Next Advanced Settings. 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 Tools Key Query Tool 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 parameter value of the Step.

Set Mech-Viz Step Parameter

Description

This command sets the parameter value of a Step in the Mech-Viz project.

Calling Sequence

This command should be called before Run Mech-Viz Project.

Command

MMSetProperty

default

Input Parameters

ID

This parameter corresponds to the Config ID field defined in the property_config file.

From the toolbar of Mech-Vision, go to Robot Communication Configuration Next Advanced Settings. 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 Tools Key Query Tool 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.

Get Gripper DO List

Description

This command obtains the control signal list for the multi-section vacuum gripper from the Mech-Vision or Mech-Viz project.

Before using this command, you must perform the following configurations in Mech-Vision or Mech-Viz.

Configure the Mech-Vision project
- In the Path Planning Step, click Config wizard. In Global configuration, enable Box depalletizing.
- In the Path Planning Step, click Config wizard, and then double-click the name of the robot tool. In the pop-up window, select Depalletizing vacuum gripper for Tool type, click Configure depalletizing vacuum gripper, and then configure DO signals according to needs.
Configure the Mech-Viz project
- In the Vision Move Step of Mech-Viz, set Select Picking Method to Box depalletizing.
- In Mech-Viz, double-click the tool name, select Depalletizing vacuum gripper for Tool type, click Configure depalletizing vacuum gripper, and then configure the DO signals according to needs.

Calling Sequence

This command must be called before the Get Mech-Vision Dataor Get Mech-Viz Data command. This means that the robot must obtain the motion path and then obtain gripper DO signals of the Vision Move waypoint.

Command

MMGetDoList

default

Input Parameters

Mech-Vision or Mech-Viz

This parameter specifies the source of the DO signal list. Valid values: Mech-Vision and Mech-Viz. The following table describes the details.

Mech-Vision: Get DO signal list from Mech-Vision. In this case, ProjectId will be displayed. ProjectId must be set to the Mech-Vision project ID.
Mech-Viz: Get DO signal list from Mech-Viz.

SuckerNum

This parameter specifies the number of gripper sections that are specified in the gripper configuration tool. For example, the number of gripper sections in the above image is 3.

Output Parameters

Do Data

This parameter indicates the number of obtained DO signals. The DO signals returned by this command vary based on the deployed project.

Gripper DO signals planned by the Mech-Vision project

Under Global Configuration of the path planning tool, if Plan all vision results is disabled, this command returns 64 gripper DO signals that are planned in this round. Valid DO signals are non-negative integers ranging from 0 to 999. Invalid DO signals are -1, which serves as a placeholder.

For example, valid DO signals in the table below are 1, 3, 5, and 6, which means that the robot will set the values of these DO signals to ON.

1st

2nd

3rd

4th

5th

6th

7th

8th

…

63rd

64th

1

3

5

6

-1

-1

-1

-1

…

-1

-1

Under Global Configuration of the path planning tool, if Plan all vision results is enabled, Mech-Vision can perform multiple rounds of planning based on the same vision result. The 64 gripper DO signals returned by this command are obtained during all rounds of planning. In this case, you can use the number of vacuum gripper sections to differentiate the gripper DO signals obtained during each round of planning.

For example, if the number of vacuum gripper sections is 4 and the command returns 64 DO signals in total, each 4 DO signals are multi-section vacuum gripper signals obtained during each round of planning.

First round of planning				Second round of planning				…	16th round of planning
1st	2nd	3rd	4th	5th	6th	7th	8th	…	61st	62nd	63rd	64th
1	3	4	-1	1	4	-1	-1	…	-1	-1	-1	-1

Gripper DO signals planned by the Mech-Viz project

If Reuse Vision Result is not selected for the Vision Move Step, this command returns 64 gripper DO signals that are planned during this round. Valid DO signals are non-negative integers ranging from 0 to 999. Invalid DO signals are -1, which serves as a placeholder.

For example, valid DO signals in the table below are 1, 3, 5, and 6, which means that the robot will set the values of these 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 Result is selected for the Vision Move Step and the Vision Move Step is used in a loop, Mech-Viz can perform multiple rounds of planning based on the same vision result. The 64 gripper DO signals returned by this command are obtained during all rounds of planning. In this case, you can use the number of vacuum gripper sections to differentiate the gripper DO signals obtained during each round of planning.

For example, if the number of vacuum gripper sections is 4 and the command returns 64 DO signals in total, each 4 DO signals are multi-section vacuum gripper signals obtained during each round of planning.

First round of planning				Second round of planning				…	16th round of planning
1st	2nd	3rd	4th	5th	6th	7th	8th	…	61st	62nd	63rd	64th
1	3	4	-1	1	4	-1	-1	…	-1	-1	-1	-1

Get Message from Notify Step

Description

When the Mech-Vision project or Mech-Viz project is executing the Notify Step, the vision system returns the message predefined in the Notify Step.

Before sending this command, complete the following settings for the Notify Step.

For a Notify Step in the Mech-Vision project:
1. Connect the Notify Step to the right side of another Step. The Output Step is used in the example in the image below.
2. Select Trigger Control Flow Given Output in the parameter panel of the Output Step.
3. In the parameter panel of the Notify Step, enter Standard Interface Notify (the value cannot be modified) for Service Name. Enter a positive integer for Message, for example, 1001.
For a Notify Step in the Mech-Viz project:
1. Connect the Notify Step to a proper Step in the workflow.
2. In the parameter panel of the Notify Step, select Standard Interface. Enter a positive integer for Message, for example, 1000.

Calling Sequence

This command should be called after Run Mech-Vision Project or Run Mech-Viz Project.

Command

MMNotify

default

Output Parameters

dataValue

This parameter stores the message from the Notify Step. Only positive integer messages are supported at the moment.

Calibration

Description

This command is used for robot hand-eye calibration (extrinsic parameter calibration). This command must be used together with the Camera Calibration setting to complete automatic calibration. You can find Camera Calibration in the toolbar of Mech-Vision. For more information, see UR e-Series (PolyScope X 10.4 or Above) Automatic Calibration.

Command

MMCalib

default

Input Parameters

PosJps

This parameter specifies the pose type of the calibration point. Valid values: Flange Pose and Joint Angle.

Flange Pose: TCP.
Joint Angle: Joint positions.

MoveType

This parameter specifies the motion type of the robot. Valid values: Movel and Movej.

Movel: Linear motion.
Movej: Joint motion.

This command includes a built-in Move-to command, where Waypoint represents the position of the calibration start point.