com.ur.urcap.api.contribution.driver.gripper

Interface GripperContribution

public interface GripperContribution

This interface defines an API for adding functionality for gripping devices to PolyScope.

Implementing this interface will create a program node contribution, an installation contribution and a toolbar contribution exposing gripper functionality to the end user. Note that the toolbar contribution is not supported on CB3 robots.

The program node contribution allows the end user to program grip and release actions. The configuration options available to the end user are based on the properties and capabilities supported by the gripper. As a minimum, all grippers must support "default" grip and release actions. All other capabilities are optional to support and can be registered when the configureGripper(GripperConfiguration, GripperAPIProvider) method is called.

The installation node contribution can be used, if any custom input from the end user is required to setup the gripper, e.g. specifying an IP address. The corresponding generated UI will be accessible in the installation node. This functionality is optional, since such configuration properties are specific for each gripper. Access to create a custom configuration based on user inputs is provided when the method configureInstallation(CustomUserInputConfiguration, SystemConfiguration, TCPConfiguration, GripperAPIProvider) is called. If no custom user inputs, texts, etc. are defined, the installation node will not be visible in PolyScope. Preamble script code (generated by generatePreambleScript(ScriptWriter)) will still be added to the robot program.

The toolbar contribution provides the end user quick access to perform grip and release actions using "default" gripper action parameters.

Since:

1.8.0

Method Summary

Modifier and Type	Method and Description
void	configureContribution(ContributionConfiguration configuration) When this method is called, optional PolyScope properties for this gripper contribution can be configured.
void	configureGripper(GripperConfiguration gripperConfiguration, GripperAPIProvider apiProvider) When this method is called, use the configuration parameter to register or setup optional properties and capabilities of the gripper.
void	configureInstallation(CustomUserInputConfiguration customConfiguration, SystemConfiguration systemConfiguration, TCPConfiguration tcpConfiguration, GripperAPIProvider apiProvider) When this method is called, required configuration related to the setup of the gripper can be defined/performed, e.g.
void	generateGripActionScript(ScriptWriter scriptWriter, GripActionParameters parameters) When this method is called, the script code for performing a grip action with the gripper must be generated.
void	generatePreambleScript(ScriptWriter scriptWriter) Generate script code that must be executed before any gripper actions can be performed (such as required initialization) when this method is called.
void	generateReleaseActionScript(ScriptWriter scriptWriter, ReleaseActionParameters parameters) When this method is called, the script code for performing a release action with the gripper must be generated.
String	getTitle(Locale locale) This method must return the title of the gripper contribution.

Method Detail

getTitle

String getTitle(Locale locale)

This method must return the title of the gripper contribution. The title is displayed in:

• The Structure section of the Program Tab for this type of gripper program node (from which the Gripper program node can be inserted)
• The program node screen for this gripper contribution.
• The Program Tree as title for the program node for this gripper contribution
• The left-hand side navigation of the Installation Tab for this gripper contribution.
• The installation node screen for this gripper contribution.
• The toolbar contribution for this gripper. Note: The toolbar contribution is not available on CB3 robots.

The return value of this method cannot be null nor an empty string.

This method is called once upon startup.

Parameters:

locale - The current locale of PolyScope. Can be used for supporting titles in several languages.

Returns:

The title of this gripper contribution, not null nor an empty string.

configureContribution

void configureContribution(ContributionConfiguration configuration)

When this method is called, optional PolyScope properties for this gripper contribution can be configured. The method is called once after this gripper contribution is registered.

Modify the configuration parameter to configure your contribution. The configuration object will already have default values for its properties.

The values of the contribution configuration object will be read once immediately after this method call. Changing values at a later stage will have no effect, so do not store a reference to the configuration object.

If the default values are appropriate, leave the implementation of this method empty.

Parameters:

configuration - A modifiable configuration instance with default values that can be used for configuring the PolyScope properties of this contribution

configureGripper

void configureGripper(GripperConfiguration gripperConfiguration,
                      GripperAPIProvider apiProvider)

When this method is called, use the configuration parameter to register or setup optional properties and capabilities of the gripper.

The method is called in the Gripper Configuration phase after this contribution has been registered when a new installation is loaded or created.

Note: If the gripper only supports basic "default" grip and release actions, leave the implementation of this method empty.

Parameters:

gripperConfiguration - A configuration instance that can be used for registering or setting up the properties and capabilities of the gripper.

apiProvider - Provides access to functionality and services available from within PolyScope which can be relevant for setting up the gripper capabilities (e.g. the SystemAPI interface with functionality for querying information about the robot).

configureInstallation

void configureInstallation(CustomUserInputConfiguration customConfiguration,
                           SystemConfiguration systemConfiguration,
                           TCPConfiguration tcpConfiguration,
                           GripperAPIProvider apiProvider)

When this method is called, required configuration related to the setup of the gripper can be defined/performed, e.g. defining custom user inputs, adding a TCP contribution for the gripper and configuring the settings of the Tool I/O Interface.

