careBT API

careBT nodes

ActionNode

class carebt.actionNode.ActionNode(bt_runner: BehaviorTreeRunner, params: str = None)

Bases: carebt.treeNode.TreeNode, abc.ABC

The careBT ActionNode class.

ActionNodes are the leafs in a careBT behavior tree. They execute the actions in the ‘world’ the behavior tree is running in. This includes manipulating the environment or actively perceiving it.

Parameters

bt_runner (‘BehaviorTreeRunner’) – The behavior tree runner which started the tree.
params (str) – The input/Output parameters of the node e.g. ‘?x ?y => ?z’

ControlNode

class carebt.controlNode.ControlNode(bt_runner: BehaviorTreeRunner, params: str = None)

Bases: carebt.treeNode.TreeNode, abc.ABC

The careBT ControlNode class.

ControlNode is the basic class for all nodes in careBT which provide a control flow functionality, like SequenceNode and ParallelNode.

final abort_current_child() → None: Abort the currently executing child.

final fix_current_child() → None

Fix the current child.

Mark the current child node as FIXED. This function should typiclly be called inside of a contingency-handler in case the handler fixes the situation and the control flow of the current ControlNode can be continued. FIXED is handled in the same way as SUCCESS, but provides the additional information that the node was ‘fixed’.

final register_contingency_handler(node, node_status_list: List[carebt.nodeStatus.NodeStatus], contingency_message: str, contingency_function: Callable) → None

Register a contingency-handler.

Registers a function which is called in case the provided contingency information are met. The registered contingency-handlers are tried to match to the current status and contingency message in the order they are registered.

For the parameters node and contingency_message a regular expression (regex) can be used.

Parameters

node (TreeNode, str) – The node the contingency-handler triggers on. In case of using regex the name has to be provided as string.
node_status_list ([NodeStatus]) – A list of NodeStatuses the contingency-handler triggers on.
contingency_message (str) – A regex the contingency-message has to match.
contingency_function (Callable) – The function which is called to handle the contingency.

final set_current_child_status(node_status: carebt.nodeStatus.NodeStatus) → None

Set the status of the currently executing child node.

Parameters: node_status (NodeStatus) – Status of the node

FallbackNode

class carebt.fallbackNode.FallbackNode(bt_runner: BehaviorTreeRunner, params: str = None)

Bases: carebt.controlNode.ControlNode, abc.ABC

The careBT FallbackNode class.

In a FallbackNode the added child nodes are executed one after another until one node completes with SUCCESS or FIXED. The child nodes are executed in the order they were added to the sequence. If all children complete with FAILURE or ABORTED the FallbackNode completes with FAILURE or ABORTED.

The FallbackNode forwards the ticks to the currently executing child - which can only be one at a time - if the status is RUNNING. If the status is SUSPENDED the ticks are not forwarded.

Parameters

bt_runner (‘BehaviorTreeRunner’) – The behavior tree runner which started the tree.
params (str) – The input/Output parameters of the node e.g. ‘?x ?y => ?z’

append_child(node: carebt.treeNode.TreeNode, params: Optional[str] = None) → None

Append a child.

Append a child node at the end of the sequence of this FallbackNode.

Parameters

node (TreeNode) – The node to be added
params (str (Default=None)) – The parameters of the added child node

insert_child_after_current(node: carebt.treeNode.TreeNode, params: Optional[str] = None) → None

Insert a child node after the current.

Insert a child node right after the currently executing child node. NOTE: When inserting more than one node, they should be inserted in reverse order. This is because each node will be inserted right after the currently executing!

Parameters

node (TreeNode) – The node to be added
params (str (Default=None)) – The parameters of the added child node

remove_all_children() → None

Remove all child nodes.

Remove all child nodes from the FallbackNode. This is typically done in a contingency handler to modify the current execution sequence and adjust it to the current situation. New children which should be executed afterwards can be added with append_child or insert_child_after_current.

ParallelNode

class carebt.parallelNode.ParallelNode(bt_runner: carebt.behaviorTreeRunner.BehaviorTreeRunner, success_threshold: int, params: Optional[str] = None)

Bases: carebt.controlNode.ControlNode, abc.ABC

The careBT ParallelNode class.

In a ParallelNode the added child nodes are executed in parallel at the same time. A ParallelNode completes with SUCCESS if equal or more than success_threshold children complete with SUCCESS or FIXED.

If as many children as necessary to beeing able to reach the success_threshold already completed with FAILURE or ABORTED the ParallelNode completes with FAILURE and sets its contingency_message to the contingency_message of the child which failed last. If two children fail in the same tick, the contingency_message of the latter one is used!

The ParallelNode forwards the ticks to all children in a quasi-parallel manner. If the ParallelNode gets ticked, it ticks the children in the order they were added - but within the same received tick.

Parameters

