AUBO Developer

Appearance

插件开发指南（v1.1） ​

1 前言 ​

AuboCaps 为 AUBO 机器人的 ARCS 软件提供插件开发需要的所有接口与配置。用户可根据本手册提供的信息进行插件开发，加载到 ARCS 软件中，配合 AUBO 机器人，扩展机器人的功能。

1.1 ARCS 工作流程 ​

插件最终都是在示教器上运行，因此插件的部分功能（主要在程序节点中）需要配合示教器软件进行。

在 ARCS 软件架构中，主要有示教器和控制器两个部分。ARCS 软件与机械臂通过脚本进行沟通，其流程大体如下：

  1. 用户在线编程或者进行配置相关参数；
  2. 将程序或配置的参数记录至示教器中；
  3. 示教器产生脚本文件；
  4. 示教器将所有脚本文件一同发送给控制器；
  5. 控制器生成机器人控制语言，然后下发给机械臂，机械臂执行相关操作。

（插入流程图）

1.2 插件开发的主体任务 ​

由 ARCS 工作流程可知，插件开发的实质是为机械臂控制器提供来自插件的脚本。在示教器中，脚本源自安装节点和程序节点，因此插件开发的主体任务是完成插件的安装节点与程序节点模块。

1.2.1 安装节点 ​

安装节点主要负责配置该插件的各类参数，并保存这些配置。类似在使用相机时，需要配置相机的基本参数，如曝光时间、相机内参等，安装节点就负责设置这些参数。

需要注意的是，安装节点在程序中只实例化一次，这类似安装其他软件时，只需要安装一次。因为参数是一个全局的概念，之后的实体机操作均基于该参数，因此只需要实例化一次。此外，该特性也可以大大优化运行效率。

1.2.3 程序节点 ​

程序节点主要根据参数生成脚本，执行具体功能。比如机械臂移动到某一点的时候，在该点设置一个程序节点负责打开抓手；机械臂移动到另一个节点的时候，设置一个程序节点负责关闭抓手。

2 插件模板结构 ​

2.1 API ​

ARCS 提供 API 接口，用户可以在插件开发过程中直接调用，缩短开发时间。根据不同 API 在安装节点和程序节点中的使用限制，可以将 API 分为两大类：domain_api 和 aubo_cpa_api。其中 domain_api 中的 system_api、user_interface_api、application_api 均既可用于安装节点，又可用于程序节点。aubo_cpa_api 中的 program_api 仅可用于程序节点，installation_api 则仅可用于安装节点。domain_api 和 aubo_cpa_api 的具体描述请参考下图。

注意：各接口的详细信息请参见《附录：aubo_caps API》

2.2 API 使用概述 ​

在模板中，安装节点和程序节点中均包含 service、contribution 和 view 三个类。其中service 类是节点的服务，可以创建 contribution 和 view 类；contribution 类中包含与数据相关的内容，view 类则包含与界面相关的内容，具体信息如下所示：

  1. 安装节点 service 类的接口：

    getTitle、getIcon、createView、configureContribution、createInstallationNode

  2. 程序节点 service 类的接口：

    getTitle、getIcon、getId、createView、configureContribution、createNode

  3. 安装节点 contribution 类中的 api_provider_ 接口：

    systemApi、 userInterfaceApi、installationApi

  4. 程序节点 contribution 类中的 api_provider_ 接口：

    systemApi、userInterfaceApi、programApi

  5. 安装节点和程序节点 view 类中 view_api_ 接口：

    systemApi、userInterfaceApi

  6. DataModel 存取数据：

    1. 配置数据一般保存在【/root/arcs_ws/program】文件夹下，当 aubo_scope 启动时，保存的配置数据会加载到 DataModel 中。
    2. 接口 DataModelPtr model_{ nullptr } 在 installation 和 program 中分别提供了一个。该接口可以将该项数据存放到 DataModel 中（但目前只提供部分数据类型，详情请参见《附录：aubo_caps API》）。
    3. 接口 DataModelPtr model_{ nullptr } 使用方式：
      1. 添加头文件 #include "aubo_caps++/meta_type.h"。
      2. 在 contribution 类的 private 区域添加 DECLARE_ATTR(名称，类型，初始值)。

3 插件开发流程 ​

