From 67102cd7312afdcf033580dd06b7ff9ee41ff0c2 Mon Sep 17 00:00:00 2001 From: Felix Exner Date: Wed, 10 Jul 2024 10:15:29 +0200 Subject: [PATCH 01/14] WIP: Update usage --- ur_robot_driver/doc/usage.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/ur_robot_driver/doc/usage.rst b/ur_robot_driver/doc/usage.rst index 365a047e5..cee3f6412 100644 --- a/ur_robot_driver/doc/usage.rst +++ b/ur_robot_driver/doc/usage.rst @@ -1,10 +1,11 @@ -.. role:: raw-html-m2r(raw) - :format: html - - Usage ===== +Prepare the robot +----------------- + +If you want to use a real robot with this driver, you need to prepare it, first. + Launch files ------------ From 25070e4a986c0bac0a5cba28fd5c7589479f92b6 Mon Sep 17 00:00:00 2001 From: Felix Exner Date: Fri, 20 Sep 2024 14:21:55 +0200 Subject: [PATCH 02/14] Add section about operation modes --- ur_robot_driver/doc/ROS_INTERFACE.rst | 2 + ur_robot_driver/doc/index.rst | 1 + ur_robot_driver/doc/operation_modes.rst | 72 +++++++++++++++++++++++++ 3 files changed, 75 insertions(+) create mode 100644 ur_robot_driver/doc/operation_modes.rst diff --git a/ur_robot_driver/doc/ROS_INTERFACE.rst b/ur_robot_driver/doc/ROS_INTERFACE.rst index 0f7a4f373..f9b051504 100644 --- a/ur_robot_driver/doc/ROS_INTERFACE.rst +++ b/ur_robot_driver/doc/ROS_INTERFACE.rst @@ -119,6 +119,8 @@ use_tool_communication (Required) Should the tool's RS485 interface be forwarded to the ROS machine? This is only available on e-Series models. Setting this parameter to TRUE requires multiple other parameters to be set as well. +.. _dashboard_client: + dashboard_client ^^^^^^^^^^^^^^^^ diff --git a/ur_robot_driver/doc/index.rst b/ur_robot_driver/doc/index.rst index bef2baf74..1493028d7 100644 --- a/ur_robot_driver/doc/index.rst +++ b/ur_robot_driver/doc/index.rst @@ -13,5 +13,6 @@ ur_robot_driver overview installation/toc usage + operation_modes setup_tool_communication ROS_INTERFACE diff --git a/ur_robot_driver/doc/operation_modes.rst b/ur_robot_driver/doc/operation_modes.rst new file mode 100644 index 000000000..0b1f82785 --- /dev/null +++ b/ur_robot_driver/doc/operation_modes.rst @@ -0,0 +1,72 @@ +.. _operation_modes: + +Modes of operation +================== + +There are two different sets of **modes** that are used throughout this documentation: + +- The driver's mode of operation (External Control vs Headless) +- (e-series only) The robot's control mode (Local Control Mode vs Remote Control Mode) + +Both will be explained below. + +Robot's control modes +--------------------- +On the e-series the robot itself can operate in different command modes: It can be either in local control mode where the teach pendant is the single point of command or in remote control mode, where motions from the TP, starting & loading programs from the TP activating the freedrive mode are blocked. Note that the remote control mode has to be explicitly enabled in the robot's settings under Settings -> System -> Remote Control. See the robot's manual for details. + +The remote control mode is needed for many aspects of this driver such as + +- :ref:`headless_mode` +- :ref:`Sending script code to the robot` +- Many :ref:`dashboard` functionalities such as + + - restarting the robot after protective / EM-Stop + - powering on the robot and do brake release + - loading and starting programs + + +Driver's operation modes +------------------------ + +There are two fundamentally different modes of operation when using this driver with a UR robot / +URSim: External Control Mode and Headless Mode. Depending on your requirements one can be more +suitable than the other. + +.. _external_control_mode: + +External Control Mode +^^^^^^^^^^^^^^^^^^^^^ + +In External Control mode you will need the :ref:`External Control URCap` +installed on the robot. With that, create a program containing the *External Control* program node. +Once the program enters that node, it will request script code from an external source (in this +case the ROS driver) and execute that. + +As soon as other script code is sent to the robot either by sending it directly through this driver +or by pressing any motion-related button on the teach pendant, the script will be overwritten by +this action and has to be restarted by using the "play" button on the teach pendant. + +If this is necessary, you will see the output ``Connection to reverse interface dropped.`` from the driver. + +.. note:: + It is also possible to use the driver's external control mode with the robot's local control + mode together. In this case you will need to load and start the program containing the *External + Control* program node through the :ref:`dashboard_client`'s ``load_program`` and ``play`` + services. + +.. _headless_mode: + +Headless mode +^^^^^^^^^^^^^ + +Inside this driver, there's the headless mode, which can be either enabled or not. When the headless mode is activated, required script code for external control will be sent to the robot directly when the driver starts. + +As soon as other script code is sent to the robot either by sending it directly through this driver +or by pressing any motion-related button on the teach pendant, the script will be overwritten by +this action and has to be restarted by using the ``/io_and_status_controller/resend_robot_program`` +service. If this is necessary, you will see the output ``Connection to reverse interface dropped.`` +from the driver. + +.. note:: + On e-Series robots the robot must be in remote_control_mode as explained above in order to use the + driver's Headless Mode. From 7a7001736471d545720a7eb04e9dcd5e25d0e722 Mon Sep 17 00:00:00 2001 From: Felix Exner Date: Fri, 20 Sep 2024 14:30:43 +0200 Subject: [PATCH 03/14] Get some usage things straight --- .../doc/installation/robot_setup.rst | 1 + ur_robot_driver/doc/usage.rst | 39 ++++++++++--------- 2 files changed, 21 insertions(+), 19 deletions(-) diff --git a/ur_robot_driver/doc/installation/robot_setup.rst b/ur_robot_driver/doc/installation/robot_setup.rst index b62e9d43e..321d0f90a 100644 --- a/ur_robot_driver/doc/installation/robot_setup.rst +++ b/ur_robot_driver/doc/installation/robot_setup.rst @@ -1,3 +1,4 @@ +.. _robot_setup: Setting up a UR robot for ur_robot_driver ========================================= diff --git a/ur_robot_driver/doc/usage.rst b/ur_robot_driver/doc/usage.rst index cee3f6412..c2066e366 100644 --- a/ur_robot_driver/doc/usage.rst +++ b/ur_robot_driver/doc/usage.rst @@ -1,10 +1,15 @@ +.. role:: raw-html-m2r(raw) + :format: html + Usage ===== Prepare the robot ----------------- -If you want to use a real robot with this driver, you need to prepare it, first. +If you want to use a real robot with this driver, you need to prepare it, first. Make sure that you +complete all steps from the :ref:`setup instructions`, installed the External +Control URCap and created a program as explained :ref:`here`. Launch files ------------ @@ -59,26 +64,19 @@ The most relevant arguments are the following: **NOTE**\ : The package can simulate hardware with the ros2_control ``MockSystem``. This emulator enables an environment for testing of "piping" of hardware and controllers, as well as testing robot's descriptions. For more details see `ros2_control documentation `_ for more details. -Modes of operation ------------------- +.. todo:: + Write something about controllers + +Simulation +---------- As mentioned in the last section the driver has two basic modes of operation: Using mock hardware or -using real hardware(Or the URSim simulator, which is equivalent from the driver's perspective). +using real hardware (Or the URSim simulator, which is equivalent from the driver's perspective). Additionally, the robot can be simulated using `Gazebo `_ or `ignition `_ but that's outside of this driver's scope. -.. list-table:: - :header-rows: 1 - - * - mode - - available controllers - * - mock_hardware - - :raw-html-m2r:`
  • joint_trajectory_controller
  • forward_velocity_controller
  • forward_position_controller
` - * - real hardware / URSim - - :raw-html-m2r:`
  • joint_trajectory_controller
  • scaled_joint_trajectory_controller
  • forward_velocity_controller
  • forward_position_controller
` - Usage with official UR simulator ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -221,10 +219,13 @@ While most tf frames come from the URDF and are published from the ``robot_state are a couple of things to know: - The ``base`` frame is the robot's base as the robot controller sees it. -- The ``tool0_controller`` is the tool frame as published from the robot controller. If there is no - additional tool configured on the Teach pendant (TP), this should be equivalent to ``tool0`` given that - the URDF uses the specific robot's :ref:`calibration `. If a tool is - configured on the TP, then the additional transformation will show in ``base`` -> ``tool0``. +- The ``tool0`` is the tool frame as calculated using forward kinematics. If there is no additional + tool configured on the Teach pendant (TP) and the URDF uses the specific robot's + :ref:`calibration ` the lookup from ``base`` -> ``tool0`` should be the + same as the tcp pose shown on the TP when the feature "Base" is selected. + + +.. _script_command_interface: Custom URScript commands ------------------------ @@ -242,7 +243,7 @@ publish a message to its interface: Be aware, that running a program on this interface (meaning publishing script code to that interface) stops any running program on the robot. Thus, the motion-interpreting program that is started by the driver gets stopped and has to be -restarted again. Depending whether you use headless mode or not, you'll have to call the +restarted again. Depending whether you use :ref:`headless_mode` or not, you'll have to call the ``resend_program`` service or press the ``play`` button on the teach panel to start the external_control program again. From f0a93e1d7fc7fcce1cb08437f82b2ec1ae226cee Mon Sep 17 00:00:00 2001 From: Felix Exner Date: Fri, 20 Sep 2024 14:37:42 +0200 Subject: [PATCH 04/14] Restructure usage into subdirectory --- ur_robot_driver/doc/index.rst | 2 +- ur_robot_driver/doc/usage.rst | 289 ---------------------- ur_robot_driver/doc/usage/controllers.rst | 5 + ur_robot_driver/doc/usage/script_code.rst | 65 +++++ ur_robot_driver/doc/usage/simulation.rst | 35 +++ ur_robot_driver/doc/usage/startup.rst | 62 +++++ ur_robot_driver/doc/usage/toc.rst | 136 ++++++++++ 7 files changed, 304 insertions(+), 290 deletions(-) delete mode 100644 ur_robot_driver/doc/usage.rst create mode 100644 ur_robot_driver/doc/usage/controllers.rst create mode 100644 ur_robot_driver/doc/usage/script_code.rst create mode 100644 ur_robot_driver/doc/usage/simulation.rst create mode 100644 ur_robot_driver/doc/usage/startup.rst create mode 100644 ur_robot_driver/doc/usage/toc.rst diff --git a/ur_robot_driver/doc/index.rst b/ur_robot_driver/doc/index.rst index 1493028d7..1382e4861 100644 --- a/ur_robot_driver/doc/index.rst +++ b/ur_robot_driver/doc/index.rst @@ -12,7 +12,7 @@ ur_robot_driver overview installation/toc - usage + usage/toc operation_modes setup_tool_communication ROS_INTERFACE diff --git a/ur_robot_driver/doc/usage.rst b/ur_robot_driver/doc/usage.rst deleted file mode 100644 index c2066e366..000000000 --- a/ur_robot_driver/doc/usage.rst +++ /dev/null @@ -1,289 +0,0 @@ -.. role:: raw-html-m2r(raw) - :format: html - -Usage -===== - -Prepare the robot ------------------ - -If you want to use a real robot with this driver, you need to prepare it, first. Make sure that you -complete all steps from the :ref:`setup instructions`, installed the External -Control URCap and created a program as explained :ref:`here`. - -Launch files ------------- - -For starting the driver there are two main launch files in the ``ur_robot_driver`` package. - - -* ``ur_control.launch.py`` - starts ros2_control node including hardware interface, joint state broadcaster and a controller. This launch file also starts ``dashboard_client`` if real robot is used. -* ``ur_dashboard_client.launch.py`` - start the dashboard client for UR robots. - -Also, there are predefined launch files for all supported types of UR robots. - -The arguments for launch files can be listed using ``ros2 launch ur_robot_driver .launch.py --show-args``. -The most relevant arguments are the following: - - -* ``ur_type`` (\ *mandatory* ) - a type of used UR robot (\ *ur3*\ , *ur3e*\ , *ur5*\ , *ur5e*\ , *ur10*\ , *ur10e*\ , or *ur16e*\ , *ur20*\ , *ur30*\ ). -* ``robot_ip`` (\ *mandatory* ) - IP address by which the root can be reached. -* ``use_mock_hardware`` (default: *false* ) - use simple hardware emulator from ros2_control. - Useful for testing launch files, descriptions, etc. See explanation below. -* ``initial_positions`` (default: dictionary with all joint values set to 0) - Allows passing a dictionary to set the initial joint values for the mock hardware from `ros2_control `_. It can also be set from a yaml file with the ``load_yaml`` commands as follows: - - .. code-block:: - - - - In this example, the **initial_positions_file** is a xacro argument that contains the absolute path to a yaml file. An example of the initial positions yaml file is as follows: - - .. code-block:: - - elbow_joint: 1.158 - shoulder_lift_joint: -0.953 - shoulder_pan_joint: 1.906 - wrist_1_joint: -1.912 - wrist_2_joint: -1.765 - wrist_3_joint: 0.0 - -* ``mock_sensor_commands`` (default: *false* ) - enables setting sensor values for the hardware emulators. - Useful for offline testing of controllers. - -* ``robot_controller`` (default: *joint_trajectory_controller* ) - controller for robot joints to be started. - Available controllers: - - - * joint_trajectory_controller - * scaled_joint_trajectory_controller - - Note: *joint_state_broadcaster*\ , *speed_scaling_state_broadcaster*\ , *force_torque_sensor_broadcaster*\ , and *io_and_status_controller* will always start. - - *HINT* : list all loaded controllers using ``ros2 control list_controllers`` command. For this, - the package ``ros2controlcli`` must be installed (``sudo apt-get install ros-${ROS_DISTRO}-ros2controlcli``). - -**NOTE**\ : The package can simulate hardware with the ros2_control ``MockSystem``. This emulator enables an environment for testing of "piping" of hardware and controllers, as well as testing robot's descriptions. For more details see `ros2_control documentation `_ for more details. - -.. todo:: - Write something about controllers - -Simulation ----------- - -As mentioned in the last section the driver has two basic modes of operation: Using mock hardware or -using real hardware (Or the URSim simulator, which is equivalent from the driver's perspective). -Additionally, the robot can be simulated using -`Gazebo `_ or -`ignition `_ but that's -outside of this driver's scope. - - -Usage with official UR simulator -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The easiest way to use URSim is the `Docker -image `_ provided by Universal Robots (See -`this link `_ for a CB3-series image). - -To start it, we've prepared a script: - -.. code-block:: bash - - ros2 run ur_client_library start_ursim.sh -m - -With this, we can spin up a driver using - -.. code-block:: bash - - ros2 launch ur_robot_driver ur_control.launch.py ur_type:= robot_ip:=192.168.56.101 launch_rviz:=true - -You can view the polyscope GUI by opening ``_. - -When we now move the robot in Polyscope, the robot's RViz visualization should move accordingly. - -For details on the Docker image, please see the more detailed guide :ref:`here `. - -Example Commands for Testing the Driver ---------------------------------------- - -Allowed UR - Type strings: ``ur3``\ , ``ur3e``\ , ``ur5``\ , ``ur5e``\ , ``ur10``\ , ``ur10e``\ , ``ur16e``\ , ``ur20``, ``ur30``. - -1. Start hardware, simulator or mockup -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - -* To do test with hardware, use: - - .. code-block:: - - ros2 launch ur_robot_driver ur_control.launch.py ur_type:= robot_ip:= launch_rviz:=true - - For more details check the argument documentation with ``ros2 launch ur_robot_driver ur_control.launch.py --show-arguments`` - - After starting the launch file start the external_control URCap program from the pendant, as described above. - -* To do an offline test with URSim check details about it in `this section <#usage-with-official-ur-simulator>`_ - -* To use mocked hardware(capability of ros2_control), use ``use_mock_hardware`` argument, like: - - .. code-block:: - - ros2 launch ur_robot_driver ur_control.launch.py ur_type:=ur5e robot_ip:=yyy.yyy.yyy.yyy use_mock_hardware:=true launch_rviz:=true - - **NOTE**\ : Instead of using the global launch file for control stack, there are also prepeared launch files for each type of UR robots named. They accept the same arguments are the global one and are used by: - - .. code-block:: - - ros2 launch ur_robot_driver .launch.py - -2. Sending commands to controllers -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Before running any commands, first check the controllers' state using ``ros2 control list_controllers`` (Remember to install the ``ros2controlcli`` package as mentioned above). - - -* Send some goal to the Joint Trajectory Controller by using a demo node from `ros2_controllers_test_nodes `_ package by starting the following command in another terminal: - - .. code-block:: - - ros2 launch ur_robot_driver test_scaled_joint_trajectory_controller.launch.py - - After a few seconds the robot should move. - -* To test another controller, simply define it using ``initial_joint_controller`` argument, for example when using mock hardware: - - .. code-block:: - - ros2 launch ur_robot_driver ur_control.launch.py ur_type:=ur5e robot_ip:=yyy.yyy.yyy.yyy initial_joint_controller:=joint_trajectory_controller use_mock_hardware:=true launch_rviz:=true - - And send the command using demo node: - - .. code-block:: - - ros2 launch ur_robot_driver test_joint_trajectory_controller.launch.py - - After a few seconds the robot should move(or jump when using emulation). - -In case you want to write your own ROS node to move the robot, there is an example python node included that you can use as a start. - - -.. code-block:: console - - $ ros2 run ur_robot_driver example_move.py - [INFO] [1720623611.547903428] [jtc_client]: Waiting for action server on scaled_joint_trajectory_controller/follow_joint_trajectory - [INFO] [1720623611.548368095] [jtc_client]: Executing trajectory traj0 - [INFO] [1720623620.530203889] [jtc_client]: Done with result: SUCCESSFUL - [INFO] [1720623622.530668700] [jtc_client]: Executing trajectory traj1 - [INFO] [1720623630.582108072] [jtc_client]: Done with result: SUCCESSFUL - [INFO] [1720623632.582576444] [jtc_client]: Done with all trajectories - [INFO] [1720623632.582957452] [jtc_client]: Done - - -.. warning:: - - This is a very basic node that doesn't have the same safety checks as the test nodes above. Look - at the code and make sure that the robot is able to perform the motions safely before running - this on a real robot! - - -3. Using only robot description -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If you just want to test description of the UR robots, e.g., after changes you can use the following command: - -.. code-block:: - - ros2 launch ur_description view_ur.launch.py ur_type:=ur5e - -Using MoveIt ------------- - -`MoveIt! `_ support is built-in into this driver already. - -To test the driver with the example MoveIt-setup, first start the driver as described -`above <#start-hardware-simulator-or-mockup>`_ and then start the MoveIt! nodes using - -.. code-block:: - - ros2 launch ur_moveit_config ur_moveit.launch.py ur_type:=ur5e launch_rviz:=true - -Now you should be able to use the MoveIt Plugin in rviz2 to plan and execute trajectories with the -robot as explained `here `_. - -For more details, please see :ref:`ur_moveit_config`. - -Robot frames ------------- - -While most tf frames come from the URDF and are published from the ``robot_state_publisher``, there -are a couple of things to know: - -- The ``base`` frame is the robot's base as the robot controller sees it. -- The ``tool0`` is the tool frame as calculated using forward kinematics. If there is no additional - tool configured on the Teach pendant (TP) and the URDF uses the specific robot's - :ref:`calibration ` the lookup from ``base`` -> ``tool0`` should be the - same as the tcp pose shown on the TP when the feature "Base" is selected. - - -.. _script_command_interface: - -Custom URScript commands ------------------------- - -The driver's package contains a ``urscript_interface`` node that allows sending URScript snippets -directly to the robot when the robot is in remote control mode. - -It gets started in the driver's launchfiles by default. To use it, simply -publish a message to its interface: - -.. code-block:: bash - - # simple popup - ros2 topic pub /urscript_interface/script_command std_msgs/msg/String '{data: popup("hello")}' --once - -Be aware, that running a program on this interface (meaning publishing script code to that interface) stops any running program on the robot. -Thus, the motion-interpreting program that is started by the driver gets stopped and has to be -restarted again. Depending whether you use :ref:`headless_mode` or not, you'll have to call the -``resend_program`` service or press the ``play`` button on the teach panel to start the -external_control program again. - -.. note:: - On E-series robots or newer the robot needs to be in remote control mode in order to execute custom URScript commands. - Currently, there is no feedback on the code's correctness. If the code sent to the - robot is incorrect, it will silently not get executed. Make sure that you send valid URScript code! - -Multi-line programs -^^^^^^^^^^^^^^^^^^^ - -When you want to define multi-line programs, make sure to check that newlines are correctly -interpreted from your message. For this purpose the driver prints the program as it is being sent to -the robot. When sending a multi-line program from the command line, you can use an empty line -between each statement: - -.. code-block:: bash - - ros2 topic pub --once /urscript_interface/script_command std_msgs/msg/String '{data: - "def my_prog(): - - set_digital_out(1, True) - - movej(p[0.2, 0.3, 0.8, 0, 0, 3.14], a=1.2, v=0.25, r=0) - - textmsg(\"motion finished\") - - end"}' - -Non-interrupting programs -^^^^^^^^^^^^^^^^^^^^^^^^^ - -To prevent interrupting the main program, you can send certain commands as `secondary programs -`_. - -.. code-block:: bash - - ros2 topic pub --once /urscript_interface/script_command std_msgs/msg/String '{data: - "sec my_prog(): - - textmsg(\"This is a log message\") - - end"}' diff --git a/ur_robot_driver/doc/usage/controllers.rst b/ur_robot_driver/doc/usage/controllers.rst new file mode 100644 index 000000000..7f0e4f3f7 --- /dev/null +++ b/ur_robot_driver/doc/usage/controllers.rst @@ -0,0 +1,5 @@ +Controllers +=========== + +.. todo:: + Write something... diff --git a/ur_robot_driver/doc/usage/script_code.rst b/ur_robot_driver/doc/usage/script_code.rst new file mode 100644 index 000000000..0a7a27f11 --- /dev/null +++ b/ur_robot_driver/doc/usage/script_code.rst @@ -0,0 +1,65 @@ +Sending URScript code to the robot +================================== + +.. _script_command_interface: + +Custom URScript commands +------------------------ + +The driver's package contains a ``urscript_interface`` node that allows sending URScript snippets +directly to the robot when the robot is in remote control mode. + +It gets started in the driver's launchfiles by default. To use it, simply +publish a message to its interface: + +.. code-block:: bash + + # simple popup + ros2 topic pub /urscript_interface/script_command std_msgs/msg/String '{data: popup("hello")}' --once + +Be aware, that running a program on this interface (meaning publishing script code to that interface) stops any running program on the robot. +Thus, the motion-interpreting program that is started by the driver gets stopped and has to be +restarted again. Depending whether you use :ref:`headless_mode` or not, you'll have to call the +``resend_program`` service or press the ``play`` button on the teach panel to start the +external_control program again. + +.. note:: + On E-series robots or newer the robot needs to be in remote control mode in order to execute custom URScript commands. + Currently, there is no feedback on the code's correctness. If the code sent to the + robot is incorrect, it will silently not get executed. Make sure that you send valid URScript code! + +Multi-line programs +^^^^^^^^^^^^^^^^^^^ + +When you want to define multi-line programs, make sure to check that newlines are correctly +interpreted from your message. For this purpose the driver prints the program as it is being sent to +the robot. When sending a multi-line program from the command line, you can use an empty line +between each statement: + +.. code-block:: bash + + ros2 topic pub --once /urscript_interface/script_command std_msgs/msg/String '{data: + "def my_prog(): + + set_digital_out(1, True) + + movej(p[0.2, 0.3, 0.8, 0, 0, 3.14], a=1.2, v=0.25, r=0) + + textmsg(\"motion finished\") + + end"}' + +Non-interrupting programs +^^^^^^^^^^^^^^^^^^^^^^^^^ + +To prevent interrupting the main program, you can send certain commands as `secondary programs +`_. + +.. code-block:: bash + + ros2 topic pub --once /urscript_interface/script_command std_msgs/msg/String '{data: + "sec my_prog(): + + textmsg(\"This is a log message\") + + end"}' diff --git a/ur_robot_driver/doc/usage/simulation.rst b/ur_robot_driver/doc/usage/simulation.rst new file mode 100644 index 000000000..15fe3f4aa --- /dev/null +++ b/ur_robot_driver/doc/usage/simulation.rst @@ -0,0 +1,35 @@ +Simulation +========== + +As mentioned in the last section the driver has two basic modes of operation: Using mock hardware or +using real hardware (Or the URSim simulator, which is equivalent from the driver's perspective). +Additionally, the robot can be simulated using +`Gazebo `_ or +`ignition `_ but that's +outside of this driver's scope. + + +Usage with official UR simulator +-------------------------------- + +The easiest way to use URSim is the `Docker +image `_ provided by Universal Robots (See +`this link `_ for a CB3-series image). + +To start it, we've prepared a script: + +.. code-block:: bash + + ros2 run ur_client_library start_ursim.sh -m + +With this, we can spin up a driver using + +.. code-block:: bash + + ros2 launch ur_robot_driver ur_control.launch.py ur_type:= robot_ip:=192.168.56.101 launch_rviz:=true + +You can view the polyscope GUI by opening ``_. + +When we now move the robot in Polyscope, the robot's RViz visualization should move accordingly. + +For details on the Docker image, please see the more detailed guide :ref:`here `. diff --git a/ur_robot_driver/doc/usage/startup.rst b/ur_robot_driver/doc/usage/startup.rst new file mode 100644 index 000000000..3f652865c --- /dev/null +++ b/ur_robot_driver/doc/usage/startup.rst @@ -0,0 +1,62 @@ +Startup the driver +================== + +Prepare the robot +----------------- + +If you want to use a real robot with this driver, you need to prepare it, first. Make sure that you +complete all steps from the :ref:`setup instructions`, installed the External +Control URCap and created a program as explained :ref:`here`. + +Launch files +------------ + +For starting the driver there are two main launch files in the ``ur_robot_driver`` package. + + +* ``ur_control.launch.py`` - starts ros2_control node including hardware interface, joint state broadcaster and a controller. This launch file also starts ``dashboard_client`` if real robot is used. +* ``ur_dashboard_client.launch.py`` - start the dashboard client for UR robots. + +Also, there are predefined launch files for all supported types of UR robots. + +The arguments for launch files can be listed using ``ros2 launch ur_robot_driver .launch.py --show-args``. +The most relevant arguments are the following: + + +* ``ur_type`` (\ *mandatory* ) - a type of used UR robot (\ *ur3*\ , *ur3e*\ , *ur5*\ , *ur5e*\ , *ur10*\ , *ur10e*\ , or *ur16e*\ , *ur20*\ , *ur30*\ ). +* ``robot_ip`` (\ *mandatory* ) - IP address by which the root can be reached. +* ``use_mock_hardware`` (default: *false* ) - use simple hardware emulator from ros2_control. + Useful for testing launch files, descriptions, etc. See explanation below. +* ``initial_positions`` (default: dictionary with all joint values set to 0) - Allows passing a dictionary to set the initial joint values for the mock hardware from `ros2_control `_. It can also be set from a yaml file with the ``load_yaml`` commands as follows: + + .. code-block:: + + + + In this example, the **initial_positions_file** is a xacro argument that contains the absolute path to a yaml file. An example of the initial positions yaml file is as follows: + + .. code-block:: + + elbow_joint: 1.158 + shoulder_lift_joint: -0.953 + shoulder_pan_joint: 1.906 + wrist_1_joint: -1.912 + wrist_2_joint: -1.765 + wrist_3_joint: 0.0 + +* ``mock_sensor_commands`` (default: *false* ) - enables setting sensor values for the hardware emulators. + Useful for offline testing of controllers. + +* ``robot_controller`` (default: *joint_trajectory_controller* ) - controller for robot joints to be started. + Available controllers: + + + * joint_trajectory_controller + * scaled_joint_trajectory_controller + + Note: *joint_state_broadcaster*\ , *speed_scaling_state_broadcaster*\ , *force_torque_sensor_broadcaster*\ , and *io_and_status_controller* will always start. + + *HINT* : list all loaded controllers using ``ros2 control list_controllers`` command. For this, + the package ``ros2controlcli`` must be installed (``sudo apt-get install ros-${ROS_DISTRO}-ros2controlcli``). + +**NOTE**\ : The package can simulate hardware with the ros2_control ``MockSystem``. This emulator enables an environment for testing of "piping" of hardware and controllers, as well as testing robot's descriptions. For more details see `ros2_control documentation `_ for more details. diff --git a/ur_robot_driver/doc/usage/toc.rst b/ur_robot_driver/doc/usage/toc.rst new file mode 100644 index 000000000..908418a97 --- /dev/null +++ b/ur_robot_driver/doc/usage/toc.rst @@ -0,0 +1,136 @@ +##### +Usage +##### + +This chapter explains how to use the ``ur_robot_driver`` + + +.. toctree:: + :maxdepth: 4 + :caption: Contents: + + startup + controllers + simulation + script_code + +Example Commands for Testing the Driver +--------------------------------------- + +Allowed UR - Type strings: ``ur3``\ , ``ur3e``\ , ``ur5``\ , ``ur5e``\ , ``ur10``\ , ``ur10e``\ , ``ur16e``\ , ``ur20``, ``ur30``. + +1. Start hardware, simulator or mockup +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +* To do test with hardware, use: + + .. code-block:: + + ros2 launch ur_robot_driver ur_control.launch.py ur_type:= robot_ip:= launch_rviz:=true + + For more details check the argument documentation with ``ros2 launch ur_robot_driver ur_control.launch.py --show-arguments`` + + After starting the launch file start the external_control URCap program from the pendant, as described above. + +* To do an offline test with URSim check details about it in `this section <#usage-with-official-ur-simulator>`_ + +* To use mocked hardware(capability of ros2_control), use ``use_mock_hardware`` argument, like: + + .. code-block:: + + ros2 launch ur_robot_driver ur_control.launch.py ur_type:=ur5e robot_ip:=yyy.yyy.yyy.yyy use_mock_hardware:=true launch_rviz:=true + + **NOTE**\ : Instead of using the global launch file for control stack, there are also prepeared launch files for each type of UR robots named. They accept the same arguments are the global one and are used by: + + .. code-block:: + + ros2 launch ur_robot_driver .launch.py + +2. Sending commands to controllers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Before running any commands, first check the controllers' state using ``ros2 control list_controllers`` (Remember to install the ``ros2controlcli`` package as mentioned above). + + +* Send some goal to the Joint Trajectory Controller by using a demo node from `ros2_controllers_test_nodes `_ package by starting the following command in another terminal: + + .. code-block:: + + ros2 launch ur_robot_driver test_scaled_joint_trajectory_controller.launch.py + + After a few seconds the robot should move. + +* To test another controller, simply define it using ``initial_joint_controller`` argument, for example when using mock hardware: + + .. code-block:: + + ros2 launch ur_robot_driver ur_control.launch.py ur_type:=ur5e robot_ip:=yyy.yyy.yyy.yyy initial_joint_controller:=joint_trajectory_controller use_mock_hardware:=true launch_rviz:=true + + And send the command using demo node: + + .. code-block:: + + ros2 launch ur_robot_driver test_joint_trajectory_controller.launch.py + + After a few seconds the robot should move(or jump when using emulation). + +In case you want to write your own ROS node to move the robot, there is an example python node included that you can use as a start. + + +.. code-block:: console + + $ ros2 run ur_robot_driver example_move.py + [INFO] [1720623611.547903428] [jtc_client]: Waiting for action server on scaled_joint_trajectory_controller/follow_joint_trajectory + [INFO] [1720623611.548368095] [jtc_client]: Executing trajectory traj0 + [INFO] [1720623620.530203889] [jtc_client]: Done with result: SUCCESSFUL + [INFO] [1720623622.530668700] [jtc_client]: Executing trajectory traj1 + [INFO] [1720623630.582108072] [jtc_client]: Done with result: SUCCESSFUL + [INFO] [1720623632.582576444] [jtc_client]: Done with all trajectories + [INFO] [1720623632.582957452] [jtc_client]: Done + + +.. warning:: + + This is a very basic node that doesn't have the same safety checks as the test nodes above. Look + at the code and make sure that the robot is able to perform the motions safely before running + this on a real robot! + + +3. Using only robot description +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you just want to test description of the UR robots, e.g., after changes you can use the following command: + +.. code-block:: + + ros2 launch ur_description view_ur.launch.py ur_type:=ur5e + +Using MoveIt +------------ + +`MoveIt! `_ support is built-in into this driver already. + +To test the driver with the example MoveIt-setup, first start the driver as described +`above <#start-hardware-simulator-or-mockup>`_ and then start the MoveIt! nodes using + +.. code-block:: + + ros2 launch ur_moveit_config ur_moveit.launch.py ur_type:=ur5e launch_rviz:=true + +Now you should be able to use the MoveIt Plugin in rviz2 to plan and execute trajectories with the +robot as explained `here `_. + +For more details, please see :ref:`ur_moveit_config`. + +Robot frames +------------ + +While most tf frames come from the URDF and are published from the ``robot_state_publisher``, there +are a couple of things to know: + +- The ``base`` frame is the robot's base as the robot controller sees it. +- The ``tool0`` is the tool frame as calculated using forward kinematics. If there is no additional + tool configured on the Teach pendant (TP) and the URDF uses the specific robot's + :ref:`calibration ` the lookup from ``base`` -> ``tool0`` should be the + same as the tcp pose shown on the TP when the feature "Base" is selected. From 3544db7c11c3010cbcc5f0abd2afad96cd0412a0 Mon Sep 17 00:00:00 2001 From: Felix Exner Date: Mon, 23 Sep 2024 15:36:50 +0200 Subject: [PATCH 05/14] Improved startup instructions --- ur_robot_driver/doc/resources/play_button.svg | 68 +++++++++++ ur_robot_driver/doc/usage/startup.rst | 108 ++++++++++++------ 2 files changed, 143 insertions(+), 33 deletions(-) create mode 100644 ur_robot_driver/doc/resources/play_button.svg diff --git a/ur_robot_driver/doc/resources/play_button.svg b/ur_robot_driver/doc/resources/play_button.svg new file mode 100644 index 000000000..ab3736552 --- /dev/null +++ b/ur_robot_driver/doc/resources/play_button.svg @@ -0,0 +1,68 @@ + + + + + + + + + + + diff --git a/ur_robot_driver/doc/usage/startup.rst b/ur_robot_driver/doc/usage/startup.rst index 3f652865c..f7e44abdc 100644 --- a/ur_robot_driver/doc/usage/startup.rst +++ b/ur_robot_driver/doc/usage/startup.rst @@ -4,59 +4,101 @@ Startup the driver Prepare the robot ----------------- -If you want to use a real robot with this driver, you need to prepare it, first. Make sure that you -complete all steps from the :ref:`setup instructions`, installed the External -Control URCap and created a program as explained :ref:`here`. +If you want to use a real robot (Or a URSim simulator) with this driver, you need to prepare it, +first. Make sure that you complete all steps from the :ref:`setup instructions`, +installed the External Control URCap and created a program as explained +:ref:`here`. Launch files ------------ -For starting the driver there are two main launch files in the ``ur_robot_driver`` package. +For starting the driver it is recommended to start the ``ur_control.launch.py`` launchfile from the +``ur_robot_driver`` package. It starts the driver, a set of controllers and a couple of helper +nodes for UR robots. The only required arguments are the ``ur_type`` and ``robot_ip`` parameters. +.. code-block:: console -* ``ur_control.launch.py`` - starts ros2_control node including hardware interface, joint state broadcaster and a controller. This launch file also starts ``dashboard_client`` if real robot is used. -* ``ur_dashboard_client.launch.py`` - start the dashboard client for UR robots. + $ ros2 launch ur_robot_driver ur_control.launch.py ur_type:=ur5e robot_ip:=192.168.56.101 + +Other important arguments are: + + +* ``use_mock_hardware`` (default: *false* ) - Use simple hardware emulator from ros2_control. Useful for testing launch files, descriptions, etc. +* ``headless_mode`` (default: *false*) - Start driver in :ref:`headless_mode`. +* ``launch_rviz`` (default: *true*) - Start RViz together with the driver. +* ``initial_joint_controller`` (default: *scaled_joint_trajectory_controller*) - Use this if you + want to start the robot with another controller. + + .. note:: + When the driver is started, you can list all loaded controllers using the ``ros2 control + list_controllers`` command. For this, the package ``ros2controlcli`` must be installed (``sudo + apt-get install ros-${ROS_DISTRO}-ros2controlcli``). + + +For all other arguments, please see + + +.. code-block:: console + + $ ros2 launch ur_robot_driver ur_control.launch.py --show-args Also, there are predefined launch files for all supported types of UR robots. -The arguments for launch files can be listed using ``ros2 launch ur_robot_driver .launch.py --show-args``. -The most relevant arguments are the following: +Finish startup on the robot +--------------------------- + +Unless :ref:`headless_mode` is used, you will now have to start the *External Control* program on +the robot that you have created earlier. + +Depending on the :ref:`robot control mode` do the following: + +* In local control mode, load the program on the robot and press the "Play" button |play_button| on the teach pendant. +* In remote control mode load and start the program using the following dashboard calls: + + .. code-block:: console + + $ ros2 service call /dashboard_client/load_program ur_dashboard_msgs/srv/Load "filename: my_robot_program.urp"`` + $ ros2 service call /dashboard_client/play std_srvs/srv/Trigger {} + +* When the driver is started with ``headless_mode:=true`` nothing is needed. The driver is running + already. + +Continuation after interruptions +-------------------------------- + +Whenever the *External Control* program gets interrupted, it has to be unpaused / restarted. + +If that happens, you will see the output ``Connection to reverse interface dropped.`` + +This can happen, e,g, when +* The running program is actively stopped. +* The robot goes into a protective stop / EM stop. (The program will be paused, then) +* The communication is stopped, since the external source did not receive a command in time. +* There was another script sent for execution e.g. -* ``ur_type`` (\ *mandatory* ) - a type of used UR robot (\ *ur3*\ , *ur3e*\ , *ur5*\ , *ur5e*\ , *ur10*\ , *ur10e*\ , or *ur16e*\ , *ur20*\ , *ur30*\ ). -* ``robot_ip`` (\ *mandatory* ) - IP address by which the root can be reached. -* ``use_mock_hardware`` (default: *false* ) - use simple hardware emulator from ros2_control. - Useful for testing launch files, descriptions, etc. See explanation below. -* ``initial_positions`` (default: dictionary with all joint values set to 0) - Allows passing a dictionary to set the initial joint values for the mock hardware from `ros2_control `_. It can also be set from a yaml file with the ``load_yaml`` commands as follows: + * Script code was sent to the robot via its primary interface + * Robot motion is performed using the Teach pendant - .. code-block:: +Depending on the operation mode, perform one of the following steps: - +* In local control mode, simply press the "Play" button |play_button| on the teach pendant. +* In remote control mode start the program using the following dashboard call: - In this example, the **initial_positions_file** is a xacro argument that contains the absolute path to a yaml file. An example of the initial positions yaml file is as follows: + .. code-block:: console - .. code-block:: + $ ros2 service call /dashboard_client/play std_srvs/srv/Trigger {} - elbow_joint: 1.158 - shoulder_lift_joint: -0.953 - shoulder_pan_joint: 1.906 - wrist_1_joint: -1.912 - wrist_2_joint: -1.765 - wrist_3_joint: 0.0 +* When the driver is started with ``headless_mode:=true`` perform the following service call: -* ``mock_sensor_commands`` (default: *false* ) - enables setting sensor values for the hardware emulators. - Useful for offline testing of controllers. + .. code-block:: console -* ``robot_controller`` (default: *joint_trajectory_controller* ) - controller for robot joints to be started. - Available controllers: + $ ros2 service call /io_and_status_controller/resend_robot_program std_srvs/srv/Trigger {} - * joint_trajectory_controller - * scaled_joint_trajectory_controller - Note: *joint_state_broadcaster*\ , *speed_scaling_state_broadcaster*\ , *force_torque_sensor_broadcaster*\ , and *io_and_status_controller* will always start. - *HINT* : list all loaded controllers using ``ros2 control list_controllers`` command. For this, - the package ``ros2controlcli`` must be installed (``sudo apt-get install ros-${ROS_DISTRO}-ros2controlcli``). -**NOTE**\ : The package can simulate hardware with the ros2_control ``MockSystem``. This emulator enables an environment for testing of "piping" of hardware and controllers, as well as testing robot's descriptions. For more details see `ros2_control documentation `_ for more details. +.. |play_button| image:: ../resources/play_button.svg + :height: 20px + :width: 20px From 93715d6c1f607fb7114bd77344437c89658371de Mon Sep 17 00:00:00 2001 From: Felix Exner Date: Mon, 23 Sep 2024 15:52:12 +0200 Subject: [PATCH 06/14] Added move page to usage --- ur_robot_driver/doc/usage/move.rst | 70 ++++++++++++++ ur_robot_driver/doc/usage/simulation.rst | 1 + ur_robot_driver/doc/usage/startup.rst | 5 + ur_robot_driver/doc/usage/toc.rst | 112 ++++------------------- 4 files changed, 93 insertions(+), 95 deletions(-) create mode 100644 ur_robot_driver/doc/usage/move.rst diff --git a/ur_robot_driver/doc/usage/move.rst b/ur_robot_driver/doc/usage/move.rst new file mode 100644 index 000000000..b8ba4a06c --- /dev/null +++ b/ur_robot_driver/doc/usage/move.rst @@ -0,0 +1,70 @@ +.. _move_the_robot: + +Move the robot +============== + +Before running any commands, first check the controllers' state using ``ros2 control list_controllers`` (Remember to install the ``ros2controlcli`` package). + + +* Send some goal to the Joint Trajectory Controller by using a demo node from `ros2_controllers_test_nodes `_ package by starting the following command in another terminal: + + .. code-block:: console + + $ ros2 launch ur_robot_driver test_scaled_joint_trajectory_controller.launch.py + + After a few seconds the robot should move. + +* To test another controller, simply define it using ``initial_joint_controller`` argument, for example when using mock hardware: + + .. code-block:: console + + $ ros2 launch ur_robot_driver ur_control.launch.py ur_type:=ur5e \ + robot_ip:=yyy.yyy.yyy.yyy use_mock_hardware:=true \ + initial_joint_controller:=joint_trajectory_controller + + And send the command using demo node: + + .. code-block:: console + + $ ros2 launch ur_robot_driver test_joint_trajectory_controller.launch.py + + After a few seconds the robot should move(or jump when using emulation). + +In case you want to write your own ROS node to move the robot, there is an example python node included that you can use as a start. + + +.. code-block:: console + + $ ros2 run ur_robot_driver example_move.py + [INFO] [1720623611.547903428] [jtc_client]: Waiting for action server on scaled_joint_trajectory_controller/follow_joint_trajectory + [INFO] [1720623611.548368095] [jtc_client]: Executing trajectory traj0 + [INFO] [1720623620.530203889] [jtc_client]: Done with result: SUCCESSFUL + [INFO] [1720623622.530668700] [jtc_client]: Executing trajectory traj1 + [INFO] [1720623630.582108072] [jtc_client]: Done with result: SUCCESSFUL + [INFO] [1720623632.582576444] [jtc_client]: Done with all trajectories + [INFO] [1720623632.582957452] [jtc_client]: Done + + +.. warning:: + + This is a very basic node that doesn't have the same safety checks as the test nodes above. Look + at the code and make sure that the robot is able to perform the motions safely before running + this on a real robot! + + +Using MoveIt +------------ + +`MoveIt! `_ support is built-in into this driver already. + +To test the driver with the example MoveIt-setup, first start the driver as described +`above <#start-hardware-simulator-or-mockup>`_ and then start the MoveIt! nodes using + +.. code-block:: + + ros2 launch ur_moveit_config ur_moveit.launch.py ur_type:=ur5e launch_rviz:=true + +Now you should be able to use the MoveIt Plugin in rviz2 to plan and execute trajectories with the +robot as explained `here `_. + +For more details, please see :ref:`ur_moveit_config`. diff --git a/ur_robot_driver/doc/usage/simulation.rst b/ur_robot_driver/doc/usage/simulation.rst index 15fe3f4aa..8d4cb7e03 100644 --- a/ur_robot_driver/doc/usage/simulation.rst +++ b/ur_robot_driver/doc/usage/simulation.rst @@ -8,6 +8,7 @@ Additionally, the robot can be simulated using `ignition `_ but that's outside of this driver's scope. +.. _usage_with_official_ur_simulator: Usage with official UR simulator -------------------------------- diff --git a/ur_robot_driver/doc/usage/startup.rst b/ur_robot_driver/doc/usage/startup.rst index f7e44abdc..4dd066593 100644 --- a/ur_robot_driver/doc/usage/startup.rst +++ b/ur_robot_driver/doc/usage/startup.rst @@ -20,6 +20,9 @@ nodes for UR robots. The only required arguments are the ``ur_type`` and ``robot $ ros2 launch ur_robot_driver ur_control.launch.py ur_type:=ur5e robot_ip:=192.168.56.101 +Allowed ``ur_type`` strings: ``ur3``, ``ur3e``, ``ur5``, ``ur5e``, ``ur10``, ``ur10e``, ``ur16e``, +``ur20``, ``ur30``. + Other important arguments are: @@ -44,6 +47,8 @@ For all other arguments, please see Also, there are predefined launch files for all supported types of UR robots. +.. _robot_startup_program: + Finish startup on the robot --------------------------- diff --git a/ur_robot_driver/doc/usage/toc.rst b/ur_robot_driver/doc/usage/toc.rst index 908418a97..e05adf3e0 100644 --- a/ur_robot_driver/doc/usage/toc.rst +++ b/ur_robot_driver/doc/usage/toc.rst @@ -10,118 +10,40 @@ This chapter explains how to use the ``ur_robot_driver`` :caption: Contents: startup + move controllers simulation script_code -Example Commands for Testing the Driver ---------------------------------------- +Quick start +----------- -Allowed UR - Type strings: ``ur3``\ , ``ur3e``\ , ``ur5``\ , ``ur5e``\ , ``ur10``\ , ``ur10e``\ , ``ur16e``\ , ``ur20``, ``ur30``. +Driver startup +^^^^^^^^^^^^^^ -1. Start hardware, simulator or mockup -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +* To start it with hardware, use: + .. code-block:: console -* To do test with hardware, use: + $ ros2 launch ur_robot_driver ur_control.launch.py ur_type:= robot_ip:= launch_rviz:=true - .. code-block:: + After starting the launch file start the external_control URCap program from the pendant, as described :ref:`here`. - ros2 launch ur_robot_driver ur_control.launch.py ur_type:= robot_ip:= launch_rviz:=true +* To run it with URSim check details about it in :ref:`this section `. - For more details check the argument documentation with ``ros2 launch ur_robot_driver ur_control.launch.py --show-arguments`` +* To use mocked hardware (capability of ros2_control), use ``use_mock_hardware`` argument, like: - After starting the launch file start the external_control URCap program from the pendant, as described above. + .. code-block:: console -* To do an offline test with URSim check details about it in `this section <#usage-with-official-ur-simulator>`_ + $ ros2 launch ur_robot_driver ur_control.launch.py ur_type:=ur5e robot_ip:=yyy.yyy.yyy.yyy use_mock_hardware:=true -* To use mocked hardware(capability of ros2_control), use ``use_mock_hardware`` argument, like: - .. code-block:: - - ros2 launch ur_robot_driver ur_control.launch.py ur_type:=ur5e robot_ip:=yyy.yyy.yyy.yyy use_mock_hardware:=true launch_rviz:=true - - **NOTE**\ : Instead of using the global launch file for control stack, there are also prepeared launch files for each type of UR robots named. They accept the same arguments are the global one and are used by: - - .. code-block:: - - ros2 launch ur_robot_driver .launch.py - -2. Sending commands to controllers -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Before running any commands, first check the controllers' state using ``ros2 control list_controllers`` (Remember to install the ``ros2controlcli`` package as mentioned above). - - -* Send some goal to the Joint Trajectory Controller by using a demo node from `ros2_controllers_test_nodes `_ package by starting the following command in another terminal: - - .. code-block:: - - ros2 launch ur_robot_driver test_scaled_joint_trajectory_controller.launch.py - - After a few seconds the robot should move. - -* To test another controller, simply define it using ``initial_joint_controller`` argument, for example when using mock hardware: - - .. code-block:: - - ros2 launch ur_robot_driver ur_control.launch.py ur_type:=ur5e robot_ip:=yyy.yyy.yyy.yyy initial_joint_controller:=joint_trajectory_controller use_mock_hardware:=true launch_rviz:=true - - And send the command using demo node: - - .. code-block:: - - ros2 launch ur_robot_driver test_joint_trajectory_controller.launch.py - - After a few seconds the robot should move(or jump when using emulation). - -In case you want to write your own ROS node to move the robot, there is an example python node included that you can use as a start. - - -.. code-block:: console - - $ ros2 run ur_robot_driver example_move.py - [INFO] [1720623611.547903428] [jtc_client]: Waiting for action server on scaled_joint_trajectory_controller/follow_joint_trajectory - [INFO] [1720623611.548368095] [jtc_client]: Executing trajectory traj0 - [INFO] [1720623620.530203889] [jtc_client]: Done with result: SUCCESSFUL - [INFO] [1720623622.530668700] [jtc_client]: Executing trajectory traj1 - [INFO] [1720623630.582108072] [jtc_client]: Done with result: SUCCESSFUL - [INFO] [1720623632.582576444] [jtc_client]: Done with all trajectories - [INFO] [1720623632.582957452] [jtc_client]: Done - - -.. warning:: - - This is a very basic node that doesn't have the same safety checks as the test nodes above. Look - at the code and make sure that the robot is able to perform the motions safely before running - this on a real robot! - - -3. Using only robot description +Sending commands to controllers ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If you just want to test description of the UR robots, e.g., after changes you can use the following command: - -.. code-block:: - - ros2 launch ur_description view_ur.launch.py ur_type:=ur5e - -Using MoveIt ------------- - -`MoveIt! `_ support is built-in into this driver already. - -To test the driver with the example MoveIt-setup, first start the driver as described -`above <#start-hardware-simulator-or-mockup>`_ and then start the MoveIt! nodes using - -.. code-block:: - - ros2 launch ur_moveit_config ur_moveit.launch.py ur_type:=ur5e launch_rviz:=true - -Now you should be able to use the MoveIt Plugin in rviz2 to plan and execute trajectories with the -robot as explained `here `_. - -For more details, please see :ref:`ur_moveit_config`. +Once the driver is started, you can use it like any other ROS robot arm driver by sending +trajectories to the ``/scaled_joint_trajectory_controller/follow_joint_trajectory`` action. If +you're new to that, please have a look at the section ":ref:`move_the_robot`". Robot frames ------------ From 05443210ded0dcad14faf4c65e06bdbc8054d2b8 Mon Sep 17 00:00:00 2001 From: Felix Exner Date: Mon, 23 Sep 2024 16:37:49 +0200 Subject: [PATCH 07/14] Add troubleshooting section --- ur_robot_driver/doc/usage/startup.rst | 4 ++ ur_robot_driver/doc/usage/toc.rst | 60 +++++++++++++++++++++++++++ 2 files changed, 64 insertions(+) diff --git a/ur_robot_driver/doc/usage/startup.rst b/ur_robot_driver/doc/usage/startup.rst index 4dd066593..d4522d042 100644 --- a/ur_robot_driver/doc/usage/startup.rst +++ b/ur_robot_driver/doc/usage/startup.rst @@ -1,3 +1,5 @@ +.. _ur_robot_driver_startup: + Startup the driver ================== @@ -68,6 +70,8 @@ Depending on the :ref:`robot control mode` do the following: * When the driver is started with ``headless_mode:=true`` nothing is needed. The driver is running already. +.. _continuation_after_interruptions: + Continuation after interruptions -------------------------------- diff --git a/ur_robot_driver/doc/usage/toc.rst b/ur_robot_driver/doc/usage/toc.rst index e05adf3e0..f26b0c61c 100644 --- a/ur_robot_driver/doc/usage/toc.rst +++ b/ur_robot_driver/doc/usage/toc.rst @@ -56,3 +56,63 @@ are a couple of things to know: tool configured on the Teach pendant (TP) and the URDF uses the specific robot's :ref:`calibration ` the lookup from ``base`` -> ``tool0`` should be the same as the tcp pose shown on the TP when the feature "Base" is selected. + +Troubleshooting +--------------- + +This section will cover some previously raised issues. + +I started everything, but I cannot control the robot +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The driver is started, but trajectory execution doesn't work. Instead, the driver logs + +.. code-block:: + + Can't accept new action goals. Controller is not running. + + +The ``External Control`` program node from the URCap is not running on the robot. Make sure to +create a program containing this node on the robot and start it using the "Play" button +|play_button|. Inside the ROS terminal you should see the output ``Robot connected to reverse +interface. Ready to receive control commands.`` + +.. note:: + + When interacting with the teach pendant, or sending other primary programs to the robot, the + program will be stopped. On the ROS terminal you will see an output ``Connection to reverse interface dropped.``. Please see the section :ref:`continuation_after_interruptions` for details on how to continue. + +In general, make sure you're starting up the robot as explained :ref:`here`. + +When starting the program on the TP, I get an error "The connection to the remote PC could not be established" +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Make sure, the IP address setup is correct, as described in the setup guides +(:ref:`CB3 robots`, :ref:`e-Series robots`) + +.. note:: + + This error can also show up, when the ROS driver is not running. + +When starting the driver, it crashes with "Variable 'speed_slider_mask' is currently controlled by another RTDE client" +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Probably, there is a fieldbus enabled on the robot. Currently, this driver cannot be used together +with an enabled fieldbus. Disable any fieldbus to workaround this error. `ROS 1 driver issue +#204 `_ contains a guide +how to do +this. + +I sent raw script code to the robot but it is not executed +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +On the e-Series the robot has to be in :ref:`remote control mode ` to accept script code from an external source. This has to be switched from the Teach-Pendant. + +Using the dashboard doesn't work +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +On the e-Series the robot has to be in :ref:`remote control mode ` to accept certain calls on the dashboard server. See :ref:`Available dashboard commands ` for details. + +.. |play_button| image:: ../resources/play_button.svg + :height: 20px + :width: 20px From 9b34dab7d06b8654510049ba97cf53cfbb566bfd Mon Sep 17 00:00:00 2001 From: Felix Exner Date: Mon, 23 Sep 2024 16:54:41 +0200 Subject: [PATCH 08/14] Add note about mock hardware simulation --- ur_robot_driver/doc/usage/simulation.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/ur_robot_driver/doc/usage/simulation.rst b/ur_robot_driver/doc/usage/simulation.rst index 8d4cb7e03..d6e7c7ae7 100644 --- a/ur_robot_driver/doc/usage/simulation.rst +++ b/ur_robot_driver/doc/usage/simulation.rst @@ -4,8 +4,8 @@ Simulation As mentioned in the last section the driver has two basic modes of operation: Using mock hardware or using real hardware (Or the URSim simulator, which is equivalent from the driver's perspective). Additionally, the robot can be simulated using -`Gazebo `_ or -`ignition `_ but that's +`Gazebo Classic `_ or +`GZ Sim `_ but that's outside of this driver's scope. .. _usage_with_official_ur_simulator: @@ -34,3 +34,12 @@ You can view the polyscope GUI by opening ` When we now move the robot in Polyscope, the robot's RViz visualization should move accordingly. For details on the Docker image, please see the more detailed guide :ref:`here `. + +Mock hardware +------------- + +The package can simulate hardware with the ros2_control ``MockSystem``. This emulator enables an +environment for testing of "piping" of hardware and controllers, as well as testing robot's +descriptions. For more details see `ros2_control documentation +`_ +for more details. From 671614e1014db8978efccc3bc18510f7b95bdef6 Mon Sep 17 00:00:00 2001 From: Felix Exner Date: Mon, 23 Sep 2024 21:17:10 +0200 Subject: [PATCH 09/14] Added information on controllers --- ur_controllers/doc/index.rst | 48 +++++++-- ur_robot_driver/doc/usage/controllers.rst | 116 +++++++++++++++++++++- 2 files changed, 156 insertions(+), 8 deletions(-) diff --git a/ur_controllers/doc/index.rst b/ur_controllers/doc/index.rst index 6d7828462..a027d8d8b 100644 --- a/ur_controllers/doc/index.rst +++ b/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 `_. @@ -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. diff --git a/ur_robot_driver/doc/usage/controllers.rst b/ur_robot_driver/doc/usage/controllers.rst index 7f0e4f3f7..b735b3dc9 100644 --- a/ur_robot_driver/doc/usage/controllers.rst +++ b/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 `_ 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 `_ 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 `_ + +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 ` + +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 `_ + +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 version of the +`joint_trajectory_controller +`_. +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 ` + +Allows setting I/O ports, controlling some UR-specific functionality and publishes status information about the robot. + +forward_velocity_controller +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Type: `velocity_controllers/JointGroupVelocityController `_ + +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 `_ + +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``. From 821e8cdfe359c72d80e756a167e877abe7f623b2 Mon Sep 17 00:00:00 2001 From: Felix Exner Date: Mon, 23 Sep 2024 21:51:03 +0200 Subject: [PATCH 10/14] Update ROS_INTERFACE by splitting it up into individual files --- ur_robot_driver/doc/ROS_INTERFACE.rst | 266 ------------------ ur_robot_driver/doc/dashboard_client.rst | 145 ++++++++++ .../doc/hardware_interface_parameters.rst | 108 +++++++ ur_robot_driver/doc/index.rst | 3 +- 4 files changed, 255 insertions(+), 267 deletions(-) delete mode 100644 ur_robot_driver/doc/ROS_INTERFACE.rst create mode 100644 ur_robot_driver/doc/dashboard_client.rst create mode 100644 ur_robot_driver/doc/hardware_interface_parameters.rst diff --git a/ur_robot_driver/doc/ROS_INTERFACE.rst b/ur_robot_driver/doc/ROS_INTERFACE.rst deleted file mode 100644 index f9b051504..000000000 --- a/ur_robot_driver/doc/ROS_INTERFACE.rst +++ /dev/null @@ -1,266 +0,0 @@ - -**NOTE**\ : This documentation is obsolete and does not cover in full the current state of driver. - -ROS interface -============= - -The new driver for Universal Robots UR3, UR5 and UR10 robots with CB3 controllers and the e-series. - -Nodes ------ - -ur_ros2_control_node -^^^^^^^^^^^^^^^^^^^^ - -This is the actual driver node containing the ROS2-Control stack. Interfaces documented here refer to the robot's hardware interface. Controller-specific API elements might be present for the individual controllers outside of this package. - -Parameters -~~~~~~~~~~ - -Note that parameters are passed through the ros2_control xacro definition. - -headless_mode -""""""""""""" - -Start robot in headless mode. This does not require the 'External Control' URCap to be running on the robot, but this will send the URScript to the robot directly. On e-Series robots this requires the robot to run in 'remote-control' mode. - -input_recipe_filename (Required) -"""""""""""""""""""""""""""""""" - -Path to the file containing the recipe used for requesting RTDE inputs. - -kinematics/hash (Required) -"""""""""""""""""""""""""" - -Hash of the calibration reported by the robot. This is used for validating the robot description is using the correct calibration. If the robot's calibration doesn't match this hash, an error will be printed. You can use the robot as usual, however Cartesian poses of the endeffector might be inaccurate. See the "ur_calibration" package on help how to generate your own hash matching your actual robot. - -non_blocking_read (default: "false") -"""""""""""""""""""""""""""""""""""" - -Enables non_blocking_read mode. Disables error generated when read returns without any data, sets -the read timeout to zero, and synchronizes read/write operations. This is a leftover from the ROS1 -driver and we currently see no real application where it would make sense to enable this. - -output_recipe_filename (Required) -""""""""""""""""""""""""""""""""" - -Path to the file containing the recipe used for requesting RTDE outputs. - -reverse_port (Required) -""""""""""""""""""""""" - -Port that will be opened to communicate between the driver and the robot controller. - -robot_ip (Required) -""""""""""""""""""" - -The robot's IP address. - -script_filename (Required) -"""""""""""""""""""""""""" - -Path to the urscript code that will be sent to the robot. - -script_sender_port (Required) -""""""""""""""""""""""""""""" - -The driver will offer an interface to receive the program's URScript on this port. - -servoj_gain (Required) -"""""""""""""""""""""" - -Specify the gain for the underlying servoj command. This will be used whenever position control is -active. A higher value will lead to sharper motions, but might also introduce -higher jerks and vibrations. - -Range: [100 - 3000] - -servoj_lookahead_time (Required) -"""""""""""""""""""""""""""""""" - -Specify lookahead_time parameter of underlying servoj command. This will be used whenever position -control is active. A higher value will result in smoother trajectories, but will also introduce a -higher delay between the commands sent from ROS and the motion being executed on the robot. - -Unit: seconds, range: [0.03 - 0.2] - -tool_baud_rate (Required) -""""""""""""""""""""""""" - -Baud rate used for tool communication. Will be set as soon as the UR-Program on the robot is started. See UR documentation for valid baud rates. Note: This parameter is only evaluated, when the parameter "use_tool_communication" is set to TRUE. Then, this parameter is required. - -tool_parity (Required) -"""""""""""""""""""""" - -Parity used for tool communication. Will be set as soon as the UR-Program on the robot is started. Can be 0 (None), 1 (odd) and 2 (even). Note: This parameter is only evaluated, when the parameter "use_tool_communication" is set to TRUE. Then, this parameter is required. - -tool_rx_idle_chars (Required) -""""""""""""""""""""""""""""" - -Number of idle chars for the RX unit used for tool communication. Will be set as soon as the UR-Program on the robot is started. Valid values: min=1.0, max=40.0 Note: This parameter is only evaluated, when the parameter "use_tool_communication" is set to TRUE. Then, this parameter is required. - -tool_stop_bits (Required) -""""""""""""""""""""""""" - -Number of stop bits used for tool communication. Will be set as soon as the UR-Program on the robot is started. Can be 1 or 2. Note: This parameter is only evaluated, when the parameter "use_tool_communication" is set to TRUE. Then, this parameter is required. - -tool_tx_idle_chars (Required) -""""""""""""""""""""""""""""" - -Number of idle chars for the TX unit used for tool communication. Will be set as soon as the UR-Program on the robot is started. Valid values: min=0.0, max=40.0 Note: This parameter is only evaluated, when the parameter "use_tool_communication" is set to TRUE. Then, this parameter is required. - -tool_voltage (Required) -""""""""""""""""""""""" - -Tool voltage that will be set as soon as the UR-Program on the robot is started. Note: This parameter is only evaluated, when the parameter "use_tool_communication" is set to TRUE. Then, this parameter is required. - -use_tool_communication (Required) -""""""""""""""""""""""""""""""""" - -Should the tool's RS485 interface be forwarded to the ROS machine? This is only available on e-Series models. Setting this parameter to TRUE requires multiple other parameters to be set as well. - -.. _dashboard_client: - -dashboard_client -^^^^^^^^^^^^^^^^ - -Advertised Services -~~~~~~~~~~~~~~~~~~~ - -add_to_log (\ `ur_dashboard_msgs/AddToLog `_\ ) -""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Service to add a message to the robot's log - -brake_release (\ `std_srvs/Trigger `_\ ) -"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Service to release the brakes. If the robot is currently powered off, it will get powered on on the fly. - -clear_operational_mode (\ `std_srvs/Trigger `_\ ) -""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -If this service is called the operational mode can again be changed from PolyScope, and the user password is enabled. - -close_popup (\ `std_srvs/Trigger `_\ ) -"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Close a (non-safety) popup on the teach pendant. - -close_safety_popup (\ `std_srvs/Trigger `_\ ) -""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Close a safety popup on the teach pendant. - -connect (\ `std_srvs/Trigger `_\ ) -"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Service to reconnect to the dashboard server - -get_loaded_program (\ `ur_dashboard_msgs/GetLoadedProgram `_\ ) -""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Load a robot installation from a file - -get_robot_mode (\ `ur_dashboard_msgs/GetRobotMode `_\ ) -""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Service to query the current robot mode - -get_safety_mode (\ `ur_dashboard_msgs/GetSafetyMode `_\ ) -"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Service to query the current safety mode - -load_installation (\ `ur_dashboard_msgs/Load `_\ ) -"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Load a robot installation from a file - -load_program (\ `ur_dashboard_msgs/Load `_\ ) -""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Load a robot program from a file - -pause (\ `std_srvs/Trigger `_\ ) -"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Pause a running program. - -play (\ `std_srvs/Trigger `_\ ) -""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Start execution of a previously loaded program - -popup (\ `ur_dashboard_msgs/Popup `_\ ) -"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Service to show a popup on the UR Teach pendant. - -power_off (\ `std_srvs/Trigger `_\ ) -"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Power off the robot motors - -power_on (\ `std_srvs/Trigger `_\ ) -""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Power on the robot motors. To fully start the robot, call 'brake_release' afterwards. - -program_running (\ `ur_dashboard_msgs/IsProgramRunning `_\ ) -"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Query whether there is currently a program running - -program_saved (\ `ur_dashboard_msgs/IsProgramSaved `_\ ) -"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Query whether the current program is saved - -program_state (\ `ur_dashboard_msgs/GetProgramState `_\ ) -"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Service to query the current program state - -quit (\ `ur_dashboard_msgs/GetLoadedProgram `_\ ) -""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Disconnect from the dashboard service. - -raw_request (\ `ur_dashboard_msgs/RawRequest `_\ ) -"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -General purpose service to send arbitrary messages to the dashboard server - -restart_safety (\ `std_srvs/Trigger `_\ ) -""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Used when robot gets a safety fault or violation to restart the safety. After safety has been rebooted the robot will be in Power Off. NOTE: You should always ensure it is okay to restart the system. It is highly recommended to check the error log before using this command (either via PolyScope or e.g. ssh connection). - -shutdown (\ `std_srvs/Trigger `_\ ) -""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Shutdown the robot controller - -stop (\ `std_srvs/Trigger `_\ ) -""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Stop program execution on the robot - -unlock_protective_stop (\ `std_srvs/Trigger `_\ ) -""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -Dismiss a protective stop to continue robot movements. NOTE: It is the responsibility of the user to ensure the cause of the protective stop is resolved before calling this service. - -Parameters -~~~~~~~~~~ - -receive_timeout (Required) -"""""""""""""""""""""""""" - -Timeout after which a call to the dashboard server will be considered failure if no answer has been received. - -robot_ip (Required) -""""""""""""""""""" - -The IP address under which the robot is reachable. diff --git a/ur_robot_driver/doc/dashboard_client.rst b/ur_robot_driver/doc/dashboard_client.rst new file mode 100644 index 000000000..f76d72e79 --- /dev/null +++ b/ur_robot_driver/doc/dashboard_client.rst @@ -0,0 +1,145 @@ +.. _dashboard_client: + +Dashboard client +================ + +Advertised Services +------------------- + +add_to_log (`ur_dashboard_msgs/AddToLog `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Service to add a message to the robot's log + +brake_release (`std_srvs/Trigger `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Service to release the brakes. If the robot is currently powered off, it will get powered on the fly. + +clear_operational_mode (`std_srvs/Trigger `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If this service is called the operational mode can again be changed from PolyScope, and the user password is enabled. + +close_popup (`std_srvs/Trigger `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Close a (non-safety) popup on the teach pendant. + +close_safety_popup (`std_srvs/Trigger `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Close a safety popup on the teach pendant. + +connect (`std_srvs/Trigger `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Service to reconnect to the dashboard server + +get_loaded_program (`ur_dashboard_msgs/GetLoadedProgram `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Load a robot installation from a file + +get_robot_mode (`ur_dashboard_msgs/GetRobotMode `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Service to query the current robot mode + +get_safety_mode (`ur_dashboard_msgs/GetSafetyMode `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Service to query the current safety mode + +load_installation (`ur_dashboard_msgs/Load `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Load a robot installation from a file + +load_program (`ur_dashboard_msgs/Load `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Load a robot program from a file + +pause (`std_srvs/Trigger `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Pause a running program. + +play (`std_srvs/Trigger `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Start execution of a previously loaded program + +popup (`ur_dashboard_msgs/Popup `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Service to show a popup on the UR Teach pendant. + +power_off (`std_srvs/Trigger `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Power off the robot motors + +power_on (`std_srvs/Trigger `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Power on the robot motors. To fully start the robot, call 'brake_release' afterwards. + +program_running (`ur_dashboard_msgs/IsProgramRunning `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Query whether there is currently a program running + +program_saved (`ur_dashboard_msgs/IsProgramSaved `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Query whether the current program is saved + +program_state (`ur_dashboard_msgs/GetProgramState `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Service to query the current program state + +quit (`ur_dashboard_msgs/GetLoadedProgram `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Disconnect from the dashboard service. + +raw_request (`ur_dashboard_msgs/RawRequest `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +General purpose service to send arbitrary messages to the dashboard server + +restart_safety (`std_srvs/Trigger `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Used when robot gets a safety fault or violation to restart the safety. After safety has been rebooted the robot will be in Power Off. NOTE: You should always ensure it is okay to restart the system. It is highly recommended to check the error log before using this command (either via PolyScope or e.g. ssh connection). + +shutdown (`std_srvs/Trigger `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Shutdown the robot controller + +stop (`std_srvs/Trigger `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Stop program execution on the robot + +unlock_protective_stop (`std_srvs/Trigger `_) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Dismiss a protective stop to continue robot movements. NOTE: It is the responsibility of the user to ensure the cause of the protective stop is resolved before calling this service. + +Parameters +---------- + +receive_timeout (Required) +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Timeout (in seconds, double) after which a call to the dashboard server will be considered failure if no answer has been received. + +robot_ip (Required) +^^^^^^^^^^^^^^^^^^^ + +The IP address under which the robot is reachable. diff --git a/ur_robot_driver/doc/hardware_interface_parameters.rst b/ur_robot_driver/doc/hardware_interface_parameters.rst new file mode 100644 index 000000000..e8396a640 --- /dev/null +++ b/ur_robot_driver/doc/hardware_interface_parameters.rst @@ -0,0 +1,108 @@ +UR Hardware interface parameters +================================ + +Note that parameters are passed through the ros2_control xacro definition. + +headless_mode +------------- + +Start robot in headless mode. This does not require the 'External Control' URCap to be running on the robot, but this will send the URScript to the robot directly. On e-Series robots this requires the robot to run in 'remote-control' mode. + +input_recipe_filename (Required) +-------------------------------- + +Path to the file containing the recipe used for requesting RTDE inputs. + +kinematics/hash (Required) +-------------------------- + +Hash of the calibration reported by the robot. This is used for validating the robot description is +using the correct calibration. If the robot's calibration doesn't match this hash, an error will be +printed. You can use the robot as usual, however Cartesian poses of the endeffector might be +inaccurate. See the "ur_calibration" package on help how to generate your own hash matching your +actual robot. + +non_blocking_read (default: "true") +----------------------------------- + +If set to false, the ROS control cycle will wait for the robot to send a status update. Tests have +shown that better real-time performance is achievable when setting this to ``true``. Required to be +set to ``true`` when combining with other hardware components. + +output_recipe_filename (Required) +--------------------------------- + +Path to the file containing the recipe used for requesting RTDE outputs. + +reverse_port (Required) +----------------------- + +Port that will be opened to communicate between the driver and the robot controller. + +robot_ip (Required) +------------------- + +The robot's IP address. + +script_filename (Required) +-------------------------- + +Path to the urscript code that will be sent to the robot. + +script_sender_port (Required) +----------------------------- + +The driver will offer an interface to receive the program's URScript on this port. + +servoj_gain (Required) +---------------------- + +Specify the gain for the underlying servoj command. This will be used whenever position control is +active. A higher value will lead to sharper motions, but might also introduce +higher jerks and vibrations. + +Range: [100 - 3000] + +servoj_lookahead_time (Required) +-------------------------------- + +Specify lookahead_time parameter of underlying servoj command. This will be used whenever position +control is active. A higher value will result in smoother trajectories, but will also introduce a +higher delay between the commands sent from ROS and the motion being executed on the robot. + +Unit: seconds, range: [0.03 - 0.2] + +tool_baud_rate (Required) +------------------------- + +Baud rate used for tool communication. Will be set as soon as the UR-Program on the robot is started. See UR documentation for valid baud rates. Note: This parameter is only evaluated, when the parameter "use_tool_communication" is set to ``true``. Then, this parameter is required. + +tool_parity (Required) +---------------------- + +Parity used for tool communication. Will be set as soon as the UR-Program on the robot is started. Can be 0 (None), 1 (odd) and 2 (even). Note: This parameter is only evaluated, when the parameter "use_tool_communication" is set to ``true``. Then, this parameter is required. + +tool_rx_idle_chars (Required) +----------------------------- + +Number of idle chars for the RX unit used for tool communication. Will be set as soon as the UR-Program on the robot is started. Valid values: min=1.0, max=40.0 Note: This parameter is only evaluated, when the parameter "use_tool_communication" is set to ``true``. Then, this parameter is required. + +tool_stop_bits (Required) +------------------------- + +Number of stop bits used for tool communication. Will be set as soon as the UR-Program on the robot is started. Can be 1 or 2. Note: This parameter is only evaluated, when the parameter "use_tool_communication" is set to ``true``. Then, this parameter is required. + +tool_tx_idle_chars (Required) +----------------------------- + +Number of idle chars for the TX unit used for tool communication. Will be set as soon as the UR-Program on the robot is started. Valid values: min=0.0, max=40.0 Note: This parameter is only evaluated, when the parameter "use_tool_communication" is set to ``true``. Then, this parameter is required. + +tool_voltage (Required) +----------------------- + +Tool voltage that will be set as soon as the UR-Program on the robot is started. Note: This parameter is only evaluated, when the parameter "use_tool_communication" is set to ``true``. Then, this parameter is required. + +use_tool_communication (Required) +--------------------------------- + +Should the tool's RS485 interface be forwarded to the ROS machine? This is only available on e-Series models. Setting this parameter to ``true`` requires multiple other parameters to be set as well. diff --git a/ur_robot_driver/doc/index.rst b/ur_robot_driver/doc/index.rst index 1382e4861..83d915f09 100644 --- a/ur_robot_driver/doc/index.rst +++ b/ur_robot_driver/doc/index.rst @@ -15,4 +15,5 @@ ur_robot_driver usage/toc operation_modes setup_tool_communication - ROS_INTERFACE + hardware_interface_parameters + dashboard_client From 1c41cbaa7d25b62e4964d6ef51b33987d17058bc Mon Sep 17 00:00:00 2001 From: "Felix Exner (fexner)" Date: Tue, 1 Oct 2024 10:21:45 +0200 Subject: [PATCH 11/14] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Rune Søe-Knudsen <41109954+urrsk@users.noreply.github.com> --- ur_controllers/doc/index.rst | 2 +- .../doc/hardware_interface_parameters.rst | 18 ++++++- ur_robot_driver/doc/operation_modes.rst | 51 +++++++++---------- ur_robot_driver/doc/usage/controllers.rst | 8 +-- ur_robot_driver/doc/usage/move.rst | 6 +-- ur_robot_driver/doc/usage/script_code.rst | 4 +- ur_robot_driver/doc/usage/simulation.rst | 4 +- ur_robot_driver/doc/usage/startup.rst | 14 ++--- ur_robot_driver/doc/usage/toc.rst | 2 +- 9 files changed, 58 insertions(+), 51 deletions(-) diff --git a/ur_controllers/doc/index.rst b/ur_controllers/doc/index.rst index a027d8d8b..bcf502355 100644 --- a/ur_controllers/doc/index.rst +++ b/ur_controllers/doc/index.rst @@ -8,7 +8,7 @@ robot family. Currently this contains: * 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. + but it uses the speed scaling reported to align progress of the trajectory between the robot and controller. * A **io_and_status_controller** that allows setting I/O ports, controlling some UR-specific functionality and publishes status information about the robot. diff --git a/ur_robot_driver/doc/hardware_interface_parameters.rst b/ur_robot_driver/doc/hardware_interface_parameters.rst index e8396a640..1d1a54612 100644 --- a/ur_robot_driver/doc/hardware_interface_parameters.rst +++ b/ur_robot_driver/doc/hardware_interface_parameters.rst @@ -37,7 +37,7 @@ Path to the file containing the recipe used for requesting RTDE outputs. reverse_port (Required) ----------------------- -Port that will be opened to communicate between the driver and the robot controller. +Port that will be used by to communicate between the robot controller and the driver. This port needs to be free and will be opened on the host running the driver. robot_ip (Required) ------------------- @@ -52,7 +52,8 @@ Path to the urscript code that will be sent to the robot. script_sender_port (Required) ----------------------------- -The driver will offer an interface to receive the program's URScript on this port. +Network port which the driver provides the URScript program that needs to run on the robot. This number needs to be configured for the [External Control URCap](https://github.com/UniversalRobots/Universal_Robots_ExternalControl_URCap). +This port needs to be free and will be opened on the host running the driver. servoj_gain (Required) ---------------------- @@ -77,32 +78,45 @@ tool_baud_rate (Required) Baud rate used for tool communication. Will be set as soon as the UR-Program on the robot is started. See UR documentation for valid baud rates. Note: This parameter is only evaluated, when the parameter "use_tool_communication" is set to ``true``. Then, this parameter is required. +This can also be configured using the robot teach pendant. Remember to save the installation on the robot to keep the setting after reboot. + tool_parity (Required) ---------------------- Parity used for tool communication. Will be set as soon as the UR-Program on the robot is started. Can be 0 (None), 1 (odd) and 2 (even). Note: This parameter is only evaluated, when the parameter "use_tool_communication" is set to ``true``. Then, this parameter is required. +This can also be configured using the robot teach pendant. Remember to save the installation on the robot to keep the setting after reboot. + tool_rx_idle_chars (Required) ----------------------------- Number of idle chars for the RX unit used for tool communication. Will be set as soon as the UR-Program on the robot is started. Valid values: min=1.0, max=40.0 Note: This parameter is only evaluated, when the parameter "use_tool_communication" is set to ``true``. Then, this parameter is required. +This can also be configured using the robot teach pendant. Remember to save the installation on the robot to keep the setting after reboot. + tool_stop_bits (Required) ------------------------- Number of stop bits used for tool communication. Will be set as soon as the UR-Program on the robot is started. Can be 1 or 2. Note: This parameter is only evaluated, when the parameter "use_tool_communication" is set to ``true``. Then, this parameter is required. +This can also be configured using the robot teach pendant. Remember to save the installation on the robot to keep the setting after reboot. + tool_tx_idle_chars (Required) ----------------------------- Number of idle chars for the TX unit used for tool communication. Will be set as soon as the UR-Program on the robot is started. Valid values: min=0.0, max=40.0 Note: This parameter is only evaluated, when the parameter "use_tool_communication" is set to ``true``. Then, this parameter is required. +This can also be configured using the robot teach pendant. Remember to save the installation on the robot to keep the setting after reboot. + tool_voltage (Required) ----------------------- Tool voltage that will be set as soon as the UR-Program on the robot is started. Note: This parameter is only evaluated, when the parameter "use_tool_communication" is set to ``true``. Then, this parameter is required. +This can also be configured using the robot teach pendant. Remember to save the installation on the robot to keep the setting after reboot. + use_tool_communication (Required) --------------------------------- Should the tool's RS485 interface be forwarded to the ROS machine? This is only available on e-Series models. Setting this parameter to ``true`` requires multiple other parameters to be set as well. +For more info please see :ref:`tool communication setup guide `. diff --git a/ur_robot_driver/doc/operation_modes.rst b/ur_robot_driver/doc/operation_modes.rst index 0b1f82785..2ebcda7f7 100644 --- a/ur_robot_driver/doc/operation_modes.rst +++ b/ur_robot_driver/doc/operation_modes.rst @@ -1,18 +1,18 @@ .. _operation_modes: -Modes of operation +Operation modes ================== There are two different sets of **modes** that are used throughout this documentation: -- The driver's mode of operation (External Control vs Headless) -- (e-series only) The robot's control mode (Local Control Mode vs Remote Control Mode) +- The ROS2 driver's mode of operation: _Teach pendant mode_ and _Headless mode_. +- The Robot's control mode: _Local Control Mode_ and _Remote Control Mode_. (Not applicable to the CB3 series) Both will be explained below. Robot's control modes --------------------- -On the e-series the robot itself can operate in different command modes: It can be either in local control mode where the teach pendant is the single point of command or in remote control mode, where motions from the TP, starting & loading programs from the TP activating the freedrive mode are blocked. Note that the remote control mode has to be explicitly enabled in the robot's settings under Settings -> System -> Remote Control. See the robot's manual for details. +E-series robots can operate in different command modes: It can be either in _local control mode_ where the teach pendant is the single point of control, or in _remote control mode_ where the teach pendant is locked and cannot be used to start any motion, including freedrive. Note that the ability to change to _remote control mode_ has to be explicitly enabled in the robot's settings under Settings -> System -> Remote Control. See the [robot manual](https://myur.universal-robots.com/manuals) for details. The remote control mode is needed for many aspects of this driver such as @@ -28,30 +28,29 @@ The remote control mode is needed for many aspects of this driver such as Driver's operation modes ------------------------ -There are two fundamentally different modes of operation when using this driver with a UR robot / -URSim: External Control Mode and Headless Mode. Depending on your requirements one can be more -suitable than the other. +There are two fundamentally different control modes of the UR ROS driver to control a UR robot or the URSim robot simulator: +- _Teach pendant mode_ using the :ref:`External Control URCap` +- _Headless Mode_ that works without interacting with Teach pendant, when _remote control mode_ has been selected on the teach pendant. -.. _external_control_mode: +.. _teach_pendant_mode: -External Control Mode +Teach Pendant Mode ^^^^^^^^^^^^^^^^^^^^^ -In External Control mode you will need the :ref:`External Control URCap` -installed on the robot. With that, create a program containing the *External Control* program node. -Once the program enters that node, it will request script code from an external source (in this -case the ROS driver) and execute that. +In Teach Pendant mode you will need the :ref:`External Control URCap` +installed on the robot. Please follow the installation guidelines for the :ref:`CB3` or :ref:`E-series`. Remember to set the correct IP address for the ROS driver host computer, and ensure the configured port number matches the ``script_sender_port`` defined in the ROS driver's launch arguments, default is 50002. -As soon as other script code is sent to the robot either by sending it directly through this driver -or by pressing any motion-related button on the teach pendant, the script will be overwritten by -this action and has to be restarted by using the "play" button on the teach pendant. +With that, create a program containing the *External Control* program node and press "play" on the teach pendant to start the program. +Hereafter the URCap will request script code from the ROS driver and execute it, once the program enters that node. In addition, the ROS driver can return the control to the Teach pendent program. This gives the possibility to combine the teach pendant program and the use of the ROS driver. + +Please note that a running program will stop as soon as another program is sent to the robot, either by sending it directly through this driver or by pressing any motion-related button on the teach pendant. Therefore, the ROS drivers will not be able to send commands to the robot again afterward until the ROS driver's program has been restarted. This can be done using the "play" button on the teach pendant. If this is necessary, you will see the output ``Connection to reverse interface dropped.`` from the driver. .. note:: - It is also possible to use the driver's external control mode with the robot's local control - mode together. In this case you will need to load and start the program containing the *External - Control* program node through the :ref:`dashboard_client`'s ``load_program`` and ``play`` + It is also possible to use the ROS driver's _Teach pendant mode_ with the robot's _Remote control + mode_ together. In this case you will need to load and start the program containing the *External + Control URCap* program node through the :ref:`dashboard_client`'s ``load_program`` and ``play`` services. .. _headless_mode: @@ -59,14 +58,12 @@ If this is necessary, you will see the output ``Connection to reverse interface Headless mode ^^^^^^^^^^^^^ -Inside this driver, there's the headless mode, which can be either enabled or not. When the headless mode is activated, required script code for external control will be sent to the robot directly when the driver starts. +When headless mode is activated while launching the ROS driver, the URScript code will be sent directly to the robot controller and started directly. -As soon as other script code is sent to the robot either by sending it directly through this driver -or by pressing any motion-related button on the teach pendant, the script will be overwritten by -this action and has to be restarted by using the ``/io_and_status_controller/resend_robot_program`` -service. If this is necessary, you will see the output ``Connection to reverse interface dropped.`` -from the driver. +Please note, that a running program will stop as soon as another program is sent to the robot, either by sending it directly through this driver, or by pressing any motion-related button on the teach pendant. Therefore, the ROS driver will not be able to send commands to the robot again afterward until the ROS driver's program has been restarted. +The robot program can be restarted using the ``/io_and_status_controller/resend_robot_program`` service. +If this is necessary, you will see the output ``Connection to reverse interface dropped.`` from the driver. .. note:: - On e-Series robots the robot must be in remote_control_mode as explained above in order to use the - driver's Headless Mode. + On e-Series robots and newer, the robot must be in _remote control mode_ as explained above in order to use the + ROS driver's _headless mode_. diff --git a/ur_robot_driver/doc/usage/controllers.rst b/ur_robot_driver/doc/usage/controllers.rst index b735b3dc9..8135d5cba 100644 --- a/ur_robot_driver/doc/usage/controllers.rst +++ b/ur_robot_driver/doc/usage/controllers.rst @@ -83,14 +83,10 @@ Type: :ref:`ur_controllers/ScaledJointTrajectoryController ` Scaled version of the `joint_trajectory_controller `_. -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. +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. .. 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 ^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/ur_robot_driver/doc/usage/move.rst b/ur_robot_driver/doc/usage/move.rst index b8ba4a06c..6abe1bf6e 100644 --- a/ur_robot_driver/doc/usage/move.rst +++ b/ur_robot_driver/doc/usage/move.rst @@ -3,16 +3,16 @@ Move the robot ============== -Before running any commands, first check the controllers' state using ``ros2 control list_controllers`` (Remember to install the ``ros2controlcli`` package). +First check the controllers' state using ``ros2 control list_controllers``, before running any commands. (Remember to install the ``ros2controlcli`` package). -* Send some goal to the Joint Trajectory Controller by using a demo node from `ros2_controllers_test_nodes `_ package by starting the following command in another terminal: +* Send goals to the Joint Trajectory Controller by using a demo node from `ros2_controllers_test_nodes `_ package by starting the following command in another terminal: .. code-block:: console $ ros2 launch ur_robot_driver test_scaled_joint_trajectory_controller.launch.py - After a few seconds the robot should move. + The robot should move, after a few seconds. * To test another controller, simply define it using ``initial_joint_controller`` argument, for example when using mock hardware: diff --git a/ur_robot_driver/doc/usage/script_code.rst b/ur_robot_driver/doc/usage/script_code.rst index 0a7a27f11..3e5f58079 100644 --- a/ur_robot_driver/doc/usage/script_code.rst +++ b/ur_robot_driver/doc/usage/script_code.rst @@ -21,10 +21,10 @@ Be aware, that running a program on this interface (meaning publishing script co Thus, the motion-interpreting program that is started by the driver gets stopped and has to be restarted again. Depending whether you use :ref:`headless_mode` or not, you'll have to call the ``resend_program`` service or press the ``play`` button on the teach panel to start the -external_control program again. +external control URCap program again. .. note:: - On E-series robots or newer the robot needs to be in remote control mode in order to execute custom URScript commands. + On E-series robots or newer the robot needs to be in _remote control mode_ in order to execute custom URScript commands. Currently, there is no feedback on the code's correctness. If the code sent to the robot is incorrect, it will silently not get executed. Make sure that you send valid URScript code! diff --git a/ur_robot_driver/doc/usage/simulation.rst b/ur_robot_driver/doc/usage/simulation.rst index d6e7c7ae7..caeb5fed3 100644 --- a/ur_robot_driver/doc/usage/simulation.rst +++ b/ur_robot_driver/doc/usage/simulation.rst @@ -1,8 +1,8 @@ Simulation ========== -As mentioned in the last section the driver has two basic modes of operation: Using mock hardware or -using real hardware (Or the URSim simulator, which is equivalent from the driver's perspective). +Apart from being used with a real robot, the ROS driver can be used with ros2_control's mock hardware or the URSim simulator (which is equivalent from the driver's perspective). + Additionally, the robot can be simulated using `Gazebo Classic `_ or `GZ Sim `_ but that's diff --git a/ur_robot_driver/doc/usage/startup.rst b/ur_robot_driver/doc/usage/startup.rst index d4522d042..2bfe2b7b0 100644 --- a/ur_robot_driver/doc/usage/startup.rst +++ b/ur_robot_driver/doc/usage/startup.rst @@ -6,7 +6,7 @@ Startup the driver Prepare the robot ----------------- -If you want to use a real robot (Or a URSim simulator) with this driver, you need to prepare it, +If you want to use a real robot, or a URSim simulator, with this driver, you need to prepare it, first. Make sure that you complete all steps from the :ref:`setup instructions`, installed the External Control URCap and created a program as explained :ref:`here`. @@ -54,13 +54,13 @@ Also, there are predefined launch files for all supported types of UR robots. Finish startup on the robot --------------------------- -Unless :ref:`headless_mode` is used, you will now have to start the *External Control* program on +Unless :ref:`headless_mode` is used, you will now have to start the *External Control URCap* program on the robot that you have created earlier. Depending on the :ref:`robot control mode` do the following: -* In local control mode, load the program on the robot and press the "Play" button |play_button| on the teach pendant. -* In remote control mode load and start the program using the following dashboard calls: +* In _local control mode_, load the program on the robot and press the "Play" button |play_button| on the teach pendant. +* In _remote control mode_ load and start the program using the following dashboard calls: .. code-block:: console @@ -75,7 +75,7 @@ Depending on the :ref:`robot control mode` do the following: Continuation after interruptions -------------------------------- -Whenever the *External Control* program gets interrupted, it has to be unpaused / restarted. +Whenever the *External Control URCap* program gets interrupted, it has to be unpaused / restarted. If that happens, you will see the output ``Connection to reverse interface dropped.`` @@ -91,8 +91,8 @@ This can happen, e,g, when Depending on the operation mode, perform one of the following steps: -* In local control mode, simply press the "Play" button |play_button| on the teach pendant. -* In remote control mode start the program using the following dashboard call: +* In _local control mode_, simply press the "Play" button |play_button| on the teach pendant. +* In _remote control mode_ start the program using the following dashboard call: .. code-block:: console diff --git a/ur_robot_driver/doc/usage/toc.rst b/ur_robot_driver/doc/usage/toc.rst index f26b0c61c..9f9beb8ee 100644 --- a/ur_robot_driver/doc/usage/toc.rst +++ b/ur_robot_driver/doc/usage/toc.rst @@ -84,7 +84,7 @@ interface. Ready to receive control commands.`` In general, make sure you're starting up the robot as explained :ref:`here`. -When starting the program on the TP, I get an error "The connection to the remote PC could not be established" +When starting the program on the teach pendant, I get an error "The connection to the remote PC could not be established" ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Make sure, the IP address setup is correct, as described in the setup guides From 7450f90d19fed3e1abe64d96d72cb0e155e59cb9 Mon Sep 17 00:00:00 2001 From: Felix Exner Date: Tue, 1 Oct 2024 10:26:17 +0200 Subject: [PATCH 12/14] ros_control -> ros2_control --- ur_controllers/README.md | 2 +- ur_controllers/doc/index.rst | 8 ++++---- ur_robot_driver/README.md | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/ur_controllers/README.md b/ur_controllers/README.md index b5f4adc34..583eb00ab 100644 --- a/ur_controllers/README.md +++ b/ur_controllers/README.md @@ -1,6 +1,6 @@ # ur_controllers -This package contains controllers and hardware interface for `ros_control` that are special to the UR +This package contains controllers and hardware interface for `ros2_control` that are special to the UR robot family. Currently this contains * A **speed_scaling_interface** to read the value of the current speed scaling into controllers. diff --git a/ur_controllers/doc/index.rst b/ur_controllers/doc/index.rst index bcf502355..099b3f8f4 100644 --- a/ur_controllers/doc/index.rst +++ b/ur_controllers/doc/index.rst @@ -1,7 +1,7 @@ ur_controllers ============== -This package contains controllers and hardware interface for ``ros_control`` that are special to the UR +This package contains controllers and hardware interface for ``ros2_controllers`` that are special to the UR robot family. Currently this contains: @@ -15,10 +15,10 @@ robot family. Currently this contains: About this package ------------------ -This package contains controllers not being available in the default ``ros_control`` set. They are -created to support more features offered by the UR robot family. Any of these controllers are +This package contains controllers not being available in the default ``ros2_controllers`` set. They are +created to support more features offered by the UR robot family. Some of these controllers are example implementations for certain features and are intended to be generalized and merged -into the default ``ros_control`` controller set at some future point. +into the default ``ros2_controllers`` controller set at some future point. Controller description ---------------------- diff --git a/ur_robot_driver/README.md b/ur_robot_driver/README.md index 8c7a3582f..62147df2d 100644 --- a/ur_robot_driver/README.md +++ b/ur_robot_driver/README.md @@ -48,8 +48,8 @@ For using the **tool communication interface** on e-Series robots, a `socat` scr forward the robot's tool communication interface to a local device on the ROS PC. See [the tool communication setup guide](doc/setup_tool_communication.rst) for details. -This driver is using [ROS-Control](https://wiki.ros.org/ros_control) for any control statements. -Therefore, it can be used with all position-based controllers available in ROS-Control. However, we +This driver is using [`ros2_control`](https://control.ros.org) for any control statements. +Therefore, it can be used with all position-based controllers available in `ros2_control`. However, we recommend using the controllers from the `ur_controllers` package. See it's [documentation](../ur_controllers/README.md) for details. **Note: Speed scaling support will only be available using the controllers from `ur_controllers`** From 56e9d53387f4c6d8dbd864154074d8c7b004c253 Mon Sep 17 00:00:00 2001 From: Felix Exner Date: Tue, 1 Oct 2024 10:39:19 +0200 Subject: [PATCH 13/14] Formatting fixes --- ur_robot_driver/doc/operation_modes.rst | 18 +++++++++--------- ur_robot_driver/doc/usage/script_code.rst | 2 +- ur_robot_driver/doc/usage/startup.rst | 8 ++++---- 3 files changed, 14 insertions(+), 14 deletions(-) diff --git a/ur_robot_driver/doc/operation_modes.rst b/ur_robot_driver/doc/operation_modes.rst index 2ebcda7f7..b6cb06841 100644 --- a/ur_robot_driver/doc/operation_modes.rst +++ b/ur_robot_driver/doc/operation_modes.rst @@ -5,14 +5,14 @@ Operation modes There are two different sets of **modes** that are used throughout this documentation: -- The ROS2 driver's mode of operation: _Teach pendant mode_ and _Headless mode_. -- The Robot's control mode: _Local Control Mode_ and _Remote Control Mode_. (Not applicable to the CB3 series) +- The ROS2 driver's mode of operation: *Teach Pendant mode* and *Headless mode*. +- The Robot's control mode: *local control mode* and *remote control mode*. (Not applicable to the CB3 series) Both will be explained below. Robot's control modes --------------------- -E-series robots can operate in different command modes: It can be either in _local control mode_ where the teach pendant is the single point of control, or in _remote control mode_ where the teach pendant is locked and cannot be used to start any motion, including freedrive. Note that the ability to change to _remote control mode_ has to be explicitly enabled in the robot's settings under Settings -> System -> Remote Control. See the [robot manual](https://myur.universal-robots.com/manuals) for details. +E-series robots can operate in different command modes: It can be either in *local control mode* where the teach pendant is the single point of control, or in *remote control mode* where the teach pendant is locked and cannot be used to start any motion, including freedrive. Note that the ability to change to *remote control mode* has to be explicitly enabled in the robot's settings under Settings -> System -> Remote Control. See the [robot manual](https://myur.universal-robots.com/manuals) for details. The remote control mode is needed for many aspects of this driver such as @@ -29,8 +29,8 @@ Driver's operation modes ------------------------ There are two fundamentally different control modes of the UR ROS driver to control a UR robot or the URSim robot simulator: -- _Teach pendant mode_ using the :ref:`External Control URCap` -- _Headless Mode_ that works without interacting with Teach pendant, when _remote control mode_ has been selected on the teach pendant. +- *Teach Pendant mode* using the :ref:`External Control URCap` +- *Headless mode* that works without interacting with Teach pendant, when *remote control mode* has been selected on the teach pendant. .. _teach_pendant_mode: @@ -48,8 +48,8 @@ Please note that a running program will stop as soon as another program is sent If this is necessary, you will see the output ``Connection to reverse interface dropped.`` from the driver. .. note:: - It is also possible to use the ROS driver's _Teach pendant mode_ with the robot's _Remote control - mode_ together. In this case you will need to load and start the program containing the *External + It is also possible to use the ROS driver's *Teach Pendant mode* with the robot's *remote control + mode* together. In this case you will need to load and start the program containing the *External Control URCap* program node through the :ref:`dashboard_client`'s ``load_program`` and ``play`` services. @@ -65,5 +65,5 @@ The robot program can be restarted using the ``/io_and_status_controller/resend_ If this is necessary, you will see the output ``Connection to reverse interface dropped.`` from the driver. .. note:: - On e-Series robots and newer, the robot must be in _remote control mode_ as explained above in order to use the - ROS driver's _headless mode_. + On e-Series robots and newer, the robot must be in *remote control mode* as explained above in order to use the + ROS driver's *Headless mode*. diff --git a/ur_robot_driver/doc/usage/script_code.rst b/ur_robot_driver/doc/usage/script_code.rst index 3e5f58079..384e8dc4b 100644 --- a/ur_robot_driver/doc/usage/script_code.rst +++ b/ur_robot_driver/doc/usage/script_code.rst @@ -24,7 +24,7 @@ restarted again. Depending whether you use :ref:`headless_mode` or not, you'll h external control URCap program again. .. note:: - On E-series robots or newer the robot needs to be in _remote control mode_ in order to execute custom URScript commands. + On E-series robots or newer the robot needs to be in *remote control mode* in order to execute custom URScript commands. Currently, there is no feedback on the code's correctness. If the code sent to the robot is incorrect, it will silently not get executed. Make sure that you send valid URScript code! diff --git a/ur_robot_driver/doc/usage/startup.rst b/ur_robot_driver/doc/usage/startup.rst index 2bfe2b7b0..8db29bb68 100644 --- a/ur_robot_driver/doc/usage/startup.rst +++ b/ur_robot_driver/doc/usage/startup.rst @@ -59,8 +59,8 @@ the robot that you have created earlier. Depending on the :ref:`robot control mode` do the following: -* In _local control mode_, load the program on the robot and press the "Play" button |play_button| on the teach pendant. -* In _remote control mode_ load and start the program using the following dashboard calls: +* In *local control mode*, load the program on the robot and press the "Play" button |play_button| on the teach pendant. +* In *remote control mode* load and start the program using the following dashboard calls: .. code-block:: console @@ -91,8 +91,8 @@ This can happen, e,g, when Depending on the operation mode, perform one of the following steps: -* In _local control mode_, simply press the "Play" button |play_button| on the teach pendant. -* In _remote control mode_ start the program using the following dashboard call: +* In *local control mode*, simply press the "Play" button |play_button| on the teach pendant. +* In *remote control mode* start the program using the following dashboard call: .. code-block:: console From 98e985821b76bbb84b22a5fe94ac8148190dcbb5 Mon Sep 17 00:00:00 2001 From: Felix Exner Date: Tue, 1 Oct 2024 10:43:46 +0200 Subject: [PATCH 14/14] More formatting fixes thanks doc8 linter :-) --- ur_robot_driver/doc/usage/controllers.rst | 1 - ur_robot_driver/doc/usage/toc.rst | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/ur_robot_driver/doc/usage/controllers.rst b/ur_robot_driver/doc/usage/controllers.rst index 8135d5cba..d1566758b 100644 --- a/ur_robot_driver/doc/usage/controllers.rst +++ b/ur_robot_driver/doc/usage/controllers.rst @@ -86,7 +86,6 @@ Scaled version of the 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. -.. note:: io_and_status_controller ^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/ur_robot_driver/doc/usage/toc.rst b/ur_robot_driver/doc/usage/toc.rst index 9f9beb8ee..a36193bd8 100644 --- a/ur_robot_driver/doc/usage/toc.rst +++ b/ur_robot_driver/doc/usage/toc.rst @@ -85,7 +85,7 @@ interface. Ready to receive control commands.`` In general, make sure you're starting up the robot as explained :ref:`here`. When starting the program on the teach pendant, I get an error "The connection to the remote PC could not be established" -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Make sure, the IP address setup is correct, as described in the setup guides (:ref:`CB3 robots`, :ref:`e-Series robots`)