适配程序（Adapter）生成器手册
本节介绍适配程序生成器，以及如何使用适配程序生成器快速生成适配程序。为方便叙述，下文中的“适配程序”统一使用“Adapter”表示。
简介
Adapter生成器是一个快速生成Adapter程序的工具。你仅需在图形化界面简单配置参数，便可快速创建相应的Adapter程序，然后在此基础上进行二次开发，实现标准接口无法满足的复杂功能。
Adapter程序是连接外部通信设备（工业机器人、上位机、PLC）与Mech-Vision/Mech-Viz软件的Python程序，类似于管家角色，对内与Mech-Vision/Mech-Viz进行通信，对外通过任何Python能够实现的通信协议与外部设备进行通信。
Adapter生成器与Adapter程序之间的关系如下图所示。
Adapter生成器的主要功能是配置机器人程序与Adapter程序之间通信的指令。配置的指令包括Mech-Vision拍照指令、设置Mech-Vision步骤参数指令、Mech-Viz拍照指令、设置Mech-Viz步骤参数指令。你可根据通信对象与实际需求配置其中一条或多条指令。 Adapter生成器的总体配置流程如下。
关于通信对象，请根据以下说明进行选择。
通信对象 |
说明 |
适用场景 |
Mech-Vision |
使用Mech-Vision软件获取视觉结果或规划路径。 |
只发送视觉结果的项目或简单的路径规划项目。 |
Mech-Viz |
使用Mech-Viz软件规划路径，Mech-Viz工程需调用Mech-Vision工程对应的视觉服务。同时，在Mech-Viz工程调用Mech-Vision工程对应的视觉服务前，无需设置Mech-Vision的步骤参数。 |
稍微复杂的路径规划项目。 |
Mech-Vision&Mech-Viz |
使用Mech-Viz软件规划路径，存在以下两种情况之一，通信对象均可选择Mech-Vision&Mech-Viz。
|
上述两种通信无法满足时，可考虑选择此通信。 |
使用Adapter生成器生成Adapter程序
本小节介绍如何使用Adapter生成器快速生成Adapter程序。
| 在开始前，请确保已成功搭建并打开Mech-Vision方案和Mech-Viz工程（若存在）。 |
打开Adapter生成器
在Mech-Vision菜单栏中，依次单击 ，弹出 适配程序（Adapter）生成器 窗口。
|
配置“基础设置”
-
在 基础设置 窗口，设置 Adapter工程名称、通信对象、通信协议、参数格式。
根据 通信对象 不同，整个配置流程会有所不同，即左侧窗口会根据 通信对象 显示不同的配置项。例如，通信对象选择 Mech-Vision，只需配置 基础设置、Mech-Vision输入、Mech-Vision输出、状态码设置。 请根据以下说明配置 基础设置。
配置项
说明
Adapter工程名称
指定Adapter工程名称。工程名称是由字母、数字或下划线组成的字符串（不能以数字作为起始字符）。
通信对象
Mech-Vision
仅需配置Mech-Vision输入与输出。
Mech-Viz
仅需配置Mech-Viz输入与输出。
Mech-Vision&Mech-Viz
需配置Mech-Vision和Mech-Viz输入与输出。
通信协议
TCP/IP
通信格式
指定通信传输的字符串格式，目前仅支持ASCII形式字符串。
服务类型
指定Adapter工程作为TCP/IP通信的服务端或客户端，默认作为服务端。
参数格式
平移单位
mm（毫米，默认）和m（米）
旋转单位
°（角度，默认）和rad（弧度）
旋转方式
欧拉角
旋转方式通常选择欧拉角即可。根据机器人类型，选择对应的 欧拉角格式。
-
ABB/EPSON/ESTUN/KUKA/NACHI： Z-Y'-X''(ZYX_ROTATED)
-
AUBO/DENSO/DOBOT/DELTA/EFORT/ELITE/FANUC/FLEXIV/FR/HANS/HYUNDAI/JAKA/MELFA/ROKAE/SIASUN/STEP/TM/YASKAWA：X-Y-Z(XYZ_STATIC)
-
COMAU/DOOSAN/KAWASAKI/QJAR：Z-Y'-Z''(ZYZ_ROTATED)
-
STAUBLI/TURIN：X-Y'-Z''(XYZ_ROTATED)
-
UR：ur_rot
四元数
选择四元数后，输入和输出中所有位姿数据都会以四元数形式进行传输。
其他数据格式
浮点小数位数
指定数据的小数位数。默认为4，可选范围为1~20。
字符串分割符
指定数据间的分割字符。默认为英文逗号，常用分割符有英文逗号、分号和空格。
通信协议选择TCP/IP及ASCII，才会出现这三项。
字符串终止符
指定指令的结束字符。默认为\r，常用终止符有\n、\r、\r\n。
添加首尾字符
指定整条指令的首尾字符。勾选后需要输入首尾字符，默认为空字符。例如，指令为“p,1\r”，若首字符使用“<”，尾字符使用“>”，则整条指令将表示为“<p,1>\r”。
-
-
完成上述配置后，单击 下一页。根据所选的通信对象，将进入相应的指令配置界面。
配置“Mech-Vision输入”
在 Mech-Vision输入 窗口，设置机器人或上位机发送给Mech-Vision的指令格式。具体配置项包括 拍照指令 、设置Mech-Vision步骤参数 和 从Mech-Vision获取机器人名称。
设置拍照指令
-
设置Mech-Vision的拍照指令。
该指令主要用于触发Mech-Vision工程运行。除此之外，该指令还可以根据需求设置以下功能。
-
如果Mech-Vision工程存在参数配方，该指令支持切换参数配方。
-
如果相机的安装方式为Eye In Hand，或者Mech-Vision工程存在“路径规划”步骤，该指令支持将机器人拍照位姿传入Mech-Vision工程。
请根据以下说明配置 拍照指令。
名称：整条指令中各部分的名称。
参数值：各部分名称所对应的具体值。
位置：各部分在整条指令中所处的起始位置，从1开始排序，一个逗号表示一个位置结束。
长度：各部分占用的字段数（字段指使用 字符串分隔符 隔开的数据）。
位置 与 长度 之间的关系：下一个参数的起始位置 = 上一个参数的起始位置 + 上一个参数的长度。
名称 参数值 位置 长度 指令码
触发Mech-Vision工程运行的指令码，默认为p，可修改。
固定为1
固定为1
工程编号
Mech-Vision工程编号，为正整数。
固定为2
固定为1
配方编号（可选）
Mech-Vision工程中参数配方的编号，为正整数。
可设置
固定为1
机器人拍照位姿（可选）
如果相机安装方式为Eye In Hand，该指令将把机器人拍照位姿传入Mech-Vision工程。该参数可设置为JPs或“JPs+法兰位姿”。
可设置
-
若旋转方式选择欧拉角：
-
位姿形式为JPs，则固定为6；
-
位姿形式为“JPs+法兰位姿”，则固定为12。
-
-
若旋转方式选择四元数：
-
位姿形式为JPs，则固定为6；
-
位姿形式为“JPs+法兰位姿”，则固定为13。
-
-
-
双击 参数值、位置、长度 三列中高亮显示的内容，可根据需求对其进行修改。
-
对于不同指令，指令码需保证唯一。
-
不同参数所占的字段位置切勿存在重叠。例如，机器人拍照位姿的位置为3，长度为12。如果配方编号的位置为4，长度为1，此时机器人拍照位姿的第二个字段位置与配方编号的位置重叠。如果配方编号的位置为大于或等于15，则机器人拍照位姿与配方编号的位置将不存在重叠。
-
若各参数所对应的位置间存在空缺，则默认使用0填充。在预览时，该空缺位置显示为 预留位置，所对应的值为0。例如，配方编号的位置为3，长度为1，机器人拍照位姿的位置为6，长度为12，则位置4和5空缺。若将机器人拍照位姿的位置修改为4，便可消除该空缺位置。建议通过修改位置，消除不必要的空缺位置。
-
-
完成上述配置后，单击 预览，将根据配置项生成相应的指令示例。
在 指令预览 窗口，将鼠标的光标悬浮到字段名称上，字段名称及对应的数据将高亮显示。
设置Mech-Vision步骤参数（可选）
若无法使用参数配方对步骤参数进行预设置，或者需要根据外部信息对步骤参数进行设置，则勾选 设置Mech-Vision步骤参数，从而配置“设置Mech-Vision步骤参数”指令。
-
选择是否勾选 与拍照指令合并。
“与拍照指令合并”是指设置Mech-Vision步骤参数写在拍照指令里，即在拍照指令的基础上添加设置的步骤参数。设置Mech-Vision步骤参数 指令可以与Mech-Vision拍照指令合并成一条指令，也可以单独作为一条指令（此时需在调用拍照指令之前被调用）。
请根据以下说明确定是否勾选 与拍照指令合并，并执行相应的操作。
-
如果通信对象选择 Mech-Vision&Mech-Viz，且需要设置Mech-Vision步骤参数，此时无需勾选 与拍照指令合并。 请根据下表说明配置“设置Mech-Vision步骤参数”指令，然后执行第二步。
名称
参数值
位置
长度
指令码
设置Mech-Vision步骤参数的指令码，默认为s，可修改。
固定为1
固定为1
工程编号
Mech-Vision工程编号，为正整数。
固定为2
固定为1
配方编号（可选）
Mech-Vision工程中参数配方的编号，为正整数。
可设置
固定为1
-
如果通信对象选择 Mech-Vision，且需要设置Mech-Vision步骤参数，此时可勾选 与拍照指令合并，也可不勾选 与拍照指令合并。如果勾选 与拍照指令合并，上述表格中的配置项将复用拍照指令中的设置，接下来执行第二步。
-
-
选择步骤参数。
单击 选择步骤参数，在弹出的窗口中，根据以下操作选择步骤参数。
-
选择方案中的某个工程，用于显示将要设置的步骤及对应的参数名称。
-
在 选择步骤 选项下，选择需设置的步骤。
-
在 步骤中的参数 选项下，勾选步骤的参数名称。
-
单击 确认。
-
若勾选 设置Mech-Vision步骤参数，则必须选择步骤参数，否则将出现以下弹窗提示。
-
步骤和参数可选择多个。
-
若步骤参数值的数据类型为布尔，则使用1表示true，0表示false。
以上图中的设置为例，单击 确认 后，设置Mech-Vision步骤参数的指令如下图所示。
-
-
不同参数所占的字段位置切勿存在重叠。
-
若各参数所对应的位置间存在空缺，则默认使用0填充。建议通过修改位置，消除不必要的空缺位置。
-
-
完成上述配置后，单击 预览，将根据配置项生成相应的指令示例。
配置“Mech-Vision输出”
在 Mech-Vision输出 窗口，设置Mech-Vision返回给机器人或上位机的数据格式。具体配置项包括 位姿数据 、物体标签 和 其他输出。
-
根据Mech-Vision工程的“输出”步骤确定相应配置项。
“输出”步骤端口类型 端口名称 配置项 适用场景 预定义（视觉结果）
poses
位姿数据（视觉点数据）
获取目标物体的位姿
预定义（视觉结果）
poses、labels
位姿数据（视觉点数据）、物体标签
获取目标物体的位姿、标签
预定义（机器人路径）
moves
位姿数据（机器人路径）
规划机器人移动至目标物体的路径
自定义
自定义端口名称
其他输出
获取自定义的数据，例如，获取OCR文字、VIN码、测量结果等
-
根据以下说明对配置项进行设置。
配置项
说明
位姿数据
视觉点数据（Mech-Vision工程无“路径规划”步骤）
数量
可设置项：1个、固定值（需手动填写）、所有。
-
1：Mech-Vision输出N个视觉点，但Adapter只返回第一个视觉点。
-
固定值M：Mech-Vision输出N个视觉点，但Adapter只返回前M个视觉点。
-
所有：Mech-Vision输出N个视觉点，Adapter返回N个视觉点。
发送的位姿个数
Mech-Vision返回的数据中将携带本次返回的位姿个数，位姿个数将位于位姿数据前面。
将物体位姿转为机器人位姿
自动将Mech-Vision识别结果的位姿绕X轴旋转180°（使其Z轴朝下），机器人便可直接移动到该位姿进行抓取。
机器人路径（Mech-Vision工程必须存在“路径规划”步骤）
位姿类型
可设置项：JPs、TCP。
发送的位姿个数
Mech-Vision返回的数据中将携带本次返回的位姿个数。位姿个数将位于位姿数据前面。
视觉点在路径中的位置
路径规划工具中“视觉移动”步骤对应的路径点在路径中的位置。
运动方式MOVEJ/MOVEL
路径点的运动方式，1表示MOVEJ，2表示MOVEL。
物体标签
“输出”步骤的labels端口数据
其他输出（单击 +，可配置多个端口）
端口名称
“输出”步骤的自定义端口名称
数据类型
可设置项：stringlist、numberlist
-
在配置 其他输出 时，请确保自定义端口数据的列表大小与标签或位姿的列表大小保持一致。
-
选择 视觉点数据：若 基础设置 中旋转方式选择四元数，则输出的每个位姿占据7个字段。
-
选择 机器人路径：若 基础设置 中旋转方式选择四元数，位姿类型选择TCP，则输出的每个位姿占据7个字段；位姿类型选择JPs，则输出的每个位姿占据6个字段。
-
若未勾选任何配置项，无法进行下一步操作。
-
-
完成上述配置后，单击 预览，将根据配置项生成相应的指令示例。确认无误后，单击 下一页，进入下一配置界面。
配置“Mech-Viz输入”
在 Mech-Viz输入 窗口，设置机器人或上位机发送给Mech-Viz的指令格式，具体配置项包括 拍照指令 、设置Mech-Viz步骤参数 和 从Mech-Viz获取机器人名称。
拍照指令
-
设置Mech-Viz的拍照指令。
该指令主要用于触发Mech-Viz工程运行。除此之外，该指令还可以根据需求设置以下功能。
-
如果Mech-Viz工程对应的Mech-Vision工程存在参数配方，该指令支持切换参数配方。
-
如果Mech-Viz工程存在一个消息分支，该指令支持设置消息分支出口。
-
如果相机的安装方式为Eye In Hand，或者将设置的示教拍照点作为Mech-Viz规划的起始点，该指令支持将机器人拍照位姿或示教拍照点位姿传入Mech-Viz工程。
请根据以下说明配置 拍照指令。
名称：整条指令中各部分的名称。
参数值：各部分名称所对应的具体值。
位置：各部分在整条指令中所处的起始位置，从1开始排序，一个逗号表示一个位置结束。
长度：各部分占用的字段数（字段指使用 字符串分隔符 隔开的数据）。
位置 与 长度 之间的关系：下一个参数的起始位置 = 上一个参数的起始位置 + 上一个参数的长度。
名称 参数值 位置 长度 指令码
触发Mech-Viz工程运行的指令码，默认为r，可修改。
固定为1
固定为1
Mech-Vision工程编号（可选）
Mech-Vision工程编号，为正整数。
固定为2
固定为1
Mech-Vision配方编号（可选）
Mech-Vision工程中参数配方的编号，为正整数。
可设置
固定为1
分支编号（可选）
“消息分支”的步骤编号。仅支持Mech-Viz工程中存在一个消息分支的场景。
可设置
固定为1
分支出口号（可选）
指定“消息分支”步骤的出口号，例如，该参数值为0，则“消息分支”步骤将沿出口号0继续运行。
可设置
固定为1
机器人拍照位姿（可选）
如果相机安装方式为Eye In Hand，该指令将把机器人拍照位姿传入Mech-Viz工程。该参数可设置为JPs、JPs+法兰位姿。
可设置
-
若旋转方式选择欧拉角：
-
位姿形式为JPs，则固定为6；
-
位姿形式为“JPs+法兰位姿”，则固定为12。
-
-
若旋转方式选择四元数：
-
位姿形式为JPs，则固定为6；
-
位姿形式为“JPs+法兰位姿”，则固定为13。
-
-
双击 参数值、位置、长度 三列中高亮显示的内容，可根据需求对其进行修改。
-
对于不同指令，指令码需保证唯一。
-
不同参数所占的字段位置切勿存在重叠。例如，机器人拍照位姿的位置为3，长度为6。如果配方编号的位置为4，长度为1，此时机器人拍照位姿的第二个字段位置与配方编号的位置重叠。如果配方编号的位置为大于或等于9，则机器人拍照位姿与配方编号的位置将不存在重叠。
-
若各参数所对应的位置间存在空缺，则默认使用0填充。在预览时，该空缺位置显示为 预留位置，所对应的值为0。例如，配方编号的位置为3，长度为1，机器人拍照位姿的位置为6，长度为6，则位置4和5空缺。若将机器人拍照位姿的位置修改为4，便可消除该空缺位置。建议通过修改位置，消除不必要的空缺位置。
-
若Mech-Viz工程中存在多个消息分支，你可预留出其他分支编号位置，以及对应的出口号位置，然后对Adapter程序进行二次开发。
-
-
完成上述配置后，单击 预览，将根据配置项生成相应的指令示例。
在 指令预览 窗口，将鼠标的光标悬浮到字段名称上，字段名称及对应的数据将高亮显示。
设置Mech-Viz步骤参数（可选）
若需设置Mech-Viz步骤参数，则勾选 设置Mech-Viz步骤参数，从而配置“设置Mech-Viz步骤参数”指令。
-
选择是否勾选 与拍照指令合并。
“与拍照指令合并”是指设置Mech-Viz步骤参数写在拍照指令里，即在拍照指令的基础上添加设置的步骤参数。设置Mech-Viz步骤参数 指令可以与Mech-Viz拍照指令合并成一条指令，也可以单独作为一条指令（此时需在调用拍照指令之前被调用）。
-
若未勾选 与拍照指令合并，请根据下表说明配置“设置Mech-Viz步骤参数”指令，然后执行第二步。
名称
参数值
位置
长度
指令码
设置Mech-Viz步骤参数的指令码，默认为t，可修改。
固定为1
固定为1
-
若勾选 与拍照指令合并，则上述表格中的项目将复用拍照指令中的设置，接下来执行第二步。
-
-
选择步骤参数。
单击 选择步骤参数，在弹出的窗口中，根据以下操作选择步骤参数。
-
在 选择步骤 选项下，选择需设置的步骤。
-
在 选择参数 选项下，勾选步骤的参数名称。
-
单击 确认。
-
若勾选 设置Mech-Viz步骤参数，则必须选择步骤参数，否则将出现以下弹窗提示。
-
步骤和参数可选择多个。
-
若步骤参数值的数据类型为布尔，则使用1表示true，0表示false。
以上图中的设置为例，单击 确认 后，设置Mech-Viz步骤参数的指令如下图所示。
-
-
不同参数所占的字段位置切勿存在重叠。
-
若各参数所对应的位置间存在空缺，则默认使用0填充。建议通过修改位置，消除不必要的空缺位置。
-
-
完成上述配置后，单击 预览，将根据配置项生成相应的指令示例。
配置“Mech-Viz输出”
在 Mech-Viz输出 窗口，设置Mech-Viz返回给机器人或上位机的数据格式。具体配置项包括 位姿类型、发送的位姿个数、视觉点在路径中的位置、发送物体标签、运动方式MOVEJ/MOVEL 和 工具编号。
-
根据以下说明对配置项进行设置。
配置项
说明
位姿类型
可选择项：JPs、TCP，默认为TCP。
发送的位姿个数
Mech-Viz返回的数据中将携带本次返回的位姿个数，位姿个数将位于位姿数据前面。
视觉点在路径中的位置
Mech-Viz工程中“视觉移动”步骤对应的路径点在路径中的位置。
发送物体标签
Mech-Viz将转发Mech-Vision的labels端口数据。
运动方式MOVEJ/MOVEL
路径点的运动方式，1表示MOVEJ，2表示MOVEL。
工具编号
机器人在移动至路径点时所使用的末端工具编号。
若 基础设置 中旋转方式选择四元数，位姿类型选择TCP，则输出的每个位姿占据7个字段；位姿类型选择JPs，则输出的每个位姿占据6个字段。
-
完成上述配置后，单击 预览，将根据配置项生成相应的指令示例。确认无误后，单击 下一页，进入下一配置界面。
配置“状态码设置”
-
在 状态码设置 窗口，为指令处理的各种结果设置对应的状态码。
Adapter生成器默认支持7种状态码。你可根据需求增加或减少状态码。
-
减少状态码：将不同的状态码对应的值设置成相同数值。例如，将“非法指令”、“工程未加载”都设置成2。
-
增加状态码：修改Adapter代码，具体可参考此处。
-
-
完成上述配置后，单击 保存并生成。若弹出以下窗口，则表明以上配置正确，单击 是，保存所有配置。
部署Adapter程序
完成Adapter生成器配置后，按照如下步骤部署Adapter工程。
-
在Mech-Vision工具栏中，单击 机器人通信配置。
-
在 机器人通信配置 窗口，进行如下配置。
-
选择机器人，单击 下一步。
-
在 接口服务类型 下，选择 Adapter。
-
在 Adapter工程文件夹 下，单击
。在弹出的文件浏览器中，选择Adapter工程文件夹。 -
（可选）建议勾选 方案打开时自动打开接口服务。
-
单击 应用。
-
-
在Mech-Vision主界面，确认工具栏中的接口服务已开启。
至此，Adapter工程部署成功。
后续说明
完成以上全部配置后，在方案文件所在目录下，其中 communication 文件夹下的XX（XX表示Adapter工程名称）文件夹就是所生成的Adapter程序，文件结构如下所示。
communication
├─adapter_generator_config.json（Adapter生成器的配置文件）
│
└─XX（XX表示设置的Adapter工程名称）
├─XX_adapter.py（编写Adapter工程的文件，由Adapter生成器配置的参数生成）
├─XX_widget.py（编写图像化界面的文件，默认未启用Widget程序）
├─__init__.py（配置Adapter工程的文件，可配置是否启用Adapter程序和Widget程序）|
若需启用Widget程序，将__init__.py文件中的下行取消注释即可。 |
另外，你可以在生成的Adapter程序上进行二次开发，以实现更多复杂功能。例如，将“超时”的状态码设置为8，你需要在XX_adapter.py文件的如下行中添加相应代码。
status_code_dict = {ms.SUCCESS: 1, ms.INVALID_COMMAND: 2, ms.PROJECT_NOT_LOADED: 3,
ms.NO_POINT_CLOUD: 4, ms.NO_RESULT: 5, ms.PLAN_FAILED: 6,
ms.OTHER_ERROR: 7, ms.TIMEOUT: 8}在抛出“超时”异常时，使用如下代码。
raise AdapterError(ms.TIMEOUT)Adapter编程相关的内容，请参阅：