api接口说明

保持寄存器格式

本文所有关于WORD, DWORD等的数据格式描述, 均按下表所述约定。用户需要自己分辨这种描述和特定PLC厂家的区别并进行相应转换。

数据类型	描述
输入线圈(Input Coils / Discrete Inputs)	只读的 BOOL 型变量 (1-bit)
保持线圈(Holding Coils / Coils of Outputs)	可读可写的 BOOL 型变量(1-bit)
输入寄存器(Input Registers / Input Data)	可读可写的 WORD 型(16-bit)型变量
保持寄存器(Holding Registers / Output Data)	可读可写的 WORD 型(16-bit)型变量

本协议只用到了 保持寄存器，没有用到其他寄存器或线圈。

PLC方需要事先告知/确定其单个保持寄存器(WORD)和双保持寄存器(DWORD)的符号位和字节序，XYZ-Studio-Max需要做相应的配置，否则数据解析会不正确。

单个保持寄存器WORD
符号位	有符号/无符号	这个必须是有符号的WORD 即数据范围支持-32768 ~ 32767，因为涉及传递负数。
字节序	大端/小端/大端交换/小端交换	字节序定义见下文 根据PLC实际情况配置上位机XYZ-Studio-MaX即可

双保持寄存器DWORD
符号位	有符号/无符号	这个必须是有符号的DWORD 即数据范围支持-2,147,483,648 ~ 2,147,483,647，因为涉及传递负数。
字节序	大端/小端/大端交换/小端交换	根据PLC实际情况配置上位机XYZ-Studio-Max即可

字节序的定义如下：

class ByteOrder(Enum):
"""
                          2Bytes(word)    4Bytes(dword/float)     8Bytes(double/4word)
    BIG_ENDIAN              AB                  AB CD                   AB CD EF GH
    LITTLE_ENDIAN           BA                  DC BA                   HG FE DC BA
    BIG_ENDIAN_SWAP         BA                  BA DC                   BA DC FE HG
    LITTLE_ENDIAN_SWAP      AB                  CD AB                   GH EF CD AB
"""
BIG_ENDIAN = 0                # 大端
LITTLE_ENDIAN = 1             # 小端
BIG_ENDIAN_SWAP = 2           # 大端交换
LITTLE_ENDIAN_SWAP = 3        # 小端交换

交互标志位寄存器

数据内容	保持寄存器地址	说明
heart_beat_flag (心跳信号)	0	通讯连接后，Max内部定期循环发送0-1-0-1-…(周期1s)
max_ready_flag (Ready信号)	1	Max端的Ready信号 PLC发送命令前，需要查询此状态： 为1，表示此时Max准备好接收来自plc的命令，plc可以发送命令请求信号 为0，表示此时Max还未准备好接收来自plc的命令，plc不要发送命令请求信号
max_done_flag (Done信号)	2	Max端的命令执行完成信号 PLC发送命令请求信号后，需要查询此状态： 为1，表示此时Max端已经执行完PLC发送的命令 为0，表示此时Max端处于命令执行的busy状态。
plc_request_flag (命令请求信号)	3	PLC端的命令请求信号 设置为1，表示触发命令 PLC需要根据时序要求，在Max命令执行完成后复位为0
预留	4~9	占用，预留

PLC保持寄存器发送区

数据内容		保持寄存器地址	说明
cmd		10	指令码，支持切换工件、获取点位等。 各指令详细信息见下文。
token		11	某些指令需要用到该值
vs_id		12	视觉服务id
tool_id		13	工具id
task_codename		14	任务代号
item_codename		15	工件代号
vision_codename		16	视觉命令代号
系统预留		17~24	请勿占用
usr_cmd_in	str_5	25~29	用户指令(xyzUsrCmd)的5个字符串输入参数 1个保持寄存器代表1个字符串
	int_10	30~39	用户指令(xyzUsrCmd)的10个Int输入参数 1个保持寄存器代表1个int值
	float_10	40~59	用户指令(xyzUsrCmd)的10个Float输入参数 2个保持寄存器代表1个Float值。 即2个保持寄存器是对Float值 * 1000后的取整值。小数点位数可以在Max中配置。
