diff --git a/.github/workflows/update-ci.yml b/.github/workflows/update-ci.yml index aa75b4f4b..f304a5899 100644 --- a/.github/workflows/update-ci.yml +++ b/.github/workflows/update-ci.yml @@ -28,7 +28,7 @@ jobs: # Create pull request - name: Create pull-request id: cpr - uses: peter-evans/create-pull-request@v6 + uses: peter-evans/create-pull-request@v7 with: branch: update-ci/pre-commit-autoupdate delete-branch: true diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 7b6e3de7e..52077980f 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -15,7 +15,7 @@ repos: # Standard hooks - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.6.0 + rev: v5.0.0 hooks: - id: check-added-large-files - id: check-ast @@ -69,7 +69,7 @@ repos: - id: ament_cppcheck name: ament_cppcheck description: Static code analysis of C/C++ files. - stages: [commit] + stages: [pre-commit] entry: env AMENT_CPPCHECK_ALLOW_SLOW_VERSIONS=1 ament_cppcheck language: system files: \.(h\+\+|h|hh|hxx|hpp|cuh|c|cc|cpp|cu|c\+\+|cxx|tpp|txx)$ @@ -80,7 +80,7 @@ repos: - id: ament_cpplint name: ament_cpplint description: Static code analysis of C/C++ files. - stages: [commit] + stages: [pre-commit] entry: ament_cpplint language: system files: \.(h\+\+|h|hh|hxx|hpp|cuh|c|cc|cpp|cu|c\+\+|cxx|tpp|txx)$ @@ -102,7 +102,7 @@ repos: - id: ament_lint_cmake name: ament_lint_cmake description: Check format of CMakeLists.txt files. - stages: [commit] + stages: [pre-commit] entry: ament_lint_cmake language: system files: CMakeLists.txt$ @@ -113,14 +113,14 @@ repos: - id: ament_copyright name: ament_copyright description: Check if copyright notice is available in all files. - stages: [commit] + stages: [pre-commit] entry: ament_copyright language: system args: ['--exclude', 'ur_robot_driver/doc/conf.py', 'ur_calibration/doc/conf.py'] # Docs - RestructuredText hooks - repo: https://github.com/PyCQA/doc8 - rev: v1.1.1 + rev: v1.1.2 hooks: - id: doc8 args: ['--max-line-length=100', '--ignore=D001'] diff --git a/ci_status.md b/ci_status.md index c4b6013f8..4df0e8f42 100644 --- a/ci_status.md +++ b/ci_status.md @@ -107,11 +107,11 @@ red pipeline there should be a corresponding issue labeled with [ci-failure](htt -
- - - - +
+ + + +
diff --git a/ur/CHANGELOG.rst b/ur/CHANGELOG.rst index 2a47844f3..de92d7836 100644 --- a/ur/CHANGELOG.rst +++ b/ur/CHANGELOG.rst @@ -2,6 +2,11 @@ Changelog for package ur ^^^^^^^^^^^^^^^^^^^^^^^^ +2.4.10 (2024-09-11) +------------------- +* Update maintainers team (`#1088 `_) +* Contributors: Vincenzo Di Pentima + 2.4.9 (2024-08-09) ------------------ diff --git a/ur/package.xml b/ur/package.xml index 492b807d9..cb6c5df62 100644 --- a/ur/package.xml +++ b/ur/package.xml @@ -2,7 +2,7 @@ ur - 2.4.9 + 2.4.10 Metapackage for universal robots Felix Exner Vincenzo Di Pentima diff --git a/ur_calibration/CHANGELOG.rst b/ur_calibration/CHANGELOG.rst index ebba7e225..9171c0e94 100644 --- a/ur_calibration/CHANGELOG.rst +++ b/ur_calibration/CHANGELOG.rst @@ -2,6 +2,11 @@ Changelog for package ur_calibration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +2.4.10 (2024-09-11) +------------------- +* Update maintainers team (`#1088 `_) +* Contributors: Vincenzo Di Pentima + 2.4.9 (2024-08-09) ------------------ diff --git a/ur_calibration/package.xml b/ur_calibration/package.xml index aa219766a..f5b2d2294 100644 --- a/ur_calibration/package.xml +++ b/ur_calibration/package.xml @@ -1,7 +1,7 @@ ur_calibration - 2.4.9 + 2.4.10 Package for extracting the factory calibration from a UR robot and change it such that it can be used by ur_description to gain a correct URDF Felix Exner diff --git a/ur_controllers/CHANGELOG.rst b/ur_controllers/CHANGELOG.rst index b4edbb8f0..1ff840740 100644 --- a/ur_controllers/CHANGELOG.rst +++ b/ur_controllers/CHANGELOG.rst @@ -2,6 +2,12 @@ Changelog for package ur_controllers ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +2.4.10 (2024-09-11) +------------------- +* Updated get_state to get_lifecycle_state (`#1087 `_) +* Update maintainers team (`#1088 `_) +* Contributors: Vincenzo Di Pentima + 2.4.9 (2024-08-09) ------------------ 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 6d7828462..099b3f8f4 100644 --- a/ur_controllers/doc/index.rst +++ b/ur_controllers/doc/index.rst @@ -1,25 +1,24 @@ 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: -* 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. + 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. 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 ---------------------- @@ -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_controllers/package.xml b/ur_controllers/package.xml index b21490d5d..98f304df8 100644 --- a/ur_controllers/package.xml +++ b/ur_controllers/package.xml @@ -2,7 +2,7 @@ ur_controllers - 2.4.9 + 2.4.10 Provides controllers that use the speed scaling interface of Universal Robots. Felix Exner diff --git a/ur_dashboard_msgs/CHANGELOG.rst b/ur_dashboard_msgs/CHANGELOG.rst index 07c82f17f..ef254ed51 100644 --- a/ur_dashboard_msgs/CHANGELOG.rst +++ b/ur_dashboard_msgs/CHANGELOG.rst @@ -2,6 +2,11 @@ Changelog for package ur_dashboard_msgs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +2.4.10 (2024-09-11) +------------------- +* Update maintainers team (`#1088 `_) +* Contributors: Vincenzo Di Pentima + 2.4.9 (2024-08-09) ------------------ diff --git a/ur_dashboard_msgs/package.xml b/ur_dashboard_msgs/package.xml index a3d5b99c2..ff12608c6 100644 --- a/ur_dashboard_msgs/package.xml +++ b/ur_dashboard_msgs/package.xml @@ -2,7 +2,7 @@ ur_dashboard_msgs - 2.4.9 + 2.4.10 Messages around the UR Dashboard server. Felix Exner diff --git a/ur_moveit_config/CHANGELOG.rst b/ur_moveit_config/CHANGELOG.rst index ec1fdd1d0..8b388c94d 100644 --- a/ur_moveit_config/CHANGELOG.rst +++ b/ur_moveit_config/CHANGELOG.rst @@ -2,6 +2,9 @@ Changelog for package ur_moveit_config ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +2.4.10 (2024-09-11) +------------------- + 2.4.9 (2024-08-09) ------------------ * Added Jazzy migration notes for moveit_config (`#1058 `_) diff --git a/ur_moveit_config/package.xml b/ur_moveit_config/package.xml index 5c2024de2..1fd61259a 100644 --- a/ur_moveit_config/package.xml +++ b/ur_moveit_config/package.xml @@ -2,7 +2,7 @@ ur_moveit_config - 2.4.9 + 2.4.10 An example package with MoveIt2 configurations for UR robots. diff --git a/ur_robot_driver/CHANGELOG.rst b/ur_robot_driver/CHANGELOG.rst index d04d40118..cd6502c5b 100644 --- a/ur_robot_driver/CHANGELOG.rst +++ b/ur_robot_driver/CHANGELOG.rst @@ -1,3 +1,9 @@ +2.4.10 (2024-09-11) +------------------- +* Fix for forward_velocity_controller test (`#1076 `_) +* Update maintainers team (`#1088 `_) +* Contributors: Vincenzo Di Pentima + 2.4.9 (2024-08-09) ------------------ * Added dynamics tag when using mock_components/GenericSystem (`#1075 `_) 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`** diff --git a/ur_robot_driver/config/test_velocity_goal_publishers_config.yaml b/ur_robot_driver/config/test_velocity_goal_publishers_config.yaml index 4d27858ca..185c7b7c4 100644 --- a/ur_robot_driver/config/test_velocity_goal_publishers_config.yaml +++ b/ur_robot_driver/config/test_velocity_goal_publishers_config.yaml @@ -1,10 +1,10 @@ publisher_forward_velocity_controller: ros__parameters: - controller_name: "forward_velocity_controller" + publish_topic: "forward_velocity_controller/commands" wait_sec_between_publish: 5 - goal_names: ["pos1", "pos2", "pos3"] - pos1: [0.0, 0.0, 0.0, 0.0, 0.0, 0.05] - pos2: [0.0, 0.0, 0.0, 0.0, 0.0, -0.05] - pos3: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0] + goal_names: ["vel1", "vel2", "vel3"] + vel1: [0.0, 0.0, 0.0, 0.0, 0.0, 0.5] + vel2: [0.0, 0.0, 0.0, 0.0, 0.0, -0.5] + vel3: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0] diff --git a/ur_robot_driver/doc/ROS_INTERFACE.rst b/ur_robot_driver/doc/ROS_INTERFACE.rst deleted file mode 100644 index 0f7a4f373..000000000 --- a/ur_robot_driver/doc/ROS_INTERFACE.rst +++ /dev/null @@ -1,264 +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 -^^^^^^^^^^^^^^^^ - -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..1d1a54612 --- /dev/null +++ b/ur_robot_driver/doc/hardware_interface_parameters.rst @@ -0,0 +1,122 @@ +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 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) +------------------- + +The robot's IP address. + +script_filename (Required) +-------------------------- + +Path to the urscript code that will be sent to the robot. + +script_sender_port (Required) +----------------------------- + +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) +---------------------- + +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. + +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/index.rst b/ur_robot_driver/doc/index.rst index bef2baf74..83d915f09 100644 --- a/ur_robot_driver/doc/index.rst +++ b/ur_robot_driver/doc/index.rst @@ -12,6 +12,8 @@ ur_robot_driver overview installation/toc - usage + usage/toc + operation_modes setup_tool_communication - ROS_INTERFACE + hardware_interface_parameters + dashboard_client 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/operation_modes.rst b/ur_robot_driver/doc/operation_modes.rst new file mode 100644 index 000000000..b6cb06841 --- /dev/null +++ b/ur_robot_driver/doc/operation_modes.rst @@ -0,0 +1,69 @@ +.. _operation_modes: + +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) + +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. + +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 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: + +Teach Pendant Mode +^^^^^^^^^^^^^^^^^^^^^ + +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. + +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 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: + +Headless mode +^^^^^^^^^^^^^ + +When headless mode is activated while launching the ROS driver, the URScript code will be sent directly to the robot controller and started directly. + +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 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/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.rst b/ur_robot_driver/doc/usage.rst deleted file mode 100644 index 365a047e5..000000000 --- a/ur_robot_driver/doc/usage.rst +++ /dev/null @@ -1,287 +0,0 @@ -.. role:: raw-html-m2r(raw) - :format: html - - -Usage -===== - -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. - -Modes of operation ------------------- - -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. - -.. 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 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -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_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``. - -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 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..d1566758b --- /dev/null +++ b/ur_robot_driver/doc/usage/controllers.rst @@ -0,0 +1,112 @@ +Controllers +=========== + +This help page describes the different controllers available for the ``ur_robot_driver``. This +should help users finding the right controller for their specific use case. + +Where are controllers defined? +------------------------------ + +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 thereby the safety compliance features, like pause on safeguard stop. In addition, it also makes it possible to adjust execution speed using the speed slider on the teach pendant or set the program in pause and restart it again. +See it's linked documentation for details. + +io_and_status_controller +^^^^^^^^^^^^^^^^^^^^^^^^ + +Type: :ref:`ur_controllers/GPIOController ` + +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``. diff --git a/ur_robot_driver/doc/usage/move.rst b/ur_robot_driver/doc/usage/move.rst new file mode 100644 index 000000000..6abe1bf6e --- /dev/null +++ b/ur_robot_driver/doc/usage/move.rst @@ -0,0 +1,70 @@ +.. _move_the_robot: + +Move the robot +============== + +First check the controllers' state using ``ros2 control list_controllers``, before running any commands. (Remember to install the ``ros2controlcli`` package). + + +* 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 + + 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: + + .. 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/script_code.rst b/ur_robot_driver/doc/usage/script_code.rst new file mode 100644 index 000000000..384e8dc4b --- /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 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. + 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..caeb5fed3 --- /dev/null +++ b/ur_robot_driver/doc/usage/simulation.rst @@ -0,0 +1,45 @@ +Simulation +========== + +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 +outside of this driver's scope. + +.. _usage_with_official_ur_simulator: + +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 `. + +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. diff --git a/ur_robot_driver/doc/usage/startup.rst b/ur_robot_driver/doc/usage/startup.rst new file mode 100644 index 000000000..8db29bb68 --- /dev/null +++ b/ur_robot_driver/doc/usage/startup.rst @@ -0,0 +1,113 @@ +.. _ur_robot_driver_startup: + +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, +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 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 + + $ 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: + + +* ``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. + +.. _robot_startup_program: + +Finish startup on the robot +--------------------------- + +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: + + .. 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: + +Continuation after interruptions +-------------------------------- + +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.`` + +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. + + * Script code was sent to the robot via its primary interface + * Robot motion is performed using the Teach pendant + +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: + + .. code-block:: console + + $ ros2 service call /dashboard_client/play std_srvs/srv/Trigger {} + +* When the driver is started with ``headless_mode:=true`` perform the following service call: + + .. code-block:: console + + $ ros2 service call /io_and_status_controller/resend_robot_program std_srvs/srv/Trigger {} + + + + + +.. |play_button| image:: ../resources/play_button.svg + :height: 20px + :width: 20px diff --git a/ur_robot_driver/doc/usage/toc.rst b/ur_robot_driver/doc/usage/toc.rst new file mode 100644 index 000000000..a36193bd8 --- /dev/null +++ b/ur_robot_driver/doc/usage/toc.rst @@ -0,0 +1,118 @@ +##### +Usage +##### + +This chapter explains how to use the ``ur_robot_driver`` + + +.. toctree:: + :maxdepth: 4 + :caption: Contents: + + startup + move + controllers + simulation + script_code + +Quick start +----------- + +Driver startup +^^^^^^^^^^^^^^ + +* To start it with hardware, use: + + .. code-block:: console + + $ ros2 launch ur_robot_driver ur_control.launch.py ur_type:= robot_ip:= launch_rviz:=true + + After starting the launch file start the external_control URCap program from the pendant, as described :ref:`here`. + +* To run it with URSim check details about it in :ref:`this section `. + +* To use mocked hardware (capability of ros2_control), use ``use_mock_hardware`` argument, like: + + .. 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 + + +Sending commands to controllers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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 +------------ + +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. + +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 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`) + +.. 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 diff --git a/ur_robot_driver/launch/test_forward_velocity_controller.launch.py b/ur_robot_driver/launch/test_forward_velocity_controller.launch.py index 87e0ca89f..ac74fa347 100644 --- a/ur_robot_driver/launch/test_forward_velocity_controller.launch.py +++ b/ur_robot_driver/launch/test_forward_velocity_controller.launch.py @@ -38,7 +38,7 @@ def generate_launch_description(): - velocity_goals = PathJoinSubstitution( + velocity_config = PathJoinSubstitution( [FindPackageShare("ur_robot_driver"), "config", "test_velocity_goal_publishers_config.yaml"] ) @@ -48,7 +48,7 @@ def generate_launch_description(): package="ros2_controllers_test_nodes", executable="publisher_forward_position_controller", name="publisher_forward_velocity_controller", - parameters=[velocity_goals], + parameters=[velocity_config], output="screen", ) ] diff --git a/ur_robot_driver/launch/ur_control.launch.py b/ur_robot_driver/launch/ur_control.launch.py index b730361c5..6af726a08 100644 --- a/ur_robot_driver/launch/ur_control.launch.py +++ b/ur_robot_driver/launch/ur_control.launch.py @@ -29,23 +29,26 @@ # # Author: Denis Stogl -from launch_ros.actions import Node -from launch_ros.parameter_descriptions import ParameterFile -from launch_ros.substitutions import FindPackageShare - from launch import LaunchDescription -from launch.actions import DeclareLaunchArgument, IncludeLaunchDescription +from launch.actions import ( + DeclareLaunchArgument, + IncludeLaunchDescription, + OpaqueFunction, +) from launch.conditions import IfCondition, UnlessCondition +from launch.launch_description_sources import AnyLaunchDescriptionSource from launch.substitutions import ( AndSubstitution, LaunchConfiguration, NotSubstitution, PathJoinSubstitution, ) -from launch.launch_description_sources import AnyLaunchDescriptionSource +from launch_ros.actions import Node +from launch_ros.parameter_descriptions import ParameterFile +from launch_ros.substitutions import FindPackageShare -def launch_setup(): +def launch_setup(context): # Initialize Arguments ur_type = LaunchConfiguration("ur_type") robot_ip = LaunchConfiguration("robot_ip") @@ -165,38 +168,20 @@ def controller_spawner(controllers, active=True): "force_torque_sensor_broadcaster", "ur_configuration_controller", ] - controllers_inactive = ["forward_position_controller"] - - controller_spawners = [controller_spawner(controllers_active)] + [ - controller_spawner(controllers_inactive, active=False) + controllers_inactive = [ + "scaled_joint_trajectory_controller", + "joint_trajectory_controller", + "forward_velocity_controller", + "forward_position_controller", ] + if activate_joint_controller.perform(context) == "true": + controllers_active.append(initial_joint_controller.perform(context)) + controllers_inactive.remove(initial_joint_controller.perform(context)) - # There may be other controllers of the joints, but this is the initially-started one - initial_joint_controller_spawner_started = Node( - package="controller_manager", - executable="spawner", - arguments=[ - initial_joint_controller, - "-c", - "/controller_manager", - "--controller-manager-timeout", - controller_spawner_timeout, - ], - condition=IfCondition(activate_joint_controller), - ) - initial_joint_controller_spawner_stopped = Node( - package="controller_manager", - executable="spawner", - arguments=[ - initial_joint_controller, - "-c", - "/controller_manager", - "--controller-manager-timeout", - controller_spawner_timeout, - "--inactive", - ], - condition=UnlessCondition(activate_joint_controller), - ) + controller_spawners = [ + controller_spawner(controllers_active), + controller_spawner(controllers_inactive, active=False), + ] rsp = IncludeLaunchDescription( AnyLaunchDescriptionSource(description_launchfile), @@ -214,8 +199,6 @@ def controller_spawner(controllers, active=True): urscript_interface, rsp, rviz_node, - initial_joint_controller_spawner_stopped, - initial_joint_controller_spawner_started, ] + controller_spawners return nodes_to_start @@ -330,6 +313,12 @@ def generate_launch_description(): DeclareLaunchArgument( "initial_joint_controller", default_value="scaled_joint_trajectory_controller", + choices=[ + "scaled_joint_trajectory_controller", + "joint_trajectory_controller", + "forward_velocity_controller", + "forward_position_controller", + ], description="Initially loaded robot controller.", ) ) @@ -481,4 +470,4 @@ def generate_launch_description(): ], ) ) - return LaunchDescription(declared_arguments + launch_setup()) + return LaunchDescription(declared_arguments + [OpaqueFunction(function=launch_setup)]) diff --git a/ur_robot_driver/launch/ur_rsp.launch.py b/ur_robot_driver/launch/ur_rsp.launch.py index aa2324223..375e6adef 100644 --- a/ur_robot_driver/launch/ur_rsp.launch.py +++ b/ur_robot_driver/launch/ur_rsp.launch.py @@ -31,6 +31,7 @@ from launch_ros.actions import Node from launch_ros.substitutions import FindPackageShare +from launch_ros.parameter_descriptions import ParameterValue from launch import LaunchDescription from launch.actions import DeclareLaunchArgument @@ -185,7 +186,9 @@ def generate_launch_description(): " ", ] ) - robot_description = {"robot_description": robot_description_content} + robot_description = { + "robot_description": ParameterValue(robot_description_content, value_type=str) + } declared_arguments = [] # UR specific arguments diff --git a/ur_robot_driver/package.xml b/ur_robot_driver/package.xml index 9cf762746..852177bfe 100644 --- a/ur_robot_driver/package.xml +++ b/ur_robot_driver/package.xml @@ -2,7 +2,7 @@ ur_robot_driver - 2.4.9 + 2.4.10 The new driver for Universal Robots UR3, UR5 and UR10 robots with CB3 controllers and the e-series. Felix Exner