EFORT Standard Interface Commands

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

■ If you're unsure about the version of the product you are using, please contact Mech-Mind Technical Support for assistance.

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.

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

Obtain Vision Results

Obtain the Path Planned by Mech-Vision

Store Vision Results or Planned Paths (Tool Pose)

Store Planned Paths (Joint Positions)

Obtain Custom Data from Mech-Vision

Obtain Suction-Cup DO Signals

Obtain Notification Messages

Calibration

Pass Object Dimensions into Mech-Vision

Initialize Communication

Establish TCP Communication

Close TCP Communication

Run Mech-Viz Project

Set the Message-Branch Exit of Mech-Viz

Set the Current Index of Mech-Viz

Obtain the Path Planned by Mech-Viz

Store Vision Results or Planned Paths (Tool Pose)

Store Planned Paths (Joint Positions)

Read Step Parameter Values of Mech-Viz

Set Step Parameter Values of Mech-Viz

Obtain Vision-Move Planning Data or Custom Data

Obtain Suction-Cup DO Signals

Obtain Notification Messages

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 command is used to set the socket number for communication with the robot.

Calling Sequence

This command must be called before Establish TCP Communication.

Command Format

MM_Init_Socket(Port)

Input Parameters

Port

This parameter indicates the socket number and must be consistent with the Socket Number set in the figure below.

Establish TCP Communication

This command is used to establish the TCP communication connection between the robot and the vision system.

Command Format

MM_Open_Socket()

Calling Sequence

This command must be called after Initialize Communication.

Close TCP Communication

This command is used to disconnect the TCP communication connection between the robot and the vision system.

Calling Sequence

After obtaining the result of the Mech-Vision or Mech-Viz project, you can immediately call this command to disconnect communication, and then store the obtained result into specified variables.

Command Format

MM_Close_Socket()

Run Mech-Vision Project

Function Description

This command is used to trigger the Mech-Vision project to run. While the Mech-Vision project is running, the vision system captures images and performs a series of vision algorithms on the image data, finally obtaining a series of vision points or path points.

Vision point: An object recognized by Mech-Vision. A vision point includes information such as object pose, label, object dimensions, and custom data.
Path point: A point that the robot reaches one by one along the planned path. A path point includes information such as robot pose, label, and motion type.

Calling Sequence

Step parameters in the project need to be set before the Mech-Vision project runs, so Switch Mech-Vision Parameter Recipe or Pass Object Dimensions into Mech-Vision must be called before Run Mech-Vision Project.
The vision system obtains vision points or path points only after the Mech-Vision project runs, so Run Mech-Vision Project must be called before Obtain Vision Results, Obtain the Path Planned by Mech-Vision, or Obtain Custom Data from Mech-Vision.

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 indicates the number of vision points or path points expected from the Mech-Vision project. The value can be 0 or a positive integer, as described below.

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

0: Obtain all vision points or path points from the Mech-Vision project.
Positive integer: Obtain the specified number of vision points or path points from the Mech-Vision project.
- If the total number of output vision points or path points is smaller than the specified value, all output vision points or path points are obtained.
- If the total number of output vision points or path points is greater than or equal to the specified value, the specified number of vision points or path points is obtained.

Run Mech-Vision Project does not return vision points or path points. Vision points are returned by Obtain Vision Results or Obtain Custom Data from Mech-Vision, and path points are returned by Obtain the Path Planned by Mech-Vision.
By default, the vision system sends up to 20 vision points or path points at a time. 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.

SendPos_Type

This parameter specifies how the pose of the real robot is passed into the Mech-Vision project. Valid values are 0, 1, 2, or 3, as shown in the following table.

SendPos_Type	Description	Applicable scenario
0	This command does not need to pass the robot pose to the Mech-Vision project. If the Mech-Vision project uses a "Path Planning" Step, the starting point of path planning is the Home point set in the path-planning tool.	Use this setting when the camera is mounted in Eye to Hand mode and the project does not require advance image capture.
1	This command needs to pass the robot’s current joint positions and flange pose into the Mech-Vision project.	This setting must be used when the camera is mounted in Eye in Hand mode. This setting is recommended for most scenarios except those using gantry robots.
2	This command needs to pass the robot’s current flange pose into the Mech-Vision project.	This setting is recommended when gantry robots are used.
3	This command needs to pass user-defined joint positions into the Mech-Vision project. These joint positions are sent to the "Path Planning" Step in Mech-Vision as the start point, that is, the robot moves from this start point to the first path point of path planning.	Use this setting when the camera is mounted in Eye to Hand mode and the project requires advance image capture.

