Tools

Robotic tools or end effectors are devices mounted to the flange of a robot arm. They enable various tasks such as grasping, welding or cutting and many more.

An activated tool changes the tool center point (TCP) of the robot, such that the configured center of the tool is moving to a desired Cartesian pose instead of the robot flange. Furthermore, it influences the dynamic parameters of the robot.

Some robotic systems also allow to trigger special tool commands and query the state of the tool.

Note

Tool selection is currently only available for robots of the Victor Robot Behavior Group.

It is expected, that one or multiple tools are preconfigured on the robot control to select from.

Tool configuration, tool commands and tool states are not supported at the moment.

Selecting Tools

You can get the selectable tools by using the get_selectable_tools_v() method. This will return a tuple of tool names. Reading the name of the currently selected tool can be achieved by using the get_selected_tool_v() method.

A tool can be selected using the select_tool_v() method. The select_tool_v() method expects a name of an available tool as a string. This method will return as soon as the selected tool is activated by robot control. If the tool does not exist on the robot control, an error will be raised.

It is also possible to deselect the active tool by using the deselect_tool_v() method.

The following example shows a simple application that selects a tool.

Using tools example

"""Tool example for robots with Victor behavior."""

from enum import StrEnum
from logging import Logger, getLogger
from typing import Protocol, runtime_checkable

from voraus_robot_arm import (
    SelectToolVictorTrait,
    VorausIndustrialRobotArm,
    configure_logging,
)

_logger: Logger = getLogger(__name__)

VORAUS_CORE_HOST = "localhost"
VORAUS_CORE_PORT = 48401


@runtime_checkable
class _RequiredRobotTraits(SelectToolVictorTrait, Protocol): ...


class MyTool(StrEnum):
    """Enum that represents relevant tools for the application."""

    EXAMPLE_TOOL = "Schunk_EGP_Co-act"
    SCHMALZ_TOOL = "Schmalz_ECBPi"


def run_tool_selection_example(robot: _RequiredRobotTraits) -> None:
    """Example application to select tools on a Victor robot."""
    selectable_tools = robot.get_selectable_tools_v()
    _logger.info("Selectable tools: %s", selectable_tools)

    selected_tool = robot.get_selected_tool_v()
    _logger.info("Selected tool: %s", selected_tool)

    robot.select_tool_v(MyTool.EXAMPLE_TOOL)
    _logger.info("Selected tool: %s", robot.get_selected_tool_v())
    robot.select_tool_v(MyTool.SCHMALZ_TOOL)
    _logger.info("Selected tool: %s", robot.get_selected_tool_v())

    robot.deselect_tool_v()
    _logger.info("Selected tool: %s", robot.get_selected_tool_v())


if __name__ == "__main__":
    configure_logging()

    robot = VorausIndustrialRobotArm()
    with robot.connect(host=VORAUS_CORE_HOST, port=VORAUS_CORE_PORT):
        run_tool_selection_example(robot)

Definition of the Tool Methods

The methods to select tools for robots with Victor behavior are defined in the SelectToolVictorTrait:

SelectToolVictorTrait

protocol SelectToolVictorTrait

Trait to select a tool for robots with Victor behavior.

This protocol is runtime checkable.

Classes that implement this protocol must have the following methods / attributes:

abstractmethod get_selectable_tools_v()

Get the names of the selectable tools.

Return type:

tuple[str, ...]

Returns:

The names of the selectable tools.

abstractmethod select_tool_v(tool_name)

Select the given tool.

Note, the tool must be configured on the robot control.

Parameters:

tool_name (str) – The tool name to select.

Raises:

RobotArmError – If the tool does not exist on the robot control.

Return type:

None

abstractmethod deselect_tool_v()

Deselect the currently selected tool.

Raises:

RobotArmError – If no tool is selected.

Return type:

None

abstractmethod get_selected_tool_v()

Get the name of the tool which is currently selected.

If no tool is selected, this will return None.

Return type:

str | None

Returns:

The currently selected tool name or None.