EFORT Standard Interface Commands

You are currently viewing the documentation for the latest version (2.2.0). To access a different version, click the "Switch version" button located in the upper-right corner of the page.

■ If you are not sure which version of the product you are currently using, please feel free to contact Mech-Mind Technical Support.

This section describes standard interface commands used in TCP communications between a EFORT 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.

send receive

Command Overview

Commands related to Mech-Vision

Commands related to Mech-Viz

Initialize Communication

Establish TCP Communication

Close TCP Communication

Run Mech-Vision Project

Switch Mech-Vision Parameter Recipe

Get Vision Result

Get Planned Path in Mech-Vision

Store Vision Result or Planned Path (TCP)

Store Planned Path (joint positions)

Get Mech-Vision Custom Data

Get Gripper DO List

Get Message from Notify Step

Calibration

Input Object Dimensions to Mech-Vision Project

Initialize Communication

Establish TCP Communication

Close TCP Communication

Run Mech-Viz Project

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

Set Current Index in Mech-Viz

Get Planned Path in Mech-Viz

Store Vision Result or Planned Path (TCP)

Store Planned Path (joint positions)

Read Mech-Viz Step Parameter

Set Mech-Viz Step Parameter

Get Vision Move Data or Custom Data

Get Gripper DO List

Get Message from Notify Step

Stop Mech-Viz Project

Precautions

  • 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

This instruction is used to set the socket number for communication with the robot.

Calling Sequence

This command should be called before Establish TCP Communication.

Command Format

MM_Init_Socket(Port)

Input Parameters

Port

This parameter indicates the socket number and must match the socket number set in the figure below.

Establish TCP Communication

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

Command Format

MM_Open_Socket()

Calling Sequence

This command should be called after MM_Init_Socket.

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 store the result in variables.

Command Format

MM_Close_Socket()

Run Mech-Vision Project

Command

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

Command Format

MM_Start_Vis(Job, Pos_Number_Need, SendPos_Type, MM_J)

Input Parameters

Job

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.

Pos_Number_Need

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, call Get Vision Result or Get Mech-Vision Custom Data. To obtain waypoints, call Get Planned Path in Mech-Vision.

  • The default maximum number of vision points or waypoints that the vision system sends at a time is 20. To modify the default maximum number of poses to obtain each time as needed, go to Robot and Communication > Robot Communication Configuration  Next  Advanced Settings in the toolbar of Mech-Vision. The upper limit is 30.

set number

SendPos_Type

This parameter specifies the pose type of the real robot to send to the Mech-Vision project. Valid values: 0, 1, 2, and 3. The following table describes the details.

SendPos_Type Description Applicable scenario

0

The command does not send the robot pose data 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.

1

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

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.

2

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

This setting is recommended for scenarios involving gantry robots.

3

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.

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

MM_J

This parameter specifies the custom joint position data.

  • If the SendPos_Type parameter is set to 3, the joint positions will be sent to the Path Planning Step in the Mech-Vision project as the start point, where the robot moves from this start point to the first waypoint of the planned path.

  • If the value of SendPos_Type is set to values other than 3, the joint positions set here will not take effect, but it has to be set.

Output Parameters

MM_Status

This parameter indicates the name of the variable for storing the command execution status code. Status code 1102 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.

Example

CALL: MM_Status := MM_Start_Vis(1, 1, 1, MM_J);

In the preceding example, the Mech-Vision project whose ID is 1 is run, and one vision point is expected to be returned by the Mech-Vision project. At the same time, the robot sends the current joint position and flange pose data to the Mech-Vision project.

Get Vision Result

Command

This command obtains vision result, namely, a series of vision points, from Mech-Vision. 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.

If the first input port of the Output Step is Object Center Points, the Output Step will convert the object center points into the corresponding pick points. Therefore, the object poses obtained by running this command are actually poses of pick points, instead of poses of object center points.
get tcp

  1. Convert the object pose from a quaternion to Euler angles.

  2. Rotate the object’s pose around the X-axis by 180° to orient its Z-axis downward.

    convert tcp

Calling Sequence

