Flexible ROS 2 node implementing a standardized interface for dynamically executing behavior trees. More...

#include <auto_apms_behavior_tree/executor/executor_node.hpp>

Inheritance diagram for TreeExecutorNode:

Public Member Functions
	TreeExecutorNode (const std::string &name, TreeExecutorNodeOptions executor_options)
	Constructor allowing to specify a custom node name and executor options.

	TreeExecutorNode (rclcpp::NodeOptions options)
	Constructor populating both the node's name and the executor options with the default.

std::shared_future< ExecutionResult >	startExecution (const std::string &build_request, const std::string &entrypoint="", const core::NodeManifest &node_manifest={})
	Start the behavior tree that is specified by a particular build request.

std::shared_future< ExecutionResult >	startExecution (TreeConstructor make_tree, double tick_rate_sec=0.1, int groot2_port=-1)
	Start a behavior tree that is built using a callback.

template<typename TimeRepT = int64_t, typename TimeT = std::milli>
std::shared_future< ExecutionResult >	startExecution (TreeConstructor make_tree, const std::chrono::duration< TimeRepT, TimeT > &tick_rate, int groot2_port=-1)
	Start a behavior tree that is built using a callback.

Public Member Functions inherited from TreeExecutorBase
	TreeExecutorBase (rclcpp::Node::SharedPtr node_ptr, rclcpp::CallbackGroup::SharedPtr tree_node_callback_group_ptr=nullptr)
	Constructor.

std::shared_future< ExecutionResult >	startExecution (TreeConstructor make_tree, double tick_rate_sec=0.1, int groot2_port=-1)
	Start a behavior tree that is built using a callback.

template<typename TimeRepT = int64_t, typename TimeT = std::milli>
std::shared_future< ExecutionResult >	startExecution (TreeConstructor make_tree, const std::chrono::duration< TimeRepT, TimeT > &tick_rate, int groot2_port=-1)
	Start a behavior tree that is built using a callback.

void	setControlCommand (ControlCommand cmd)
	Set the command that handles the control flow of the execution routine.

bool	isBusy ()
	Determine whether this executor is currently executing a behavior tree.

ExecutionState	getExecutionState ()
	Get a status code indicating the current state of execution.

std::string	getTreeName ()
	Get the name of the tree that is currently executing.

TreeBlackboardSharedPtr	getGlobalBlackboardPtr ()
	Get a shared pointer to the global blackboard instance.

TreeStateObserver &	getStateObserver ()
	Get a reference to the current behavior tree state observer.

rclcpp::Node::SharedPtr	getNodePtr ()
	Get a shared pointer to the parent ROS 2 node.

rclcpp::node_interfaces::NodeBaseInterface::SharedPtr	get_node_base_interface ()
	Get the node's base interface. Is required to be able to register derived classes as ROS2 components.

rclcpp::CallbackGroup::SharedPtr	getTreeNodeWaitablesCallbackGroupPtr ()
	Get the callback group used for all waitables registered by behavior tree nodes.

rclcpp::executors::SingleThreadedExecutor::SharedPtr	getTreeNodeWaitablesExecutorPtr ()
	Get the ROS 2 executor instance used for spinning waitables registered by behavior tree nodes.

Protected Member Functions
std::map< std::string, rclcpp::ParameterValue >	getParameterValuesWithPrefix (const std::string &prefix)
	Assemble all parameters of this node that have a specific prefix.

bool	updateScriptingEnumsWithParameterValues (const std::map< std::string, rclcpp::ParameterValue > &value_map, bool simulate=false)
	Update the internal buffer of scripting enums used when a behavior tree is created.

bool	updateGlobalBlackboardWithParameterValues (const std::map< std::string, rclcpp::ParameterValue > &value_map, bool simulate=false)
	Update the global blackboard using parameter values.

void	loadBuildHandler (const std::string &name)
	Load a particular behavior tree build handler plugin.

TreeConstructor	makeTreeConstructor (const std::string &build_request, const std::string &entrypoint="", const core::NodeManifest &node_manifest={})
	Create a callback that builds a behavior tree according to a specific request.

virtual bool	clearGlobalBlackboard () override
	Reset the global blackboard and clear all entries. This also unsets the corresponding parameters.

Static Protected Member Functions
static std::string	stripPrefixFromParameterName (const std::string &prefix, const std::string &param_name)
	Get the name of a parameter without its prefix.