SendPos_Type

Description

Applicable scenario

This command does not need to pass the robot pose to the Mech-Vision project.

If the Mech-Vision project uses a "Path Planning" Step, the starting point of path planning is the Home point set in the path-planning tool.

Use this setting when the camera is mounted in Eye to Hand mode and the project does not require advance image capture.

This command needs to pass the robot’s current joint positions and flange pose into the Mech-Vision project.

This setting must be used when the camera is mounted in Eye in Hand mode.

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

This command needs to pass the robot’s current flange pose into the Mech-Vision project.

This setting is recommended when gantry robots are used.

This command needs to pass user-defined joint positions into the Mech-Vision project.

These joint positions are sent to the "Path Planning" Step in Mech-Vision as the start point, that is, the robot moves from this start point to the first path point of path planning.

Use this setting when the camera is mounted in Eye to Hand mode and the project requires advance image capture.

MM_J

This parameter indicates user-defined joint-position data.

If SendPos_Type is 3, these joint positions are sent to the "Path Planning" Step in Mech-Vision as the start point.
If SendPos_Type is not 3, these joint positions have no practical use here, but must still be set.

Output Parameters

MM_Status

This parameter stores the command execution status code. If the command is executed normally, the status code is 1102. 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);

The preceding example means running Mech-Vision project 1 and expecting the project to return 1 vision point, while the robot passes its current joint and flange data into the Mech-Vision project.

Obtain Vision Results

Function Description

This command is used to obtain vision results output by Mech-Vision (a series of vision points). The object poses of the vision points (that is, the pose data of the poses port of the Output Step) are automatically converted by the vision system into tool poses corresponding to the robot, as shown below.

If the first input port of the Output Step is Object Center Point, the Output Step converts the Object Center Point into the corresponding Pick Point. Therefore, the pose obtained through this command is actually the pose of the pick point rather than the pose of the object center point.

Convert the object pose from a quaternion to Euler angles.
Rotate the object’s pose around the X-axis by 180° to orient its Z-axis downward.

Calling Sequence

This command must be called after Run Mech-Vision Project. After using this command, call Store Vision Results or Planned Paths (Tool Pose) 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.

MM_LastData

This parameter indicates whether all vision points have been obtained. Its value is 0 or 1.

0: Not all vision points have been obtained.
1: All vision points have been obtained.

MM_Status

This parameter stores the command execution status code. If the command is executed normally, the status code is 1100. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.

Example

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

The preceding example means obtaining the vision result of Mech-Vision project 1.

Store Vision Results or Planned Paths (Tool Pose)

Function Description

This command is used to store the tool pose, label, and end-tool ID of a vision point or path point into specified variables.

Command Format

MM_Get_Pose(Index)

Input Parameters

Index

This parameter specifies the index of a vision point or path point, that is, the tool pose, label, and end-tool ID of the corresponding vision point or path point are stored into specified variables. Indexes start from 1.

Output Parameters

MM_Pose[Index]

This parameter stores the tool pose of the specified indexed vision point or path point.

MM_Label[Index]

This parameter stores the label of the specified indexed vision point or path point.

MM_Tool[Index]

This parameter stores the end-tool ID of the specified indexed vision point or path point.

Example

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

The preceding example means that the tool pose of the first vision point or path point is stored in MM_Pose[1], the label is stored in MM_Label[1], and the end-tool ID is stored in MM_Tool[1].

Store Planned Paths (Joint Positions)

Function Description

This command is used to store the joint positions, label, and end-tool ID of a path point into specified variables.

Command Format

MM_GET_JPS(Index)

Input Parameters

Index

This parameter specifies the index of a path point, that is, the joint positions, label, and end-tool ID of the corresponding path point are stored into specified variables. Indexes start from 1.

Output Parameters

MM_JPS[Index]

This parameter stores the joint positions of the specified indexed path point.

MM_Label[Index]

This parameter stores the label of the specified indexed path point.

MM_Tool[Index]

This parameter stores the end-tool ID of the specified indexed path point.

Example

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

The preceding example means that the joint positions of the first path point are stored in MM_JPS[1], the label is stored in MM_Label[1], and the end-tool ID is stored in MM_Tool[1].

Switch Mech-Vision Parameter Recipe

Function Description

This command is used to switch the parameter recipe used by a Mech-Vision project. The figure below shows manually switching recipe A or recipe B for a Mech-Vision project. For more information about parameter recipes, see Parameter Recipe.

Calling Sequence

