# blackcoffeerobotics/vector_pursuit_controller architecture

> Architecture diagram of the GitHub repository blackcoffeerobotics/vector_pursuit_controller, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/blackcoffeerobotics/vector_pursuit_controller
- Repository: https://github.com/blackcoffeerobotics/vector_pursuit_controller

## Overview

##### Project Type and Purpose
- This is a ROS 2 “controller plugin” package for the Nav2 Controller Server.
- Purpose: implement the Vector Pursuit path‐tracking algorithm as a drop-in plugin to the Nav2 stack, providing precise, collision‐aware velocity commands for differential‐drive robots.

##### File Structure
- Top‐level files: CMakeLists.txt, package.xml (build and packaging), README.md (documentation), LICENSE, CHANGELOG.
- config/: YAML and PGM map files; default parameters for plugin and mappings.
- /vector_pursuit_controller: public C++ headers.
- src/vector_pursuit_controller.cpp: plugin implementation.
- launch/: ROS 2 launch script to spin up Nav2 + this plugin in simulation (bcr_bot_demo.launch.py).
- test/: CMakeLists and unit tests for path utilities and core controller logic.
- vector_pursuit_controller.xml: pluginlib manifest for Nav2 to discover the plugin.

##### Extract Key Architectural Insights from README
- The plugin lives inside the Nav2 Controller Server (using pluginlib).
- It subscribes to: planned Path, odometry, costmap or other obstacle data via ROS 2 topics/services.
- It publishes geometry_msgs/Twist velocity commands.
- Configuration is driven by ROS 2 parameters (loaded from YAML in config/ or via the launch file).
- Can be run in simulation (Gazebo via ros_gz_bridge) or on real robot hardware.

##### Main Components to Display
a. ROS 2 Core / DDS Middleware
b. Nav2 Stack:
- Lifecycle Manager
- Controller Server
c. Vector Pursuit Controller Plugin
- Implements nav2_controller::Controller interface
- Path subscriber
- TF2 listener
- Collision checker (costmap subscriber or service)
- Screw‐theory based algorithm module
d. Robot Hardware Interface (or Gazebo Simulation via ros_gz_bridge)
e. Parameter Server / YAML Configuration
f. Unit Test Suite (optional side component)

##### Relationships and Data Flows
- Nav2 Lifecycle Manager → starts Controller Server
- Controller Server loads vector_pursuit_controller via pluginlib (vector_pursuit_controller.xml)
- Plugin subscribes to:
- /plan (nav_msgs/Path) from the Planner component of Nav2
- /odom (nav_msgs/Odometry) or /tf
- /costmap (nav2_msgs/Costmap) for collision detection
and uses config parameters from the Parameter Server.
- Plugin computes velocity commands (geometry_msgs/Twist) → publishes to /cmd_vel
- /cmd_vel → Robot Hardware Driver (or Gazebo Bridge)

##### Architectural Patterns and Design Principles
- Plugin architecture (Nav2 uses pluginlib; vector_pursuit_controller registers itself).
- ROS 2 node‐based, asynchronous pub/sub and service calls.
- Separation of concerns: planning (Nav2 Planner) vs. control (this plugin) vs. actuation.
- Configuration via ROS 2 parameters loaded from YAML.
- Unit tests separated from production code.