Note: If the multi-gripper capability has been registered (see GripperCapabilities.registerMultiGripperCapability(GripperListProvider)), then the TCPConfiguration parameter should not be used to add, remove or update a TCP. Instead use SystemConfiguration.getTCPConfiguration(SelectableGripper) (through the systemConfiguration parameter) to add a TCP for each individual gripper/zone (in the multi-gripper).

If no custom user inputs or texts etc. are defined the installation node will not be visible in PolyScope. Preamble script will still be added to the robot program.

The method is called in the Installation Configuration phase after this contribution has been registered when a new installation is loaded or created.

If no configuration is needed, leave the implementation of this method empty.

Parameters:

customConfiguration - Use this instance to register custom user inputs for setting up the gripper. The corresponding generated UI will be accessible in the installation node.

systemConfiguration - Use this instance to configure the robot system for this gripper, e.g. configure the Tool I/O interface settings

tcpConfiguration - Use this instance to add a TCP for this gripper to PolyScope as well as update the TCP's offset and remove the TCP again. A gripper contribution can only contribute one TCP to PolyScope unless it has registered the multi-gripper capability (see GripperCapabilities.registerMultiGripperCapability(GripperListProvider)). If that is the case, do not use this parameter. Instead use SystemConfiguration.getTCPConfiguration(SelectableGripper) (accessible through the systemConfiguration parameter) to add a TCP for each individual gripper/zone.

apiProvider - Provides access to functionality and services available from within PolyScope which can be relevant for defining the installation of the gripper (e.g. the PoseFactory interface which is needed for creating TCPs)

generatePreambleScript

void generatePreambleScript(ScriptWriter scriptWriter)

Generate script code that must be executed before any gripper actions can be performed (such as required initialization) when this method is called.

The method is called in several scenarios where the script code generated by this method is:

• Added to the beginning (preamble) of the script code executed when a robot program is run
• Prepended to the script code generated when the end user tests the configuration of a gripper program node
• Prepended to the script code generated when the gripper is operated using the toolbar

Note: Generating preamble script code is optional. Leave the implementation of this method empty, if execution of initialization script code is not needed.

Parameters:

scriptWriter - Use this script writer instance to generate the script code that must be executed before gripper actions can be performed

generateGripActionScript

void generateGripActionScript(ScriptWriter scriptWriter,
                              GripActionParameters parameters)

When this method is called, the script code for performing a grip action with the gripper must be generated.

The parameters for the registered optional gripper capabilities defined/configured by the end user are provided as input to the script generation.

The method is called in the following scenarios:

• When the script code for a gripper program node configured with a grip action should be generated as part of a robot program to be executed
• When the end user tests a grip configuration of a gripper program node
• When the gripper is operated using the toolbar

NOTE:

• Applying a new total payload after an object has been gripped is not the responsibility of the gripper, since this is automatically handled by PolyScope.

• When the end user has specified a new payload (in the Gripper program node or toolbar), the user-defined payload value will be applied by PolyScope immediately after the generated script code for the grip action has finished executing. Hence the script code should not finish earlier than when it is appropriate to apply the new payload value (i.e. when the object has been gripped). This typically means that the script code should wait a time period corresponding to closing the gripper's "fingers" fully (if the gripper is vacuum operated then long enough to achieve some level of vacuum).

  If the grip detected feedback capability has been registered (using GripperFeedbackCapabilities.registerGripDetectedCapability(ScriptCodeGenerator)), different script code should be generated depending on whether the end user has enabled or disabled the grip detection option (in the Gripper program node). For more details, see Javadoc for GripActionParameters.isGripDetectionEnabled().

Parameters:

scriptWriter - Use this script writer instance to generate the script code for gripping

parameters - The parameters for the gripper action defined/configured by the end user

generateReleaseActionScript

void generateReleaseActionScript(ScriptWriter scriptWriter,
                                 ReleaseActionParameters parameters)

When this method is called, the script code for performing a release action with the gripper must be generated.

The parameters for the registered optional gripper capabilities defined/configured by the end user are provided as input to the script generation.

The method is called in the following scenarios:

• When the script code for a gripper program node configured with a release action should be generated as part of a robot program to be executed
• When the end user tests a release configuration of a gripper program node
• When the gripper is operated using the toolbar

NOTE:

• Applying a new total payload after an object has been released is not the responsibility of the gripper, since this is automatically handled by PolyScope.

• When the end user has specified a new payload (in the Gripper program node or toolbar), the user-defined payload value will be applied by PolyScope immediately after the generated script code for the release action has finished executing. Hence the script code should not finish earlier than when it is appropriate to apply the new payload value (i.e. when the object has been released). This typically means that the script code should wait a time period corresponding to opening the gripper's "fingers" fully (if the gripper is vacuum operated then long enough to achieve some level of vacuum).

  If the release detected feedback capability has been registered (using GripperFeedbackCapabilities.registerReleaseDetectedCapability(ScriptCodeGenerator)), different script code should be generated depending on whether the end user has enabled or disabled the release detection option (in the Gripper program node). For more details, see Javadoc for ReleaseActionParameters.isReleaseDetectionEnabled().

Parameters:

scriptWriter - Use this script writer instance to generate the script code for releasing the gripper

parameters - The parameters for the gripper action defined/configured by the end user