# keerthisagarsn/coresense_bt_controller architecture

> Architecture diagram of the GitHub repository keerthisagarsn/coresense_bt_controller, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/keerthisagarsn/coresense_bt_controller
- Repository: https://github.com/keerthisagarsn/coresense_bt_controller

## Overview

#### 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: [`src/bt_controller.cpp`](https://github.com/keerthisagarsn/coresense_bt_controller/blob/main/src/bt_controller.cpp) (BT controller), [`src/tree_execution_client_bt_action.cpp`](https://github.com/keerthisagarsn/coresense_bt_controller/blob/main/src/tree_execution_client_bt_action.cpp) (Tree execution client), [`CMakeLists.txt`](https://github.com/keerthisagarsn/coresense_bt_controller/blob/main/CMakeLists.txt) (CMake build), [`launch/bt_controller.launch.py`](https://github.com/keerthisagarsn/coresense_bt_controller/blob/main/launch/bt_controller.launch.py) (Controller launch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_package["ROS 2 Package"]
  node_cmake["CMake build<br/>build definition<br/>[CMakeLists.txt]"]
  node_package_xml["Package manifest<br/>ament package<br/>[package.xml]"]
  node_launch["Controller launch<br/>ROS launch"]
  node_config["Controller parameters<br/>YAML config<br/>[bt_controller.yaml]"]
end

subgraph group_runtime["Controller Runtime"]
  node_controller_header["Controller interface<br/>C++ API<br/>[bt_controller.hpp]"]
  node_controller["BT controller<br/>ROS 2 executable<br/>[bt_controller.cpp]"]
  node_bt_factory["BT factory/runtime<br/>BehaviorTree.CPP"]
  node_action_header["Action BT node interface<br/>C++ API"]
  node_action_client["Tree execution client<br/>BT ROS action node"]
end

subgraph group_tree["Behavior Tree"]
  node_tree_xml["Decision tree<br/>BT XML asset<br/>[decision_tree1.xml]"]
  node_tree_execution["Tree ticking<br/>execution loop"]
end

subgraph group_external["External ROS System"]
  node_ros_action_server{{"ROS action server<br/>external service"}}
end

node_cmake -->|"builds"| node_controller
node_package_xml -->|"declares package dependencies"| node_cmake
node_launch -->|"starts"| node_controller
node_config -->|"supplies parameters"| node_launch
node_controller_header -->|"defines interface"| node_controller
node_controller -->|"initializes"| node_bt_factory
node_controller -->|"loads"| node_tree_xml
node_bt_factory -->|"registers node type"| node_action_client
node_action_header -->|"defines interface"| node_action_client
node_tree_xml -->|"defines control flow"| node_tree_execution
node_bt_factory -->|"instantiates"| node_tree_execution
node_controller -->|"drives ticks"| node_tree_execution
node_tree_execution -->|"invokes"| node_action_client
node_action_client -->|"sends goals and observes results"| node_ros_action_server
node_action_client -->|"returns BT status"| node_tree_execution

click node_cmake "https://github.com/keerthisagarsn/coresense_bt_controller/blob/main/CMakeLists.txt"
click node_package_xml "https://github.com/keerthisagarsn/coresense_bt_controller/blob/main/package.xml"
click node_launch "https://github.com/keerthisagarsn/coresense_bt_controller/blob/main/launch/bt_controller.launch.py"
click node_config "https://github.com/keerthisagarsn/coresense_bt_controller/blob/main/config/bt_controller.yaml"
click node_controller_header "https://github.com/keerthisagarsn/coresense_bt_controller/blob/main/include/coresense_bt_controller/bt_controller.hpp"
click node_controller "https://github.com/keerthisagarsn/coresense_bt_controller/blob/main/src/bt_controller.cpp"
click node_action_header "https://github.com/keerthisagarsn/coresense_bt_controller/blob/main/include/coresense_bt_controller/tree_execution_client_bt_action.hpp"
click node_action_client "https://github.com/keerthisagarsn/coresense_bt_controller/blob/main/src/tree_execution_client_bt_action.cpp"
click node_tree_xml "https://github.com/keerthisagarsn/coresense_bt_controller/blob/main/behavior_trees/decision_tree1.xml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmake,node_package_xml,node_launch,node_config toneBlue
class node_controller_header,node_controller,node_bt_factory,node_action_header,node_action_client toneAmber
class node_tree_xml,node_tree_execution toneMint
class node_ros_action_server toneRose
```

## Components

### ROS 2 Package

- [CMake build](https://github.com/keerthisagarsn/coresense_bt_controller/blob/main/CMakeLists.txt): build definition · `CMakeLists.txt`
- [Package manifest](https://github.com/keerthisagarsn/coresense_bt_controller/blob/main/package.xml): ament package · `package.xml`
- [Controller launch](https://github.com/keerthisagarsn/coresense_bt_controller/blob/main/launch/bt_controller.launch.py): ROS launch · `launch/bt_controller.launch.py`
- [Controller parameters](https://github.com/keerthisagarsn/coresense_bt_controller/blob/main/config/bt_controller.yaml): YAML config · `config/bt_controller.yaml`

### Controller Runtime

- [Controller interface](https://github.com/keerthisagarsn/coresense_bt_controller/blob/main/include/coresense_bt_controller/bt_controller.hpp): C++ API · `include/coresense_bt_controller/bt_controller.hpp`
- [BT controller](https://github.com/keerthisagarsn/coresense_bt_controller/blob/main/src/bt_controller.cpp): ROS 2 executable · Initializes ROS, registers nodes, loads the tree, and drives ticks. · `src/bt_controller.cpp`
- **BT factory/runtime**: BehaviorTree.CPP · Registers custom node types and instantiates the XML tree.
- [Action BT node interface](https://github.com/keerthisagarsn/coresense_bt_controller/blob/main/include/coresense_bt_controller/tree_execution_client_bt_action.hpp): C++ API · `include/coresense_bt_controller/tree_execution_client_bt_action.hpp`
- [Tree execution client](https://github.com/keerthisagarsn/coresense_bt_controller/blob/main/src/tree_execution_client_bt_action.cpp): BT ROS action node · Maps asynchronous ROS action state to BT success, failure, or running. · `src/tree_execution_client_bt_action.cpp`

### Behavior Tree

- [Decision tree](https://github.com/keerthisagarsn/coresense_bt_controller/blob/main/behavior_trees/decision_tree1.xml): BT XML asset · Defines orchestration, branching, retries, and action invocation. · `behavior_trees/decision_tree1.xml`
- **Tree ticking**: execution loop · Traverses instantiated control and action nodes until a terminal state.

### External ROS System

- **ROS action server**: external service · Concrete action type and server are outside this repository.

## Connections

- 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