This command must 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 how to view the parameter recipe ID, see View the Parameter Recipe ID.

Output Parameters

MM_Status

This parameter stores the command execution status code. If the command is executed normally, the status code is 1107. 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);

The preceding example means switching the parameter recipe of Mech-Vision project 1 to recipe 1.

Obtain the Path Planned by Mech-Vision

Function Description

This command is used to obtain the path planned by Mech-Vision (a series of path points). The path here is planned by the "Path Planning Tool" entered from the Configuration Wizard shown below. For related content of the Path Planning Step, see Path Planning.

The Port Type parameter of the Output Step in Mech-Vision needs to be set to "Predefined (Robot Path)".

Calling Sequence

This command must be called after Run Mech-Vision Project. After using this command, call Store Vision Results or Planned Paths (Tool Pose) or Store Planned Paths (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.

1: joint positions. After you run this command, run Store Planned Paths (Joint Positions) to access joint position data.
2: tool poses. After you run this command, run Store Vision Results or Planned Paths (Tool Pose) to access tool pose data.

Output Parameters

MM_LastData

This parameter indicates whether all path points have been obtained. Its value is 0 or 1.

0: Not all path points have been obtained.
1: All path points have been obtained.

MM_POS_NUM

This parameter stores the number of path points returned by the vision system. By default, the maximum number of path points sent by the vision system at a time is 20, so the default maximum 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.

Before calling Obtain the Path Planned by Mech-Vision, make sure to set Pos_Number_Need of Run Mech-Vision Project to 0 to reduce the number of times Obtain the Path Planned by Mech-Vision needs to be called. If Pos_Number_Need of Run Mech-Vision Project is set to 1, each call to Obtain the Path Planned by Mech-Vision gets only one path point, and multiple calls are required to obtain all path points.

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 stores the command execution status code. If the command is executed normally, the status code is 1103. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.

Example

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

The preceding example means obtaining the planned path returned by Mech-Vision project 1. The pose form of path points is tool pose, the number of path points is stored in MM_POS_NUM, the position index of the Vision Move path point is stored in MM_VisPosNum, and the command execution status code is stored in MM_Status.

Obtain Custom Data from Mech-Vision

Function Description

This command is used to obtain data from the custom ports of the Output Step in Mech-Vision. Each call of this command can obtain the custom data of 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.

Data output from Predefined Keys, such as poses, labels, sizes, offsets, is not custom data.
You must set Port Type of the Output Step to Custom and select the poses port in the Predefined Keys section in Mech-Vision.

Calling Sequence

This command must be called after Run Mech-Vision Project. After using this command, call Store Vision Results or Planned Paths (Tool Pose) to obtain the pose, label, and end-tool ID of a vision point.

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

MM_LastData

This parameter indicates whether all vision points have been obtained. Its value is 0 or 1.

0: Not all vision points have been obtained.
1: All vision points have been obtained.

MM_UserDataNum

This parameter stores the number of custom data items. Custom data is stored in variable MM_UserData.

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 preceding example means obtaining custom data from Mech-Vision project 1. The custom data is stored in MM_UserData, the tool pose is stored in MM_Pose[1], and the label is stored in MM_Label[1].

Pass Object Dimensions into Mech-Vision

Function Description

This command is used to pass object dimensions into a Mech-Vision project. The passed object dimensions are the values of the Box Dimension Settings parameter of the "Read Object Dimensions" Step, as shown below.

When using this command, there can be only one "Read Object Dimensions" Step in the Mech-Vision project. Otherwise, the vision system returns an error.

Calling Sequence

This command must be called before 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

These three parameters indicate the object dimensions passed into the Mech-Vision project (length, width, and height respectively, in millimeters). The dimension values are read by the "Read Object Dimensions" Step and written into Length Along X-axis, Length Along Y-axis, and Length Along Z-axis respectively.

Output Parameters

MM_Status

This parameter stores the command execution status code. If the command is executed normally, the status code is 1108. 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);

The preceding example means setting the object dimensions of the "Read Object Dimensions" Step in the Mech-Vision project to 500 脳 300 脳 200 mm.

Run Mech-Viz Project

Function Description

This command is used to trigger the Mech-Viz project to run. Mech-Viz plans the robot motion path based on the vision results output by Mech-Vision.

In the Resource panel of the Mech-Viz project, right-click the project name and select Set to Auto Load.

Calling Sequence

Step parameters in the project need to be set before triggering the Mech-Viz project, so Read Step Parameter Values of Mech-Viz or Set Step Parameter Values of Mech-Viz must be called before Run Mech-Viz Project.