bt_runner (‘BehaviorTreeRunner’) – The behavior tree runner which started the tree.
success_threshold (int) – Threshold how many of the children should complete with SUCCESS or FIXED that the ParallelNode completes with SUCCESS.
params (str) – The input/Output parameters of the node e.g. ‘?x ?y => ?z’

add_child(node: carebt.treeNode.TreeNode, params: Optional[str] = None) → None

Add a child node.

Parameters

node (TreeNode) – The node to be added
params (str (Default=None)) – The parameters of the added child node

get_success_threshold() → int

Return the success_threshold.

Returns: success_threshold – The success_threshold
Return type: int

remove_all_children() → None: Remove all child nodes.

remove_child(pos: int) → None

Remove a child node.

Remove the child node at the provided position. The positions are in the order the children are added starting with zero.

Parameters: pos (int) – Position of the child to remove

set_success_threshold(success_threshold: int) → None

Set the success_threshold.

Parameters: success_threshold (int) – Threshold how many of the children should complete with SUCCESS or FIXED that the ParallelNode completes with SUCCESS.

RateControlNode

class carebt.rateControlNode.RateControlNode(bt_runner: BehaviorTreeRunner, throttle_ms: int, params: str = None)

Bases: carebt.controlNode.ControlNode, abc.ABC

The careBT RateControlNode class.

The RateControlNode is a special node to throttle the tick rate of its only child. It is similar to the throttle mechanism of the ActionNode. But the ActionNode needs to be already implemented with the throttling. The RateControlNode on the other hand can throttle all careBT nodes, such as SequenceNode, ParallelNode or as already mentioned an ActionNode. For the latter one this is especially useful if the implementation of the custon ActionNode should or could not be modified.

Parameters

bt_runner (‘BehaviorTreeRunner’) – The behavior tree runner which started the tree.
rate_ms (int) – Throttling rate in milliseconds
params (str) – The input/Output parameters of the node e.g. ‘?x ?y => ?z’

set_child(node: carebt.treeNode.TreeNode, params: Optional[str] = None) → None

Set the child node.

Set the child node to this RateControlNode. There can only be one child at the same time.

Parameters

node (TreeNode) – The node to be set
params (str (Default=None)) – The parameters of the added child node

SequenceNode

class carebt.sequenceNode.SequenceNode(bt_runner: BehaviorTreeRunner, params: str = None)

Bases: carebt.controlNode.ControlNode, abc.ABC

The careBT SequenceNode class.

In a SequenceNode the added child nodes are executed one after another until they all complete with SUCCESS or FIXED. The child nodes are executed in the order they were added to the sequence. If all children complete with SUCCESS or FIXED the SequenceNode completes with SUCCESS.

If one of the children completes with FAILURE or ABORTED and the situation is not fixed by a contingency-handler the SequenceNode completes also with FAILURE or ABORTED.

The SequenceNode forwards the ticks to the currently executing child - which can only be one at a time - if the status is RUNNING. If the status is SUSPENDED the ticks are not forwarded.

Parameters

bt_runner (‘BehaviorTreeRunner’) – The behavior tree runner which started the tree.
params (str) – The input/Output parameters of the node e.g. ‘?x ?y => ?z’

append_child(node: carebt.treeNode.TreeNode, params: Optional[str] = None) → None

Append a child node.

Append a child node at the end of the sequence of this SequenceNode.

Parameters

node (TreeNode) – The node to be added
params (str (Default=None)) – The parameters of the added child node

insert_child_after_current(node: carebt.treeNode.TreeNode, params: Optional[str] = None) → None

Insert a child node after the current.

Insert a child node right after the currently executing child node. NOTE: When inserting more than one node, they should be inserted in reverse order. This is because each node will be inserted right after the currently executing!

Parameters

node (TreeNode) – The node to be added
params (str (Default=None)) – The parameters of the added child node

remove_all_children() → None

Remove all child nodes.

Remove all child nodes from the SequenceNode. This is typically done in a contingency handler to modify the current execution sequence and adjust it to the current situation. New children which should be executed afterwards can be added with append_child or insert_child_after_current.

TreeNode

class carebt.treeNode.TreeNode(bt_runner: BehaviorTreeRunner, params: str = None)

Bases: abc.ABC

The careBT TreeNode class.

TreeNode is the basic class which provides the common implementation for all careBT nodes.

final abort() → None: Abort the current node.

final cancel_timeout_timer() → None: Cancel the timeout timer of the node.

final get_contingency_history() → list

Return the contincency-history.

Returns the contincency-history of the node. This history documents which contingencies occured during execution of the node.

Returns: The contingency history
Return type: list

final get_contingency_message() → str

Return the contincency-message.

Returns the contincency-message of the node. Typically this message is set in case the node completes with FAILURE to provide more details what went wrong.

Returns: The contingency message
Return type: str

final get_logger() → AbstractLogger

Return the current logger.

Return the current logger, which is an implementation of AbstractLogger.

Returns: The current logger
Return type: AbstractLogger

