TCP客户端通信配置

约 5067 字大约 17 分钟

2026-01-26

TCP客户端是 PickWiz 作为客户端、机器人作为服务端的通信方式，PickWiz 与机器人进行通信时主动控制机器人，向机器人发送指令，机器人接收到指令后执行指令并返回数据。

在配置机器人通信之前，请先参照项目操作指南新建项目，然后在主界面点击 机器人配置面板 进入 新增机器人 界面。

1. 新增机器人

（1）进入 新增机器人 界面，点击 +新增机器人

（2）通信方式选择TCP客户端，点击下一步，进入 机器人配置 界面

2. 配置机器人

在机器人配置界面，可进行机器人信息配置、通信基础配置、自定义通信报文配置。

2.1 机器人信息

配置项	说明
通信方式	PickWiz 与机器人之间建立通信的通信协议，不可修改
配置名称	机器人配置的名称，支持中英文、数字、字符
配置ID	机器人配置的唯一标识ID，可修改，只支持数字
品牌	机器人的品牌，若机器人端连接的是PLC，品牌选择其他设备
型号	机器人的型号，若机器人端连接的是PLC，型号选择其他设备
模型	品牌和型号选择其他设备时，需上传该设备的模型，模型文件的格式为urdf
轴数	机器人拥有的机械臂轴数，可选三轴、四轴、六轴
旋转表达式	描述机器人在三维空间中的姿态，目前有欧拉角和旋转矢量两种方法，欧拉角的顺序可修改。

2.2 通信基础配置

配置项		说明
通信地址	主机ip	主机ip地址，TCP 通信方式下默认为0.0.0.0
通信地址	端口号	机器人连接主机的指定端口，默认端口号8887，一般无需修改
读写格式	欧拉角单位	欧拉角的单位，可选角度、弧度，默认角度。
	长度单位	机器人使用的长度单位，包括机器人位姿，工件尺寸等等，默认mm
	位姿类型	机器人位姿的表示方式，默认工具位姿。工具位姿是指机器人末端工具的位姿；关节角是指机器人各个关节的位姿，各个关节的位姿组合可以确定机械臂或末端工具的位姿。机器人品牌和型号选择其他设备时，位姿类型默认只能选择工具位姿
	分隔符	分隔符用于分隔数据，例如pose有6位数据，即xyzabc，分隔符用于区分开这6位数据，例如x,y,z,a,b,c（数据末尾不加）。分隔符可填除了\n、\r、\t这些转义字符外的任意字符。
	末尾特殊字符	有些机械臂可能接收或发出的一条消息末尾都要求一些特殊字符，例如\n\r，可以在这里填写这些特殊字符，软件在发送每条消息时会在末尾附加这些特殊字符，在接收来自机械臂的每条消息时，会尝试去除末尾的特殊字符（如果有）。
	指令长度限制	有些机械臂一条消息只能接收或发送指定字节数量的数据，因此可在这里设置一条消息的字节数量
	保留小数位数	机器人指令中的浮点数据保留几位小数，只支持数字，默认为1

2.3 自定义通信报文

通用指令规则

发送给机械臂的一条消息的编码格式为：utf-8；
指令代表软件和机械臂之间的通信协议，不同的操作需要定义好各自的指令；一条指令由指令符和自定义字符构成；
指令符以shell变量的形式提供：$ {指令符}；指令符用于标识这是一个占位，发送消息时一个指令符会被替换成具体的数据，如指令符${p}，会被替换成：0,0,0,0,0,0 （中间的分隔符可以自定义）；
自定义字符可以是任意字符（\n,\r,\t这些转义字符除外），也可以在一条指令中的任意位置出现；
指令可以不需要指令符，都是自定义字符，也可以只有单个指令符，但是必须保证每种操作的指令存在区分度（即通信协议应是唯一的），否则软件和机械臂都无法定位收到一条消息后应该做什么功能。
软件如何定位一条消息代表的含义：当接收到一条消息时，软件会将所有用户配置的指令中的指令符替换，使整条指令变成一个正则表达式，而后将这条消息和所有通过指令得到的正则表达式进行匹配，当匹配成功，就意味着知道了这条消息代表了什么操作，如果全部匹配失败，说明要么指令填写有问题，要么机械臂发送的数据不对。

3. TCP指令说明

3.1 标定通信报文

PickWiz 向机器人发送请求：getRobotPose，获取机器人的坐标
机器人向 PickWiz 返回机器人坐标

p：机器人末端工具的位姿信息

