How blackcoffeerobotics/vector_pursuit_controller works
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)”