Siemens PLC Snap7
This topic introduces the commands of the Siemens PLC Snap7 Standard Interface.
Command 101: Start Mech-Vision Project
This function starts the Mech-Vision project that executes image capturing and performs vision recognition. This command is for applications that use only Mech-Vision but not Mech-Viz.
Parameters in Sent Command
| Parameter | DB offset |
|---|---|
Command code 101 |
2.0 |
Mech-Vision project ID |
8.0 |
Expected number of vision points |
6.0 |
Robot pose type |
4.0 |
Robot pose |
12.0 (joint positions) or 36.0 (flange pose) |
Mech-Vision project ID
You can view the Mech-Vision project ID in the Project List panel of Mech-Vision. The number before the project name is the Project ID.
Expected number of vision points
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 fromMech-Vision. -
Integer greater than 0: Receive the specified number of vision points in the recognition result from the Mech-Vision project.-
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 parameters of command 102 indicates if all the requested vision points have been obtained. If not, please repeat the calling of command 102. |
Robot pose type and robot pose
-
Robot pose type specifies the type of pose of the real robot to be input to Mech-Vision. The value range is 0–3.
-
The values of robot pose depend on the value of robot pose type.
The following table explains the relationship between the two parameters.
| Value of robot pose type | Value of robot pose | Description | Applicable scenario |
|---|---|---|---|
0 |
0, 0, 0, 0, 0, 0 |
No need to input robot pose to Mech-Vision |
The project is in the eye-to-hand setup. If the “Path Planning” Step is used in the Mech-Vision project, the planned path starts at the Home position 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 |
The project is in the eye-in-hand setup. Applicable to most robots (excluding truss robots). |
2 |
Current flange pose of the robot |
Robot flange pose must be input to Mech-Vision |
The project is in the eye-in-hand setup. The robot has no joint positions and only flange pose (such as truss 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 |
The project is in the eye-to-hand setup and the Mech-Vision project contains the “Path Planning” Step, whose start point needs to be set from the robot side. |
The data type of the robot pose is Real.
Command 102: Get Vision Target(s)
This command is called after command 101 to obtain the vision points output by Mech-Vision and automatically transform the vision points into vision targets.
The transformation process, in which the poses of vision points are transformed into the robot TCP, is as follows:
-
Rotate the poses around their X axes by 180 degrees.
-
Determine whether the definition of the reference frame used by the robot model involves robot base height, and add a vertical offset accordingly.
| This command can only fetch at most 20 vision targets at a time. Therefore, to obtain more than 20 vision targets, please repeat the calling of this command. |
Parameters in Sent Command
| Parameter | DB offset |
|---|---|
Command code 102 |
2.0 |
Mech-Vision project ID |
8.0 |
Mech-Vision project ID
You can view the Mech-Vision project ID in the Project List panel of Mech-Vision. The number before the project name is the Project ID.
Parameters in Returned Data
| Parameter | DB offset |
|---|---|
Status code |
200.0 |
Data transmission status |
202.0 |
Number of vision targets |
204.0 |
Reserved field |
/ |
Obtained robot TCPs |
208.0 |
Obtained labels |
1168.0 |
Status code
If there is no error, status code 1100 will be returned. Otherwise, the corresponding error code will be returned.
After calling this command, if the vision result from Mech-Vision is not returned within 10 seconds, the error code for timeout will be returned.
Data transmission status
This parameter indicates whether the data returned is new.
1: The returned data is new and can be read.
| After the newly returned data is read, reset this parameter to 0. |
Number of vision targets
The number of received vision targets.
-
If the requested number of vision targets is greater than or equal to the number of vision points output by Mech-Vision, all vision points output by Mech-Vision will be obtained.
-
If the requested number of vision targets is smaller than the number of vision points output by Mech-Vision, the requested number of vision points will be obtained.
Reserved field
This field is not currently in use. The value is 0 by default.
Obtained robot TCPs
Each TCP consists of the Cartesian coordinates (XYZ) and Euler angles (ABC).
Obtained labels
The integer labels corresponding to the obtained poses. If the labels in the Mech-Vision project are strings, please use the “Label Mapping” Step before the “Output” Step to map the labels to integers. If there are no labels in the project, the value of this parameter is 0 by default.
Command 103: Switch Mech-Vision Recipe
This function 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.
The parameters that can be altered by switching parameter recipes usually include the point cloud matching model, image matching template, ROI, and confidence threshold.
| This command must be called before command 101 is called. |
Parameters in Sent Command
| Parameter | DB offset |
|---|---|
Command code 103 |
2.0 |
Mech-Vision project ID |
8.0 |
Parameter recipe ID |
10.0 |
Mech-Vision project ID
You can view the Mech-Vision project ID in the Project List panel of Mech-Vision. The number before the project name is the Project ID.
Parameter recipe ID
The ID of the parameter recipe in the Mech-Vision project. The ID is a positive integer in the range of 1–99. To view the parameter recipe ID, in the lower right of Mech-Vision, click .
Command 105: Get Result of Step “Path Planning” in Mech-Vision
After calling command 101, call this command to obtain the collision-free picking path planned by the “Path Planning” Step in the Mech-Vision project.
When using this command, set the Port Type parameter of the “Output” Step in the Mech-Vision project to “Predefined (robot path)”.
| Before calling command 105, please set expected number of vision points of command 101 to 0 to reduce the times of calling command 105. If expected number of vision points of command 101 is set to 1, then every time command 105 is called, only 1 waypoint is returned, and command 105 must be called multiple times to obtain all the waypoints. |
Parameters in Sent Command
| Parameter | DB offset |
|---|---|
Command code 105 |
2.0 |
Mech-Vision project ID |
8.0 |
Waypoint pose type |
4.0 |
Mech-Vision project ID
You can view the Mech-Vision project ID in the Project List panel of Mech-Vision. The number before the project name is the Project ID.
Waypoint 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.
Parameters in Returned Data
| Parameter | DB offset |
|---|---|
Status code |
200.0 |
Data transmission status |
202.0 |
Number of waypoints |
204.0 |
Position of “Vision Move” in the planned path |
206.0 |
All waypoint poses returned |
208.0 |
All waypoint labels returned |
1168.0 |
Tool IDs of all waypoints sent this time |
1248.0 |
Status code
If there is no error, status code 1103 will be returned. Otherwise, the corresponding error code will be returned.
Data transmission status
This parameter indicates whether the data returned is new.
1: The returned data is new and can be read.
| After the newly returned data is read, reset this parameter to 0. |
Number of waypoints
The number of waypoints returned. The value range is 0 to 20. If the planned path contains more than 20 waypoints, please repeat the calling of this command.
Position of “Vision Move” in the planned path
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 any “Vision Move”, the value of this parameter is 0.
All waypoint poses returned
The Cartesian coordinates (XYZ in mm) and Euler angles (ABC in degrees), or joint positions (in degrees). The type is determined by the “waypoint pose type” parameter in the sent command.
All waypoint labels returned
The integer labels corresponding to the obtained poses. If the labels in the Mech-Vision project are strings, please use the “Label Mapping” Step before the “Output” Step to map the labels to integers. If there are no labels in the project, the value of this parameter is 0.
Tool IDs of all waypoints sent this time
The tool IDs set in the path planning tool.
Command 110: Get Custom Output Data from Mech-Vision
This command 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 “Output” Step. The output ports can be customized if the “Port Type” parameter of the Step is set to “Custom”.
Parameters in Sent Command
| Parameter | DB offset |
|---|---|
Command code 110 |
2.0 |
Mech-Vision project ID |
8.0 |
Mech-Vision project ID
You can view the Mech-Vision project ID in the Project List panel of Mech-Vision. The number before the project name is the Project ID.
Parameters in Returned Data
| Parameter | DB offset |
|---|---|
Status code |
200.0 |
Data transmission status |
202.0 |
Obtained robot TCPs |
208.0 |
Obtained labels |
1168.0 |
Custom port outputs |
1456.0 |
Status code
If there is no error, status code 1100 will be returned. Otherwise, the corresponding error code will be returned.
After calling this command, if the vision result from Mech-Vision is not returned within 10 seconds, the error code for timeout will be returned.
Data transmission status
This parameter indicates whether the data returned is new.
1: The returned data is new and can be read.
Obtained robot TCPs
Each TCP consists of the Cartesian coordinates (XYZ) and Euler angles (ABC).
Obtained labels
The object information label corresponding to the pose. The label should be a positive integer. If not, use the “Label Mapping” Step in the Mech-Vision project to map it to a positive integer. If the “Output” Step does not have a label port, this parameter is filled with 0.
Custom data items
The custom output data of the port corresponding to its data type in the Output Step.
The custom data items are arranged in alphabetical order of the custom port names.
Command 201: Start Mech-Viz Project
This function is for applications that use both Mech-Vision and Mech-Viz. This command 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.
| In Mech-Viz, right-click the project name in the Resources panel and select Autoload Project. |
Parameters in Sent Command
| Parameter | DB offset |
|---|---|
Command code 201 |
2.0 |
Robot pose type |
4.0 |
Robot pose |
12.0 (joint positions) or 36.0 (flange pose) |
Robot pose type and robot pose
-
Robot pose type specifies the type of pose of the real robot to be input to Mech-Viz. The value range is 0–2.
-
The values of robot pose depend on the value of robot pose type.
The following table explains the relationship between the two parameters.
| Value of robot pose type | Value of robot pose | Description | Applicable scenario |
|---|---|---|---|
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. |
The project is in the eye-to-hand setup. 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 setup. |
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 setup. |
The reason for setting robot pose type to 2 when the project is in the eye-to-hand setup:
In the eye-to-hand setup, 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, which may cause inconsistent paths of the simulated robot and the real robot. Therefore, the path of the real robot may contain unpredicted collisions, leading to safety hazards.
The simulated robot in Mech-Viz will move from the current pose to the waypoint set in the first move-type Step, while the real robot might move to another point first, and then move to that waypoint.
In conclusion, robot pose type should be set to 2 for projects in the eye-to-hand setup.
Command 202: Stop Mech-Viz Project
This command stops the execution of the Mech-Viz project. This command is only needed if the Mech-Viz project falls into an infinite loop or cannot be stopped normally.
Command 203: Select Mech-Viz Branch
This command 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.
Before calling this command, please call command 201 first.
When the next Step to execute is a “Branch by Msg” Step, the Mech-Viz project will wait for this command to specify the exit port to take.
Parameters in Sent Command
| Parameter | DB offset |
|---|---|
Command code 203 |
2.0 |
Step ID of the “Branch by Msg” Step |
60.0 |
Exit port number |
62.0 |
Step ID of the “Branch by Msg” Step
Step ID of the “Branch by Msg” Step. The value should be a positive integer. The Step ID is displayed in the parameters of the Step.
Exit port number
The number of the exit port to take. The Mech-Viz project will proceed along the workflow connected to this exit port. The value is a positive integer in the range of 1 to 99.
| This exit port number should be the output port number displayed in the Step plus 1. For example, if the output port number of the branch is 0, then the exit port number is 1. |
Command 204: Set Move Index
This function 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 “Predefined Pallet Pattern”.
Before calling this command, please call command 201 first.
Parameters in Sent Command
| Parameter | DB offset |
|---|---|
Command code 204 |
2.0 |
Step ID |
64.0 |
Index value |
66.0 |
Step ID
The Step 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 value
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 command, the Current Index value in Mech-Viz will be increased by 1.
Command 205: Get Planned Path
This command obtains the planned path from Mech-Viz.It should be used after calling command 201.
This command can only fetch at most 20 waypoints at a time by default. Therefore, to obtain more than 20 waypoints, please repeat the calling of this command.
|
If the waypoint of a move-type Step should not be sent to the robot in the project, please clear the “Send Waypoint” option in the parameters of this Step. |
Parameters in Sent Command
| Parameter | DB offset |
|---|---|
Command code 205 |
2.0 |
Waypoint type |
4.0 |
Waypoint type
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).
Parameters in Returned Data
| Parameter | DB offset |
|---|---|
Status code |
200.0 |
Data transmission status |
202.0 |
Number of waypoints |
204.0 |
Position of “Vision Move” in the planned path |
206.0 |
All waypoint poses returned |
208.0 |
All waypoint labels returned |
1168.0 |
Tool IDs of all waypoints sent this time |
1248.0 |
Status code
If there is no error, status code 2100 will be returned. Otherwise, the corresponding error code will be returned.
| After calling this command, if the vision result from Mech-Viz is not returned within 10 seconds, the error code for timeout will be returned. |
Data transmission status
This parameter indicates whether the data returned is new.
1: The returned data is new and can be read.
| After the newly returned data is read, reset this parameter to 0. |
Number of waypoints
The number of waypoints returned. The value range is 0 to 20. This command can only fetch at most 20 waypoints at a time by default. Therefore, to obtain more than 20 waypoints, please repeat the calling of this command.
Position of “Vision Move” in the planned path
The position of the “Vision Move” waypoint in the entire planned path.
For example, if the planned path consists 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 any “Vision Move”, the value of this parameter is 0.
All waypoint poses returned
The Cartesian coordinates (XYZ in mm) and Euler angles (ABC in degrees), or joint positions (in degrees). The type is determined by the “waypoint pose type” parameter in the command 205.
All waypoint labels returned
The integer labels corresponding to the obtained poses. If the labels in the Mech-Vision project are strings, please map them to integers by using the “Label Mapping” Step before output. If there are no labels in the project, the value of this parameter is 0.
Tool IDs of all waypoints sent this time
The tool IDs set in the Mech-Viz project.
Command 206: Get DO List
This function gets the planned DO signal list. The DO signal list is used to control multiple grippers or multiple suction cup sections.
Before calling this command, please call command 205 to obtain the planned motion path from Mech-Viz.
Please deploy the Mech-Viz project based on the example project and set the corresponding suction cup configuration file. The example project is stored in the Mech-Mind Software Suite installation directory (in the Communication Component\tool\viz_project\suction_zone folder).
In the parameters of the “Set DO List” Step in Mech-Viz:
-
Select the “Standard Interface” checkbox under “Receiver”.
-
Select the “Get DO List from ‘Vision Move’” checkbox.
-
Select a “Vision Move” Step that needs the DO signal list in the “Select ‘Vision Move’” drop-down list.
Parameters in Returned Data
| Parameter | DB offset |
|---|---|
Status code |
200.0 |
DO signal list |
1408.0 |
Status code
If there is no error, status code 2102 will be returned. Otherwise, the corresponding error code will be returned.
DO signal values
A total of 64 integer DO signal values are returned.
Value range: 0–999.
Placeholder value: -1.
For example, if the DO signal values are 1, 3, 5, and 6, the returned data looks like the following:
| 1 | 3 | 5 | 6 | -1 | -1 | -1 | -1 | ... | -1 | -1 |
|---|---|---|---|---|---|---|---|---|---|---|
First value |
Second value |
Third value |
Fourth value |
Fifth value |
Sixth value |
Seventh value |
Eighth value |
... |
Sixty-third value |
Sixty-fourth value |
Command 501: Input Object Dimensions to Mech-Vision
This function is used for dynamically inputting 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, and the Read Sizes from Properties parameter of this Step should be checked.
Parameters in Sent Command
| Parameter | DB offset |
|---|---|
Command code 501 |
2.0 |
Mech-Vision project ID |
8.0 |
[Length, width, height] |
68.0 |
Mech-Vision project ID
You can view the Mech-Vision project ID in the Project List panel of Mech-Vision. The number before the project name is the Project ID.
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.
Unit: mm
Command 901: Get Software Status
This command is designed for obtaining the software execution status.
Currently, this command is capable of checking whether Mech-Vision is ready to run projects.
Parameters in Returned Data
| Parameter | DB offset |
|---|---|
Status code |
200.0 |
Status code
Software status. Status code 1101 indicates that Mech-Vision is ready to run projects. Other status codes indicate that Mech-Vision is not ready. The command is currently capable of checking whether Mech-Vision is ready to run projects.