Class for configuring and instantiating behavior trees. More...

#include <auto_apms_behavior_tree_core/builder.hpp>

Inheritance diagram for TreeBuilder:

Public Member Functions
	TreeBuilder (rclcpp::Node::SharedPtr ros_node, rclcpp::CallbackGroup::SharedPtr tree_node_waitables_callback_group, rclcpp::executors::SingleThreadedExecutor::SharedPtr tree_node_waitables_executor, NodeRegistrationLoader::SharedPtr tree_node_loader=NodeRegistrationLoader::make_shared())
	Constructor.

	TreeBuilder (NodeRegistrationLoader::SharedPtr tree_node_loader=NodeRegistrationLoader::make_shared())
	Constructor.

TreeBuilder &	registerNodes (const NodeManifest &tree_node_manifest, bool override=false) override
	Load behavior tree node plugins and register them with the internal behavior tree factory.

TreeBuilder &	setScriptingEnum (const std::string &enum_name, int val)
	Define enums that may be used by any scripts inside the behavior tree.

template<typename EnumT>
TreeBuilder &	setScriptingEnumsFromType ()
	Define enums that may be used by any scripts inside the behavior tree.

Tree	instantiate (const std::string &root_tree_name, TreeBlackboardSharedPtr bb_ptr=TreeBlackboard::create())
	Create the behavior tree.

Tree	instantiate (TreeBlackboardSharedPtr bb_ptr=TreeBlackboard::create())
	Create the behavior tree.

Public Member Functions inherited from TreeDocument
	TreeDocument (const std::string &format_version=BTCPP_FORMAT_DEFAULT_VERSION, NodeRegistrationLoader::SharedPtr tree_node_loader=NodeRegistrationLoader::make_shared())
	Create a an empty tree document.

TreeDocument &	mergeTreeDocument (const XMLDocument &other, bool adopt_root_tree=false)
	Merge another tree document with this one.

TreeDocument &	mergeTreeDocument (const TreeDocument &other, bool adopt_root_tree=false)
	Merge another tree document with this one.

TreeDocument &	mergeString (const std::string &tree_str, bool adopt_root_tree=false)
	Create a tree document from a string and merge it with this one.

TreeDocument &	mergeFile (const std::string &path, bool adopt_root_tree=false)
	Create a tree document from a file and merge it with this one.

TreeDocument &	mergeResource (const TreeResource &resource, bool adopt_root_tree=false)
	Merge the behavior trees from one of the installed package's behavior tree resources.

TreeDocument &	mergeTree (const TreeElement &tree, bool make_root_tree=false)
	Merge an existing behavior tree with this tree document.

TreeElement	newTree (const std::string &tree_name)
	Create a new behavior tree inside this document.

TreeElement	newTree (const TreeElement &other_tree)
	Create a new behavior tree inside this document with the same content of another.

TreeElement	newTreeFromDocument (const TreeDocument &other, const std::string &tree_name="")
	Create a new behavior tree inside this document with the content of one found inside another tree document.

TreeElement	newTreeFromString (const std::string &tree_str, const std::string &tree_name="")
	Create a new behavior tree inside this document with the content of one found inside the XML string.

TreeElement	newTreeFromFile (const std::string &path, const std::string &tree_name="")
	Create a new behavior tree inside this document with the content of one found inside the XML file.

TreeElement	newTreeFromResource (const TreeResource &resource, const std::string &tree_name="")
	Create a new behavior tree inside this document with the content of one the trees found inside a particular behavior tree resource.

bool	hasTreeName (const std::string &tree_name) const
	Determine if this document specifies a behavior tree with a particular name.

TreeElement	getTree (const std::string &tree_name)
	Get the corresponding behavior tree element for a tree inside this document.

TreeDocument &	setRootTreeName (const std::string &tree_name)
	Define the root tree of this document.

bool	hasRootTreeName () const
	Determine if this document specifies which of its trees is the root tree.

std::string	getRootTreeName () const
	Get the name of this document's root tree.

TreeElement	getRootTree ()
	Get the corresponding behavior tree element for the root tree of this document.

TreeDocument &	removeTree (const std::string &tree_name)
	Remove a particular behavior tree from this document.

TreeDocument &	removeTree (const TreeElement &tree)
	Remove a particular behavior tree from this document.

std::vector< std::string >	getAllTreeNames () const
	Get the names of all behavior trees inside this document.

std::set< std::string >	getRegisteredNodeNames (bool include_native=true) const
	Get the names of all nodes that are known to this document.

NodeManifest	getRequiredNodeManifest () const
	Assemble the node manifest that is required for successfully creating an instance of any of the document's trees.

TreeDocument &	addNodeModel (bool include_native=false)
	Add an behavior tree node model element to the document.

NodeModelMap	getNodeModel (bool include_native=false) const
	Create a behavior tree node model for all nodes registered with this document.

BT::Result	verify () const
	Verify that all behavior trees of this document are structured correctly and can be created successfully.

std::string	writeToString () const
	Write the XML of this tree document to a string.

void	writeToFile (const std::string &path) const
	Write the XML of this tree document to a file.

TreeDocument &	reset ()
	Clear this document and reset it to its initial state.

Additional Inherited Members
Public Types inherited from TreeDocument
using	NodeModelMap = std::map<std::string, NodeModel>
	Mapping of node registration names and their implementation details.

Static Public Member Functions inherited from TreeDocument
static NodeModelMap	getNodeModel (tinyxml2::XMLDocument &doc)
	Convert a behavior tree node model document to the corresponding data structure.

Detailed Description

Class for configuring and instantiating behavior trees.

This class extends the functionality provided by BT::BehaviorTreeFactory of BehaviorTree.CPP and offers a user-friendly builder API for configuring behavior trees. In contrast to the original API, the user doesn't need to manually register behavior tree node entities with the factory in order to create an instance of BT::Tree. Instead, this class conveniently automates this process for you by querying the ament_index.

Usage

To create an executable behavior tree object, one must configure the tree using the inherited TreeDocument API. Afterwards, the behavior tree may be instantiated using the factory method TreeBuilder::instantiate.

The most convenient way of building and executing behavior trees is by using the included TreeBuildHandler plugins integrated with the TreeExecutorNode concept. The user may also implement their own build handlers and expose them to an executor node.

TODO Insert links to user guide showcasing the use of build handlers with executor nodes

Definition at line 54 of file builder.hpp.

Constructor & Destructor Documentation

◆ TreeBuilder() [1/2]

TreeBuilder	(	rclcpp::Node::SharedPtr	ros_node,
		rclcpp::CallbackGroup::SharedPtr	tree_node_waitables_callback_group,
		rclcpp::executors::SingleThreadedExecutor::SharedPtr	tree_node_waitables_executor,
		NodeRegistrationLoader::SharedPtr	tree_node_loader = NodeRegistrationLoader::make_shared() )

explicit

Constructor.

Arguments ros_node, tree_node_waitables_callback_group and tree_node_waitables_executor are passed to behavior tree node plugins which utilize ROS 2 communication interfaces or waitables in general, that is, all nodes inheriting from RosPublisherNode, RosSubscriberNode, RosServiceNode or RosActionNode.

Parameters

ros_node	Weak pointer to the ROS 2 node instance to be associate the behavior tree node with.
tree_node_waitables_callback_group	The ROS 2 callback group to be used within tree nodes when adding waitables.
tree_node_waitables_executor	The ROS 2 executor instance that may be used for executing work provided by the node's waitables.
tree_node_loader	Shared pointer to the behavior tree node plugin loader instance.

Definition at line 25 of file builder.cpp.

◆ TreeBuilder() [2/2]

TreeBuilder ( NodeRegistrationLoader::SharedPtr tree_node_loader = NodeRegistrationLoader::make_shared() )

explicit