##### What to Label
- Config store: “YAML parameters: lookahead_dist, k, max_accel, …”.
- Plugin manifest: “vector_pursuit_controller.xml (pluginlib)”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Middleware
    ROS2Core["ROS 2 Core / DDS"]:::ros

    %% Parameter Server
    Params["YAML Parameters<br/>lookahead_dist, k, max_accel, …"]:::param

    %% Nav2 Stack
    subgraph "Nav2 Stack" 
        direction TB
        LM["Lifecycle Manager"]:::ros
        CS["Controller Server"]:::ros
    end

    %% Planner and Data Sources
    Planner["Nav2 Planner<br/>(nav_msgs/Path)"]:::ros
    OdomTF["Odometry / TF 2<br/>(nav_msgs/Odometry)"]:::ros
    Costmap["Costmap Subscriber<br/>(nav2_msgs/Costmap)"]:::ros

    %% Vector Pursuit Plugin
    subgraph "Vector Pursuit Controller Plugin" 
        direction TB
        VPC["VectorPursuitController<br/>(plugin)"]:::plugin
        subgraph "Internal Modules"
            direction TB
            PathSub["Path Subscriber"]:::plugin
            TFListener["TF2 Listener"]:::plugin
            CollisionDetect["Collision Checker"]:::plugin
            ScrewEngine["Screw Theory Engine"]:::plugin
        end
    end

    %% Actuation
    CmdVel["/cmd_vel<br/>(geometry_msgs/Twist)"]:::ros
    extCloud["Robot Hardware / Gazebo<br/>Simulation"]:::external

    %% Unit Tests
    Tests["Unit Test Suite<br/>PathUtils & Controller"]:::test

    %% Relationships
    ROS2Core --> LM
    LM --> CS
    CS -->|loads plugin via pluginlib| VPC
    Planner -->|nav_msgs/Path| VPC
    OdomTF -->|nav_msgs/Odometry / TF| VPC
    Costmap -->|nav2_msgs/Costmap| VPC
    Params -->|ROS 2 parameters| VPC
    VPC -->|geometry_msgs/Twist| CmdVel
    CmdVel --> extCloud

    %% Styling
    classDef ros fill:#dae8fc,stroke:#6c8ebf,color:#1f3659
    classDef plugin fill:#d5e8d4,stroke:#82b366,color:#274e13
    classDef external fill:#ffe6cc,stroke:#d79b00,color:#663c00
    classDef param fill:#fff2cc,stroke:#d6b656,color:#665c00
    classDef test fill:#f2f2f2,stroke:#999999,color:#333333

    %% Click Events
    click VPC "https://github.com/blackcoffeerobotics/vector_pursuit_controller/blob/master/include/vector_pursuit_controller/vector_pursuit_controller.hpp"
    click VPC "https://github.com/blackcoffeerobotics/vector_pursuit_controller/blob/master/src/vector_pursuit_controller.cpp"
    click VPC "https://github.com/blackcoffeerobotics/vector_pursuit_controller/blob/master/vector_pursuit_controller.xml"
    click Params "https://github.com/blackcoffeerobotics/vector_pursuit_controller/blob/master/config/sample_nav2_params.yaml"
    click Params "https://github.com/blackcoffeerobotics/vector_pursuit_controller/blob/master/config/bcr_map.yaml"
    click extCloud "https://github.com/blackcoffeerobotics/vector_pursuit_controller/blob/master/config/bcr_map.pgm"
    click Tests "https://github.com/blackcoffeerobotics/vector_pursuit_controller/blob/master/test/path_utils/path_utils.cpp"
    click Tests "https://github.com/blackcoffeerobotics/vector_pursuit_controller/blob/master/test/path_utils/path_utils.hpp"
    click Tests "https://github.com/blackcoffeerobotics/vector_pursuit_controller/blob/master/test/path_utils/test_path_utils.cpp"
    click Tests "https://github.com/blackcoffeerobotics/vector_pursuit_controller/blob/master/test/test_vector_pursuit.cpp"
    click Tests "https://github.com/blackcoffeerobotics/vector_pursuit_controller/blob/master/test/CMakeLists.txt"
    click LM "https://github.com/blackcoffeerobotics/vector_pursuit_controller/blob/master/CMakeLists.txt"
    click LM "https://github.com/blackcoffeerobotics/vector_pursuit_controller/blob/master/package.xml"
    click LM "https://github.com/blackcoffeerobotics/vector_pursuit_controller/blob/master/CHANGELOG.rst"
    click LM "https://github.com/blackcoffeerobotics/vector_pursuit_controller/blob/master/README.md"
    click LM "https://github.com/blackcoffeerobotics/vector_pursuit_controller/tree/master/LICENSE"
    click ROS2Core "https://github.com/blackcoffeerobotics/vector_pursuit_controller/blob/master/code_coverage_report.info"
```
