# Configuring a Custom Tool for the Robot

The objective of this tutorial is to demonstrate the procedure for creating and fitting a custom tool in the robot modeling and simulation environment.

## Geometric Modeling

The pneumatic suction cup gripper seen above was modeled as a 3D solid with perhaps excessive amount of details such as counter sunk holes, alignment pin holes and machined channels as seen below. In general, you can include as much geometry as needed as long as it static. For instance the blue pneumatic tubing cannot be modeled as they change shape while the robot is moving.

The model is drawn centered in the World XY plane such as the flange of the robot is represented by the XY plane (see below). Jeneratiff needs to know how to apply a plane-to-plane transformation from “somewhere” on to the flange of the robot as it moves in 3D space. The World XY plane as a source of transformation seems a reasonable choice.

Once the model is complete convert all solids into meshes and extract their boundary edges as seen below. You may also create additional curves as for example the vertical line (seen in red below) from the World Origin to the Tool Center Point (TCP). This will look nice with the kinematics skeleton in the robot visualization and also it will be a good reminder of the TCP visually. Place all mesh and curves required for the tool visualization in one layer with a unique name such as “Pneumatics”. Note that you can attach basic display materials to meshes and colors to curves. Those will be used for drawing the geometries by the simulator.

This is only half of the work complete.  Jeneratiff also needs to know the tool transformation from the flange to the TCP in order to associate the tool geometry with the kinematics model. The example seen here is rather trivial as the transformation from the flange coordinate system to the TCP is just a translation along the Z axis. Place a CPlane at the end of the red line and save it with the same name as your geometry layer (in this example “Pneumatics” as seen below).

To associate the tool geometry with Grasshopper and Jeneratiff just add the tool name (the same name used for the geometry layer and saved CPlane) under the robot model in the definition string as seen below. Make sure you re-link the text box to the Robot Model in order to force Grasshopper to reload the geometry from the layer and CPlane collection. Notice that the kinematics State has now updated the last coordinate transform matrix to accommodate the tool information. If you make mistakes with the geometry orientation or CPlane transform make the appropriate corrections to both pieces of information and re-link the Robot Model definition.

The tool below represents a parallel two-jag pneumatic gripper. What is rather more challenging in this scenario is the definition of the tool transformation from the flange basis (represented by the World XY plane) to the center between the jaws as it involved rotations. The are multiple ways to define the orientation of tool axes.

While there is no single best approach to defining the tool plane there are some customary rules of the thumb see below:

## Tool Center Point Definition

Place the tool origin in a location that makes sense visually and/or semantically. The middle point between the jaws seem like a reasonable choice for instance.

Optionally make sure the translation vector from the origin to the tool center point is numerically clear such as (0.0, 93.0, 26.0) as in 93mm along the Y-axis and 26mm along the Z-axis. This is much easier to track compared to extended decimal numbers.

## Normal Direction Definition

Select a Z-axis for the tool that also makes sense semantically. By convention moving along the positive Z-axis means moving forward in some ways. The robot without the tool moves forward as the Z-axis at the flange is pointing normal outwards from it. In the example below the Z-axis points along the jaws / gripper direction.

In 3-axis machining applications often the Z-axis points along the tool bit and upwards away from the material stock. This is also a reasonable convention as it relates motion directions conceptually with cutting and jogging.

## Normal Rotation Definition

Select both the X and Y axes of the tool plane such that the rotation from the flange to the tool frame is minimized (or it appears simple). This will allow debugging the robot’s motion much easier as jogging along the tool or flange will match in one way or another. In the example below since we only need one rotation about 90deg to bring the flange plane onto the tool plane the X-axis of the tool is selected such that it is aligned with the flange X-axis. It is also now very clear that we just need rotate about the X-axis of the flange by 90deg to bring the Y-axis on the tool Y-axis direction.

Another potential logic for setting up the tool orientation is to choose some non-square rotation. Instead of 90deg use 30deg or 45deg for instance in order to avoid potential problems with start motions which may onto or close to singularities.