GripperDB

Introduction

The GripperDB module (gripper database module) is an optional on-board module of the rc_cube and is licensed with any of the modules ItemPick and BoxPick or CADMatch and SilhouetteMatch. Otherwise it requires a separate CollisionCheck license to be purchased.

The module provides services to set, retrieve and delete grippers which can then be used for checking collisions with a load carrier or other detected objects (only in combination with CADMatch and SilhouetteMatch). The specified grippers are available for all modules supporting collision checking on the rc_cube.

Note

This module is global on the rc_cube. Changes to its settings or parameters affect every camera pipeline running on the rc_cube.

Table 51 Specifications of the GripperDB module
Max. number of grippers 50
Supported gripper element geometries Box, Cylinder, CAD Element
Max. number of elements per gripper 15
Collision checking available in ItemPick and BoxPick, CADMatch and SilhouetteMatch

Setting a gripper

The gripper is a collision geometry used to determine whether the grasp is in collision with the load carrier. The gripper consists of up to 15 elements connected to each other.

At this point, the gripper can be built of elements of the following types:

  • BOX, with dimensions box.x, box.y, box.z.
  • CYLINDER, with radius cylinder.radius and height cylinder.height.
  • CAD, with the id cad.id of the chosen CAD element.

Additionally, for each gripper the flange radius, and information about the Tool Center Point (TCP) have to be defined.

The configuration of the gripper is normally performed offline during the setup of the desired application. This can be done via the REST-API interface or the rc_cube Web GUI.

Robot flange radius

Collisions are checked only with the gripper, the robot body is not considered. As a safety feature, to prevent collisions between the load carrier and the robot, all grasps having any part of the robot’s flange inside the load carrier can be designated as colliding (see Fig. 50). This check is based on the defined gripper geometry and the flange radius value. It is optional to use this functionality, and it can be turned on and off with the CollisionCheck module’s run-time parameter check_flange as described in Parameter overview.

_images/check_flange.svg

Fig. 50 Case A would be marked as collision only if check_flange is true, because the robot’s flange (red) is inside the load carrier. Case B is collision free independent of check_flange.

Uploading gripper CAD elements

A gripper can consist of boxes, cylinders and CAD elements. While boxes and cylinders can be parameterized when the gripper is created, the CAD elements must be uploaded beforehand to be available during gripper creation. A CAD element can be uploaded via the REST-API interface as described in Section CAD element API or via the rc_cube Web GUI. Supported file formats are STEP (*.stp, *.step), STL (*.stl), OBJ (*.obj) and PLY (*.ply). The maximum file size to be uploaded is limited to 30 MB. The files are internally converted to PLY and, if necessary, simplified. The CAD elements can be referenced during gripper creation by their ID.

Creating a gripper via the REST-API or the Web GUI

When creating a gripper via the REST-API interface or the Web GUI, each element of the gripper has a parent element, which defines how they are connected. The gripper is always built in the direction from the robot flange to the TCP, and at least one element must have ‘flange’ as parent. The elements’ IDs must be unique and must not be ‘tcp’ or ‘flange’. The pose of the child element has to be given in the coordinate frame of the parent element. The coordinate frame of an element is always in its geometric center. Accordingly, for a child element to be exactly below the parent element, the position of the child element must be computed from the heights of both parent and child element (see Fig. 51).

_images/gripper_frames_restapi.svg

Fig. 51 Reference frames for gripper creation via the REST-API and the Web GUI

In case a CAD element is used, the element’s origin is defined in the CAD data and is not necessarily located in the center of the element’s bounding box.

It is recommended to create a gripper via the Web GUI, because it provides a 3D visualization of the gripper geometry and also allows to automatically attach the child element to the bottom of its parent element, when the corresponding option for this element is activated. In this case, the elements also stay attached when any of their sizes change. Automatic attachment of CAD elements uses the element’s bounding box as reference. Automatic attachment is only possible when the child element is not rotated around the x or y axis with respect to its parent.

The reference frame for the first element for the gripper creation is always the center of the robot’s flange with the z axis pointing outwards. It is possible to create a gripper with a tree structure, corresponding to multiple elements having the same parent element, as long as they are all connected.

Calculated TCP position

After gripper creation via the set_gripper service call, the TCP position in the flange coordinate system is calculated and returned as tcp_pose_flange. It is important to check if this value is the same as the robot’s true TCP position. When creating a gripper in the Web GUI the current TCP position is always displayed in the 3D gripper visualization.

Creating rotationally asymmetric grippers

