Add migration notes

ros-controls · Mar 27, 2024 · 9bdcda2 · 9bdcda2
1 parent b5c7a4d
commit 9bdcda2
Show file tree

Hide file tree

Showing 4 changed files with 111 additions and 50 deletions.
diff --git a/doc/index.rst b/doc/index.rst
@@ -33,3 +33,14 @@ Concepts
  Controller Chaining / Cascade Control <../controller_manager/doc/controller_chaining.rst>
  Hardware Components <../hardware_interface/doc/hardware_components_userdoc.rst>
  Mock Components <../hardware_interface/doc/mock_components_userdoc.rst>
+
+
+================
+Migration Guides
+================
+
+.. toctree::
+ :titlesonly:
+
+ Foxy to Galactic <migration/Foxy.rst>
+ Iron to Jazzy <migration/Iron.rst>
diff --git a/doc/migration/Foxy.rst b/doc/migration/Foxy.rst
@@ -0,0 +1,51 @@
+Foxy to Galactic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+hardware_interface
+**************************************
+Between Foxy and Galactic we made substantial changes to the interface of hardware components to enable management of their lifecycle.
+The following list shows a set of quick changes to port existing hardware components to Galactic:
+
+1. Rename ``configure`` to ``on_init`` and change return type to ``CallbackReturn``
+
+2. If using BaseInterface as base class then you should remove it. Specifically, change:
+
+ .. code-block:: c++
+
+ hardware_interface::BaseInterface<hardware_interface::[Actuator|Sensor|System]Interface>
+
+ to
+
+ .. code-block:: c++
+
+ hardware_interface::[Actuator|Sensor|System]Interface
+
+3. Remove include of headers ``base_interface.hpp`` and ``hardware_interface_status_values.hpp``
+
+4. Add include of header ``rclcpp_lifecycle/state.hpp`` although this may not be strictly necessary
+
+5. replace first three lines in ``on_init`` to
+
+ .. code-block:: c++
+
+ if (hardware_interface::[Actuator|Sensor|System]Interface::on_init(info) != CallbackReturn::SUCCESS)
+ {
+ return CallbackReturn::ERROR;
+ }
+
+
+6. Change last return of ``on_init`` to ``return CallbackReturn::SUCCESS;``
+
+7. Remove all lines with ``status_ = ...`` or ``status::...``
+
+8. Rename ``start()`` to ``on_activate(const rclcpp_lifecycle::State & previous_state)`` and
+ ``stop()`` to ``on_deactivate(const rclcpp_lifecycle::State & previous_state)``
+
+9. Change return type of ``on_activate`` and ``on_deactivate`` to ``CallbackReturn``
+
+10. Change last return of ``on_activate`` and ``on_deactivate`` to ``return CallbackReturn::SUCCESS;``
+
+11. If you have any ``return_type::ERROR`` in ``on_init``, ``on_activate``, or ``in_deactivate`` change to ``CallbackReturn::ERROR``
+
+12. If you get link errors with undefined refernences to symbols in ``rclcpp_lifecycle::node_interfaces::LifecycleNodeInterface``, then add
+ ``rclcpp_lifecyle`` package dependency to ``CMakeLists.txt`` and ``package.xml``
diff --git a/doc/migration/Iron.rst b/doc/migration/Iron.rst
@@ -0,0 +1,49 @@
+Iron to Jazzy
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+component parser
+**************************************
+
+* All ``joints`` defined in the ``<ros2_control>``-tag have to be present in the URDF received :ref:`by the controller manager <doc/ros2_control/controller_manager/doc/userdoc:subscribers>`, otherwise a ``std::runtime_error`` is thrown. This is to ensure that the URDF and the ``<ros2_control>``-tag are consistent. E.g., for configuration ports use ``gpio`` tags instead.
+* The syntax for mimic joints is changed to the `official URDF specification <https://wiki.ros.org/urdf/XML/joint>`__. The parameters within the ``ros2_control`` tag are not supported any more. Instead of
+
+ .. code-block:: xml
+
+ <ros2_control name="GazeboSystem" type="system">
+ <joint name="right_finger_joint">
+ <command_interface name="position"/>
+ <state_interface name="position">
+ <param name="initial_value">0.15</param>
+ </state_interface>
+ <state_interface name="velocity"/>
+ <state_interface name="effort"/>
+ </joint>
+ <joint name="left_finger_joint">
+ <param name="mimic">right_finger_joint</param>
+ <param name="multiplier">1</param>
+ <command_interface name="position"/>
+ <state_interface name="position"/>
+ <state_interface name="velocity"/>
+ <state_interface name="effort"/>
+ </joint>
+ </ros2_control>
+
+ define your mimic joints directly in the joint definitions:
+
+ .. code-block:: xml
+
+ <joint name="right_finger_joint" type="prismatic">
+ <axis xyz="0 1 0"/>
+ <origin xyz="0.0 -0.48 1" rpy="0.0 0.0 0.0"/>
+ <parent link="base"/>
+ <child link="finger_right"/>
+ <limit effort="1000.0" lower="0" upper="0.38" velocity="10"/>
+ </joint>
+ <joint name="left_finger_joint" type="prismatic">
+ <mimic joint="right_finger_joint" multiplier="1" offset="0"/>
+ <axis xyz="0 1 0"/>
+ <origin xyz="0.0 0.48 1" rpy="0.0 0.0 3.1415926535"/>
+ <parent link="base"/>
+ <child link="finger_left"/>
+ <limit effort="1000.0" lower="0" upper="0.38" velocity="10"/>
+ </joint>
diff --git a/hardware_interface/doc/hardware_components_userdoc.rst b/hardware_interface/doc/hardware_components_userdoc.rst
@@ -27,53 +27,3 @@ If ``hardware_interface::return_type::ERROR`` is returned from ``read()`` or ``w
 Error handling follows the `node lifecycle <https://design.ros2.org/articles/node_lifecycle.html>`_.
 If successful ``CallbackReturn::SUCCESS`` is returned and hardware is again in ``UNCONFIGURED`` state, if any ``ERROR`` or ``FAILURE`` happens the hardware ends in ``FINALIZED`` state and can not be recovered.
 The only option is to reload the complete plugin, but there is currently no service for this in the Controller Manager.
