YASKAWA Standard Interface Commands¶
The YASKAWA Standard Interface provides the following jobs:
When writing your own program, pay attention to the following:
Multiple parameters should be separated by semi-colons.
When calling jobs: input parameter is a string by default; output parameter is a string by default, each element in the string corresponding to a global variable in the background.
Attention
For Mech-Mind Software Suite prior to version 1.6.1, every Standard Interface job encapsulates codes that initialize the communication and disconnect the communication.
For Mech-Mind Software Suite 1.6.1 and above, the following changes have been made:
To facilitate testing, only MM_INIT_SOCKET keeps codes used for communication establishment and disconnection. The MM_INIT_SOCKET job only needs to be called once because the set IP address will be valid globally from then on.
Codes used for communication establishment and disconnection are divided into two individual jobs, which are MM_OPEN_SOCKET and MM_CLOSE_SOCKET. The communication is established when MM_OPEN_SOCKET is called and remains alive until MM_CLOSE_SOCKET is called to disconnect it. With these two jobs, frequent reconnection of communication between the robot and the vision system can be avoided.
This Standard Interface is over the TCP/IP protocol.
Initialize Communication¶
MM_INIT_SOCKET ("IP_Address;Server_Port;Time_Out")
This job sets the IP address and port number of the IPC and wait time before the program stops trying to establish the communication.
Parameters¶
Input parameters
Name
Description
IP_Address
IP address of the IPC
Server_Port
Port number of the IPC, the default is 50000
Time_Out
Wait time in minutes before stopping connection attempt
Example¶
CALL JOB:MM_INIT_SOCKET ("192.168.1.1;50000;5")
This example sets the IP address and port number of the IPC to 192.168.1.1:50000 and wait time to 5 minutes.
Start TCP Socket¶
MM_OPEN_SOCKET
This job begins the communication between the robot and the vision system. The MM_INIT_SOCKET job should be called before this job to set the IP address and port number of the IPC correctly.
Parameters¶
No parameters.
Example¶
CALL JOB:MM_OPEN_SOCKET
Close TCP Socket¶
MM_CLOSE_SOCKET
This job shuts down the TCP/IP socket and therefore ends the communication between the robot and the vision system. You can call this job after all the vision tasks are completed.
Parameters¶
No parameters.
Example¶
CALL JOB:MM_CLOSE_SOCKET
Start Mech-Vision Project¶
MM_START_VIS ("Job;Pos_Num_Need;SendPos_Type;prNum")
This job is for applications that use Mech-Vision but not Mech-Viz. It runs the corresponding Mech-Vision project to acquire and process data.
Parameters¶
Input parameters
Name
Description
Job
Mech-Vision Project ID, from 1 to 99
Pos_Num_Need
Number of vision points for Mech-Vision to send, from 0 to 20, where 0 means “send all”
SendPos_Type
Set the robot pose to send to Mech-Vision, from 0 to 2
See the following table for explanations of the 4 values
prNum
P variable for storing the joint positions of the start point when SendPos_Type = 3
The data type of the P variable should be set to PULSE, otherwise the “MM:PVAR_SET_ERROR” will be raised
SendPos_Type value
Pose sent to Mech-Vision
Applicable scenario
0
No robot pose sent to Mech-Vision
Project is in the eye-to-hand mode. If the “Path Planning” Step is used, the planned path starts at the Home point set in the path planning tool.
1
Current joint positions and flange pose of the robot as image-capturing pose
Project is in the eye-in-hand mode. Applicable to most robots (excluding truss robots).
2
Current flange pose of the robot as image-capturing pose
Project is in the eye-in-hand mode. The robot has no joint positions and only flange pose (such as truss robots).
3
Joint positions of a specific start point
Project is in the eye-to-hand mode and the Mech-Vision project contains the “Path Planning” Step, whose start point needs to be set from the robot side.
Example¶
CALL JOB:MM_START_VIS ("1;1;1")
This example runs Mech-Vision project No. 1, and asks the project to send over 1 vision point, and the robot sends its current joint positions and flange pose when this job is called as the image-capturing pose.
Get Vision Target(s)¶
MM_GET_VISDATA ("Job;Last_Data;Pos_Num;MM_Status")
This job is for applications that use Mech-Vision but not Mech-Viz. It obtains the vision result from the corresponding Mech-Vision project.
Note
If custom outputs are defined in the “Procedure Out” Step in the Mech-Vision project, use MM_GET_DYDATA to obtain the vision result instead.
Parameters¶
Input parameter
Name
Description
Job
Mech-Vision Project ID, from 1 to 99
Output parameters
Name
Description
Last_Data
I variable, indicating whether all vision points have been sent, 0 or 1
0: NOT all vision points have been sent (more on the way) 1: All vision points have been sent If 0, call this JOB again until all are sent
Pos_Num
I variable for storing the number of received vision points
MM_Status
I variable for storing status code. Please see Status Codes and Troubleshooting.
Example¶
CALL JOB:MM_GET_VISDATA ("1;50;51;52")
This example obtains the vision result from Mech-Vision project No. 1. Whether all vision points have been sent is stored in I50, the number of vision points received is stored in I51, and the status code is stored in I52.
Start Mech-Viz Project¶
MM_START_VIZ ("SendPos_Type;prNum")
This job is for applications that use both Mech-Vision and Mech-Viz. It runs the corresponding Mech-Viz project (which triggers the corresponding Mech-Vision project to run), and sets the initial joint positions of the simulated robot in Mech-Viz.
Note
Only the poses and their corresponding labels and velocities are obtained by this job. If any other type of data are needed, such as custom outputs from Mech-Vision project or depalletizing planning data, use MM_GET_PLANDATA to obtain the planned path instead.
Parameter¶
Input parameter
Name
Description
SendPos_Type
Set the initial pose for the simulated robot in Mech-Viz, from 0 to 2
See the following table for explanations of the 3 values
prNum
P variable for storing the joint positions of the start point when SendPos_Type = 2
The data type of the P variable should be set to PULSE, otherwise the “MM:PVAR_SET_ERROR” will be raised
SendPos_Type value
Pose sent to Mech-Viz
Applicable scenario
0
No robot pose sent to Mech-Viz
Project is in the eye-to-hand mode. The simulated robot in Mech-Viz moves from joint positions = [0, 0, 0, 0, 0, 0] to the first waypoint.
1
Current joint positions and flange pose of the robot
This setting is recommended for projects in the eye-in-hand mode. The simulated robot in Mech-Viz moves from the input joint positions to the first waypoint.
2
Joint positions of a specific start point
This setting is recommended for projects in the eye-to-hand mode. The simulated robot in Mech-Viz moves from the input joint positions to the first waypoint.
Note
When the scene contains objects that obstruct the robot to move from [0,0,0,0,0,0] to the first waypoint, this parameter should not be set to 1.
Example¶
CALL JOB:MM_START_VIZ ("1")
This example runs the corresponding Mech-Viz project, and sets the initial joint positions of the simulated robot to the current joint positions of the real robot.
Get Planned Path¶
MM_GET_VIZDATA ("GetPos_Type;Last_Data;Pos_Num;VisPos_Num;MM_Status")
This job obtains the planned path from Mech-Viz.
Parameters¶
Input parameter
Name
Description
GetPos_Type
Whether Mech-Viz should send waypoint poses as joint positions or TCPs, 1 or 2
1: Mech-Viz sends joint positions 2: Mech-Viz sends TCPs
Output parameters
Name
Description
Last_Data
I variable, indicating whether all waypoints have been sent, 0 or 1
0: NOT all waypoints have been sent (more on the way) 1: All waypoints have been sent If 0, call this JOB again until all are sent
Pos_Num
I variable for storing the number of received waypoints
VisPos_Num
I variable for storing the position of the first Vision Move waypoint in the path
Example path: Move_1, Move_2, Vision Move_3, Move_3, Vision Move_2 In this path, the position of the first Vision Move waypoint is 3. If the path does not contain Vision Move waypoint, the return value is 0.
MM_Status
I variable for storing status code. Please see Status Codes and Troubleshooting.
Example¶
CALL JOB:MM_GET_VIZDATA ("2;50;51;52;53")
This example obtains the planned path from Mech-Viz in the form of TCPs. Whether all waypoints have been sent is stored in I50, the number of waypoints received is stored in I51, the position of the Vision Move waypoint is stored in I52, and the status code is stored in I53.
Obtain Pose¶
MM_GET_POSE ("Index;PosTarget;Label;Pose_Speed")
This job stores a vision pose returned by Mech-Vision or a waypoint pose (as TCP) returned by Mech-Viz in the specified variable.
Parameters¶
Input parameter
Name
Description
Index
Specify the index of the pose to be stored
Output parameters
Name
Description
PosTarget
P variable for storing the specified pose
Label
I variable for storing the label corresponding to the specified pose
Pose_Speed
I variable for storing the velocity corresponding to the specified pose
Example¶
CALL JOB:MM_GET_POSE ("1;60;61;62")
This example stores the first received pose to P60, the corresponding label to I61, and the corresponding velocity to I62.
Obtain Joint Positions¶
MM_GET_JPS ("Index;JointTarget;Label;Pose_Speed")
This job stores a set of joint positions returned by Mech-Viz in the specified variable.
Note
As Mech-Vision does not output joint position data, this job can only be used with Mech-Viz.
Parameters¶
Input parameter
Name
Description
Index
Specify the index of the set of joint positions to be stored
Output parameters
Name
Description
JointTarget
P variable for storing the specified set of joint positions
Label
I variable for storing the label corresponding to the specified set of joint positions
Pose_Speed
I variable for storing the velocity corresponding to the specified set of joint positions
Example¶
CALL JOB:MM_GET_JPS ("1;60;61;62")
This example stores the first set of received joint positions to P60, the corresponding label to I61, and the corresponding velocity to I62.
Switch Mech-Vision Recipe¶
MM_SET_MODEL ("Job;Model_Number")
This job specifies which parameter recipe of the Mech-Vision project to use. For more information on parameter recipe, please see Parameter Recipe.
Note
This job must be called BEFORE MM_START_VIS.
The corresponding Mech-Vision project must have parameter recipes already configured and saved.
Parameters¶
Input parameters
Name
Description
Job
Mech-Vision Project ID, from 1 to 99
Model_Number
The ID of a parameter recipe in the Mech-Vision project, from 1 to 99
Example¶
CALL JOB:MM_SET_MODEL ("1;1")
This example switches the parameter recipe used to No. 1 in Mech-Vision project No. 1.
Select Mech-Viz Branch¶
MM_SET_BRANCH ("Branch_Num;Exit_Num")
This job is used to select along which branch the Mech-Viz project should proceed. Such branching is achieved by adding Branch by Msg Step(s) to the project. This job specifies which exit port such Step(s) should take.
Note
MM_START_VIZ must be called BEFORE this job.
When the next Step to be executed in Mech-Viz is a Branch by Msg Step, Mech-Viz will wait for this job to send the exit port number it should take.
Parameters¶
Input parameters
Name
Description
Branch_Num
Step ID of the “Branch by Msg” Step, can be viewed in Mech-Viz
Exit_Num
The number of the exit port to take + 1, from 1 to 99
Example: To select exit port 0 in Mech-Viz, set the value of this parameter to 1.
Example¶
CALL MM_SET_BRANCH ("1;3")
This example tells Mech-Viz to take exit port 3 for the “Branch by Msg” Step whose Step ID is 1.
Set Move Index¶
MM_SET_INDEX ("Skill_Num;Index_Num")
This job sets the value for the Current Index parameter of Mech-Viz Steps. Steps that have this parameter include Move by List, Move by Grid, Custom Pallet Pattern, and Smart Pallet Pattern.
Note
mm_start_viz must be called BEFORE this job.
Parameters¶
Input parameters
Name
Description
Skill_Num
Step ID of the Step, can be viewed in Mech-Viz
Index_Num
Value for the Current Index parameter when the Step is executed
Example¶
CALL JOB:MM_SET_INDEX ("2;10")
This example sets the Current Index value to 9 for the Step whose Step ID is 2. When the Step is executed, the Current Index value will be added 1 and become 10.
Get Software Status¶
MM_GET_STATUS ("Status")
This job is currently capable of checking whether Mech-Vision is ready to run projects. In the future, this job can be used for obtaining the execution status of Mech-Vision, Mech-Viz, and Mech-Center.
Parameter¶
Output parameter
Name
Description
Status
Variable for storing status code
Status code 1101 indicates that Mech-Vision is ready to run projects. For other status codes, please see Status Codes and Troubleshooting.
Input Object Dimensions to Mech-Vision¶
MM_SET_BOXSIZE("Job;Length;Width;Height")
This job inputs object dimensions to the Mech-Vision project.
Note
This job must be called BEFORE MM_START_VIS.
Parameters¶
Input parameters
Name
Description
Job
Mech-Vision Project ID, from 1 to 99
Length
Length of object in mm
Width
Width of object in mm
Height
Height of object in mm
Example¶
CALL JOB:MM_SET_BOXSIZE ("1;500;300;200")
This example sets the object dimensions in the Read Object Dimensions Step in the Mech-Vision project No. 1 to 500*300*200 mm.
Get DO Signal List¶
MM_GET_DOLIST
This job obtains the planned DO Signal list for controlling multiple sections of a sectioned vacuum gripper.
Note
MM_GET_VIZDATA must be called BEFORE this job.
Please deploy the Mech-Viz project based on the template project in xxx\Mech-Mind Software Suite-x.x.x\Mech-Center\tool\viz_project\suction_zone, and set the suction cup configuration file in the Mech-Viz project.
Parameters¶
No parameters.
Example¶
CALL JOB:MM_GET_DOLIST
This example obtains the DO signal list planned by Mech-Viz and writes the values in OT1 – OT16.
Input TCP to Mech-Viz¶
MM_SET_POSE ("Pos")
This job inputs TCP data to the External Move Step.
Note
This job must be called BEFORE MM_START_VIZ.
Please deploy the Mech-Viz project based on the template project in xxx\Mech-Mind Software Suite-x.x.x\Mech-Center\tool\viz_project\outer_move, and put the External Move Step at a proper position in the workflow.
Parameter¶
Input parameter
Name
Description
Pos
P variable for storing the TCP data to be sent to Mech-Viz
Example¶
CALL JOB:MM_SET_POSE ("10")
This example sends the TCP data stored in P10 to the External Move Step in the Mech-Viz project.
Calibration¶
MM_CALIB ("Move_Type;Pos_Jps;Wait_Time;Rnum;Ext;Pos")
This job is used for hand-eye calibration (camera extrinsic parameter calibration). It automates the calibration process in conjunction with the Camera Calibration function in Mech-Vision. For detailed instructions, see KUKA Calibration Program.
Parameters¶
Input parameters
Name
Description
Move_Type
Motion type, 1 or 2
1: MOVL 2: MOVJ
Pos_Jps
Pose as flange pose or joint positions, 1 or 2
1: flange pose 2: Joint positions
Wait_Time
The time the robot waits to avoid shaking after it moves to the calibration point; the default value is 2 (s)
Rnum
Number of robot axes
Ext
Data of the external 7th axis in mm, optional
Pos
Start point for the calibration, P99 by default
Example¶
CALL JOB:MM_CALIB ("2;1;2;6;0;99")
This example moves the robot with MOVJ, receives pose data in the form of flange pose, and sets the wait time to 2 seconds to avoid the robot from shaking after it moves to the calibration point. This robot has 6 axes and does not have an external axis installed. The start point for the calibration is stored in P99.
Get Vision Result from Mech-Vision¶
MM_GET_DYDATA ("Job;Pos_Num;MM_Status")
This job is used for obtaining the vision result that includes custom port outputs from the corresponding Mech-Vision project. “Custom port outputs” refers to data output by ports other than poses and labels of the “Procedure Out” Step in Mech-Vision. The output ports can be customized if the Port Type parameter of the Step is set to “Custom”.
Note
MM_START_VIS must be called BEFORE this job.
If only poses and labels are needed (no custom output ports defined), use MM_GET_VIZDATA to obtain the vision result instead.
Parameters¶
Input parameter
Name
Description
Job
Mech-Vision Project ID, from 1 to 99
Can check and adjust in the Project List panel in Mech-Vision
Output parameters
Name
Description
Pos_Num
I variable for storing the number of received vision points
MM_Status
I variable for storing status code. Please see Status Codes and Troubleshooting.
Example¶
CALL JOB:MM_GET_DYDATA ("2;60;61")
This example obtains the vision result that includes custom port outputs from Mech-Vision project No. 2. The number of vision points received is stored in I60, and the status code is stored in I61.
Save Vision Point to Specified Variables¶
MM_GET_DYPOSE ("Serial;PosTarget;Label;UserData")
This job stores the data in a vision point returned by Mech-Vision in the specified variables.
Note
This job is called AFTER MM_GET_DYDATA.
Parameters¶
Input parameter
Name
Description
Serial
Specify the index of the vision point to be stored
Output parameters
Name
Description
PosTarget
P variable for storing the pose in the specified vision point
Label
I variable for storing the label in the specified vision point
UserData
The first R variable for storing the custom port outputs in the specified vision point
Data are stored in R variables consecutive to the input one. Reserve enough R variables.
Example¶
CALL JOB:MM_GET_DYPOSE ("2;60;60;60")
This example stores the pose in the second received vision point to P60, the corresponding label to I60, and the corresponding custom port outputs to R60 and consecutive R variables.
Get Waypoint from Mech-Viz¶
MM_GET_PLANDATA ("Jps_Pos;Pos_Num;VisPos_Num;MM_Status")
This job is used for obtaining the planned path from Mech-Viz. This job can obtain all data output by Mech-Viz, including motion type, tool number, custom port outputs from Mech-Vision and depalletizing planning data.
“Custom port output” refers to data output by ports other than poses and labels of the “Procedure Out” Step in Mech-Vision. The output ports can be customized if the Port Type parameter of the Step is set to “Custom”.
“Depalletizing planning data” is explained below.
Note
MM_START_VIZ must be called BEFORE this job.
If only poses, labels and velocities are needed, use MM_GET_VIZDATA to obtain the planned path instead.
Parameters¶
Input parameters
Name
Description
Jps_Pos
Expected format of the returned data, see the following table for explanations
The relationship between the value of Jps_Pos and the format of the returned data is summarized below.
Jps_Pos value
Format of returned data (Explained below)
1
Pose (joint positions), motion type, tool number, velocity, number of custom ports, custom port output, custom port output, … custom port output
2
Pose (TCP), motion type, tool number, velocity, number of custom ports, custom port output, custom port output, … custom port output
3
Pose (joint positions), motion type, tool number, velocity, depalletizing planning data, number of custom ports, custom port output, custom port output, … custom port output
4
Pose (TCP), motion type, tool number, velocity, depalletizing planning data, number of custom ports, custom port output, custom port output, … custom port output
Pose
The pose of the waypoint, as joint positions (in degree) or TCP, which is composed of Cartesian coordinates (XYZ in mm) and Euler angles (ABC in degree).
Motion type
Value is 1: joint motion
Value is 2: linear motion
Tool number
The index number of the tool to be used at this waypoint. -1 means no tool is used.
Velocity
Velocity percentage of the waypoint, equals to the velocity setting in the corresponding move-type Step × the global velocity setting in Mech-Viz.
Depalletizing planning data:
Data used in planning multi-pick depalletizing tasks. These data are part of the waypoint of the “Vision Move” Step. The following data are included:
Label: composed of 10 integers, if fewer than 10 labels are obtained, the rest of the digits are filled with 0.
Number of picked workobjects
Number of workobjects to be picked this time
Edge-corner ID of vacuum gripper: can be checked by double-clicking the corresponding tool in Resources in Mech-Viz and then selecting Configure control logic.
TCP offset: The offset between the tool pose at the center of the to-pick workobjects and the actual tool pose.
Workobject orientation: whether the X-axis of the workobject reference frame is aligned with the X-axis of the tool reference frame (value: 0 or 1).
Dimensions of the workobjects combined
Number of custom ports
The number of output keys excluding poses and labels when the Port Type parameter of the “Procedure Out” Step in the Mech-Vision project is set to “Custom”.
Custom port outputs
The outputs excluding poses and labels when the Port Type parameter of the “Procedure Out” Step in the Mech-Vision project is set to “Custom”. These data are part of the waypoint of the “Vision Move” Step.
The custom port outputs are arranged in alphabetical order of the custom port names.
Waypoints in a planned path can be divided into two types: those of the “Vision Move” Step and those of other move-type Steps.
All waypoints contain the following data: pose, motion type, tool number and velocity.
The waypoints of the “Vision Move” Step also contain depalletizing planning data.
If custom ports are defined for the “Procedure Out” Step in Mech-Vision, then the waypoints of the “Vision Move” Step also contain custom port outputs.
To obtain the depalletizing planning data, set Jps_Pos to 3 or 4; if the depalletizing planning data are not needed, set Jps_Pos to 1 or 2.
Output parameters
Name
Description
Pos_Num | I variable for storing the number of received waypoints
VisPos_Num
I variable for storing the position of the first Vision Move waypoint in the path
Example path: Move_1, Move_2, Vision Move_3, Move_3, Vision Move_2 In this path, the position of the first Vision Move waypoint is 3. If the path does not contain Vision Move waypoint, the return value is 0.
MM_Status
I variable for storing status code. Please see Status Codes and Troubleshooting.
Example¶
CALL JOB:MM_GET_DYDATA ("2;60;61;62")
This example obtains the planned path that includes custom port outputs from Mech-Viz, and the poses obtained are in the form of TCPs. The number of waypoints received is stored in I60, the position of the Vision Move waypoint is stored in I61, and the status code is stored in I62.
Save Waypoint to Specified Variables¶
MM_GET_PLANPOSE("Serial;Target;Pose_Info;Plan_Result")
This job stores the data in a waypoint returned by Mech-Viz in the specified variables.
Note
These jobs are called AFTER MM_GET_DYDATA.
Input parameter
Name
Description
Serial
Specify the index of the waypoint to be stored
Output parameters
Name
Description
Target
P variable for storing the poses in the specified waypoint
If Jps_Pos in MM_GET_PLANDATA is 1 or 3: set the data type of the P variable to PULSE If Jps_Pos in MM_GET_PLANDATA is 2 or 4: set the data type of the P variable to ROBOT
Pose_Info
The first B variable for storing the motion type, tool number and velocity in the specified waypoint
Make sure the next two B variables are free for storing the above data.
Plan_Result
The first R variable for storing the depalletizing planning data and custom port outputs in the specified waypoint
Omit for waypoints not of the Vision Move Step Data are stored in R variables consecutive to the input one. Reserve enough R variables. The depalletizing planning data occupies 20 variables. The custom port outputs depend on settings in Mech-Vision.
Examples¶
CALL JOB:MM_GET_PLANPOSE ("2;60;60;60")
This example stores the TCP in the first received waypoint to P60, the corresponding motion type, tool number and velocity to B60, B61 and B62, the corresponding custom port outputs to R60 and consecutive R variables.
Get Result of Step “Path Planning” in Mech-Vision¶
MM_GET_VISPATH("Job;GetPos_Type;Last_Data;Pos_Num;VisPos_Num;MM_Status")
This job is for applications that use Mech-Vision but not Mech-Viz. It obtains the collision-free path planned by the “Path Planning” Step from the corresponding Mech-Vision project.
Note
MM_START_VIS must be called BEFORE this job.
The Port Type parameter of the “Procedure Out” Step in the Mech-Vision project must be set to “Predefined (robot path)”.
Input parameters
Name
Description
Job
Mech-Vision Project ID, from 1 to 99
Can check and adjust in the Project List panel in Mech-Vision
GetPos_Type
Whether Mech-Vision should send poses as joint positions or TCPs, 1 or 2
1: Mech-Vision sends joint positions 2: Mech-Vision sends TCPs
Output parameters
Name
Description
Last_Data
I variable, indicating whether all waypoints have been sent, 0 or 1
0: NOT all waypoints have been sent (more on the way) 1: All waypoints have been sent
Pos_Num
I variable for storing the number of received waypoints
VisPos_Num
I variable for storing the position of the first Vision Move waypoint in the path
Example path: Move_1, Move_2, Vision Move_3, Move_3, Vision Move_2 In this path, the position of the first Vision Move waypoint is 3. If the path does not contain Vision Move waypoint, the return value is 0.
MM_Status
I variable for storing status code. Please see Status Codes and Troubleshooting.
Example¶
CALL JOB:MM_GET_VISPATH ("1;2;50;51;52;53")
This example obtains the planned path from Mech-Vision project No. 1 in the form of TCPs. Whether all waypoints have been sent is stored in I50, the number of waypoints received is stored in I51, the position of the Vision Move waypoint is stored in I52, and the status code is stored in I53.