1. URCap开发环境搭建

URCap（UR Capability）是优傲机器人（Universal Robots）为PolyScope示教器提供的插件机制。一个URCap本质上是一个符合特定目录结构与XML描述规范的压缩包，安装到示教器后可以扩展程序节点、安装配置、工具栏按钮或后台服务。要开发URCap，不能直接在真实机器人上反复试错，而应先在PC上搭建一套“仿真示教器 + SDK + Java构建工具”的本地开发环境。本章的目标是完成环境搭建，并让第一个Hello World URCap出现在URSim虚拟示教器中。

1.1 开发环境由哪些部分组成

URCap开发环境可以理解为四个相互配合的层次：仿真层、SDK层、构建层和IDE层。仿真层是URSim，它模拟真实控制柜与示教器，提供PolyScope界面和URCap安装入口；SDK层是URCap SDK，提供API、示例工程、Maven依赖和打包脚本；构建层是JDK与Maven，负责编译Java代码并生成.urcap文件；IDE层是Eclipse或IntelliJ IDEA，用于编写、调试和运行代码。四者关系如下：IDE调用Maven，Maven依赖SDK，SDK生成的URCap安装到URSim的PolyScope中运行。

1.2 安装URSim与PolyScope

URSim提供Linux和Windows两种发行方式。以Windows为例，从优傲官方支持站点下载对应PolyScope版本的URSim压缩包（例如URSim 5.14或与目标机器人一致的版本），解压到不含中文和空格的路径，如D:\ur\ursim-5.14。进入目录后运行start-ursim.bat，脚本会启动虚拟控制柜和PolyScope界面。首次启动时选择机器人型号（如UR5e），等待示教器加载完成。此时可以在“设置 → 系统 → URCap”中看到已安装的URCap列表，后续Hello World将出现在这里。

需要注意版本匹配：URCap SDK版本、URSim版本和PolyScope版本应尽量一致。若SDK为5.14而URSim为5.9，API可能不兼容，安装时会提示“URCap requires a newer PolyScope version”。建议在项目初期固定一个版本组合，例如PolyScope 5.14 + URCap SDK 1.14 + JDK 17。

1.3 安装URCap SDK与配置Maven

URCap SDK通常以压缩包形式提供，解压后包含api、samples、pom等目录。SDK中的API jar需要安装到本地Maven仓库，或者通过systemPath方式引用。推荐做法是进入SDK的api目录，执行以下命令将API安装到本地仓库：

mvn install:install-file ^
  -Dfile=urcap-api-1.14.0.jar ^
  -DgroupId=com.ur.urcap ^
  -DartifactId=api ^
  -Dversion=1.14.0 ^
  -Dpackaging=jar

随后在项目pom.xml中声明依赖：

<dependency>
  <groupId>com.ur.urcap</groupId>
  <artifactId>api</artifactId>
  <version>1.14.0</version>
</dependency>

Maven还需要配置maven-compiler-plugin指定Java版本，以及SDK提供的打包插件（通常为urcap-maven-plugin），用于把target/classes、manifest.xml、资源文件等组装成.urcap。若使用Eclipse，可通过“Import → Existing Maven Projects”导入SDK示例；若使用IntelliJ IDEA，直接打开pom.xml作为项目即可。

1.4 创建第一个Hello World URCap

Hello World URCap的最小结构包括：pom.xml、manifest.xml、一个继承URCap接口的主类，以及一个继承ProgramNodeService或InstallationNodeService的服务类。下面给出一个可在PolyScope中显示“Hello World”程序节点的示例。

主类HelloWorldURCap.java：

package com.example.helloworld;

import com.ur.urcap.api.contribution.URCap;
import com.ur.urcap.api.contribution.ProgramNodeService;
import java.util.Collection;
import java.util.Collections;

public class HelloWorldURCap implements URCap {
    @Override
    public Collection<ProgramNodeService> getProgramNodeServices() {
        return Collections.singletonList(new HelloWorldProgramNodeService());
    }
}

程序节点服务类HelloWorldProgramNodeService.java：

package com.example.helloworld;

import com.ur.urcap.api.contribution.ProgramNodeService;
import com.ur.urcap.api.contribution.program.ProgramNodeConfiguration;
import com.ur.urcap.api.contribution.program.CreationContext;
import com.ur.urcap.api.contribution.program.ProgramNodeView;
import com.ur.urcap.api.domain.ProgramAPI;

public class HelloWorldProgramNodeService implements ProgramNodeService {
    @Override
    public String getId() { return "hello-world"; }

    @Override
    public String getTitle() { return "Hello World"; }

    @Override
    public ProgramNodeView createView(CreationContext context) {
        return new HelloWorldProgramNodeView();
    }

    @Override
    public void configure(ProgramNodeConfiguration config, CreationContext context) {
        // 无参数配置
    }
}

视图类HelloWorldProgramNodeView.java负责在示教器上显示一个标签：

package com.example.helloworld;

import com.ur.urcap.api.contribution.program.ProgramNodeView;
import javax.swing.JLabel;
import javax.swing.JPanel;

public class HelloWorldProgramNodeView implements ProgramNodeView {
    @Override
    public JPanel createView() {
        JPanel panel = new JPanel();
        panel.add(new JLabel("Hello World from URCap!"));
        return panel;
    }
}

manifest.xml需要声明URCap的ID、版本、供应商和入口类：

<?xml version="1.0" encoding="UTF-8"?>
<manifest version="1.0">
  <id>com.example.helloworld</id>
  <version>1.0.0</version>
  <vendor>Example</vendor>
  <entryPoint>com.example.helloworld.HelloWorldURCap</entryPoint>
  <apiVersion>1.14.0</apiVersion>
</manifest>

1.5 打包与部署到虚拟示教器

在项目根目录执行mvn clean package。若配置正确，Maven会在target目录生成hello-world-1.0.0.urcap。这个文件本质是一个ZIP包，可以用解压工具查看内部结构，确认包含manifest.xml、com/example/helloworld/*.class以及依赖的API jar。

部署时，在URSim的PolyScope中进入“设置 → 系统 → URCap”，点击“+”选择该.urcap文件，确认安装。安装完成后重启示教器，新建程序，在“程序节点”列表中找到“Hello World”，拖入程序树。选中该节点，右侧应显示“Hello World from URCap!”。若未出现，检查PolyScope日志（~/.urcontrol/log或URSim控制台输出），常见原因是manifest.xml的entryPoint类名错误、API版本不匹配或缺少依赖jar。

1.6 环境验证清单