For grippers which are not rotationally symmetric around the z axis, it is crucial to ensure that the gripper is properly mounted, so that the representation stored in the GripperDB module corresponds to reality.

Services

The GripperDB module is called rc_gripper_db in the REST-API and is represented in the Web GUI under Database ‣ Grippers. The user can explore and call the GripperDB module’s services, e.g. for development and testing, using the REST-API interface or the Web GUI.

The GripperDB module offers the following services.

set_gripper

Persistently stores a gripper on the rc_cube. All configured grippers are persistent over firmware updates and rollbacks.

Details

This service can be called as follows.

PUT http://<host>/api/v2/nodes/rc_gripper_db/services/set_gripper
Request
Response

Required arguments:

elements: list of geometric elements for the gripper. Each element must be of type ‘CYLINDER’ or ‘BOX’ with the corresponding dimensions in the cylinder or box field, or of type ‘CAD’ with the corresponding id in the cad field. The pose of each element must be given in the coordinate frame of the parent element (see Setting a gripper for an explanation of the coordinate frames). The element’s id must be unique and must not be ‘tcp’ or ‘flange’. The parent_id is the ID of the parent element. It can either be ‘flange’ or it must correspond to another element in list.

flange_radius: radius of the flange used in case the check_flange run-time parameter is active.

id: unique name of the gripper

tcp_parent_id: ID of the element on which the TCP is defined

tcp_pose_parent: The pose of the TCP with respect to the coordinate frame of the element specified in tcp_parent_id.

The definition for the request arguments with corresponding datatypes is:

{
  "args": {
    "elements": [
      {
        "box": {
          "x": "float64",
          "y": "float64",
          "z": "float64"
        },
        "cad": {
          "id": "string"
        },
        "cylinder": {
          "height": "float64",
          "radius": "float64"
        },
        "id": "string",
        "parent_id": "string",
        "pose": {
          "orientation": {
            "w": "float64",
            "x": "float64",
            "y": "float64",
            "z": "float64"
          },
          "position": {
            "x": "float64",
            "y": "float64",
            "z": "float64"
          }
        },
        "type": "string"
      }
    ],
    "flange_radius": "float64",
    "id": "string",
    "tcp_parent_id": "string",
    "tcp_pose_parent": {
      "orientation": {
        "w": "float64",
        "x": "float64",
        "y": "float64",
        "z": "float64"
      },
      "position": {
        "x": "float64",
        "y": "float64",
        "z": "float64"
      }
    }
  }
}

gripper: returns the gripper as defined in the request with an additional field tcp_pose_flange. This gives the coordinates of the TCP in the flange coordinate frame for comparison with the true settings of the robot’s TCP.

return_code: holds possible warnings or error codes and messages.

The definition for the response with corresponding datatypes is:

{
  "name": "set_gripper",
  "response": {
    "gripper": {
      "elements": [
        {
          "box": {
            "x": "float64",
            "y": "float64",
            "z": "float64"
          },
          "cad": {
            "id": "string"
          },
          "cylinder": {
            "height": "float64",
            "radius": "float64"
          },
          "id": "string",
          "parent_id": "string",
          "pose": {
            "orientation": {
              "w": "float64",
              "x": "float64",
              "y": "float64",
              "z": "float64"
            },
            "position": {
              "x": "float64",
              "y": "float64",
              "z": "float64"
            }
          },
          "type": "string"
        }
      ],
      "flange_radius": "float64",
      "id": "string",
      "tcp_parent_id": "string",
      "tcp_pose_flange": {
        "orientation": {
          "w": "float64",
          "x": "float64",
          "y": "float64",
          "z": "float64"
        },
        "position": {
          "x": "float64",
          "y": "float64",
          "z": "float64"
        }
      },
      "tcp_pose_parent": {
        "orientation": {
          "w": "float64",
          "x": "float64",
          "y": "float64",
          "z": "float64"
        },
        "position": {
          "x": "float64",
          "y": "float64",
          "z": "float64"
        }
      },
      "type": "string"
    },
    "return_code": {
      "message": "string",
      "value": "int16"
    }
  }
}

get_grippers

Returns the configured grippers with the requested gripper_ids.

Details

This service can be called as follows.

PUT http://<host>/api/v2/nodes/rc_gripper_db/services/get_grippers
Request
Response

If no gripper_ids are provided, all configured grippers are returned.

The definition for the request arguments with corresponding datatypes is:

{
  "args": {
    "gripper_ids": [
      "string"
    ]
  }
}