This command should be called after Run Mech-Vision Project. After you call this command, call Store Vision Result or Planned Path (TCP) to access pose data.

Command Format

MM_Get_VisData(Job)

Input Parameters

Job

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

MM_POS_NUM

This parameter stores the number of vision points returned by Mech-Vision.

By default, after the robot sends this command, the vision system returns the result in 10 seconds. If the vision system fails to return any result in 10 seconds, a timeout error code is returned. To modify the default timeout period as needed, go to Robot and Communication > Robot Communication Configuration  Next  Advanced Settings in the toolbar of Mech-Vision.

set vis time

MM_LastData

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.

MM_Status

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.

Example

CALL: MM_Status, MM_LastData, MM_POS_NUM := MM_Get_VisData(1);

The above example demonstrates how to obtain the vision result in Mech-Vision Project 1.

Store Vision Result or Planned Path (TCP)

Command

This command stores the TCP, label, and tool ID of the vision point or waypoint in the variables.

Command Format

MM_Get_Pose(Index)

Input Parameters

Index

This parameter specifies the index of the vision point or waypoint. The TCP, label, and tool ID of the vision point or waypoint that corresponds to the index are stored in the variables. Indexes start from 1.

Output Parameters

MM_Pose[Index]

This parameter stores the TCP of the vision point or waypoint that corresponds to the index.

MM_Label[Index]

This parameter stores the label of the vision point or waypoint that corresponds to the index.

MM_Tool[Index]

This parameter stores the tool ID of the vision point or waypoint that corresponds to the index.

Example

CALL: MM_Pose[1], MM_Label[1], MM_Tool[1] := MM_Get_Pose(1)

The above example indicates that the TCP of the first vision point or waypoint will be stored in MM_Pose[1], the label will be stored in MM_Label[1], and the tool ID will be stored in MM_Tool[1].

Store Planned Path (joint positions)

Command

This command stores the joint positions, label, and tool ID of the waypoint in the variables.

Command Format

MM_GET_JPS(Index)

Input Parameters

Index

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

Output Parameters

MM_JPS[Index]

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

MM_Label[Index]

This parameter stores the label of the waypoint that corresponds to the index.

MM_Tool[Index]

This parameter stores the tool ID of the waypoint that corresponds to the index.

Example

CALL: MM_JPS[1], MM_Label[1], MM_Tool[1] := MM_GET_JPS(1)

The above example indicates that the joint positions of the first waypoint will be stored in MM_JPS[1], the label will be stored in MM_Label[1], and the tool ID will be stored in MM_Tool[1].

Switch Mech-Vision Parameter Recipe

Command

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.

set recipe

Calling Sequence

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

Command Format

MM_Switch_Model(Job, Model_ID)

Input Parameters

Job

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 details on how to check the parameter recipe ID, see View the Parameter Recipe ID.

Output Parameters

MM_Status

This parameter indicates the name of the variable for storing the command execution status code. Status code 1107 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.

Example

CALL: MM_Status := MM_Switch_Model(1, 1);

In the preceding example, the parameter recipe of the Mech-Vision project whose ID is 1 is switched to recipe 2.

Get Planned Path in Mech-Vision

Command

This command obtains the path planned by the Mech-Vision project 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).
get plan path step

Calling Sequence

This command should be called after Run Mech-Vision Project. After you call this command, call Store Vision Result or Planned Path (TCP) or Store Planned Path (joint positions) to access pose data.

Command Format

MM_Get_VisPath(Job, Pose_Type)

Input Parameters

Job

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 type of waypoint poses to be obtained. can be set to 1 or 2.

Output Parameters

MM_LastData

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.

MM_POS_NUM

This parameter stores the number of waypoints that are returned by the vision system. By default, the vision system sends no more than 20 waypoints at a time. Therefore, the maximum default value of this parameter is 20. To modify the default maximum number of poses to obtain each time as needed, go to Robot and Communication > Robot Communication Configuration  Next  Advanced Settings in the toolbar of Mech-Vision. The upper limit is 30.

