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

Interface GripperCapabilities

@ProviderType
public interface GripperCapabilities

Register the physical capabilities of the gripper using this interface.

Method Summary

Modifier and Type	Method and Description
GripForceCapability	registerGrippingForceCapability(double minForce, double maxForce, double defaultGripForce, Force.Unit unit) Register a force capability for a gripper that supports gripping using a user configurable force.
GripVacuumCapability	registerGrippingVacuumCapability(double minVacuum, double maxVacuum, double defaultGripVacuum, Pressure.Unit unit) Register a vacuum capability for a gripper that supports gripping using a user configurable vacuum level.
MultiGripperCapability	registerMultiGripperCapability(GripperListProvider gripperListProvider) Register a multi-gripper capability for a gripper that supports a set of multiple individual grippers/zones (from which the end user can select an individual gripper/zone to operate).
SpeedCapability	registerSpeedCapability(double minSpeed, double maxSpeed, double defaultGripSpeed, double defaultReleaseSpeed, Speed.Unit unit) Register a speed capability for a gripper that supports operating using a user configurable speed.
WidthCapability	registerWidthCapability(double minWidth, double maxWidth, double defaultGripWidth, double defaultReleaseWidth, Length.Unit unit) Register a width/position capability for a gripper that supports moving to a user configurable position (open/close to a configurable width).

Method Detail

registerWidthCapability

WidthCapability registerWidthCapability(double minWidth,
                                        double maxWidth,
                                        double defaultGripWidth,
                                        double defaultReleaseWidth,
                                        Length.Unit unit)

Register a width/position capability for a gripper that supports moving to a user configurable position (open/close to a configurable width).

Parameters:

minWidth - The minimum width supported by the gripper

maxWidth - The maximum width supported by the gripper

defaultGripWidth - default value for the width for a grip action. This value is used for, e.g. performing a "default" grip action using the toolbar

defaultReleaseWidth - default value for the width for a release action. This value is used for, e.g. performing a "default" release action using the toolbar

unit - the unit for all specified values, not null

Returns:

a width capability allowing for dynamic adjustments of the capability properties including the value range and default values

Throws:

InvalidCapabilityRange - if minWidth > maxWidth

InvalidCapabilityRange - if defaultGripWidth or defaultReleaseWidth is outside the range defined by minWidth and maxWidth.

CapabilityAlreadyRegistered - if this capability has already been registered

CalledOutsideGripperConfigurationPhase - if this method is called at the wrong time by a URCap implementing the GripperContribution interface, i.e. called outside the scope of the configuration of the gripper.

CalledOutsideMethodScope - if this method is called at the wrong time by a (regular) URCap which has registered its program node contribution/service as conformant with a PolyScope gripper (using GripperRegistrationManager.registerAsGripper(Class)), i.e. called outside the scope of the call to either SwingProgramNodeService.configureContribution(ContributionConfiguration) (for a Swing-based URCap) or ProgramNodeServiceConfigurable.configureContribution(ProgramNodeConfiguration) (for a HTML-based URCap).

registerGrippingForceCapability

GripForceCapability registerGrippingForceCapability(double minForce,
                                                    double maxForce,
                                                    double defaultGripForce,
                                                    Force.Unit unit)

Register a force capability for a gripper that supports gripping using a user configurable force.

Parameters:

minForce - minimum force supported by the gripper

maxForce - maximum force supported by the gripper

defaultGripForce - default value for the force for a grip action. This value is used for, e.g. performing a "default" grip action using the toolbar

unit - the unit for all specified values, null

Returns:

a force capability allowing for dynamic adjustments of the capability properties including the value range and default value

Throws:

InvalidCapabilityRange - if minForce > maxForce or defaultGripForce is outside the range defined by minForce and maxForce.

CapabilityAlreadyRegistered - if this capability has already been registered

CalledOutsideGripperConfigurationPhase - if this method is called at the wrong time by a URCap implementing the GripperContribution interface, i.e. called outside the scope of the configuration of the gripper.

