Added information on controllers

Author: Felix Exner

ur_controllers/doc/index.rst

@@ -5,13 +5,12 @@ This package contains controllers and hardware interface for ``ros_control`` tha
 robot family. Currently this contains:
 
 
-* A **speed_scaling_interface** to read the value of the current speed scaling into controllers.
-* A **scaled_joint_command_interface** that provides access to joint values and commands in
-  combination with the speed scaling value.
-* A **speed_scaling_state_controller** that publishes the current execution speed as reported by
+* A **speed_scaling_state_broadcaster** that publishes the current execution speed as reported by
   the robot to a topic interface. Values are floating points between 0 and 1.
 * A **scaled_joint_trajectory_controller** that is similar to the *joint_trajectory_controller*\ ,
   but it uses the speed scaling reported by the robot to reduce progress in the trajectory.
+* A **io_and_status_controller** that allows setting I/O ports, controlling some UR-specific
+  functionality and publishes status information about the robot.
 
 About this package
 ------------------
@@ -27,6 +26,8 @@ Controller description
 This packages offers a couple of specific controllers that will be explained in the following
 sections.
 
+.. _speed_scaling_state_broadcaster:
+
 ur_controllers/SpeedScalingStateBroadcaster
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -41,8 +42,10 @@ fields ``speed_scaling`` (which should be equal to the value shown by the speed
 teach pendant) and ``target_speed_fraction`` (Which is the fraction to which execution gets slowed
 down by the controller).
 
-position_controllers/ScaledJointTrajectoryController and velocity_controllers/ScaledJointTrajectoryController
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. _scaled_jtc:
+
+ur_controlers/ScaledJointTrajectoryController
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 These controllers work similar to the well-known
 `joint_trajectory_controller <https://control.ros.org/master/doc/ros2_controllers/joint_trajectory_controller/doc/userdoc.html>`_.
@@ -97,3 +100,36 @@ Under the hood this is implemented by proceeding the trajectory not by a full ti
 the fraction determined by the current speed scaling. If speed scaling is currently at 50% then
 interpolation of the current control cycle will start half a time step after the beginning of the
 previous control cycle.
+
+.. _io_and_status_controller:
+
+ur_controllers/GPIOController
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This controller allows setting I/O ports, controlling some UR-specific functionality and publishes
+status information about the robot.
+
+Published topics
+""""""""""""""""
+
+* ``~/io_states [ur_msgs/msg/IOStates]``: Status of all I/O ports
+* ``~/robot_mode [ur_dashboard_msgs/msg/RobotMode]``: The current robot mode (e.g. ``POWER_OFF``,
+  ``IDLE``, ``RUNNING``)
+* ``~/robot_program_running [std_msgs/msg/Bool]``: Publishes whether **the External Control
+  program** is running or not. If this is ``false`` no commands can be sent to the robot.
+* ``~/safety_mode [ur_dashboard_msgs/msg/SafetyMode]``: The robot's current safety mode (e.g.
+  ``PROTECTIVE_STOP``, ``ROBOT_EMERGENCY_STOP``, ``NORMAL``)
+* ``~/tool_data [ur_msgs/msg/ToolDataMsg]``: Information about the robot's tool configuration
+
+Advertised services
+"""""""""""""""""""
+
+* ``~/hand_back_control [std_srvs/srv/Trigger]``: Calling this service will make the robot program
+  exit the *External Control* program node and continue with the rest of the program.
+* ``~/resend_robot_program [std_srvs/srv/Trigger]``: When :ref:`headless_mode` is used, this
+  service can be used to restart the *External Control* program on the robot.
+* ``~/set_io [ur_msgs/srv/SetIO]``: Set an output pin on the robot.
+* ``~/set_payload [ur_msgs/srv/SetPayload]``: Change the robot's payload on-the-fly.
+* ``~/set_speed_slider [ur_msgs/srv/SetSpeedSliderFraction]``: Set the value of the speed slider.
+* ``~/zero_ftsensor [std_srvs/srv/Trigger]``: Zeroes the reported wrench of the force torque
+  sensor.

ur_robot_driver/doc/usage/controllers.rst

@@ -1,5 +1,117 @@
 Controllers
 ===========
 
-.. todo::
-   Write something...
+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?
+------------------------------
+
+Controllers are defined in the ``config/ur_controllers.yaml`` file.
+
+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.
+
+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.
+
+For example, to switch from the default ``scaled_joint_trajectory_controller`` to the
+``forward_position_controller`` you can call
+
+.. code-block:: console
+
+   $ ros2 control switch_controllers --deactivate scaled_joint_trajectory_controller \
+     --activate forward_position_controller
+   [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 can also be paused when pausing the *External
+Control* program. See it's linked documentation for details.
+
+.. note::
+
+   It is planned to replace this controller with ros2_control's joint_trajectory_controller once
+   that has received the capability of being scaled, as well.
+
+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_velocity_controller
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Type: `velocity_controllers/JointGroupVelocityController <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 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/velocity_controllers/doc/userdoc.html#velocity-controllers-jointgroupvelocitycontroller>`_
+
+Allows setting target joint velocities directly. The user is responsible for sending commands that
+are achievable. This controller is particularly useful when doing servoing such as
+``moveit_servo``.