Private Member Functions
virtual void	preconfigureBuilder (TreeBuilder &builder, const std::string &build_request, const std::string &entrypoint, const core::NodeManifest &node_manifest)
	Callback invoked every time before any behavior trees are built.

bool	afterTick () override final

Additional Inherited Members
Public Types inherited from TreeExecutorBase
enum class	ExecutionState : uint8_t { IDLE , STARTING , RUNNING , PAUSED , HALTED }
	Enum representing possible behavior tree execution states. More...

enum class	ControlCommand : uint8_t { RUN , PAUSE , HALT , TERMINATE }
	Enum representing possible commands for controlling the behavior tree execution routine. More...

enum class	TreeExitBehavior : uint8_t { TERMINATE , RESTART }
	Enum representing possible options for what to do when a behavior tree is completed. More...

enum class	ExecutionResult : uint8_t { TREE_SUCCEEDED , TREE_FAILED , TERMINATED_PREMATURELY , ERROR }
	Enum representing possible behavior tree execution results. More...

Protected Attributes inherited from TreeExecutorBase
rclcpp::Node::SharedPtr	node_ptr_
	Shared pointer to the parent ROS 2 node.

const rclcpp::Logger	logger_
	Logger associated with the parent ROS 2 node.

Detailed Description

Flexible ROS 2 node implementing a standardized interface for dynamically executing behavior trees.

The executor is configured using ROS 2 parameters. Parameters are typically set using parameter overrides when launching a node or during runtime using the ros2 param set command line tool.

A behavior tree can be executed via command line:

ros2 run auto_apms_behavior_tree run_behavior <build_request>

Alternatively, an executor can also be included as part of a ROS 2 components container. The following executor components are provided:

auto_apms_behavior_tree::TreeExecutorNode
auto_apms_behavior_tree::NoUndeclaredParamsExecutorNode
auto_apms_behavior_tree::OnlyScriptingEnumParamsExecutorNode
auto_apms_behavior_tree::OnlyBlackboardParamsExecutorNode
auto_apms_behavior_tree::OnlyInitialScriptingEnumParamsExecutorNode
auto_apms_behavior_tree::OnlyInitialBlackboardParamsExecutorNode

Definition at line 117 of file executor_node.hpp.

Constructor & Destructor Documentation

◆ TreeExecutorNode() [1/2]

TreeExecutorNode	(	const std::string &	name,
		TreeExecutorNodeOptions	executor_options )

Constructor allowing to specify a custom node name and executor options.

Parameters

name	Default name of the `rclcpp::Node`.
executor_options	Executor specific options. Simply pass a `rclcpp::NodeOptions` object to use the default options.

Definition at line 85 of file executor_node.cpp.

◆ TreeExecutorNode() [2/2]

TreeExecutorNode ( rclcpp::NodeOptions options )

explicit

Constructor populating both the node's name and the executor options with the default.

Parameters

options Options forwarded to rclcpp::Node constructor.

Definition at line 245 of file executor_node.cpp.

Member Function Documentation

◆ startExecution() [1/3]

std::shared_future< TreeExecutorNode::ExecutionResult > startExecution	(	const std::string &	build_request,
		const std::string &	entrypoint = "",
		const core::NodeManifest &	node_manifest = {} )

Start the behavior tree that is specified by a particular build request.

Executing the behavior tree is achieved by regularly invoking the internal routine that ticks the behavior tree created using make_tree. This requires to register a timer with the associated ROS 2 node. Consequently, the behavior tree is executed asynchronously. The user is provided a shared future object that allows to check whether the execution finished. Once this future completes, the execution result can be evaluated.

Parameters

build_request	Behavior build request for creating the behavior.
entrypoint	Single point of entry for behavior execution.
node_manifest	Behavior tree node manifest to be loaded for behavior execution.

Returns: Shared future that completes once executing the tree is finished or an error occurs. In that case, it is assigned an execution result code.

Definition at line 256 of file executor_node.cpp.

◆ preconfigureBuilder()

void preconfigureBuilder	(	core::TreeBuilder &	builder,
		const std::string &	build_request,
		const std::string &	entrypoint,
		const core::NodeManifest &	node_manifest )

privatevirtual

Callback invoked every time before any behavior trees are built.

This is invoked first thing inside the tree constructor callback returned by TreeExecutorNode::makeTreeConstructor just after the tree builder object has been instantiated. Therefore, the builder object is "empty" when passed to this method.

