PolyScope X SDK user guide

Before starting make sure that you have gone through the setup which will help to get your development environment up and running.

This guide describes how to get started and use the URCap SDK which is released together with PolyScope X version Pre-Release.

The SDK can be used to develop URCaps to PolyScope X that are loaded when PolyScope X starts up. Currently, customized program nodes and application nodes can be developed and contributed to PolyScope X, as well as Docker container contributions.

The URCap along with its resources is packaged and distributed as a single zip-file with the .urcapx extension. A URCap can be run on a real robot, or it can be tested in the PolyScope X simulator (please consult the installation guide for the simulator).

Getting started

The two easiest ways to start developing an URCap:

  1. Create a new contribution project from a template using the URCap Contribution Generator.

  2. Base the new contribution on a modification of a sample, if it is reminiscent of one of the included samples.

The benefit of using one of these methods is that project build tools and metadata files will already be created.

Create URCap using the URCap Contribution Generator

The URCap Contribution Generator is an interactive tool that is executed by invoking newurcap.sh The tool will prompt the user for the type and name of the contribution to be created. See How to work with the URCap Contribution Generator for further details. The generated URCap project will include all source and metadata files needed by a complete URCap Contribution. The generated project also includes build tools and can therefore be built and installed immediately after being generated. The contribution metadata files can be edited at any time. See How to configure, package and install a contribution

URCap samples

The samples included in this SDK can be used as inspiration for how to create contributions or modified into customized URCaps. When basing a new URCap on a sample it is at a minimum a good idea to modify the contribution metadata to avoid clashes with installed samples see How to configure, package and install a contribution.

Samples included in the SDK are:

  • calibration-info

    • Demonstrates how to retrieve calibration information from the controller, from a Docker container contribution

  • datastorage

    • Demonstrates how to use different methods of storing data in a Docker container contribution

  • devices

    • Demonstrates how to communicate with a serial device from a Docker container contribution

  • gripdistance

    • Demonstrates how to create an application contribution for configuring the grip distance of a gripper.

  • macvlan

    • Demonstrates how to set up a virtual network interface in a Docker container contribution

  • rtde-sample

    • Demonstrates how to communicate with the RTDE interface of the controller, from a Docker container contribution

  • simple-docker

    • Demonstrates how to create a Docker container contribution and an application contribution that communicates with the container contribution.

  • simple-gripper

    • Demonstrates how to create a full gripper contribution. The sample is based on ROS2 communication and the tool serial interface for communicating with a physical gripper.

  • simple-rest

    • Demonstrates how to use REST based communication inside a URCap Contribution, between the Docker backend and the Web frontend.

  • simple-ros2-node

    • Demonstrates how to create a ROS2 node inside a Docker container contribution that communicates with the Controller using urinterfaces message types in Python.

  • simple-websocket

    • Demonstrates how to use websocket based communication inside a URCap Contribution between the Docker backend and the Web frontend

  • simple-xmlrpc

    • This sample contains an example of how to communicate from both URScript and the frontend with a backend using XML-RPC

  • xmlrpc-gripper

    • Demonstrates how to create a full gripper contribution. The sample is based on XML-RPC communication and the tool serial interface for communicating with a physical gripper.

  • ur-program-nodes

    • Collection of program nodes which are delivered with PolyScope X that illustrates how program-nodes have been developed at Universal Robots. These program nodes includes assignment, loop, move-to, set, tool-force and wait.

Build and install a URCap

A contribution based on the generator or a sample will include tooling for building and installing it in PolyScope X. In the contribution project navigate to the folder where package.json is located and then run:

npm install

The npm install command is only required the first time or when package dependencies have changed. Then build the contribution using:

npm run build

NOTE: Relevant for development environments running on ARM64

If the URCap has a container contribution, the container image produced by npm run build, will be an AMD64 image.

See page cpu-architecture for more about container compatibility here.

The URCap file, with the urcapx extension, is built and placed in the target folder.

npm run install-urcap

Will attempt to install the URCap in the simulator, this will only succeed if the simulator is running. It is possible to install or uninstall a URCap at any time using the sdk-utils. See section “Installing/Uninstalling contributions” in: How to configure, package and install a contribution.

Testing URCaps

URCaps are installed in the simulator by using the relevant scripts in the included utilities NPM package (see How to configure, package and install a contribution in the howtos folder for details).

Documentation and help

Upgrade URCap from SDK v0.11 to v0.12

This section describes how to upgrade a URCap project created with SDK v0.10 to the v0.11 SDK.

  • On the host copy the URCap project folder from SDK v0.10 to v0.11 cp -r polyscopex-old/sdk-polyscopex-old/myContribution polyscopex-new/sdk-polyscopex-new

  • Locate the new NPM dependencies here: sdk-polyscopex-new/urcap-generator/generators/web-docker/templates/angular/package.json.

  • If the URCap contains both frontend and backend contributions there will be a top level package.json:

    • Update the urcap-utils dependency.

  • If you have a frontend contribution:

    • Update sdk-polyscopex-new/myContribution/my-frontend/package.json

  • In sdk-polyscopex-new/myContribution/my-frontend/src/polyfills.ts change import ‘zone.js/dist/zone’; to import ‘zone.js’;

  • Run npm install in the URCap root folder: sdk-polyscopex-new/myContribution

Fix build steps in the top level package.json file:

  • Remove the previous “rename-to-urcapx” step

  • Fix package build step. It should be: “package”: “package-urcap dist target”