Command Format

MM_Start_Viz(SendPos_Type, MM_J)

Input Parameters

SendPos_Type

This parameter specifies how the pose of the real robot is passed into the Mech-Viz project. Valid values are 0, 1, or 2, as described below.

SendPos_Type	Description	Applicable scenario
0	This command does not need to pass the robot pose into the Mech-Viz project. The simulated robot in Mech-Viz moves from the configured Home point to the first path point.	The camera is mounted in Eye to Hand mode.
1	This command needs to pass the robot’s current joint positions and flange pose into the Mech-Viz project. The simulated robot in Mech-Viz moves from the passed joint positions to the first path point.	The camera is mounted in Eye in Hand mode. This setting is recommended.
2	This command needs to pass one taught point of the robot (not the current joint positions but custom joint positions) into the Mech-Viz project, so that when the robot is outside the image-capture area, the next round of path planning can be triggered in advance, as shown below. The simulated robot in Mech-Viz starts moving from the passed taught point to the first path point.	The camera is mounted in Eye to Hand mode. This setting is recommended.

SendPos_Type

Description

Applicable scenario

This command does not need to pass the robot pose into the Mech-Viz project. The simulated robot in Mech-Viz moves from the configured Home point to the first path point.

The camera is mounted in Eye to Hand mode.

This command needs to pass the robot’s current joint positions and flange pose into the Mech-Viz project. The simulated robot in Mech-Viz moves from the passed joint positions to the first path point.

The camera is mounted in Eye in Hand mode. This setting is recommended.

This command needs to pass one taught point of the robot (not the current joint positions but custom joint positions) into the Mech-Viz project, so that when the robot is outside the image-capture area, the next round of path planning can be triggered in advance, as shown below. The simulated robot in Mech-Viz starts moving from the passed taught point to the first path point.

The camera is mounted in Eye to Hand mode. This setting is recommended.

Why is Robot Pose Type 2 recommended when the camera is mounted in Eye to Hand mode?

In the following figure, the robot is working in the placement area.

If SendPos_Type is set to 1 in this scenario, the current robot pose is sent to Mech-Viz. The real robot may move to other positions before moving to the first path point. The simulated robot moves directly from the current position to the first path point in the Mech-Viz project, and collision may be detected during this motion, causing a warning.

If SendPos_Type is set to 2, the taught image-capture point configured on the robot side is sent to Mech-Viz. In this way, the real robot can trigger Mech-Viz in advance from the placement area to plan the next path, thereby shortening the cycle time.

This is why Robot Pose Type 2 is recommended in Eye to Hand mode.

MM_J

This parameter indicates user-defined joint-position data.

If SendPos_Type is 2, these joint positions are sent to the Mech-Viz project as the start point.
If SendPos_Type is not 2, these joint positions have no practical use here, but must still be set.

Output Parameters

MM_Status

This parameter stores the command execution status code. If the command is executed normally, the status code is 2103. 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);

The preceding example means passing the current joint positions and flange pose of the robot into the Mech-Viz project and then running the Mech-Viz project.

Stop Mech-Viz Project

Function Description

This command is used to stop a running Mech-Viz project.

Calling Sequence

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

Command Format

MM_Stop_Viz()

Output Parameters

MM_Status

This parameter stores the command execution status code. If the command is executed normally, the status code is 2104. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.

Example

CALL: MM_Status := MM_Stop_Viz()

The preceding example means stopping the running Mech-Viz project.

Set the Message-Branch Exit of Mech-Viz

Function Description

This command is used to set the exit of a Message Branch Step. When the Mech-Viz project runs to the Message Branch Step, it waits for this command to specify the exit.

Calling Sequence

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

Command Format

MM_Set_Branch(Branch_ID, Branch_Port)

Input Parameters

Branch_ID

This parameter specifies the step ID of the Message Branch Step. The value is a positive integer. The step ID can be viewed in the step parameters. For example, the step ID in the figure above is 1.

Branch_Port

This parameter specifies the exit number of the Message Branch Step. The value is a positive integer. If this parameter is set to N, the Mech-Viz project continues from exit N-1 of the Message Branch Step.

Output Parameters

MM_Status

This parameter stores the command execution status code. If the command is executed normally, the status code is 2105. 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);

The preceding example means that at Message Branch Step 1, the Mech-Viz project continues from exit 2.

Set the Current Index of Mech-Viz

Function Description

This command is used to set the current index value of an index-type step. Index-type steps are steps that contain an "Index" parameter, such as "Move by Array", "Move by Sequence", "Custom Pallet Pattern", and "Preset Pallet Pattern".

