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

    Can check and adjust in Mech-Vision

    .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

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

    Can check and adjust in Mech-Vision

    .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

    Can check and adjust in Mech-Vision

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