Capabilities
Universal Robots A/S
Version 1.14.0
Abstract
As of URCap API version 1.7, the concept of capabilities supported by the underly-
ing robot/system is introduced for version 3.10.0/5.4.0 of PolyScope. This document will
describe how to work with this capability concept.
Copyright c 2009-2023 by Universal Robots A/S, all rights reserved
Capabilities 1 Version 1.14.0
0 Contents
Contents
1 Introduction 3
2 How to Query for a Capability 3
3 Which API Areas Require Capability Checks 3
4 Code Example 4
Copyright c 2009-2023 by Universal Robots A/S, all rights reserved
Capabilities 2 Version 1.14.0
3 Which API Areas Require Capability Checks
1 Introduction
A capability is a system feature which may or may not be present on a given robot system. The
feature can be hardware-based or software-based, such as certain types of program nodes. It can
be available on the robot system depending on its generation, specific robot type or purchased
options.
2 How to Query for a Capability
When using areas of the URCap API where a given method or interface is referring to a ca-
pability, it must first be verified whether the capability is available using the CapabilityManager
interface. After successful verification, the aforementioned method or interface can be used.
Failing to do so will result in a CapabilityNotSupportedException being thrown, if the capability is
not present on the robot system.
3 Which API Areas Require Capability Checks
All capabilities are Java enums implementing the Capability marker interface. They are located
in sub-packages of the com.ur.urcap.api.domain.system.capability package.
Copyright c 2009-2023 by Universal Robots A/S, all rights reserved
Listing 1 shows an example of the declaration of such a capability enum (representing Tool I/O
Interface capabilities) located in the tooliointerface sub-package.
Listing 1: Example of a declaration of a Capability enum
1 public enum T o o l I O C a p a b i l i t y implements Capability {
2
3 /* *
4 * <p >
5 * Capability to configure the analog inputs in the tool to be used as a
Tool Communication Interface ( TCI )
6 * </p >
7 *
8 * Note : This functionality is not available on CB3 robots
9 */
10 COMM UNICATIO N_INTERF ACE_MOD E ,
11
12 /* *
13 * <p >
14 * Capability to configure output mode of the digital outputs in the tool
15 * </p >
16 *
17 * Note : This functionality is not available on CB3 robots
18 */
19 DIGITAL_OUTPUT_MODE
20
21 }
Another way is to inspect the Javadoc and annotations of a method or entire interface. This will
state whether or not it is necessary to check beforehand, if the capability (that is not guaranteed
to be available on all systems) is present on the underlying system.
If a method or interface requires an availability check, the RequiredCapability annotation will
mention which specific type of enum to use with the hasCapability(Capability) method in the
Capabilities 3 Version 1.14.0
4 Code Example
interface. If the annotation is on an interface, then an availability check should
CapabilityManager
be performed before using any of the methods in that interface.
An example of a method annotated with RequiredCapability is shown in Listing 2 (in this case
for the Tool Output Mode feature of the Tool I/O Interface). Listing 3 shows an example of an
interface with the RequiredCapability annotation.
Listing 2: Example of a method with the RequiredCapability annotation
1 public interface To o lI OI nt e rf ac e {
2 ...
3 @RequiredCapability ( DIGITAL_OUTPUT_MODE )
4 D i g i t a l O u t p u t M o d e C o n f i g g e t D i g i t a l O u t p u t M o d e C o n f i g () ;
5 ...
6 }
Listing 3: Example of an interface with the RequiredCapability annotation
1 @RequiredCapability ( DIGITAL_OUTPUT_MODE )
2 public interface D i g i t a l O u t p u t M o d e C o n f i g F a c t o r y {
3 ...
4 }
Below in Table 1 is a list of capabilities in the URCap API as of version 1.14.
Copyright c 2009-2023 by Universal Robots A/S, all rights reserved
Capability enum Interface Method
ProgramNodeCapability
SCREWDRIVING ScrewdrivingNode all methods
SCREWDRIVING ProgramNodeFactory createScrewdrivingNode()
ToolIOCapability
DIGITAL_OUTPUT_MODE ToolIOInterface getDigitalOutputModeConfig()
DIGITAL_OUTPUT_MODE ToolIOInterfaceControllable setDigitalOutputModeConfig(...)
DIGITAL_OUTPUT_MODE ToolIOInterfaceControllable getDigitalOutputModeConfigFactory()
DIGITAL_OUTPUT_MODE DigitalOutputModeConfigFactory all methods
COMMUNICATION_INTERFACE_MODE CommunicationInterfaceConfig all methods
COMMUNICATION_INTERFACE_MODE AnalogInputModeConfigFactory createCommunicationInterfaceConfig(...)
Table 1: Capabilities in URCap API version 1.14
4 Code Example
Below in Listing 4 is an example of how to check if the Tool Communication Interface (TCI)
feature is available on the underlying robot system. If this capability is present, a configuration
of this interface is applied.
Note that to configure the TCI feature, it is required to have exclusive control of the Tool I/O
Interface (not shown in this example). This is described in the document Resource Control .
Listing 4: Checking the availability of a system capability
1 ...
2 C a p ab i l i t y M a n a g e r c a p a b i l i t y M a n a g e r = apiProvider . getSystemAPI () .
g e t C a p a b i l i t y M a n a g e r () ;
Capabilities 4 Version 1.14.0
4 Code Example
3
4 if ( c a p a b i l i t y M a n a g e r . hasCapability ( T o o l I O C a p a b i l i t y .
COMMUNICATION_INTERFACE_MODE )) {
5 A n a l o g I n p u t M o d e C o n f i g F a c t o r y factory =
6 c o n t r o l l a b l e I n s t a n c e . g e t A n a l o g I n p u t M o d e C o n f i g F a c t o r y () ;
7
8 C o m m u n i c a t i o n I n t e r f a c e C o n f i g config =
9 factory . c r e a t e C o m m u n i c a t i o n I n t e r f a c e C o n f i g ( baudrate , parity , stopbits ,
rxidle , txidle ) ;
10
11 c o n t r o l l a b l e I n s t a n c e . s e t A n a l o g I n p u t M o d e C o n f i g ( config ) ;
12 }
13 ...
Copyright c 2009-2023 by Universal Robots A/S, all rights reserved
Capabilities 5 Version 1.14.0