Calling Sequence

Usually there is a Message Branch Step before an index-type step. On the robot side, first call Run Mech-Viz Project, then Set the Current Index of Mech-Viz, and finally Set the Message-Branch Exit of Mech-Viz. In this way, 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. The value is a positive integer. The step ID can be viewed in step parameters. For example, the step ID in the figure above is 3.

Index_Num

This parameter specifies the current index value of the index-type step. The value is a positive integer. If this parameter is set to N, the current index value of the corresponding step is N-1.

Output Parameters

MM_Status

This parameter stores the command execution status code. If the command is executed normally, the status code is 2106. 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);

The preceding example means setting the current index value of step 2 in the Mech-Viz project to 9.

Obtain the Path Planned by Mech-Viz

Function Description

This command is used to obtain the motion path planned by the Mech-Viz project (a series of path points).

Path point: A point that the robot reaches one by one along the planned path. A path point includes information such as robot pose, label, and motion type. Path points can be divided into the following two types:

Vision Move path point: Path point corresponding to the Vision Move Step.
Non-Vision Move path point: Path point corresponding to move-type steps other than the Vision Move Step.

Calling Sequence

This command must be called after Run Mech-Viz Project. After using this command, call Store Vision Results or Planned Paths (Tool Pose) or Store Planned Paths (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.

1: joint positions. After you run this command, run Store Planned Paths (Joint Positions) to access joint position data.
2: tool poses. After you run this command, run Store Vision Results or Planned Paths (Tool Pose) to access tool pose data.

Output Parameters

MM_Status

This parameter stores the command execution status code. If the command is executed normally, the status code is 2100. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.

MM_LastData

This parameter indicates whether all path points have been obtained. Its value is 0 or 1.

0: Not all path points have been obtained.
1: All path points have been obtained.

MM_POS_NUM

This parameter stores the number of path points returned by the vision system. By default, the vision system sends at most 20 path points at a time, so the default maximum 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.

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 preceding example means obtaining the path planned by the Mech-Viz project, and the pose form of the path points is tool pose.

Read Step Parameter Values of Mech-Viz

Function Description

This command is used to read the parameter value of a specified step in the Mech-Viz project.

Calling Sequence

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

Command Format

MM_Get_property(Config_ID)

Input Parameters

Config_ID

This parameter is the Configuration ID field specified 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

MM_Status

This parameter stores the command execution status code. If the command is executed normally, the status code is 2109. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.

MM_Viz_Prop

This parameter stores the returned parameter value of the specified step.

Example

For example, add the following content to the property_config file, where 5 indicates the configuration ID, 3 indicates the step ID, and xCount indicates the key name.

read,5,3,xCount

After the robot sends the following command, the parameter value corresponding to xCount is obtained.

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

The preceding example means that the value of parameter xCount in step 3 of the Mech-Viz project is stored in MM_Viz_Prop.

Set Step Parameter Values of Mech-Viz

Function Description

This command is used to set the parameter value of a specified step in the Mech-Viz project.

Calling Sequence

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

Command Format

MM_Set_property(Config_ID)

Input Parameters

Config_ID

This parameter is the Configuration ID field specified 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.

Output Parameters

MM_Status

This parameter stores the command execution status code. If the command is executed normally, the status code is 2108. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.

Example

For example, the content of the property_config file is as follows, where 1 indicates the configuration ID, 3 indicates the step ID, xOffset, yOffset, and zOffset are key names, and 10, 20, and 30 are the corresponding parameter values.

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

After the robot sends the following command, Mech-Viz sets the parameter values corresponding to xOffset, yOffset, and zOffset to 10, 20, and 30 respectively.

CALL: MM_Status := MM_Set_property(1);

The preceding example means that the parameter values corresponding to xOffset, yOffset, and zOffset are set to 10, 20, and 30 respectively.

Obtain Suction-Cup DO Signals

Function Description

This command is used to obtain the control signals of multi-zone suction cups planned by the Mech-Vision or Mech-Viz project.

Before using this command, you need to configure the following in Mech-Vision or Mech-Viz.

Configure a Mech-Vision project
- In the Path Planning Step parameters, click Configuration Wizard. In Global Settings, turn on Plan All Vision Results.
- In the Path Planning Step parameters, click Configuration Wizard, double-click the end-tool name, select Depalletizing Suction Cup as Tool Type, click Depalletizing Suction Cup Configuration, and configure DO signals as needed.
Configure a Mech-Viz project
- In Mech-Viz, set Grasp Technique of the Vision Move Step to Box Depalletizing.
- In Mech-Viz, double-click the end-tool name, select Depalletizing Suction Cup as Tool Type, click Depalletizing Suction Cup Configuration, and configure DO signals as needed.

Calling Sequence

This command must be called after Obtain the Path Planned by Mech-Vision, Obtain the Path Planned by Mech-Viz, or Obtain Vision-Move Planning Data or Custom Data. That is, the robot first obtains the motion path and then obtains the suction-cup DO signals corresponding to the Vision Move path point.

Command Format

MM_Get_DoList(Resource, Block_Num)

Input Parameters

Resource

This parameter specifies the source of the DO signal list. Valid values are 0 or positive integers, as follows.

0: Obtain the DO signal list from Mech-Viz.
Positive integer: Obtain the DO signal list from Mech-Vision. The positive integer here is the Mech-Vision project ID.

Block_Num

This parameter is the number of suction-cup zones set in the Suction Cup Configurator. For example, the number of suction-cup zones in the figure above is 3.

Depending on the built project, the DO signals returned by this command differ, as follows.

Suction-cup DO signals planned by a Mech-Vision project

If Plan All Vision Results is off in the global settings of path planning, this command returns 64 DO signals, representing the suction-cup DO signals of the current round of planning. Valid DO signals are non-negative integers in the range 0 to 999. Invalid DO signals are -1, used as placeholder values.

For example, in the following table, the valid DO signals returned are 1, 3, 5, and 6, which means the robot needs to set the corresponding DO signals to ON.

1st

2nd

3rd

4th

5th

6th

7th

8th

鈥?

63rd

64th

1

3

5

6

-1

-1

-1

-1

鈥?

-1

-1

If Plan All Vision Results is on, Mech-Vision can perform multiple rounds of planning based on the same vision result. The 64 DO signals returned by this command are the suction-cup DO signals for all planning rounds. At this time, the number of suction-cup zones can be used to distinguish the DO signals of each planning round.

For example, if the number of suction-cup zones is 4, this command returns 64 DO signals in total, where every 4 DO signals represent the multi-zone suction-cup control signals of one planning round.

Round 1 planning				Round 2 planning				鈥?	Round 16 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

Suction-cup DO signals planned by a Mech-Viz project

If Reuse Vision Results is not selected in the Vision Move Step, this command returns 64 DO signals, representing the suction-cup DO signals of the current round of planning. Valid DO signals are non-negative integers in the range 0 to 999, and invalid DO signals are -1 placeholders.

For example, in the following table, the valid DO signals returned are 1, 3, 5, and 6, which means the robot needs to set the corresponding DO signals to ON.

1st

2nd

3rd

4th

5th

6th

7th

8th

鈥?

63rd

64th

1

3

5

6

-1

-1

-1

-1

鈥?

-1

-1

If Reuse Vision Results is selected in the Vision Move Step, and the Vision Move Step is in a loop process, Mech-Viz can perform multiple rounds of planning based on the same vision result. The 64 DO signals returned by this command are the suction-cup DO signals of all planning rounds. At this time, the number of suction-cup zones can be used to distinguish the DO signals of each planning round.

For example, if the number of suction-cup zones is 4, this command returns 64 DO signals in total, where every 4 DO signals represent the multi-zone suction-cup control signals of one planning round.

Round 1 planning				Round 2 planning				鈥?	Round 16 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 obtained DO signal list.

MM_Status

This parameter stores the command execution status code. If the DO signal list is successfully obtained from Mech-Viz, the status code is 2102. If it 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);

