Siemens PLC Snap7 Standard Command Description

This section introduces the standard interface commands based on Siemens Snap7 protocol (hereinafter referred to as S7 protocol).

Command Overview

RVS 2.0 S7 protocol supports the following standard commands:

• 101 Command: Run RVS 2.0 Project

• 102 Command: Get Vision Results

• 103 Command: Switch Parameter Recipe

• 109 Command: Get User Label Data

• 110 Command: Get Custom Data

• 501 Command: Pass Object Dimensions to RVS 2.0 Project

• 901 Command: Get System Status

Register Description

Field Name	Type	Offset/Address	Description
Command Trigger	Bool	0.0	Trigger signal
Command	Int	2.0	Command code
Pose Type	Int	4.0	Pose type
Pose Number	Int	6.0	Expected vision point or path point count
Vision Project No.	Int	8.0	Project number
Recipe No.	Int	10.0	Parameter recipe number
Flange Pose	Array[0..5] of Real	36.0	Flange pose data
External Input Box Dimension	Array[0..2] of Real	68.0	Object dimensions passed into the RVS 2.0 project
Index Counter	Int	108.0	Index count
Index Name	Int	110.0	Index number

Field Name	Type	Offset/Address	Description
Trigger Acknowledge	Bool	194.0	Trigger acknowledgment
Status Code	Int	200.0	Status code
Status of Pose Sent	Bool	202.0	Whether all vision points have been obtained
Number of Pose Sent	Int	204.0	Number of vision points
Target Pose	Array[0..39, 0..5] of Real	208.0	Poses of all vision points obtained this time
Target Label	Array[0..39] of Int	1168.0	Labels of all vision points obtained this time
Target Tool ID	Array[0..39] of Int	1248.0	End tool IDs of all vision points obtained this time

Command Sending and Receiving

The robot or host computer, acting as the server, sends commands to the RVS 2.0 vision system, which acts as the client. After processing the command, the vision system returns the result to the robot or host computer.

Attention

The current version only supports this software running as an S7 client.

Command Data Units

• RVS 2.0 software internally uses quaternions to represent poses, but they are automatically converted to Euler angle form during command communication.

• A robot flange pose or robot tool pose consists of position and orientation. Position values (X, Y, Z) are measured in millimeters (mm), and orientation is expressed in Euler angles measured in degrees (°).

101 Command: Run RVS 2.0 Project

Description

This command starts the specified RVS 2.0 project. During execution, the vision system captures images, processes them, runs the configured algorithms, and then outputs a set of vision points.

Attention

Vision Point: The information unit used to describe a target object identified by the system. Each vision point contains the object’s pose, label, dimensions, and user-defined data.

Calling Sequence

• Step parameters in the project need to be set before running the project. Therefore, 103 Command: Switch Parameter Recipe must be called before the 101 command.

• Only after running the project can the vision system obtain vision points. Therefore, the 101 command must be called before 102 Command: Get Vision Results or 109 Command: Get User Label Data.

Input Parameters

Name	Data Type	Offset	Description
Command	Int	2.0	Command code is 101
Vision Project No.	Int	8.0	RVS 2.0 project number
Pose Number	Int	6.0	Expected vision point count
Pose Type	Int	4.0	Robot pose type
Flange Pose	Array[0..5] of Real	36.0	Robot pose, Flange Pose is flange pose data

Parameters

Parameter	Description
RVS 2.0 Project Number	View in the project list window. The number before the project name is the number.
Expected Vision Point Count	Expected number of vision points to obtain: 0: Obtain all vision points output by the project. Positive integer: Obtain the specified number of vision points. If the actual output is less than this value, all will be returned; if greater than or equal to this value, the specified number will be returned.
Robot Pose Type	Specifies the input form of robot pose: 0: Do not input robot pose. 2: Input the robot’s current flange pose.
Robot Pose	Pass corresponding data according to “Robot Pose Type”. See the table below for details.

Robot Pose Type and Pose Data Description

Robot Pose Type	Robot Pose Format	Description	Applicable Scenario
0	0,0,0,0,0,0 (placeholder, actually invalid)	Do not pass robot pose to the vision system.	Used when camera is Eye To Hand and project does not require pre-photo capture.
2	Robot’s current flange pose	Pass the robot’s current flange pose for the vision system to calculate camera position.	Applicable to most scenarios, especially Eye In Hand camera mounting.

Output Parameters

Field Name	Type	Offset/Address	Description
Status Code	Int	200.0	Status code

If the command executes successfully, the status code is 1102; otherwise, the corresponding error code is returned. See RVS 2.0 Error Codes for details.

