ROKAE 接口程序指令说明
指令调用说明：
指令受ROKAE语法限制，导致无法传递形参和返回值，因此指令涉及的参数和返回值均为全局变量。
启动 Mech-Vision 工程
该指令用于触发 Mech-Vision 工程的运行，执行相机拍照和视觉处理。用于只使用 Mech-Vision 而不使用 Mech-Viz 的场景。
程序
Job = 1
Pos_Num_Need = 1
SendPos_Type = 1
MM_J = UpdateJnttarget(MM_J,0,0,0,0,0,0,0,0,0,0,0,0)
MM_Start_Vis()该程序触发 Mech-Vision 工程 1 的运行，希望 Mech-Vision 工程 1 返回 1 个视觉点，机器人将当前关节角和法兰数据传入 Mech-Vision。UpdateJnttarget(MM_J,0,0,0,0,0,0,0,0,0,0,0,0) 表示设置固定关节角值，在 SendPos_Type 参数值为 3 时使用。
输入参数
Job
Mech-Vision 工程编号可在 Mech-Vision 工程列表窗口中查看，工程名称前的数字表示工程编号。
Pos_Num_Need
预期视觉点数量，即期望从 Mech-Vision 得到的视觉点数量。视觉点信息包括视觉位姿及对应点云、标签、缩放等。
-
0：从 Mech-Vision 工程取得识别结果中所有的视觉点。 -
大于0的整数：从 Mech-Vision 工程取得识别结果中指定数量的视觉点。-
如果视觉点总数小于该参数值，则取得识别结果中所有视觉点。
-
如果视觉点总数大于等于该参数值，则取得该参数指定数量的视觉点。
-
| 获取视觉点的指令是 102 指令。默认每次执行 102 指令最多可以获取 20 个视觉点。在第一次执行 102 指令后，其中一个返回的参数将体现是否已返回所有请求的视觉点；如果没有，请重复执行 102 指令。 |
SendPos_Type
机器人位姿类型，该参数指定真实机器人的位姿将以何种形式传入 Mech-Vision。参数范围：0~3。
-
0：该指令不需向视觉系统传入机器人位姿。若相机安装方式为 Eye To Hand，则拍照与机器人位姿无关，Mech-Vision 不需要机器人的位姿。 -
1：该指令以“机器人当前关节角+当前法兰”形式向视觉系统传入机器人位姿。若相机安装方式为 Eye In Hand，则推荐使用该参数。在使用时，Mech-Vision 工程中存在的“路径规划”步骤将使用机器人发送关节角。如果法兰位姿为全零，则忽略法兰数据。 -
2：该指令以当前法兰位姿形式向视觉系统传入机器人位姿，适用于相机安装方式为 Eye In Hand，且机器人无关节角数据，仅有法兰位姿数据（如桁架机器人）的场景中。 -
3：该指令以预定义关节角（读取用户设置的关节角变量）形式向视觉系统传入机器人位姿。若相机安装方式为 Eye To Hand，则推荐使用该参数。在使用时，Mech-Vision 工程中存在的“路径规划”步骤将使用机器人发送的关节角作为初始位姿。
MM_J
用户自己定义的关节角。在 SendPos_Type 参数值为 3 时，该关节角数据将发送给 Mech-Vision 工程的“路径规划”步骤作为第一个路径点进行规划。若 SendPos_Type 参数值为 3 以外的其他参数值，此处的关节角无实际用处，但必须设定该关节角。
获取视觉目标点
该指令用在“启动 Mech-Vision 工程”指令之后，用于获取 Mech-Vision 输出的视觉点，然后自动将视觉点转换为视觉目标点。
视觉系统会自动将视觉点信息转换为对应的机器人 TCP。
| 102 指令单次接收 TCP 数量上限默认为 20。如需要获取的 TCP 数量大于 20，需多次执行该指令来获取所有所需 TCP。 |
程序
Job = 1
MM_Get_VisData()该程序用于获取 Mech-Vision 工程 1 的视觉结果。该指令的输出值保存在全局变量（Last_Data、Pose_Num、MM_Status）中。 其中，Last_Data 表示是否仍有 TCP 未传输完毕，Pose_Num 表示当次返回的 TCP 数量，MM_Status为状态码。
输出参数
Last_Data
该参数表明是否已取得所有所需 TCP。值为 0 或 1。
-
0：未取得所有所需 TCP。请重复执行 102 指令直到该参数值为 1。 -
1：已取得所有所需 TCP。
如果“启动 Mech-Vision 工程”指令指定的预期 TCP 数量大于 20（收发数据长度的默认值），可通过该参数判断是否还有未发送的 TCP。若数据未发送完毕，则可以重复调用 102 指令，继续接收。
| 如未取得所有 TCP，若此时调用 101 指令重新拍照，则未取得的 TCP 将被清除。 |
变量类型：int
Pos_Num
执行该指令获得的 TCP 数量。
-
如果请求 TCP 数量大于等于 Mech-Vision 识别的视觉点数量，按照 Mech-Vision 识别的视觉点数量发送。
-
如果请求 TCP 数量小于 Mech-Vision 识别视觉点数量，按照请求数量发送。
默认范围：0~20。
变量类型：int
MM_Status
若指令执行正常，则返回 1100 状态码；否则返回对应的错误码。
调用该指令时，若 Mech-Vision 结果还未返回，则视觉系统会等待 Mech-Vision 结果返回后再给机器人返回。默认等待 10 秒超时，若发生超时，返回超时错误状态码。
变量类型：int
启动 Mech-Viz 工程
用于既使用 Mech-Vision 又使用 Mech-Viz 的场景。该指令用于运行 Mech-Viz 工程，启动对应的 Mech-Vision 工程，Mech-Viz 基于 Mech-Vision 的视觉结果规划机器人的运动路径。
请在需要启动 Mech-Viz 工程中勾选 自动加载。
Mech-Vision和Mech-Viz软件安装目录下 Communication Component/tool/viz_project 文件夹内有一些典型应用工程模板，用户可以在模板的基础上进行修改。
输入参数
SendPos_Type
机器人的位姿类型。参数范围：0~2。
0：无需向 Mech-Viz 传入机器人位姿，Mech-Viz 软件中仿真机器人将会从关节角 [0,0,0,0,0,0] 位置开始，运动到第一个路径点。
1：将机器人的当前关节角和法兰位姿传入 Mech-Viz，Mech-Viz 软件中仿真机器人将会从当前机器人关节角位置开始，运动到第一个路径点。
2：将机器人的一个预定义关节角传入 Mech-Viz，Mech-Viz 软件中仿真机器人将会从当前机器人关节变量设定的位置开始，运动到第一个路径点。
MM_J
用户自定义的关节角数据。仅当 SendPos_Type 为 2 时，该关节角数据将发送给 Mech-Viz 作为第一个路径点进行规划；当 SendPos_Type 为其他值时，该关节角数据无实际意义，但必须设定其值。
获取 Mech-Viz 数据
该指令用于获取 Mech-Viz 规划的路径。应在执行“启动 Mech-Viz 工程”指令后获取规划路径。
限制：默认设置下，该指令每次最多只能获取 20 个规划路径的路径点，所以该指令可能需要调用多次。
|
如果工程中某个移动类步骤的路径点不应发给机器人，请取消勾选该步骤参数中的“发送移动目标”选项。 |
程序
Jps_Pos = 2
MM_Get_VizData()该程序用于接收 Mech-Viz 返回的机器人移动路径，路径点数据类型为 TCP， 路径点是否发送完毕保存在全局变量 Last_Data 中，路径点的数量保存在全局变量 Pos_Num 中，视觉移动路径点在路径中的编号保存在全局变量 VisPos_Num 中，指令执行的状态码保存在全局变量 MM_Status 中。
输出参数
Last_Data
是否发送完成。
-
0：未发送完路径中的全部路径点。请重复执行该指令，直到该参数值为 1。 -
1：已发送完路径中全部路径点。
Pos_Num
路径点数量。该参数用于显示此次执行该指令返回了多少路径点（[位姿、标签、速度]）。
如果路径中含有 20 个以上路径点，请多次执行该指令。
默认范围：0~20。
VisPos_Num
“视觉移动”步骤位置，即“视觉移动”步骤路径点在整个路径中的位置。“视觉移动”步骤即移动至视觉点（抓取物体的点）的移动步骤。
比如，如果规划路径由以下步骤组成：“定点移动_1”，“定点移动_2”，“视觉移动”，“定点移动_3”，则“视觉移动”步骤位置为3。
如果路径中无“视觉移动”步骤，则该参数值为 0。
MM_Status
状态码。
若指令执行正常，则返回 2100 状态码；否则返回对应的错误码。
| 调用该指令时，若 Mech-Viz 结果还未返回（正在运行中），视觉系统会等待 Mech-Viz 结果返回后再给机器人返回，默认等待 10s 超时，若发生超时，则给机器人返回超时错误。 |
获取视觉点坐标值
获取视觉点关节角（用 Mech-Viz 规划时有效）
切换 Mech-Vision 配方
切换 Mech-Vision 工程内的参数配方。
Mech-Vision 中步骤的参数设定可通过切换参数配方调整。
| 需要在执行“启动 Mech-Vision 工程”指令之前使用该指令。 |
选择 Mech-Viz 分支
当 Mech-Viz 工程中有分支步骤时，该指令可控制 Mech-Viz 工程中的分支步骤走指定的出口。
在执行该指令前请先执行“启动 Mech-Viz 工程”指令。
Mech-Viz 工程运行至分支步骤时，将等待该指令指定出口。
设置移动索引
向 Mech-Vision 中传入物体尺寸
获取 DO 信号列表
该指令用于获取规划的 DO 信号列表。DO 信号列表用于控制多个工具或吸盘分区。
执行该指令前，需要先执行“获取规划路径”指令来获取 Mech-Viz 规划的路径。
请根据模板工程来部署 Mech-Viz 工程，并在工程中设置对应的吸盘配置文件。模板工程位于Mech-Vision和Mech-Viz软件安装目录下 Communication Component/tool/viz_project/suction_zone 文件夹。
设置 DO 信号列表
标定
该指令用于手眼标定（相机外参标定）。
该指令会与 Mech-Vision 同步标定状态，并从 Mech-Vision 处获得机器人需要到达的标定点。
该指令需要运行多次以完成标定。
获取 Mech-Vision 自定义数据
该指令用于从 Mech-Vision 中的“输出”步骤接收自定义数据，即除 poses 和 labels 之外其他端口的数据（“输出”步骤参数“端口类型”设置为“自定义”）。
该指令调用一次获取全部数据到机器人内存。
将 MM_Get_Dy_Data() 获取的自定义数据分配至各变量中
该指令用于将一组自定义数据按指定索引从内存存放到不同变量中，在触发 获取 Mech-Vision 自定义数据 指令之后使用。
从 Mech-Viz 获取路径点
该指令用于从 Mech-Viz 获取路径规划结果。其中，路径点可以是一般移动路径点，也可以是视觉移动路径点。路径点可能包含位姿、速度、工具信息、工件信息等。该指令调用一次便可将获取的全部数据存放到机器人内存中。
执行该指令得到的路径点可以是以下三种之一。
-
除了“视觉移动”之外的一般移动路径点，其信息包括运动类型（关节运动或直线运动）、工具编号、速度。
-
视觉移动路径点，其信息包括标签、已抓取的工件总数、本次抓取的工件数量、吸盘边角号、TCP 偏移量、工件朝向、工件组尺寸。
-
包含自定义数据的视觉移动路径点，此时 Mech-Vision 工程“输出”步骤的端口类型需设置为“自定义”。
程序
Jps_Pos = 4
MM_Get_PlanData()该示例在 Mech-Viz 工程运行后，将所有输出数据存放到机器人全局数组中，VisPos_Num 变量为视觉移动位置编号，MM_Status 变量为本指令执行的状态码。
输入参数
Jps_Pos
int 类型全局变量。预期的返回数据格式，取值范围为 1~4。
以下是四种预期的返回数据格式说明。
| 预期的返回数据格式 参数值 | 预期的返回数据 说明（每个字段的具体解释参见下文） |
|---|---|
1 |
位姿（JPs 形式）, 运动类型, 工具编号, 速度, 自定义数据项个数, 自定义数据项 1, …, 自定义数据项 N |
2 |
位姿（TCP 形式）, 运动类型, 工具编号, 速度, 自定义数据项个数, 自定义数据项 1, …, 自定义数据项 N |
3 |
位姿（JPs 形式）, 运动类型, 工具编号, 速度, 视觉规划结果, 自定义数据项个数, 自定义数据项 1, …, 自定义数据项 N |
4 |
位姿（TCP 形式）, 运动类型, 工具编号, 速度, 视觉规划结果, 自定义数据项个数, 自定义数据项 1, …, 自定义数据项 N |
位姿 （保存于 MM_Pose_Pos[128] 中）
路径点的位姿可以是机器人关节角（JPs，单位为度）或工具位姿（TCP，其中三维坐标单位为毫米，欧拉角单位为度），其形式取决于发送的指令参数。
运动类型 （保存于 MM_Pose_MoveType[128] 中）
-
1：关节运动，MOVEJ -
2：直线运动，MOVEL
工具编号 （保存于 MM_Pose_ToolNum[128] 变量中）
路径点的工具编号。 -1 表示不使用工具。
速度 （保存于 MM_Pose_Speed[128] 中）
路径点的速度百分比值，其值为 Mech-Viz 工程中该路径点对应移动类步骤的参数中设置的速度乘以 Mech-Viz 中设置的全局速度，使用百分数表示。
视觉规划结果 （保存于 Plan_Results[128][128] 中）
路径中的规划结果信息（如果路径点对应移动步骤为视觉移动）。通常用于纸箱多拣、卸垛等。信息包括：
-
标签：由 10 个正整数组成，默认为 10 个 0。
-
已抓取的工件总数。
-
本次抓取的工件数量。
-
吸盘边角号：用于指定工件靠近吸盘的哪个边角。在 Mech-Viz 的“工程资源”中双击对应的末端工具名称，然后单击 控制逻辑配置窗口 ，便可查看吸盘边角号。
-
工具位姿（TCP）偏移量：从对应工件中心的 TCP 到 实际 TCP 的偏移量。
-
工件朝向：工件坐标系 X 轴相对于 TCP X 轴的方向。
-
工件组尺寸。
自定义数据项个数 （保存于 UserDataNum 中）
当 Mech-Vision 工程中“输出”步骤的端口类型为“自定义”时，除 poses 和 labels 之外其他端口的数量。
自定义数据项 （保存于 UserData[128][128] 中）
当 Mech-Vision 工程中“输出”步骤的端口类型为“自定义”时，除 poses 和 labels 之外其他端口的数据。
各自定义数据按照端口名称的字母顺序（A—Z）排列。
将 MM_Get_PlanData() 获取的数据分配各变量中
该指令用在 从 Mech-Viz 获取路径点 后，用于按指定索引将对应的一组数据存放到不同变量中，根据 Jps_Pos 参数值选择不同的程序。
程序
Serial = 2
Jps_Pos = 4
MM_Get_PlanPose()该示例程序运行后，将 Mech-Viz 规划的第二个路径点的 TCP 数据存放在全局变量 MM_P 中，运动类型、工具编号、速度分别存放在全局变量 MM_MoveType、MM_ToolNum、MM_Speed 中。如果该路径点不是视觉移动路径点，则无后续信息；如果是视觉移动路径点，则将视觉规划结果保存到 MM_Plan_Results 全局数组中， 将自定义输出数据保存到 MM_UserData 全局数组中。
Serial = 1
Jps_Pos = 3
MM_Get_PlanJps()该示例程序运行后，将 Mech-Viz 规划的第一个路径点的关节角数据存放在全局变量 MM_J 中，运动类型、工具编号、速度分别存放在全局变量 MM_MoveType、MM_ToolNum、MM_Speed 中。如果该路径点不是视觉移动路径点，则无后续信息；如果是视觉移动路径点，则将视觉规划结果保存到 MM_Plan_Results 全局数组中， 将自定义输出数据保存到 MM_UserData 全局数组中。
输入参数
Serial
int 类型变量。指定获取全局数组中的第几组路径点数据（数据顺序按照 Mech-Viz 输出的路径点顺序排列）。
Jps_Pos
int 类型变量。需要与 MM_Get_PlanData() 中的 Jps_Pos 所选值一致。
输出参数
MM_P
robtarget 类型全局变量。保存指定路径点对应的 TCP 数据（程序 1 使用）。
MM_J
Jointtarget 类型全局变量。保存指定路径点对应的关节角数据（程序 2 使用）。
MM_MoveType
int 类型全局变量。保存指定路径点对应的运动类型。
MM_ToolNum
int 类型全局变量。保存指定路径点对应的工具编号。
MM_Speed
int 类型全局变量。保存指定路径点对应的速度。
MM_UserData
全局数组变量（用户不需要传递该参数，直接读取该数组即可）。保存指定路径点对应的用户自定义数据。
MM_Plan_Results
全局数组变量（用户不需要传递该参数，直接读取该数组即可）。保存指定路径点对应的视觉规划结果。
获取 Mech-Vision “路径规划”步骤的结果
在启动 Mech-Vision 工程后，该指令用于获取 Mech-Vision 中“路径规划”步骤输出的免碰撞抓取路径。
在使用该指令时，Mech-Vision “输出”步骤的 端口类型 参数需要设置为“预定义（机器人路径）”。
程序
Job = 2
Jps_Pos = 2
MM_Get_VisPath()该示例用于接收 Mech-Vision 工程 2 返回的机器人移动路径，路径点位姿类型为 TCP，路径点的数量保存在全局变量 Pos_Num 中，视觉移动路径点在路径中的位置编号保存在变量 VisPos_Num 中，执行指令后的状态码保存在变量 MM_Status 中。