The preceding example means storing the DO signal list obtained from Mech-Viz in MM_Do_Port.

Obtain Vision-Move Planning Data or Custom Data

Function Description

This command is used to obtain the vision-move planning data of a Mech-Vision project, or the vision-move planning data or custom data of a Mech-Viz project. Each call of this command obtains related data for only one path point.

The path obtained by this command contains both Vision Move path points and Non-Vision Move path points. In addition to pose and end-tool ID, Vision Move path points also contain vision-move planning data or custom data, which is the main difference from Obtain the Path Planned by Mech-Viz or Obtain the Path Planned by Mech-Vision.
Do not mix this command with Obtain the Path Planned by Mech-Viz or Obtain the Path Planned by Mech-Vision.
This command is only for depalletizing tasks and is not applicable to other picking tasks.

For a Mech-Vision project: the "vision-move planning data" here refers to the data planned by the Vision Move Step in the Path Planning Tool, including the label of the picked workpiece, the total number of picked workpieces, the number of workpieces picked this time, suction-cup corner ID, TCP offset, orientation of the workpiece group, orientation of a single workpiece, and group dimensions.

For a Mech-Viz project:

Vision-move planning data: Data planned by the Vision Move Step in Mech-Viz, including the label of the picked workpiece, total number of picked workpieces, number of workpieces picked this time, suction-cup corner ID, TCP offset, orientation of the workpiece group, orientation of a single workpiece, and group dimensions.

