From 67a92be87f8a00470313c232b1462d45379273e8 Mon Sep 17 00:00:00 2001
From: Shivang Patel <shivaang14@gmail.com>
Date: Wed, 23 Oct 2019 13:04:21 -0400
Subject: [PATCH] Add doxygen doc to nav2_controller (#1267)
* Add doxygen doc to nav2_controller
- Add doxygen doc to nav2_controller.hpp
- Add doxygen doc to progress_checker.hpp
* Address PR feedback
* Fix typo
- Refactored isGoalReached method doc
- Removed "flag" from reset method doc
---
.../nav2_controller/nav2_controller.hpp | 98 +++++++++++++++++--
.../nav2_controller/progress_checker.hpp | 28 +++++-
2 files changed, 119 insertions(+), 7 deletions(-)
diff --git a/nav2_controller/include/nav2_controller/nav2_controller.hpp b/nav2_controller/include/nav2_controller/nav2_controller.hpp
index 26c39283..c13f4344 100644
--- a/nav2_controller/include/nav2_controller/nav2_controller.hpp
+++ b/nav2_controller/include/nav2_controller/nav2_controller.hpp
@@ -34,39 +34,125 @@ namespace nav2_controller
{
class ProgressChecker;
-
+/**
+ * @class nav2_controller::ControllerServer
+ * @brief This class hosts variety of plugins of different algorithms to
+ * complete control tasks from the exposed FollowPath action server.
+ */
class ControllerServer : public nav2_util::LifecycleNode
{
public:
+ /**
+ * @brief Constructor for nav2_controller::ControllerServer
+ */
ControllerServer();
+ /**
+ * @brief Destructor for nav2_controller::ControllerServer
+ */
~ControllerServer();
protected:
- // The lifecycle interface
+ /**
+ * @brief Configures controller parameters and member variables
+ *
+ * Configures controller plugin and costmap; Initialize odom subscriber,
+ * velocity publisher and follow path action server.
+ * @param state LifeCycle Node's state
+ * @return Success or Failure
+ * @throw pluginlib::PluginlibException When failed to initialize controller
+ * plugin
+ */
nav2_util::CallbackReturn on_configure(const rclcpp_lifecycle::State & state) override;
+ /**
+ * @brief Activates member variables
+ *
+ * Activates controller, costmap, velocity publisher and follow path action
+ * server
+ * @param state LifeCycle Node's state
+ * @return Success or Failure
+ */
nav2_util::CallbackReturn on_activate(const rclcpp_lifecycle::State & state) override;
+ /**
+ * @brief Deactivates member variables
+ *
+ * Deactivates follow path action server, controller, costmap and velocity
+ * publisher. Before calling deactivate state, velocity is being set to zero.
+ * @param state LifeCycle Node's state
+ * @return Success or Failure
+ */
nav2_util::CallbackReturn on_deactivate(const rclcpp_lifecycle::State & state) override;
+ /**
+ * @brief Calls clean up states and resets member variables.
+ *
+ * Controller and costmap clean up state is called, and resets rest of the
+ * variables
+ * @param state LifeCycle Node's state
+ * @return Success or Failure
+ */
nav2_util::CallbackReturn on_cleanup(const rclcpp_lifecycle::State & state) override;
+ /**
+ * @brief Called when in Shutdown state
+ * @param state LifeCycle Node's state
+ * @return Success or Failure
+ */
nav2_util::CallbackReturn on_shutdown(const rclcpp_lifecycle::State & state) override;
+ /**
+ * @brief Called when in Error state
+ * @param state LifeCycle Node's state
+ * @return Success or Failure
+ */
nav2_util::CallbackReturn on_error(const rclcpp_lifecycle::State & state) override;
using ActionServer = nav2_util::SimpleActionServer<nav2_msgs::action::FollowPath>;
// Our action server implements the FollowPath action
std::unique_ptr<ActionServer> action_server_;
-
- // The action server callback
+ /**
+ * @brief FollowPath action server callback. Handles action server updates and
+ * spins server until goal is reached
+ *
+ * Provides global path to controller received from action client. Twist
+ * velocities for the robot are calculated and published using controller at
+ * the specified rate till the goal is reached.
+ * @throw nav2_core::PlannerException
+ */
void followPath();
-
+ /**
+ * @brief Assigns path to controller
+ * @param path Path received from action server
+ */
void setPlannerPath(const nav_msgs::msg::Path & path);
+ /**
+ * @brief Calculates velocity and publishes to "cmd_vel" topic
+ */
void computeAndPublishVelocity();
+ /**
+ * @brief Calls setPlannerPath method with an updated path received from
+ * action server
+ */
void updateGlobalPath();
+ /**
+ * @brief Calls velocity publisher to publish the velocity on "cmd_vel" topic
+ * @param velocity Twist velocity to be published
+ */
void publishVelocity(const geometry_msgs::msg::TwistStamped & velocity);
+ /**
+ * @brief Calls velocity publisher to publish zero velocity
+ */
void publishZeroVelocity();
+ /**
+ * @brief Checks if goal is reached
+ * @return true or false
+ */
bool isGoalReached();
+ /**
+ * @brief Obtain current pose of the robot
+ * @param pose To store current pose of the robot
+ * @return true if able to obtain current pose of the robot, else false
+ */
bool getRobotPose(geometry_msgs::msg::PoseStamped & pose);
- // The local controller needs a costmap node
+ // The controller needs a costmap node
std::shared_ptr<nav2_costmap_2d::Costmap2DROS> costmap_ros_;
std::unique_ptr<nav2_util::NodeThread> costmap_thread_;
diff --git a/nav2_controller/include/nav2_controller/progress_checker.hpp b/nav2_controller/include/nav2_controller/progress_checker.hpp
index ab929053..fc87316e 100644
--- a/nav2_controller/include/nav2_controller/progress_checker.hpp
+++ b/nav2_controller/include/nav2_controller/progress_checker.hpp
@@ -21,16 +21,42 @@
namespace nav2_controller
{
-
+/**
+ * @class nav2_controller::ProgressChecker
+ * @brief This class is used to check the position of the robot to make sure
+ * that it is actually progressing towards a goal.
+ */
class ProgressChecker
{
public:
+ /**
+ * @brief Constructor of ProgressChecker
+ * @param node Node pointer
+ */
explicit ProgressChecker(const rclcpp::Node::SharedPtr & node);
+ /**
+ * @brief Checks if the robot has moved compare to previous
+ * pose
+ * @param current_pose Current pose of the robot
+ * @throw nav2_core::PlannerException when failed to make progress
+ */
void check(geometry_msgs::msg::PoseStamped & current_pose);
+ /**
+ * @brief Reset class state upon calling
+ */
void reset() {baseline_pose_set_ = false;}
protected:
+ /**
+ * @brief Calculates robots movement from baseline pose
+ * @param pose Current pose of the robot
+ * @return true, if movement is greater than radius_, or false
+ */
bool is_robot_moved_enough(const geometry_msgs::msg::Pose2D & pose);
+ /**
+ * @brief Resets baseline pose with the current pose of the robot
+ * @param pose Current pose of the robot
+ */
void reset_baseline_pose(const geometry_msgs::msg::Pose2D & pose);
rclcpp::Node::SharedPtr nh_;
--
GitLab