From 1ca7ce2ddd2eff74428b805be83bcbf75dcaf10a Mon Sep 17 00:00:00 2001 From: Alberto Tudela Date: Mon, 5 Feb 2024 22:35:03 +0100 Subject: [PATCH] Documentation for Graceful Motion (#517) * Documentation for Graceful Motion Signed-off-by: Alberto Tudela * Minor fix --------- Signed-off-by: Alberto Tudela --- configuration/index.rst | 1 + ...configuring-graceful-motion-controller.rst | 232 ++++++++++++++++++ migration/Iron.rst | 7 + plugins/index.rst | 51 ++-- 4 files changed, 268 insertions(+), 23 deletions(-) create mode 100644 configuration/packages/configuring-graceful-motion-controller.rst diff --git a/configuration/index.rst b/configuration/index.rst index b085b32ea..50f00ed7a 100644 --- a/configuration/index.rst +++ b/configuration/index.rst @@ -23,6 +23,7 @@ the best navigation performance. packages/configuring-regulated-pp.rst packages/configuring-mppic.rst packages/configuring-rotation-shim-controller.rst + packages/configuring-graceful-motion-controller.rst packages/configuring-map-server.rst packages/configuring-amcl.rst packages/configuring-behavior-server.rst diff --git a/configuration/packages/configuring-graceful-motion-controller.rst b/configuration/packages/configuring-graceful-motion-controller.rst new file mode 100644 index 000000000..6987b490b --- /dev/null +++ b/configuration/packages/configuring-graceful-motion-controller.rst @@ -0,0 +1,232 @@ +.. _configuring_graceful_motion_controller: + +Graceful Motion Controller +########################## + +Source code on Github_. + +.. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_graceful_motion_controller + +The graceful motion controller implements a controller based on the works of Jong Jin Park and Benjamin Kuipers in "A Smooth Control Law for Graceful Motion of Differential Wheeled Mobile Robots in 2D Environment" (ICRA 2011). In this implementation, a `motion_target` is set at a distance away from the robot that is exponentially stable to generate a smooth trajectory for the robot to follow. + +See the package's ``README`` for more complete information. + +Graceful Motion Controller Parameters +************************************* + +:transform_tolerance: + + ============== =========================== + Type Default + -------------- --------------------------- + double 0.1 + ============== =========================== + + Description + The TF transform tolerance (s). + +:motion_target_dist: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.6 + ============== ============================= + + Description + The lookahead distance (m) to use to find the motion_target point. + +:max_robot_pose_search_dist: + + ============== ================================================= + Type Default + -------------- ------------------------------------------------- + double Local costmap max extent (max(width, height) / 2) + ============== ================================================= + + Description + Upper bound on integrated distance along the global plan to search for the closest pose to the robot pose. This should be left as the default unless there are paths with loops and intersections that do not leave the local costmap, in which case making this value smaller is necessary to prevent shortcutting. If set to ``-1``, it will use the maximum distance possible to search every point on the path for the nearest path point. + +:k_phi: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 3.0 + ============== ============================= + + Description + Ratio of the rate of change in phi to the rate of change in r. Controls the convergence of the slow subsystem. If this value is equal to zero, the controller will behave as a pure waypoint follower. A high value offers extreme scenario of pose-following where theta is reduced much faster than r. + +:k_delta: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 2.0 + ============== ============================= + + Description + Constant factor applied to the heading error feedback. Controls the convergence of the fast subsystem. The bigger the value, the robot converge faster to the reference heading. + +:beta: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.2 + ============== ============================= + + Description + Constant factor applied to the path curvature. This value must be positive. Determines how fast the velocity drops when the curvature increases. + +:lambda: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 2.0 + ============== ============================= + + Description + Constant factor applied to the path curvature. This value must be greater or equal to 1. Determines the sharpness of the curve: higher lambda implies sharper curves. + +:v_linear_min: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.1 + ============== ============================= + + Description + Minimum linear velocity (m/s). + +:v_linear_max: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.5 + ============== ============================= + + Description + Maximum linear velocity (m/s). + +:v_angular_max: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 1.0 + ============== ============================= + + Description + Maximum angular velocity (rad/s) produced by the control law. + +:slowdown_radius: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 1.5 + ============== ============================= + + Description + Radius (m) around the goal pose in which the robot will start to slow down. + +:initial_rotation: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= + + Description + Enable a rotation in place to the goal before starting the path. The control law may generate large sweeping arcs to the goal pose, depending on the initial robot orientation and ``k_phi``, ``k_delta``. + +:initial_rotation_min_angle: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.75 + ============== ============================= + + Description + The difference in the path orientation and the starting robot orientation to trigger a rotate in place, if ``initial_rotation`` is enabled. + +:final_rotation: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= + + Description + Similar to ``initial_rotation``, the control law can generate large arcs when the goal orientation is not aligned with the path. If this is enabled, the final pose will be ignored and the robot will follow the orientation of he path and will make a final rotation in place to the goal orientation. + +:rotation_scaling_factor: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.5 + ============== ============================= + + Description + The scaling factor applied to the rotation in place velocity. + +:allow_backward: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool false + ============== ============================= + + Description + Whether to allow the robot to move backward. + +Example +******* +.. code-block:: yaml + + controller_server: + ros__parameters: + use_sim_time: True + controller_frequency: 20.0 + min_x_velocity_threshold: 0.001 + min_y_velocity_threshold: 0.5 + min_theta_velocity_threshold: 0.001 + progress_checker_plugins: ["progress_checker"] # progress_checker_plugin: "progress_checker" For Humble and older + goal_checker_plugins: ["goal_checker"] + controller_plugins: ["FollowPath"] + + progress_checker: + plugin: "nav2_controller::SimpleProgressChecker" + required_movement_radius: 0.5 + movement_time_allowance: 10.0 + goal_checker: + plugin: "nav2_controller::SimpleGoalChecker" + xy_goal_tolerance: 0.25 + yaw_goal_tolerance: 0.25 + stateful: True + FollowPath: + plugin: nav2_graceful_motion_controller::GracefulMotionController + transform_tolerance: 0.1 + motion_target_dist: 0.6 + initial_rotation: true + initial_rotation_min_angle: 0.75 + final_rotation: true + allow_backward: false + k_phi: 3.0 + k_delta: 2.0 + beta: 0.4 + lambda: 2.0 + v_linear_min: 0.1 + v_linear_max: 1.0 + v_angular_max: 5.0 + slowdown_radius: 1.5 diff --git a/migration/Iron.rst b/migration/Iron.rst index 41fdbc7e6..30fde7214 100644 --- a/migration/Iron.rst +++ b/migration/Iron.rst @@ -223,3 +223,10 @@ Full Stack Uses Node Clocks *************************** The stack no longer contains wall timers or wall rates. It will now use the node clocks. This will be ROS Time for simulation when ``use_sim_time`` is true. Else, it uses a steady clock. + +New Graceful Motion Controller +****************************** + +`PR #4021 `_ introduces a new type of controller for differential robots based on a pose-following kinematic control law that generates a smooth and confortable trajectory. + +See :ref:`configuring_graceful_motion_controller` for more information. \ No newline at end of file diff --git a/plugins/index.rst b/plugins/index.rst index 69e062f7a..d1281e020 100644 --- a/plugins/index.rst +++ b/plugins/index.rst @@ -103,35 +103,40 @@ Costmap Filters Controllers =========== -+----------------------------+--------------------+----------------------------------+-----------------------+ -| Plugin Name | Creator | Description | Drivetrain support | -+============================+====================+==================================+=======================+ -| `DWB Controller`_ | David Lu!! | A highly configurable DWA | Differential, | -| | | implementation with plugin | Omnidirectional, | -| | | interfaces | Legged | -+----------------------------+--------------------+----------------------------------+-----------------------+ -| `TEB Controller`_ | Christoph Rösmann | A MPC-like controller suitable | **Ackermann**, Legged,| -| | | for ackermann, differential, and | Omnidirectional, | -| | | holonomic robots. | Differential | -+----------------------------+--------------------+----------------------------------+-----------------------+ -| `Regulated Pure Pursuit`_ | Steve Macenski | A service / industrial robot | **Ackermann**, Legged,| -| | | variation on the pure pursuit | Differential | -| | | algorithm with adaptive features.| | -+----------------------------+--------------------+----------------------------------+-----------------------+ -| `MPPI Controller`_ | Steve Macenski | A predictive MPC controller with | Differential, Omni, | -| | Aleksei Budyakov | modular & custom cost functions | **Ackermann** | -| | | that can accomplish many tasks. | | -+----------------------------+--------------------+----------------------------------+-----------------------+ -| `Rotation Shim Controller`_| Steve Macenski | A "shim" controller to rotate | Differential, Omni, | -| | | to path heading before passing | model rotate in place | -| | | to main controller for tracking.| | -+----------------------------+--------------------+----------------------------------+-----------------------+ ++--------------------------------+--------------------+----------------------------------+-----------------------+ +| Plugin Name | Creator | Description | Drivetrain support | ++================================+====================+==================================+=======================+ +| `DWB Controller`_ | David Lu!! | A highly configurable DWA | Differential, | +| | | implementation with plugin | Omnidirectional, | +| | | interfaces | Legged | ++--------------------------------+--------------------+----------------------------------+-----------------------+ +| `TEB Controller`_ | Christoph Rösmann | A MPC-like controller suitable | **Ackermann**, Legged,| +| | | for ackermann, differential, and | Omnidirectional, | +| | | holonomic robots. | Differential | ++--------------------------------+--------------------+----------------------------------+-----------------------+ +| `Regulated Pure Pursuit`_ | Steve Macenski | A service / industrial robot | **Ackermann**, Legged,| +| | | variation on the pure pursuit | Differential | +| | | algorithm with adaptive features.| | ++--------------------------------+--------------------+----------------------------------+-----------------------+ +| `MPPI Controller`_ | Steve Macenski | A predictive MPC controller with | Differential, Omni, | +| | Aleksei Budyakov | modular & custom cost functions | **Ackermann** | +| | | that can accomplish many tasks. | | ++--------------------------------+--------------------+----------------------------------+-----------------------+ +| `Rotation Shim Controller`_ | Steve Macenski | A "shim" controller to rotate | Differential, Omni, | +| | | to path heading before passing | model rotate in place | +| | | to main controller for tracking.| | ++--------------------------------+--------------------+----------------------------------+-----------------------+ +| `Graceful Motion Controller`_ | Alberto Tudela | A controller based on a | Differential | +| | | pose-following control law to | | +| | | generate smooth trajectories. | | ++--------------------------------+--------------------+----------------------------------+-----------------------+ .. _DWB Controller: https://github.com/ros-planning/navigation2/tree/main/nav2_dwb_controller .. _TEB Controller: https://github.com/rst-tu-dortmund/teb_local_planner .. _Regulated Pure Pursuit: https://github.com/ros-planning/navigation2/tree/main/nav2_regulated_pure_pursuit_controller .. _Rotation Shim Controller: https://github.com/ros-planning/navigation2/tree/main/nav2_rotation_shim_controller .. _MPPI Controller: https://github.com/ros-planning/navigation2/tree/main/nav2_mppi_controller +.. _Graceful Motion Controller: https://github.com/ros-planning/navigation2/tree/main/nav2_graceful_motion_controller Planners ========