Custom data: Data output from the custom ports of Mech-Vision and then forwarded by Mech-Viz.

Data output from Predefined Keys, such as poses, labels, sizes, offsets, is not custom data.
You must set Port Type of the Output Step to Custom and select the poses port in the Predefined Keys section in Mech-Vision.

Calling Sequence

This command must 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 vision-move planning data. Valid values are 0 or positive integers, as follows.

0: Obtain vision-move planning data from Mech-Viz.
Positive integer: Obtain vision-move planning data from Mech-Vision. The positive integer here is the Mech-Vision project ID.

Pose_Type

This parameter indicates the expected return data format.

When Job is 0, valid values of Pose_Type are 1 to 4, as follows.

Pose_Type value

Description of expected returned data (see below for details of each field; if the Mech-Vision project has no custom ports, there is no custom data item)

Path-point type

Data information

Non-Vision Move path point

Pose (joint positions), move type, end-tool ID

Vision Move path point

Pose (joint positions), move type, end-tool ID, custom data item 1, …, custom data item N

Non-Vision Move path point

Pose (tool pose), move type, end-tool ID

Vision Move path point

Pose (tool pose), move type, end-tool ID, custom data item 1, …, custom data item N

Non-Vision Move path point

Pose (joint positions), move type, end-tool ID

Vision Move path point

Pose (joint positions), move type, end-tool ID, Mech-Viz vision-move planning data, custom data item 1, …, custom data item N

Non-Vision Move path point

Pose (tool pose), move type, end-tool ID

Vision Move path point

Pose (tool pose), move type, end-tool ID, Mech-Viz vision-move planning data, custom data item 1, …, custom data item N

When Job is a positive integer, valid values of Pose_Type are 1 to 2, as follows.

Pose_Type value

Description of expected returned data (see below for details of each field)

Path-point type

Data information

Non-Vision Move path point

Pose (joint positions), move type, end-tool ID

Vision Move path point

Pose (joint positions), move type, end-tool ID, Mech-Vision vision-move planning data

Non-Vision Move path point

Pose (tool pose), move type, end-tool ID

Vision Move path point

Pose (tool pose), move type, end-tool ID, Mech-Vision vision-move planning data

Pose

The pose of a path point can be robot joint positions (unit: degree) or tool pose (3D coordinates in millimeters and Euler angles in degrees).

After calling MM_Get_PlanData, use Store Vision Results or Planned Paths (Tool Pose) or Store Planned Paths (Joint Positions) to obtain the pose, label, and end-tool ID.

Move type

Robot move type. The value is 1 or 2 and is stored in variable MM_MoveType.

1: Joint motion.
2: Linear motion.

End-tool ID

The end-tool ID of a path point. If the value is -1, it means no end tool is used.

After calling MM_Get_PlanData, use Store Vision Results or Planned Paths (Tool Pose) or Store Planned Paths (Joint Positions) to obtain the pose, label, and end-tool ID.

Vision-move planning data

The data planned by the Vision Move Step in Mech-Vision or Mech-Viz, including the label of the picked workpiece, total number of picked workpieces, number of workpieces picked this time, suction-cup corner ID, TCP offset, orientation of the workpiece group, orientation of a single workpiece, and group dimensions. Vision-move planning data is stored in MM_PlanData.

Name	Description	Dimension
Label of the picked workpiece	Consists of 10 integers and defaults to 10 zeros	10
Total number of picked workpieces	Cumulative number of picked workpieces	1
Number of workpieces picked this time	Number of workpieces picked this time	1
Suction-cup corner ID	Corner ID used by the suction cup this time	1
TCP offset	XYZ offset of the center of the workpiece group relative to the center of the end tool	3
Orientation of the workpiece group	Orientation relationship between the workpiece group and the long side of the suction cup. 0 means parallel and 1 means perpendicular.	1
Orientation of a single workpiece	Orientation relationship between the long side of a single workpiece and the long side of the suction cup. 0 means parallel and 1 means perpendicular.	1
Group dimensions	Length, width, and height of the workpiece group picked this time	3

Name

Description

Dimension

Label of the picked workpiece

