URCap manifest

manifest.yaml

All URCapX files must provide a manifest.yaml file to identify itself as a URCap. The metadata in the manifest file provides id and name for the URCap and one or more artifacts.

All manifest.yaml files must contain the following Vendor and URCap fields in the metadata section:

vendorID : The id to identify the vendor or company.

vendorName : The name of the vendor or company.

urcapID : Is used to identify a URCap.

urcapName : Defines the name of a URCap.

version : The version of the URCap.

The fields vendorID and urcapID in combination uniquely defines an ID for the URCap. They must only contain letters, digits and hyphens. The fields vendorName, urcapName and versionare used for presentation.

Web Contributions

The following example is the manifest file for the “Grip Distance” URCap

metadata:
  vendorID: universal-robots
  vendorName: "Universal Robots"
  urcapID: gripdistance
  urcapName: "Grip Distance"
  version: 1.0.0
artifacts:
  webArchives:
    - id: gripdistance
      folder: gripdistance

Fields required for a web frontend artifact are:

webArchives : Specifies the type of artifacts. The artifacts are a list if web-archives.

id : The name to identify the artifact. All artifacts must have a name.

folder : Defines a folder to this specific artifact and is part of a unique path to the artifact.

In this example the URCap name is `Grip Distance’ and it contains an artifact with the name ‘gripdistance’. A manifest file could also contain more artifacts, each with its own artifact name.

Docker Container

If a Docker Container is included then an artifact entry for that needs to be added, like in this sample manifest.yaml file:

metadata:
  vendorID: universal-robots
  urcapID: sample-docker
  version: 0.0.1
  vendorName: Universal Robots
  urcapName: Sample Docker Contribution
  contactInfo: Energivej 25, 5260 Odense S, Denmark
  description: Daemon Sample URCap
  copyright: Copyright (c) 2009-2021 Universal Robots. All rights reserved.
  licenseType: Sample license
artifacts:
  containers:
    - id: sample-docker-backend
      image: sample-docker-backend
      ingress:
        - id: rest-api
          containerPort: 5000
          protocol: http
          proxyUrl: /
      mounts:
        - mount: mount-type:/mount
      devices:
        - device: ttytool:/dev/ur-ttylink

containers Specifies a list of container contributions. Container contributions have the following fields:

id : The name to identify the artifact. All artifacts must have a name.

image : The name of the docker image.

ingress : A list of container network configurations, each configuration consists of: name, port, protocol and proxyUrl. The service configured in the ingress will be reachable at a URL defined using this template: <vendorID>/<urcapID>/<container-name>/<ingress-name>. In the above example the REST endpoint can be accessed at: universal-robots/sample-docker/sample-docker-backend/rest-api. The docker container will receive the requests on port 5000 at location “/”. * id: Used to reach the service or websocket. * containerPort: Container port of the http server in the container. * protocol: Specifies the communication protocol. Supported values are “http” (default), “https” or “websocket”. * proxyUrl: Specifies the URL being forwarded to. mounts : List of volumes (mounts) that will be available in the docker container and is set by choosing the type of mount, and a path.

devices : Mapping a list of host devices (device) to docker container device. This example will make the tool serial port “/dev/ur-ttylink” available inside the contributed docker container.

ROS2

If ROS2 is included it will have to reside in a container. Therefore, the artifact type must be containers and all the container yaml parameters can be used as described above.

Program nodes, Application nodes, SmartSkills, SidebarItems and OperatorScreens

Items of type Program node, Application node, SmartSkill, SidebarItem and OperatorScreen are contributions that belong to a web-archive. Any contributed item in a web-archive must identify itself as an item using a file called ‘contribution.json’ that must be placed in the ‘src’ folder. The contribution.json files syntax is defined below.

As an example is here a ‘contribution.json’ file for the gripdistance sample. This sample defines one of all type of contributions.

{
   "applicationNodes": [
     {
       "translationPath": "assets/i18n/",
       "behaviorURI": "gripdistance-application.worker.js",
       "presenterURI": "main.js",
       "componentTagName": "ur-sample-gripdistance-application"
     }
   ],
   "programNodes": [
     {
       "excludeFromToolbox": false,
       "translationPath": "assets/i18n/",
       "iconURI": "assets/icons/gripdistance.svg",
       "behaviorURI": "gripdistance-program.worker.js",
       "presenterURI": "main.js",
       "componentTagName": "ur-sample-gripdistance-program"
     }
   ],
   "smartSkills": [
    {
      "name": "ur-grip-distance-cc",
      "iconURI": "assets/icons/gripdistance.svg",
      "presenterURI": "main.js",
      "componentTagName": "ur-sample-gripdistance-smartskill",
      "behaviorURI": "gripdistance-smartskill.worker.js",
      "translationPath": "assets/i18n/"
    }],
  "sidebarItems": [
    {
      "name": "ur-grip-distance-vv",
      "iconURI": "assets/icons/grip-distance.svg",
      "presenterURI": "main.js",
      "componentTagName": "ur-sample-gripdistance-sidebaritem",
      "behaviorURI": "gripdistance-sidebaritem.worker.js",
      "translationPath": "assets/i18n/"
    }],
  "operatorScreens": [
    {
      "translationPath": "assets/i18n/",
      "behaviorURI": "gripdistance-operatorscreen.worker.js",
      "presenterURI": "main.js",
      "componentTagName": "ur-sample-gripdistance-operatorscreen"
    }]
}

The “programNodes” part contains the fields:

excludeFromToolbox : This method is used to control if the contributed program node should be visible in the tool box.

translationPath : Points to the folder with the translation files. These are json files for all languages supported, like ‘en.json’ for english. All program nodes that is to be shown in the program tree should at least provide translations for the program node name. This is done using the key: “program.tree.nodes”. In this example the full key would be “program.tree.nodes.ur-sample-gripdistance-program”. Application contributions use the key: “application.nodes”, like “application.nodes.ur-sample-gripdistance-application”, and consists of an object with “title” and “supportiveText” properties to be shown when presenting the node. Translation keys should also be used in the frontend presenters and translations for these keys should be added as well.

iconURI : The URI to the icon for the program tree node. The icon should be a svg file for scalability, but other formats are also supported like png, jpg etc.

behaviorURI : The URI to behavior for the program contribution. The behavior file is a javascript file containing the factory of the node and behaviors like URScript generation, rules and validation.

presenterURI : The URI to presenters for this contribution. This is a javascript file containing the custom web components for the user interface.

componentTagName: : The tag name of the custom web component contributed.

categoryName: : The category to place the program node in. This will result in proper coloring of the node in the program tree and the toolbox. If no category is provided, the node will be placed in the “default” category.’ : Available categories are: : “move”, “logic”, “structure”, “tool”, “operator”, “comment”

The other types contain mostly the same fields as program node.

See How to create a Frontend Contribution for examples of the translation files, pointed to by the translationPath.

The “applicationNodes” part is very similar except that an application node does not provide an icon and does not have the option “excludeFromToolbox”.

Note

The web frontend contribution must also contain a custom web component (here called ‘gripdistance-program’) and register that using the method:

window.customElements.define('ur-sample-gripdistance-program', GripDistanceProgramComponent);

if javascript is used. If using Angular then the following is needed to register a program component:

ngDoBootstrap() {
  const gripDistanceProgramComponent = createCustomElement(GripDistanceProgramComponent, { injector: this.injector });
  customElements.define('ur-sample-gripdistance-program', gripDistanceProgramComponent);
}

Installing/Uninstalling URCaps

The SDK comes with a sdk-utils npm package, containing various helper functionalities for URCaps. This enables you to install and uninstall URCaps using the NPM commandline tools. To use the NPM package, add @universal-robots/urcap-utils to the devDependencies element in package.json (it is included by default in URCaps created with the URCap Generator)

Building

When building your URCap for the first time or if any package dependencies have changed you need to run

npm install

Then afterward you can build the URCap with

npm run build

And now you are ready to test the URCap either in the simulator or on a robot.

Installing

To install a URCap, use the following command

npm run install-urcap -- [--host <HOST_IP>] [--port <PORT>] [--force-replace]

This will install the URCap in PolyScope X. If you are running the simulator on a different port, you can specify it by using the -- --port <PORT> parameter (NB: notice the -- in front of the --host/--port/--force-replace parameters; this is NPM’s way of adding parameters to an npm run command). If a URCap with the same VendorId and URCapId exists this will be updated, thus preserving any persisted data. If you wish to completely remove the existing URCap before installing the new version, use the --force-replace flag. To see the changes in PolyScope X, it is necessary to refresh the browser, once the URCap is installed.

If no --host parameter is given to install-urcap or delete-urcap, it will default to the Docker gateway IP which means it will be installed/deleted in the currently running simulator.

Example DevContainer

You have started the simulator and created a URCap named my-urcap and built it so a target/my-urcap.urcapx file exists. Then the command would be

npm run install-urcap 

Example Robot

You have a robot with the IP address 192.168.2.80, and have created a URCap named my-urcap and built it so a target/my-urcap.urcapx file exists. Then the command would be

npm run install-urcap -- --host 192.168.2.80 

Uninstalling

Uninstalling a URCap is similar to installing; simply use the following command

npm run delete-urcap <VENDOR_ID> <URCAP_ID> [-- --host <HOST_IP>] [-- --port <PORT>]

As when installing, it is necessary to refresh the browser to see the changes in PolyScope X.

Example

The simulator has a URCap installed, with vendorID: my-vendor and urcapID: my-urcap. Then the command would be

npm run delete-urcap my-vendor my-urcap