There are two common use cases where this method is useful:

The user wants to define an executor-specific initial configuration of the builder object, before it is passed to the currently configured build handler.

The user wants to bypass the build handler concept and directly create the behavior tree using this method.

Parameters

builder	Tree builder to be configured. This is used for creating the behavior tree later.
build_request	Behavior build request for creating the behavior.
entrypoint	Single point of entry for behavior execution.
node_manifest	Behavior tree node manifest to be loaded for behavior execution.

Definition at line 250 of file executor_node.cpp.

◆ getParameterValuesWithPrefix()

std::map< std::string, rclcpp::ParameterValue > getParameterValuesWithPrefix ( const std::string & prefix )

protected

Assemble all parameters of this node that have a specific prefix.

This function searches with depth = 2, so given that prefix = "foo" it will only consider parameters with names that match foo.bar but not foo.bar1.bar2 and deeper patterns. The user must specify prefix accordingly.

Parameters

prefix Only consider parameters that have this prefix in their names.

Returns: Map of parameter names and their respective values.

Definition at line 264 of file executor_node.cpp.

◆ stripPrefixFromParameterName()

std::string stripPrefixFromParameterName	(	const std::string &	prefix,
		const std::string &	param_name )

staticprotected

Get the name of a parameter without its prefix.

Parameters

prefix	Prefix to remove from `param_name`.
param_name	Name of the parameter with its prefix.

Returns: Name of the parameter without its prefix. If param_name doesn't contain prefix, an empty string is returned.

Definition at line 276 of file executor_node.cpp.

◆ updateScriptingEnumsWithParameterValues()

bool updateScriptingEnumsWithParameterValues	(	const std::map< std::string, rclcpp::ParameterValue > &	value_map,
		bool	simulate = false )

protected

Update the internal buffer of scripting enums used when a behavior tree is created.

This function automatically deduces the underlying type of each parameter value in value_map. Scripting enums are stored as integers, so if a parameter value is not int or bool (true == 1 and false == 0) an error is raised. If simulate is true, the buffer won't be modified and instead of raising an error this function simply returns false.

Parameters

value_map	Map of parameter names and their respective values.
simulate	Set this to `true` to only validate that the underlying types of the provided parameter values comply with the above mentioned requirements.

Returns: true if updating the scripting enums using value_map is possible, false otherwise. Only if simulate is false, they are actually updated.

Exceptions

auto_apms_behavior_tree::exceptions::ParameterConversionError if a parameter value cannot be converted to a valid scripting enum.

Definition at line 283 of file executor_node.cpp.

◆ updateGlobalBlackboardWithParameterValues()

bool updateGlobalBlackboardWithParameterValues	(	const std::map< std::string, rclcpp::ParameterValue > &	value_map,
		bool	simulate = false )

protected

Update the global blackboard using parameter values.

This function automatically deduces the underlying type of each parameter value in value_map and sets the global blackboard entries determined by the map's keys accordingly. If a blackboard entry already exists, it is only allowed to modify it with a value that has the same type. If the types mismatch, an error is raised. If simulate is true, the blackboard is not modified and instead of raising an error this function simply returns false.

Parameters

value_map	Map of parameter names and their respective values.
simulate	Set this to `true` to only validate that the underlying types of the provided parameter values comply with the above mentioned requirements.

Returns: true if updating the global blackboard using value_map is possible, false otherwise. Only if simulate is false, it is actually updated.

Exceptions

auto_apms_behavior_tree::exceptions::ParameterConversionError	if a parameter value cannot be converted to a valid blackboard entry.
BT::LogicError	if the user tries to change the type of an existing blackboard entry.

Definition at line 318 of file executor_node.cpp.

◆ loadBuildHandler()

void loadBuildHandler ( const std::string & name )

protected

Load a particular behavior tree build handler plugin.

This enables this executor to dynamically change the build handler which accepts incoming build requests.

Parameters

name	Fully qualified name of the respective behavior tree build handler class. Set to `none` to simply unload the current build handler.

Definition at line 355 of file executor_node.cpp.

◆ makeTreeConstructor()

TreeConstructor makeTreeConstructor	(	const std::string &	build_request,
		const std::string &	entrypoint = "",
		const core::NodeManifest &	node_manifest = {} )

protected

Create a callback that builds a behavior tree according to a specific request.