Consists of 10 integers and defaults to 10 zeros

Total number of picked workpieces

Cumulative number of picked workpieces

Number of workpieces picked this time

Suction-cup corner ID

Corner ID used by the suction cup this time

TCP offset

XYZ offset of the center of the workpiece group relative to the center of the end tool

Orientation of the workpiece group

Orientation relationship between the workpiece group and the long side of the suction cup. 0 means parallel and 1 means perpendicular.

Orientation of a single workpiece

Orientation relationship between the long side of a single workpiece and the long side of the suction cup. 0 means parallel and 1 means perpendicular.

Group dimensions

Length, width, and height of the workpiece group picked this time

Custom data item

This parameter stores the number of custom data items. Custom data is stored in MM_UserData.

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 indicates whether all path points have been obtained. Its value is 0 or 1.

0: Not all path points have been obtained.
1: All path points have been obtained.

MM_Status

This parameter stores the command execution status code. If the vision-move planning data of a Mech-Vision project is obtained successfully, the status code is 1103. If the vision-move planning data or custom data of a Mech-Viz project is obtained successfully, the status code is 2100. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.

Is_Visual_move

This parameter indicates the position index of the path point corresponding to the Vision Move Step in the path. Data type: num. If there is no Vision Move path point in the path, this parameter is 0.

For example, if the planned path consists of the following path points: "Fixed-Point Move_1", "Fixed-Point Move_2", "Vision Move", and "Fixed-Point Move_3", then the position index of the Vision Move path point is 3.

MM_MoveType

This parameter stores the move type of the path point. Its value is 1 or 2.

1: Joint motion.
2: Linear motion.

MM_UserDataNum

This parameter stores the number of custom data items. Its value is 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);

The preceding example means obtaining the vision-move planning data or custom data of the Mech-Viz project. The command execution status code is stored in MM_Status, the position index of the Vision Move path point is stored in MM_Is_Visual_move, the move type of the path point is stored in MM_MoveType, the number of custom data items is stored in MM_UserDataNum, custom data is stored in MM_UserData, vision-move planning data is stored in MM_PlanData, the tool pose is stored in MM_Pose, and the end-tool ID is stored in MM_Tool.

Obtain Notification Messages

Function Description

When a Mech-Vision or Mech-Viz project runs to a Notify Step, the vision system returns the message preset in that Notify Step.

Before using this command, the Notify Step must meet the following settings.

Notify Step in a Mech-Vision project
1. Connect the Notify Step to the right side of another step (the Output Step is used as an example here).
2. In the step parameters of the Output Step, select Trigger Control Flow When Output Exists.
3. In the step parameters of the Notify Step, set the service name to Standard Interface Notify (cannot be changed), and set the message to 1001 (set as required, but it must be a positive integer).
Notify Step in a Mech-Viz project
1. Connect the Notify Step at an appropriate position in the workflow.
2. In the step parameters of the Notify Step, select Standard Interface, and set the message to 1000 (set as required, but it must be a positive integer).

Calling Sequence

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

Command Format

MM_Get_Notify()

Output Parameters

MM_Msg

This parameter stores the notification message (currently only positive integers are supported).

When the Mech-Vision or Mech-Viz project runs to the Notify Step, the configured message is cached in the vision system for only 3 seconds. Therefore, you need to control the call timing of this command appropriately to obtain the message content.

Example

CALL: MM_Msg := MM_Get_Notify();

The preceding example means that the message obtained from the Notify Step is stored in MM_Msg.

Calibration

Function Description

This command is used for hand-eye calibration (extrinsic calibration) of the robot. This command must be used together with Camera Calibration in the toolbar of Mech-Vision to realize automatic calibration. For details, see EFORT Automatic Calibration.

Command Format

MM_Calibration(Move_Type, Pos_Jps, Wait_Time)

Input Parameters

MOVE_TYPE

This parameter indicates the robot move type. Valid values are 1 or 2.

1: Linear motion.
2: Joint motion.

Pos_Jps

This parameter specifies the pose form of the calibration point. Valid values are 1 or 2.

1: Tool pose.
2: Joint positions.

Wait_Time

This parameter indicates the waiting time after the robot moves to the calibration point to prevent robot vibration. Unit: second.

Output Parameters

MM_Status

This parameter stores the command execution status code. If the command is executed normally, the status code is 7101. 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);

The preceding example means that the waiting time after the robot moves to the calibration point in joint-position mode is 2 seconds.

Is this page helpful?

Leave a feedback

Thanks for your support!

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.

I accept

I don't accept