Base class that offers basic functionality for executing behavior trees. More...

#include <auto_apms_behavior_tree/executor/executor_base.hpp>

Inheritance diagram for TreeExecutorBase:

[legend]

Public Types
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...

Public Member Functions
	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.

std::shared_future< ExecutionResult >	startExecution (std::unique_ptr< Tree > tree, double tick_rate_sec=0.1, int groot2_port=-1)
	Start executing a behavior tree that has already been created.

template<typename TimeRepT = int64_t, typename TimeT = std::milli>
std::shared_future< ExecutionResult >	startExecution (std::unique_ptr< Tree > tree, const std::chrono::duration< TimeRepT, TimeT > &tick_rate, int groot2_port=-1)
	Start executing a behavior tree that has already been created.

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

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 Attributes
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.

Private Member Functions
virtual bool	onInitialTick ()
	Callback invoked once before the behavior tree is ticked for the very first time.

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

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

virtual TreeExitBehavior	onTreeExit (bool success)
	Callback invoked last thing when the execution routine completes because the behavior tree is finished.

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

Detailed Description

Base class that offers basic functionality for executing behavior trees.

This class implements a highly configurable execution routine for behavior trees. Inheriting classes are able to modify certain callbacks by overriding the corresponding virtual methods. The user is able to control the execution by giving certain commands at runtime.

See also: TreeExecutorNode for a standardized implementation as a rclcpp::Node.

Definition at line 40 of file executor_base.hpp.

Member Enumeration Documentation

◆ ExecutionState

enum class ExecutionState : uint8_t

strong

Enum representing possible behavior tree execution states.

Enumerator
IDLE	Nothing to do.
STARTING	Initializing execution.
RUNNING	Executor is busy and tree has been ticked at least once.
PAUSED	Execution routine is active, but tree is not being ticked.
HALTED	Execution routine is active, but tree is not being ticked and has been halted before.

Definition at line 46 of file executor_base.hpp.

◆ ControlCommand

enum class ControlCommand : uint8_t

strong

Enum representing possible commands for controlling the behavior tree execution routine.

Enumerator
RUN	Start/Resume the execution routine.
PAUSE	Pause the execution routine.
HALT	Halt the currently executing tree and pause the execution routine.
TERMINATE	Halt the currently executing tree and terminate the execution routine.

Definition at line 58 of file executor_base.hpp.

◆ TreeExitBehavior

enum class TreeExitBehavior : uint8_t

strong

Enum representing possible options for what to do when a behavior tree is completed.

Enumerator
TERMINATE	Stop execution and reset the timer.
RESTART	Restart execution and keep on running.

Definition at line 69 of file executor_base.hpp.

◆ ExecutionResult

enum class ExecutionResult : uint8_t

strong

Enum representing possible behavior tree execution results.

Enumerator
TREE_SUCCEEDED	Tree completed with `BT::NodeStatus::SUCCESS`.
TREE_FAILED	Tree completed with `BT::NodeStatus::FAILURE`.
TERMINATED_PREMATURELY	Execution terminated before the tree was able to propagate the tick to all its nodes.
ERROR	An unexpected error occurred.

Definition at line 78 of file executor_base.hpp.

Constructor & Destructor Documentation

◆ TreeExecutorBase()

TreeExecutorBase	(	rclcpp::Node::SharedPtr	node_ptr,
		rclcpp::CallbackGroup::SharedPtr	tree_node_callback_group_ptr = nullptr )

Constructor.

Parameters

node_ptr	Parent ROS 2 node to be used to set up the required communication interfaces.
tree_node_callback_group_ptr	Callback group that is used for all waitables registered by behavior tree nodes.

Definition at line 25 of file executor_base.cpp.

Member Function Documentation

◆ startExecution() [1/4]

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 48 of file executor_base.cpp.

◆ startExecution() [2/4]

template<typename TimeRepT, typename TimeT>

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 327 of file executor_base.hpp.

◆ startExecution() [3/4]

std::shared_future< TreeExecutorBase::ExecutionResult > startExecution	(	std::unique_ptr< Tree >	tree,
		double	tick_rate_sec = 0.1,
		int	groot2_port = -1 )

Start executing a behavior tree that has already been created.

Unlike the TreeConstructor overloads, this variant lets the caller construct the BT::Tree themselves (e.g. via GenericTreeExecutorNode::makeTreeConstructor) and hand over ownership. This decouples the potentially expensive tree construction from starting the execution routine, so a caller can build the tree ahead of time and react to build failures before committing to execution (e.g. abort registration if the tree cannot be built).

Note: For global blackboard entries (the @-prefixed keys) to resolve at runtime, tree must have been created with a blackboard rooted at this executor's global blackboard (see getGlobalBlackboardPtr).

Parameters

tree	Ownership of the behavior tree to execute. Must not be `nullptr`.
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.

Exceptions

auto_apms_behavior_tree::exceptions::TreeExecutorError if the executor is busy or tree is nullptr.

Definition at line 71 of file executor_base.cpp.

◆ startExecution() [4/4]

template<typename TimeRepT, typename TimeT>

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

inline

Start executing a behavior tree that has already been created.

See also: startExecution(std::unique_ptr<Tree>, double, int) for details.

Parameters

tree	Ownership of the behavior tree to execute. Must not be `nullptr`.
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.

Definition at line 335 of file executor_base.hpp.

◆ onInitialTick()

bool onInitialTick ( )

privatevirtual

Callback invoked once before the behavior tree is ticked for the very first time.

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

Definition at line 258 of file executor_base.cpp.