cart_pose	x	60~61	占用2个保持寄存器, 数据解析规则是有符号类型的DWORD 案例:想传递的真实数据是: -123.456, 默认小数点位数为3位 则数据*100后取整为 -123456, 该值的16进制是: FF FE 1D C0 [60] → FF FE [61] → 1D C0 说明： 小数点位数可以在Max中进行配置 [60]和[61]中字节顺序需要变化的，可以在Max中进行配置。如[60] -> FE FF, [61] -> C0 1D
	y	62~63	格式同x 如果姿态是欧拉角形式，则d没有用到，填0即可
	z	64~65
	a	66~67
	b	68~69
	c	70~71
	d	72~73
joints	j1	74~75	格式同cart_pose中的x
	j2	76~77
	j3	78~79
	j4	80~81
	j5	82~83
	j6	84~85
系统预留		86~99	请勿使用
系统预留		100~129	请勿使用

PLC保持寄存器接收区

数据内容		保持寄存器地址	说明
xyz_error	error	130	0：没有错误 1：有错误
	error_code	131~132	具体的错误代码 占用2个保持寄存器, 数据解析规则是有符号类型的DWORD
token		133	会用于某些指令的输入参数
pose_num		134	点位数量
pipeline_num		135	运动流程编号
register_num		136	抓取序号
object_name		137	物体名称
dint_value_6		138~149	某些指令的输出参数，可在Max中自定义其含义 2个寄存器代表1个dint值，合计6个dint输出
系统预留		150~159	请勿使用
cart_pose	x	160~161	同发送区的cart_pose
	y	162~163
	z	164~165
	a	166~167
	b	168~169
	c	170~171
	d	172~173
joints	j1	174~175	同发送区的joints
	j2	176~177
	j3	178~179
	j4	180~181
	j5	182~183
	j6	184~185
trajectory	way_point_num	186	轨迹中的点位数量,一段轨迹最多支持30个点
	系统预留	187~189	请勿使用
	way_point_types	190~219	存放轨迹中的各个点位和点位的类型，具体分类如下： 第一个点 wp1_type: [190] wp1: data1: [220, 221] data2: [222, 223] data3: [224, 225] data4: [226, 227] data5: [228, 229] data6: [230, 231] — 第二个点 wp2_type: [191] wp2: data1: [232, 233] data2: [234, 235] data3: [236, 237] data4: [238, 239] data5: [240, 241] data6: [242, 243] 其他点依次类推 — wp_type取值范围和含义如下： 11：moveJ(joints)，对应点位的6个值是joints。机器人需要用MoveJ方式执行该点位 12：moveL(joints)，对应点位的6个值是joints。机器人需要用MoveL方式执行该点位 21：moveJ(cart_pose)，对应点位的6个值是cart_pose(xyzabc)。机器人需要用MoveJ方式执行该点位 22：moveL(cart_pose)，对应点位的6个值是cart_pose(xyzabc)。机器人需要用MoveL方式执行该点位
	way_points	220~579
系统预留		580~584
usr_cmd_out	str_5	585~589	用户指令(xyzUsrCmd)的5个字符串输出参数 格式参考 发送区的usr_cmd_in
	int_10	590~599	用户指令(xyzUsrCmd)的10个Int输出参数 格式参考 发送区的usr_cmd_in
	float_10	600~619	用户指令(xyzUsrCmd)的10个Float输出参数 格式参考 发送区的usr_cmd_in
系统预留		620~799	请勿占用

支持的指令

每条指令涉及保持寄存器发送区和保持寄存器接收区。下列指令仅列出数据名称，具体寄存器地址请查阅上文地址表。

心跳信号
功能描述	通信连接后，Max定期循环发送1-0-1-…到heart_beat_flag标志位，周期1s