set number
Before you call Get Planned Path in Mech-Vision, set Pos_Number_Need of Run Mech-Vision Project to 0 to reduce the number of Get Planned Path in Mech-Vision calls. If Pos_Number_Need of Run Mech-Vision Project is set to 1, only one waypoint is obtained each time you call Get Planned Path in Mech-Vision. You need to call Command 105 several times to obtain all waypoints.

MM_VisPosNum

The sequence number of the Vision Move waypoint (the waypoint corresponding to the Vision Move step of the path planning tool) in the path. If the waypoint does not exist in the path, the petameter value 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.

MM_Status

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.

Example

CALL: MM_Status, MM_LastData, MM_POS_NUM, MM_VisPosNum := MM_Get_VisPath(1, 2)

In the preceding example, the planned path returned by Mech-Vision project 1 is obtained, the waypoints of the path are stored in the TCP format, the number of waypoints is stored in MM_POS_NUM, the sequence number of the Vision Move waypoint in the planned path is stored in MM_VisPosNum, and the command execution status code is stored in MM_Status.

Get Mech-Vision Custom Data

Command

This command obtains data from the custom port(s) of the “Output” Step in Mech-Vision. A single invocation of this instruction can retrieve the custom data for only one vision point.

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.

  1. Data output from Predefined Keys, such as poses, labels, sizes, offsets, is not custom data.

  2. You must set Port Type of the Output Step to Custom and select the poses port in the Predefined Keys section in Mech-Vision.
custom data

Calling Sequence

This command should be called after Run Mech-Vision Project. After you call this command, call Store Vision Result or Planned Path (TCP) to obtain the poses, labels, and tool IDs of vision points.

Command Format

MM_Get_DyData(Job)

Input Parameters

Job

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

MM_Status

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.

MM_LastData

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.

MM_UserDataNum

This parameter stores the number of custom elements. Custom data will be stored in the MM_UserData variable.

Custom number of data items indicates the total number of elements in the data output of all custom ports. For example, the following table displays the output data of the ports of the Output step. customData1 and customData2 are custom ports, with 3 and 2 columns in their respective output data. Therefore, the number of elements in custom output data is 5 (3 + 2).

Port name

poses

labels

customData1

customData2

Output 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]

]

Number of rows (i.e. number of items in the list)

2

2

2

2

Number of columns (i.e. number of elements in each item of the list)

7

1

3

2

Example

CALL: MM_Status, MM_LastData, MM_UserDataNum := MM_Get_DyData(1);
CALL: MM_Pose[1], MM_Label[1], MM_Tool[1] := MM_Get_Pose(1);

The above example indicates that the custom data of Mech-Vision project 1 is obtained, the custom data is stored in MM_UserData, the TCP is stored in MM_Pose[1], and the label is stored in MM_Label[1].

Input Object Dimensions to Mech-Vision Project

Command

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.
read object dimensions

Calling Sequence

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

Command Format

MM_Set_BoxSize(Job, Length, Width, Height)

Input Parameters

Job

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.

Output Parameters

MM_Status

This parameter indicates the name of the variable for storing the command execution status code. Status code 1108 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.

Example

CALL: MM_Status := MM_Set_BoxSize(1, 500, 300, 200);

In the preceding example, the length, width, and height of the object of the Read Object Dimensions Step in the Mech-Vision project are 500 mm, 300 mm, and 200 mm respectively.

Run Mech-Viz Project

Command

This command triggers the Mech-Viz project to run. Mech-Viz plans a path for the robot based on the vision results 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 Format

MM_Start_Viz(SendPos_Type, MM_J)

Input Parameters

SendPos_Type

This parameter specifies the way in which the real robot pose is sent to the Mech-Viz project. Valid values: 0, 1, and 2. The following table describes the details.

SendPos_Type Description Applicable scenario

0

This command does not need to send the robot pose to the Mech-Viz project. 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.

1

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.

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

2

In this command, the robot sends the joint positions of a teach point (the custom joint positions, instead of the current joint positions) 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, as shown in the following figure. 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.
Why robot pose type 2 is recommended when the camera is mounted in eye to hand mode?

In eye to hand mode, the camera can perform image capturing for the next round of path planning before the robot returns to the image capture region and picking region, thus shortening the cycle time. The image below demonstrates how a robot works in the placing region.