CalledOutsideMethodScope - if this method is called at the wrong time by a (regular) URCap which has registered its program node contribution/service as conformant with a PolyScope gripper (using GripperRegistrationManager.registerAsGripper(Class)), i.e. called outside the scope of the call to either SwingProgramNodeService.configureContribution(ContributionConfiguration) (for a Swing-based URCap) or ProgramNodeServiceConfigurable.configureContribution(ProgramNodeConfiguration) (for a HTML-based URCap).

registerSpeedCapability

SpeedCapability registerSpeedCapability(double minSpeed,
                                        double maxSpeed,
                                        double defaultGripSpeed,
                                        double defaultReleaseSpeed,
                                        Speed.Unit unit)

Register a speed capability for a gripper that supports operating using a user configurable speed.

Parameters:

minSpeed - minimum speed supported by the gripper

maxSpeed - maximum speed supported by the gripper

defaultGripSpeed - default value for the speed for a grip action. This value is used for, e.g. performing a "default" grip action using the toolbar

defaultReleaseSpeed - default value for the speed for a grip action. This value is used for, e.g. performing a "default" release action using the toolbar

unit - the unit for all specified values, not null

Returns:

a speed capability allowing for dynamic adjustments of the capability properties including the value range and default values

Throws:

InvalidCapabilityRange - if minSpeed > maxSpeed

InvalidCapabilityRange - if defaultGripSpeed or defaultReleaseSpeed is outside the range defined by minSpeed and maxSpeed.

CapabilityAlreadyRegistered - if this capability has already been registered

CalledOutsideGripperConfigurationPhase - if this method is called at the wrong time by a URCap implementing the GripperContribution interface, i.e. called outside the scope of the configuration of the gripper.

CalledOutsideMethodScope - if this method is called at the wrong time by a (regular) URCap which has registered its program node contribution/service as conformant with a PolyScope gripper (using GripperRegistrationManager.registerAsGripper(Class)), i.e. called outside the scope of the call to either SwingProgramNodeService.configureContribution(ContributionConfiguration) (for a Swing-based URCap) or ProgramNodeServiceConfigurable.configureContribution(ProgramNodeConfiguration) (for a HTML-based URCap).

registerGrippingVacuumCapability

GripVacuumCapability registerGrippingVacuumCapability(double minVacuum,
                                                      double maxVacuum,
                                                      double defaultGripVacuum,
                                                      Pressure.Unit unit)

Register a vacuum capability for a gripper that supports gripping using a user configurable vacuum level.

If the gripper works with absolute pressure, specify a positive range for the supported vacuum level. If the gripper works with relative pressure (vacuum), specify a negative range for the supported vacuum level.

Parameters:

minVacuum - minimum vacuum level supported by the gripper

maxVacuum - maximum vacuum level supported by the gripper

defaultGripVacuum - default value for the vacuum level for a grip action. This value is used for, e.g. performing a "default" grip action using the toolbar

unit - the unit for all specified values, not null

Returns:

a vacuum capability allowing for dynamic adjustments of the capability properties including the value range and default value

Throws:

InvalidCapabilityRange - if minVacuum > maxVacuum or defaultGripVacuum is outside the range defined by minVacuum and maxVacuum.

CapabilityAlreadyRegistered - if this capability has already been registered

CalledOutsideGripperConfigurationPhase - if this method is called at the wrong time by a URCap implementing the GripperContribution interface, i.e. called outside the scope of the configuration of the gripper.

CalledOutsideMethodScope - if this method is called at the wrong time by a (regular) URCap which has registered its program node contribution/service as conformant with a PolyScope gripper (using GripperRegistrationManager.registerAsGripper(Class)), i.e. called outside the scope of the call to either SwingProgramNodeService.configureContribution(ContributionConfiguration) (for a Swing-based URCap) or ProgramNodeServiceConfigurable.configureContribution(ProgramNodeConfiguration) (for a HTML-based URCap).

registerMultiGripperCapability