切换任务(xyzSwitchTask)
功能描述	切换Max中的任务流图
相关参数	数据内容	说明
PLC数据发送区	cmd	用户需要填 502
	task_codename	Max中的任务代号，后缀”.t”不用填
PLC数据接收区	xyz_error:error
	xyz_error:error_code

切换工具(xyzSwitchTool)
功能描述
相关参数	数据内容	说明
PLC数据发送区	cmd	用户需要填 503
	tool_id	工具id
PLC数据接收区	xyz_error:error
	xyz_error:error_code

呼叫视觉命令(xyzCallVisionCmd)
功能描述
相关参数	数据内容	说明
PLC数据发送区	cmd	用户需要填 504
	vs_id	视觉服务id
	vision_codename	视觉命令代号
PLC数据接收区	xyz_error:error
	xyz_error:error_code

请求抓取目标点位(xyzReqGraspPose)
功能描述	异步请求 抓取点的位姿
相关参数	数据内容	说明
PLC数据发送区	cmd	用户需要填 507
	vs_id	视觉服务id
PLC数据接收区	xyz_error:error
	xyz_error:error_code
	token	在执行”获取抓取目标点位(xyzGetGraspPose)”时使用到

获取抓取目标点位(xyzGetGraspPose)
功能描述	使用该指令前需先调用“请求抓取目标点位(xyzReqGraspPose)”
相关参数	数据内容	说明
PLC数据发送区	cmd	用户需要填 508
	token	“请求抓取目标点位(xyzReqGraspPose)”中返回的token
PLC数据接收区	xyz_error:error
	xyz_error:error_code
	cart_pose	抓取目标点的位姿数据
	pose_num	当前可供抓取的点位数量
	pipeline_num	运动流程编号
	register_num	抓取序号
	dint_value_6	可在Max中中自定义含义

请求物体位姿(xyzReqObjPose)
功能描述	异步请求 物体位姿
相关参数	数据内容	说明
PLC数据发送区	cmd	用户需要填 509
	vs_id	视觉服务id
PLC数据接收区	xyz_error:error
	xyz_error:error_code
	token	在执行“获取物体位姿(xyzGetObjPose)”时用到

获取物体位姿(xyzGetObjPose)
功能描述	使用该指令前需先调用“请求物体位姿(xyzReqObjPose)”
相关参数	数据内容	说明
PLC数据发送区	cmd	用户需要填 510
	token	“请求物体位姿(xyzReqObjPose)”中返回的token
PLC数据接收区	xyz_error:error
	xyz_error:error_code
	cart_pose	物体的位姿数据
	pose_num	当前物体位姿个数
	object_name	物体名称
	dint_value_6	可在Max中中自定义含义

重置任务(xyzResetTask)
功能描述	下位机在初始化时需要调用该指令
相关参数	数据内容	说明
PLC数据发送区	cmd	用户需要填 511
PLC数据接收区	xyz_error:error
	xyz_error:error_code

发送机器人当前关节坐标(xyzSendCurrentJoints)
功能描述
相关参数	数据内容	说明
PLC数据发送区	cmd	用户需要填 512
	joints	机器人当前的角度信息。 如果机器人轴数小于6轴，则需要对应位置补零
PLC数据接收区	xyz_error:error
	xyz_error:error_code

发送机器人当前笛卡尔坐标(xyzSendCurrentCartPose)
功能描述
相关参数	数据内容	说明
PLC数据发送区	cmd	用户需要填 513
	cart_pose	机器人当前姿态数据 如果机器人是欧拉角形式，则只需给a,b,c赋值，d赋值0即可
PLC数据接收区	xyz_error:error
	xyz_error:error_code

发送机器人当前扩展轴坐标(xyzSendCurrentExtJoints)
功能描述
相关参数	数据内容	说明
PLC数据发送区	cmd	用户需要填 514
	joints	机器人当前扩展轴的角度信息 如果扩展轴数不足6的,需要补零后发送六个数