$(p)：输出机器人末端工具的位姿信息，6位数据

示例1

PickWiz 向机器人发送请求getRobotPose，机器人向 PickWiz 返回机器人坐标p,${p}。

示例2

PickWiz 向机器人发送请求(getRobotPose)，机器人向 PickWiz 返回机器人坐标p,$

示例3

PickWiz 向机器人发送请求getRobotPose，机器人向 PickWiz 返回机器人坐标p,${p}\n，\n是自定义字符。

当机器人向 PickWiz 返回机器人坐标中不包含自定义字符时，软件无法匹配该指令；当机器人向 PickWiz 返回机器人坐标中包含自定义字符时，软件才能匹配该指令；

3.2 视觉计算通信报文

（1）机器人发送至 PickWiz 指令

占位符

占位符是指在编程中使用的符号或标记，实际通信过程中占位符会被具体内容替换。

占位符	说明
p	机器人工具位姿，6位数据在`位姿类型`为工具位姿时，机器人向PickWiz 返回当前机器人末端工具的位姿
j	机器人参考关节姿态，6位数据在`位姿类型`为关节角时，机器人需要发送`参考关节姿态`，用于计算距离该参考关节姿态最近的抓取点关节姿态
ps	工件尺寸来料是多种尺寸的工件，机器人需根据不同的尺寸自动调整抓取策略不同场景下，机器人侧传入的工件尺寸位数与位数对应的工件信息不同。圆面场景传入位数为1位，代表半径；圆柱场景传入位数为2位，代表半径\高度；纸箱场景传入位数为3位，代表长\宽\高；四边形场景为2位，代表宽\长。
p_tol	工件尺寸容差来料是多种尺寸的工件，机器人需根据不同的尺寸自动调整抓取策略不同场景下，机器人侧传入的工件尺寸容差的位数与位数对应的工件信息不同。圆面场景传入位数为1位，代表半径的容差；圆柱场景传入位数为2位，代表半径\高度的容差；四边形场景为2位，代表宽\长的容差。
pid	工件ID，用于机器人自动切换抓取的工件
wid	作业ID，用于机器人自动切换作业
calib_id	标定ID，用于机器人自动切换手眼标定配置文件
ee_id	末端工具ID，用于机器人执行任务时自动切换末端工具
roi_id	ROI的ID，用于机器人自动切换ROI
vp_id	视觉参数ID，用于机器人自动切换视觉参数
so_id	场景物体ID，用于机器人自动切换场景物体
co	视觉计算规则 0：重新拍照取图和视觉计算； 1：使用上一次的图像数据进行计算； 2：仅拍照取图 3：进行“随机姿态自动采样”的拍照 4：视觉漂移实时校正 5：使用历史数据进行视觉计算 6：工控机关机

发送指令信息（机器人向PickWiz发送指令）

配置机器人向 PickWiz 发送指令的内容

d：指令标识符

$(p)：机器人末端工具的位姿信息，6位数据

$(wid)：作业ID，1位，用于机器人切换作业

示例1

发送指令信息设置为d,${ps}，机器人向PickWiz只发送位姿信息，触发流程

示例2

发送指令信息设置为d,${ps}，麻袋单拆场景下，机器人向PickWiz发送工件尺寸，会报错并提示仅适用于纸箱、圆、圆柱、四边形；纸箱单拆场景下，机器人向PickWiz发送纸箱的长宽高，触发检测流程

示例3

发送指令信息设置为d,${p},${wid}，机器人向PickWiz发送位姿信息和作业ID，自动切换作业1、2、4、5的检测流程

清除缓存

清除缓存：拍一抓多的情况下，清除当前剩余实例缓存，将在下一次触发检测流程时重新拍照

抓取逻辑：

拍一抓一：表示视觉拍照一次，计算一次，计算后将结果发送给机器人，丢弃多余的结果，机器人执行相关的抓取动作，然后重复；
拍一抓多：表示视觉拍照一次，计算一次，将计算后将结果发送给机器人，将多余的视觉结果保存，机器人执行相关的抓取动作，下一次机器人发送拍照计算指令时，先查看保存的视觉结果是否满足要求，若是则不执行拍照 + 计算的逻辑，直接返回结果给机器人，然后重复；

示例

不勾选拍一抓多时，机器人每一次触发检测流程，PickWiz都要进行拍照计算

