Create debugging.rst

doc/debugging.rst

@@ -0,0 +1,80 @@
+Debugging
+^^^^^^^^^
+
+All controllers and hardware components are plugins loaded into the ``controller_manager``. Therefore, the debugger must be attached to the ``controller_manager``. If multiple ``controller_manager`` instances are running on your robot or machine, you need to attach the debugger to the ``controller_manager`` associated with the hardware component or controller you want to debug.
+
+How-To
+******************
+
+* Install ``xterm``, ``gdb`` and ``gdbserver`` on your system
+
+  .. code-block:: bash
+
+    sudo apt install xterm gdb gdbserver
+
+* Make sure you run a "debug" or "release with debug information" build:
+  This is done by passing ``--cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo`` to ``colcon build``.
+  Remember that in release builds some breakpoints might not behave as you expect as the the corresponding line might have been optimized by the compiler. For such cases, a full Debug build (``--cmake-args -DCMAKE_BUILD_TYPE=Debug``) is recommended.
+
+* Adapt the launch file to run the controller manager with the debugger attached:
+
+  * Version A: Run it directly with the gdb CLI:
+
+    Add ``prefix=['xterm -e gdb -ex run --args']`` to the ``controller_manager`` node entry in your launch file.
+    Due to how ``ros2launch`` works we need to run the specific node in a separate terminal instance.
+
+  * Version B: Run it with gdbserver:
+
+    Add ``prefix=['gdbserver localhost:3000']`` to the ``controller_manager`` node entry in your launch file.
+    Afterwards, you can either attach a gdb CLI instance or any IDE of your choice to that ``gdbserver`` instance.
+    Ensure you start your debugger from a terminal where you have sourced your workspace to properly resolve all paths.
+
+  Example launch file entry:
+
+  .. code-block:: python
+
+    # Obtain the controller config file for the ros2 control node
+    controller_config_file = get_package_file("<package name>", "config/controllers.yaml")
+
+    controller_manager = Node(
+        package="controller_manager",
+        executable="ros2_control_node",
+        parameters=[controller_config_file],
+        output="both",
+        emulate_tty=True,
+        remappings=[
+            ("~/robot_description", "/robot_description")
+        ],
+        prefix=['xterm -e gdb -ex run --args']  # or prefix=['gdbserver localhost:3000']
+    )
+
+    ld.add_action(controller_manager)
+
+
+Additional notes
+*****************
+
+* Debugging plugins
+
+  You can only set breakpoints in plugins after the plugin has been loaded. In the ros2_control context this means after the controller / hardware component has been loaded:
+
+* Debug builds
+
+  It's often practical to include debug information only for the specific package you want to debug.
+  ``colcon build --packages-select [package_name] --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo`` or ``colcon build --packages-select [package_name] --cmake-args -DCMAKE_BUILD_TYPE=Debug``
+
+* Realtime
+
+.. warning::
+  The ``update/on_activate/on_deactivate`` method of a controller and the ``read/write/on_activate/perform_command_mode_switch`` methods of a hardware component all run in the context of the realtime update loop. Setting breakpoints there can and will cause issues that might even break your hardware in the worst case.
+
+From experience, it might be better to use meaningful logs for the real-time context (with caution) or to add additional debug state interfaces (or publishers in the case of a controller).
+
+However, running the controller_manager and your plugin with gdb can still be very useful for debugging errors such as segfaults, as you can gather a full backtrace.
+
+References
+***********
+
+* `ROS 2 and GDB <https://juraph.com/miscellaneous/ros2_and_gdb/>`_
+* `Using GDB to debug a plugin <https://stackoverflow.com/questions/10919832/how-to-use-gdb-to-debug-a-plugin>`_
+* `GDB CLI Tutorial <https://www.cs.umd.edu/~srhuang/teaching/cmsc212/gdb-tutorial-handout.pdf>`_

doc/index.rst

@@ -28,3 +28,12 @@ Concepts
    Joint Kinematics <../hardware_interface/doc/joints_userdoc.rst>
    Hardware Components <../hardware_interface/doc/hardware_components_userdoc.rst>
    Mock Components <../hardware_interface/doc/mock_components_userdoc.rst>
+
+=====================================
+Guidelines and Best Practices
+=====================================
+
+.. toctree::
+   :titlesonly:
+
+   Debugging the Controller Manager and Plugins <debugging.rst>