3.1 环境配置 ​

  1. 软件环境：

    分类名称推荐版本
    操作系统Ubuntu16 及以上
    软件QT Creator5.0.0 及以上
    软件配置QT5.12.9 及以上
    软件配置GCC7.5 及以上

  2. 打开终端，进行以下操作，安装 aubo_caps：

    git clone http://git.aubo-robotics.cn:8001/aubo_plus/template.git
cd template
chmod +x ./INSTALL.sh
./INSTALL.sh

  3. 操作完成以后，可以进行以下操作查看是否操作成功：

    • 打开 QT Creator，单击【文件 > 新建文件或项目】。

    • 弹框中选择【Library】，查看是否存在 aubo_caps。

    • 如果没有 aubo_caps ，请尝试重新进行第 2 步操作。

3.2 新建插件工程 ​

  1. 打开 QT Creator，单击菜单栏【文件 > 新建文件或项目】。

  2. 在【新建文件或项目】的向导中单击【Library > aubo_caps】，单击【Choose】。

  3. 设置新工程的名称及保存路径，单击【下一步】。

  4. 设置工程详细信息：厂商名字（Vendor name）、邮箱（Email）、工程描述（Description）、官网链接（URL），单击【下一步】。

  5. 选择编译系统，单击【下一步】。目前仅支持 CMake。

  6. 选择编译工具链，单击【下一步】。选择 Qt 5.12.9 + gcc7.5 工具链。

  7. 检查添加到工程的文件，单击【完成】。

3.3 编译工程 ​

  1. 单击工程名字，右键弹出下拉菜单，单击【执行 CMake（Run CMake）】。

    • CMake 将联网下载依赖，因此这一步要求开发设备必须联网；
    • 根据网络连接情况，CMake 过程会持续一段时间。

  2. CMake 完成之后即可对该工程进行编译，单击工程名字，右键弹出下拉菜单，单击【构建（Build）】。

3.4 工程内添加新节点 ​

  1. 菜单栏单击【文件 > 新建文件或工程】，在【新建文件或项目】的向导中单击【aubo_caps > Aubo installation/program Node】，单击【Choose】。

  2. 设置安装/程序节点名称（Installation/Program Node name）。

  3. 单击【浏览（Browse）】设置节点路径。在【src】文件夹下新建文件夹【installation】或【program】，单击【打开（Open）】选择文件夹。单击【下一步】。

    • 安装节点对应【installation】文件夹，程序节点对应【program】文件夹。

  4. 选择节点类型，单击【下一步】。

  5. 检查将要添加到工程的文件列表，单击【完成】。

  6. 添加节点后，需对【CMakeLists.txt】和【activator.cpp】进行相应的配置：

    1. 在【CMakeLists.txt】中添加节点源码。由于在【src】文件夹下已经创建【installation】文件夹或【program】文件夹，因此将下面对应的语句取消注释（删除前面的 "#"）即可。

      ...
## file(GLOB_RECURSE install_src "src/installation/*")
## file(GLOB_RECURSE program_src "src/program/*")
...

    2. 在【activator.cpp】中添加响应语句。

      1. 将对应的服务类头文件引入。

        #include "program/firstnode_program_node_service.h"

        <img class="img-center" src="./pics/qtcreator-cpp-add-include.png"style="width:40em;">

      2. 取消对应需要注册的节点类型的注释，修改类名。

  7. 单击工程名字，右键弹出下拉菜单，单击【构建（Build）】。

4 插件打包与加载 ​

示教器软件第一次载入某个插件时，需先在开发环境下将插件打包成 zip 文件，然后将打包后的文件拷贝至示教器软件指定路径下，打开示教器软件加载插件，方可使用插件。

插件载入示教器软件后，如果需要更新，只需要更新【.../arcs_ws/extensions】文件夹下对应插件的内容即可，具体内容请参见 “5. 插件调试”。

4.1 准备工作 ​

插件中的 package.json 文件用于描述插件信息，其包含的字段如下：

json
"name": "plugin_name", # 插件名称
"displayName": "plugin_name", 
"group": "aubo_scope",
"description": "Visual localization plugin",
"version": "0.1.0",
"publisher": "aubo-robotics",
"url": "https://www.aubo-robotics.com",
"email": "aubo_developer@aubo-robotics.com",
"license": "aubo",
"icon": "", 
"api_version": "0.6.0" # 插件当前使用的 api 版本