102 Command: Get Vision Results

Description

This command is used to obtain the vision results (a series of vision points) output after the RVS 2.0 project runs. The object poses in the vision points (corresponding to the Any port data of the “Vision Output” step) have been converted by the vision system to the corresponding robot tool poses.

Calling Sequence

This command must be called after the 101 Command: Run RVS 2.0 Project has successfully run the project and the 109 Command: Get User Label Data has been called. After this command is called to retrieve data, the data of the “Vision Output” step is cleared.

Input Parameters

Name	Data Type	Offset	Description
Command	Int	2.0	Command code is 102
Vision Project No.	Int	8.0	RVS 2.0 project number
Index Counter	Int	108.0	Index count
Index Name	Int	110.0	Index number

RVS 2.0 Project Number

Must be consistent with the project number run in the 101 command.

Index Count and Index Number (Optional)

Specifies the count and numbers of vision points to obtain. Index starts from 0. For example, if there are currently 3 vision points and you want to obtain 2 this time, you can specify the desired combination by index number (for example, 0,1, 0,2, or 1,2).

Output Parameters

Name	Data Type	Offset	Description
Status Code	Int	200.0	Status code
Status of Pose Sent	Bool	202.0	Whether all vision points have been obtained
Number of Pose Sent	Int	204.0	Number of vision points
Target Pose	Array[0..39, 0..5] of Real	208.0	Poses of all vision points obtained this time
Target Label	Array[0..39] of Int	1168.0	Labels of all vision points obtained this time
Target Tool ID	Array[0..39] of Int	1248.0	End tool IDs of all vision points obtained this time

Parameters

Parameter	Description
Status Code	1100: Execution successful; others are error codes. See RVS 2.0 Error Codes.
Whether All Vision Points Have Been Obtained	False: Not all vision points have been obtained. True: All vision points have been obtained.
Vision Point Count	Number of vision points returned this time.
Poses of all vision points obtained this time	Poses of all vision points obtained this time, in the form of robot tool poses. The vision system automatically converts the object pose of each vision point (that is, the Any port data of the “Vision Output” step) into the corresponding robot tool pose.
Labels of all vision points obtained this time	Labels of all vision points obtained this time. If there is no label information, the label value defaults to 0.
End tool IDs of all vision points obtained this time	End tool IDs of all vision points obtained this time. If none, it defaults to 0.

103 Command: Switch Parameter Recipe

Description

This command is used to switch the parameter recipe used by the RVS 2.0 project.

Calling Sequence

This command must be called before 101 Command: Run RVS 2.0 Project.

Input Parameters

Name	Data Type	Offset	Description
Command	Int	2.0	Command code is 103
Vision Project No.	Int	8.0	RVS 2.0 project number
Recipe No.	Int	10.0	Parameter recipe number

The parameters are described below:

• RVS 2.0 Project Number

  Check the project list window; the number before the project name is the project number.

• Parameter Recipe Number

  See Edit a parameter recipe.

Output Parameters

Field Name	Type	Offset/Address	Description
Status Code	Int	200.0	Status code

If the command executes normally, the status code is 1107; otherwise, the corresponding error code is returned. See RVS 2.0 Error Codes for details.

109 Command: Get User Label Data

Description

This command is used to obtain the user label data defined by the RVS 2.0 project (that is, the input to the User Label pin of the Vision Output step).

Calling Sequence

This command must be called after the 101 Command: Run RVS 2.0 Project has successfully run the project, and before the 102 Command: Get Vision Results.

Input Parameters

Name	Data Type	Offset	Description
Command	Int	2.0	Command code is 109
Vision Project No.	Int	8.0	RVS 2.0 project number

RVS 2.0 Project Number

Must be consistent with the project number run in the 101 command.

Output Parameters

Name	Data Type	Offset	Description
Status Code	Int	200.0	Status code
Target Label	Array[0..39] of Int	1168.0	User label data obtained this time
Status of Pose Sent	Bool	202.0	Whether all user label data has been obtained

If the command executes normally, the status code is 1100; otherwise, the corresponding error code is returned. See RVS 2.0 Error Codes for details.

110 Command: Get Custom Data

Description

This command obtains custom port data from the “Vision Output” step and allows you to configure the input ports as needed.

Attention

1. The data from the preset ports shown at the top of the figure, such as poses, labels, sizes, and offsets, is predefined data, not custom data.

2. The Port Type parameter of the “Vision Output” step must be set to “Custom”, and the poses port is required.

Calling Sequence

This command must be called after 101 Command: Run RVS 2.0 Project.

Input Parameters

Name	Data Type	Offset	Description
Command	Int	2.0	Command code is 110
Vision Project No.	Int	8.0	RVS 2.0 project ID

RVS 2.0 Project ID

You can check the ID of an RVS 2.0 project in the Project List panel. The number before the project name is its ID. Ensure that the Vision Project No. used in the 101 command is consistent with the project ID.

Output Parameters

Name	Data Type	Offset	Description
Status Code	Int	200.0	Status code
Status of Pose Sent	Bool	202.0	Whether all vision points have been obtained
Target Pose	Array[0..39, 0..5] of Real	208.0	Poses of all vision points obtained this time
Target Label	Array[0..39] of Int	1168.0	Labels of all vision points obtained this time
Custom Vision Output	Array[0..39, 0..9] of Real	1456.0	Custom data of all vision points obtained this time

Status Code

Status code 1100 is returned on successful command execution. On failure, the corresponding error code is returned. See RVS 2.0 Error Codes for details.

Status of Pose Sent

This parameter indicates whether all vision points have been obtained. The value is False or True.

• False: Not all vision points are obtained.

• True: All vision points are obtained.

Target Pose

This parameter indicates the poses of all vision points obtained this time. The vision system automatically converts the object pose of each vision point (that is, the data from the poses port of the “Vision Output” step) into the corresponding robot tool pose. The conversion process is as follows:

1. Convert the object pose from quaternion form to Euler angles.

2. Rotate the object pose 180° around the X-axis so that its Z-axis points downward.

Target Label

This parameter indicates the labels of all vision points obtained this time.

Note

• The label must be a string in integer format.

• If there is no label information, the label value defaults to 0.

Custom Vision Output

Custom data of all vision points obtained this time. The custom data items are arranged in alphabetical order by custom port name.

For example, if the data output from the ports of the “Vision Output” step is as shown in the table below, the robot obtains [0, 0, 1] and [0, 0] for the custom data items of the first vision point, and [1, 0, 0] and [1, 1] for those of the second vision point.

Port Name	poses	labels	Custom Data 1	Custom Data 2
Port Data	[	[	[	[
	[0, 0, 0, 1, 0, 0, 0],	“0”,	[0, 0, 1],	[0, 0],
	[0, 0, 0, 1, 0, 0, 0],	“1”	[1, 0, 0]	[1, 1]
	]	]	]	]
First vision point	[0, 0, 0, 1, 0, 0, 0]	0	[0, 0, 1]	[0, 0]
Second vision point	[0, 0, 0, 1, 0, 0, 0]	1	[1, 0, 0]	[1, 1]

501 Command: Input Object Dimensions into an RVS 2.0 Project

Description

This command inputs object dimensions into an RVS 2.0 project. The input dimensions are the values of the Box Size Settings parameters of the “Read Object Dimensions” step, as shown below.

Attention

When using this command, only one “Read Object Dimensions” step is allowed in an RVS 2.0 project. Otherwise, the vision system returns an error.

Calling Sequence

This command must be called before 101 Command: Run RVS 2.0 Project.

Input Parameters

Name	Data Type	Offset	Description
Command	Int	2.0	Command code is 501
Vision Project No.	Int	8.0	RVS 2.0 project ID
External Input Box Dimension	Array[0..2] of Real	68.0	Object dimensions (length, width, height) to be input into the RVS 2.0 project

Vision Project No.

You can check the ID of an RVS 2.0 project in the Project List panel. The number before the project name is its ID. Ensure that the Vision Project No. used in the 101 command is consistent with the project ID.

External Input Box Dimension

The length, width, and height of the object, in millimeters (mm). The values are read by the “Read Object Dimensions” step and written to the Length on X-axis, Length on Y-axis, and Length on Z-axis parameters respectively.

Output Parameters

Name	Data Type	Offset	Description
Status Code	Int	200.0	Status code

Status Code

Status code 1108 is returned on successful command execution. On failure, the corresponding error code is returned. See RVS 2.0 Error Codes for details.

901 Command: Get System Status

Description

This command checks whether the RVS 2.0 vision system is ready, including the RVS 2.0 status and the camera status.

Input Parameters

Name	Data Type	Offset	Description
Command	Int	2.0	Command code is 901

Output Parameters

Name	Data Type	Offset	Description
Status Code	Int	200.0	Status code

Status Code

Status code 1101 is returned on successful command execution. On failure, the corresponding error code is returned. See RVS 2.0 Error Codes for details.