◆ onTick()

bool onTick ( )

privatevirtual

Callback invoked every time before the behavior tree is ticked.

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

Definition at line 260 of file executor_base.cpp.

◆ afterTick()

bool afterTick ( )

privatevirtual

Callback invoked every time after the behavior tree is ticked.

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

Definition at line 262 of file executor_base.cpp.

◆ onTreeExit()

TreeExecutorBase::TreeExitBehavior onTreeExit ( bool success )

privatevirtual

Callback invoked last thing when the execution routine completes because the behavior tree is finished.

This callback is only invoked, if there haven't been any errors during execution.

Returns: Whether to terminate or restart the routine.

Definition at line 264 of file executor_base.cpp.

◆ onTermination()

void onTermination ( const ExecutionResult & result )

privatevirtual

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.

Definition at line 269 of file executor_base.cpp.

◆ clearGlobalBlackboard()

bool clearGlobalBlackboard ( )

virtual

Reset the global blackboard and clear all entries.

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

Reimplemented in GenericTreeExecutorNode.

Definition at line 271 of file executor_base.cpp.

◆ setControlCommand()

void setControlCommand ( ControlCommand cmd )

Set the command that handles the control flow of the execution routine.

Note: The given control command is not validated, so the user must be careful when using this low-level setter.

Parameters

cmd	Control command.

Definition at line 284 of file executor_base.cpp.

◆ isBusy()

bool isBusy ( )

Determine whether this executor is currently executing a behavior tree.

Returns: true if this executor is busy, false otherwise.

Definition at line 286 of file executor_base.cpp.

◆ getExecutionState()

TreeExecutorBase::ExecutionState getExecutionState ( )

Get a status code indicating the current state of execution.

Returns: Execution state.

Definition at line 288 of file executor_base.cpp.

◆ getTreeName()

std::string getTreeName ( )

Get the name of the tree that is currently executing.

If the executor is not busy, NO_TREE_NAME is returned.

Returns: Name of the currently executing tree.

Definition at line 303 of file executor_base.cpp.

◆ getGlobalBlackboardPtr()

TreeBlackboardSharedPtr getGlobalBlackboardPtr ( )

Get a shared pointer to the global blackboard instance.

The global blackboard is used as a root blackboard on every tree that is being created. This means, that all entries of the global blackboard are publicly available to the trees at runtime and can be queried using the '@' prefix.

Note: This method creates a copy of the internal shared pointer object, so you are not able to modify the internal pointer variable itself.

Returns: Shared pointer to the global blackboard.

Definition at line 309 of file executor_base.cpp.

◆ getStateObserver()

TreeStateObserver & getStateObserver ( )

Get a reference to the current behavior tree state observer.

Returns: Current state observer reference.

Exceptions

auto_apms_behavior_tree::exceptions::TreeExecutorError if executor is not busy.

Definition at line 311 of file executor_base.cpp.

◆ getNodePtr()

rclcpp::Node::SharedPtr getNodePtr ( )

Get a shared pointer to the parent ROS 2 node.

Returns: Shared pointer to the rclcpp::Node associated with this executor.

Definition at line 319 of file executor_base.cpp.

◆ get_node_base_interface()

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.

Returns: Base interface of the rclcpp::Node associated with this executor.

Definition at line 321 of file executor_base.cpp.

◆ getTreeNodeWaitablesCallbackGroupPtr()

rclcpp::CallbackGroup::SharedPtr getTreeNodeWaitablesCallbackGroupPtr ( )

Get the callback group used for all waitables registered by behavior tree nodes.

Returns: Shared pointer to the behavior tree node waitables callback group.

Definition at line 326 of file executor_base.cpp.

◆ getTreeNodeWaitablesExecutorPtr()

rclcpp::executors::SingleThreadedExecutor::SharedPtr getTreeNodeWaitablesExecutorPtr ( )

Get the ROS 2 executor instance used for spinning waitables registered by behavior tree nodes.

Returns: Shared pointer to the rclcpp::executors::SingleThreadedExecutor for behavior tree node waitables.

Definition at line 331 of file executor_base.cpp.

Member Data Documentation

◆ node_ptr_

rclcpp::Node::SharedPtr node_ptr_

protected

Shared pointer to the parent ROS 2 node.

Definition at line 296 of file executor_base.hpp.

◆ logger_

const rclcpp::Logger logger_

protected

Logger associated with the parent ROS 2 node.

Definition at line 298 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_base.hpp
auto_apms_behavior_tree/src/executor/executor_base.cpp

Public Types

Public Member Functions

Protected Attributes

Private Member Functions

Detailed Description

Member Enumeration Documentation

◆ ExecutionState

◆ ControlCommand

◆ TreeExitBehavior

◆ ExecutionResult

Constructor & Destructor Documentation

◆ TreeExecutorBase()

Member Function Documentation

◆ startExecution() [1/4]

◆ startExecution() [2/4]

◆ startExecution() [3/4]

◆ startExecution() [4/4]

◆ onInitialTick()

◆ onTick()

◆ afterTick()

◆ onTreeExit()

◆ onTermination()

◆ clearGlobalBlackboard()

◆ setControlCommand()

◆ isBusy()

◆ getExecutionState()

◆ getTreeName()

◆ getGlobalBlackboardPtr()

◆ getStateObserver()

◆ getNodePtr()

◆ get_node_base_interface()

◆ getTreeNodeWaitablesCallbackGroupPtr()

◆ getTreeNodeWaitablesExecutorPtr()

Member Data Documentation

◆ node_ptr_

◆ logger_