BehaviorTree.ROS2

BehaviorTree.ROS2 provides wrappers to integrate ROS2 with BehaviorTree.CPP. It is designed to minimize boilerplate and ensure that asynchronous ROS2 Actions remain non-blocking within the behavior tree execution.

Key capabilities include implementing:

• Behavior Tree Executors using the ROS Action interface.
• Action clients.
• Service clients.
• Topic subscribers.
• Topic publishers.

The TreeExecutionServer is a base class that wraps a Behavior Tree executor inside an rclcpp_action::Server. This allows external ROS 2 nodes to trigger and control Behavior Tree execution using rclcpp_action::Client commands.

Key features include:

• XML Loading: Loads Behavior Tree definitions from a list of folders.
• Plugin Loading: Loads BT plugins (ROS-dependent or independent) from a list of folders.
• ROS Integration: Configurable via ROS parameters and provides feedback to action clients.
• Extensibility: Can be used out-of-the-box or extended by deriving from this class to add custom nodes, loggers, or global blackboard patterns.

To extend the BehaviorTree factory with custom plugins or pre-defined SubTrees, use the plugins and behavior_trees parameters. Both parameters accept a string_array of paths in the format 'package_name/subfolder'.

• Use plugins to load custom BehaviorTree plugins.
• Use behavior_trees to load SubTrees into the factory.

Ensure that these lists contain no duplicate entries.

bt_server:
  ros__parameters:
    plugins: ["my_custom_pkg/plugins"]
    behavior_trees: ["my_bt_pkg/subtrees"]

To subscribe to ROS topics within a Behavior Tree, derive a class from the ROS Topic Subscriber Wrapper. You must implement the required onTick method to process incoming messages.

Required Methods

• NodeStatus onTick(const std::shared_ptr<TopicT>& last_msg): Invoked during the tick. You must return either SUCCESS or FAILURE.

Optional Methods

• bool latchLastMessage(): Determines if the last processed message should be reused if no new message arrives.
  • Return false: No message will be processed if no new message is received.
  • Return true: The same message will be processed again until a new one arrives.

The TreeExecutionServer is configurable via ROS parameters. Detailed documentation for specific parameters is located in the bt_executor_parameters.md file.

If you are a maintainer and need to regenerate the parameter documentation from the source YAML, use the following command:

generate_parameter_library_markdown --input_yaml src/bt_executor_parameters.yaml --output_markdown_file bt_executor_parameters.md

Before using this library, ensure your environment meets the following minimum version requirements:

• BT.CPP: version 4.6 or newer.
• ROS2: Humble or newer.

The TreeExecutionServer is a sample server that loads a list of plugins and BehaviorTrees from a yaml configuration file.

To start the sample Execution Server, use the following launch command:

ros2 launch btcpp_ros2_samples sample_bt_executor.launch.xml

Upon startup, the server logs the ROS Action name it is hosting, followed by the successfully loaded plugins (e.g., .so files) and BehaviorTrees (e.g., .xml files).

To publish ROS topics from a Behavior Tree, derive a class from the ROS Topic Publisher Wrapper. You must implement the required setMessage method to provide the data for each tick.

// Example signature for implementation
bool setMessage(TopicT& msg);

To use a ROS Service within a Behavior Tree, derive a class from the ROS Service Behavior Wrapper base class. You must implement the required setRequest and onResponseReceived methods.

Required Methods

• setRequest(typename Request::SharedPtr& request): Sets the service request message.
• BT::NodeStatus onResponseReceived(const typename Response::SharedPtr& response): Defines whether the service response results in SUCCESS or FAILURE.

Optional Methods

• BT::NodeStatus onFailure(ServiceNodeErrorCode error): Handles service errors. Must return either SUCCESS or FAILURE.

The bt_server node uses several ROS 2 parameters to define its execution behavior, plugin loading, and communication ports. You can configure these in your ROS 2 parameter file (YAML). Note that some parameters like action_name, tick_frequency, and groot2_port are read-only at runtime.

bt_server:
  ros__parameters:
    action_name: bt_execution
    behavior_trees: []
    groot2_port: 1667
    plugins: []
    ros_plugins_timeout: 1000
    tick_frequency: 100

Once the TreeExecutionServer is running, you can trigger the execution of a specific BehaviorTree using the ros2 action command. The server exposes the btcpp_ros2_interfaces/action/ExecuteTree action.

To execute a tree named CrossDoor, use:

ros2 action send_goal /behavior_server btcpp_ros2_interfaces/action/ExecuteTree "{target_tree: CrossDoor}"

You can also trigger behaviors that act as ROS Action or Service clients themselves (e.g., a SleepActionSample) using the same interface: