com.ur.urcap.api.domain.payload

Interface PayloadContributionModel

@ProviderType
public interface PayloadContributionModel

This interface provides functionality for adding, updating and removing payloads in PolyScope.

Note: This interface must only be used in an installation contribution.

Since:

1.13.0

Method Summary

Modifier and Type	Method and Description
Payload	addPayload(String idKey, String suggestedName, Mass mass, Position centerOfGravity) Add a payload to the current installation in PolyScope.
Payload	addPayload(String idKey, String suggestedName, Mass mass, Position centerOfGravity, InertiaMatrix inertiaMatrix) Add a payload to the current installation in PolyScope.
InertiaMatrix	createInertiaMatrix(double ixx, double iyy, double izz, double ixy, double ixz, double iyz, MomentOfInertia.Unit unit) Creates an inertia matrix to be used when adding a payload to the installation in PolyScope using the method addPayload(String, String, Mass, Position, InertiaMatrix), or updating an existing payload using updatePayload(String, Mass, Position, InertiaMatrix).
Payload	getPayload(String idKey) Returns the payload previously added by this URCap using the same idKey identifier.
void	removePayload(String idKey) Remove a payload added by this URCap from PolyScope.
void	updatePayload(String idKey, Mass mass, Position centerOfGravity) Update the mass and center of gravity (CoG) of an existing payload added by this URCap.
void	updatePayload(String idKey, Mass mass, Position centerOfGravity, InertiaMatrix inertiaMatrix) Update the mass, center of gravity (CoG) and inertia matrix of an existing payload added by this URCap.

Method Detail

createInertiaMatrix

InertiaMatrix createInertiaMatrix(double ixx,
                                  double iyy,
                                  double izz,
                                  double ixy,
                                  double ixz,
                                  double iyz,
                                  MomentOfInertia.Unit unit)

Creates an inertia matrix to be used when adding a payload to the installation in PolyScope using the method addPayload(String, String, Mass, Position, InertiaMatrix), or updating an existing payload using updatePayload(String, Mass, Position, InertiaMatrix).

The inertia matrix is defined in a coordinate system with center at the payload's center of gravity (CoG), also referred to as center of mass, and the axes aligned with the tool output flange coordinate system (axes). The center of gravity is defined as the offset between the center of the tool output flange and the center of gravity of the attached payload.

The inertia matrix is specified by the six component values for the moments of inertia (i.e. Ixx, Iyy, Izz) and products of inertia (i.e. Ixy, Ixz, Iyz).

Parameters:

ixx - The moment of inertia around the x-axis. Must be positive.

iyy - The moment of inertia around the y-axis. Must be positive.

izz - The moment of inertia around the z-axis. Must be positive.

ixy - The product of inertia around the x and y axes

ixz - The product of inertia around the x and z axes

iyz - The product of inertia around the y and z axes

unit - The unit for all the specified values

Returns:

A new inertia matrix

addPayload

Payload addPayload(String idKey,
                   String suggestedName,
                   Mass mass,
                   Position centerOfGravity)

Add a payload to the current installation in PolyScope.

This makes the payload selectable by the end user as well as available to other URCap contributions (through the PayloadModel interface). The payload is not modifiable by the end user or other URCaps.

A default guess for the inertia matrix for the payload will be computed based on the specified payload mass and center of gravity. If data for the payload's inertia matrix is available, the method addPayload(String, String, Mass, Position, InertiaMatrix) can used instead (this might give better performance of the robot arm).

Note: The specified payload mass must be the total mass of the payload attached to the tool output flange of the robot.

The valid range for the payload mass and the coordinates of the center of gravity (CoG) are available through the RobotLimits interface which can be accessed with RobotModel.getRobotLimits() (an instance of the RobotModel interface can be retrieved through SystemAPI.getRobotModel()).

Parameters:

idKey - The key to identify this payload by, not null nor an empty string. The key is for this URCap only, i.e. it only has to be unique for this URCap and not "globally" for other URCaps.

suggestedName - Suggested name for the payload, not null nor an empty string. Valid names must match regex [a-zA-Z][a-zA-Z0-9_]{0,14} for a total of 15 characters. The final name can be retrieved from the returned payload instance.

mass - The total mass of the payload attached to the tool output flange of the robot, not null. Create it using SimpleValueFactory.createMass(double, Mass.Unit).

centerOfGravity - The center of gravity (CoG), also referred to as center of mass, for the payload. It is defined as the offset between the center of the tool output flange and the center of gravity of the attached payload. Cannot be null. Create it using the PositionFactory interface.

Returns:

The payload created and registered in PolyScope.

Throws:

PayloadAlreadyAddedException - If a payload has previously been added using the same idKey identifier. Use getPayload(String) to check if the payload has already been added to the current installation. Use updatePayload(String, Mass, Position) or updatePayload(String, Mass, Position, InertiaMatrix) to update the payload if the payload parameters have changed.

IllegalPayloadNameException - If the suggested name does not match required regex.

IllegalMassException - If the specified mass is not inside the valid range as defined by PolyScope.

IllegalCenterOfGravityException - If any of the values of the specified center of gravity are not inside the valid range as defined by PolyScope.

addPayload

Payload addPayload(String idKey,
                   String suggestedName,
                   Mass mass,
                   Position centerOfGravity,
                   InertiaMatrix inertiaMatrix)

Add a payload to the current installation in PolyScope.

