Deprecate forward_command_controller specializations (#1913)

christophfroehlich · web-flow · commit 61b3bc601582 · 2025-11-19T21:41:29.000+01:00
diff --git a/doc/controllers_index.rst b/doc/controllers_index.rst
@@ -36,16 +36,6 @@ Controllers for Wheeled Mobile Robots
 Controllers for Manipulators and Other Robots
 *********************************************
 
-The controllers are using `common hardware interface definitions`_, and may use namespaces depending on the following command interface types:
-
-  - ``position_controllers``: ``hardware_interface::HW_IF_POSITION``
-  - ``velocity_controller``: ``hardware_interface::HW_IF_VELOCITY``
-  - ``effort_controllers``: ``hardware_interface::HW_IF_ACCELERATION``
-  - ``effort_controllers``: ``hardware_interface::HW_IF_EFFORT``
-
-.. _common hardware interface definitions: https://github.com/ros-controls/ros2_control/blob/{REPOS_FILE_BRANCH}/hardware_interface/include/hardware_interface/types/hardware_interface_type_values.hpp
-
-
 .. toctree::
    :titlesonly:
 
diff --git a/doc/migration.rst b/doc/migration.rst
@@ -2,5 +2,17 @@
 
 Migration Guides: Kilted Kaiju to Lyrical Luth
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
 This list summarizes important changes between Kilted Kaiju (previous) and Lyrical Luth (current) releases, where changes to user code might be necessary.
+
+
+effort_controllers
+*****************************
+* ``effort_controllers/JointGroupEffortController`` is deprecated. Use :ref:`forward_command_controller <forward_command_controller_userdoc>` instead by adding the ``interface_name`` parameter and set it to ``effort``. (`#1913 <https://github.com/ros-controls/ros2_controllers/pull/1913>`_).
+
+position_controllers
+*****************************
+* ``position_controllers/JointGroupPositionController`` is deprecated. Use :ref:`forward_command_controller <forward_command_controller_userdoc>` instead by adding the ``interface_name`` parameter and set it to ``position``. (`#1913 <https://github.com/ros-controls/ros2_controllers/pull/1913>`_).
+
+velocity_controllers
+*****************************
+*  ``velocity_controllers/JointGroupVelocityController`` is deprecated. Use :ref:`forward_command_controller <forward_command_controller_userdoc>` instead by adding the ``interface_name`` parameter and set it to ``velocity``. (`#1913 <https://github.com/ros-controls/ros2_controllers/pull/1913>`_).
diff --git a/effort_controllers/doc/userdoc.rst b/effort_controllers/doc/userdoc.rst
@@ -12,6 +12,10 @@ The package contains the following controllers:
 effort_controllers/JointGroupEffortController
 -------------------------------------------------
 
+.. warning::
+
+  ``effort_controllers/JointGroupEffortController`` is deprecated. Use :ref:`forward_command_controller <forward_command_controller_userdoc>` instead by adding the ``interface_name`` parameter and set it to ``effort``.
+
 This is specialization of the :ref:`forward_command_controller <forward_command_controller_userdoc>` that works using the "effort" joint interface.
 
 
diff --git a/effort_controllers/package.xml b/effort_controllers/package.xml
@@ -34,5 +34,10 @@
 
   <export>
     <build_type>ament_cmake</build_type>
+    <deprecated>
+      This package will be removed in ROS 2 Lyrical Luth. Instead, use
+      forward_command_controller, see migration guides for details:
+      https://control.ros.org/rolling/doc/ros2_controllers/doc/migration.html
+    </deprecated>
   </export>
 </package>
diff --git a/effort_controllers/src/joint_group_effort_controller.cpp b/effort_controllers/src/joint_group_effort_controller.cpp
@@ -29,6 +29,11 @@ JointGroupEffortController::JointGroupEffortController()
 
 controller_interface::CallbackReturn JointGroupEffortController::on_init()
 {
+  RCLCPP_WARN(
+    get_node()->get_logger(),
+    "'effort_controllers/JointGroupEffortController' is deprecated. "
+    "Use 'forward_command_controller/ForwardCommandController' instead by adding the "
+    "'interface_name' parameter and set it to 'effort'.");
   try
   {
     // Explicitly set the interface parameter declared by the forward_command_controller
diff --git a/forward_command_controller/doc/userdoc.rst b/forward_command_controller/doc/userdoc.rst
@@ -5,16 +5,16 @@
 forward_command_controller
 ==========================
 
-This is a base class implementing a feedforward controller. Specific implementations of this base class can be found in:
+A selection of controllers that forward commands of different types.
 
-* :ref:`position_controllers_userdoc`
-* :ref:`velocity_controllers_userdoc`
-* :ref:`effort_controllers_userdoc`
+forward_command_controller and multi_interface_forward_command_controller
+#########################################################################
+Both controllers forward ``std_msgs::msg::Float64MultiArray`` to a set of interfaces, which can be parameterized as follows: While ``forward_command_controller/ForwardCommandController`` only claims a single interface type per joint (``joint[i] + "/" + interface_name``), the ``forward_command_controller/MultiInterfaceForwardCommandController`` claims the combination of all interfaces specified in the ``interface_names`` parameter (``joint[i] + "/" + interface_names[j]``).
 
 Hardware interface type
 -----------------------
 
-This controller can be used for every type of command interface.
+This controller can be used for every type of command interface, not only limited to joints.
 
 
 ROS 2 interface of the controller
diff --git a/forward_command_controller/src/forward_command_controller_parameters.yaml b/forward_command_controller/src/forward_command_controller_parameters.yaml
@@ -9,7 +9,7 @@ forward_command_controller:
   }
   interface_name: {
     type: string,
-    description: "Name of the interface to command",
+    description: "Name of the interface of the joint",
     validation: {
       not_empty<>: []
     },
diff --git a/forward_command_controller/src/multi_interface_forward_command_controller_parameters.yaml b/forward_command_controller/src/multi_interface_forward_command_controller_parameters.yaml
@@ -9,7 +9,7 @@ multi_interface_forward_command_controller:
   }
   interface_names: {
     type: string_array,
-    description: "Names of the interfaces to command",
+    description: "Names of the interfaces per joint to claim",
     validation: {
       not_empty<>: []
     },
diff --git a/position_controllers/doc/userdoc.rst b/position_controllers/doc/userdoc.rst
@@ -12,6 +12,10 @@ The package contains the following controllers:
 position_controllers/JointGroupPositionController
 -------------------------------------------------
 
+.. warning::
+
+  ``position_controllers/JointGroupPositionController`` is deprecated. Use :ref:`forward_command_controller <forward_command_controller_userdoc>` instead by adding the ``interface_name`` parameter and set it to ``position``.
+
 This is specialization of the :ref:`forward_command_controller <forward_command_controller_userdoc>` that works using the "position" joint interface.
 
 
diff --git a/position_controllers/package.xml b/position_controllers/package.xml
@@ -34,5 +34,10 @@
 
   <export>
     <build_type>ament_cmake</build_type>
+    <deprecated>
+      This package will be removed in ROS 2 Lyrical Luth. Instead, use
+      forward_command_controller, see migration guides for details:
+      https://control.ros.org/rolling/doc/ros2_controllers/doc/migration.html
+    </deprecated>
   </export>
 </package>
diff --git a/position_controllers/src/joint_group_position_controller.cpp b/position_controllers/src/joint_group_position_controller.cpp
@@ -29,6 +29,11 @@ JointGroupPositionController::JointGroupPositionController()
 
 controller_interface::CallbackReturn JointGroupPositionController::on_init()
 {
+  RCLCPP_WARN(
+    get_node()->get_logger(),
+    "'position_controllers/JointGroupPositionController' is deprecated. "
+    "Use 'forward_command_controller/ForwardCommandController' instead by adding the "
+    "'interface_name' parameter and set it to 'position'.");
   try
   {
     // Explicitly set the interface parameter declared by the forward_command_controller
diff --git a/velocity_controllers/doc/userdoc.rst b/velocity_controllers/doc/userdoc.rst
@@ -12,6 +12,10 @@ The package contains the following controllers:
 velocity_controllers/JointGroupVelocityController
 -------------------------------------------------
 
+.. warning::
+
+  ``velocity_controllers/JointGroupVelocityController`` is deprecated. Use :ref:`forward_command_controller <forward_command_controller_userdoc>` instead by adding the ``interface_name`` parameter and set it to ``velocity``.
+
 This is specialization of the :ref:`forward_command_controller <forward_command_controller_userdoc>` that works using the "velocity" joint interface.
 
 
diff --git a/velocity_controllers/package.xml b/velocity_controllers/package.xml
@@ -34,5 +34,10 @@
 
   <export>
     <build_type>ament_cmake</build_type>
+    <deprecated>
+      This package will be removed in ROS 2 Lyrical Luth. Instead, use
+      forward_command_controller, see migration guides for details:
+      https://control.ros.org/rolling/doc/ros2_controllers/doc/migration.html
+    </deprecated>
   </export>
 </package>
diff --git a/velocity_controllers/src/joint_group_velocity_controller.cpp b/velocity_controllers/src/joint_group_velocity_controller.cpp
@@ -29,6 +29,11 @@ JointGroupVelocityController::JointGroupVelocityController()
 
 controller_interface::CallbackReturn JointGroupVelocityController::on_init()
 {
+  RCLCPP_WARN(
+    get_node()->get_logger(),
+    "'velocity_controllers/JointGroupVelocityController' is deprecated. "
+    "Use 'forward_command_controller/ForwardCommandController' instead by adding the "
+    "'interface_name' parameter and set it to 'velocity'.");
   try
   {
     // Explicitly set the interface parameter declared by the forward_command_controller

Original file line number	Diff line number	Diff line change
`@@ -29,6 +29,11 @@ JointGroupEffortController::JointGroupEffortController()`
`29`	`29`
`30`	`30`	`controller_interface::CallbackReturn JointGroupEffortController::on_init()`
`31`	`31`	`{`
	`32`	`+ RCLCPP_WARN(`
	`33`	`+ get_node()->get_logger(),`
	`34`	`+ "'effort_controllers/JointGroupEffortController' is deprecated. "`
	`35`	`+ "Use 'forward_command_controller/ForwardCommandController' instead by adding the "`
	`36`	`+ "'interface_name' parameter and set it to 'effort'.");`
`32`	`37`	`try`
`33`	`38`	`{`
`34`	`39`	`// Explicitly set the interface parameter declared by the forward_command_controller`
Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@ forward_command_controller:`
`9`	`9`	`}`
`10`	`10`	`interface_name: {`
`11`	`11`	`type: string,`
`12`		`- description: "Name of the interface to command",`
	`12`	`+ description: "Name of the interface of the joint",`
`13`	`13`	`validation: {`
`14`	`14`	`not_empty<>: []`
`15`	`15`	`},`
Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@ multi_interface_forward_command_controller:`
`9`	`9`	`}`
`10`	`10`	`interface_names: {`
`11`	`11`	`type: string_array,`
`12`		`- description: "Names of the interfaces to command",`
	`12`	`+ description: "Names of the interfaces per joint to claim",`
`13`	`13`	`validation: {`
`14`	`14`	`not_empty<>: []`
`15`	`15`	`},`