Skip to content

Tools

RAI provides various ROS 2 tools, both generic (mimics ros2cli) and specific (e.g., nav2, moveit2, etc.)

Class Definition

BaseROS2Tool is the base class for all ROS 2 tools. It provides a common interface for all ROS 2 tools including name allowlist/blocklist for all the communication protocols (messages, services, actions)

Class Definition

rai.tools.ros2.base.BaseROS2Tool

Bases: BaseTool

Base class for all ROS2 tools.

Attributes:

Name Type Description
connector ROS2Connector

The connector to the ROS 2 system.
readable Optional[List[str]]

The topics that can be read. If the list is not provided, all topics can be read.
writable Optional[List[str]]

The names (topics/actions/services) that can be written. If the list is not provided, all topics can be written.
forbidden Optional[List[str]]

The names (topics/actions/services) that are forbidden to read and write.
name str

The name of the tool.
description str

The description of the tool.
Source code in src/rai_core/rai/tools/ros2/base.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
class BaseROS2Tool(BaseTool):
    """
    Base class for all ROS2 tools.

    Attributes
    ----------
    connector : ROS2Connector
        The connector to the ROS 2 system.
    readable : Optional[List[str]]
        The topics that can be read. If the list is not provided, all topics can be read.
    writable : Optional[List[str]]
        The names (topics/actions/services) that can be written. If the list is not provided, all topics can be written.
    forbidden : Optional[List[str]]
        The names (topics/actions/services) that are forbidden to read and write.
    name : str
        The name of the tool.
    description : str
        The description of the tool.
    """

    connector: ROS2Connector
    readable: Optional[List[str]] = None
    writable: Optional[List[str]] = None
    forbidden: Optional[List[str]] = None

    name: str = ""
    description: str = ""

    def is_readable(self, topic: str) -> bool:
        if self.forbidden is not None and topic in self.forbidden:
            return False
        if self.readable is None:
            return True
        return topic in self.readable

    def is_writable(self, topic: str) -> bool:
        if self.forbidden is not None and topic in self.forbidden:
            return False
        if self.writable is None:
            return True
        return topic in self.writable

Usage example

from rai.communication.ros2 import ROS2Connector
from rai.tools.ros2.base import BaseROS2Tool

connector = ROS2Connector()

BaseROS2Tool( # BaseROS2Tool cannot be used directly, this is just an example
    connector=connector,
    readable=["/odom", "/scan"], # readable topics, services and actions
    writable=["/robot_position"], # writable topics, services and actions
    forbidden=["/cmd_vel"], # forbidden topics, services and actions
)

Generic ROS 2 Tools

RAI provides a generic ROS 2 toolkit, which allows the Agent to interact with any ROS 2 topics, services and actions.

from rai.tools.ros2 import ROS2Toolkit
from rai.communication.ros2 import ROS2Connector

connector = ROS2Connector()
tools = ROS2Toolkit(connector=connector).get_tools()

Below is the list of tools provided by the generic ROS 2 toolkit that can also be used as standalone tools (except for the ROS 2 action tools, which should be used via the ROS2ActionToolkit as they share a state):

Topics

Tool Name Description
PublishROS2MessageTool Tool for publishing messages to ROS 2 topics
ReceiveROS2MessageTool Tool for receiving messages from ROS 2 topics
GetROS2ImageTool Tool for retrieving image data from topics
GetROS2TopicsNamesAndTypesTool Tool for listing all available topics and their types
GetROS2MessageInterfaceTool Tool for getting message interface information
GetROS2TransformTool Tool for retrieving transform data

Services

Tool Name Description
GetROS2ServicesNamesAndTypesTool Tool for listing all available services and their types
CallROS2ServiceTool Tool for calling ROS 2 services

Actions

Tool Name Description
GetROS2ActionsNamesAndTypesTool Tool for listing all available actions and their types
StartROS2ActionTool Tool for starting ROS 2 actions
GetROS2ActionFeedbackTool Tool for retrieving action feedback
GetROS2ActionResultTool Tool for retrieving action results
CancelROS2ActionTool Tool for canceling running actions
GetROS2ActionIDsTool Tool for getting action IDs

Specific ROS 2 Tools

RAI provides specific ROS 2 tools for certain ROS 2 packages.

Tool Name Description
NavigateToPoseTool Tool for navigating to a pose
GetNavigateToPoseFeedbackTool Tool for retrieving the feedback of a navigate to pose action
GetNavigateToPoseResultTool Tool for retrieving the result of a navigate to pose action
CancelNavigateToPoseTool Tool for canceling a navigate to pose action
GetOccupancyGridTool Tool for retrieving the occupancy grid

Custom Tools

Tool Name Description
MoveToPointTool Tool for moving to a point
GetObjectPositionsTool Tool for retrieving the positions of objects