在视觉计算配置勾选拍一抓多，PickWiz可以实现拍照计算一次抓取多次，如下图所示，识别出5个实例，第一次抓取由PickWiz触发，后4次抓取由机器人触发，后4次抓取时机器人向 PickWiz 发送位姿信息触发检测流程，PickWiz 不进行拍照计算，而是直接返回抓取位姿。

第1次抓取由客户端触发，第2、3次抓取由机器人触发，机器人向 PickWiz 发送位姿信息触发检测流程，PickWiz 不进行拍照计算，而是直接返回抓取位姿。然后输入co指令清除缓存，第4次抓取PickWiz又开始进行拍照计算

（2）PickWiz 发送至机器人指令

占位符

占位符是指在编程中使用的符号或标记，实际通信过程中占位符会被具体内容替换。

占位符	含义
s	检测结果信号，视觉检测信号，1位，默认值成功为`100`，其他异常为`0`，可自定义配置
entity	返回实例类型，1位，`1`为托盘，`0`为工件
ln	剩余实例数量，1位，在`拍一抓多`的抓取逻辑下，返回当前剩余的缓存实例数量
rn	返回实例数量，1位，返回实例分割2D识别出的实例数量，该值小于等于`发送实例个数`，如有多个实例，`抓取相关信息长度`会随着返回实例数量增加
tn	实例检测总量，1位，未被实例过滤的检测实例数量
vn	有效实例数量，1位，实例过滤后的检测实例数量
info	抓取相关信息
cid	工件类型
sr	标定采样结果，是自动采样标定指令，不同标定采样结果对应不同信号值。 0：样本达到最小数量 1：新增样本成功 11：新增样本失败 12：自动采样结束，样本列表执行完毕 13：生成采样姿态失败 14：未进入标定采样页面 15：系统错误
cp	下次采样位姿，是自动采样标定指令，下一次机器人采集标定样本的移动位置
<SPLIT>	特殊分隔符，使用时无需加上${}，直接在指令中加上这个标识，在该位置处，数据将被强制拆分。该功能和按字符数切分数据的功能互斥，并且这个功能优先级更高。

视觉检测发送指令（PickWiz 向机器人发送指令）

配置 PickWiz 向机器人发送指令的内容

自动标定采样发送指令

手眼标定方式是“随机姿态自动采样”时，需要设置该指令，否则机器人无法与PickWiz通信

抓取相关信息

以下表达的抓取相关信息长度位数为单抓取点的长度位数，如果是多抓取点，长度为位数x抓取点数

全场景通用信息

字段	说明
抓取工件ID	1位；表示当前工件序号
抓取点位姿	6位；表示抓取点的位姿数据
抓取点索引	1位；表示当前抓取点序号
额外信息	1位；表示当前工件的自定义额外信息
前进点	仅适用于位姿类型为关节角的情况，长度为1+路径点个数；格式为(路径点数,预抓点到抓取点的关节路径点姿态)
后撤点	仅适用于位姿类型为关节角的情况，长度为1+路径点个数；格式为(路径点数,抓取点到后撤抓取点的关节路径点姿态)

视觉状态码

视觉状态码用于故障排查，建议的状态码如下表

需在视觉检测发送指令中配置 ¥{s}
若未自定义配置视觉状态码，默认值为成功返回100，其他异常均返回0

错误内容	默认值	相关节点
成功	100
检测到底板	301	前景处理(Foreground Builder)
未检测到料框	4000	料框检测(Container Builder)
未检测到实例	5000	实例分割(Instance Builder)
未检测到姿态	6000	姿态估计(Pose Builder)
未检测到抓取点	7000	抓取点生成(Grasp Builder)
未检测到路径	8000	机器人运动轨迹生成器(Trajectory Builder)
未检测到实例尺寸	9000	工件尺寸生成器(Size Builder)
空ROI	1101	无效点过滤器(ValidPoints Criteria)
没有有效实例	12000	实例过滤(Instance Criteria)
没有有效工件姿态	13000	姿态过滤(Pose Criteria)
没有有效抓取点	14000	抓取点过滤(Grasp Criteria)
全部检测结果碰撞不可抓	15000	碰撞检测过滤(Collision Criteria)
没有尺寸有效的实例	17000	工件尺寸过滤(Size Criteria)
异常	20000	通用异常错误，请查看日志确认
显存不足	20001	通用异常错误，请查看日志确认
无效输入（请检查算法参数）	20002	通用异常错误，请查看日志确认
满检	20003	点云处理算子相关(full_detect_judgment)
异物检测异常	20004	实例过滤算子相关(foreign_matter_judgement)