ROKAE Standard Interface Procedures
Notes for calling commands:
Since the commands are restricted by ROKAE syntax, the parameters and returned values cannot be passed. Therefore, all parameters and returned values involved in the command are global variables.
Initialize Communication
Start Mech-Vision Project
This function is used for applications that use Mech-Vision. It runs the corresponding project to acquire and process data. It applies for applications that use Mech-Vision but not Mech-Viz.
Procedure
Job = 1
Pos_Num_Need = 1
SendPos_Type = 1
MM_J = UpdateJnttarget(MM_J,0,0,0,0,0,0,0,0,0,0,0,0)
MM_Start_Vis()This example triggers the Mech-Vision project whose ID is 1 to run; the Mech-Vision project is expected to send back one vision point; and the robot sends its current joint positions and flange pose as the image-capturing pose to Mech-Vision. UpdateJnttarget(MM_J,0,0,0,0,0,0,0,0,0,0,0,0) sets a set of fixed joint positions, and it will be used when the value of SendPos_Type is 3.
Input Parameters
Job
Mech-Vision project ID, which can be viewed before the project name in the Project List panel in Mech-Vision.
Pos_Num_Need
The expected number of vision points for Mech-Vision to send. The vision point contains the vision pose, corresponding point cloud, label, scaling, etc.
-
0: Receive all vision points in the recognition result from Mech-Vision. -
Integer greater than 0: Receive the specified number of vision points in the recognition result from Mech-Vision.-
If the total number of vision points is less than the parameter value, all vision points in the recognition result will be received.
-
If the total number of vision points is greater than or equal to the parameter value, the specified number of vision points will be received.
-
| The command used to obtain the vision points is command 102. Command 102 can only fetch at most 20 vision points at a time. One of the returned parameter of command 102 indicates if all the requested vision points have been obtained. If not, please execute command 102 repeatedly. |
SendPos_Type
The type of the robot pose to be sent to Mech-Vision. Value range: 0 to 3.
-
0: No robot poses need to be sent to the vision system. If the camera is mounted in the Eye To Hand mode, the image capturing process is independent of the robot pose, and therefore the robot pose is not needed. -
1: The robot pose in the current joint positions together with the current flange pose will be sent to the vision system. It is recommended to set this value when the camera is mounted in the Eye In Hand mode. When this parameter is set to this value, the “Path Planning” Step in the Mech-Vision project will use the joint positions sent by the robot. If the flange pose data are all 0, the vision system ignores the flange pose data. -
2: The robot pose in the current flange pose will be sent to the vision system. It is recommended to set this value when the camera is mounted in the Eye In Hand mode or in other scenarios where only the flange pose data is available (such as truss robots). -
3: The robot pose in the joint positions defined by the user will be sent to the vision system. It is recommended to set this value when the camera is mounted in the Eye To Hand mode. When this parameter is set to this value, the “Path Planning” Step in the Mech-Vision project will use the joint positions sent by the robot as the initial pose.
MM_J
User-defined joint positions. When the value of SendPos_Type is set to 3, this set of joint positions will be used as the first waypoint in the path planned by the “Path Planning” Step in the Mech-Vision project. If the value of SendPos_Type is set to values other than 3, the joint positions set here will not take effect, but it has to be set.
Get Vision Target(s)
This procedure is called after Start Mech-Vision Project to obtain the vision points output by Mech-Vision and automatically transform the vision points into vision targets.
The vision system will automatically convert the vision point information into the corresponding robot TCP.
| By default, command 102 can only fetch at most 20 TCPs at a time. Therefore, command 102 may need to be repeatedly executed until all TCPs required are obtained. |
Procedure
Job = 1
MM_Get_VisData()This example obtains the vision result from the Mech-Vision project whose ID is 1. The output values of this procedure is stored in global variables (Last_Data, Pose_Num, and MM_Status). Whether all vision points have been sent is stored in Last_Data, the number of vision points received is stored in Pose_Num, and the status code is stored in MM_Status.
Input Parameters
Job
Mech-Vision project ID, which can be viewed before the project name in the Project List panel in Mech-Vision.
Output Parameters
Last_Data
This parameter indicates whether all TCPs requested have been obtained. The value is 0 or 1.
-
0: NOT all required TCPs have been sent (more on the way). Please execute command 102 repeatedly until the value turns to 1. -
1: All required TCPs have been sent.
If the expected number of TCPs set in “Start Mech-Vision Project” procedure is greater than 20 (default value length for sending and receiving data), this parameter can be used to determine whether there is any TCP that has not been sent. If not all data have been sent, you can call command 102 repeatedly until all TCPs have been received.
| If not all TCPs have been received, and command 101 is called to re-capture an image at this time, the unreceived TCPs will be cleared. |
Variable type: int
Pos_Num
The number of received TCPs.
-
If the required number of TCPs is greater than or equal to the number of vision points recognized by Mech-Vision, the number of recognized vision points will be sent.
-
If the required number of TCPs is less than the number of the recognized vision points, the required number of vision points will be sent.
Value range: 0 to 20
Variable type: int
MM_Status
If there is no error, status code 1100 will be returned. Otherwise, the corresponding error code will be returned.
When this function is called, the vision system waits for the result from Mech-Vision and then sends it to the robot. The default wait time is 10 seconds. If a timeout occurs, a timeout error code will be returned to the robot.
Variable type: int
Start Mech-Viz Project
This procedure is for applications that use both Mech-Vision and Mech-Viz. This function runs the Mech-Viz project (which triggers the corresponding Mech-Vision project to run), and Mech-Viz will plan a robot motion path based on the vision result received from Mech-Vision.
Please right-click the Mech-Viz project to be started in Resources panel and select Autoload Project in the context menu.
There are some example projects of typical applications stored in Communication Component/tool/viz_project in the installation directory of Mech-Vision & Mech-Viz. You can modify the example projects according to practical requirements.
Procedure
SendPos_Type = 1
MM_J = CJointT()
MM_Start_Viz()This procedure triggers the Mech-Viz project to run and sends the current joint positions and flange pose of the robot to Mech-Viz.
Input Parameters
SendPos_Type
Robot pose type. Value range: 0–2
0: No robot poses need to be sent to Mech-Viz. The simulated robot in Mech-Viz will start from joint positions [0,0,0,0,0,0] and move to the first waypoint.
1: The current joint positions and flange pose of the real robot need to be sent to Mech-Viz. The simulated robot in Mech-Viz will start from the current joint positions of the real robot and move to the first waypoint.
2:The predefined joint positions of the robot need to be sent to Mech-Viz. The simulated robot in Mech-Viz will start from the predefined joint positions and move to the first waypoint.
MM_J
User-defined joint positions. User-defined joint positions. When the value of SendPos_Type is set to 2, this set of joint positions will be used as the first waypoint in the path planned by Mech-Viz. If the value of SendPos_Type is set to values other than 2, the joint positions set here will not take effect, but it has to be set.
Get Planned Path from Mech-Viz
This procedure obtains the planned path from Mech-Viz. It should be used after executing the “Start Mech-Viz Project” procedure to obtain the planned path.
By default, this procedure can only fetch at most 20 waypoints at a time. Therefore, it may need to be repeatedly executed until all the waypoints are obtained.
|
If the waypoint of a move-type Step should not be sent to the robot, please clear the “Send Waypoint” option in the parameters of this Step. |
Procedure
Jps_Pos = 2
MM_Get_VizData()This procedure obtains the waypoints in the planned path from Mech-Viz in the form of TCPs. Whether all waypoints have been sent is stored in the global variable Last_Data. The number of waypoints received is stored in the global variable Pos_Num. The position of the Vision Move waypoint is stored in the global variable VisPos_Num. The status code is stored in the global variable MM_Status.
Input Parameters
Jps_Pos
This parameter specifies the type of waypoint pose returned by Mech-Viz.
-
1: The waypoint poses are returned in the form of joint positions (JPs). -
2: The waypoint poses are returned in the form of tool center point (TCP).
Output Parameters
Last_Data
Variable indicating whether all waypoints have been sent.
-
0: NOT all waypoints have been sent (more on the way). Please repeat the calling of this procedure until the value of this parameter becomes 1. -
1: All waypoints have been sent.
Pos_Num
Number of waypoints. Variable for storing the number of received waypoints which contains the corresponding pose, label, velocity.
If the planned path contains more than 20 waypoints, please repeat executing this procedure.
Value range: 0 to 20
VisPos_Num
The position of the waypoint in the “Vision Move” Step in the entire planned path. The “Vision Move” waypoint is the one where the robot performs the picking.
For example, if the path is composed of Steps Fixed-Point Move_1, Fixed-Point Move_2, Vision Move, Fixed-Point Move_3 sequentially, the position of Vision Move is 3.
If the path does not contain any Vision Move waypoint, the returned value is 0.
MM_Status
Status code.
If there is no error, status code 2100 will be returned. Otherwise, the corresponding error code will be returned.
| When calling this function, the vision system waits for the result from Mech-Viz and then sends it to the robot. The default wait time is 10 seconds. If a timeout occurs, a timeout error code will be returned to the robot. |
Obtain Pose
This procedure stores a pose of the vision point returned by Mech-Vision or a pose of the waypoint returned by Mech-Viz in the specified position variable.
Obtain Joint Positions (Available when Mech-Viz is used)
This procedure stores a vision point (in JPs) returned by Mech-Vision or a waypoint (in JPs) returned by Mech-Viz in the specified position variable.
Switch Mech-Vision Recipe
This procedure specifies the parameter recipe to be used in the Mech-Vision project.
In Mech-Vision, you can change the values of Step parameters by switching the parameter recipe in use.
| This procedure must be called BEFORE “Start Mech-Vision Project”. |
Select Mech-Viz Branch
This procedure selects along which branch the Mech-Viz project should proceed. Such branching is achieved by adding the “Branch by Msg” Step(s) to the Mech-Viz project.
“Start Mech-Viz Project” must be executed BEFORE this procedure.
When the next Step to execute is a “Branch by Msg” Step, the Mech-Viz project will wait for this procedure to specify the exit port to take.
Procedure
Branch_Num = 1
Export_Num = 3
MM_Set_Branch()This procedure tells Mech-Viz to take exit port 3 for the “Branch by Msg” Step whose Step ID is 1.
Input Parameters
Branch_Num
Step ID of the “Branch by Msg” Step.
Export_Num
Exit port number in integers.
| This parameter value should be 1 greater than the exit port number displayed in the Step. For example, if the specified exit port is the second exit port of the Step from left to right, the exit port number is 2. |
Set Move Index
This procedure sets the value of the Current Index parameter of the specified Mech-Viz Step. Steps that have this parameter include “Move by List”, “Move by Grid”, “Custom Pallet Pattern”, and “Predefined Pallet Pattern”.
“Start Mech-Viz Project” must be executed BEFORE this procedure.
Procedure
Skill_Num = 2
Index_Num = 10
MM_Set_Index()This example sets the Current Index value to 9 for the Step in Mech-Viz whose Step ID is 2. When the Step is executed, the Current Index value will be added 1 and become 10.
Input Parameters
Skill_Num
Step ID.
The ID of the Step whose Current Index value needs to be set.
The value of this parameter should be a positive integer. The Step ID is displayed in the parameters of the Step.
Index_Num
The Current Index value that should be set the next time this Step is executed.
When this procedure is sent, the current index value in Mech-Viz will become the parameter value minus 1.
When the Mech-Viz project runs to the Step specified by this procedure, the current index value in Mech-Viz will be increased by 1 to become the parameter’s value.
Get Software Status
Input Object Dimensions to Mech-Vision
This procedure dynamically inputs object dimensions into the Mech-Vision project. Please check the actual object dimensions before running the Mech-Vision project.
The Mech-Vision project should contain the “Read Object Dimensions” Step. The Read Sizes from Properties parameter of this Step must be selected.
Procedure
Job = 1
Length = 500
Width = 300
Height = 200
MM_Set_BoxSize()This example sets the object dimensions in the “Read Object Dimensions” Step in the Mech-Vision project to 500 × 300 × 200 mm.
Input Parameters
Job
Mech-Vision project ID, which can be viewed before the project name in the Project List panel in Mech-Vision.
Length, Width, Height
The object dimensions (length, width, height) to be input to the Mech-Vision project. The dimensions will be read into the “Read Object Dimensions” Step.
The unit is millimeters.
Get DO Signal List
This function gets the planned DO signal list. The DO signal list is used to control multiple grippers or multiple suction cup sections.
“Get Planned Path” should be called before this procedure to obtain the path planned by Mech-Viz.
Please deploy the Mech-Viz project based on the template project and set the corresponding suction cup configuration file. The example project is stored in Communication Component/tool/viz_project/suction_zone in the installation directory of Mech-Vision & Mech-Viz.
Set DO Signal List
This procedure sets the DO list sent by Mech-Viz to GO signals. It supports 4 groups of 16-bit GO signals in maximum. If you need to set multiple groups of GO signals, please run this procedure for several times.
| MM_Get_DoList must be called BEFORE this procedure. |
Calibration
This procedure is used for hand-eye calibration (camera extrinsic parameter calibration).
This procedure synchronizes the calibration status with Mech-Vision and obtains the next calibration point that the robot needs to reach from Mech-Vision.
This procedure must be executed multiple times to complete the calibration.
Procedure
Move_Type = 2
Jps_Pos = 1
Wait_Time = 2
IsAxis7 = false
MM_Calib()This procedure moves the robot in MoveJ type, receives pose data in the form of TCP, and sets the wait time to 2 seconds to avoid the robot from shaking after it moves to the calibration point. In addition, this robot does not have an external axis installed.
Move_Type = 2
Jps_Pos = 1
Wait_Time = 2
IsAxis7 = true
Axis7 = 0
MM_Calib()This example moves the robot in MoveJ type, receives pose data in the form of TCP, and sets the wait time to 2 seconds to avoid the robot from shaking after it moves to the calibration point. Moreover, the 7th axis value of this robot is 0.
Input Parameters
| Move_Type | The motion type of the robot. 1: MoveL. 2: MoveJ. |
|---|---|
Jps_Pos |
Pose as joint positions or TCP. 1: Joint positions. 2: TCP. |
Wait_Time |
The time the robot waits to avoid shaking after it moves to the calibration point; the default value is 2 (s). |
IsAxis7 |
Whether there is an external 7th axis, true or false. The default value is false, i.e., no 7th axis. |
Axis7 |
Optional variable for storing the external axis data in mm. It is only used when there is a 7th axis. |
Get Vision Result from Mech-Vision
This procedure obtains the custom output data from the corresponding Mech-Vision project. “Custom output data” refers to the data output by ports other than poses and labels of the “Output” Step. The output ports can be customized if the “Port Type” parameter of the Step is set to “Custom”.
Call this procedure once and you can obtain and store all data to the robot.
Procedure
Job = 2
MM_Get_Dy_Data()This example obtains the vision result that includes custom port outputs from Mech-Vision project No.2. The obtained poses and corresponding labels are stored in the global arrays MM_Pose_Pos[128] and MM_Pose_Label[128], and the corresponding custom port outputs are stored in the global array UserData[128][128]. The number of vision points received is stored in the global variable Pos_Num, and the status code is stored in the global variable MM_Status.
Save Vision Point to Specified Variables
This procedure stores the data in a vision point returned by Mech-Vision in the specified variables. This procedure is called AFTER Get Vision Result from Mech-Vision.
Procedure
Serial = 2
MM_Get_DyPose()This example stores the pose in the second received vision point to MM_P, the corresponding label to MM_Label, and the corresponding custom port outputs to MM_UserData.
Input Parameters
Serial
Variable in the integer data type. Specify the index of the vision point in which the custom data you want to store. The index is defined by the sequence that Mech-Vision sends the data.
Output Parameters
MM_P
Variable in the robtarget data type. for storing the pose in the specified vision point.
MM_Label
Variable in the double data type. for storing the label in the specified vision point. If there is not a label port in Mech-Vision, 0 will be filled in automatically.
MM_UserData
Variable in the double data type. Used for storing the custom port outputs in the specified vision point.
Get Waypoint from Mech-Viz
This procedure is used for obtaining the planned path from Mech-Viz. The waypoint may be for a Vision Move Step, or for one of the other move-type Steps. A waypoint may contain pose, velocity, gripper info, object info, etc. Calling this procedure once will store all the obtained data to the robot.
Waypoints in a planned path can be divided into the following three types.
-
All waypoints contain the following data: motion type (joint motion or linear motion), tool ID and velocity.
-
Vision Move waypoints, containing information such as label, number of objects that have been picked, number of objects picked this time, edge/corner ID of the suction cup, the TCP offset, object orientation, and object dimensions.
-
Vision move waypoints including custom data, where the port type of the Output step of the Mech-Vision project should be “custom”.
Procedure
Jps_Pos = 4
MM_Get_PlanData()This example obtains the planned path that includes depalletizing planning data and custom port outputs from Mech-Viz, and stores all the output data to the global array of the robot. The sequence number of the Vision Move waypoint is stored in VisPos_Num, and the status code is stored in MM_Status.
Input Parameters
Jps_Pos
Global variable in the integer data type. Expected format of the returned data, from 1 to 4.
See the following table for explanations.
| jpsPos value | Format of returned data (Explained below) |
|---|---|
1 |
Pose (joint positions), motion type, tool ID, velocity, number of custom ports, custom port output, custom port output, … custom port output |
2 |
Pose (TCP), motion type, tool ID, velocity, number of custom ports, custom port output, custom port output, … custom port output |
3 |
Pose (joint positions), motion type, tool ID, velocity, depalletizing planning data, number of custom ports, custom port output, custom port output, … custom port output |
4 |
Pose (TCP), motion type, tool ID, velocity, depalletizing planning data, number of custom ports, custom port output, custom port output, … custom port output |
Pose (Stored in MM_Pose_Pos[128])
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 (Stored in MM_Pose_MoveType[128])
-
1: joint motion, MOVEJ -
2: linear motion, MOVEL
Tool ID (Stored in MM_Pose_ToolNum[128])
The tool ID of the waypoint. -1 indicates no tool is used.
Velocity (Stored in MM_Pose_Speed[128])
Velocity of the waypoint, equals to the velocity setting in the corresponding move-type Step multiplied by the global velocity setting in Mech-Viz, in the format of percentage.
Depalletizing planning data (Stored in Plan_Results[128][128])
Data used in planning multi-pick depalletizing tasks. These data are part of the waypoint of the “Vision Move” Step. Usually used for box multi-pick and depalletizing scenarios. 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: used to specify the gripper corner to which the workobject is aligned. Can be checked by double-clicking the corresponding tool in the Resources panel 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 (Stored in UserDataNum)
The number of output ports excluding poses and labels when the “Port Type” parameter of the “Output” Step in the Mech-Vision project is set to “Custom”.
Custom port outputs (Stored in UserData[128][128])
The outputs that exclude poses and labels when the “Port Type” parameter of the “Output” 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.
Output Parameters
Pos_Num
Variable in the integer data type. Used for storing the number of received waypoints.
VisPos_Num
Variable in the integer data type. Used for storing the sequence number of the first Vision Move waypoint in the path. For example, if the path is composed of Fixed-Point Move_1, Fixed-Point Move_2, Vision Move, and Fixed-Point Move_3 sequentially, the position of Vision Move is 3. If the path does not contain “Vision Move”, the value of this parameter is 0.
MM_Status
Variable in the integer data type. for storing the status code.
Save Waypoint to Specified Variables
This procedure should be called after Get Waypoint from Mech-Viz. It stores the corresponding set of data to different variables according to the specified index. The code will be slightly different according to the value of Jps_Pos.
Procedure
Serial = 2
Jps_Pos = 4
MM_Get_PlanPose()This example procedure stores the TCP in the second received waypoint from Mech-Viz to MM_P, the corresponding motion type to MM_MoveType, the corresponding tool ID to MM_ToolNum, the corresponding velocity to MM_Speed. If the waypoint is not a Vision Move waypoint, there is no further information; if it is a Vision Move waypoint, the corresponding custom port outputs will be stored to MM_UserData, and the corresponding depalletizing planning data will be stored to MM_Plan_Results.
Serial = 1
Jps_Pos = 3
MM_Get_PlanJps()This example procedure stores the joint position in the first received waypoint from Mech-Viz to MM_J, the corresponding motion type to MM_MoveType, the corresponding tool ID to MM_ToolNum, the corresponding velocity to MM_Speed. If the waypoint is not a Vision Move waypoint, there is no further information; if it is a Vision Move waypoint, the corresponding custom port outputs will be stored to MM_UserData, and the corresponding depalletizing planning data will be stored to MM_Plan_Results.
Input Parameters
Serial
Variable in the integer data type. Specify the index of the waypoint to be stored. The index of the waypoint is determined by the order in which Mech-Viz sends data.
Jps_Pos
Variable in the integer data type. The parameter value should be the same as that of Jps_Pos in MM_Get_PlanData().
Output Parameters
MM_P
Global variable in the robtarget data type. Used for storing the TCP in the specified waypoint.
MM_J
Global variable in the Jointtarget data type. Used for storing the joint positions in the specified waypoint.
MM_MoveType
Variable in the integer data type. Used for storing the motion type in the specified waypoint.
MM_ToolNum
Variable in the integer data type. Used for storing the tool ID in the specified waypoint.
MM_Speed
Variable in the integer data type. Used for storing the velocity in the specified waypoint.
MM_UserData
Global array variable that can be read directly without the need for parameter passing. Used for storing the custom port outputs in the specified waypoint.
MM_Plan_Results
Global array variable that can be read directly without the need for parameter passing. Used for storing the depalletizing planning data corresponding to the specified waypoint.
Get Result of Step “Path Planning” in Mech-Vision
This procedure obtains the collision-free path planned by the “Path Planning” Step from the corresponding Mech-Vision project.
The Port Type parameter of the “Output” Step in the Mech-Vision project must be set to “Predefined (robot path)”.
Procedure
Job = 2
Jps_Pos = 2
MM_Get_VisPath()This example obtains the planned path from Mech-Vision project No.2 in the form of TCPs. The number of waypoints received is stored in Pos_Num, the sequence number of the Vision Point in the path is stored in VisPos_Num, and the status code is stored in MM_Status.
Input Parameters
Job
Global variable type: int. Mech-Vision project ID, which can be viewed before the project name in the Project List panel in Mech-Vision.
Jps_Pos
Global variable in the integer data type. The pose type of waypoints returned by the “Path Planning” Step.
-
1: Waypoints in joint positions will be returned. -
2: Waypoints in TCPs will be returned.
Output Parameters
Last_Data
Global variable in the integer data type. This variable indicates whether all waypoints have been sent, 0 or 1.
-
0: NOT all waypoints have been sent (more on the way). Please repeat the calling of this procedure until the value of this parameter becomes 1. -
1: All waypoints have been sent.
Pos_Num
Global variable in the integer data type. Used for storing the number of returned waypoints.
VisPos_Num
Global variable in the integer data type. Used for storing the position of the “Vision Move” waypoint in the entire planned path in the Path Planning tool. For example, if the path is composed of Fixed-Point Move_1, Fixed-Point Move_2, Vision Move, and Fixed-Point Move_3 sequentially, the position of Vision Move is 3. If the path does not contain “Vision Move”, the value of this parameter is 0.
MM_Status
Global variable in the integer data type. for storing the status code.