This makes the payload selectable by the end user as well as available to other URCap contributions (through the PayloadModel interface). The payload is not modifiable by the end user or other URCaps.

Use the addPayload(String, String, Mass, Position, InertiaMatrix) method instead if data for the payload's inertia matrix is not available.

Note: The specified payload mass must be the total mass of the payload attached to the tool output flange of the robot.

The valid range for the payload mass and the coordinates of the center of gravity (CoG) are available through the RobotLimits interface which can be accessed with RobotModel.getRobotLimits() (an instance of the RobotModel interface can be retrieved through SystemAPI.getRobotModel()).

Parameters:

idKey - The key to identify this payload by, not null nor an empty string. The key is for this URCap only, i.e. it only has to be unique for this URCap and not "globally" for other URCaps.

suggestedName - Suggested name for the payload, not null nor an empty string. Valid names must match regex [a-zA-Z][a-zA-Z0-9_]{0,14} for a total of 15 characters. The final name can be retrieved from the returned payload instance.

mass - The total mass of the payload attached to the tool output flange of the robot, not null. Create it using SimpleValueFactory.createMass(double, Mass.Unit).

centerOfGravity - The center of gravity (CoG), also referred to as center of mass, for the payload. It is defined as the offset between the center of the tool output flange and the center of gravity of the attached payload. Cannot be null. Create it using the PositionFactory interface.

inertiaMatrix - The inertia matrix of the payload, defined in a coordinate system with center at the payload's center of gravity and the axes aligned with the tool output flange coordinate system (axes). Cannot be null. Create it using createInertiaMatrix(double, double, double, double, double, double, MomentOfInertia.Unit).

Returns:

The payload created and registered in PolyScope.

Throws:

PayloadAlreadyAddedException - If a payload has previously been added using the same idKey identifier. Use getPayload(String) to check if the payload has already been added to the current installation. Use updatePayload(String, Mass, Position) or updatePayload(String, Mass, Position, InertiaMatrix) to update the payload if the payload parameters have changed.

IllegalPayloadNameException - If the suggested name does not match required regex.

IllegalMassException - If the specified mass is not inside the valid range as defined by PolyScope.

IllegalCenterOfGravityException - If any of the values of the specified center of gravity are not inside the valid range as defined by PolyScope.

IllegalInertiaMatrixException - If any of the values of the specified inertia matrix are not inside the valid range as defined by PolyScope.

getPayload

Payload getPayload(String idKey)

Returns the payload previously added by this URCap using the same idKey identifier. Use this to verify if the payload is present in the current installation.

Parameters:

idKey - The key to identify this payload by, not null nor an empty string.

Returns:

The payload previously added by this URCap. Returns null if no payload exists in current installation (with the specified idKey identifier).

updatePayload

void updatePayload(String idKey,
                   Mass mass,
                   Position centerOfGravity)

Update the mass and center of gravity (CoG) of an existing payload added by this URCap.

Note: If an inertia matrix has been specified for the payload, calling this method will replace (overwrite) it with a computed default guess based the new specified payload mass and center of gravity. To avoid overwriting an existing inertia matrix (or to update an existing inertia matrix), instead use the method updatePayload(String, Mass, Position, InertiaMatrix).

Parameters:

idKey - The key to identify the payload, not null nor an empty string. A payload must have been added using the same key prior to calling this method.

mass - The total mass of the payload attached to the tool output flange of the robot, not null. Create it using SimpleValueFactory.createMass(double, Mass.Unit).

centerOfGravity - The center of gravity of the payload, not null. Create it using the PositionFactory interface.

Throws:

PayloadNotFoundException - If no payload exists with the provided idKey identifier in the current installation.

IllegalMassException - If the specified mass is not inside the valid range as defined by PolyScope.

IllegalCenterOfGravityException - If any of the values of the specified center of gravity are not inside the valid range as defined by PolyScope.

updatePayload

void updatePayload(String idKey,
                   Mass mass,
                   Position centerOfGravity,
                   InertiaMatrix inertiaMatrix)

Update the mass, center of gravity (CoG) and inertia matrix of an existing payload added by this URCap.

Parameters:

idKey - The key to identify the payload, not null nor an empty string. A payload must have been added using the same key prior to calling this method.

mass - The total mass of the payload attached to the tool output flange of the robot, not null. Create it using SimpleValueFactory.createMass(double, Mass.Unit).

centerOfGravity - The center of gravity of the payload, not null. Create it using the PositionFactory interface.

inertiaMatrix - The inertia matrix of the payload, not null. Create it using createInertiaMatrix(double, double, double, double, double, double, MomentOfInertia.Unit)

Throws:

PayloadNotFoundException - If no payload exists with the provided idKey identifier in the current installation.

IllegalMassException - If the specified mass is not inside the valid range as defined by PolyScope.

IllegalCenterOfGravityException - If any of the values of the specified center of gravity are not inside the valid range as defined by PolyScope.

IllegalInertiaMatrixException - If any of the values of the specified inertia matrix are not inside the valid range as defined by PolyScope.

removePayload

void removePayload(String idKey)

Remove a payload added by this URCap from PolyScope. Program nodes using the payload will be become undefined because the payload is no longer resolvable.

Parameters:

idKey - The identifier key used to add the payload with, not null nor an empty string.

Throws:

PayloadNotFoundException - If no payload exists with the provided idKey identifier in the current installation.