MultiGripperCapability registerMultiGripperCapability(GripperListProvider gripperListProvider)

Register a multi-gripper capability for a gripper that supports a set of multiple individual grippers/zones (from which the end user can select an individual gripper/zone to operate).

When this capability is registered, it is possible to support two use cases:

• A gripping device physically constructed in a way where it is logically partitioned in multiple zones/grippers ("built into" the device).
• A gripper URCap with the option of supporting a number of separate, identical grippers which can be mounted on the robot at the same time (for instance using a special mounting bracket). Typically the end user has the choice of using either a setup with a single gripper or one with multiple grippers.

Each of the individual grippers will have to support any other capability (e.g. the width capability) that has been registered with this interface, i.e. all the grippers will have the exact same set of capabilities. Note that it is a requirement for registering this capability that the grippers are identical in terms of their capabilities.
It possible to dynamically adjust properties (including the value range and default values) of each registered capability exclusively for each individual gripper (independently of the other grippers). This is typically not applicable for most grippers, but can be relevant when the range depends on another custom gripper setting (which can be configured by the user).
If an update of the properties of a capability needs to apply for all individual grippers, it is more convenient to perform the adjustment simultaneously for all grippers using the capability instance (e.g. WidthCapability) returned when the capability was registered (with this interface).

When this capability is registered, all potentially supported grippers must be added upfront, but can be created in an initial disabled state, and the full list of grippers must contain at least two grippers. Adding additional grippers at a later time is not possible.
It is, however, possible to enable and disable each gripper dynamically using MultiGripperCapability.setEnabled(SelectableGripper, boolean). This is useful, if the gripper URCap is meant to support both a use case with only a single gripper as well as supporting the option of mounting several separate, identical grippers on the robot at the same time. In this case, the secondary gripper(s) can be created in an initial disabled state, and then enabled when the end user is using a multi-gripper setup.

Other contributions (for example contributed by other 3rd party URCaps) will be able to select a specific individual gripper when creating a configuration for a GripperNode which is using this multi-gripper device.

The following is only relevant for URCaps implementing the GripperContribution interface:

• After registration of this capability, each (enabled) individual gripper will be selectable by the end user in the Gripper toolbar and program node (for this gripper device). This enables the end user to select which individual gripper or zone to operate.
• After each gripper has been created, it is possible to add an individual TCP for the gripper using the SystemConfiguration.getTCPConfiguration(SelectableGripper) method (accessible through the systemConfiguration parameter when GripperContribution.configureInstallation(CustomUserInputConfiguration, SystemConfiguration, TCPConfiguration, GripperAPIProvider) is called)

Parameters:

gripperListProvider - Provider of the list of all supported individual grippers/zones, not null. The implementation of GripperListProvider.getGripperList(GripperListBuilder, Locale) will be called once (by PolyScope) to retrieve the list.

Returns:

A multi-gripper capability instance providing access to functionality, such as, enabling/disabling individual grippers, access to all registered capabilities (e.g. the width capability) allowing for dynamic adjustment of their parameters exclusively for this specific gripper (independently of the other grippers), and access to the list of added grippers.

Throws:

CapabilityAlreadyRegistered - if this capability has already been registered

LessThanTwoGrippers - if null is returned (instead of a list) when PolyScope calls the implementation of GripperListProvider.getGripperList(GripperListBuilder, Locale).

CalledOutsideGripperConfigurationPhase - if this method is called at the wrong time by a URCap implementing the GripperContribution interface, i.e. called outside the scope of the configuration of the gripper.

CalledOutsideMethodScope - if this method is called at the wrong time by a (regular) URCap which has registered its program node contribution/service as conformant with a PolyScope gripper (using GripperRegistrationManager.registerAsGripper(Class)), i.e. called outside the scope of the call to either SwingProgramNodeService.configureContribution(ContributionConfiguration) (for a Swing-based URCap) or ProgramNodeServiceConfigurable.configureContribution(ProgramNodeConfiguration) (for a HTML-based URCap).