The definition for the response with corresponding datatypes is:

{
  "name": "get_grippers",
  "response": {
    "grippers": [
      {
        "elements": [
          {
            "box": {
              "x": "float64",
              "y": "float64",
              "z": "float64"
            },
            "cad": {
              "id": "string"
            },
            "cylinder": {
              "height": "float64",
              "radius": "float64"
            },
            "id": "string",
            "parent_id": "string",
            "pose": {
              "orientation": {
                "w": "float64",
                "x": "float64",
                "y": "float64",
                "z": "float64"
              },
              "position": {
                "x": "float64",
                "y": "float64",
                "z": "float64"
              }
            },
            "type": "string"
          }
        ],
        "flange_radius": "float64",
        "id": "string",
        "tcp_parent_id": "string",
        "tcp_pose_flange": {
          "orientation": {
            "w": "float64",
            "x": "float64",
            "y": "float64",
            "z": "float64"
          },
          "position": {
            "x": "float64",
            "y": "float64",
            "z": "float64"
          }
        },
        "tcp_pose_parent": {
          "orientation": {
            "w": "float64",
            "x": "float64",
            "y": "float64",
            "z": "float64"
          },
          "position": {
            "x": "float64",
            "y": "float64",
            "z": "float64"
          }
        },
        "type": "string"
      }
    ],
    "return_code": {
      "message": "string",
      "value": "int16"
    }
  }
}

delete_grippers

Deletes the configured grippers with the requested gripper_ids.

Details

This service can be called as follows.

PUT http://<host>/api/v2/nodes/rc_gripper_db/services/delete_grippers
Request
Response

All grippers to be deleted must be explicitly stated in gripper_ids.

The definition for the request arguments with corresponding datatypes is:

{
  "args": {
    "gripper_ids": [
      "string"
    ]
  }
}

The definition for the response with corresponding datatypes is:

{
  "name": "delete_grippers",
  "response": {
    "return_code": {
      "message": "string",
      "value": "int16"
    }
  }
}

Return codes

Each service response contains a return_code, which consists of a value plus an optional message. A successful service returns with a return_code value of 0. Negative return_code values indicate that the service failed. Positive return_code values indicate that the service succeeded with additional information. The smaller value is selected in case a service has multiple return_code values, but all messages are appended in the return_code message.

The following table contains a list of common codes:

Table 52 Return codes of the GripperDB services
Code Description
0 Success
-1 An invalid argument was provided
-7 Data could not be read or written to persistent storage
-9 No valid license for the module
-10 New gripper could not be added as the maximum storage capacity of grippers has been exceeded
10 The maximum storage capacity of grippers has been reached
11 Existing gripper was overwritten

CAD element API

For gripper CAD element upload, download, listing and removal, special REST-API endpoints are provided. CAD elements can also be uploaded, downloaded and removed via the Web GUI. Up to 50 CAD elements can be stored persistently on the rc_cube.

The maximum file size to be uploaded is limited to 30 MB.

GET /cad/gripper_elements

Get list of all CAD gripper elements.

Template request

GET /api/v2/cad/gripper_elements HTTP/1.1

Template response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "string"
  }
]
Response Headers:
 
Status Codes:
  • 200 OK – successful operation (returns array of GripperElement)
  • 404 Not Found – element not found
Referenced Data Models:
 
GET /cad/gripper_elements/{id}

Get a CAD gripper element. If the requested content-type is application/octet-stream, the gripper element is returned as file.

Template request

GET /api/v2/cad/gripper_elements/<id> HTTP/1.1

Template response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "string"
}
Parameters:
  • id (string) – id of the element (required)
Response Headers:
 
  • Content-Type – application/json application/octet-stream
Status Codes:
Referenced Data Models:
 
PUT /cad/gripper_elements/{id}

Create or update a CAD gripper element.

Template request

PUT /api/v2/cad/gripper_elements/<id> HTTP/1.1
Accept: multipart/form-data application/json

Template response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "string"
}
Parameters:
  • id (string) – id of the element (required)
Form Parameters:
 
  • file – CAD file (required)
Request Headers:
 
  • Accept – multipart/form-data application/json
Response Headers:
 
Status Codes:
Referenced Data Models:
 
DELETE /cad/gripper_elements/{id}

Remove a CAD gripper element.

Template request

DELETE /api/v2/cad/gripper_elements/<id> HTTP/1.1
Accept: application/json
Parameters:
  • id (string) – id of the element (required)
Request Headers:
 
Response Headers:
 
Status Codes: