TCP 标准指令说明
本文介绍基于 TCP/IP 协议的标准接口指令。
指令总览
RVS 2.0 TCP 通信支持以下标准指令：
指令说明
指令的收发
机器人或上位机（客户端）向 RVS 2.0 视觉系统（服务端）发送指令，视觉系统处理完成后将结果返回给机器人或上位机。
注意
当前版本仅支持本软件作为 TCP 服务端运行。
指令的数据传输格式
指令支持 ASCII 和 HEX 两种编码格式。
ASCII
ASCII 格式字符串使用英文逗号作为数据分隔符，末尾终止符为 \r。本文示例均采用 ASCII 格式字符串，并省略末尾终止符（\r）。
例如，机器人向视觉系统发送 103 指令时，若包含末尾终止符，指令格式如下：
103,1,2\r
HEX
HEX（十六进制）字节序分为大端和小端。发送指令时，字节长度固定为 64；若不足 64，则使用 0 填充；若超过 64，视觉系统将忽略超出部分。
以 ASCII 格式字符串“103,1,2”为例，若以 HEX 大端形式发送，指令格式如下。十进制数 103 对应十六进制数 67，其大端字节序表示为 00 00 00 67。
00 00 00 67 00 00 00 01 00 00 00 02 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
若以 HEX 小端形式发送，指令格式如下。十六进制数 67 的小端字节序表示为 67 00 00 00。
67 00 00 00 01 00 00 00 02 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
指令的数据单位
关节角单位为度（°）。
机器人法兰位姿或机器人工具位姿由位置和姿态组成：位置（XYZ 坐标值）单位为毫米（mm），姿态采用欧拉角表示，单位为度（°）。
101 指令：运行 RVS 2.0 工程
功能介绍
该指令用于触发指定的 RVS 2.0 工程运行。工程运行期间，视觉系统将依次执行拍照、图像处理与算法分析，并最终输出一系列视觉点。
注意
视觉点：指系统识别出的目标物体信息单元，每个视觉点包含物体的位姿、标签、尺寸及用户自定义数据等。
调用顺序
工程中的步骤参数需在运行工程之前设置，因此 103 指令：切换参数配方 需先于 101 指令 调用。
只有运行工程后，视觉系统才会生成视觉点，因此 101 指令 需先于 102 指令：获取视觉结果 或 109 指令：获取用户标签数据 调用。
发送格式
101,RVS 2.0 工程编号,预期视觉点数量,机器人位姿类型,机器人位姿
参数说明
参数 |
说明 |
|---|---|
RVS 2.0 工程编号 |
在工程列表窗口中查看，工程名称前的数字即为编号。 |
预期视觉点数量 |
期望获取的视觉点数量： |
机器人位姿类型 |
指定机器人位姿的传入形式： |
机器人位姿 |
根据“机器人位姿类型”传入对应数据，详见下表。 |
机器人位姿类型与位姿数据说明
机器人位姿格式 |
说明 |
适用场景 |
|
|---|---|---|---|
0 |
0,0,0,0,0,0（占位参数，实际无效） |
不向视觉系统传入机器人位姿。 |
相机为 Eye To Hand（眼在手外）安装，且项目无需提前拍照时使用。 |
2 |
机器人当前法兰位姿 |
传入机器人当前法兰位姿，用于视觉系统计算相机位置。 |
适用于绝大多数场景，尤其是 Eye In Hand（眼在手上）安装方式。 |
返回格式
101,状态码
其中，若指令执行成功，状态码为 1102；若指令执行异常，则状态码为对应的错误码，具体参见 RVS 2.0 错误状态码。
指令实例
实例 1：Eye In Hand 场景，传入法兰位姿
机器人向视觉系统发送如下指令（2 表示机器人向视觉系统传入当前法兰位姿），触发工程 1 运行：
101,1,1,2,350.25,150.72,480.36,-179.88,0.12,90.05
视觉系统向机器人返回如下结果（1102表示成功触发 RVS 2.0 工程）：
101,1102
实例 2：Eye To Hand 场景，不传法兰位姿
机器人向视觉系统发送如下指令（机器人位姿类型为 0），触发工程 1 运行：
101,1,1,0,0,0,0,0,0,0
视觉系统向机器人返回如下结果（1102表示成功触发 RVS 2.0 工程）：
101,1102
实例 3：工程未注册错误
机器人向视觉系统发送如下指令，请求未注册的工程 2：
101,2,1,0,0,0,0,0,0,0
视觉系统向机器人返回如下结果（1011表示 RVS 2.0 工程未注册）：
101,1011
102 指令：获取视觉结果
功能介绍
该指令用于获取 RVS 2.0 工程运行后输出的视觉结果（即一系列视觉点）。视觉点中的物体位姿（对应“视觉输出”步骤的 Any 端口数据）已由视觉系统转换为对应机器人的工具位姿。
调用顺序
该指令需在 101 指令：运行 RVS 2.0 工程 成功运行工程、且已调用 109 指令：获取用户标签数据 之后调用。调用该指令获取数据后，“视觉输出”步骤的数据将被清空。
发送格式
102,RVS 2.0 工程编号,本次想获取的视觉点数量,视觉点的索引编号
RVS 2.0 工程编号
需与 101 指令中运行的工程编号一致。
本次想获取的视觉点数量（可选项）
指定本次要获取的视觉点个数，取值为正整数。 若实际输出的视觉点数量少于该值，则全部返回；否则仅返回指定数量的视觉点。
视觉点的索引编号（可选项）
指定要获取的视觉点索引编号，索引从 0 开始。 例如，当前共有 3 个视觉点，本次要获取 2 个，可通过索引编号指定具体组合（如 0,1、0,2 或 1,2）。
返回格式
102,状态码,是否已获取所有视觉点,视觉点数量,保留字段,视觉点1(工具位姿, 标签, 末端工具编号),视觉点2(工具位姿, 标签, 末端工具编号),…
参数 |
说明 |
|---|---|
状态码 |
1100：执行成功；其他为错误码，具体参见 RVS 2.0 错误状态码。 |
是否已获取所有视觉点 |
0：未获取全部视觉点。 |
视觉点数量 |
本次返回的视觉点个数。 |
保留字段 |
暂未使用，固定值为0。 |
视觉点 |
每个视觉点由 8 个数据 构成： |
工具位姿转换说明
视觉系统会将视觉点的物体位姿（即“视觉输出”步骤的 Any 端口数据）自动转换为对应的机器人工具位姿。
RVS 2.0 软件内部使用四元数表示位姿，但指令通信时会自动转换为欧拉角形式。
指令实例
实例 1：获取单个视觉点
工程运行后共产生 2 个视觉点，分两次获取，每次获取一个视觉点：
运行工程
机器人发送 101 指令，触发工程 2 运行（1 表示期望一次获取一个视觉点）：
101,2,1,2,352.10,148.33,479.85,-179.92,0.08,89.98
视觉系统返回运行成功：
101,1102
获取第 1 个视觉结果
机器人发送 102 指令，获取第 1 个视觉点：
102,2
视觉系统返回第 1 个视觉点：
102,1100,0,1,0,125.48,320.76,85.21,179.95,0.03,-90.12,0,0
获取第 2 个视觉结果
机器人发送 102 指令，获取第 2 个视觉点：
102,2
视觉系统返回第 2 个视觉点：
102,1100,1,1,0,130.25,315.42,82.15,178.92,1.25,-88.76,0,0
实例 2：一次性获取多个视觉点
以获取 2 个视觉点为例：
运行工程
机器人发送 101 指令，触发工程 2 运行（0 表示期望获取全部视觉点）：
101,2,0,2,352.10,148.33,479.85,-179.92,0.08,89.98
视觉系统返回运行成功：
101,1102
获取视觉结果
机器人发送 102 指令，获取视觉点：
102,2
视觉系统返回 2 个视觉点：
102,1100,1,2,0,125.48,320.76,85.21,179.95,0.03,-90.12,0,0,130.25,315.42,82.15,178.92,1.25,-88.76,0,0
实例 3：无视觉结果时返回
运行工程
机器人发送 101 指令，触发工程 3 运行：
101,3,1,2,355.00,152.50,481.20,-179.95,0.15,90.10
视觉系统返回运行成功：
101,1102
获取视觉结果
机器人发送 102 指令：
102,3
视觉系统返回错误（当前无视觉结果）：
102,1002
实例 4：按索引获取指定视觉点组合
工程运行后共产生 3 个视觉点，本次希望只获取其中 2 个，并通过索引编号指定获取第 1 个和第 3 个视觉点。
运行工程
机器人发送 101 指令，触发工程 4 运行（0 表示期望获取全部视觉点）：
101,4,0,2,351.20,149.60,478.40,-179.90,0.10,90.00
视觉系统返回运行成功：
101,1102
按索引获取视觉结果
机器人发送 102 指令，本次希望获取 2 个视觉点，并通过索引 0,2 指定获取第 1 个和第 3 个视觉点：
102,4,2,0,2
视觉系统返回 2 个指定视觉点：
102,1100,1,2,0,120.35,318.40,84.10,179.80,0.15,-89.95,1,0,133.72,309.18,81.64,178.55,1.02,-87.43,3,0
103 指令：切换参数配方
功能介绍
该指令用于切换 RVS 2.0 工程所使用的参数配方。
调用顺序
该指令需在 101 指令：运行 RVS 2.0 工程 之前调用。
发送格式
103,RVS 2.0 工程编号,参数配方编号
其中，
RVS 2.0 工程编号
在工程列表窗口中查看，工程名称前的数字即为编号。
参数配方编号
返回格式
103,状态码
其中，若指令执行正常，则状态码为 1107。若指令执行异常，则状态码为对应的错误码，具体参见 RVS 2.0 错误状态码。
指令实例
机器人向视觉系统发送如下指令，将工程 1 的参数配方编号切换为 2。
103,1,2
若视觉系统向机器人返回如下结果，则表示指令执行正常。1107 表示已成功将工程 1 的参数配方编号切换为 2。
103,1107
若视觉系统向机器人返回如下结果，则表示指令执行异常。1012 表示设置的参数配方编号无对应的参数配方。
103,1012
109 指令：获取用户标签数据
功能介绍
该指令用于获取 RVS 2.0 工程定义的用户标签数据（对应视觉输出步骤“用户标签”引脚的输入）。
调用顺序
该指令需在 101 指令：运行 RVS 2.0 工程 成功运行工程之后调用，并在 102 指令：获取视觉结果 之前调用。
发送格式
109,RVS 2.0 工程编号
RVS 2.0 工程编号
需与 101 指令中运行的工程编号一致。
返回格式
109,状态码,预留字段,用户标签的个数,预留字段,标签数据
参数 |
说明 |
|---|---|
状态码 |
1100：执行成功；其他为错误码，具体参见 RVS 2.0 错误状态码。 |
用户标签数 |
用户标签的个数。 |
用户标签数据 |
用户标签的数据。 |
指令实例
运行工程
机器人向视觉系统发送 101 指令，触发工程 1 运行：
101,1,0,2,350.25,150.72,480.36,-179.88,0.12,90.05
视觉系统向机器人返回运行成功：
101,1102
获取用户标签数据
机器人向视觉系统发送 109 指令：
109,1
视觉系统向机器人返回结果，表示指令执行成功（视觉输出步骤“用户标签”引脚的输入为 [1,2,3,4,5,6]）：
109,1100,0,6,0,1,2,3,4,5,6
110 指令：获取自定义数据
功能介绍
该指令用于获取“视觉输出”步骤的自定义端口数据，输入端口可根据需求自定义配置。
注意
图中上方的
poses、labels、sizes、offsets等预设端口数据不属于自定义数据。“视觉输出”步骤的 端口类型 参数需设置为“自定义”，且必须存在
poses端口。
调用顺序
该指令需在 101 指令：运行 RVS 2.0 工程 成功运行工程之后调用。
发送格式
110,RVS 2.0 工程编号
RVS 2.0 工程编号
需与 101 指令中运行的工程编号一致。
返回格式
110,状态码,是否已获取所有视觉点,自定义数据的个数,位姿,标签,自定义数据项1,…,自定义数据项N
状态码
若指令执行正常，则状态码为 1100。若指令执行异常，则状态码为对应的错误码， 具体参见 RVS 2.0 错误状态码。
是否已获取所有视觉点
0：未获取全部视觉点。
1：已获取全部视觉点。
备注
执行一次该指令，仅获取一个视觉点对应的位姿和自定义数据。如需获取多个视觉点的自定义数据，请多次执行该指令。
在编写程序时，可通过判断该参数值是否为 1，从而判断是否已获取所有视觉点。若该参数值为 0，则再次调用该指令，直到该参数值为 1，即可获取所有视觉点。
调用该指令后，若视觉系统默认在 10 秒内未返回处理结果，则将返回超时错误状态码。可在 RVS 2.0 工具栏的“机器人通信配置” > “下一步” > “高级设置”下，根据需求更改“获取Vision数据超时时间”。
自定义数据项个数
所有自定义端口数据的列维数之和。例如，“视觉输出”步骤的端口数据由以下数据组成，其中 customData1 和 customData2 为自定义端口，列维数分别为 3 和 2，因此自定义数据项个数为 3+2=5。
端口名称 |
poses |
|||
|---|---|---|---|---|
端口数据 |
[ |
[ |
[ |
[ |
[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] |
|
] |
] |
] |
] |
|
行维数（列表中元素个数） |
2 |
2 |
2 |
2 |
7 |
1 |
3 |
2 |
位姿
单个视觉点的机器人工具位姿。视觉系统会自动将视觉点的物体位姿（即“视觉输出”步骤的 poses 端口数据）转换为对应的机器人工具位姿，转换流程如下：
将物体位姿由四元数形式转换为欧拉角形式。
将物体位姿绕 X 轴旋转 180°，使其 Z 轴朝下。
标签
单个视觉点的标签。
备注
标签必须是一个整数形式的字符串。
若无标签信息，则标签值默认为 0。
自定义数据项
单个视觉点的所有自定义端口的数据，其数量与 自定义数据项个数 相等。自定义数据项按照自定义端口名称的字母顺序（A—Z）排列。
例如，若“视觉输出”步骤各端口的数据如下表所示，则机器人获取的第一个视觉点的 自定义数据项 为 [0, 0, 1] 与 [0, 0]，第二个视觉点的 自定义数据项 为 [1, 0, 0] 与 [1, 1]。
端口名称 |
poses |
labels |
自定义数据项1 |
自定义数据项2 |
|---|---|---|---|---|
端口数据 |
[ |
[ |
[ |
[ |
[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] |
|
] |
] |
] |
] |
|
第一个视觉点 |
[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] |
指令实例
假设工程的“视觉输出”步骤各端口数据如下图所示，以下演示如何通过 101 指令：运行 RVS 2.0 工程 与 110 指令：获取自定义数据 获取自定义端口数据。
机器人向视觉系统发送 101 指令，期望获取所有视觉点（共 2 个）。
101,1,0,0
视觉系统返回运行成功：
101,1102
机器人向视觉系统发送 110 指令，获取第一个视觉点的所有数据。
110,1
视觉系统返回结果，其中自定义数据项为 11 和 21。
110,1100,0,2,1150.1272,-297.2476,-55.0715,-0.1087,-1.6156,-176.1518,1,11,21
机器人再次向视觉系统发送 110 指令，获取第二个视觉点的所有数据。
110,1
视觉系统返回结果，其中 1 表示已获取所有视觉点，自定义数据项为 12 和 22。
110,1100,1,2,592.6891,-256.7424,-56.6007,0.0723,1.1348,-176.355,2,12,22
501 指令：向 RVS 2.0 工程传入物体尺寸
功能介绍
该指令用于向 RVS 2.0 工程传入物体尺寸。传入的物体尺寸即“读取物体尺寸”步骤的 箱子尺寸设置 参数值，如下图所示。
使用该指令时，RVS 2.0 工程中只能包含一个“读取物体尺寸”步骤，否则视觉系统将返回错误。
调用顺序
该指令需在 101 指令：运行 RVS 2.0 工程 之前调用。
发送格式
501,RVS 2.0 工程编号,物体尺寸X,物体尺寸Y,物体尺寸Z
RVS 2.0 工程编号
在工程列表窗口中查看，工程名称前的数字即为编号。
物体尺寸X/Y/Z
物体尺寸的长宽高，单位为毫米（mm）。尺寸值将被“读取物体尺寸”步骤读取，并分别写入 X轴上的长度、Y轴上的长度、Z轴上的长度。
返回格式
501,状态码
状态码
若指令执行正常，则状态码为 1108。若指令执行异常，则状态码为对应的错误码，具体参见 RVS 2.0 错误状态码。
指令实例
机器人向视觉系统发送如下指令，将工程 1 的物体尺寸设置为 X=100 mm、Y=200 mm、Z=300 mm。
501,1,100,200,300
若视觉系统向机器人返回如下结果，则表示指令执行正常。1108 表示已将工程 1 的物体尺寸设置为 X=100 mm、Y=200 mm、Z=300 mm。
501,1108
901 指令：获取系统状态
功能介绍
该指令用于检测 RVS 2.0 工程是否就绪。
发送格式
901
返回格式
901,状态码
状态码
若指令执行正常，则状态码为 1101。若指令执行异常，则状态码为对应的错误码，具体参见 RVS 2.0 错误状态码。
指令实例
机器人向视觉系统发送 901 指令：
901视觉系统返回结果，1101 表示 RVS 2.0 工程已就绪：
901,1101