CGXi标准接口指令
本文介绍CGXi机器人与梅卡曼德视觉系统之间进行TCP协议通信的标准接口指令。其中，机器人（客户端）发送指令给梅卡曼德视觉系统（服务端），梅卡曼德视觉系统将处理后的数据返回给机器人。
在开始前，请注意以下事项：
-
CGXi机器人指令调用说明：
-
本文介绍的每个指令都将是以单个脚本文件（.crscript）的形式集成到机器人程序中。
-
对于指令的输入参数（input），用户无需重复定义变量，只需在脚本里给对应变量赋值即可。
-
对于指令的输出参数（output），用户需要在调用指令时指定相应的接收变量，以便能在机器人程序里使用。
-
-
指令的数据单位：
-
关节角的单位是度（°）。
-
机器人法兰位姿或机器人工具位姿由位置和姿态组成，位置（XYZ坐标值）单位为毫米（mm）；姿态使用欧拉角表示，单位为度（°）。
-
-
视觉点或路径点：
-
视觉点：Mech-Vision识别的目标物体，一个视觉点包括物体位姿、标签、物体尺寸、自定义数据等信息。
-
路径点：机器人沿着规划路径需逐一到达的点位，一个路径点包括机器人位姿、标签、移动类型等信息。路径点可分为以下两种类型：
-
视觉移动路径点：“视觉移动”步骤对应的路径点。
-
非视觉移动路径点：除“视觉移动”步骤外，其他移动类步骤对应的路径点。
-
-
运行Mech-Vision工程
功能介绍
该指令用于触发Mech-Vision工程运行。在Mech-Vision工程运行期间，视觉系统会执行相机拍照，并对图像数据进行一系列的视觉算法处理，最终得到一系列视觉点或路径点。
|
调用顺序
-
工程中的步骤参数需要在运行Mech-Vision工程之前被设置，因此切换Mech-Vision参数配方指令或向Mech-Vision工程传入物体尺寸指令需先于运行Mech-Vision工程指令被调用。
-
只有运行Mech-Vision工程后，视觉系统才得到视觉点或路径点，因此运行Mech-Vision工程指令需先于获取视觉结果指令、获取Mech-Vision规划路径指令或获取Mech-Vision自定义数据指令被调用。
指令格式
mm_start_vis(_proj_no,_pos_num_need,_sendpos_type,_init_jps,_socket_id)输入参数
_proj_no
该参数表示Mech-Vision工程编号。Mech-Vision工程编号可在Mech-Vision工程列表窗口中查看，工程名称前的数字表示工程编号。
_pos_num_need
该参数表示期望从Mech-Vision工程获取的视觉点或路径点数量。取值为0或大于0的整数，具体说明如下。
| 若Mech-Vision工程中存在“路径规划”步骤，该参数表示预期路径点数量，否则表示预期视觉点数量。 |
-
0：从Mech-Vision工程获取所有视觉点或路径点。
-
大于0的整数：从Mech-Vision工程获取指定数量的视觉点或路径点。
-
如果Mech-Vision工程输出的视觉点或路径点总数小于指定的参数值，则获取输出的所有视觉点或路径点。
-
如果Mech-Vision工程输出的视觉点或路径点总数大于或等于指定的参数值，则获取指定数量的视觉点或路径点。
-
|
_sendpos_type
该参数指定真实机器人的位姿将以何种形式传入Mech-Vision工程。取值为0、1、2或3，具体说明如下表。
| _sendpos_type | 说明 | 适用场景 |
|---|---|---|
0 |
该指令无需向Mech-Vision工程传入机器人位姿。 |
相机的安装方式为Eye To Hand。若Mech-Vision工程中使用“路径规划”步骤，则路径规划的起始点为路径规划工具中设置的Home点。 |
1 |
该指令需要将机器人的关节角和法兰位姿传入Mech-Vision工程。 |
相机的安装方式为Eye In Hand。除桁架机器人外，大多数机器人适用该设定。 |
2 |
该指令需要将机器人的当前法兰位姿传入Mech-Vision工程。 |
相机的安装方式为Eye In Hand，机器人无关节角数据，仅有法兰位姿数据（如桁架机器人）。 |
3 |
该指令需要将用户自定义的关节角传入Mech-Vision工程。 |
相机的安装方式为Eye To Hand，并且Mech-Vision工程中存在“路径规划”步骤，且需要从机器人端设置“路径规划”步骤的起始点。 |
_init_jps
该参数表示用户自定义的关节角数据。
-
若_sendpos_type参数值为3，此关节角数据将发送给Mech-Vision工程的“路径规划”步骤作为第一个路径点进行规划。
-
若_sendpos_type参数值为3以外的其他参数值，此处的关节角数据无实际用处，但必须设定该关节角数据。
_socket_id
机器人端socket识别号；默认为8，取值范围为2~23。
获取视觉结果
功能介绍
该指令用于获取Mech-Vision输出的视觉结果（一系列视觉点）。视觉点的物体位姿（即“输出”步骤的poses端口数据）将会由视觉系统自动转换为对应机器人的工具位姿，具体转换流程如下。
-
将物体位姿由四元数形式转换为欧拉角形式。
-
将物体位姿绕X轴旋转180°，使其Z轴朝下。
调用顺序
该指令需在运行Mech-Vision工程指令之后被调用。在使用该指令后，用户需调用转存视觉结果或规划路径（位姿为工具位姿）指令才可访问位姿数据。
指令格式
mm_get_vis_data(_proj_no,_socket_id)输入参数
_proj_no
该参数表示Mech-Vision工程编号。Mech-Vision工程编号可在Mech-Vision工程列表窗口中查看，工程名称前的数字表示工程编号。
_socket_id
机器人端socket识别号；默认为8，取值范围为2~23。
输出参数
g_mm_status
该参数用于保存该指令执行的状态码。若指令执行正常，则状态码为1100。 若指令执行异常，则状态码为对应的错误码，具体可参考《标准接口状态码及错误排查》。
_pos_num
该参数用于保存Mech-Vision返回的视觉点数量。
|
调用该指令后，视觉系统默认在10秒内未返回处理结果，则将返回超时错误状态码。在Mech-Vision工具栏的 下，可根据需求更改此默认超时时间。 
|
切换Mech-Vision参数配方
调用顺序
该指令需在运行Mech-Vision工程指令之前被调用。
指令格式
mm_set_model(_proj_no,_model_id,_socket_id)输入参数
_proj_no
该参数表示Mech-Vision工程编号。Mech-Vision工程编号可在Mech-Vision工程列表窗口中查看，工程名称前的数字表示工程编号。
_model_id
该参数表示Mech-Vision工程中参数配方的编号。如何查看参数配方的编号，可参考《查看参数配方的编号》。
_socket_id
机器人端socket识别号；默认为8，取值范围为2~23。
获取Mech-Vision规划路径
功能介绍
该指令用于获取Mech-Vision规划的路径（一系列路径点）。此处的路径由“路径规划工具”（从下图的打开编辑器进入）规划。“路径规划”步骤相关的内容，可参考《路径规划》。
| Mech-Vision“输出”步骤的端口类型参数需要设置为“预定义（机器人路径）”。 |
调用顺序
该指令需在运行Mech-Vision工程指令之后被调用。在使用该指令后，用户需调用转存视觉结果或规划路径（位姿为工具位姿）指令或转存规划路径（位姿为关节角）指令才可访问位姿数据。
指令格式
mm_get_vis_path(_proj_no,_pos_type,_socket_id)输入参数
_proj_no
该参数表示Mech-Vision工程编号。Mech-Vision工程编号可在Mech-Vision工程列表窗口中查看，工程名称前的数字表示工程编号。
_pos_type
该参数用于指定获取路径点的位姿形式。取值为1或2。
-
1：关节角。在使用该指令后，用户需调用转存规划路径（位姿为关节角）指令才可访问关节角数据。
-
2：工具位姿。在使用该指令后，用户需调用转存视觉结果或规划路径（位姿为工具位姿）指令才可访问工具位姿数据。
_socket_id
机器人端socket识别号；默认为8，取值范围为2~23。
输出参数
g_mm_status
该参数用于保存该指令执行的状态码。若指令执行正常，则状态码为1103。 若指令执行异常，则状态码为对应的错误码，具体可参考《标准接口状态码及错误排查》。
_pos_num
该参数用于保存视觉系统返回的路径点数量。视觉系统默认单次发送路径点的最大数量为20，因此该参数默认最大值为20。 在Mech-Vision工具栏的下，可根据需求更改默认最大数量，但最大数量的上限为30。
| 在调用获取Mech-Vision规划路径指令前，请务必将运行Mech-Vision工程指令的_pos_num_need设置为0，以减少调用获取Mech-Vision规划路径指令的次数。若运行Mech-Vision工程指令的_pos_num_need设置为1，则每次调用获取Mech-Vision规划路径指令只会获取一个路径点，只有多次调用才能获取全部路径点。 |
_vispos_idx
该参数表示路径规划工具中“视觉移动”步骤对应的路径点（视觉移动路径点）在路径中的位置编号。如果路径中无视觉移动路径点，则该参数值为0。
例如，如果规划路径由以下路径点组成：“定点移动_1”，“定点移动_2”，“视觉移动”，“定点移动_3”，则视觉移动路径点的位置编号为3。
示例
--input
mm_proj_no=2
mm_pos_type=2
--output
mm_status=0
mm_pos_num=0
mm_vispos_idx=0
......
mm_status,mm_pos_num,mm_vispos_idx=mm_get_vis_path(mm_proj_no,mm_pos_type,mm_socket_id)上述示例表示，获取Mech-Vision工程2返回的规划路径，路径点的位姿形式为工具位姿，路径点的数量将保存至mm_pos_num，视觉移动路径点在路径中的位置编号将保存至mm_vispos_idx，指令执行的状态码将保存至mm_status。
获取Mech-Vision自定义数据
功能介绍
该指令用于从Mech-Vision“输出”步骤获取自定义端口的数据。该指令调用一次便可将“输出”步骤的所有端口数据存放到机器人内存中。
自定义端口的设置可从“输出”步骤参数的打开编辑器处进入，其中自定义通信键名就是自定义端口名称，例如下图中customeData1和customeData2端口就是自定义端口。
|
调用顺序
该指令需在运行Mech-Vision工程指令之后被调用。在使用该指令后，用户需调用转存Mech-Vision自定义数据指令才可访问自定义数据。
指令格式
mm_get_dy_data(_proj_no,_socket_id)输入参数
_proj_no
该参数表示Mech-Vision工程编号。Mech-Vision工程编号可在Mech-Vision工程列表窗口中查看，工程名称前的数字表示工程编号。
_socket_id
机器人端socket识别号；默认为8，取值范围为2~23。
输出参数
g_mm_status
该参数用于保存该指令执行的状态码。若指令执行正常，则状态码为1100。 若指令执行异常，则状态码为对应的错误码，具体可参考《标准接口状态码及错误排查》。
_pos_num
该参数用于保存Mech-Vision返回的视觉点数量。
转存Mech-Vision自定义数据
调用顺序
该指令需在获取Mech-Vision自定义数据指令之后被调用。
向Mech-Vision工程传入物体尺寸
调用顺序
该指令需在运行Mech-Vision工程指令之前被调用。
运行Mech-Viz工程
功能介绍
该指令用于触发Mech-Viz工程运行。Mech-Viz是基于Mech-Vision输出的视觉结果规划机器人的移动路径。
| 在Mech-Viz工程资源面板中，右键单击工程名称，勾选设为自动加载。 |
调用顺序
工程中的步骤参数需要在触发Mech-Viz工程运行之前被设置，因此读取Mech-Viz步骤参数值指令或设置Mech-Viz步骤参数值指令需先于运行Mech-Viz工程指令被调用。
指令格式
mm_start_viz(_sendpos_type,_init_jps,_socket_id)输入参数
_sendpos_type
该参数指定真实机器人的位姿将以何种形式传入Mech-Viz工程，取值为0、1或2，具体说明如下表。
| 机器人位姿类型 | 说明 | 适用场景 |
|---|---|---|
0 |
该指令无需向Mech-Viz工程传入机器人位姿，Mech-Viz工程中仿真机器人将从初始位姿JPs=[0,0,0,0,0,0]开始移动到第一个路径点。 |
相机的安装方式为Eye To Hand。 |
1 |
该指令需要将机器人的当前关节角和法兰位姿传入Mech-Viz工程，Mech-Viz工程中仿真机器人将从传入的关节角开始移动到第一个路径点。 |
相机的安装方式为Eye In Hand，推荐使用该设定。 |
2 |
该指令需要将机器人的一个示教点（非当前关节角，而是自定义关节角）传入Mech-Viz工程，用于在机器人处于拍照区域外时，提前触发Mech-Viz工程规划下一轮路径（如下图），Mech-Viz工程中仿真机器人将从传入的示教点开始运动到第一个路径点。 |
相机的安装方式为Eye To Hand，推荐使用该设定。 |
相机的安装方式为Eye To Hand，为何机器人位姿类型推荐使用2？
在下图中，机器人正在放置区进行作业。
若在此种场景中，将_sendpos_type设置为1，表示将机器人当前位姿发送给Mech-Viz，真实机器人可能在移动至其他位置后才移动至第一个路径点。仿真机器人将直接从当前位置移动至Mech-Viz工程中的第一个路径点，在这段移动过程中可能会检测到碰撞而发出警告。
若在此种场景中，将_sendpos_type设置为2，表示将机器人端设置的示教拍照点发送给Mech-Viz，这样真实机器人在放置区即可提前触发Mech-Viz规划下一轮路径，从而缩短节拍。
以上就是Eye To Hand模式下，机器人位姿类型推荐使用2的原因。
_init_jps
该参数表示用户自定义的关节角数据。
-
若_sendpos_type参数值为2，此处的关节角数据将发送给Mech-Viz工程作为第一个路径点进行规划。
-
若_sendpos_type参数值为2以外的其他参数值，此处的关节角数据无实际用处，但必须设定该关节角数据。
_socket_id
机器人端socket识别号；默认为8，取值范围为2~23。
停止Mech-Viz工程
调用顺序
该指令需在运行Mech-Viz工程指令之后被调用。
设置Mech-Viz消息分支出口
调用顺序
该指令需在运行Mech-Viz工程指令之后被调用。
设置Mech-Viz当前索引
调用顺序
通常在索引类步骤前存在一个“消息分支”步骤，机器人端首先调用运行Mech-Viz工程指令，然后调用设置Mech-Viz当前索引指令，最后调用设置Mech-Viz消息分支出口指令。如此，Mech-Viz将有充足时间设置当前索引值。
获取Mech-Viz规划路径
功能介绍
该指令用于获取Mech-Viz工程规划的移动路径（一系列路径点）。
|
路径点：机器人沿着规划路径需逐一到达的点位，一个路径点包括机器人位姿、标签、移动类型等信息。路径点可分为以下两种类型：
|
调用顺序
该指令需在运行Mech-Viz工程之后被调用。在使用该指令后，用户需调用转存视觉结果或规划路径（位姿为工具位姿）指令或转存规划路径（位姿为关节角）指令才可访问位姿数据。
指令格式
mm_get_viz_data(_pos_type,_socket_id)输入参数
_pos_type
该参数用于指定获取路径点的位姿形式。取值为1或2。
-
1：关节角。在使用该指令后，用户需调用转存规划路径（位姿为关节角）指令才可访问关节角数据。
-
2：工具位姿。在使用该指令后，用户需调用转存视觉结果或规划路径（位姿为工具位姿）指令才可访问工具位姿数据。
_socket_id
机器人端socket识别号；默认为8，取值范围为2~23。
输出参数
g_mm_status
该参数用于保存该指令执行的状态码。若指令执行正常，则状态码为2100。 若指令执行异常，则状态码为对应的错误码，具体可参考《标准接口状态码及错误排查》。
|
调用该指令后，视觉系统默认在10秒内未返回处理结果，则将返回超时错误状态码。在Mech-Vision工具栏的 下，可根据需求更改此默认超时时间。 
|
_pos_num
该参数用于保存视觉系统返回的路径点数量。视觉系统默认单次发送路径点的最大数量为20，因此该参数默认最大值为20。 在Mech-Vision工具栏的下，可根据需求更改默认最大数量，但最大数量的上限为30。
_vispos_idx
该参数表示Mech-Viz工程中“视觉移动”步骤对应的路径点（视觉移动路径点）在路径中的位置编号。如果路径中无视觉移动路径点，则该参数值为0。
例如，如果规划路径由以下路径点组成：“定点移动_1”，“定点移动_2”，“视觉移动”，“定点移动_3”，则视觉移动路径点的位置编号为3。
读取Mech-Viz步骤参数值
调用顺序
该指令需在运行Mech-Viz工程指令之前被调用。
指令格式
mm_get_property(_config_id,_socket_id)输入参数
_config_id
该参数为property_config文件中指定的配置编号字段。
|
在Mech-Vision工具栏的 下，单击 属性配置，即可打开property_config文件。 
|
在使用该指令前，用户需提前在property_config文件中指定步骤编号和参数名称对应的key名称，具体格式如下所示。
read, 配置编号, 步骤编号, key名称
read |
指定该行用于读取步骤参数值。 |
配置编号 |
指定一个唯一的编号，为正整数。一个配置编号只能用于读取一个步骤参数值。如果读取多个步骤参数值，请使用不同的配置编号。 |
步骤编号 |
指定将要读取的参数所属步骤的编号。 |
key名称 |
指定将要读取的参数名称对应的key名称。 |
|
|
property_config文件中可以设置多条read指令，但每条read指令的配置编号必须唯一。 |
_socket_id
机器人端socket识别号；默认为8，取值范围为2~23。
输出参数
g_mm_status
该参数用于保存该指令执行的状态码。若指令执行正常，则状态码为2109。 若指令执行异常，则状态码为对应的错误码，具体可参考《标准接口状态码及错误排查》。
viz_prop_val
该参数用于保存返回的指定步骤的参数值。
示例
例如，在property_config文件中添加如下内容，5表示配置编号，3表示步骤编号，xCount表示key名称。
read,5,3,xCount机器人发送如下指令后，将会获取到xCount对应的参数值。
--input
mm_config_id=5
--output
mm_status=0
mm_viz_prop_val=0
......
mm_status,mm_viz_prop_val=mm_get_property(mm_config_id,mm_socket_id)上述示例表示，指令执行的状态码将保存至mm_status，Mech-Viz工程中步骤编号3的xCount对应参数值将保存至mm_viz_prop_val。
设置Mech-Viz步骤参数值
调用顺序
该指令需在运行Mech-Viz工程指令之前被调用。
指令格式
mm_set_property(_config_id,_socket_id)输入参数
_config_id
该参数为property_config文件中指定的配置编号字段。
|
在Mech-Vision工具栏的 下，单击 属性配置，即可打开property_config文件。
|
在使用该指令前，用户需提前在property_config文件中指定步骤编号、参数名称对应的key名称和参数值，具体格式如下所示。
write, 配置编号, 步骤编号, key名称, 参数值
write |
指定该行用于设置步骤参数值。 |
配置编号 |
指定一个编号（非唯一），为正整数。 |
步骤编号 |
指定将要设置的参数所属步骤的编号。 |
key名称 |
指定将要设置的参数名称对应的key名称。 |
参数值 |
指定将要设置的参数值。 |
|
_socket_id
机器人端socket识别号；默认为8，取值范围为2~23。
示例
例如，property_config文件内容如下，1表示配置编号，3表示步骤编号，xOffset、yOffset和zOffset表示key名称，10表示xOffset对应的参数值，20表示yOffset对应的参数值，30表示zOffset对应的参数值。
write,1,3,xOffset,10
write,1,3,yOffset,20
write,1,3,zOffset,30机器人发送如下指令后，Mech-Viz会将xOffset、yOffset和zOffset对应的参数值分别设置为10、20和30。
--input
mm_config_id=1
--output
mm_status=0
......
mm_status=mm_set_property(mm_config_id,mm_socket_id)上述示例表示，xOffset、yOffset和zOffset对应的参数值将分别设置为10、20和30，指令执行的状态码将保存至mm_status。
获取吸盘DO信号
功能介绍
该指令用于获取Mech-Vision或Mech-Viz工程规划的多分区吸盘的控制信号。该指令返回64个DO信号，其中有效的DO信号为非负整数，范围为0~999；无效的DO信号为-1（作为占位值）。机器人通过设置吸盘DO信号指令将获取到的DO信号列表作用于末端工具。
例如，在下表中，返回的有效DO信号为1、3、5、6，即表示将上述DO信号对应的值设为ON。
第1个 |
第2个 |
第3个 |
第4个 |
第5个 |
第6个 |
第7个 |
第8个 |
… |
第63个 |
第64个 |
1 |
3 |
5 |
6 |
-1 |
-1 |
-1 |
-1 |
… |
-1 |
-1 |
使用该指令前，用户需提前配置DO信号。
-
配置Mech-Vision工程中的DO信号
在“路径规划”步骤参数中，单击打开编辑器，双击末端工具名称，工具类型选择拆垛吸盘，单击拆垛吸盘配置，根据需求配置DO信号。
-
配置Mech-Viz工程中的DO信号
在Mech-Viz软件中，双击末端工具名称，工具类型选择拆垛吸盘，单击拆垛吸盘配置，根据需求配置DO信号。
调用顺序
-
该指令需在获取Mech-Vision规划路径指令、获取Mech-Viz规划路径指令或获取视觉移动规划数据或自定义数据指令之后被调用，即机器人先获取移动路径，再获取视觉移动路径点对应的吸盘DO信号。
-
该指令需在设置吸盘DO信号指令之前被调用。
设置吸盘DO信号
调用顺序
该指令需在获取吸盘DO信号指令之后被调用。
获取视觉移动规划数据或自定义数据
功能介绍
该指令用于获取Mech-Vision工程的视觉移动规划数据，或者获取Mech-Viz工程的视觉移动规划数据或自定义数据。该指令调用一次便可将所有数据存放至机器人内存中。
| 对于Mech-Viz 2.0版本软件，该指令暂时不支持获取自定义数据，仅支持获取视觉移动规划数据。 |
-
对于Mech-Vision工程：此处的“视觉移动规划数据”是指路径规划工具（从“路径规划”步骤处进入）中“视觉移动”步骤规划的数据，包括被抓取工件的标签、已抓取的工件总数、本次抓取的工件数量、吸盘边角号、TCP偏移量、工件组朝向、单个工件朝向、工件组尺寸。
-
对于Mech-Viz工程：
-
视觉移动规划数据：Mech-Viz中“视觉移动”步骤规划的数据，包括被抓取工件的标签、已抓取的工件总数、本次抓取的工件数量、吸盘边角号、TCP偏移量、工件组朝向、单个工件朝向、工件组尺寸。
-
自定义数据：Mech-Vision自定义端口输出的数据，再经Mech-Viz转发后得到的数据。
自定义端口的设置可从“输出”步骤参数的打开编辑器处进入，其中自定义通信键名就是自定义端口名称，例如下图中customeData1和customeData2端口就是自定义端口。
-
预设通信键（下图中的poses、labels、sizes、offsets等）所代表的端口数据不属于自定义数据。
-
Mech-Vision “输出”步骤的端口类型参数需要设置为“自定义”，且必须存在poses端口。
-
-
调用顺序
该指令需在运行Mech-Vision工程指令或运行Mech-Viz工程之后被调用。在使用该指令后，用户需调用转存视觉移动规划数据或自定义数据指令才可访问视觉移动规划数据或自定义数据。
指令格式
mm_get_plan_data(_resource,_pos_type,_socket_id)输入参数
_resource
该参数指定视觉移动规划数据的来源。取值为0或正整数，具体说明如下。
-
0：从Mech-Viz获取视觉移动规划数据。
-
正整数：从Mech-Vision获取视觉移动规划数据。此处设置的正整数就是Mech-Vision工程编号。
_pos_type
该参数表示预期的返回数据格式。
-
当_resource为0时，_pos_type参数取值范围为1~4，具体说明如下。
_pos_type参数值 预期的返回数据说明（每个字段的具体解释参见下文；若Mech-Vision工程无自定义端口，则无自定义数据项） 1
位姿（关节角形式）,移动类型,末端工具编号,速度,自定义数据项1,…,自定义数据项N
2
位姿（工具位姿形式）,移动类型,末端工具编号,速度,自定义数据项1,…,自定义数据项N
3
位姿（关节角形式）,移动类型,末端工具编号,速度,Mech-Viz视觉移动规划数据,自定义数据项1,…,自定义数据项N
4
位姿（工具位姿形式）,移动类型,末端工具编号,速度,Mech-Viz视觉移动规划数据,自定义数据项1,…,自定义数据项N
-
当_resource为正整数时，_pos_type参数取值范围为1~2，具体说明如下。
_pos_type参数值 预期的返回数据说明（每个字段的具体解释参见下文） 1
位姿（关节角形式）,移动类型,末端工具编号,速度,Mech-Vision视觉移动规划数据
2
位姿（工具位姿形式）,移动类型,末端工具编号,速度,Mech-Vision视觉移动规划数据
位姿
路径点的位姿可以是机器人关节角（单位为度）或工具位姿（其中三维坐标单位为毫米，欧拉角单位为度）。
移动类型
机器人移动类型，取值为1或2。
-
1：关节移动。
-
2：直线移动。
末端工具编号
路径点的末端工具编号。若值为-1，表示不使用末端工具。
速度
根据不同的工程，速度的含义也有所不同，具体如下。
-
对于Mech-Vision工程：速度指路径规划工具中设置的仿真速度值，使用百分数表示。
-
对于Mech-Viz工程：速度指移动类步骤参数中设置的速度参数值乘以Mech-Viz中设置的全局速度，使用百分数表示。
视觉移动规划数据
Mech-Vision或Mech-Viz中“视觉移动”步骤规划的数据，包括被抓取工件的标签、已抓取的工件总数、本次抓取的工件数量、吸盘边角号、TCP偏移量、工件组朝向、单个工件朝向、工件组尺寸。
名称 说明 维数 被抓取工件的标签
由10个整数组成，默认为10个0
10
已抓取的工件总数
累计已抓取的工件数量
1
本次抓取的工件数量
本次抓取的工件数量
1
吸盘边角号
本次吸盘所使用的边角号
1
TCP偏移量
工件组中心相对于末端工具中心的XYZ偏移量
3
工件组朝向
工件组与吸盘长边的朝向关系，0表示平行，1表示垂直
1
单个工件朝向
单个工件长边与吸盘长边的朝向关系，0表示平行，1表示垂直
1
工件组尺寸
本次抓取的工件组的长宽高
3
自定义数据项
单个视觉点的所有自定义端口的数据。例如，“输出”步骤各端口的数据如下表所示，则机器人获取第一个视觉点的自定义数据项为 [0,0,1]与[0,0]， 机器人获取第二个视觉点的自定义数据项为[1,0,0]与[1,1]。
端口名称
poses
labels
customData1
customData2
端口数据
[
[0, 0, 0, 1, 0, 0, 0],
[0, 0, 0, 1, 0, 0, 0]
]
[
"0",
"1"
]
[
[0, 0, 1],
[1, 0, 0]
]
[
[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]
-
_socket_id
机器人端socket识别号；默认为8，取值范围为2~23。
输出参数
g_mm_status
该参数用于保存该指令执行的状态码。若指令成功获取Mech-Vision工程的视觉移动规划数据，则状态码为1103。若指令成功获取Mech-Viz工程的视觉移动规划数据或自定义数据，则状态码为2100。
_pos_num
该参数用于保存视觉系统返回的路径点数量。
_vispos_idx
该参数表示Mech-Viz工程中“视觉移动”步骤对应的路径点（视觉移动路径点）在路径中的位置编号。如果路径中无视觉移动路径点，则该参数值为0。
例如，如果规划路径由以下路径点组成：“定点移动_1”，“定点移动_2”，“视觉移动”，“定点移动_3”，则视觉移动路径点的位置编号为3。
转存视觉移动规划数据或自定义数据
调用顺序
该指令需在获取视觉移动规划数据或自定义数据指令之后被调用。
指令格式
mm_get_plan_pos(_idx) （当获取视觉移动规划数据或自定义数据指令的_pos_type为2或者4时）
mm_get_plan_jps(_idx) （当获取视觉移动规划数据或自定义数据指令的_pos_type为1或者3时）输出参数
_pos
该参数用于保存指定索引号对应路径点的工具位姿（mm_get_plan_pos指令中使用该参数）。
_jps
该参数用于保存指定索引号对应路径点的关节角（mm_get_plan_jps指令中使用该参数）。
_movetype
该参数用于保存指定索引号对应路径点的移动类型。1表示关节移动，2表示直线移动。
_toolnum
该参数用于保存指定索引号对应路径点的末端工具编号。若编号为-1，表示不使用末端工具。
_speed
该参数用于保存指定索引号对应路径点的速度。
mm_userdata
该参数用于保存指定索引号对应路径点的自定义数据。
mm_plandata
该参数用于保存指定索引号对应路径点的视觉移动规划数据。
mm_plandata变量的具体内容如下表所示。
| 数据 | 说明 | 变量 |
|---|---|---|
被抓取工件的标签 |
由10个整数组成，默认为10个0 |
mm_plandata[1~10] |
已抓取的工件总数 |
累计已抓取的工件数量 |
mm_plandata[11] |
本次抓取的工件数量 |
本次抓取的工件数量 |
mm_plandata[12] |
吸盘边角号 |
本次吸盘所使用的边角号 |
mm_plandata[13] |
TCP偏移量 |
工件组中心相对于末端工具中心的XYZ偏移量 |
mm_plandata[14~16] |
工件组朝向 |
工件组与吸盘长边的朝向关系，0表示平行，1表示垂直 |
mm_plandata[17] |
单个工件朝向 |
单个工件长边与吸盘长边的朝向关系，0表示平行，1表示垂直 |
mm_plandata[18] |
工件组尺寸 |
本次抓取的工件组的长宽高 |
mm_plandata[19~21] |
示例
--input
mm_idx=1
--output
mm_jps={0,0,0,0,0,0}
mm_movetype=0
mm_toolnum=0
mm_speed=0
mm_userdata={}
mm_plandata={}
......
mm_jps,mm_movetype,mm_toolnum,mm_speed,mm_userdata,mm_plandata = mm_get_plan_jps(mm_idx)上述示例表示，将第一个路径点的关节角、移动类型、末端工具编号、速度分别保存至mm_jps、mm_movetype、mm_toolnum、mm_speed。如果该路径点不是视觉移动路径点，则无后续信息；如果该路径点是视觉移动路径点，则将视觉移动规划数据保存至mm_plandata，将自定义数据保存至mm_userdata。
获取通知的消息
功能介绍
当Mech-Vision工程或Mech-Viz工程运行至“通知”步骤时，视觉系统会返回“通知”步骤中预先设置的消息。
在使用该指令前，“通知”步骤需满足以下设置。
-
Mech-Vision工程中的“通知”步骤
-
将“通知”步骤连接在其他步骤的右侧（此处以“输出”步骤为例）。
-
在“输出”的步骤参数处，勾选有输出时触发控制流。
-
在“通知”的步骤参数处，服务名称填写Standard Interface Notify（不可更改），消息填写1001（根据需求填写，但必须为正整数）。
-
-
Mech-Viz工程中的“通知”步骤
-
将“通知”步骤连接在工作流程中的合适位置。
-
在“通知”的步骤参数处，勾选标准接口，消息填写1000（根据需求填写，但必须为正整数）。
-
调用顺序
该指令需在运行Mech-Vision工程指令或运行Mech-Viz工程指令之后立即被调用。
标定
功能介绍
该指令用于机器人的手眼标定（外参标定）。该指令需要与Mech-Vision工具栏中的相机标定结合使用，从而实现自动标定，具体参见CGXi自动标定。
获取工程状态
指令格式
mm_get_status(_socket_id)输出参数
g_mm_status
该参数用于保存该指令执行的状态码。若指令执行正常，则状态码为1101，表示Mech-Vision工程已就绪。 若指令执行异常，则状态码为对应的错误码，具体可参考《标准接口状态码及错误排查》。