-
-Migration from Foxy to newer versions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Between Foxy and Galactic we made substantial changes to the interface of hardware components to enable management of their lifecycle.
-The following list shows a set of quick changes to port existing hardware components to Galactic:
-
-1. Rename ``configure`` to ``on_init`` and change return type to ``CallbackReturn``
-
-2. If using BaseInterface as base class then you should remove it. Specifically, change:
-
- .. code-block:: c++
-
- hardware_interface::BaseInterface<hardware_interface::[Actuator|Sensor|System]Interface>
-
- to
-
- .. code-block:: c++
-
- hardware_interface::[Actuator|Sensor|System]Interface
-
-3. Remove include of headers ``base_interface.hpp`` and ``hardware_interface_status_values.hpp``
-
-4. Add include of header ``rclcpp_lifecycle/state.hpp`` although this may not be strictly necessary
-
-5. replace first three lines in ``on_init`` to
-
- .. code-block:: c++
-
- if (hardware_interface::[Actuator|Sensor|System]Interface::on_init(info) != CallbackReturn::SUCCESS)
- {
- return CallbackReturn::ERROR;
- }
-
-
-6. Change last return of ``on_init`` to ``return CallbackReturn::SUCCESS;``
-
-7. Remove all lines with ``status_ = ...`` or ``status::...``
-
-8. Rename ``start()`` to ``on_activate(const rclcpp_lifecycle::State & previous_state)`` and
- ``stop()`` to ``on_deactivate(const rclcpp_lifecycle::State & previous_state)``
-
-9. Change return type of ``on_activate`` and ``on_deactivate`` to ``CallbackReturn``
-
-10. Change last return of ``on_activate`` and ``on_deactivate`` to ``return CallbackReturn::SUCCESS;``
-
-11. If you have any ``return_type::ERROR`` in ``on_init``, ``on_activate``, or ``in_deactivate`` change to ``CallbackReturn::ERROR``
-
-12. If you get link errors with undefined refernences to symbols in ``rclcpp_lifecycle::node_interfaces::LifecycleNodeInterface``, then add
- ``rclcpp_lifecyle`` package dependency to ``CMakeLists.txt`` and ``package.xml``