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 &tree_build_request)
	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.

void	clearGlobalBlackboard ()
	Reset the global blackboard and clear all entries.

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_handler_request, const std::string &root_tree_name, const core::NodeManifest &node_manifest={}, const core::NodeManifest &node_overrides={})
	Create a callback that builds a behavior tree according to a specific request.

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	setUpBuilder (TreeBuilder &builder, const core::NodeManifest &node_manifest)
	Callback invoked every time before any behavior trees are built.

bool	onTick () override final
	Callback invoked every time before the behavior tree is ticked.

bool	afterTick () override final
	Callback invoked every time after the behavior tree is ticked.

void	onTermination (const ExecutionResult &result) override final
	Callback invoked when the execution routine terminates.

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_tree <tree_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 118 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 81 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 225 of file executor_node.cpp.

Member Function Documentation

◆ startExecution() [1/3]

std::shared_future< TreeExecutorNode::ExecutionResult > startExecution ( const std::string & tree_build_request )

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

tree_build_request Behavior tree build request forwarded to the currently loaded build handler.

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 232 of file executor_node.cpp.

◆ setUpBuilder()

void setUpBuilder	(	core::TreeBuilder &	builder,
		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, this allows the user to define an executor specific initial configuration of the builder object, before the underlying tree document is passed to the currently configured build handler and the tree is instantiated.

Parameters

builder	Tree builder to be configured. This is used for creating the behavior tree later.
node_manifest	Behavior tree node manifest that specifies which nodes to use and how to load them. It is provided by the `StartTreeExecutor` goal request sent to this executor.

Definition at line 230 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 239 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 251 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 258 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 293 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 330 of file executor_node.cpp.

◆ makeTreeConstructor()

TreeConstructor makeTreeConstructor	(	const std::string &	build_handler_request,
		const std::string &	root_tree_name,
		const core::NodeManifest &	node_manifest = {},
		const core::NodeManifest &	node_overrides = {} )

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_handler_request	Request that specifies how to build the behavior tree encoded in a string.
root_tree_name	Name of the requested root tree.
node_manifest	Behavior tree node manifest that specifies which nodes to use and how to load them.
node_overrides	Behavior tree node manifest that specifies which nodes to override once the tree has been built. This may be used to swap specific node plugins that have been loaded by the build handler.

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 359 of file executor_node.cpp.

◆ onTick()

bool onTick ( )

finaloverrideprivatevirtual

Callback invoked every time before the behavior tree is ticked.

Returns: false if the execution should be aborted, true to continue.

Reimplemented from TreeExecutorBase.

Definition at line 755 of file executor_node.cpp.

◆ afterTick()

bool afterTick ( )

finaloverrideprivatevirtual

Callback invoked every time after the behavior tree is ticked.

Returns: false if the execution should be aborted, true to continue.

Synchronize parameters with new blackboard entries if enabled

Send feedback

Reimplemented from TreeExecutorBase.

Definition at line 764 of file executor_node.cpp.

◆ onTermination()

void onTermination ( const ExecutionResult & result )

finaloverrideprivatevirtual

Callback invoked when the execution routine terminates.

If the execution routine is restarted, this won't be called. It's only when a final result is available, that this callback takes effect.

Parameters

result Final result code of the behavior tree execution.

Reimplemented from TreeExecutorBase.

Definition at line 849 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]

◆ setUpBuilder()

◆ getParameterValuesWithPrefix()

◆ stripPrefixFromParameterName()

◆ updateScriptingEnumsWithParameterValues()

◆ updateGlobalBlackboardWithParameterValues()

◆ loadBuildHandler()

◆ makeTreeConstructor()

◆ onTick()

◆ afterTick()

◆ onTermination()

◆ startExecution() [2/3]

◆ startExecution() [3/3]