final get_status() → carebt.nodeStatus.NodeStatus

Return the current status of the node.

Returns: Current status of the node
Return type: NodeStatus

on_abort() → None

Is called on abort.

The on_abort callback is called in case the node is aborted.

on_delete() → None

Is called on deletion.

The on_delete callback is called if the node has completed execution. This allows to free blocked or allocated resources, especially when working with asynchronous actions.

on_init() → None

Is called on init.

The on_init callback is called right after the node is instantiated.

on_tick() → None

Is called on each tick.

The on_tick callback is called every time the Node is ticked by its parent node, considering the optional throttle rate.

on_timeout() → None

Is call if timeout occurs.

The on_timeout callback is called in case the node timed out. To set the timer use set_timeout.

final set_contingency_message(contingency_message: str) → None

Set the contincency-message.

Set the contincency-message of the node. Typically this message is set in case the node completes with FAILURE to provide more details what went wrong.

Parameters: contingency_message (str) – The contingency message

final set_status(node_status: carebt.nodeStatus.NodeStatus) → None

Set the current status of the node.

Parameters: node_status (NodeStatus) – Current status of the node

set_throttle_ms(throttle_ms: int) → None

Set the throttle rate in milliseconds.

Reduces the ticks the Nodes on_tick method is called to the provided throttle_ms value. For example, to reduce the calls of the on_tick callback to 500 milliseconds, the throttle_ms should be set to 500.

Parameters: throttle_ms (int) – The throttle rate in milliseconds

final set_timeout(timeout_ms: int) → None

Set the timeout.

Set a timeout and starts the timer. In case a timeout occures, the on_timeout callback is called.

Parameters: timeout_ms (int) – The timeout in milliseconds

careBT execution engine

BehaviorTreeRunner

class carebt.behaviorTreeRunner.BehaviorTreeRunner

Bases: object

The careBT BehaviorTreeRunner class.

The BehaviorTreeRunner is the interface to the careBT execution engine. With the run method a careBT behavior tree, respectively each careBT node can be executed.

get_contingency_message() → str

Return the contincency message of the last execution.

Returns: The contingency message
Return type: str

get_logger() → carebt.abstractLogger.AbstractLogger

Return the current logger.

Returns: The current logger
Return type: AbstractLogger

get_status() → carebt.nodeStatus.NodeStatus

Return the status of the last execution.

Returns: Current status of the node
Return type: NodeStatus

get_tick_count() → int

Return the current tick count.

Returns the current counter of the ticks the careBT execution engine has taken for the last execution of the run method.

Returns: Ticks taken for the behavior tree execution
Return type: int

run(node: carebt.treeNode.TreeNode, params: Optional[str] = None) → None

Execute the provided node, respectively the provided behavior tree.

Parameters

node (TreeNode) – The node which should be executed
params (str, optional) – The parameters for the node which should be executed

set_logger(logger: carebt.abstractLogger.AbstractLogger)

Set a custom logger.

Sets a custom logger which is then used by the careBT execution engine.

Parameters: logger (AbstractLogger) – A logger implementation

set_tick_rate_ms(tick_rate_ms: int) → None

Set the tick rate in milliseconds.

Sets the rate in milliseconds in which the careBT execution engine runs. It is the rate at which the nodes are ticked. Default is 50 ms.

Parameters: tick_rate_ms (int) – The tick rate in milliseconds

NodeStatus

class carebt.nodeStatus.NodeStatus(value)

Bases: enum.Enum

An Enum representing the status of a careBT node.

ABORTED = 5: Node has completed with ABORTED

FAILURE = 4: Node has completed with FAILURE

FIXED = 6: Node has completed with FIXED (by contingency-handler)

IDLE = 0: Node is waiting for first execution

RUNNING = 1: Node is currently executing

SUCCESS = 3: Node has completed with SUCCESS

SUSPENDED = 2: Node is currently executing, but on_tick() is not called

careBT logging

AbstractLogger

class carebt.abstractLogger.AbstractLogger

Bases: abc.ABC

The AbstractLogger interface.

The AbstractLogger interface has to be implemented for a custom logger.

abstract debug(msg: str)

abstract error(msg: str)

abstract info(msg: str)

set_log_level(log_level: carebt.abstractLogger.LogLevel)

abstract trace(msg: str)

abstract warn(msg: str)

class carebt.abstractLogger.LogLevel(value)

Bases: enum.IntEnum

An Enum representing the logging levels.

DEBUG = 1

ERROR = 4

INFO = 2

OFF = 5

TRACE = 0

WARN = 3

SimplePrintLogger

class carebt.simplePrintLogger.SimplePrintLogger

Bases: carebt.abstractLogger.AbstractLogger

The careBT SimplePrintLogger class.

A simple logger implementaion which prints the statements on standard output.

debug(msg: str)

error(msg: str)

info(msg: str)

trace(msg: str)

warn(msg: str)