Constructor.

Using this signature you'll only be able to instantiate behavior trees tha only contain nodes which don't require an instance of RosNodeContext during construction time (non-ROS nodes).

Parameters

tree_node_loader Shared pointer to the behavior tree node plugin loader instance.

Definition at line 38 of file builder.cpp.

Member Function Documentation

◆ registerNodes()

TreeBuilder & registerNodes	(	const NodeManifest &	tree_node_manifest,
		bool	override = false )

overridevirtual

Load behavior tree node plugins and register them with the internal behavior tree factory.

This makes it possible to add any nodes specified in tree_node_manifest to the tree.

Parameters

tree_node_manifest	Parameters for locating and configuring the behavior tree node plugins.
override	If `tree_node_manifest` specifies nodes that have already been registered, unregister the existing plugin and use the new one instead.

Exceptions

auto_apms_behavior_tree::exceptions::NodeRegistrationError if registration fails.

Reimplemented from TreeDocument.

Definition at line 46 of file builder.cpp.

◆ setScriptingEnum()

TreeBuilder & setScriptingEnum	(	const std::string &	enum_name,
		int	val )

Define enums that may be used by any scripts inside the behavior tree.

Parameters

enum_name	Name that is used to refer to the given value.
val	Value of the enum.

Returns: Modified tree builder.

Definition at line 64 of file builder.cpp.

◆ setScriptingEnumsFromType()

template<typename EnumT>

TreeBuilder & setScriptingEnumsFromType ( )

Define enums that may be used by any scripts inside the behavior tree.

This function automatically defines the scripting enums by inspecting EnumT using https://github.com/Neargye/magic_enum.

Warning: Refer to this page to learn about the limitations when using this approach.

Template Parameters

EnumT Type of the enumeration.

Returns: Modified tree builder.

Definition at line 149 of file builder.hpp.

◆ instantiate() [1/2]

Tree instantiate	(	const std::string &	root_tree_name,
		TreeBlackboardSharedPtr	bb_ptr = TreeBlackboard::create() )

Create the behavior tree.

This creates an instance of BT::Tree which holds the memory of all node callbacks and enables the user to actually execute the behavior tree. The entry point is determined by root_tree_name.

Parameters

root_tree_name	Name of an existing tree that should be the root tree.
bb_ptr	Optional pointer to the parent blackboard.

Returns: Instance of BT::Tree representing the configured behavior tree.

Exceptions

auto_apms_behavior_tree::exceptions::TreeBuildError	if there's no tree named `root_tree_name`.
auto_apms_behavior_tree::exceptions::TreeBuildError	if the tree cannot be instantiated.

Definition at line 70 of file builder.cpp.

◆ instantiate() [2/2]

Tree instantiate ( TreeBlackboardSharedPtr bb_ptr = TreeBlackboard::create() )

Create the behavior tree.

This creates an instance of BT::Tree which holds the memory of all node callbacks and enables the user to actually execute the behavior tree. The entry point will be the underlying document's root tree.

Parameters

bb_ptr Optional pointer to the parent blackboard.

Returns: Instance of BT::Tree representing the configured behavior tree.

Exceptions

auto_apms_behavior_tree::exceptions::TreeBuildError	if it's not defined which one of the existing trees is the root tree.
auto_apms_behavior_tree::exceptions::TreeBuildError	if the tree cannot be instantiated.

Definition at line 87 of file builder.cpp.

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

auto_apms_behavior_tree_core/include/auto_apms_behavior_tree_core/builder.hpp
auto_apms_behavior_tree_core/src/builder.cpp

Public Member Functions

Additional Inherited Members

Detailed Description

Usage

Constructor & Destructor Documentation

◆ TreeBuilder() [1/2]

◆ TreeBuilder() [2/2]

Member Function Documentation

◆ registerNodes()

◆ setScriptingEnum()

◆ setScriptingEnumsFromType()

◆ instantiate() [1/2]

◆ instantiate() [2/2]