If SendPos_Type is set to 1, the robot will send the current pose to Mech-Viz. It is possible that the real robot moves to other positions before reaching the first waypoint. However, the simulated robot moves directly to the first waypoint of the Mech-Viz project from the pose sent by the robot. Consequently, there may be a mismatch between the paths of the real robot and simulated robot. This mismatch can potentially lead to unpredicted safety hazards, especially if a collision is detected in the path of the simulated robot.

On the other hand, if SendPos_Type is set to 2, the robot will send the image-capturing pose set by teaching to Mech-Viz. Thus, the real robot can trigger the next round of path planning in Mech-Viz when the real robot is in the image-capturing region and the cycle time can be shortened.

In conclusion, robot pose type should be set to 2 for projects in eye to hand mode.

robot example

MM_J

This parameter specifies the custom joint position data.

  • If SendPos_Type parameter is set to 2, the joint positions will be sent to the Mech-Viz project as the start point, where the robot moves from this start point to the first waypoint of the planned path.

  • If the value of SendPos_Type is set to values other than 2, the joint positions set here will not take effect, but it has to be set.

Output Parameters

MM_Status

This parameter indicates the name of the variable for storing the command execution status code. Status code 2103 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.

Example

CALL: MM_Status := MM_Start_Viz(1, MM_J);

In the preceding example, the joint positions and flange pose of the robot are input to the Mech-Viz project for the Mech-Viz project to run.

Stop Mech-Viz Project

Command

This command stops the Mech-Viz project.

Calling Sequence

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

Command Format

MM_Stop_Viz()

Output Parameters

MM_Status

This parameter indicates the name of the variable for storing the command execution status code. Status code 2104 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.

Example

CALL: MM_Status := MM_Stop_Viz()

In the preceding example, the running Mech-Viz project is stopped.

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

Command

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 to take.

set branch

Calling Sequence

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

Command Format

MM_Set_Branch(Branch_ID, Branch_Port)

Input Parameters

Branch_ID

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.

Branch_Port

This parameter indicate 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.

Output Parameters

MM_Status

This parameter indicates the name of the variable for storing the command execution status code. Status code 2105 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.

Example

CALL: MM_Status := MM_Set_Branch(1, 3);

In the preceding example, the Mech-Viz project with an ID of 1 exits from the port with an ID of 2 of the Branch by Msg Step.

Set Current Index in Mech-Viz

Command

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.

set index

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 Format

MM_Set_Index(Skill_Num, Index_Num)

Input Parameters

Skill_Num

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.

Index_Num

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.

Output Parameters

MM_Status

This parameter indicates the name of the variable for storing the command execution status code. Status code 2106 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.

Example

CALL: MM_Status := MM_Set_Index(2, 10);

In the preceding example, the current index of the Step with an ID of 2 of the Mech-Viz project is 9.

Get Planned Path in Mech-Viz

Command

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. After you call this command, call Store Vision Result or Planned Path (TCP) or Store Planned Path (joint positions) to access pose data.

Command Format

MM_Get_VizData(Pose_Type)

Input Parameters

Pose_Type

This parameter specifies the type of waypoint poses to be obtained. can be set to 1 or 2.

Output Parameters

MM_Status

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.

By default, after the robot sends this command, the vision system returns the result in 10 seconds. If the vision system fails to return any result in 10 seconds, a timeout error code is returned. To modify the default timeout period as needed, go to Robot and Communication > Robot Communication Configuration  Next  Advanced Settings in the toolbar of Mech-Vision.

set viz time

MM_LastData

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.

MM_POS_NUM

This parameter stores the number of waypoints that are returned by the vision system. By default, the vision system sends no more than 20 waypoints at a time. Therefore, the maximum default value of this parameter is 20. To modify the default maximum number of poses to obtain each time as needed, go to Robot and Communication > Robot Communication Configuration  Next  Advanced Settings in the toolbar of Mech-Vision. The upper limit is 30.

set number

MM_VisPosNum

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 path. If the waypoint does not exist in the path, the petameter value 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.

Example

CALL: MM_Status, MM_LastData, MM_POS_NUM, MM_VisPosNum := MM_Get_VizData(2);

