How keerthisagarsn/coresense_bt_controller works
Purpose and Entry Points
This is a ROS 2 C++ package that runs a BehaviorTree.CPP-based controller. It loads a behavior-tree XML definition, exposes/consumes ROS actions through custom BT nodes, and executes the tree under ROS launch.
Primary entry points:
• Build/package definition: CMakeLists.txt, package.xml
• ROS launch entry point: launch/bt_controller.launch.py
• Controller executable implementation: src/bt_controller.cpp
• Default tree asset: behavior_trees/decision_tree1.xml
Controller Runtime
src/bt_controller.cpp implements the main ROS 2 node/controller runtime, with its public interface in include/coresense_bt_controller/bt_controller.hpp. It is responsible for initializing ROS-facing controller state, registering behavior-tree node types, loading the selected XML tree, and driving tree execution.
The controller is configured externally rather than hard-coding runtime settings:
• config/bt_controller.yaml
• launch/bt_controller.launch.py
• behavior_trees/decision_tree1.xml
Behavior Tree Definition Boundary
Behavior logic is represented as XML assets, separating orchestration policy from C++ node implementation:
• behavior_trees/decision_tree1.xml
• src/bt_controller.cpp
The XML tree determines control flow—such as sequencing, branching, retries, or action invocation—while the C++ controller provides the BehaviorTree.CPP factory/runtime integration. This makes tree policy replaceable without changing the controller executable, provided referenced node registrations remain available.
Custom ROS Action BT Node
TreeExecutionClientBtAction is the architecture-defining adapter between BehaviorTree.CPP and ROS 2 action execution:
• include/coresense_bt_controller/tree_execution_client_bt_action.hpp
• src/tree_execution_client_bt_action.cpp
• src/bt_controller.cpp
This component acts as a BT action node/client: tree ticks initiate or monitor an asynchronous ROS action request, action feedback/result state is translated into BT node status, and completion/failure determines subsequent XML-defined control flow. It is the principal boundary between synchronous tree ticking and asynchronous ROS middleware communication.
Data and Control Flow
1. ROS 2 launch starts the controller using launch/bt_controller.launch.py.
2. Parameters from config/bt_controller.yaml select or configure controller/tree behavior.
3. src/bt_controller.cpp initializes the controller and BehaviorTree.CPP factory.
4. The controller loads behavior_trees/decision_tree1.xml.
5. Tree ticks traverse XML-defined control nodes and invoke registered custom nodes.
6. TreeExecutionClientBtAction sends and observes ROS action work, returning BT success, failure, or running state.
7. The controller continues ticking until the tree reaches its terminal outcome or the ROS node shuts down.
Infrastructure and Dependencies
The package is built with CMake and distributed as an ament/ROS 2 package:
• CMakeLists.txt
• package.xml
Material runtimes are ROS 2 (rclcpp-style node/action infrastructure implied by the package structure), BehaviorTree.CPP, ROS launch, YAML parameters, and XML behavior-tree assets. The external service boundary is a ROS 2 action server consumed by the tree-execution client node; its concrete action type/server is implemented outside this repository.
Main entry points: bt_controller.cpp BT controller · tree_execution_client_bt_action.cpp Tree execution client · CMakeLists.txt CMake build · bt_controller.launch.py Controller launch
Components 12
ROS 2 Package
- CMake build
CMakeLists.txt - Package manifest
package.xml - Controller launch
launch/bt_controller.launch.py - Controller parameters
config/bt_controller.yaml
Controller Runtime
- Controller interface
include/coresense_bt_controller/bt_controller.hpp - BT controller · Initializes ROS, registers nodes, loads the tree, and drives ticks.
src/bt_controller.cpp - BT factory/runtime · Registers custom node types and instantiates the XML tree.
- Action BT node interface
include/coresense_bt_controller/tree_execution_client_bt_action.hpp - Tree execution client · Maps asynchronous ROS action state to BT success, failure, or running.
src/tree_execution_client_bt_action.cpp
Behavior Tree
- Decision tree · Defines orchestration, branching, retries, and action invocation.
behavior_trees/decision_tree1.xml - Tree ticking · Traverses instantiated control and action nodes until a terminal state.
External ROS System
- ROS action server · Concrete action type and server are outside this repository.
Connections 15
- CMake build → BT controller: builds
- Package manifest → CMake build: declares package dependencies
- Controller launch → BT controller: starts
- Controller parameters → Controller launch: supplies parameters
- Controller interface → BT controller: defines interface
- BT controller → BT factory/runtime: initializes
- BT controller → Decision tree: loads
- BT factory/runtime → Tree execution client: registers node type
- Action BT node interface → Tree execution client: defines interface
- Decision tree → Tree ticking: defines control flow
- BT factory/runtime → Tree ticking: instantiates
- BT controller → Tree ticking: drives ticks
- Tree ticking → Tree execution client: invokes
- Tree execution client → ROS action server: sends goals and observes results
- Tree execution client → Tree ticking: returns BT status