MELFA Standard Interface Commands
This section describes standard interface commands used in TCP communications between a MELFA 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
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.
-
-
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.
|
Calling Sequence
-
You should set Step parameters before starting a Mech-Vision project. Therefore, call Switch Mech-Vision Parameter Recipe or Input Object Dimensions to Mech-Vision Project before calling Run Mech-Vision Project.
-
Vision system gets vision points and waypoints only after a Mech-Vision project runs. Therefore, call Run Mech-Vision Project before calling Get Vision Result, Get Planned Path in Mech-Vision, or Get Mech-Vision Custom Data.
Command Format
MM_START_VIS(MM_ProjID,MM_ExpVal,MM_RbtPose,JntSend,MM_Status)Input Parameters
MM_ProjID
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.
MM_ExpVal
This parameter indicates 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.
-
|
MM_RbtPose
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.
| MM_RbtPose | 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. |
|
JntSend
This parameter specifies the custom joint positions.
-
If MM_RbtPose 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 MM_RbtPose is set to a parameter value other than 3, the joint positions are of no practical use but must be set.
Example
MM_START_VIS(1,1,1,JntSend,MM_Status)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. In this example, JntSend has no practical use, but the ID of this variable must be set.
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. |
-
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 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_VIS(MM_ProjID,MM_SentPt,MM_VisionPt_Num,MM_Status,MM_Result())Input Parameters
MM_ProjID
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.
MM_SendPt
This parameter specifies the maximum number of positions sent in a single transmission, with an upper limit of 5.
Output Parameters
MM_VisionPt_Num
This parameter stores the number of vision points returned by Mech-Vision.
MM_Status
This parameter stores the command status code.
MM_Result()
This parameter is the vision result, representing a series of vision points. Its data type is a 2D array numeric variable.
|
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 > in the toolbar of Mech-Vision. 
|
Example
Dim MM_Result(10,8) MM_GET_VIS(1,5,MM_VisionPt_Num,MM_Status,MM_Result)The above example indicates that up to 5 vision results from Mech-Vision Project 1 are acquired, the number of vision points is stored in <MM_VisionPt_Num>, and the command execution status code is stored in <MM_Status>. A maximum of 10 output vision results (a sequence of vision points) will be stored in the array variable <MM_Result>.
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_POS(MM_Result(),MM_Serial,PosSave,MM_Label,MM_ToolID)Input Parameters
MM_Result()
This parameter is the vision result, representing a series of vision points. Its data type is a 2D array numeric variable.
MM_Serial
This parameter specifies the index number of a vision point or waypoint, i.e., it copies the tool pose, label, and end‑effector tool number corresponding to that index into the specified variable. Indexes start from 1.
Output Parameters
PosSave
This parameter stores the TCP of the vision point or waypoint that corresponds to the index.
MM_Label
This parameter stores the label of the vision point or waypoint that corresponds to the index.
MM_ToolID
This parameter stores the tool ID of the vision point or waypoint that corresponds to the index.
Example
Dim MM_Result(10, 8) MM_GET_VIS(1, 3, MM_Status, MM_VisionPt_Num, MM_Result) MM_GET_POS(MM_Result, 2, PosSave, MM_Label, MM_ToolID)After executing the sample code above, the tool pose of the second vision point or waypoint will be stored in the position variable <PosSave>, the label will be stored in the numeric variable <MM_Label>, and the tool ID will be stored in the numeric variable <MM_ToolID>.
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_JNT(MM_Result(),MM_Serial,JntSave,MM_Label,MM_ToolID)Input Parameters
MM_Result()
This parameter is the vision result, representing a series of vision points. Its data type is a 2D array numeric variable.
MM_Serial
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.
Example
Dim MM_Result(10, 8) MM_GET_VIS(1, 3, MM_Status, MM_VisionPt_Num, MM_Result) MM_GET_JNT(MM_Result, 2, JntSave, MM_Label, MM_ToolID)After executing the sample code above, the joint angles of the second waypoint will be stored in the joint variable <JntSave>, the label will be stored in the numeric variable <MM_Label>, and the tool ID will be stored in the numeric variable <MM_ToolID>.
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.
Calling Sequence
This command should be called before Run Mech-Vision Project.
Command Format
MM_SET_MOD(MM_ProjID,MM_ParamID,MM_Status)Input Parameters
MM_ProjID
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.
MM_ParamID
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.
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). |
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_VISP(MM_ProjID,MM_WpPose,MM_SendPt,MM_Status,MM_WayPt_Num,MM_VPos_Num,MM_Result())Input Parameters
MM_ProjID
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.
MM_WpPose
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 Path (joint positions) to access joint position data.
-
2: tool poses. After you run this command, run Store Vision Result or Planned Path (TCP) to access tool pose data.
MM_SendPt
This parameter specifies the maximum number of positions sent in a single transmission, with an upper limit of 5.
Output Parameters
MM_WayPt_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 > in the toolbar of Mech-Vision. The upper limit is 30.
| Before you call Get Planned Path in Mech-Vision, set MM_ExpVal of Run Mech-Vision Project to 0 to reduce the number of Get Planned Path in Mech-Vision calls. If MM_ExpVal 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_VPos_Num
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.
MM_Result()
This parameter is the vision result, representing a series of vision points. Its data type is a 2D array numeric variable.
|
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 > in the toolbar of Mech-Vision.
|
Example
Dim MM_Result(10, 8) MM_GET_VISP(1,2,5,MM_Status,MM_WayPt_Num,MM_VPos_Num,MM_Result)In the preceding example, the planned path of the Mech-Vision project No.1 is returned and specifying that the waypoint pose type is a tool pose. The number of waypoints is stored in <MM_VisionPt_Num>; The position index within the overall path of the waypoint used for vision‑guided motion is stored in <MM_VPos_Num>; The command execution status code is stored in <MM_Status>. A maximum of 10 output vision results (a sequence of vision points) will be stored in the array variable <MM_Result>.
Get Mech-Vision Custom Data
Command
This command obtains data from the custom port(s) of the Output Step in Mech-Vision. One command call saves all port data of the Output Step to robot memory.
Select the Output Step, set Port Type to Custom, and then click Open the editor to go to the custom port configuration window. The Customized Keys section of the window displays custom port names, such as customeData1 and customeData2 as shown in the following figure.
|
Calling Sequence
This command should be called after Run Mech-Vision Project. After you call this command, call Store Mech-Vision Custom Data to access custom data.
Command Format
MM_GET_CUST(MM_ProjID,MM_Status,MM_VisionPt_Num,MM_CustInfo_Num,MM_Result(),MM_CustInfo())Input Parameters
MM_ProjID
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_VisionPt_Num
This parameter stores the number of vision points returned by Mech-Vision.
MM_CustInfo_Num
This parameter stores the total number of acquired custom data items.
MM_CustInfo()
This parameter holds custom data and is defined as a two-dimensional numeric array variable.
MM_Result()
This parameter is the vision result, representing a series of vision points. Its data type is a 2D array numeric variable.
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
Dim MM_Result(10,8) Dim MM_CustInfo(10,15) MM_GET_CUST(2,MM_Status,MM_VisionPt_Num,MM_CustInfo_Num,MM_Result,MM_CustInfo)The above example demonstrates how to obtain the vision result in Mech-Vision Project 2. The number of returned vision points is stored in <MM_VisionPt_Num>; the command execution status code is stored in <MM_Status>; the number of received user‑defined data items is stored in <MM_Result>; the custom data count is stored in <MM_CustInfo_Num>; the custom data are stored in <MM_CustInfo>.
|
The custom port outputs are arranged in the alphabetical order of the names of custom ports. For example, the custom data ports are named as follows:
The transmitted data will be sorted alphabetically by custom name as follows: …aData, bData, cData… |
Store Mech-Vision Custom Data
Calling Sequence
This command should be called after Get Mech-Vision Custom Data.
Command Format
MM_GET_CUSTP(MM_Result(),MM_CustInfo_Num,MM_CustInfo(),MM_Serial,PosSave,MM_Label,MM_CustData())Input Parameters
MM_Serial
This parameter specifies the index of the vision point. The custom data of the vision point that corresponds to the index is stored in the variable. Indexes start from 1.
MM_Result()
This parameter is the vision result, representing a series of vision points. Its data type is a 2D array numeric variable.
MM_CustInfo_Num
This parameter stores the total number of acquired custom data items.
MM_CustInfo()
This parameter holds custom data and is defined as a two-dimensional numeric array variable.
Output Parameters
PosSave
This parameter stores the TCP of the vision point that corresponds to the index.
MM_Label
This parameter stores the label of the vision point that corresponds to the index. If no label ports are specified in Mech-Vision, 0 is used.
MM_CustData()
This parameter stores the custom data of the vision point that corresponds to the specified index. The parameter is a predefined global array variable.
Example
Dim MM_Result(10, 8) MM_GET_CUST(1, 3, MM_Status, MM_VisionPt_Num, MM_Result, MM_CustInfo_Num, MM_CustInfo) Dim MM_CustData(15) MM_GET_CUSTP(MM_Result, MM_CustInfo_Num, MM_CustInfo, 2, PosSave, MM_Label, MM_CustData)In the preceding example, the tool pose of the second vision point stored in <PosSave>, the corresponding label stored in <MM_Label>, and the corresponding custom data stored in sequentially starting from <MM_CustData>.
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 [MELFA-tcp-207] or Set Mech-Viz Step Parameter before calling Run Mech-Viz Project.
Command Format
MM_START_VIZ(MM_RbtPose,JntSend,MM_Status)Input Parameters
MM_RbtPose
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.
| Robot pose 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 MM_RbtPose 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 collision is detected in the path of the simulated robot.
On the other hand, if MM_RbtPose is set to 2, the robot will send the image-capturing pose set by teach 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.
JntSend
This parameter specifies the custom joint positions.
-
If MM_RbtPose 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 MM_RbtPose is set to a parameter value other than 2, the joint positions are of no practical use but must be set.
Set Exit Port for 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.
Calling Sequence
This command should be called after Run Mech-Viz Project.
Command Format
MM_SET_BCH(MM_BchID,MM_ExportID,MM_Status)Input Parameters
MM_BchID
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.
MM_ExportID
This parameter indicates the exit port of the Branch by Msg Step. Valid values: positive integers. When the parameter value is set to N, the Mech-Viz project exits from the port with an ID of N-1 of the Branch by Msg Step.
Set Current Index in Mech-Viz
Command
This command sets the value of the Current Index parameter of index-type Steps. Steps that include the Index section include Move by Grid, Move by List, Custom Pallet Pattern, and Predefined Pallet Pattern.
Calling Sequence
Index-type Steps are often preceded by a Branch by Msg Step. The robot should call commands in this order: Run Mech-Viz Project, Set Current Index in Mech-Viz, and Set Exit Port for 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_IDX(MM_StepID,MM_Index_Num,MM_Status)Input Parameters
MM_StepID
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.
MM_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.
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:
|
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_VIZ(MM_WpPose, MM_SendPt, MM_Status, MM_WayPt_Num, MM_VPos_Num, MM_Result())Input Parameters
MM_WpPose
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 Path (joint positions) to access joint position data.
-
2: tool poses. After you run this command, run Store Vision Result or Planned Path (TCP) to access tool pose data.
MM_SendPt
This parameter specifies the maximum number of positions sent in a single transmission, with an upper limit of 5.
Output Parameters
MM_WayPt_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 > in the toolbar of Mech-Vision. The upper limit is 30.
MM_VPos_Num
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.
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 > in the toolbar of Mech-Vision. 
|
Example
Dim MM_Result(10, 8) MM_GET_VIZ(2,3,MM_Status,MM_WayPt_Num,MM_VPos_Num,MM_Result)The above example demonstrates how to obtain the path planned in the Mech-Viz project. The waypoints are represented in tool pose. The number of waypoints is stored in <MM_VisionPt_Num>; The position index within the overall path of the waypoint used for vision‑guided motion is stored in <MM_VPos_Num>; The command execution status code is stored in <MM_Status>. Up to 10 planned path points can be stored in <MM_Result>.
Get Vision Move Data or Custom Data
Command
This command obtains Vision Move data from the Mech-Vision project, or the Vision Move data or custom data from the Mech-Viz project. One command call stores all data in robot memory.
|
-
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 target objects, number of picked target objects, number of target objects to be picked this time, edge or corner ID of vacuum gripper, TCP offset, orientation of target object group, orientation of target object, and dimensions of target object group.
-
Mech-Viz projects:
-
Vision Move data refers to data output by the Vision Move Step in Mech-Viz, including the labels of picked target objects, number of picked target objects, number of target objects to be picked this time, edge or corner ID of vacuum gripper, TCP offset, orientation of target object group, orientation of target object, and dimensions of target object group.
-
Custom data refers to data output by the custom port(s) of the Output Step in Mech-Vision and then forwarded by Mech-Viz.
Select the Output Step, set Port Type to Custom, and then click Open the editor to go to the custom port configuration window. The Customized Keys section of the window displays custom port names, such as customeData1 and customeData2 as shown in the following figure.
-
Data output from Predefined Keys, such as poses, labels, sizes, offsets, is not custom data.
-
You must set Port Type of the Output Step to Custom and select the poses port in the Predefined Keys section in Mech-Vision.
-
-
Calling Sequence
This command should be called after Run Mech-Vision Project or Run Mech-Viz Project. After you call this command, call Store Vision Move Data or Custom Coordinate Data to access Vision Move data or custom data.
Command Format
MM_GET_VMD(MM_ProjID,MM_WpPose,MM_RcvFormat,MM_Status,MM_VisionPt_Num,MM_VPos_Num,MM_Result(),MM_VisionInfo())Input Parameters
MM_ProjID
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.
MM_WpPose
This parameter specifies the type of waypoint poses to be obtained.
| MM_WpPose | Pose | Further operation |
|---|---|---|
1 |
JPs |
After calling this function, execute the |
2 |
Tool Pose |
After calling this function, execute the |
MM_RcvFormat
This parameter is used to set the format of the data returned by Mech-Viz.
| MM_RcvFormat | Data Format Description |
|---|---|
1 |
Pose (joint-angle format) |
2 |
Pose (tool-pose format) |
3 |
Pose (joint‑angle format) + the planning results for vision‑guided motion |
4 |
Waypoint data (pose in position‑coordinate format) + the planning results for vision‑guided motion |
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.
| 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 |
Number of target objects to be picked this time |
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 |
Elements in custom data
The data of all custom ports of a single vision point. For example, data output from ports of the Output Step is presented in the following table. The elements in custom data of the first vision point are [0, 0, 1] and [0, 0]; and the elements in custom data of the second vision point are [1, 0, 0] and [1, 1].
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] ] |
First vision point |
[0, 0, 0, 1, 0, 0, 0] |
0 |
[0, 0, 1] |
[0, 0] |
Second vision point |
[0, 0, 0, 1, 0, 0, 0] |
1 |
[1, 0, 0] |
[1, 1] |
Output Parameters
MM_VisionPt_Num
This parameter stores the number of waypoints that are returned by the vision system.
MM_VPos_Num
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_Status
MM_VisionInfo()
This parameter is used to store the planning results for vision‑guided motion.
2D array variable MM_VisionInfo(row, col) |
Data Content Description |
|---|---|
MM_VisionInfo(row, 1) |
Labels of picked target objects(1) |
MM_VisionInfo(row, 2) |
Labels of picked target objects(2) |
MM_VisionInfo(row, 3) |
Labels of picked target objects(3) |
MM_VisionInfo(row, 4) |
Labels of picked target objects(4) |
MM_VisionInfo(row, 5) |
Labels of picked target objects(5) |
MM_VisionInfo(row, 6) |
Labels of picked target objects(6) |
MM_VisionInfo(row, 7) |
Labels of picked target objects(7) |
MM_VisionInfo(row, 8) |
Labels of picked target objects(8) |
MM_VisionInfo(row, 9) |
Labels of picked target objects(9) |
MM_VisionInfo(row, 10) |
Labels of picked target objects(10) |
MM_VisionInfo(row, 11) |
Total number of picked workpieces. |
MM_VisionInfo(row, 12) |
Number of target objects to be picked this time |
MM_VisionInfo(row, 13) |
Suction cup edge‑corner index number. |
MM_VisionInfo(row, 14) |
TCP offset X coordinate. |
MM_VisionInfo(row, 15) |
TCP offset Y coordinate. |
MM_VisionInfo(row, 16) |
TCP offset Z coordinate. |
MM_VisionInfo(row, 17) |
Orientation of the workpiece group. |
MM_VisionInfo(row, 18) |
Orientation of the individual workpiece. |
MM_VisionInfo(row, 19) |
X dimension of the workpiece group. |
MM_VisionInfo(row, 20) |
Y dimension of the workpiece group. |
MM_VisionInfo(row, 21) |
Z dimension of the workpiece group. |
Example
Dim MM_Result(10, 9) Dim MM_VisionInfo(10, 21) MM_GET_VMD (2,1,1,MM_Status,MM_VisionPt_Num,MM_VPos_Num,MM_Result,MM_VisionInfo)In the preceding example, the planned path and the planning results for vision‑guided motion are obtained from the Mech-Viz project 2. The number of vision points is stored in <MM_VisionPt_Num>, and the command execution status code is stored in <MM_Status>. Up to 10 planned path points can be stored in <MM_Result>. <MM_VisionInfo> stores the planning results for vision‑guided motion.
Store Vision Move Data or Custom Coordinate Data
Command
After calling the Get Vision Move Data or Custom Data command, this command is used to save the waypoint data to specified variables.
Calling Sequence
This command should be called after Get Vision Move Data or Custom Data.
Command Format
MM_GET_VMP(<MM_Result()>,<MM_VisionInfo()>,<MM_Serial>,<PosSave>,<MM_MotionType>,<MM_ToolID>,<MM_Velocity>,<MM_VisionData()>)Input Parameters
MM_Serial
This parameter specifies the index of the waypoint. The joint positions of the waypoint that corresponds to the index are stored in the variables. Indexes start from 1.
MM_VisionInfo()
This parameter is used to store the planning results for vision‑guided motion.
2D array variable MM_VisionInfo(row, col) |
Data Content Description |
|---|---|
MM_VisionInfo(row, 1) |
Labels of picked target objects(1) |
MM_VisionInfo(row, 2) |
Labels of picked target objects(2) |
MM_VisionInfo(row, 3) |
Labels of picked target objects(3) |
MM_VisionInfo(row, 4) |
Labels of picked target objects(4) |
MM_VisionInfo(row, 5) |
Labels of picked target objects(5) |
MM_VisionInfo(row, 6) |
Labels of picked target objects(6) |
MM_VisionInfo(row, 7) |
Labels of picked target objects(7) |
MM_VisionInfo(row, 8) |
Labels of picked target objects(8) |
MM_VisionInfo(row, 9) |
Labels of picked target objects(9) |
MM_VisionInfo(row, 10) |
Labels of picked target objects(10) |
MM_VisionInfo(row, 11) |
Total number of picked workpieces. |
MM_VisionInfo(row, 12) |
Number of target objects to be picked this time |
MM_VisionInfo(row, 13) |
Suction cup edge‑corner index number. |
MM_VisionInfo(row, 14) |
TCP offset X coordinate. |
MM_VisionInfo(row, 15) |
TCP offset Y coordinate. |
MM_VisionInfo(row, 16) |
TCP offset Z coordinate. |
MM_VisionInfo(row, 17) |
Orientation of the workpiece group. |
MM_VisionInfo(row, 18) |
Orientation of the individual workpiece. |
MM_VisionInfo(row, 19) |
X dimension of the workpiece group. |
MM_VisionInfo(row, 20) |
Y dimension of the workpiece group. |
MM_VisionInfo(row, 21) |
Z dimension of the workpiece group. |
MM_Result()
This parameter is the vision result, representing a series of vision points. Its data type is a 2D array numeric variable.
Output Parameters
PosSave
This parameter stores the TCP data of the waypoint that corresponds to the index. This parameter is used in MM_GET_VMP.
JntSend
This parameter stores the joint positions of the waypoint that corresponds to the index. This parameter is used in MM_GET_VMJ.
MM_MotionType
This parameter stores the motion type of the waypoint that corresponds to the index. 1 stands for joint motion, and 2 stands for linear motion.
MM_ToolID
This parameter stores the tool ID of the waypoint that corresponds to the index. A value of −1 means that no tool is used.
MM_Velocity
This parameter stores the velocity of the waypoint that corresponds to the index.
MM_VisionData()
This parameter stores the custom data of the waypoint that corresponds to the index. The parameter is a predefined global array variable.
This parameter stores the Vision Move data of the waypoint that corresponds to the index. The parameter is a predefined global array variable.
The following table describes the array variable.
| Value | Description | Variable |
|---|---|---|
Labels of picked target objects |
A label consists of 10 integers. The default value is ten 0s. |
(1) ~ (10) |
Number of picked target objects |
The total number of picked target objects. |
(11) |
Number of target objects to be picked this time |
Number of target objects to be picked this time |
(12) |
Edge or corner ID of vacuum gripper |
The ID of the edge or corner used to pick target objects this time. |
(13) |
TCP offset |
The XYZ offset between the center of the target object group and the tool pose center. |
(14) ~ (16) |
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. |
(17) |
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. |
(18) |
Dimensions of target object group |
The length, width, and height of the target object group to be picked this time. |
(19) ~ (21) |
Example
Dim MM_Result(10, 9) Dim MM_VisionInfo(10, 21) Dim MM_VisionData(21) MM_GET_VMD(1,3,MM_Status,MM_VisionPt_Num,MM_VPos_Num,MM_Result,MM_VisionInfo) MM_GET_VMP(MM_Result,MM_VisionInfo,2,PosSave,MM_MotionType,MM_ToolID,MM_Velocity,MM_VisionData)The example above indicates that the tool pose of the second waypoint is stored in <PosSave>, the motion type is stored in <MM_MotionType>, the tool ID is stored in <MM_ToolID>, the velocity is stored in <MM_Velocity>, and the planning results for vision‑guided motion is stored in <MM_VisionData>.
Store Vision Move Data or Custom Joint Data
Command
After calling the Get Vision Move Data or Custom Data command, this command is used to save the waypoint data to specified variables.
Calling Sequence
This command should be called after Get Vision Move Data or Custom Data.
Command Format
MM_GET_VMJ(<MM_Result()>,<MM_VisionInfo>,<MM_Serial>,<JntSave>,<MM_MotionType>,<MM_ToolID>,<MM_Velocity>,<MM_VisionData()>)Input Parameters
MM_Serial
This parameter specifies the index of the waypoint. The joint positions of the waypoint that corresponds to the index are stored in the variables. Indexes start from 1.
MM_VisionInfo()
This parameter is used to store the planning results for vision‑guided motion.
2D array variable MM_VisionInfo(row, col) |
Data Content Description |
|---|---|
MM_VisionInfo(row, 1) |
Labels of picked target objects(1) |
MM_VisionInfo(row, 2) |
Labels of picked target objects(2) |
MM_VisionInfo(row, 3) |
Labels of picked target objects(3) |
MM_VisionInfo(row, 4) |
Labels of picked target objects(4) |
MM_VisionInfo(row, 5) |
Labels of picked target objects(5) |
MM_VisionInfo(row, 6) |
Labels of picked target objects(6) |
MM_VisionInfo(row, 7) |
Labels of picked target objects(7) |
MM_VisionInfo(row, 8) |
Labels of picked target objects(8) |
MM_VisionInfo(row, 9) |
Labels of picked target objects(9) |
MM_VisionInfo(row, 10) |
Labels of picked target objects(10) |
MM_VisionInfo(row, 11) |
Total number of picked workpieces. |
MM_VisionInfo(row, 12) |
Number of target objects to be picked this time |
MM_VisionInfo(row, 13) |
Suction cup edge‑corner index number. |
MM_VisionInfo(row, 14) |
TCP offset X coordinate. |
MM_VisionInfo(row, 15) |
TCP offset Y coordinate. |
MM_VisionInfo(row, 16) |
TCP offset Z coordinate. |
MM_VisionInfo(row, 17) |
Orientation of the workpiece group. |
MM_VisionInfo(row, 18) |
Orientation of the individual workpiece. |
MM_VisionInfo(row, 19) |
X dimension of the workpiece group. |
MM_VisionInfo(row, 20) |
Y dimension of the workpiece group. |
MM_VisionInfo(row, 21) |
Z dimension of the workpiece group. |
MM_Result()
This parameter is the vision result, representing a series of vision points. Its data type is a 2D array numeric variable.
Output Parameters
JntSave
This parameter stores the joint positions of the waypoint that corresponds to the index. This parameter is used in MM_GET_VMJ.
MM_MotionType
This parameter stores the motion type of the waypoint that corresponds to the index. 1 stands for joint motion, and 2 stands for linear motion.
MM_ToolID
This parameter stores the tool ID of the waypoint that corresponds to the index. A value of −1 means that no tool is used.
MM_Velocity
This parameter stores the velocity of the waypoint that corresponds to the index.
MM_VisionData()
This parameter stores the custom data of the waypoint that corresponds to the index. The parameter is a predefined global array variable.
Example
Dim MM_Result(10, 9) Dim MM_VisionInfo(10, 21) Dim MM_VisionData(21) MM_GET_VMD(1, 3, MM_Status, MM_VisionPt_Num, MM_VPos_Num, MM_Result, MM_VisionInfo) MM_GET_VMJ(MM_Result, MM_VisionInfo, 2, JntSave, MM_MotionType, MM_ToolID, MM_Velocity, MM_VisionData)The example above indicates that the joint angles of the second waypoint is stored in <JntSave>, the motion type is stored in <MM_MotionType>, the tool ID is stored in <MM_ToolID>, the velocity is stored in <MM_Velocity>, and the planning results for vision‑guided motion is stored in <MM_VisionData>.
Set Mech-Viz Step Parameter
Calling Sequence
This command should be called before Run Mech-Viz Project.
Command Format
MM_SET_PROP(MM_StructID,MM_Status)Input Parameters
MM_StructID
This parameter corresponds to the Config ID field defined in the property_config file.
|
From the toolbar of Mech-Vision, go to . Click Property Configuration to open the property_config file. 
|
Before sending this command, you should define a Config ID and its corresponding Step ID, parameter key name and parameter value in the following format in the property_config file.
write, Config ID, Step ID, parameter key name, parameter value
write |
Indicates that this line is used to set the parameter value of a Step. |
Config ID |
Specifies an ID, which is a positive integer and can be used repeatedly. |
Step ID |
Specifies the Step whose parameter value the robot requires to read. |
parameter key name |
Specifies the key name of the parameter whose value the robot requires to set. |
parameter value |
Specifies the value that the robot sets for the parameter. |
|
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,30When the robot sends the command below, Mech-Viz sets the values of the parameters whose key names are xOffset, yOffset and zOffset respectively to 10, 20 and 30.
MM_SET_PROP(1,MM_Status)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.
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. |
Calling Sequence
This command should be called before Run Mech-Vision Project.
Command Format
MM_SET_BS(MM_ProjID,MM_Length,MM_Width,MM_Height,MM_Status)Input Parameters
MM_ProjID
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.
MM_Length, MM_Width, and MM_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.
Input Pose Data to Mech-Vision Project
Command
This command dynamically inputs poses to the Mech-Vision project. The input poses are used as the value of the Poses parameter of the Easy Create Poses Step.
Calling Sequence
This command should be called before Run Mech-Vision Project.
Command Format
MM_SET_POS(MM_ProjID,MM_StepName,PosSend,MM_Status)Input Parameters
MM_ProjID
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.
MM_StepName
This parameter specifies the value of the Step Name parameter of the Easy Create Poses Step. The value must be set to a number in advance. Sample value: 1, as shown in the image below.
PosSend
This parameter specifies the position register ID. The P register that corresponds to the ID stores the input pose data. The pose data will become the value of the Poses parameter in the Easy Create Poses Step.
|
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:
-
Connect the Notify Step to the right side of another Step. The Output Step is used in the example in the image below.
-
Select Trigger Control Flow Given Output in the parameter panel of the Output Step.
-
In the parameter panel of the Notify Step, enter Standard Interface Notify (a required value) for Service Name. Enter a positive integer for Message, for example, 1001.
-
-
For a Notify Step in the Mech-Viz project:
-
Connect the Notify Step to a proper Step in the workflow.
-
In the parameter panel of the Notify Step, select Standard Interface. Enter a positive integer for Message, for example, 1000.
-
Calling Sequence
This command should be called right after Run Mech-Vision Project or Run Mech-Viz Project.
Command Format
MM_GET_MSG(MM_NotifyMsg)Output Parameters
MM_NotifyMsg
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 second. Therefore, you should consider the timing of calling this command to ensure successful message retrieval. |
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 MELFA Automatic Calibration.
Command Format
MM_CALIB(MM_MoveType,MM_CalibPoseType,MM_WaitTime,MM_Ext,MM_CalibInfo())Input Parameters
MM_MoveType
This parameter specifies the motion type of the robot. Valid values: 1 and 2.
-
1: Linear motion (MOVEL)
-
2: Joint motion (MOVEJ)
MM_CalibPoseType
This parameter specifies the type of calibration point poses to be obtained. Valid values: 1 and 2.
-
1: TCP
-
2: Joint positions
MM_WaitTime
This parameter specifies the time the robot waits to avoid shaking after it moves to the calibration point. The default value is 2 (s).
MM_Ext
This parameter specifies the external axis data. Unit: millimeters. If a 7th axis exists and is controlled by the robot on site, this parameter must be set to the specific external exist data. Otherwise, this parameter must be set to 0.
MM_CalibInfo
This parameter is the vision result, representing a series of vision points. Its data type is a 2D array numeric variable.
Stop Mech-Viz Project
Calling Sequence
This command should be called after Run Mech-Viz Project.
Get Project Status
Command Format
MM_GET_STAT(MM_Status)Output Parameters
MM_Status
This parameter indicates the name of the variable for storing the command execution status code. Status code 1101 is returned for a successful command execution, indicating that the Mech-Vision project is ready. If a command fails to be run, a specific error code is returned. For details, see Status Codes and Troubleshooting.