其中，api_version 用于表示开发当前插件所使用的 aubo_caps_interface 版本，是打包前必须添加的字段。示教器软件会验证当前插件所用的 api 版本，若所用的版本大于示教器软件所支持的版本，将无法加载插件（可通过升级示教器软件版本解决无法加载问题）。若 api_version 为空可能会因为兼容问题导致插件不可用。

4.2 插件打包 ​

  1. 插件开发环境下，打开终端，运行以下指令，通过执行【deploy,sh】脚本进行打包。

    cd <工程根目录>
chmod +x ./deploy.sh
./deploy.sh

## 插件将生成在 build 目录

  2. 脚本运行成功后，【build】文件夹中将创建一个 zip 文件，即打包成功。

4.3 插件加载与卸载 ​

请参见 示教器插件的加载与卸载 。

5 插件调试 ​

请参见 示教器插件调试方案 。

6 插件与资源文件 ​

请参见 插件资源加载方式说明 。

7 插件与 ARCS 内置键盘 ​

请参见 示教器内置键盘使用说明。

8 插件翻译 ​

请参见 插件翻译文件使用说明 。

9 RPC 接口 ​

请参见 RPC 接口使用说明 。

附录：AuboCaps API 总览 ​

本文将详细介绍各类API的功能，读者可以通过浏览本文对 aubo_scope API 系统有个整体把握，在 aubo_caps 开发过程中能更好的使用这些API。

1 域 API ​

1.1 系统 API (systemApi) ​

  • getmajorVersion(): 获取软件的主要版本。
  • getMinVersion(): 获取软件的最小版本。
  • getBugfixVersion(): 获取软件的 bug 修复版本 。
  • getBuildNumber(): 获取软件的内部版本号。
  • getLocale(): 获取本地语言。
  • getlocale for Programming Language(): 获取系统设置语言。
  • getUnitType(): 获取系统当前的单位类型。
  • getSerialNumber(): 获取机器人的序列号。
  • isRealRobot(): 如果控制的是真实物理机器人返回 true，如果是模拟的返回 false

获取最大位置的关节弧度。

  • getJointMaxPositions(): 获取关节最大位置。
  • getJointMinPositions(): 获取关节最小位置。
  • getJointDefaultVelocity(): 获取关节默认速度。
  • getJointDefaultAcceleration(): 获取关节默认的加速度。
  • getJointMaxVelocity(): 获取关节最大速度。
  • getJointMaxAcceleration(): 获取关节最大加速度。
  • getTcpDefaultVelocity(): 获取 TCP 的默认速度。
  • getTcpDefaultAcceleration(): 获取 TCP 的默认加速度。
  • getTcpMaxVelocity(): 获取 TCP 的最大速度。
  • getTcpMaxAcceleration(): 获取 TCP 的最大加速度。
  • getTcpMaxDistance(): 获取 TCP 的最远距离。
  • getMaxPayloadMass(): 获取最大有效载荷的质量。
  • getMaxPayloadDistance(): 获取最大有效载荷的距离。
  • getHomeDefaultPosition(): 获取 home 默认位置。
  • getHomePackagePosition(): 获取 home paceage 位置。
  • getRobotDhParams():获取机器人 Dh 参数（连杆）。
  • getMaxPower(): 获取最大力。
  • getMinPower(): 获取最小力。
  • getMaxMomentum(): 获取最大动量。
  • getMinMomentum(): 获取最小动量。
  • getMaxStoppingTime(): 获取最大的 stop 时间。
  • getMinStoppingTime(): 获取最小的 stop 时间。
  • getMaxStoppingDistance(): 获取最大的 stop 距离。
  • getMinStoppingDistance(): 获取最小的 stop 距离。
  • getMaxToolForce(): 获取工具的最大力。
  • getMinToolForce(): 获取工具的最小力。
  • getMaxElbowSpeed(): 获取最大的肘部速度。
  • getMaxElbowForce(): 获取最大的肘部力量。
  • getMinElbowForce(): 获取最小的肘部力量。
  • getStandardDigitalInputConfigure(): 获取标准的数字输入配置。
  • getToolDigitalInputConfigure(): 获取 Tool 的数字输入配置。
  • getConfigureableDigitalInputConfigure(): 获取 configureable 的数字输入配置。
  • getStandardDigitaloutputConfigure(): 获取标准的数字输出配置。
  • getToolDigitaloutputConfigure(): 获取 Tool 的数字输出配置。
  • getConfigureableDigitaloutputConfigure(): 获取 configureable 的数字输出配置。
  • getStandardAnalogoutputConfigure(): 获取标准的模拟输出配置。
  • getToolAnalogoutputConfigure(): 获取 Tool 的模拟输出配置。
  • getStandardAnaloginputConfigure(): 获取标准的模拟输入配置。
  • getToolAnaloginputConfigure(): 获取 Tool 的模拟输入配置。
  • getStaticSafetyInputConfigure(): 获取安全系统配置的输入值。
  • getStaticSafetyoutputConfigure(): 获取安全系统配置的输出值。
  • getStaticLinkInputConfigure():获取 Link 输入配置。
  • getStaticLinkOutputConfigure():获取 Link 输出配置。

