TreeBuildHandler Class Reference

Base class for plugins that implement patterns for creating behavior trees using a standardized interface. More...

#include <auto_apms_behavior_tree/build_handler/build_handler.hpp>

Inheritance diagram for TreeBuildHandler:

Public Member Functions
	TreeBuildHandler (const std::string &name, rclcpp::Node::SharedPtr ros_node_ptr, NodeLoader::SharedPtr tree_node_loader_ptr)
	Constructor allowing to give the build handler a specific name.
	TreeBuildHandler (rclcpp::Node::SharedPtr ros_node_ptr, NodeLoader::SharedPtr tree_node_loader_ptr)
	Constructor.
virtual bool	setBuildRequest (const std::string &build_request, const NodeManifest &node_manifest, const std::string &root_tree_name)
	Specify the behavior tree build request encoded in a string.
virtual TreeDocument::TreeElement	buildTree (TreeDocument &doc, TreeBlackboard &bb)=0
	Build the behavior tree specified before.
rclcpp::Node::SharedPtr	getRosNodePtr () const
	Get a shared pointer to the parent rclcpp::Node of this build handler.
NodeLoader::SharedPtr	getNodeLoaderPtr () const
	Get a shared pointer to the class loader instance used for loading the required behavior tree nodes.

Protected Attributes
const rclcpp::Logger	logger_
	ROS 2 logger initialized with the name of the build handler.

Detailed Description

Base class for plugins that implement patterns for creating behavior trees using a standardized interface.

Inheriting classes must implement TreeBuildHandler::buildTree. Additionally, the user is given the possibility to define specific rules for when to accept a request and what to do when one arrives. This can be achieved by overriding TreeBuildHandler::setBuildRequest. By default, all requests are accepted and the arguments of that method are ignored.

A tree build handler allows TreeExecutorNode to create a behavior tree at runtime when an execution request is received. The user may change the the way how a behavior tree is created by simply switching to the desired build handler implementation. To make those implementations available at runtime, the user must register them using the CMake macro auto_apms_behavior_tree_declare_build_handlers in the CMakeLists.txt of the parent package.

Usage

Behavior tree build handler plugins are created like this:

// my_custom_build_handler.cpp
 
#include "auto_apms_behavior_tree/build_handler.hpp"
 
namespace my_namespace
{
class MyCustomBuildHandler : public TreeBuildHandler
{
public:
  using TreeBuildHandler::TreeBuildHandler;
 
  bool setBuildRequest(const std::string & build_request,
                       const NodeManifest & node_manifest,
                       const std::string & root_tree_name) override final
  {
    // Do something when a build request arrives
    // When this isn't overriden, all requests are accepted regardless the arguments given above
    // ...
 
    // Returning true means accepting the request, false means rejecting it
    return true;
  }
 
  TreeDocument::TreeElement buildTree(TreeDocument & doc,
                                      TreeBlackboard & bb) override final
  {
    // Configure the behavior tree
    // ...
 
    // The returned tree element will be used as the root tree by TreeExecutorNode. It must belong to doc
    return doc.newTree("MyCustomTree");
  }
}
}  // namespace my_namespace
 
// Make sure the plugin class is discoverable
AUTO_APMS_BEHAVIOR_TREE_DECLARE_BUILD_HANDLER(my_namespace::MyCustomBuildHandler)

Given this implementation, the CMake macro auto_apms_behavior_tree_declare_build_handlers must be called in the CMakeLists.txt of the parent package like this:

find_package(ament_cmake REQUIRED)
find_package(auto_apms_behavior_tree REQUIRED)
 
# Create a shared library
add_library(my_custom_build_handler_lib SHARED
    "my_custom_build_handler.cpp"  # Add the source file
)
ament_target_dependencies(my_custom_build_handler_lib
    auto_apms_behavior_tree  # The library must link against auto_apms_behavior_tree
)
 
# Add the plugin to this package's ament_index resources
auto_apms_behavior_tree_declare_build_handlers(my_custom_build_handler_lib
    "my_namespace::MyCustomBuildHandler"
)
 
# Make sure to install the shared library to the standard directory
install(
   TARGETS
   my_custom_build_handler_lib
   LIBRARY DESTINATION lib
   ARCHIVE DESTINATION lib
   RUNTIME DESTINATION bin
)

Once the parent package has been installed, the build handler plugin may be loaded using TreeBuildHandlerLoader. With a behavior tree executor node, the user may simply set its parameter called build_handler to "my_namespace::MyCustomBuildHandler" (the fully qualified class name). All build requests that the node receives from this point on are forwarded to this specific build handler implementation.