The created callback makes all defined scripting enums available for the behavior tree and invokes the currently configured build handler to build it. It returns a corresponding instance of BT::Tree that may be ticked to execute the tree.

Parameters

build_request	Request that specifies how to build the behavior tree encoded in a string.
entrypoint	Single point of entry for behavior execution.
node_manifest	Behavior tree node manifest that specifies which nodes to use and how to load them.

Returns: Callback for creating the behavior tree according to the build request.

Exceptions

auto_apms_behavior_tree::exceptions::TreeBuildError if the build handler rejects the request.

Definition at line 384 of file executor_node.cpp.

◆ clearGlobalBlackboard()

bool clearGlobalBlackboard ( )

overrideprotectedvirtual

Reset the global blackboard and clear all entries. This also unsets the corresponding parameters.

Returns: true if blackboard was cleared, false if executor is not idle meaning that the blackboard cannot be cleared.

Reimplemented from TreeExecutorBase.

Definition at line 422 of file executor_node.cpp.

◆ afterTick()

bool afterTick ( )

finaloverrideprivatevirtual

Synchronize parameters with new blackboard entries if enabled

Send feedback

Reimplemented from TreeExecutorBase.

Definition at line 784 of file executor_node.cpp.

◆ startExecution() [2/3]

std::shared_future< TreeExecutorBase::ExecutionResult > startExecution	(	TreeConstructor	make_tree,
		double	tick_rate_sec = 0.1,
		int	groot2_port = -1 )

Start a behavior tree that is built using a callback.

Executing the behavior tree is achieved by regularly invoking the internal routine that ticks the behavior tree created using make_tree. This requires to register a timer with the associated ROS 2 node. Consequently, the behavior tree is executed asynchronously. The user is provided a shared future object that allows to check whether the execution finished. Once this future completes, the execution result can be evaluated.

Parameters

make_tree	Callback that creates a `BT::Tree` object which will be ticked to execute the tree.
tick_rate_sec	Behavior tree tick rate in seconds (1 tick every `tick_rate_sec` seconds) i.e. the interval of the timer that regularly invokes the execution routine.
groot2_port	Port number used for introspection and debugging with Groot2. `-1` means that no `BT::Groot2Publisher` will be installed.

Returns: Shared future that completes once executing the tree is finished or an error occurs. In that case, it is assigned an execution result code.

Definition at line 116 of file executor_base.cpp.

◆ startExecution() [3/3]

template<typename TimeRepT = int64_t, typename TimeT = std::milli>

std::shared_future< TreeExecutorBase::ExecutionResult > startExecution	(	TreeConstructor	make_tree,
		const std::chrono::duration< TimeRepT, TimeT > &	tick_rate,
		int	groot2_port = -1 )

inline

Start a behavior tree that is built using a callback.

Executing the behavior tree is achieved by regularly invoking the internal routine that ticks the behavior tree created using make_tree. This requires to register a timer with the associated ROS 2 node. Consequently, the behavior tree is executed asynchronously. The user is provided a shared future object that allows to check whether the execution finished. Once this future completes, the execution result can be evaluated.

Parameters

make_tree	Callback that creates a `BT::Tree` object which will be ticked to execute the tree.
tick_rate	Behavior tree tick rate i.e. the interval of the timer that regularly invokes the execution routine.
groot2_port	Port number used for introspection and debugging with Groot2. `-1` means that no `BT::Groot2Publisher` will be installed.

Returns: Shared future that completes once executing the tree is finished or an error occurs. In that case, it is assigned an execution result code.

Definition at line 135 of file executor_base.hpp.

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

auto_apms_behavior_tree/include/auto_apms_behavior_tree/executor/executor_node.hpp
auto_apms_behavior_tree/src/executor/executor_node.cpp

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Private Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ TreeExecutorNode() [1/2]

◆ TreeExecutorNode() [2/2]

Member Function Documentation

◆ startExecution() [1/3]

◆ preconfigureBuilder()

◆ getParameterValuesWithPrefix()

◆ stripPrefixFromParameterName()

◆ updateScriptingEnumsWithParameterValues()

◆ updateGlobalBlackboardWithParameterValues()

◆ loadBuildHandler()

◆ makeTreeConstructor()

◆ clearGlobalBlackboard()

◆ afterTick()

◆ startExecution() [2/3]

◆ startExecution() [3/3]