1.2 应用程序 API (applicationApi) ​

  • getIoModel(): 获取机器人 IO 数据。
  • getFeatureModel(): 获取机器人环境坐标系配置信息。
  • getTcpModel(): 获取机器人工具中心点的所有配置。
  • getPayloadModel(): 获取机器人末端执行器的有效负载配置信息。
  • getVariableModel(): 获取所有的程序变量和表达式信息。
  • getValueFactory(): 创建复杂的变量以及表达式。
  • getDeviceManager(): 提供设备管理器接口，访问所有已注册的设备。

1.3 用户界面 API (userInterfaceApi) ​

getUserInteraction(): 提供请求输入功能的接口，这些接口如下所示：

getUserDefinedRobotPosition():  要求用户去定义机器人位姿,并返回该位姿

getRobotThumb(): 获取机器人缩略图；

getKeyboardInputFactory()：创建各类键盘

requestUserToMoveJoint(): 根据用户要求位姿去移动关节

2 安装 API ​

安装 API 是对应用程序 API 的扩展，因此首先它具有应用程序 API 的所有功能，其次扩展的 API 功能如下：

  • getFunctionModel(): 为 aubo_scopet 提供脚本函数。
  • getTcpContributionModel(): 创建、配置、获取、更新 TCP。
  • getFeatureContributionModel(): 创建、配置、获取、更新 Feature。
  • getPayloadContributionModel(): 创建、配置、获取、更新 Payload。

3 程序 API ​

Program API 是服务于程序域中的程序节点，而程序节点可能需要获取有关机器人的系统信息（例如序列号，软件版本）这涉及到 System API 的访问，因此 Program API 中提供了对 System API 访问的接口 getSystemApi() 程序节点还可能需要与用户交互的功能，这涉及到 UserInterface API 的访问，因此 Program API 中提供了对 UserInterface API 访问的接口 getUserInterfaceApi()。而 Program API 还提供了仅在程序域中才有意义的API,这些API功能如下：

getProgramModel()：在这个接口中有以下功能可使用。

getProgramNodeFactory();   //创建各类程序节点（包括已经注册的插件提供的程序节点）
getTreeNode(ProgramNodeContribution *root); //在程序树中添加、删除、移动子节点

getWaypointModel()：创建、配置路点信息。

getUndoRedoManager(): 记录程序节点可撤销更改。

4 节点数据 ​

4.1 程序节点 ​

  • getId(): 获取程序节点的唯一标识符。
  • getTitle(): 获取程序节点在程序树上应显示的文本。
  • getIcon(): 获取程序节点在程序树上应显示的图标的资源路径。
  • configureContribution(): 为 Contribution 设置配置项。
  • createView(): 为程序节点创建相应界面。
  • createNode(): 为程序节点创建 Contribution。

4.2 安装节点 ​

  • getTitle(): 获取安装节点在界面上应显示的名字。
  • getIcon(): 获取安装节点在界面上应显示的图标的资源路径。
  • configureContribution(): 为 Contribution 设置配置项。
  • createView(): 为安装节点创建相应界面。
  • createInstallationNode(): 为安装节点创建 Contribution。

4.3 DataModel ​

  • get(): 获取指定键对应的值。
  • set(): 设定指定键对应的值。
  • getKeys(): 获取所有的键。
  • remove(): 移除一项指定的键值。