Definition at line 126 of file build_handler.hpp.

Constructor & Destructor Documentation

TreeBuildHandler() [1/2]

TreeBuildHandler	(	const std::string &	name,
		rclcpp::Node::SharedPtr	ros_node_ptr,
		NodeLoader::SharedPtr	tree_node_loader_ptr )

Constructor allowing to give the build handler a specific name.

Parameters

name	Name of the build handler.
ros_node_ptr	Shared pointer to the associated ROS 2 node.
tree_node_loader_ptr	Shared pointer to an existing behavior tree node loader that the build handler may work with.

Definition at line 22 of file build_handler.cpp.

TreeBuildHandler() [2/2]

TreeBuildHandler	(	rclcpp::Node::SharedPtr	ros_node_ptr,
		NodeLoader::SharedPtr	tree_node_loader_ptr )

Constructor.

This signature is used when creating an instance of this build handler.

The build handler is given a generic name. To provide a user defined name, reimplement the constructor and delegate construction to the overload above. This may look something like this:

MyCustomBuildHandler(rclcpp::Node::SharedPtr ros_node_ptr, NodeLoader::SharedPtr tree_node_loader_ptr)
: TreeBuildHandler("my_custom_name", ros_node_ptr, tree_node_loader_ptr)
{
}

Parameters

ros_node_ptr	Shared pointer to the associated ROS 2 node.
tree_node_loader_ptr	Shared pointer to an existing behavior tree node loader that the build handler may work with.

Definition at line 30 of file build_handler.cpp.

Member Function Documentation

setBuildRequest()

bool setBuildRequest ( const std::string & build_request, const NodeManifest & node_manifest, const std::string & root_tree_name )

virtual

Specify the behavior tree build request encoded in a string.

Additionally, you may provide an associated node manifest and a specific tree name for setting the root tree. When using TreeExecutorNode, all arguments are populated using the respective parameters of the incoming StartTreeExecutor action goal. It's up to the specific implementation, if and how they are interpreted.

The intention with the boolean return value is to indicate whether the respective behavior tree is allowed to be built or not. Only if this returns true, TreeBuildHandler::buildTree is to be called afterwards. The user must stick to this design pattern and implement this function accordingly.

By default, this callback always returns true.

Parameters

build_request	Request that specifies how to build the behavior tree encoded in a string.
node_manifest	Behavior tree node manifest that specifies which nodes to use and how to load them.
root_tree_name	Name of the requested root tree.

Returns

true if the build handler accepts the request, false if it is rejected.

Reimplemented in MissionBuildHandlerBase.

Definition at line 35 of file build_handler.cpp.

buildTree()

virtual TreeDocument::TreeElement buildTree ( TreeDocument & doc, TreeBlackboard & bb )

pure virtual

Build the behavior tree specified before.

Typically, the build handler stores the information received when TreeBuildHandler::setBuildRequest was called. As soon as this function is invoked, this information should be looked up and used to configure the corresponding behavior tree with doc. Optionally, initial values for the global blackboard may be set using bb.

Parameters

doc	Reference to the behavior tree document that is used to instantiate the tree that is built by this function.
bb	Reference to the global blackboard that is used as a parent blackboard when instantiating the tree that is built by this function.

Returns

Tree element representing one of the trees inside doc. It is used to determine the root tree.

Implemented in MissionBuildHandlerBase.

getRosNodePtr()

rclcpp::Node::SharedPtr getRosNodePtr

(

)

const

Get a shared pointer to the parent rclcpp::Node of this build handler.

Returns

Shared pointer of the associated ROS 2 node.

Definition at line 41 of file build_handler.cpp.

getNodeLoaderPtr()

TreeBuildHandler::NodeLoader::SharedPtr getNodeLoaderPtr

(

)

const

Get a shared pointer to the class loader instance used for loading the required behavior tree nodes.

Returns

Shared pointer of the associated behavior tree node loader.

Definition at line 49 of file build_handler.cpp.

Member Data Documentation

logger_

const rclcpp::Logger logger_

protected

ROS 2 logger initialized with the name of the build handler.

Definition at line 219 of file build_handler.hpp.

---

The documentation for this class was generated from the following files:

• auto_apms_behavior_tree/include/auto_apms_behavior_tree/build_handler/build_handler.hpp
• auto_apms_behavior_tree/src/build_handler/build_handler.cpp