You're reading the documentation for an older, but still supported, version of ROS 2. For information on the latest version, please have a look at Kilted.

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

    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:

    # 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)

Catching Exceptions

  • The controller manager by default catches most of the exceptions thrown by controllers and hardware components to avoid crashing the whole system. However, it does print the exception type and message to the console. This can make debugging difficult as the debugger might not catch the exception and also when the exception message is not clear enough to identify the root cause. This behaviour can be disabled by setting the parameter handle_exceptions to false in the controller manager node, this way the exceptions will propagate up to the controller manager and can be caught by the debugger (or) crash by printing the stacktrace during normal execution.

    Example controller manager config file:

    controller_manager:
  ros__parameters:
    update_rate: 1000
    handle_exceptions: false

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