The above example demonstrates how to obtain the path planned in the Mech-Viz project. The waypoints are represented in TCP.

Read Mech-Viz Step Parameter

Command

This job 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 Format

MM_Get_property(Config_ID)

Input Parameters

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

get property config

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.

    parameter key name

  • 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

MM_Status

This parameter indicates the name of the variable for storing the command execution status code. Status code 2109 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.

MM_Viz_Prop

This parameter stores the parameter value of the Step.

Example

In the line below, 5 is the Config ID; 3 is the Step ID; and xCount is the parameter key name. Add this line to the property_config file.

read,5,3,xCount

When the robot sends the command below, the robot receives the value of the parameter whose key name is xCount.

CALL: MM_Status, MM_Viz_Prop := MM_Get_property(5);

In the preceding example, the value of the xCount parameter of the Step with an ID of 3 of the Mech-Viz project is stored in MM_Viz_Prop.

Set Mech-Viz Step Parameter

Command

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

Calling Sequence

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

Command Format

MM_Set_property(Config_ID)

Input Parameters

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

get property config

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.

    parameter key name

  • 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

MM_Status

This parameter indicates the name of the variable for storing the command execution status code. Status code 2108 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.

Example

In the line below, 1 is the Config ID and 3 is the Step ID. xOffset, yOffset and zOffset are parameter key names; and 10, 20 and 30 are their respective values. Add this line to the property_config file.

write,1,3,xOffset,10
write,1,3,yOffset,20
write,1,3,zOffset,30

When the robot calls the job below, Mech-Viz sets the values of the parameters whose key names are “xOffset”, “yOffset” and “zOffset” respectively to “10”, “20” and “30”.

CALL: MM_Status := MM_Set_property(1);

In the preceding example, the values of the parameters whose key names are xOffset, yOffset and zOffset are respectively set to 10, 20, and 30.

Get Gripper DO List

Command

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.

      vision move vis

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

      sucker vis

  • Configure the Mech-Viz project

    • In the Vision Move Step of Mech-Viz, set Select Picking Method to Box depalletizing.

      vision move viz

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

      sucker viz

Calling Sequence

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

Command Format

MM_Get_DoList(Resource, Block_Num)

Input Parameters

Resource

This parameter specifies the source of the DO signal list. Valid values: 0 to the largest positive integer.

  • 0: Get DO signal list from Mech-Viz.

  • A positive integer: Get DO signal list from Mech-Vision. The positive integer is the Mech-Vision project ID.

Block_Num

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.

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.

      plan all vis off

      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.

      plan all vis on

      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.

      vision move off

      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.

      vision move on

      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

Output Parameters

MM_Do_Port

This parameter indicates the source of the DO signal list.

MM_Status

This parameter indicates the name of the variable for storing the command execution status code. If the DO signal list is successfully obtained from Mech-Viz, the status code is 2102. If the DO signal list is successfully obtained from Mech-Vision, the status code is 1106. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.

Example

CALL: MM_Status,MM_Do_Port := MM_Get_DoList(0, 1);

This example stores the DO signal list obtained from Mech-Viz in MM_Do_Port.

Get Vision Move Data or Custom Data

Command

This command obtains Vision Move output from the Mech-Vision project, or the Vision Move output or custom output from the Mech-Viz project. A single invocation of this instruction can retrieve the custom data for only one vision point.

  • Mech-Vision projects: Vision Move data refers to data output by the Vision Move Step in the path planning tool, which you may enter from the Path Planning Step. Vision Move data includes 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.

  • Mech-Viz projects:

    • 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-type 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.

      1. Data output from Predefined Keys, such as poses, labels, sizes, offsets, is not custom data.

      2. You must set Port Type of the Output Step to Custom and select the poses port in the Predefined Keys section in Mech-Vision.
      custom data

Calling Sequence

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

Command Format

MM_Get_PlanData(Job, Pose_Type)

Input Parameters

Job

This parameter specifies the source of the Vision Move data. Valid values: 0 to the largest positive integer.

  • 0: Get Vision Move data from Mech-Viz.

  • Positive integer: Get Vision Move data from Mech-Vision. The positive integer is the Mech-Vision project ID.

