Siemens PLC Client–Siemens SIMATIC S7 PLC Functions
This topic introduces the functions for Siemens PLC Snap 7 communication between a Siemens SIMATIC S7 PLC and Mech-Vision and Mech-Viz.
Function Descriptions
Start Mech-Vision Project
This function is used for applications that use Mech-Vision but not Mech-Viz. This function starts the Mech-Vision project that executes image capturing and performs vision recognition.
Parameters
IN
-
Vision_Proj_Num: Mech-Vision project ID, which is the number before the project name in the Project List panel in Mech-Vision.
-
Req_Pose_Num: The number of vision points that Mech-Vision is requested to send, from 0 to 20, where 0 indicates “send all”.
-
Robot_Pose_Type: The type of robot pose to input to Mech-Vision. The value range is from 0 to 3.
-
Robot_Pose: The pose received from the robot, value depends on the value of Robot_Pose_Type. Data type: two-dimensional array [0..1, 0..5] of Real, array[0] is joint positions and array[1] is flange pose.
The following table explains the relationship between Robot_Pose_Type and Robot_Pose.
| Robot_Pose_Type value | Robot_Pose value | Description | Applicable Scenarios |
|---|---|---|---|
0 |
0, 0, 0, 0, 0, 0 |
No need to input robot pose to Mech-Vision |
Project is in the Eye To Hand mode. If the “Path Planning” Step is used in the Mech-Vision project, the planned path starts at the home point set in the path planning tool. |
1 |
Current joint positions and flange pose of the robot |
Robot joint positions and flange pose must be input to Mech-Vision |
Project is in the eye-in-hand mode. Applicable to most robots (excluding gantry robots). |
2 |
Current flange pose of the robot |
Robot flange pose must be input to Mech-Vision |
Project is in the eye-in-hand mode. The robot has no joint positions and only flange pose (such as gantry robots). |
3 |
Joint positions of the start point of the planned path |
The joint positions of the path start point must be input to Mech-Vision |
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. |
-
Start_Vision: Trigger the start of the Mech-Vision project at the rising edge.
-
Trigger_Acknowledge: Used to determine whether the vision system is triggered successfully by the Command_Trigger signal. 1 indicates that the vision system is triggered successfully, while 0 indicates that the Command_Trigger signal has not been received.
IN/OUT
-
Set_Flag: The triggering action flag.
OUT
-
Vision_Proj_Num_O: Mech-Vision project ID.
-
Req_Pose_Num_O: The number of vision points output from Mech-Vision. 0 indicates that all vision points will be obtained.
-
Robot_Pose_Type_O: Robot pose type.
-
Robot_JPS: Robot joint positions.
-
Robot_Pose_TCP_O: Robot flange pose.
-
Command: The function code, whose value is assigned by the FB automatically.
-
Command_Trigger: The function switch, which is triggered by the FB automatically.
Data returned by the MM Interface DB:
-
Status code: If there is no error, status code 1102 will be returned. Otherwise, the corresponding error code will be returned.
Example
Example Description
In this example, the value of “Camera_User”.Step_Num is set to 6. After the “MM_Start_Vis” function is enabled, when variable “Camera_User”.Start_Vis is at the rising edge, the PLC triggers Mech-Vision project No.1 to run, requests the vision result from Mech-Vision project No.1, and sends the joint positions and flange pose to Mech-Vision.
Get Vision Target(s)
This function is used for applications that use Mech-Vision but not Mech-Viz. It obtains the vision result from the corresponding Mech-Vision project.
Parameters
IN
-
Vision_Proj_Num: Mech-Vision project ID, which is the number before the project name in the Project List panel in Mech-Vision.
-
Get_VisData: Obtain vision points from Mech-Vision project when a rising edge occurs.
-
Trigger_Acknowledge: Used to determine whether the vision system is triggered successfully by the Command_Trigger signal. 1 indicates that the vision system is triggered successfully, while 0 indicates that the Command_Trigger signal has not been received.
IN/OUT
-
Set_Flag: The triggering action flag.
OUT
-
Vision_Proj_Num_O: Mech-Vision project ID.
-
Command: The function code, whose value is assigned by the FB automatically.
-
Command_Trigger: The function switch, which is triggered by the FB automatically.
Data returned by the MM Interface DB:
-
Status code: If there is no error, status code 1100 will be returned. Otherwise, the corresponding error code will be returned.
-
Status of Pose Sent: 1 indicates that the pose data written in are new. After PLC reads the pose data, please reset this register.
-
Number of Pose Sent: Store the number of vision points returned. The value range is from 1 to 20.
-
Target Pose: Store the waypoint poses sent by Mech-Vision as TCPs.
-
Target_Label: Store the integer labels corresponding to the poses. Labels are set in Mech-Vision. The returned label values are integers.
Example
Example Description
In this example, the value of “Camera_User”.Step_Num is set to 8. After the “MM_Get_VisData” function is enabled, when variable “Camera_User”.Get_VisData is at the rising edge, the PLC retrieves the vision result from Mech-Vision project No.1.
Switch Mech-Vision Parameter Recipe
This function specifies which parameter recipe of the Mech-Vision project to use. Parameter recipes can be used to switch parameter settings, including point cloud model for matching, ROI, confidence threshold, etc, in the same Mech-Vision project when it is used to recognize different workpieces. This function must be called BEFORE MM_Start_Vis.
Parameters
IN
-
Vision_Proj_Num: Mech-Vision project ID, which is the number before the project name in the Project List panel in Mech-Vision.
-
Vision_Recipe_Num: The ID of a parameter recipe in the Mech-Vision project. Value range: 1 to 99.
-
Switch_Recipe: Switch the parameter recipe used by the Mech-Vision project when a rising edge occurs.
-
Trigger_Acknowledge: Used to determine whether the vision system is triggered successfully by the Command_Trigger signal. 1 indicates that the vision system is triggered successfully, while 0 indicates that the Command_Trigger signal has not been received.
IN/OUT
-
Set_Flag: The triggering action flag.
OUT
-
Vision_Proj_Num_O: Mech-Vision project ID.
-
Vision_Recipe_Num_O: The ID of a parameter recipe in the Mech-Vision project.
-
Command: The function code, whose value is assigned by the FB automatically.
-
Command_Trigger: The function switch, which is triggered by the FB automatically.
Data returned by the MM Interface DB:
-
Status code: If there is no error, status code 1107 will be returned. Otherwise, the corresponding error code will be returned.
Example
Example Description
In this example, the value of “Camera_User”.Step_Num is set to 4. After the “MM_Switch_Recipe” function is enabled, when variable “Camera_User”.Switch_Recipe is at the rising edge, the parameter recipe of Mech-Vision project No.1 is switched to recipe No.2.
Get Result of Step “Path Planning” in Mech-Vision
After calling MM_Start_Vis, call this function to obtain the collision-free picking path planned by the “Path Planning” Step in the Mech-Vision project.
When using this function, set the Port Type parameter of the “Output” Step in the Mech-Vision project to “Predefined (robot path)”.
| Before executing this function, please set Req_Pose_Num in MM_Start_Vis to 0 to reduce the times of execution of this function. If Req_Pose_Num in MM_Start_Vis is set to 1, then every time this function is executed, only 1 waypoint is returned, and this function must be executed multiple times to obtain all the waypoints. |
Parameters
IN
-
Vision_Proj_Num: Mech-Vision project ID, which is the number before the project name in the Project List panel in Mech-Vision.
-
Request_Pose_Type: This parameter specifies the type of waypoint poses returned by the “Path Planning” Step.
-
1: The waypoint poses are returned in the form of joint positions. -
2: The waypoint poses are returned in the form of TCP.
-
| Request_Pose_Type here and Robot_Pose_Type in the MM_Start_Vis and MM_Start_Viz functions correspond to the same Pose Type parameter in the MM Interface data block. If the set values are different, they cannot take effect at the same time. |
-
Get_VisData: Obtains the planned path from the “Path Planning” Step in Mech-Vision at the rising edge.
-
Trigger_Acknowledge: Used to determine whether the vision system is triggered successfully by the Command_Trigger signal. 1 indicates that the vision system is triggered successfully, while 0 indicates that the Command_Trigger signal has not been received.
IN/OUT
-
Set_Flag: The triggering action flag.
OUT
-
Vision_Proj_Num_O: Mech-Vision project ID.
-
Request_Pose_Type_O: The pose type of the waypoint returned by the Path Planning Step. 1 indicates joint positions, while 2 indicates TCP.
-
Command: The function code, whose value is assigned by the FB automatically.
-
Command_Trigger: The function switch, which is triggered by the FB automatically.
Data returned by the MM Interface DB:
-
Status code: If there is no error, status code 1103 will be returned. Otherwise, the corresponding error code will be returned.
-
Status of Pose Sent: 1 means that the written pose data is new data. After PLC reads the pose data, please reset this register.
-
Number of Pose Sent: Store the number of received waypoints output by the “Path Planning” Step, from 1 to 20.
-
Index of Vision Move: Store the position of the Vision Move waypoint in the path.
-
Target Pose: Store the received waypoint poses in the form of joint positions or the XYZ Euler angles, depending on the input parameter Request_Pose_Type.
-
Target Label: Store the integer labels corresponding to the poses. Labels are set in Mech-Vision.
-
Target Tool ID: The tool ID specified in the path planning tool.
Example
Example Description
In this example, the value of “Camera_User”.Step_Num is set to 12. After the “MM_Get_Planned_VisData” function is enabled, when variable “Camera_User”.Get_VisData is at the rising edge, the PLC receives the planned path from Mech-Vision project No.1 and the waypoints are in the form of JPs.
Get Mech-Vision Custom Output
This function obtains data from the custom port(s) of the Output Step in Mech-Vision.
| The number of custom ports cannot exceed 10. The obtained custom data is sorted in a case-sensitive alphabetical order of ports. |
Parameters
IN
-
Vision_Proj_Num: Mech-Vision project ID, which is the number before the project name in the Project List panel in Mech-Vision.
-
Get_VisData: Obtain vision points from Mech-Vision project when a rising edge occurs.
-
Trigger_Acknowledge: Used to determine whether the vision system is triggered successfully by the Command_Trigger signal. 1 indicates that the vision system is triggered successfully, while 0 indicates that the Command_Trigger signal has not been received.
IN/OUT
-
Set_Flag: The triggering action flag.
OUT
-
Vision_Proj_Num_O: Mech-Vision project ID.
-
Command: The function code, whose value is assigned by the FB automatically.
-
Command_Trigger: The function switch, which is triggered by the FB automatically.
Data returned by the MM Interface DB:
-
Status code: If there is no error, status code 1100 will be returned. Otherwise, the corresponding error code will be returned.
-
Status of Pose Sent: 1 means that the written pose data is new data. After PLC reads the pose data, please reset this register.
-
Number of Pose Sent: Store the number of vision points returned by the vision system, from 1 to 20.
-
Target Pose: Store the waypoint poses sent by Mech-Vision as TCPs.
-
Target Label: Store the integer labels corresponding to the poses. Labels are set in Mech-Vision.
-
Custom Data Output: Obtain data from the custom ports.
Example
Example Description
In this example, the value of “Camera_User”.Step_Num is set to 10. After the “MM_Get_Custom_VisData” function is enabled, when variable “Camera_User”.Get_VisData is at the rising edge, the PLC retrieves the custom data output by Mech-Vision project No.1.
Start Mech-Viz Project
This function 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 then plans the path for picking.
Parameters
IN
-
Robot_Pose_Type: The robot pose type specifies the type of the pose of the real robot to be input to the Mech-Viz project. The value range is from 0 to 2.
-
Robot_Pose: The pose received from the robot, value depends on the value of Robot_Pose_Type. Data type: two-dimensional array [0..1, 0..5] of Real, array[0] is joint positions and array[1] is flange pose.
The following table explains the relationship between Robot_Pose_Type and Robot_Pose.
| Robot_Pose_Type value | Robot_Pose value | Description | Applicable Scenarios |
|---|---|---|---|
0 |
0, 0, 0, 0, 0, 0 |
No need to input the robot pose to Mech-Viz. The simulated robot in Mech-Viz moves from the initial pose JPs = [0, 0, 0, 0, 0, 0] to the first waypoint. |
Project is in the Eye To Hand mode. This setting is not recommended. |
1 |
Current joint positions and flange pose of the robot |
Robot joint positions and flange pose must be input to Mech-Viz. The simulated robot in Mech-Viz moves from the input JPs to the first waypoint. |
This setting is recommended for projects in the eye-in-hand mode. |
2 |
Specific joint positions of the robot |
The robot joint positions of a point determined by teaching must be input to Mech-Viz. The input joint positions are used to trigger Mech-Viz to plan the next path in advance while the robot is not in the camera capture region, as shown below. The simulated robot in Mech-Viz moves from the input joint positions to the first waypoint. |
This setting is recommended for projects in the eye-to-hand mode. |
|
The reason for setting Robot_Pose_Type to 2 when the project is in the Eye To Hand mode:
In the Eye To Hand mode, the camera can perform image capturing for the next round of path planning before the robot returns to the camera capture region and picking region, shortening the cycle time. If Robot_Pose_Type is set to 1, the robot’s current pose is sent to Mech-Viz. The simulated robot will move from the input pose to the first waypoint in the planned path, while the real robot might move to another point first, and then move to the first waypoint. Therefore, the path of the real robot may contain unpredicted collisions, leading to safety hazards. In conclusion, Robot_Pose_Type should be set to 2 for projects in the eye-to-hand mode. 
|
-
Start_Viz: Triggers Mech-Viz project to run at the rising edge.
-
Trigger_Acknowledge: Used to determine whether the vision system is triggered successfully by the Command_Trigger signal. 1 indicates that the vision system is triggered successfully, while 0 indicates that the Command_Trigger signal has not been received.
IN/OUT
-
Set_Flag: The triggering action flag.
OUT
-
Robot_Pose_Type_O: Robot pose type.
-
Robot_JPS: Robot joint positions.
-
Robot_Pose_TCP_O: Robot flange pose.
-
Command: The function code, whose value is assigned by the FB automatically.
-
Command_Trigger: The function switch, which is triggered by the FB automatically.
Data returned by the MM Interface DB:
-
Status code: If there is no error, status code 2103 will be returned. Otherwise, the corresponding error code will be returned.
Example
Example Description
In this example, the value of “Camera_User”.Step_Num is set to 18. After the “MM_Start_Viz” function is enabled, when variable “Camera_User”.Start_Viz is at the rising edge, the PLC triggers Mech-Viz project to run and sends the current joint positions and flange pose of the robot to Mech-Viz.
Stop Mech-Viz Project
This function stops the execution of the Mech-Viz Project.
Parameters
IN
-
Stop_Viz: Stops the execution of the Mech-Viz project at the rising edge.
-
Trigger_Acknowledge: Used to determine whether the vision system is triggered successfully by the Command_Trigger signal. 1 indicates that the vision system is triggered successfully, while 0 indicates that the Command_Trigger signal has not been received.
IN/OUT
-
Set_Flag: The triggering action flag.
OUT
-
Command: The function code, whose value is assigned by the FB automatically.
-
Command_Trigger: The function switch, which is triggered by the FB automatically.
Data returned by the MM Interface DB:
-
Status code: If there is no error, status code 2104 ill be returned. Otherwise, the corresponding error code will be returned.
Example
Example Description
In this example, the value of “Camera_User”.Step_Num is set to 20. After the “MM_Stop_Viz” function is enabled, when variable “Camera_User”.Stop_Viz is at the rising edge, the PLC stops the Mech-Viz project.
Select Mech-Viz Branch
This function 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 function specifies which exit port such Step(s) should take. MM_Start_Viz should be called BEFORE this function. When executing the “Branch by Msg” Step, Mech-Viz waits for the exit port No. sent by this function.
Parameters
IN
-
Branch_Name: Step ID of the Branch by Msg Step, which is a positive integer.
-
Branch_Exit_Port: The exit port of the Branch by Msg Step. If the parameter value is set to N, the Mech-Viz project will take the exit with an ID of N-1.
-
Set_Branch: The trigger signal for setting the branch. The rising edge does the trigger.
-
Trigger_Acknowledge: Used to determine whether the vision system is triggered successfully by the Command_Trigger signal. 1 indicates that the vision system is triggered successfully, while 0 indicates that the Command_Trigger signal has not been received.
IN/OUT
-
Set_Flag: The triggering action flag.
OUT
-
Branch_Name_O: Step ID of the Branch by Msg Step.
-
Branch_Exit_Port_O: The number of the exit port to take.
-
Command: The function code, whose value is assigned by the FB automatically.
-
Command_Trigger: The function switch, which is triggered by the FB automatically.
Data returned by the MM Interface DB:
-
Status code: If there is no error, status code 2105 will be returned. Otherwise, the corresponding error code will be returned.
Example
Example Description
In this example, the value of “Camera_User”.Step_Num is set to 24. After the “MM_Set_Branch” function is enabled, when variable “Camera_User”.Set_Branch is at the rising edge, the PLC instructs the Mech-Viz project to take exit 1 at the “Branch by Msg” Step with an ID of 1.
Set Current Index
This function sets the value of the Current Index parameter of move-type Steps. Steps that have this parameter include Move by List, Move by Grid, Custom Pallet Pattern, and Predefined Pallet Pattern. MM_Start_Viz must be called BEFORE this function.
Parameters
IN
-
Index_Name: Step ID of the index-type Step, which is a positive integer.
-
Index_Counter: The Current Index value of the index-type Step, which is a positive integer. When this parameter value is set to N, the Current Index value of the corresponding Step is N-1.
-
Set_Index: The trigger signal to set the index. The rising edge does the trigger.
-
Trigger_Acknowledge: Used to determine whether the vision system is triggered successfully by the Command_Trigger signal. 1 indicates that the vision system is triggered successfully, while 0 indicates that the Command_Trigger signal has not been received.
IN/OUT
-
Set_Flag: The triggering action flag.
OUT
-
Index_Name_O: The Step ID of the index-type Step.
-
Index_Counter_O: The Current Index value of the index-type Step.
-
Command: The function code, whose value is assigned by the FB automatically.
-
Command_Trigger: The function switch, which is triggered by the FB automatically.
Data returned by the MM Interface DB:
-
Status code: If there is no error, status code 2106 will be returned. Otherwise, the corresponding error code will be returned.
Example
Example Description
In this example, the value of “Camera_User”.Step_Num is set to 22. After the “MM_Set_Index” function is enabled, when variable “Camera_User”.Set_Index is at the rising edge, the PLC sets the Current Index value of Step 5 of the Mech-Viz project to 3.
Get Planned Path
This function obtains the planned path from Mech-Viz.
Parameters
IN
-
Request_Pose_Type: Specify the type of waypoint pose returned.
-
The pose type returned by Mech-Viz is joint positions.
-
The pose type returned by Mech-Viz is TCPs.
Request_Pose_Type here and Robot_Pose_Type in the MM_Start_Vis and MM_Start_Viz functions correspond to the same Pose Type parameter in the MM Interface data block. If the set values are different, they cannot take effect at the same time.
-
-
Get_VizData: Obtains the planned path from Mech-Viz at the rising edge.
-
Trigger_Acknowledge: Used to determine whether the vision system is triggered successfully by the Command_Trigger signal. 1 indicates that the vision system is triggered successfully, while 0 indicates that the Command_Trigger signal has not been received.
IN/OUT
-
Set_Flag: The triggering action flag.
OUT
-
Request_Pose_Type_O: The pose type of the waypoints returned by Mech-Viz. 1 indicates JPs, and 2 indicates TCP.
-
Command: The function code, whose value is assigned by the FB automatically.
-
Command_Trigger: The function switch, which is triggered by the FB automatically.
Data returned by the MM Interface DB:
-
Status code: If there is no error, status code 2100 will be returned. Otherwise, the corresponding error code will be returned.
-
Status of Pose Sent: 1 indicates that the pose data written in are new. After PLC reads the pose data, please reset this register.
-
Number of Pose Sent: Store the number of waypoints received from Mech-Viz. The value range is from 1 to 20.
-
Index of Vision Move: Store the position of the Vision Move waypoint in the path.
-
Target Pose: Store the received waypoint poses in the form of joint positions or the XYZ Euler angles, depending on the pose type set by the PLC.
-
Target Label: Store the object labels, which are recognized by Mech-Vision. The returned values are integers.
-
Target Tool ID: The tool ID specified in the Mech-Viz project.
Example
Example Description
In this example, the value of “Camera_User”.Step_Num is set to 26. After the “MM_Get_VizData” function is enabled, when variable “Camera_User”.Get_VizData is at the rising edge, the PLC receives the planned path from the Mech-Viz project and the waypoints are in the form of TCPs.
Get Gripper DO List
This function obtains the gripper DO list planned by Mech-Vision or Mech-Viz. MM_Get_Planned_VisData or MM_Get_VizData should be called BEFORE this function.
Before using this function, you must perform the following configurations in Mech-Vision or Mech-Viz.
-
Configure the Mech-Vision project
-
In the Path Planning Step, click Config wizard. In Global configuration, enable Box depalletizing.
-
In the Path Planning Step, click Config wizard, and then double-click the name of the robot tool. In the pop-up window, select Depalletizing vacuum gripper for Tool type, click Configure depalletizing vacuum gripper, and then configure DO signals according to needs.
-
-
Configure the Mech-Viz project
-
In the Vision Move Step of Mech-Viz, set Select Picking Method to Box depalletizing.
-
In Mech-Viz, double-click the tool name, select Depalletizing vacuum gripper for Tool type, click Configure depalletizing vacuum gripper, and then configure the DO signals according to needs.
-
Parameters
IN
-
Vision_Proj_Num: Specify the source of the gripper DO signal. The value can be:
-
0: Get gripper DO list from Mech-Viz.
-
Positive integer: Get gripper DO list from Mech-Vision. The positive integer is the ID of the Mech-Vision project.
-
-
Depalletize_Tool_Section_Count: The number of vacuum gripper sections.
-
Get_DoList: Obtain the DO list planned by Mech-Vision or Mech-Viz at the rising edge.
-
Trigger_Acknowledge: Used to determine whether the vision system is triggered successfully by the Command_Trigger signal. 1 indicates that the vision system is triggered successfully, while 0 indicates that the Command_Trigger signal has not been received.
IN/OUT
-
Set_Flag: The triggering action flag.
OUT
-
Vision_Proj_Num_O: The source of the DO signal list.
-
Depalletize_Tool_Section_Count_O: The number of vacuum gripper sections.
-
Command: The function code, whose value is assigned by the FB automatically.
-
Command_Trigger: The function switch, which is triggered by the FB automatically.
Data returned by the MM Interface DB:
-
Status code: If there is no error, status code 2102 (when the DO list is obtained from Mech-Viz) or 1106 (when the DO list is obtained from Mech-Vision) will be returned. Otherwise, the corresponding error code will be returned.
-
DO: The list of 64 DO values.
The DO signals returned by this function vary based on the deployed project.
-
Gripper DO signals planned by the Mech-Vision project
-
Under Global Configuration of the path planning tool, if Plan all vision results is disabled, this function returns 64 gripper DO signals that are planned in this round. Valid DO signals are non-negative integers ranging from 0 to 999. Invalid DO signals are -1, which serves as a placeholder.
For example, valid DO signals in the table below are 1, 3, 5, and 6, which means that the robot will set the values of these DO signals to ON.
1st
2nd
3rd
4th
5th
6th
7th
8th
…
63rd
64th
1
3
5
6
-1
-1
-1
-1
…
-1
-1
-
Under Global Configuration of the path planning tool, if Plan all vision results is enabled, Mech-Vision can perform multiple rounds of planning based on the same vision result. The 64 gripper DO signals returned by this function are obtained during all rounds of planning. In this case, you can use the number of vacuum gripper sections to differentiate the gripper DO signals obtained during each round of planning.
For example, if the number of vacuum gripper sections is 4 and the function returns 64 DO signals in total, each 4 DO signals are multi-section vacuum gripper signals obtained during each round of planning.
First round of planning
Second round of planning
…
16th round of planning
1st
2nd
3rd
4th
5th
6th
7th
8th
…
61st
62nd
63rd
64th
1
3
4
-1
1
4
-1
-1
…
-1
-1
-1
-1
-
-
Gripper DO signals planned by the Mech-Viz project
-
If Reuse Vision Result is not selected for the Vision Move Step, this function returns 64 gripper DO signals that are planned during this round. Valid DO signals are non-negative integers ranging from 0 to 999. Invalid DO signals are -1, which serves as a placeholder.
For example, valid DO signals in the table below are 1, 3, 5, and 6, which means that the robot will set the values of these DO signals to ON.
1st
2nd
3rd
4th
5th
6th
7th
8th
…
63rd
64th
1
3
5
6
-1
-1
-1
-1
…
-1
-1
-
If Reuse Vision Result is selected for the Vision Move Step and the Vision Move Step is used in a loop, Mech-Viz can perform multiple rounds of planning based on the same vision result. The 64 gripper DO signals returned by this function are obtained during all rounds of planning. In this case, you can use the number of vacuum gripper sections to differentiate the gripper DO signals obtained during each round of planning.
For example, if the number of vacuum gripper sections is 4 and the function returns 64 DO signals in total, each 4 DO signals are multi-section vacuum gripper signals obtained during each round of planning.
First round of planning
Second round of planning
…
16th round of planning
1st
2nd
3rd
4th
5th
6th
7th
8th
…
61st
62nd
63rd
64th
1
3
4
-1
1
4
-1
-1
…
-1
-1
-1
-1
-
Example
Example Description
In this example, "Camera_User".Step_Num is set to 6 to enable the "MM_Get_DoList" function. When a rising edge is detected for "Camera_User".Get_DoList, if Vision_Proj_Num is 0 and Depalletize_Tool_Section_Count is 3, the DO signal list returned by Mech-Viz will be saved to the DO array.
Input Object Dimensions to Mech-Vision
This function dynamically inputs object dimensions into the Mech-Vision project. The object dimensions are assigned to the Box Size Settings parameters of the “Read Object Dimensions” Step.
Parameters
IN
-
Vision_Proj_Num: Mech-Vision project ID, which is the number before the project name in the Project List panel in Mech-Vision.
-
External_Input_Box_Dimension: The 3D dimensions to input to the project in the unit of mm. The data type is Array[0..2] of Real.
-
Set_Box_Dimension: Inputs the object dimensions in the Mech-Vision project dynamically at the rising edge.
-
Trigger_Acknowledge: Used to determine whether the vision system is triggered successfully by the Command_Trigger signal. 1 indicates that the vision system is triggered successfully, and 0 indicates that the Command_Trigger signal has not been received.
IN/OUT
-
Set_Flag: The triggering action flag.
OUT
-
Vision_Proj_Num_O: Mech-Vision project ID.
-
External_Input_Box_Dimension_O: Length, width, and height values of the object.
-
Command: The function code, whose value is assigned by the FB automatically.
-
Command_Trigger: The function switch, which is triggered by the FB automatically.
Data returned by the MM Interface DB:
-
Status code: If there is no error, status code 1108 will be returned. Otherwise, the corresponding error code will be returned.
Example
Example Description
In this example, the value of “Camera_User”.Step_Num is set to 2. After the “MM_Set_Box_Dimension” function is enabled, when variable “Camera_User”.Set_Box_Dimension is at the rising edge, the PLC sets the object dimensions in the “Read Object Dimensions” Step to the value of variable External_Input_Box_Dimension.
Get Software Status
This function is for obtaining the software running status (at present, only whether Mech-Vision is ready to start running the project can be checked).
Parameters
IN
-
Get_Status: Check whether Mech-Vision is ready to run projects at the rising edge.
-
Trigger_Acknowledge: Used to determine whether the vision system is triggered successfully by the Command_Trigger signal. 1 indicates that the vision system is triggered successfully, and 0 indicates that the Command_Trigger signal has not been received.
IN/OUT
-
Set_Flag: The triggering action flag.
OUT
-
Command: The function code, whose value is assigned by the FB automatically.
-
Command_Trigger: The function switch, which is triggered by the FB automatically.
Data returned by the MM Interface DB:
-
Status code: If status code 1101 is returned, Mech-Vision is ready. Otherwise, Mech-Vision is not ready.
Example
Example Description
In this example, the value of “Camera_User”.Step_Num is set to 32. After the “MM_Get_Status” function is enabled, when variable “Camera_User”.Get_Status is at the rising edge, the PLC stores the obtained status code to variable Status code.
Clear Waypoint Data
This function clears the obtained data stored in Target_Pose, Target_Label, and Target_Tool_ID.
Parameters
IN
-
Start_Empty: Clear the data stored in Target Pose, Target Label, and Target Tool ID when it is set.
IN/OUT
-
Target_Pose: Obtained waypoint pose data.
-
Target_Label: Obtained waypoint label.
-
Target_Tool_ID: The obtained tool ID.
| This function should not always be in the enabled status. As IN/OUT parameters, Target_Pose, Target_Label and Target_Tool_ID will be read/written in each scan cycle if the function remains in the enabled status. Consequently, data already sent by the vision system might be overwritten. |
Example
Example Description
In this example, the value of “Camera_User”.Step_Num is set to 14. After the “MM_Empty_Target” function is enabled, when variable “Camera_User”.Start_Empty is at the rising edge, the PLC clears the obtained data in variables Target Pose, Target Label and Target Tool ID.
Get Vision Move Data or Custom Output Data
This function obtains Vision Move output from the Mech-Vision project, or the Vision Move output or custom output from the Mech-Viz project.
Parameters
IN
-
Vision_Proj_Num: Specify the source of the Vision Move data. The value can be:
-
0: Get Vision Move output from Mech-Viz.
-
Positive integer: Get Vision Move output from Mech-Vision. The positive integer is the Mech-Vision project ID.
-
-
Request_Pose_Type: The returned data format. The value range is from 1 to 4.
Request_Pose_Type here and Robot_Pose_Type in the MM_Start_Vis and MM_Start_Viz functions correspond to the same Pose Type parameter in the MM Interface data block. If the set values are different, they cannot take effect at the same time. -
When Vision_Proj_Num is 0, the value range of Request_Pose_Type is from 1 to 4. Detailed description is in the table below.
Robot_Pose_Type value Format of returned data (Explained below) 1
Pose (joint positions), motion type, tool ID, velocity, element 1 in custom output data, … element N in custom output data
2
Pose (TCP), motion type, tool ID, velocity, element 1 in custom output data, … element N in custom output data
3
Pose (joint positions), motion type, tool ID, velocity, Mech-Viz Vision Move data, element 1 in custom output data, … element N in custom output data
4
Pose (TCP), motion type, tool ID, velocity, Mech-Viz Vision Move data, element 1 in custom output data, … element N in custom output data
-
When Vision_Proj_Num is a positive integer, the value range of Request_Pose_Type is from 1 to 2. Detailed description is in the table below.
Robot_Pose_Type value Format of returned data (Explained below) 1
Pose (joint positions), motion type, tool ID, velocity, Mech-Vision Vision Move data
2
Pose (TCP), motion type, tool ID, velocity, Mech-Vision Vision Move data
Pose
The pose type of the waypoints can be robot’s joint positions or TCP, depending on the value of Request_Pose_Type.
Motion type
-
1: joint motion (MOVEJ)
-
2: linear motion (MOVEL)
Tool ID
The ID of the tool to be used at this waypoint. The value “-1” means that no tool will be used at this waypoint.
Velocity
The velocity of the waypoint in the form of percentage.
Vision Move data
Data output by the “Vision Move” Step in Mech-Vision or Mech-Viz, including labels of picked workobjects, number of picked workobjects, number of workobjects to be picked this time, edge/corner ID of vacuum gripper, TCP offset, orientation of workobject group, orientation of workobject, dimensions of workobject group.
Details on Vision Move data are in the table below.
Name Description Number of Elements Labels of picked workobjects
Consists of 10 integers. The default value is ten 0s.
10
Number of picked workobjects
The total number of workobjects that have been picked.
1
Number of workobjects to be picked this time
Number of workobjects to be picked this time
1
Edge/corner ID of vacuum gripper
The ID of the edge/corner used to pick workobjects this time.
1
TCP offset
The XYZ offset between the center of the workobject group and the tool pose center.
3
Orientation of workobject group
The relative position between the workobject group and the length of the vacuum gripper. The value is 0 or 1, where 0 stands for parallel and 1 for vertical.
1
Orientation of workobject
The relative position between the length of a workobject and that of the vacuum gripper. The value is 0 or 1, where 0 stands for parallel and 1 for vertical.
1
Dimensions of workobject group
The length, width and height of the workobject group to be picked this time.
3
Element in custom output data
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 number of custom ports cannot exceed 10. The obtained custom data is sorted in a case-sensitive alphabetical order of ports.
-
-
Get_VizData: Get Vision Move Data or custom output data at the rising edge.
-
Trigger_Acknowledge: Used to determine whether the vision system is triggered successfully by the Command_Trigger signal. 1 indicates that the vision system is triggered successfully, and 0 indicates that the Command_Trigger signal has not been received.
IN/OUT
-
Set_Flag: The triggering action flag.
OUT
-
Vision_Proj_Num_O: Mech-Vision project ID.
-
Request_Pose_Type_O: Returned data format.
-
Command: The function code, whose value is assigned by the FB automatically.
-
Command_Trigger: The function switch, which is triggered by the FB automatically.
Data returned by the MM Interface DB:
-
Status code: If there is no error, status code 2100 (when the Vision Move data or custom output data is obtained from Mech-Viz) or 1103 (when the Vision Move data is obtained from Mech-Vision) will be returned. Otherwise, the corresponding error code will be returned.
-
Status of Pose Sent: 1 means that the written pose data is new data. After PLC reads the pose data, please reset this register.
-
Number of Pose Sent: Store the number of received waypoints, from 1 to 20.
-
Index of Vision Picking Point: The position of the Vision Move waypoint in the entire robot motion path.
-
Target Pose: Store the received waypoint poses in the form of joint positions or the XYZ Euler angles, depending on the input parameter Request_Pose_Type.
-
Target Label: Label of a single waypoint.
-
Speed Percentage: The velocity at the waypoint.
-
Custom Vision Output: Data output by the custom ports.
-
Target IsVisualMove: Specify whether the waypoint is a Vision Move waypoint. 0 indicates that it is not a Vision Move waypoint, and 1 indicates that it is a Vision Move waypoint. Only Vision Move waypoint carries Vision Move data or custom output data.
-
Target Move Type: The motion type.
-
Target Tool ID: The ID of the tool.
-
VisualMove Planning Result:The data output by the Vision Move Step.
Example
Example Description
In this example, the value of “Camera_User”.Step_Num is set to 4 and the value of “Vision_Proj_Num” is set to 0. After the “MM_Get_Planned_Result” function is enabled, when variable “Camera_User”.Get_VizData is at the rising edge, the PLC obtains waypoints from the Mech-Viz project in the form of TCPs. When the value of Target IsVisualMove is 1, it indicates that the waypoint obtained from the vision system is a Vision Move waypoint. Data output by the Vision Move Step is stored in VisualMove Planning Result, data output by the custom ports is stored in Custom Vision Output.
Get Message from Notify Step
After the Mech-Vision or Mech-Viz project is triggered, this function can be called to get message from the “Notify” Step.
| When the “Notify” Step is executed in the Mech-Vision or Mech-Viz project, the message remains in the buffer of the vision system for only 1 second. Therefore, users should consider the timing of calling this function to ensure successful message retrieval. Additionally, after receiving the message, the PLC should clear the data in the register. |
Parameters
-
Get_Notify: Get a message from the “Notify” Step, triggered at a rising edge.
-
Trigger_Acknowledge: Used to determine whether the vision system is triggered successfully by the Command_Trigger signal. 1 indicates that the vision system is triggered successfully, and 0 indicates that the Command_Trigger signal has not been received.
IN/OUT
-
Set_Flag: The triggering action flag.
OUT
-
Command: The function code, whose value is assigned by the FB automatically.
-
Command_Trigger: The function switch, which is triggered by the FB automatically.
Data returned by the MM Interface DB:
-
Notify: The message from the Notify Step, which is an integer.
Example
For example, the message set in the “Notify” Step is 777, and the PLC is obtaining a message in the automatic mode.
Example Description
In this example, when “Camera_User”.Step_Num is set to 7 in the automatic mode, the value of “MM Interface”.FromCamera.Notify is not 777. After the “MM_Get_Custom_Notify” function is enabled, when variable “Camera_User”.Get_Notify is at the rising edge, the program retrieves the message from the “Notify” Step. If the message retrieval is successful, the value of “MM Modbus TCP Interface”.Notify changes to 777. Otherwise, if the value remains unchanged, the PLC will prompt an error after 3 seconds.
Appendix
Description of the Status Codes
Please refer to Status Codes and Troubleshooting for detailed information.