Kawasaki Standard Interface Commands¶
The Kawasaki Standard Interface provides the following subroutines:
When writing your own program, pay attention to the following:
Multiple parameters should be separated by commas.
All parameters should be defined as local variables.
Parameters can be defined as input or output parameters.
Input arguments can be constants, global variables or local variables; output arguments can be global variables or local variables.
This Standard Interface is over the TCP/IP protocol.
Initialize Communication¶
mm_init_skt(.ip1,.ip2,.ip3,.ip4,.port)
This subroutine sets the IP address and port number of the host IPC.
Parameters¶
Input parameters
Name
Description
.ip1 - .ip4
IP address of the IPC
.port
Port number of the IPC, the default is 50000
Example¶
CALL mm_init_skt(192,168,1,1,50000)
This example sets the IP address and port number of the host IPC to 192.168.1.1:50000.
Start Mech-Vision Project¶
mm_start_vis(.job,.pos_num_need,.sendpos_type,.#start_vis)
This subroutine 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 3
See the following table for explanations of the 4 values
.#start_vis
Variable for storing the joint positions of the start point when .sendpos_type = 3
If .sendpos_type is not 3, set the value to #start_vis when calling the command
.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.
Examples¶
CALL mm_start_vis(1,1,1,#start_vis)
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 subroutine is called as the image-capturing pose.
CALL mm_start_vis(1,1,3,#start_vis)
This example runs Mech-Vision project No. 1, and asks the project to send over 1 vision point, and the robot sends the joint positions stored in .#start_vis when this subroutine is called as the start point for the planned path to Mech-Vision.
Get Vision Target(s)¶
mm_get_visdata(.job,.pos_num,.ret)
This subroutine 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_dy_data to obtain the vision result instead.
Parameters¶
Input parameter
Name
Description
.job
Mech-Vision Project ID, from 1 to 99
Output parameters
Name
Description
.pos_num
Variable for storing the number of received vision points
.ret
Variable for storing status code. Please see Status Codes and Troubleshooting.
Example¶
CALL mm_get_visdata(1,posnum,statuscode)
This example obtains the vision result from Mech-Vision project No. 1. The number of vision points received is stored in posnum, and the status code is stored in statuscode.
Start Mech-Viz Project¶
mm_start_viz(.sendpos_type,.#start_viz)
This subroutine 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.
Parameter¶
Input parameters
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
.#start_viz
Variable for storing the joint positions of the start point when .sendpos_type = 2
If .sendpos_type is not 2, set the value to #start_viz when calling the command
.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.
Examples¶
CALL mm_start_viz(1,#start_viz)
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.
CALL mm_start_viz(2,#start_viz)
This example runs the corresponding Mech-Viz project, and sets the initial joint positions of the simulated robot to the joint positions stored in .#start_viz.
Get Planned Path¶
mm_get_vizdata(.getpos_type,.pos_num,.vispos_num,.ret)
This subroutine obtains the planned path from Mech-Viz.
Note
Only the poses and their corresponding labels and velocities are obtained by this subroutine. 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.
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
.pos_num
Variable for storing the number of received waypoints
.vispos_num
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.
.ret
Variable for storing status code. Please see Status Codes and Troubleshooting.
Example¶
CALL mm_get_vizdata(2,posnum,vis_index,statuscode)
This example obtains the planned path from Mech-Viz in the form of TCPs. The number of waypoints received is stored in posnum, the position of the Vision Move waypoint is stored in vis_index, and the status code is stored in statuscode.
Obtain Pose¶
mm_get_pose(.index,.&targetpos,.label,.speed)
This subroutine 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, starting from 1
Output parameters
Name
Description
.&targetpos
Variable for storing the specified pose
Must add “&” before the variable name to indicate the variable as transformation values
.label
Variable for storing the label corresponding to the specified pose
.speed
Variable for storing the velocity corresponding to the specified pose
Example¶
CALL mm_get_pose(1,.&pt[1],pt_label[1],pt_speed[1])
This example stores the first received pose to pt[1], the corresponding label to pt_label[1], and the corresponding velocity to pt_speed[1].
Obtain Joint Positions¶
mm_get_jps(.index,.#targetpos,.label,.speed)
This subroutine 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 subroutine can only be used with Mech-Viz.
Parameters¶
Input parameter
Name
Description
.index
Specify the index of the pose to be stored, starting from 1
Output parameters
Name
Description
.#targetpos
Variable for storing the specified set of joint positions
Must add “#” before the variable name to indicate the variable as joint displacement values
.label
Variable for storing the label corresponding to the specified set of joint positions
.speed
Variable for storing the velocity corresponding to the specified set of joint positions
Example¶
CALL mm_get_jps(1,.#pt[1],pt_label[1],pt_speed[1])
This example stores the first set of received joint positions to pt[1], the corresponding label to pt_label[1], and the corresponding velocity to pt_speed[1].
Switch Mech-Vision Recipe¶
mm_switch_model(.job,.model_number)
This subroutine specifies which parameter recipe of the Mech-Vision project to use. For more information on parameter recipe, please see Parameter Recipe.
Note
This subroutine 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 mm_switch_model(2,2)
This example switches the parameter recipe used to No. 2 in Mech-Vision project No. 2.
Select Mech-Viz Branch¶
mm_set_branch(.branch_num,.exit_num)
This subroutine 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 subroutine specifies which exit port such Step(s) should take.
Note
mm_start_viz must be called BEFORE this subroutine.
When the next Step to be executed in Mech-Viz is a Branch by Msg Step, Mech-Viz will wait for this subroutine 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 “Branch by Msg” Step whose Step ID is 1.
Set Move Index¶
mm_set_index(.skill_num,.index_num)
This subroutine 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 subroutine.
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 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(.ret)
This subroutine is currently capable of checking whether Mech-Vision is ready to run projects. In the future, this subroutine can be used for obtaining the execution status of Mech-Vision, Mech-Viz, and Mech-Center.
Parameter¶
Output parameter
Name
Description
.ret
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.
Example¶
CALL mm_get_status(statuscode)
This example obtains the status code and stores it in statuscode.
Input Object Dimensions to Mech-Vision¶
mm_set_boxsize(.job,.length,.width,.height)
This subroutine inputs object dimensions to the Mech-Vision project.
Note
This subroutine must be called BEFORE mm_start_vis.
The corresponding Mech-Vision project must contain the “Read Object Dimensions” Step, and the Read Sizes from Properties parameter of this step must be checked.
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 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 subroutine obtains the planned DO Signal list for controlling multiple sections of a sectioned vacuum gripper.
Note
mm_get_vizdata must be called BEFORE this subroutine.
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 mm_get_dolist
This example obtains the DO signal list planned by Mech-Viz and stores it in setdo[] array. The first array element is setdo[0] and the last is setdo[io_index-1].
Input TCP to Mech-Viz¶
mm_set_pos(.&pos)
This subroutine inputs TCP data to the External Move Step.
Note
This subroutine 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
Variable for storing the TCP data to be sent to Mech-Viz
Must add “&” before the variable name to indicate the variable as transformation values
Example¶
CALL mm_set_pos(&pos)
This example sends the TCP data stored in &pos to the External Move Step in the Mech-Viz project.
Calibration¶
calibrate()
This subroutine 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 Kawasaki Calibration Program.
Get Vision Result from Mech-Vision¶
mm_get_dy_data(.job,.pos_num,.ret)
This subroutine 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 subroutine.
The custom port outputs are stored in the vis_custom_data[i,j] array in alphabetical order of the custom port names.
If only poses and labels are needed (no custom output ports defined), use mm_get_visdata 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
Variable for storing the number of received vision points
.ret
Variable for storing status code. Please see Status Codes and Troubleshooting.
Example¶
CALL mm_get_dy_data(1,posnum,statuscode)
This example obtains the vision result that includes custom port outputs from Mech-Vision project No. 1. The number of vision points received is stored in posnum, and the status code is stored in statuscode.
Get Waypoint from Mech-Viz¶
mm_get_plandata(.getpos_type,.pos_num,.vispos_num,.ret)
This subroutine is used for obtaining the planned path from Mech-Viz. This subroutine can obtain all data contained in waypoints, including pose, motion type, tool number, depalletizing planning data and custom port outputs from Mech-Vision.
“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”.
Other data are explained below in “Parameters”.
Note
mm_start_viz must be called BEFORE this subroutine.
If only poses, labels and velocities are needed, use mm_get_vizdata to obtain the planned path instead.
Parameters¶
Input parameter
Name
Description
.getpos_type
Expected format of the returned data, see the following table for explanations
The relationship between the value of .getpos_type and the format of the returned data is summarized below.
.getpos_type 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 .getpos_type to 3 or 4; if the depalletizing planning data are not needed, set .getpos_type to 1 or 2.
Output parameters
Name
Description
.pos_num
Variable for storing the number of received waypoints
.vispos_num
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.
.ret
Variable for storing status code. Please see Status Codes and Troubleshooting.
If this subroutine is executed successfully, the returned data are stored in the following variables.
Returned data |
Variable |
Joint positions |
vis_pos_j1[i], vis_pos_j2[i], vis_pos_j3[i], vis_pos_j4[i], vis_pos_j5[i], vis_pos_j6[i] |
TCP |
vis_pos_x[i], vis_pos_y[i], vis_pos_z[i], vis_pos_o[i], vis_pos_a[i], vis_pos_t[i] |
Velocity |
vis_pos_spd[i] |
Motion type |
vis_pos_type[i] |
Tool number |
vis_pos_tool[i] |
Custom port outputs |
vis_custom_data[i, j] |
Depalletizing planning data |
vis_plan_result[i, j] |
Example¶
CALL mm_get_plandata (3,posnum,vis_index,statuscode)
This example obtains the planned path that includes depalletizing planning data and custom port outputs from Mech-Viz, and the poses obtained are in the form of joint positions. The number of waypoints received is stored in posnum, the position of the Vision Move waypoint is stored in vis_index, and the status code is stored in statuscode.
Get Result of Step “Path Planning” in Mech-Vision¶
mm_get_vispath(.job,.getpos_type,.pos_num,.vispos_num,.ret)
This subroutine 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 subroutine.
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
.pos_num
Variable for storing the number of received waypoints
.vispos_num
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.
.ret
Variable for storing status code. Please see Status Codes and Troubleshooting.
Example¶
CALL mm_get_vispath(1,1,posnum,vis_index,statuscode)
This example obtains the planned path from Mech-Vision project No. 1 in the form of joint positions. The number of waypoints received is stored in posnum, the position of the Vision Move waypoint is stored in vis_index, and the status code is stored in statuscode.