PLC数据接收区	xyz_error:error
	xyz_error:error_code

请求抓放规划(xyzReqPickPlace)
功能描述
相关参数	数据内容	说明
PLC数据发送区	cmd	用户需要填 517
	vs_id	视觉服务id
PLC数据接收区	xyz_error:error
	xyz_error:error_code

获取取料入框轨迹(xyzGetPickin)
功能描述
相关参数	数据内容	说明
PLC数据发送区	cmd	用户需要填 518
	vs_id	视觉服务id
PLC数据接收区	xyz_error:error
	xyz_error:error_code
	pipeline_num	运动流程编号
	register_num	抓取序号
	Trajectory	轨迹

获取取料出框轨迹(xyzGetPickout)
功能描述
相关参数	数据内容	说明
PLC数据发送区	cmd	用户需要填 519
	vs_id	视觉服务id
PLC数据接收区	xyz_error:error
	xyz_error:error_code
	pipeline_num	运动流程编号
	register_num	抓取序号
	Trajectory	轨迹

获取放料入框轨迹(xyzGetPlacein)
功能描述
相关参数	数据内容	说明
PLC数据发送区	cmd	用户需要填 520
	vs_id	视觉服务id
PLC数据接收区	xyz_error:error
	xyz_error:error_code
	pipeline_num	运动流程编号
	register_num	抓取序号
	Trajectory	轨迹

获取放料出框轨迹(xyzGetPlaceout)
功能描述
相关参数	数据内容	说明
PLC数据发送区	cmd	用户需要填 521
	vs_id	视觉服务id
PLC数据接收区	xyz_error:error
	xyz_error:error_code
	pipeline_num	运动流程编号
	register_num	抓取序号
	Trajectory	轨迹

料箱重定位(xyzUpdateTotePose)
功能描述
相关参数	数据内容	说明
PLC数据发送区	cmd	用户需要填 523
	vs_id	视觉服务id
PLC数据接收区	xyz_error:error
	xyz_error:error_code

工件在手上的二次定位(xyzUpdateObjPoseInHand)
功能描述
相关参数	数据内容	说明
PLC数据发送区	cmd	用户需要填 524
PLC数据接收区	xyz_error:error
	xyz_error:error_code
	cart_pose	放置位姿数据

切换工件(xyzSwitchItem)
功能描述
相关参数	数据内容	说明
PLC数据发送区	cmd	用户需要填 528
	vs_id	视觉服务id
	item_codename	工件代号
PLC数据接收区	xyz_error:error
	xyz_error:error_code

计算抓取目标点位(xyzCalculateGraspPose)
功能描述	该指令等价于xyzReqGraspPose + xyzGetGraspPose
相关参数	数据内容	说明
PLC数据发送区	cmd	用户需要填 529
	vs_id	视觉服务id
PLC数据接收区	xyz_error:error
	xyz_error:error_code
	cart_pose	抓取目标点的位姿数据
	pose_num	当前可供抓取的点位数量
	pipeline_num	运动流程编号
	register_num	抓取序号
	dint_value_6	可在Max中中自定义含义

计算物体位姿(xyzCalculateObjectPose)
功能描述	该指令等价于xyzReqObjPose+xyzGetObjPose
相关参数	数据内容	说明
PLC数据发送区	cmd	用户需要填 530
	vs_id	视觉服务id
PLC数据接收区	xyz_error:error
	xyz_error:error_code
	cart_pose	物体的位姿数据
	pose_num	当前物体位姿个数
	object_name	物体名称
	dint_value_6	可在Max中中自定义含义

用户指令(xyzUsrCmd)
功能描述	用于基础指令不支持的情况下，配合任务流图完成用户特定功能。 各个参数的含义取决于任务流图中设定的输入输出
相关参数	数据内容	说明
PLC数据发送区	cmd	用户需要填 600
	usr_cmd_in	自定义输入参数
PLC数据接收区	xyz_error:error
	xyz_error:error_code
	usr_cmd_out	自定义输出参数