Pose_Type

This parameter specifies the expected returned data format.

  • When the value of _resource is 0, the valid value range of Pose_Type is 1 to 4. Details are provided below.

    Value of Pose Type

    Description of expected returned data (Each field is explained below. If the Mech-Vision project does not have a custom port, no elements of custom data are returned.)

    Waypoint type

    Data

    1

    Non-Vision Move waypoint

    Pose (joint positions), motion type, tool ID

    Vision Move waypoint

    Pose (joint positions), motion type, tool ID, velocity, element 1 in custom data, … element N in custom data

    2

    Non-Vision Move waypoint

    Pose (TCP), motion type, tool ID, velocity

    Vision Move waypoint

    Pose (TCP), motion type, tool ID, velocity, element 1 in custom data, … element N in custom data

    3

    Non-Vision Move waypoint

    Pose (joint positions), motion type, tool ID

    Vision Move waypoint

    Pose (joint positions), motion type, tool ID, velocity, Mech-Viz Vision Move data, element 1 in custom data, … element N in custom data

    4

    Non-Vision Move waypoint

    Pose (TCP), motion type, tool ID, velocity

    Vision Move waypoint

    Pose (TCP), motion type, tool ID, velocity, Mech-Viz Vision Move data, element 1 in custom data, … element N in custom data

  • When the value of _resource is a positive integer, the valid value range of Pose_Type is 1 to 2. Details are provided below.

    Value of Pose Type

    Description of expected returned data (Each field is explained below.)

    Waypoint type

    Data

    1

    Non-Vision Move waypoint

    Pose (joint positions), motion type, tool ID

    Vision Move waypoint

    Pose (joint positions), motion type, tool ID, velocity, Mech-Vision Vision Move data

    2

    Non-Vision Move waypoint

    Pose (TCP), motion type, tool ID, velocity

    Vision Move waypoint

    Pose (TCP), motion type, tool ID, velocity, Mech-Vision Vision Move data

Pose

The pose of a waypoint can be joint positions (measured in degrees) or TCP (measured in millimeters for three-dimensional coordinates and in degrees for Euler angles) of the robot.

After calling the MM_Get_PlanData instruction, the user can obtain the pose, label, and end-effector tool ID by invoking command Store Vision Result or Planned Path (TCP) or command Store Planned Path (joint positions).

Motion type

Robot motion type: Takes a value of 1 or 2 and is stored in the MM_MoveType variable.

  • 1: Joint motion (MOVEJ)

  • 2: Linear motion (MOVEL)

Tool ID

The ID of the tool to be used at this waypoint. A value of -1 means that no tool is used at this waypoint.

After calling the MM_Get_PlanData instruction, the user can obtain the pose, label, and end-effector tool ID by invoking command Store Vision Result or Planned Path (TCP) or command Store Planned Path (joint positions).

Vision Move data

Data output by the “Vision Move” Step in Mech-Vision or Mech-Viz, including labels of picked workobjects, number of picked workobjects, number of workobjects to be picked this time, edge/corner ID of vacuum gripper, TCP offset, orientation of workobject group, orientation of workobject, dimensions of workobject group. Vision motion planning data will be stored in the MM_PlanData variable.

Name Description Number of Elements

Labels of picked target objects

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

10

Number of picked target objects

The total number of picked target objects.

1

The number of target objects to be picked this time.

The number of target objects to be picked this time.

1

Edge or corner ID of vacuum gripper

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

1

TCP offset

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

3

Orientation of target object group

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

1

Orientation of target object

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

1

Dimensions of target object group

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

3

Element in custom data

This parameter stores the number of custom elements. Custom data will be stored in the MM_UserData variable.

Custom number of data items indicates the total number of elements in the data output of all custom ports. For example, the following table displays the output data of the ports of the Output step. customData1 and customData2 are custom ports, with 3 and 2 columns in their respective output data. Therefore, the number of elements in custom output data is 5 (3 + 2).

Port name

poses

labels

customData1

customData2

Output 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]

]

Number of rows (i.e. number of items in the list)

