You're reading the documentation for an older, but still supported version (1.33.4).
For information on the latest version, please have a look at 1.33.5.

add_tool (Manual Mode)

This section explains how to use add_tool in Manual mode during initialization routines to register a new tool (end-effector) on the robot controller.

A tool definition includes weight, center of gravity (CoG), and inertia information, all of which are necessary for accurate trajectory generation and force estimation. Once registered, a tool can be activated using set_tool.

Available in Manual mode. In any other mode the function returns false and prints this command can only be used in manual mode. please change to manual mode as robot mode. The mode check uses the value returned by get_robot_mode.

Caution

On a real robot the safety board also refuses the call while the robot is moving; the motion is quick-stopped and a running program is stopped.

Typical usage

  • Register a new gripper, probe, or custom end-effector.

  • Load tool data measured from Smart Setup or CAD specifications.

  • Prepare multiple tool configurations for automated tool-changing processes.

  • Initialize tool definitions during system startup or commissioning.

Note

  • The name is limited to 32 bytes; longer names are truncated. Adding a name that already exists replaces that entry, and if the tool (TCP) is active the new values take effect immediately. The controller holds up to 50 tools and 50 TCPs; adding beyond that raises an alarm and stops the running program.

  • Weight and CoG values should match the physical tool as closely as possible.

  • Tool registration is typically performed once—not every cycle.

Example: Registering a New Tool Configuration

float cog[3]     = {0.f, 0.f, 40.f};       // in mm relative to flange/TCP
float inertia[6] = {0.f, 0.f, 0.f, 0.f, 0.f, 0.f};

// Register a new tool
if (drfl.add_tool("NEW_END_EFFECTOR", 1.2f, cog, inertia)) {
    printf("Tool registered successfully.\n");
} else {
    printf("Failed to register tool.\n");
    return -1;
}

// Select the new tool
drfl.set_tool("NEW_END_EFFECTOR");

In this example, a new tool is created and then enabled for subsequent motion using set_tool().

Tips

  • Register all tools during initialization, then switch tools using set_tool.

  • Use accurate mass/CoG values to ensure safe motion and torque estimation.

  • Store tool symbols in a central recipe table for multi-tool automation.