Improved controller usage documentation (#1754)

Improved controller usage documentation adding a dedicate page for
* Position and Velocity related controllers
* Force Torque related controllers
* Utility controller page for all others controllers

And
* Add a Test verifying that all the controllers have been mentioned
* Document tcp_pose_broadcaster in more detail

---------

Co-authored-by: Felix Exner <feex@universal-robots.com>

Author: urrsk

.github/workflows/sphinx_build.yml

@@ -25,6 +25,8 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install -r doc_requirements.txt
+      - name: Verify controller documentation coverage
+        run: python ur_robot_driver/test/test_controller_doc_coverage.py
       - name: Build documentation
         run: |
           sphinx-build -W -b html ur_calibration/doc _doc_build_calibration && \

ur_controllers/doc/index.rst

@@ -1,5 +1,7 @@
 :github_url: https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/blob/main/ur_controllers/doc/index.rst
 
+.. _ur_controllers:
+
 ur_controllers
 ==============
 
@@ -461,3 +463,29 @@ The controller provides one action for enabling tool contact. For the controller
   .. code-block::
 
      ros2 action send_goal /tool_contact_controller/detect_tool_contact ur_msgs/action/ToolContact
+
+.. _ur_configuration_controller:
+
+ur_controllers/URConfigurationController
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This controller provides access to UR-specific robot configuration data. Currently, it provides a
+service to query the robot's software version.
+
+Parameters
+""""""""""
+
++-------------------------+--------+---------------+---------------------------------------------------------------------------------------+
+| Parameter name          | Type   | Default value | Description                                                                           |
+|                         |        |               |                                                                                       |
++-------------------------+--------+---------------+---------------------------------------------------------------------------------------+
+| ``tf_prefix``           | string | <empty>       | Urdf prefix of the corresponding arm                                                  |
++-------------------------+--------+---------------+---------------------------------------------------------------------------------------+
+
+Service interface / usage
+"""""""""""""""""""""""""
+
+* ``~/get_software_version [ur_msgs/srv/GetRobotSoftwareVersion]``: Get the robot's software
+  version. The response contains the major, minor and patch version of the robot's software, as
+  well as the build number if available. For example, for a robot running PolyScope 5.12.1 the
+  response would be major version 5, minor version 12 and patch version 1.

ur_robot_driver/doc/features.rst

@@ -9,13 +9,15 @@ Feature list and roadmap
    :header-rows: 1
 
    * - Feature
-     - ROS2 Driver
+     - ROS 2 Driver
    * - joint-position-based control
      - yes
    * - scaled joint-position-based control
      - yes (:ref:`scaled_jtc`)
    * - joint-velocity-based control
      - yes\ :raw-html-m2r:`<sup>1</sup>`
+   * - joint-effort-based control (torque control)
+     - yes (:ref:`force_torque_control`)
    * - Cartesian position-based control
      - no
    * - Cartesian twist-based control

ur_robot_driver/doc/hardware_interface.rst

@@ -50,3 +50,8 @@ comfortably used through the ``ros2 control`` `command line tool
 
 E.g. ``ros2 control list_hardware_components`` will list all hardware components, including the UR
 hardware interface with its interfaces as listed above.
+
+When the launch files from this driver are used, a predefined set of controllers is already loaded.
+See :ref:`usage_controllers` for a description of the available controllers grouped by control mode.
+
+Users can also load other controllers that use the interfaces provided by the hardware interface.

ur_robot_driver/doc/usage/controllers.rst

@@ -1,31 +1,37 @@
 :github_url: https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/blob/main/ur_robot_driver/doc/usage/controllers.rst
 
-.. _ur_controllers:
+.. _usage_controllers:
 
 Controllers
 ===========
 
 This help page describes the different controllers available for the ``ur_robot_driver``. This
 should help users finding the right controller for their specific use case.
 
-Where are controllers defined?
-------------------------------
+Available Controllers
+---------------------
+.. toctree::
+   :maxdepth: 2
 
-Controllers are defined in the ``config/ur_controllers.yaml`` file.
+   position_velocity_control
+   force_torque_control
+   utility_controllers
 
 How do controllers get loaded and started?
 ------------------------------------------
 
 As this driver uses `ros2_control <https://control.ros.org>`_ all controllers are managed by the
-controller_manager. During startup, a default set of running controllers is loaded and started,
-another set is loaded in stopped mode. Stopped controllers won't be usable right away, but they
-need to be started individually.
+controller_manager. During startup, a default set of running controllers is loaded and activated,
+another set is loaded in inactive mode. Inactive controllers won't be usable right away, but they
+need to be activated individually.
 
 Controllers that are actually writing to some command interfaces (e.g. joint positions) will claim
 those interfaces. Only one controller claiming a certain interface can be active at one point.
 
 Controllers can be switched either through the controller_manager's service calls, through the
-`rqt_controller_manager <https://control.ros.org/rolling/doc/ros2_control/controller_manager/doc/userdoc.html#rqt-controller-manager>`_ gui or through the ``ros2 control`` verb from the package ``ros-${ROS_DISTRO}-ros2controlcli`` package.
+`rqt_controller_manager
+<https://control.ros.org/rolling/doc/ros2_control/controller_manager/doc/userdoc.html#rqt-controller-manager>`_
+gui or through the ``ros2 control`` verb from the ``ros-${ROS_DISTRO}-ros2controlcli`` package.
 
 For example, to switch from the default ``scaled_joint_trajectory_controller`` to the
 ``forward_position_controller`` you can call
@@ -37,97 +43,7 @@ For example, to switch from the default ``scaled_joint_trajectory_controller`` t
    [INFO 2024-09-23 20:32:04.373] [_ros2cli_1207798]: waiting for service /controller_manager/switch_controller to become available...
    Successfully switched controllers
 
-Read-only broadcasters
-----------------------
-
-These broadcasters are read-only. They read states from the robot and publish them on a ROS topic.
-As they are read-only, they don't claim any resources and can be combined freely. By default, they
-are all started and running. Those controllers do not require the robot to have the
-external_control script running.
-
-joint_state_broadcaster
-^^^^^^^^^^^^^^^^^^^^^^^
-
-Type: `joint_state_broadcaster/JointStateBroadcaster <https://control.ros.org/rolling/doc/ros2_controllers/joint_state_broadcaster/doc/userdoc.html>`_
-
-Publishes all joints' positions, velocities, and motor currents as ``sensor_msgs/JointState`` on the ``joint_states`` topic.
-
-.. note::
-
-   The effort field contains the currents reported by the joints and not the actual efforts in a
-   physical sense.
-
-speed_scaling_state_broadcaster
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Type: :ref:`ur_controllers/SpeedScalingStateBroadcaster <speed_scaling_state_broadcaster>`
-
-This broadcaster publishes the current actual execution speed as reported by the robot. Values are
-floating points between 0 and 1.
-
-force_torque_sensor_broadcaster
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Type: `force_torque_sensor_broadcaster/ForceTorqueSensorBroadcaster <https://control.ros.org/rolling/doc/ros2_controllers/force_torque_sensor_broadcaster/doc/userdoc.html>`_
-
-Publishes the robot's wrench as reported from the controller.
-
-Commanding controllers
-----------------------
-
-The commanding controllers control the robot's motions. Those controllers can't be combined
-arbitrarily, as they will claim hardware resources. Only one controller can claim one hardware
-resource at a time.
-
-scaled_joint_trajectory_controller (Default motion controller)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Type: :ref:`ur_controllers/ScaledJointTrajectoryController <scaled_jtc>`
-
-Scaled version of the
-`joint_trajectory_controller
-<https://control.ros.org/master/doc/ros2_controllers/joint_trajectory_controller/doc/userdoc.html>`_.
-It uses the robot's speed scaling information and thereby the safety compliance features, like pause on safeguard stop. In addition, it also makes it possible to adjust execution speed using the speed slider on the teach pendant or set the program in pause and restart it again.
-See it's linked documentation for details.
-
-io_and_status_controller
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-Type: :ref:`ur_controllers/GPIOController <io_and_status_controller>`
-
-Allows setting I/O ports, controlling some UR-specific functionality and publishes status information about the robot.
-
-forward_effort_controller
-^^^^^^^^^^^^^^^^^^^^^^^^^
-Type: `effort_controllers/JointGroupEffortController <https://control.ros.org/rolling/doc/ros2_controllers/effort_controllers/doc/userdoc.html#effort-controllers-jointgroupeffortcontroller>`_
-
-Allows setting target joint efforts (torques) directly. The user is therefore responsible for sending commands that are achievable. This controller is useful when implementing compliance or force control strategies.
-
-forward_velocity_controller
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Type: `velocity_controllers/JointGroupVelocityController <https://control.ros.org/rolling/doc/ros2_controllers/velocity_controllers/doc/userdoc.html#velocity-controllers-jointgroupvelocitycontroller>`_
-
-Allows setting target joint velocities directly. The user is therefore responsible for sending commands that are achievable. This controller is particularly useful when doing servoing such as ``moveit_servo``.
-
-forward_position_controller
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Type: `position_controllers/JointGroupPositionController <https://control.ros.org/rolling/doc/ros2_controllers/position_controllers/doc/userdoc.html#position-controllers-jointgrouppositioncontroller>`_
-
-Allows setting target joint positions directly. The robot tries to reach the target position as fast as possible. The user is responsible for sending commands that are achievable. This controller is particularly useful when doing servoing such as ``moveit_servo``.
-
-force_mode_controller
-^^^^^^^^^^^^^^^^^^^^^
-
-Type: :ref:`ur_controllers/ForceModeController <force_mode_controller>`
-
-Allows utilizing the robot's builtin *Force Mode*.
-
-freedrive_mode_controller
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Type: :ref:`ur_controllers/FreedriveModeController <freedrive_mode_controller>`
+Where are controllers defined?
+------------------------------
 
-Allows utilizing the robot's *Freedrive mode*, making it possible to manually move the robot's
-joints.
+Controllers are defined in the ``config/ur_controllers.yaml`` file.