2

2

2

2

Number of columns (i.e. number of elements in each item of the list)

7

1

3

2

Output Parameters

MM_LastData

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.

MM_Status

This parameter indicates the name of the variable for storing the command execution status code. If the command successfully obtained the Vision Move data from the Mech-Vision project, the status code is 1103. If the command successfully obtained the Vision Move data or custom data from the project, the status code is Mech-Vision2100Mech-Vision. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.

Is_Visual_move

This parameter indicates the sequence number of the Vision Move waypoint (i.e., the waypoint corresponding to the “Vision Move” Step) in the planned path. The data type is num. If the path does not contain a “Vision Move” waypoint, the value of this parameter is 0.

For example, if the planned path consists of the following waypoints: "Fixed-Point Move_1", "Fixed-Point Move_2", "Vision Move", "Fixed-Point Move_3", the sequence number of the Vision Move waypoint is 3.

MM_MoveType

This parameter stores the motion type of the waypoint, valid values are 1 or 2.

  • 1: Joint motion (MOVEJ)

  • 2: Linear motion (MOVEL)

MM_UserDataNum

This parameter stores the number of custom elements, takes a value of 0 or a positive integer.

Example

CALL: MM_Status, MM_LastData, MM_Is_Visual_move, MM_MoveType, MM_UserDataNum := MM_Get_PlanData(0, 4);
CALL: MM_Pose[1], MM_Label[1], MM_Tool[1] := MM_Get_Pose(1);

This example indicates that when the Mech-Viz project’s vision motion-planning data or user-defined data are retrieved, the instruction’s execution status code is stored to MM_Status; the position index of the vision-motion waypoint within the path is stored to MM_Is_Visual_move; the waypoint motion type is stored to MM_MoveType; the number of user-defined data items is stored to MM_UserDataNum; the user-defined data are stored to MM_UserData; the vision motion-planning data are stored to MM_PlanData; the tool pose is stored to MM_Pose; and the end-effector tool ID is stored to MM_Tool.

Get Message from Notify Step

Command

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.

      notify 1

    2. Select Trigger Control Flow Given Output in the parameter panel of the Output Step.

      notify 5

    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.

      notify 2

  • For a Notify Step in the Mech-Viz project:

    1. Connect the Notify Step to a proper Step in the workflow.

      notify 3

    2. In the parameter panel of the Notify Step, select Standard Interface. Enter a positive integer for Message, for example, 1000.

      notify 4

Calling Sequence

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

Command Format

MM_Get_Notify()

Output Parameters

MM_Msg

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

When the Notify Step is executed in the Mech-Vision or Mech-Viz project, the message remains in the buffer of the vision system for only three seconds. Therefore, you should consider the timing of calling this command to ensure successful message retrieval.

Example

CALL: MM_Msg := MM_Get_Notify();

In the preceding example, the message obtained from the Notify Step is stored in MM_Msg.

Calibration

Command

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 EFORT Automatic Calibration.

Command Format

MM_Calibration(Move_Type, Pos_Jps, Wait_Time)

Input Parameters

MOVE_TYPE

This parameter indicates the motion type of the robot. Valid values: 1 and 2.

  • 1: Linear motion (MOVEL)

  • 2: Joint motion (MOVEJ)

Pos_Jps

This parameter specifies the type of calibration point poses to be obtained. Valid values: 1 and 2.

  • 1: TCP

  • 2: Joint positions

Wait_Time

This parameter specifies the time the robot waits to avoid shaking after it moves to the calibration point.

Output Parameters

MM_Status

This parameter indicates the name of the variable for storing the command execution status code. Status code 7101 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.

Example

CALL: MM_Calibration(2, 2, 2);

In the preceding example, the robot moves to the calibration point based on the joint positions of the robot and then waits for 2 seconds.

Is this page helpful?

You can give a feedback in any of the following ways:

We Value Your Privacy

We use cookies to provide you with the best possible experience on our website. By continuing to use the site, you acknowledge that you agree to the use of cookies. If you decline, a single cookie will be used to ensure you're not tracked or remembered when you visit this website.

  • Preference
  • I accept
  • I don't accept