From 0a6401856944d1b70a23caa4e60fcf96da0e8c40 Mon Sep 17 00:00:00 2001 From: Felix Exner Date: Thu, 10 Mar 2022 14:47:58 +0100 Subject: [PATCH 1/2] Migrate doc structure towards sphinx documentation This gets built by the buildfarm automatically, which should provide a a better entrypoint for users. The generated documentation will be hosted on docs.ros.org --- ur_robot_driver/doc/ROS_INTERFACE.md | 1059 ------------- ur_robot_driver/doc/ROS_INTERFACE.rst | 1324 +++++++++++++++++ ur_robot_driver/doc/conf.py | 185 +++ ur_robot_driver/doc/controllers.md | 190 --- ur_robot_driver/doc/controllers.rst | 231 +++ ur_robot_driver/doc/features.md | 38 - ur_robot_driver/doc/features.rst | 68 + ur_robot_driver/doc/index.rst | 14 + ur_robot_driver/doc/installation/build.rst | 61 + .../initial_setup_images/cb3_01_welcome.png | Bin .../cb3_05_urcaps_installed.png | Bin .../cb3_07_installation_excontrol.png | Bin .../cb3_10_prog_structure_urcaps.png | Bin .../cb3_11_program_view_excontrol.png | Bin .../initial_setup_images/e-Series.jpg | Bin .../initial_setup_images/es_01_welcome.png | Bin .../es_05_urcaps_installed.png | Bin .../es_07_installation_excontrol.png | Bin .../es_10_prog_structure_urcaps.png | Bin .../es_11_program_view_excontrol.png | Bin .../install_urcap_cb3.rst} | 31 +- .../install_urcap_e_series.rst} | 33 +- .../doc/installation/real_time_kernel.rst | 312 ++++ .../doc/installation/requirements.rst | 17 + .../doc/installation/robot_setup.rst | 48 + ur_robot_driver/doc/installation/toc.rst | 17 + ur_robot_driver/doc/real_time.md | 282 ---- ur_robot_driver/doc/rosdoc.yaml | 2 + ...cation.md => setup_tool_communication.rst} | 53 +- .../{usage_example.md => usage_example.rst} | 203 ++- 30 files changed, 2486 insertions(+), 1682 deletions(-) delete mode 100644 ur_robot_driver/doc/ROS_INTERFACE.md create mode 100644 ur_robot_driver/doc/ROS_INTERFACE.rst create mode 100644 ur_robot_driver/doc/conf.py delete mode 100644 ur_robot_driver/doc/controllers.md create mode 100644 ur_robot_driver/doc/controllers.rst delete mode 100644 ur_robot_driver/doc/features.md create mode 100644 ur_robot_driver/doc/features.rst create mode 100644 ur_robot_driver/doc/index.rst create mode 100644 ur_robot_driver/doc/installation/build.rst rename ur_robot_driver/doc/{ => installation}/initial_setup_images/cb3_01_welcome.png (100%) rename ur_robot_driver/doc/{ => installation}/initial_setup_images/cb3_05_urcaps_installed.png (100%) rename ur_robot_driver/doc/{ => installation}/initial_setup_images/cb3_07_installation_excontrol.png (100%) rename ur_robot_driver/doc/{ => installation}/initial_setup_images/cb3_10_prog_structure_urcaps.png (100%) rename ur_robot_driver/doc/{ => installation}/initial_setup_images/cb3_11_program_view_excontrol.png (100%) rename ur_robot_driver/doc/{ => installation}/initial_setup_images/e-Series.jpg (100%) rename ur_robot_driver/doc/{ => installation}/initial_setup_images/es_01_welcome.png (100%) rename ur_robot_driver/doc/{ => installation}/initial_setup_images/es_05_urcaps_installed.png (100%) rename ur_robot_driver/doc/{ => installation}/initial_setup_images/es_07_installation_excontrol.png (100%) rename ur_robot_driver/doc/{ => installation}/initial_setup_images/es_10_prog_structure_urcaps.png (100%) rename ur_robot_driver/doc/{ => installation}/initial_setup_images/es_11_program_view_excontrol.png (100%) rename ur_robot_driver/doc/{install_urcap_cb3.md => installation/install_urcap_cb3.rst} (70%) rename ur_robot_driver/doc/{install_urcap_e_series.md => installation/install_urcap_e_series.rst} (69%) create mode 100644 ur_robot_driver/doc/installation/real_time_kernel.rst create mode 100644 ur_robot_driver/doc/installation/requirements.rst create mode 100644 ur_robot_driver/doc/installation/robot_setup.rst create mode 100644 ur_robot_driver/doc/installation/toc.rst delete mode 100644 ur_robot_driver/doc/real_time.md rename ur_robot_driver/doc/{setup_tool_communication.md => setup_tool_communication.rst} (55%) rename ur_robot_driver/doc/{usage_example.md => usage_example.rst} (52%) diff --git a/ur_robot_driver/doc/ROS_INTERFACE.md b/ur_robot_driver/doc/ROS_INTERFACE.md deleted file mode 100644 index 90d627a4d..000000000 --- a/ur_robot_driver/doc/ROS_INTERFACE.md +++ /dev/null @@ -1,1059 +0,0 @@ -# ur_robot_driver - -The new driver for Universal Robots UR3, UR5 and UR10 robots with CB3 controllers and the e-series. - -## Launchfiles - -### ur3e_bringup.launch - -Standalone launchfile to startup a ur3e. This requires a robot reachable via a network connection. - -#### Arguments - -##### controller_config_file (default: "$(find ur_robot_driver)/config/ur3e_controllers.yaml") - -Config file used for defining the ROS-Control controllers. - -##### controllers (default: "joint_state_controller scaled_pos_joint_traj_controller speed_scaling_state_controller force_torque_sensor_controller") - -Controllers that are activated by default. - -##### debug (default: "false") - -Debug flag that will get passed on to ur_common.launch - -##### headless_mode (default: "false") - -Automatically send URScript to robot to execute. On e-Series this does require the robot to be in 'remote-control' mode. With this, the URCap is not needed on the robot. - -##### kinematics_config (default: "$(find ur_description)/config/ur3e/default_kinematics.yaml") - -Kinematics config file used for calibration correction. This will be used to verify the robot's calibration is matching the robot_description. - -**Note:** The `default_kinematics.yaml` file will not reflect the kinematic parameters of your -robot. Make sure to [generate your own config file](https://github.com/UniversalRobots/Universal_Robots_ROS_Driver#extract-calibration-information). - -##### limited (default: "false") - -Use the description in limited mode (Every axis rotates from -PI to PI) - -##### reverse_port (default: "50001") - -Port that will be opened by the driver to allow direct communication between the driver and the robot controller. - -##### robot_description_file (default: "$(find ur_description)/launch/load_ur3e.launch") - -Robot description launch file. - -##### robot_ip (Required) - -IP address by which the robot can be reached. - -##### script_sender_port (default: "50002") - -The driver will offer an interface to receive the program's URScript on this port. If the robot cannot connect to this port, `External Control` will stop immediately. - -##### stopped_controllers (default: "pos_joint_traj_controller joint_group_vel_controller") - -Controllers that are initally loaded, but not started. - -##### tf_prefix (default: "") - -tf_prefix used for the robot. - -##### wrench_frame_id (default: "wrench") - -Parameter to set the id of the wrench frame, required if using multiple robots - -##### tool_baud_rate (default: "115200") - -Baud rate used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_device_name (default: "/tmp/ttyUR") - -Local device name used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_parity (default: "0") - -Parity configuration used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_rx_idle_chars (default: "1.5") - -Number of idle chars in RX channel used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_stop_bits (default: "1") - -Number of stop bits used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_tcp_port (default: "54321") - -Port on which the robot controller publishes the tool comm interface. Only used, when `use_tool_communication` is set to true. - -##### tool_tx_idle_chars (default: "3.5") - -Number of idle chars in TX channel used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_voltage (default: "0") - -Tool voltage set at the beginning of the UR program. Only used, when `use_tool_communication` is set to true. - -##### use_tool_communication (default: "false") - -On e-Series robots tool communication can be enabled with this argument - -### ur10_bringup.launch - -Standalone launchfile to startup a ur10 robot. This requires a robot reachable via a network connection. - -#### Arguments - -##### controller_config_file (default: "$(find ur_robot_driver)/config/ur10_controllers.yaml") - -Config file used for defining the ROS-Control controllers. - -##### controllers (default: "joint_state_controller scaled_pos_joint_traj_controller speed_scaling_state_controller force_torque_sensor_controller") - -Controllers that are activated by default. - -##### debug (default: "false") - -Debug flag that will get passed on to ur_common.launch - -##### headless_mode (default: "false") - -Automatically send URScript to robot to execute. On e-Series this does require the robot to be in 'remote-control' mode. With this, the URCap is not needed on the robot. - -##### kinematics_config (default: "$(find ur_description)/config/ur10/default_kinematics.yaml") - -Kinematics config file used for calibration correction. This will be used to verify the robot's calibration is matching the robot_description. - -**Note:** The `default_kinematics.yaml` file will not reflect the kinematic parameters of your -robot. Make sure to [generate your own config file](https://github.com/UniversalRobots/Universal_Robots_ROS_Driver#extract-calibration-information). - -##### limited (default: "false") - -Use the description in limited mode (Every axis rotates from -PI to PI) - -##### reverse_port (default: "50001") - -Port that will be opened by the driver to allow direct communication between the driver and the robot controller. - -##### robot_description_file (default: "$(find ur_description)/launch/load_ur10.launch") - -Robot description launch file. - -##### robot_ip (Required) - -IP address by which the robot can be reached. - -##### script_sender_port (default: "50002") - -The driver will offer an interface to receive the program's URScript on this port. If the robot cannot connect to this port, `External Control` will stop immediately. - -##### stopped_controllers (default: "pos_joint_traj_controller joint_group_vel_controller") - -Controllers that are initally loaded, but not started. - -##### tf_prefix (default: "") - -tf_prefix used for the robot. - -### ur_control.launch - -Robot bringup launchfile without the robot description. Include this, if you want to include robot control into a larger launchfile structure. - -#### Arguments - -##### controller_config_file (Required) - -Config file used for defining the ROS-Control controllers. - -##### controllers (default: "joint_state_controller vel_based_pos_joint_traj_controller force_torque_sensor_controller") - -Controllers that are activated by default. - -##### debug (default: "false") - -If set to true, will start the driver inside gdb - -##### headless_mode (default: "false") - -Automatically send URScript to robot to execute. On e-Series this does require the robot to be in 'remote-control' mode. With this, the URCap is not needed on the robot. - -##### kinematics_config (Required) - -Kinematics config file used for calibration correction. This will be used to verify the robot's calibration is matching the robot_description. Pass the same config file that is passed to the robot_description. - -**Note:** The `default_kinematics.yaml` file will not reflect the kinematic parameters of your -robot. Make sure to [generate your own config file](https://github.com/UniversalRobots/Universal_Robots_ROS_Driver#extract-calibration-information). - -##### launch_prefix (Required) - -Please add description. See file "launch/ur_control.launch". - -##### reverse_port (default: "50001") - -Port that will be opened by the driver to allow direct communication between the driver and the robot controller. - -##### robot_ip (Required) - -IP address by which the robot can be reached. - -##### rtde_input_recipe_file (default: "$(find ur_robot_driver)/resources/rtde_input_recipe.txt") - -Recipe file used for the RTDE-inputs. Only change this if you know what you're doing. - -##### rtde_output_recipe_file (default: "$(find ur_robot_driver)/resources/rtde_output_recipe.txt") - -Recipe file used for the RTDE-outputs. Only change this if you know what you're doing. - -##### script_sender_port (default: "50002") - -The driver will offer an interface to receive the program's URScript on this port. If the robot cannot connect to this port, `External Control` will stop immediately. - -##### stopped_controllers (default: "joint_group_vel_controller") - -Controllers that are initally loaded, but not started. - -##### tf_prefix (default: "") - -tf_prefix used for the robot. - -##### tool_baud_rate (default: "115200") - -Baud rate used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_device_name (default: "/tmp/ttyUR") - -Local device name used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_parity (default: "0") - -Parity configuration used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_rx_idle_chars (default: "1.5") - -Number of idle chars in RX channel used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_stop_bits (default: "1") - -Number of stop bits used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_tcp_port (default: "54321") - -Port on which the robot controller publishes the tool comm interface. Only used, when `use_tool_communication` is set to true. - -##### tool_tx_idle_chars (default: "3.5") - -Number of idle chars in TX channel used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_voltage (default: "0") - -Tool voltage set at the beginning of the UR program. Only used, when `use_tool_communication` is set to true. - -##### urscript_file (default: "$(find ur_client_library)/resources/external_control.urscript") - -Path to URScript that will be sent to the robot and that forms the main control program. - -##### use_tool_communication (Required) - -On e-Series robots tool communication can be enabled with this argument - -### ur_common.launch - -Launchfile that starts a robot description with robot_state publisher and the driver for a given robot. It is recommended to use the individual launch files instead such as `ur10_bringup.launch`. Additionally, this launchfile can be used as a template to include this driver into a larger launch file structure. - -#### Arguments - -##### controller_config_file (Required) - -Config file used for defining the ROS-Control controllers. - -##### controllers (default: "joint_state_controller scaled_pos_joint_traj_controller speed_scaling_state_controller force_torque_sensor_controller") - -Controllers that are activated by default. - -##### debug (default: "false") - -Debug flag that will get passed on to ur_control.launch - -##### headless_mode (default: "false") - -Automatically send URScript to robot to execute. On e-Series this does require the robot to be in 'remote-control' mode. With this, the URCap is not needed on the robot. - -##### kinematics_config (Required) - -Kinematics config file used for calibration correction. This will be used to verify the robot's calibration is matching the robot_description. - -**Note:** The `default_kinematics.yaml` file will not reflect the kinematic parameters of your -robot. Make sure to [generate your own config file](https://github.com/UniversalRobots/Universal_Robots_ROS_Driver#extract-calibration-information). - -##### limited (default: "false") - -Use the description in limited mode (Every axis rotates from -PI to PI) - -##### reverse_port (default: "50001") - -Port that will be opened by the driver to allow direct communication between the driver and the robot controller. - -##### robot_description_file (Required) - -Robot description launch file. - -##### robot_ip (Required) - -IP address by which the robot can be reached. - -##### script_sender_port (default: "50002") - -The driver will offer an interface to receive the program's URScript on this port. If the robot cannot connect to this port, `External Control` will stop immediately. - -##### stopped_controllers (default: "pos_joint_traj_controller joint_group_vel_controller") - -Controllers that are initally loaded, but not started. - -##### tf_prefix (default: "") - -tf_prefix used for the robot. - -##### tool_baud_rate (default: "115200") - -Baud rate used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_device_name (default: "/tmp/ttyUR") - -Local device name used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_parity (default: "0") - -Parity configuration used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_rx_idle_chars (default: "1.5") - -Number of idle chars in RX channel used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_stop_bits (default: "1") - -Number of stop bits used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_tcp_port (default: "54321") - -Port on which the robot controller publishes the tool comm interface. Only used, when `use_tool_communication` is set to true. - -##### tool_tx_idle_chars (default: "3.5") - -Number of idle chars in TX channel used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_voltage (default: "0") - -Tool voltage set at the beginning of the UR program. Only used, when `use_tool_communication` is set to true. - -##### use_tool_communication (Required) - -On e-Series robots tool communication can be enabled with this argument - -### ur5_bringup.launch - -Standalone launchfile to startup a ur5 robot. This requires a robot reachable via a network connection. - -#### Arguments - -##### controller_config_file (default: "$(find ur_robot_driver)/config/ur5_controllers.yaml") - -Config file used for defining the ROS-Control controllers. - -##### controllers (default: "joint_state_controller scaled_pos_joint_traj_controller speed_scaling_state_controller force_torque_sensor_controller") - -Controllers that are activated by default. - -##### debug (default: "false") - -Debug flag that will get passed on to ur_common.launch - -##### headless_mode (default: "false") - -Automatically send URScript to robot to execute. On e-Series this does require the robot to be in 'remote-control' mode. With this, the URCap is not needed on the robot. - -##### kinematics_config (default: "$(find ur_description)/config/ur5/default_kinematics.yaml") - -Kinematics config file used for calibration correction. This will be used to verify the robot's calibration is matching the robot_description. - -**Note:** The `default_kinematics.yaml` file will not reflect the kinematic parameters of your -robot. Make sure to [generate your own config file](https://github.com/UniversalRobots/Universal_Robots_ROS_Driver#extract-calibration-information). - -##### limited (default: "false") - -Use the description in limited mode (Every axis rotates from -PI to PI) - -##### reverse_port (default: "50001") - -Port that will be opened by the driver to allow direct communication between the driver and the robot controller. - -##### robot_description_file (default: "$(find ur_description)/launch/load_ur5.launch") - -Robot description launch file. - -##### robot_ip (Required) - -IP address by which the robot can be reached. - -##### script_sender_port (default: "50002") - -The driver will offer an interface to receive the program's URScript on this port. If the robot cannot connect to this port, `External Control` will stop immediately. - -##### stopped_controllers (default: "pos_joint_traj_controller joint_group_vel_controller") - -Controllers that are initally loaded, but not started. - -##### tf_prefix (default: "") - -tf_prefix used for the robot. - -### ur5e_bringup.launch - -Standalone launchfile to startup a ur5e robot. This requires a robot reachable via a network connection. - -#### Arguments - -##### controller_config_file (default: "$(find ur_robot_driver)/config/ur5e_controllers.yaml") - -Config file used for defining the ROS-Control controllers. - -##### controllers (default: "joint_state_controller scaled_pos_joint_traj_controller speed_scaling_state_controller force_torque_sensor_controller") - -Controllers that are activated by default. - -##### debug (default: "false") - -Debug flag that will get passed on to ur_common.launch - -##### headless_mode (default: "false") - -Automatically send URScript to robot to execute. On e-Series this does require the robot to be in 'remote-control' mode. With this, the URCap is not needed on the robot. - -##### kinematics_config (default: "$(find ur_description)/config/ur5e/default_kinematics.yaml") - -Kinematics config file used for calibration correction. This will be used to verify the robot's calibration is matching the robot_description. - -**Note:** The `default_kinematics.yaml` file will not reflect the kinematic parameters of your -robot. Make sure to [generate your own config file](https://github.com/UniversalRobots/Universal_Robots_ROS_Driver#extract-calibration-information). - -##### limited (default: "false") - -Use the description in limited mode (Every axis rotates from -PI to PI) - -##### reverse_port (default: "50001") - -Port that will be opened by the driver to allow direct communication between the driver and the robot controller. - -##### robot_description_file (default: "$(find ur_description)/launch/load_ur5e.launch") - -Robot description launch file. - -##### robot_ip (Required) - -IP address by which the robot can be reached. - -##### script_sender_port (default: "50002") - -The driver will offer an interface to receive the program's URScript on this port. If the robot cannot connect to this port, `External Control` will stop immediately. - -##### stopped_controllers (default: "pos_joint_traj_controller joint_group_vel_controller") - -Controllers that are initally loaded, but not started. - -##### tf_prefix (default: "") - -tf_prefix used for the robot. - -##### tool_baud_rate (default: "115200") - -Baud rate used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_device_name (default: "/tmp/ttyUR") - -Local device name used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_parity (default: "0") - -Parity configuration used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_rx_idle_chars (default: "1.5") - -Number of idle chars in RX channel used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_stop_bits (default: "1") - -Number of stop bits used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_tcp_port (default: "54321") - -Port on which the robot controller publishes the tool comm interface. Only used, when `use_tool_communication` is set to true. - -##### tool_tx_idle_chars (default: "3.5") - -Number of idle chars in TX channel used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_voltage (default: "0") - -Tool voltage set at the beginning of the UR program. Only used, when `use_tool_communication` is set to true. - -##### use_tool_communication (default: "false") - -On e-Series robots tool communication can be enabled with this argument - -### ur3_bringup.launch - -Standalone launchfile to startup a ur3 robot. This requires a robot reachable via a network connection. - -#### Arguments - -##### controller_config_file (default: "$(find ur_robot_driver)/config/ur3_controllers.yaml") - -Config file used for defining the ROS-Control controllers. - -##### controllers (default: "joint_state_controller scaled_pos_joint_traj_controller speed_scaling_state_controller force_torque_sensor_controller") - -Controllers that are activated by default. - -##### debug (default: "false") - -Debug flag that will get passed on to ur_common.launch - -##### headless_mode (default: "false") - -Automatically send URScript to robot to execute. On e-Series this does require the robot to be in 'remote-control' mode. With this, the URCap is not needed on the robot. - -##### kinematics_config (default: "$(find ur_description)/config/ur3/default_kinematics.yaml") - -Kinematics config file used for calibration correction. This will be used to verify the robot's calibration is matching the robot_description. - -**Note:** The `default_kinematics.yaml` file will not reflect the kinematic parameters of your -robot. Make sure to [generate your own config file](https://github.com/UniversalRobots/Universal_Robots_ROS_Driver#extract-calibration-information). - -##### limited (default: "false") - -Use the description in limited mode (Every axis rotates from -PI to PI) - -##### reverse_port (default: "50001") - -Port that will be opened by the driver to allow direct communication between the driver and the robot controller. - -##### robot_description_file (default: "$(find ur_description)/launch/load_ur3.launch") - -Robot description launch file. - -##### robot_ip (Required) - -IP address by which the robot can be reached. - -##### script_sender_port (default: "50002") - -The driver will offer an interface to receive the program's URScript on this port. If the robot cannot connect to this port, `External Control` will stop immediately. - -##### stopped_controllers (default: "pos_joint_traj_controller joint_group_vel_controller") - -Controllers that are initally loaded, but not started. - -##### tf_prefix (default: "") - -tf_prefix used for the robot. - -### ur10e_bringup.launch - -Standalone launchfile to startup a ur10e robot. This requires a robot reachable via a network connection. - -#### Arguments - -##### controller_config_file (default: "$(find ur_robot_driver)/config/ur10e_controllers.yaml") - -Config file used for defining the ROS-Control controllers. - -##### controllers (default: "joint_state_controller scaled_pos_joint_traj_controller speed_scaling_state_controller force_torque_sensor_controller") - -Controllers that are activated by default. - -##### debug (default: "false") - -Debug flag that will get passed on to ur_common.launch - -##### headless_mode (default: "false") - -Automatically send URScript to robot to execute. On e-Series this does require the robot to be in 'remote-control' mode. With this, the URCap is not needed on the robot. - -##### kinematics_config (default: "$(find ur_description)/config/ur10e/default_kinematics.yaml") - -Kinematics config file used for calibration correction. This will be used to verify the robot's calibration is matching the robot_description. - -**Note:** The `default_kinematics.yaml` file will not reflect the kinematic parameters of your -robot. Make sure to [generate your own config file](https://github.com/UniversalRobots/Universal_Robots_ROS_Driver#extract-calibration-information). - -##### limited (default: "false") - -Use the description in limited mode (Every axis rotates from -PI to PI) - -##### reverse_port (default: "50001") - -Port that will be opened by the driver to allow direct communication between the driver and the robot controller. - -##### robot_description_file (default: "$(find ur_description)/launch/load_ur10e.launch") - -Robot description launch file. - -##### robot_ip (Required) - -IP address by which the robot can be reached. - -##### script_sender_port (default: "50002") - -The driver will offer an interface to receive the program's URScript on this port. If the robot cannot connect to this port, `External Control` will stop immediately. - -##### stopped_controllers (default: "pos_joint_traj_controller joint_group_vel_controller") - -Controllers that are initally loaded, but not started. - -##### tf_prefix (default: "") - -tf_prefix used for the robot. - -##### tool_baud_rate (default: "115200") - -Baud rate used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_device_name (default: "/tmp/ttyUR") - -Local device name used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_parity (default: "0") - -Parity configuration used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_rx_idle_chars (default: "1.5") - -Number of idle chars in RX channel used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_stop_bits (default: "1") - -Number of stop bits used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_tcp_port (default: "54321") - -Port on which the robot controller publishes the tool comm interface. Only used, when `use_tool_communication` is set to true. - -##### tool_tx_idle_chars (default: "3.5") - -Number of idle chars in TX channel used for tool communication. Only used, when `use_tool_communication` is set to true. - -##### tool_voltage (default: "0") - -Tool voltage set at the beginning of the UR program. Only used, when `use_tool_communication` is set to true. - -##### use_tool_communication (default: "false") - -On e-Series robots tool communication can be enabled with this argument - -## Nodes - -### ur_robot_driver_node - -This is the actual driver node containing the ROS-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. - -#### Advertised Services - -##### dashboard/add_to_log ([ur_dashboard_msgs/AddToLog](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/AddToLog.html)) - -Service to add a message to the robot's log - -##### dashboard/brake_release ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Service to release the brakes. If the robot is currently powered off, it will get powered on on the fly. - -##### dashboard/clear_operational_mode ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -If this service is called the operational mode can again be changed from PolyScope, and the user password is enabled. - -##### dashboard/close_popup ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Close a (non-safety) popup on the teach pendant. - -##### dashboard/close_safety_popup ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Close a safety popup on the teach pendant. - -##### dashboard/connect ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Service to reconnect to the dashboard server - -##### dashboard/get_loaded_program ([ur_dashboard_msgs/GetLoadedProgram](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/GetLoadedProgram.html)) - -Load a robot installation from a file - -##### dashboard/get_robot_mode ([ur_dashboard_msgs/GetRobotMode](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/GetRobotMode.html)) - -Service to query the current robot mode - -##### dashboard/get_safety_mode ([ur_dashboard_msgs/GetSafetyMode](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/GetSafetyMode.html)) - -Service to query the current safety mode - -##### dashboard/load_installation ([ur_dashboard_msgs/Load](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/Load.html)) - -Load a robot installation from a file - -##### dashboard/load_program ([ur_dashboard_msgs/Load](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/Load.html)) - -Load a robot program from a file - -##### dashboard/pause ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Pause a running program. - -##### dashboard/play ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Start execution of a previously loaded program - -##### dashboard/popup ([ur_dashboard_msgs/Popup](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/Popup.html)) - -Service to show a popup on the UR Teach pendant. - -##### dashboard/power_off ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Power off the robot motors - -##### dashboard/power_on ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Power on the robot motors. To fully start the robot, call 'brake_release' afterwards. - -##### dashboard/program_running ([ur_dashboard_msgs/IsProgramRunning](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/IsProgramRunning.html)) - -Query whether there is currently a program running - -##### dashboard/program_saved ([ur_dashboard_msgs/IsProgramSaved](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/IsProgramSaved.html)) - -Query whether the current program is saved - -##### dashboard/program_state ([ur_dashboard_msgs/GetProgramState](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/GetProgramState.html)) - -Service to query the current program state - -##### dashboard/quit ([ur_dashboard_msgs/GetLoadedProgram](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/GetLoadedProgram.html)) - -Disconnect from the dashboard service. - -##### dashboard/raw_request ([ur_dashboard_msgs/RawRequest](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/RawRequest.html)) - -General purpose service to send arbitrary messages to the dashboard server - -##### dashboard/restart_safety ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -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). - -##### dashboard/shutdown ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Shutdown the robot controller - -##### dashboard/stop ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Stop program execution on the robot - -##### dashboard/unlock_protective_stop ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -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. - -##### hand_back_control ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Calling this service will make the "External Control" program node on the UR-Program return. - -##### resend_robot_program ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -When in headless mode, this sends the URScript program to the robot for execution. Use this after the program has been interrupted, e.g. by a protective- or EM-stop. - -##### set_io (ur_msgs/SetIO) - -Service to set any of the robot's IOs - -##### set_speed_slider (ur_msgs/SetSpeedSliderFraction) - -Set the speed slider fraction used by the robot's execution. Values should be between 0 and 1. Only set this smaller than 1 if you are using the scaled controllers (as by default) or you know what you're doing. Using this with other controllers might lead to unexpected behaviors. - -##### set_payload (ur_msgs/SetPayload) - -Setup the mounted payload through a ROS service - -##### zero_ftsensor ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Calling this service will zero the robot's ftsensor. Note: On e-Series robots this will only work when the robot is in remote-control mode. - -#### Parameters - -##### dashboard/receive_timeout (Required) - -Timeout after which a call to the dashboard server will be considered failure if no answer has been received. - -##### hardware_interface/joints (Required) - -Names of the joints. Usually, this is given in the controller config file. - -##### headless_mode (Required) - -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_file (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. Should only be used with combined_robot_hw. Disables error generated when read returns without any data, sets the read timeout to zero, and synchronises read/write operations. Enabling this when not used with combined_robot_hw can suppress important errors and affect real-time performance. - -##### output_recipe_file (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_file (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 gain for servoing to position in joint space. A higher gain can sharpen the trajectory. - -##### servoj_lookahead_time (Required) - -Specify lookahead time for servoing to position in joint space. A longer lookahead time can smooth the trajectory. - -##### tf_prefix (default: "") - -When the robot's URDF is being loaded with a prefix, we need to know it here, as well, in order to publish correct frame names for frames reported by the robot directly. - - -##### 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. - -#### Published topics - -##### robot_program_running ([std_msgs/Bool](http://docs.ros.org/api/std_msgs/html/msg/Bool.html)) - -Whenever the runtime state of the "External Control" program node in the UR-program changes, a message gets published here. So this is equivalent to the information whether the robot accepts commands from ROS side. - -#### Subscribed topics - -##### script_command ([std_msgs/String](http://docs.ros.org/api/std_msgs/html/msg/String.html)) - -Send arbitrary script commands to this topic. Note: On e-Series the robot has to be in remote-control mode. Sending scripts to this will stop program execution unless wrapped in a secondary program: sec myProgram(): set_digital_out(0, True) end - -### dashboard_client - - - -#### Advertised Services - -##### add_to_log ([ur_dashboard_msgs/AddToLog](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/AddToLog.html)) - -Service to add a message to the robot's log - -##### brake_release ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -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](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -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](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Close a (non-safety) popup on the teach pendant. - -##### close_safety_popup ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Close a safety popup on the teach pendant. - -##### connect ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Service to reconnect to the dashboard server - -##### get_loaded_program ([ur_dashboard_msgs/GetLoadedProgram](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/GetLoadedProgram.html)) - -Load a robot installation from a file - -##### get_robot_mode ([ur_dashboard_msgs/GetRobotMode](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/GetRobotMode.html)) - -Service to query the current robot mode - -##### get_safety_mode ([ur_dashboard_msgs/GetSafetyMode](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/GetSafetyMode.html)) - -Service to query the current safety mode - -##### load_installation ([ur_dashboard_msgs/Load](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/Load.html)) - -Load a robot installation from a file - -##### load_program ([ur_dashboard_msgs/Load](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/Load.html)) - -Load a robot program from a file - -##### pause ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Pause a running program. - -##### play ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Start execution of a previously loaded program - -##### popup ([ur_dashboard_msgs/Popup](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/Popup.html)) - -Service to show a popup on the UR Teach pendant. - -##### power_off ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Power off the robot motors - -##### power_on ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Power on the robot motors. To fully start the robot, call 'brake_release' afterwards. - -##### program_running ([ur_dashboard_msgs/IsProgramRunning](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/IsProgramRunning.html)) - -Query whether there is currently a program running - -##### program_saved ([ur_dashboard_msgs/IsProgramSaved](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/IsProgramSaved.html)) - -Query whether the current program is saved - -##### program_state ([ur_dashboard_msgs/GetProgramState](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/GetProgramState.html)) - -Service to query the current program state - -##### quit ([ur_dashboard_msgs/GetLoadedProgram](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/GetLoadedProgram.html)) - -Disconnect from the dashboard service. - -##### raw_request ([ur_dashboard_msgs/RawRequest](http://docs.ros.org/api/ur_dashboard_msgs/html/srv/RawRequest.html)) - -General purpose service to send arbitrary messages to the dashboard server - -##### restart_safety ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -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](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Shutdown the robot controller - -##### stop ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Stop program execution on the robot - -##### unlock_protective_stop ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -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. - -### robot_state_helper - -This node prints the robot- and safety mode to ROS logging and offers an action to set the robot to a specific mode (e.g. for initial startup or recovery after a protective stop or EM-Stop). It should best be started inside the hardware interface's namespace - -#### Service Clients - -##### dashboard/brake_release ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Service to release the robot's brakes - -##### dashboard/play ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Service to start UR program execution on the robot - -##### dashboard/power_off ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Service to power off the robot - -##### dashboard/power_on ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Service to power on the robot - -##### dashboard/restart_safety ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Service to restart safety - -##### dashboard/stop ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Service to stop UR program execution on the robot - -##### dashboard/unlock_protective_stop ([std_srvs/Trigger](http://docs.ros.org/api/std_srvs/html/srv/Trigger.html)) - -Service to unlock protective stop - -#### Subscribed topics - -##### robot_mode ([ur_dashboard_msgs/RobotMode](http://docs.ros.org/api/ur_dashboard_msgs/html/msg/RobotMode.html)) - -Topic on which the robot_mode is published by the driver - -##### safety_mode ([ur_dashboard_msgs/SafetyMode](http://docs.ros.org/api/ur_dashboard_msgs/html/msg/SafetyMode.html)) - -Topic on which the safety is published by the driver - -### tool_communication - -This node is used to start the RS485 tunneling interface on the ROS machine. This requires that the RS485 daemon is running on the robot controller and tool communication is enabled on the robot. - -#### Parameters - -##### ~device_name (Required) - -By default, socat will create a pty in /dev/pts/N with n being an increasing number. Additionally, a symlink at the given location will be created. Use an absolute path here. - -##### ~robot_ip (Required) - -IP address of the robot - diff --git a/ur_robot_driver/doc/ROS_INTERFACE.rst b/ur_robot_driver/doc/ROS_INTERFACE.rst new file mode 100644 index 000000000..95cbb76aa --- /dev/null +++ b/ur_robot_driver/doc/ROS_INTERFACE.rst @@ -0,0 +1,1324 @@ + +ROS interface for the ur_robot_driver +===================================== + +The new driver for Universal Robots UR3, UR5 and UR10 robots with CB3 controllers and the e-series. + +Launchfiles +----------- + +ur3e_bringup.launch +^^^^^^^^^^^^^^^^^^^ + +Standalone launchfile to startup a ur3e. This requires a robot reachable via a network connection. + +Arguments +~~~~~~~~~ + +controller_config_file (default: "$(find ur_robot_driver)/config/ur3e_controllers.yaml") +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Config file used for defining the ROS-Control controllers. + +controllers (default: "joint_state_controller scaled_pos_joint_traj_controller speed_scaling_state_controller force_torque_sensor_controller") +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Controllers that are activated by default. + +debug (default: "false") +"""""""""""""""""""""""" + +Debug flag that will get passed on to ur_common.launch + +headless_mode (default: "false") +"""""""""""""""""""""""""""""""" + +Automatically send URScript to robot to execute. On e-Series this does require the robot to be in 'remote-control' mode. With this, the URCap is not needed on the robot. + +kinematics_config (default: "$(find ur_description)/config/ur3e/default_kinematics.yaml") +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Kinematics config file used for calibration correction. This will be used to verify the robot's calibration is matching the robot_description. + +**Note:** The ``default_kinematics.yaml`` file will not reflect the kinematic parameters of your +robot. Make sure to `generate your own config file `_. + +limited (default: "false") +"""""""""""""""""""""""""" + +Use the description in limited mode (Every axis rotates from -PI to PI) + +reverse_port (default: "50001") +""""""""""""""""""""""""""""""" + +Port that will be opened by the driver to allow direct communication between the driver and the robot controller. + +robot_description_file (default: "$(find ur_description)/launch/load_ur3e.launch") +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Robot description launch file. + +robot_ip (Required) +""""""""""""""""""" + +IP address by which the robot can be reached. + +script_sender_port (default: "50002") +""""""""""""""""""""""""""""""""""""" + +The driver will offer an interface to receive the program's URScript on this port. If the robot cannot connect to this port, ``External Control`` will stop immediately. + +stopped_controllers (default: "pos_joint_traj_controller joint_group_vel_controller") +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Controllers that are initally loaded, but not started. + +tf_prefix (default: "") +""""""""""""""""""""""" + +tf_prefix used for the robot. + +wrench_frame_id (default: "wrench") +""""""""""""""""""""""""""""""""""" + +Parameter to set the id of the wrench frame, required if using multiple robots + +tool_baud_rate (default: "115200") +"""""""""""""""""""""""""""""""""" + +Baud rate used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_device_name (default: "/tmp/ttyUR") +"""""""""""""""""""""""""""""""""""""""" + +Local device name used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_parity (default: "0") +"""""""""""""""""""""""""" + +Parity configuration used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_rx_idle_chars (default: "1.5") +""""""""""""""""""""""""""""""""""" + +Number of idle chars in RX channel used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_stop_bits (default: "1") +""""""""""""""""""""""""""""" + +Number of stop bits used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_tcp_port (default: "54321") +"""""""""""""""""""""""""""""""" + +Port on which the robot controller publishes the tool comm interface. Only used, when ``use_tool_communication`` is set to true. + +tool_tx_idle_chars (default: "3.5") +""""""""""""""""""""""""""""""""""" + +Number of idle chars in TX channel used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_voltage (default: "0") +""""""""""""""""""""""""""" + +Tool voltage set at the beginning of the UR program. Only used, when ``use_tool_communication`` is set to true. + +use_tool_communication (default: "false") +""""""""""""""""""""""""""""""""""""""""" + +On e-Series robots tool communication can be enabled with this argument + +ur10_bringup.launch +^^^^^^^^^^^^^^^^^^^ + +Standalone launchfile to startup a ur10 robot. This requires a robot reachable via a network connection. + +Arguments +~~~~~~~~~ + +controller_config_file (default: "$(find ur_robot_driver)/config/ur10_controllers.yaml") +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Config file used for defining the ROS-Control controllers. + +controllers (default: "joint_state_controller scaled_pos_joint_traj_controller speed_scaling_state_controller force_torque_sensor_controller") +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Controllers that are activated by default. + +debug (default: "false") +"""""""""""""""""""""""" + +Debug flag that will get passed on to ur_common.launch + +headless_mode (default: "false") +"""""""""""""""""""""""""""""""" + +Automatically send URScript to robot to execute. On e-Series this does require the robot to be in 'remote-control' mode. With this, the URCap is not needed on the robot. + +kinematics_config (default: "$(find ur_description)/config/ur10/default_kinematics.yaml") +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Kinematics config file used for calibration correction. This will be used to verify the robot's calibration is matching the robot_description. + +**Note:** The ``default_kinematics.yaml`` file will not reflect the kinematic parameters of your +robot. Make sure to `generate your own config file `_. + +limited (default: "false") +"""""""""""""""""""""""""" + +Use the description in limited mode (Every axis rotates from -PI to PI) + +reverse_port (default: "50001") +""""""""""""""""""""""""""""""" + +Port that will be opened by the driver to allow direct communication between the driver and the robot controller. + +robot_description_file (default: "$(find ur_description)/launch/load_ur10.launch") +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Robot description launch file. + +robot_ip (Required) +""""""""""""""""""" + +IP address by which the robot can be reached. + +script_sender_port (default: "50002") +""""""""""""""""""""""""""""""""""""" + +The driver will offer an interface to receive the program's URScript on this port. If the robot cannot connect to this port, ``External Control`` will stop immediately. + +stopped_controllers (default: "pos_joint_traj_controller joint_group_vel_controller") +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Controllers that are initally loaded, but not started. + +tf_prefix (default: "") +""""""""""""""""""""""" + +tf_prefix used for the robot. + +ur_control.launch +^^^^^^^^^^^^^^^^^ + +Robot bringup launchfile without the robot description. Include this, if you want to include robot control into a larger launchfile structure. + +Arguments +~~~~~~~~~ + +controller_config_file (Required) +""""""""""""""""""""""""""""""""" + +Config file used for defining the ROS-Control controllers. + +controllers (default: "joint_state_controller vel_based_pos_joint_traj_controller force_torque_sensor_controller") +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Controllers that are activated by default. + +debug (default: "false") +"""""""""""""""""""""""" + +If set to true, will start the driver inside gdb + +headless_mode (default: "false") +"""""""""""""""""""""""""""""""" + +Automatically send URScript to robot to execute. On e-Series this does require the robot to be in 'remote-control' mode. With this, the URCap is not needed on the robot. + +kinematics_config (Required) +"""""""""""""""""""""""""""" + +Kinematics config file used for calibration correction. This will be used to verify the robot's calibration is matching the robot_description. Pass the same config file that is passed to the robot_description. + +**Note:** The ``default_kinematics.yaml`` file will not reflect the kinematic parameters of your +robot. Make sure to `generate your own config file `_. + +launch_prefix (Required) +"""""""""""""""""""""""" + +Please add description. See file "launch/ur_control.launch". + +reverse_port (default: "50001") +""""""""""""""""""""""""""""""" + +Port that will be opened by the driver to allow direct communication between the driver and the robot controller. + +robot_ip (Required) +""""""""""""""""""" + +IP address by which the robot can be reached. + +rtde_input_recipe_file (default: "$(find ur_robot_driver)/resources/rtde_input_recipe.txt") +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Recipe file used for the RTDE-inputs. Only change this if you know what you're doing. + +rtde_output_recipe_file (default: "$(find ur_robot_driver)/resources/rtde_output_recipe.txt") +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Recipe file used for the RTDE-outputs. Only change this if you know what you're doing. + +script_sender_port (default: "50002") +""""""""""""""""""""""""""""""""""""" + +The driver will offer an interface to receive the program's URScript on this port. If the robot cannot connect to this port, ``External Control`` will stop immediately. + +stopped_controllers (default: "joint_group_vel_controller") +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Controllers that are initally loaded, but not started. + +tf_prefix (default: "") +""""""""""""""""""""""" + +tf_prefix used for the robot. + +tool_baud_rate (default: "115200") +"""""""""""""""""""""""""""""""""" + +Baud rate used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_device_name (default: "/tmp/ttyUR") +"""""""""""""""""""""""""""""""""""""""" + +Local device name used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_parity (default: "0") +"""""""""""""""""""""""""" + +Parity configuration used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_rx_idle_chars (default: "1.5") +""""""""""""""""""""""""""""""""""" + +Number of idle chars in RX channel used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_stop_bits (default: "1") +""""""""""""""""""""""""""""" + +Number of stop bits used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_tcp_port (default: "54321") +"""""""""""""""""""""""""""""""" + +Port on which the robot controller publishes the tool comm interface. Only used, when ``use_tool_communication`` is set to true. + +tool_tx_idle_chars (default: "3.5") +""""""""""""""""""""""""""""""""""" + +Number of idle chars in TX channel used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_voltage (default: "0") +""""""""""""""""""""""""""" + +Tool voltage set at the beginning of the UR program. Only used, when ``use_tool_communication`` is set to true. + +urscript_file (default: "$(find ur_client_library)/resources/external_control.urscript") +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Path to URScript that will be sent to the robot and that forms the main control program. + +use_tool_communication (Required) +""""""""""""""""""""""""""""""""" + +On e-Series robots tool communication can be enabled with this argument + +ur_common.launch +^^^^^^^^^^^^^^^^ + +Launchfile that starts a robot description with robot_state publisher and the driver for a given robot. It is recommended to use the individual launch files instead such as ``ur10_bringup.launch``. Additionally, this launchfile can be used as a template to include this driver into a larger launch file structure. + +Arguments +~~~~~~~~~ + +controller_config_file (Required) +""""""""""""""""""""""""""""""""" + +Config file used for defining the ROS-Control controllers. + +controllers (default: "joint_state_controller scaled_pos_joint_traj_controller speed_scaling_state_controller force_torque_sensor_controller") +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Controllers that are activated by default. + +debug (default: "false") +"""""""""""""""""""""""" + +Debug flag that will get passed on to ur_control.launch + +headless_mode (default: "false") +"""""""""""""""""""""""""""""""" + +Automatically send URScript to robot to execute. On e-Series this does require the robot to be in 'remote-control' mode. With this, the URCap is not needed on the robot. + +kinematics_config (Required) +"""""""""""""""""""""""""""" + +Kinematics config file used for calibration correction. This will be used to verify the robot's calibration is matching the robot_description. + +**Note:** The ``default_kinematics.yaml`` file will not reflect the kinematic parameters of your +robot. Make sure to `generate your own config file `_. + +limited (default: "false") +"""""""""""""""""""""""""" + +Use the description in limited mode (Every axis rotates from -PI to PI) + +reverse_port (default: "50001") +""""""""""""""""""""""""""""""" + +Port that will be opened by the driver to allow direct communication between the driver and the robot controller. + +robot_description_file (Required) +""""""""""""""""""""""""""""""""" + +Robot description launch file. + +robot_ip (Required) +""""""""""""""""""" + +IP address by which the robot can be reached. + +script_sender_port (default: "50002") +""""""""""""""""""""""""""""""""""""" + +The driver will offer an interface to receive the program's URScript on this port. If the robot cannot connect to this port, ``External Control`` will stop immediately. + +stopped_controllers (default: "pos_joint_traj_controller joint_group_vel_controller") +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Controllers that are initally loaded, but not started. + +tf_prefix (default: "") +""""""""""""""""""""""" + +tf_prefix used for the robot. + +tool_baud_rate (default: "115200") +"""""""""""""""""""""""""""""""""" + +Baud rate used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_device_name (default: "/tmp/ttyUR") +"""""""""""""""""""""""""""""""""""""""" + +Local device name used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_parity (default: "0") +"""""""""""""""""""""""""" + +Parity configuration used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_rx_idle_chars (default: "1.5") +""""""""""""""""""""""""""""""""""" + +Number of idle chars in RX channel used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_stop_bits (default: "1") +""""""""""""""""""""""""""""" + +Number of stop bits used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_tcp_port (default: "54321") +"""""""""""""""""""""""""""""""" + +Port on which the robot controller publishes the tool comm interface. Only used, when ``use_tool_communication`` is set to true. + +tool_tx_idle_chars (default: "3.5") +""""""""""""""""""""""""""""""""""" + +Number of idle chars in TX channel used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_voltage (default: "0") +""""""""""""""""""""""""""" + +Tool voltage set at the beginning of the UR program. Only used, when ``use_tool_communication`` is set to true. + +use_tool_communication (Required) +""""""""""""""""""""""""""""""""" + +On e-Series robots tool communication can be enabled with this argument + +ur5_bringup.launch +^^^^^^^^^^^^^^^^^^ + +Standalone launchfile to startup a ur5 robot. This requires a robot reachable via a network connection. + +Arguments +~~~~~~~~~ + +controller_config_file (default: "$(find ur_robot_driver)/config/ur5_controllers.yaml") +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Config file used for defining the ROS-Control controllers. + +controllers (default: "joint_state_controller scaled_pos_joint_traj_controller speed_scaling_state_controller force_torque_sensor_controller") +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Controllers that are activated by default. + +debug (default: "false") +"""""""""""""""""""""""" + +Debug flag that will get passed on to ur_common.launch + +headless_mode (default: "false") +"""""""""""""""""""""""""""""""" + +Automatically send URScript to robot to execute. On e-Series this does require the robot to be in 'remote-control' mode. With this, the URCap is not needed on the robot. + +kinematics_config (default: "$(find ur_description)/config/ur5/default_kinematics.yaml") +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Kinematics config file used for calibration correction. This will be used to verify the robot's calibration is matching the robot_description. + +**Note:** The ``default_kinematics.yaml`` file will not reflect the kinematic parameters of your +robot. Make sure to `generate your own config file `_. + +limited (default: "false") +"""""""""""""""""""""""""" + +Use the description in limited mode (Every axis rotates from -PI to PI) + +reverse_port (default: "50001") +""""""""""""""""""""""""""""""" + +Port that will be opened by the driver to allow direct communication between the driver and the robot controller. + +robot_description_file (default: "$(find ur_description)/launch/load_ur5.launch") +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Robot description launch file. + +robot_ip (Required) +""""""""""""""""""" + +IP address by which the robot can be reached. + +script_sender_port (default: "50002") +""""""""""""""""""""""""""""""""""""" + +The driver will offer an interface to receive the program's URScript on this port. If the robot cannot connect to this port, ``External Control`` will stop immediately. + +stopped_controllers (default: "pos_joint_traj_controller joint_group_vel_controller") +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Controllers that are initally loaded, but not started. + +tf_prefix (default: "") +""""""""""""""""""""""" + +tf_prefix used for the robot. + +ur5e_bringup.launch +^^^^^^^^^^^^^^^^^^^ + +Standalone launchfile to startup a ur5e robot. This requires a robot reachable via a network connection. + +Arguments +~~~~~~~~~ + +controller_config_file (default: "$(find ur_robot_driver)/config/ur5e_controllers.yaml") +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Config file used for defining the ROS-Control controllers. + +controllers (default: "joint_state_controller scaled_pos_joint_traj_controller speed_scaling_state_controller force_torque_sensor_controller") +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Controllers that are activated by default. + +debug (default: "false") +"""""""""""""""""""""""" + +Debug flag that will get passed on to ur_common.launch + +headless_mode (default: "false") +"""""""""""""""""""""""""""""""" + +Automatically send URScript to robot to execute. On e-Series this does require the robot to be in 'remote-control' mode. With this, the URCap is not needed on the robot. + +kinematics_config (default: "$(find ur_description)/config/ur5e/default_kinematics.yaml") +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Kinematics config file used for calibration correction. This will be used to verify the robot's calibration is matching the robot_description. + +**Note:** The ``default_kinematics.yaml`` file will not reflect the kinematic parameters of your +robot. Make sure to `generate your own config file `_. + +limited (default: "false") +"""""""""""""""""""""""""" + +Use the description in limited mode (Every axis rotates from -PI to PI) + +reverse_port (default: "50001") +""""""""""""""""""""""""""""""" + +Port that will be opened by the driver to allow direct communication between the driver and the robot controller. + +robot_description_file (default: "$(find ur_description)/launch/load_ur5e.launch") +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Robot description launch file. + +robot_ip (Required) +""""""""""""""""""" + +IP address by which the robot can be reached. + +script_sender_port (default: "50002") +""""""""""""""""""""""""""""""""""""" + +The driver will offer an interface to receive the program's URScript on this port. If the robot cannot connect to this port, ``External Control`` will stop immediately. + +stopped_controllers (default: "pos_joint_traj_controller joint_group_vel_controller") +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Controllers that are initally loaded, but not started. + +tf_prefix (default: "") +""""""""""""""""""""""" + +tf_prefix used for the robot. + +tool_baud_rate (default: "115200") +"""""""""""""""""""""""""""""""""" + +Baud rate used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_device_name (default: "/tmp/ttyUR") +"""""""""""""""""""""""""""""""""""""""" + +Local device name used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_parity (default: "0") +"""""""""""""""""""""""""" + +Parity configuration used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_rx_idle_chars (default: "1.5") +""""""""""""""""""""""""""""""""""" + +Number of idle chars in RX channel used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_stop_bits (default: "1") +""""""""""""""""""""""""""""" + +Number of stop bits used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_tcp_port (default: "54321") +"""""""""""""""""""""""""""""""" + +Port on which the robot controller publishes the tool comm interface. Only used, when ``use_tool_communication`` is set to true. + +tool_tx_idle_chars (default: "3.5") +""""""""""""""""""""""""""""""""""" + +Number of idle chars in TX channel used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_voltage (default: "0") +""""""""""""""""""""""""""" + +Tool voltage set at the beginning of the UR program. Only used, when ``use_tool_communication`` is set to true. + +use_tool_communication (default: "false") +""""""""""""""""""""""""""""""""""""""""" + +On e-Series robots tool communication can be enabled with this argument + +ur3_bringup.launch +^^^^^^^^^^^^^^^^^^ + +Standalone launchfile to startup a ur3 robot. This requires a robot reachable via a network connection. + +Arguments +~~~~~~~~~ + +controller_config_file (default: "$(find ur_robot_driver)/config/ur3_controllers.yaml") +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Config file used for defining the ROS-Control controllers. + +controllers (default: "joint_state_controller scaled_pos_joint_traj_controller speed_scaling_state_controller force_torque_sensor_controller") +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Controllers that are activated by default. + +debug (default: "false") +"""""""""""""""""""""""" + +Debug flag that will get passed on to ur_common.launch + +headless_mode (default: "false") +"""""""""""""""""""""""""""""""" + +Automatically send URScript to robot to execute. On e-Series this does require the robot to be in 'remote-control' mode. With this, the URCap is not needed on the robot. + +kinematics_config (default: "$(find ur_description)/config/ur3/default_kinematics.yaml") +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Kinematics config file used for calibration correction. This will be used to verify the robot's calibration is matching the robot_description. + +**Note:** The ``default_kinematics.yaml`` file will not reflect the kinematic parameters of your +robot. Make sure to `generate your own config file `_. + +limited (default: "false") +"""""""""""""""""""""""""" + +Use the description in limited mode (Every axis rotates from -PI to PI) + +reverse_port (default: "50001") +""""""""""""""""""""""""""""""" + +Port that will be opened by the driver to allow direct communication between the driver and the robot controller. + +robot_description_file (default: "$(find ur_description)/launch/load_ur3.launch") +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Robot description launch file. + +robot_ip (Required) +""""""""""""""""""" + +IP address by which the robot can be reached. + +script_sender_port (default: "50002") +""""""""""""""""""""""""""""""""""""" + +The driver will offer an interface to receive the program's URScript on this port. If the robot cannot connect to this port, ``External Control`` will stop immediately. + +stopped_controllers (default: "pos_joint_traj_controller joint_group_vel_controller") +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Controllers that are initally loaded, but not started. + +tf_prefix (default: "") +""""""""""""""""""""""" + +tf_prefix used for the robot. + +ur10e_bringup.launch +^^^^^^^^^^^^^^^^^^^^ + +Standalone launchfile to startup a ur10e robot. This requires a robot reachable via a network connection. + +Arguments +~~~~~~~~~ + +controller_config_file (default: "$(find ur_robot_driver)/config/ur10e_controllers.yaml") +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Config file used for defining the ROS-Control controllers. + +controllers (default: "joint_state_controller scaled_pos_joint_traj_controller speed_scaling_state_controller force_torque_sensor_controller") +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Controllers that are activated by default. + +debug (default: "false") +"""""""""""""""""""""""" + +Debug flag that will get passed on to ur_common.launch + +headless_mode (default: "false") +"""""""""""""""""""""""""""""""" + +Automatically send URScript to robot to execute. On e-Series this does require the robot to be in 'remote-control' mode. With this, the URCap is not needed on the robot. + +kinematics_config (default: "$(find ur_description)/config/ur10e/default_kinematics.yaml") +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Kinematics config file used for calibration correction. This will be used to verify the robot's calibration is matching the robot_description. + +**Note:** The ``default_kinematics.yaml`` file will not reflect the kinematic parameters of your +robot. Make sure to `generate your own config file `_. + +limited (default: "false") +"""""""""""""""""""""""""" + +Use the description in limited mode (Every axis rotates from -PI to PI) + +reverse_port (default: "50001") +""""""""""""""""""""""""""""""" + +Port that will be opened by the driver to allow direct communication between the driver and the robot controller. + +robot_description_file (default: "$(find ur_description)/launch/load_ur10e.launch") +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Robot description launch file. + +robot_ip (Required) +""""""""""""""""""" + +IP address by which the robot can be reached. + +script_sender_port (default: "50002") +""""""""""""""""""""""""""""""""""""" + +The driver will offer an interface to receive the program's URScript on this port. If the robot cannot connect to this port, ``External Control`` will stop immediately. + +stopped_controllers (default: "pos_joint_traj_controller joint_group_vel_controller") +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Controllers that are initally loaded, but not started. + +tf_prefix (default: "") +""""""""""""""""""""""" + +tf_prefix used for the robot. + +tool_baud_rate (default: "115200") +"""""""""""""""""""""""""""""""""" + +Baud rate used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_device_name (default: "/tmp/ttyUR") +"""""""""""""""""""""""""""""""""""""""" + +Local device name used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_parity (default: "0") +"""""""""""""""""""""""""" + +Parity configuration used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_rx_idle_chars (default: "1.5") +""""""""""""""""""""""""""""""""""" + +Number of idle chars in RX channel used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_stop_bits (default: "1") +""""""""""""""""""""""""""""" + +Number of stop bits used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_tcp_port (default: "54321") +"""""""""""""""""""""""""""""""" + +Port on which the robot controller publishes the tool comm interface. Only used, when ``use_tool_communication`` is set to true. + +tool_tx_idle_chars (default: "3.5") +""""""""""""""""""""""""""""""""""" + +Number of idle chars in TX channel used for tool communication. Only used, when ``use_tool_communication`` is set to true. + +tool_voltage (default: "0") +""""""""""""""""""""""""""" + +Tool voltage set at the beginning of the UR program. Only used, when ``use_tool_communication`` is set to true. + +use_tool_communication (default: "false") +""""""""""""""""""""""""""""""""""""""""" + +On e-Series robots tool communication can be enabled with this argument + +Nodes +----- + +ur_robot_driver_node +^^^^^^^^^^^^^^^^^^^^ + +This is the actual driver node containing the ROS-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. + +Advertised Services +~~~~~~~~~~~~~~~~~~~ + +dashboard/add_to_log (\ `ur_dashboard_msgs/AddToLog `_\ ) +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Service to add a message to the robot's log + +dashboard/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. + +dashboard/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. + +dashboard/close_popup (\ `std_srvs/Trigger `_\ ) +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Close a (non-safety) popup on the teach pendant. + +dashboard/close_safety_popup (\ `std_srvs/Trigger `_\ ) +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Close a safety popup on the teach pendant. + +dashboard/connect (\ `std_srvs/Trigger `_\ ) +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Service to reconnect to the dashboard server + +dashboard/get_loaded_program (\ `ur_dashboard_msgs/GetLoadedProgram `_\ ) +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Load a robot installation from a file + +dashboard/get_robot_mode (\ `ur_dashboard_msgs/GetRobotMode `_\ ) +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Service to query the current robot mode + +dashboard/get_safety_mode (\ `ur_dashboard_msgs/GetSafetyMode `_\ ) +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Service to query the current safety mode + +dashboard/load_installation (\ `ur_dashboard_msgs/Load `_\ ) +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Load a robot installation from a file + +dashboard/load_program (\ `ur_dashboard_msgs/Load `_\ ) +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Load a robot program from a file + +dashboard/pause (\ `std_srvs/Trigger `_\ ) +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Pause a running program. + +dashboard/play (\ `std_srvs/Trigger `_\ ) +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Start execution of a previously loaded program + +dashboard/popup (\ `ur_dashboard_msgs/Popup `_\ ) +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Service to show a popup on the UR Teach pendant. + +dashboard/power_off (\ `std_srvs/Trigger `_\ ) +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Power off the robot motors + +dashboard/power_on (\ `std_srvs/Trigger `_\ ) +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Power on the robot motors. To fully start the robot, call 'brake_release' afterwards. + +dashboard/program_running (\ `ur_dashboard_msgs/IsProgramRunning `_\ ) +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Query whether there is currently a program running + +dashboard/program_saved (\ `ur_dashboard_msgs/IsProgramSaved `_\ ) +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Query whether the current program is saved + +dashboard/program_state (\ `ur_dashboard_msgs/GetProgramState `_\ ) +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Service to query the current program state + +dashboard/quit (\ `ur_dashboard_msgs/GetLoadedProgram `_\ ) +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Disconnect from the dashboard service. + +dashboard/raw_request (\ `ur_dashboard_msgs/RawRequest `_\ ) +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +General purpose service to send arbitrary messages to the dashboard server + +dashboard/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). + +dashboard/shutdown (\ `std_srvs/Trigger `_\ ) +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Shutdown the robot controller + +dashboard/stop (\ `std_srvs/Trigger `_\ ) +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Stop program execution on the robot + +dashboard/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. + +hand_back_control (\ `std_srvs/Trigger `_\ ) +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Calling this service will make the "External Control" program node on the UR-Program return. + +resend_robot_program (\ `std_srvs/Trigger `_\ ) +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +When in headless mode, this sends the URScript program to the robot for execution. Use this after the program has been interrupted, e.g. by a protective- or EM-stop. + +set_io (ur_msgs/SetIO) +"""""""""""""""""""""" + +Service to set any of the robot's IOs + +set_speed_slider (ur_msgs/SetSpeedSliderFraction) +""""""""""""""""""""""""""""""""""""""""""""""""" + +Set the speed slider fraction used by the robot's execution. Values should be between 0 and 1. Only set this smaller than 1 if you are using the scaled controllers (as by default) or you know what you're doing. Using this with other controllers might lead to unexpected behaviors. + +set_payload (ur_msgs/SetPayload) +"""""""""""""""""""""""""""""""" + +Setup the mounted payload through a ROS service + +zero_ftsensor (\ `std_srvs/Trigger `_\ ) +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Calling this service will zero the robot's ftsensor. Note: On e-Series robots this will only work when the robot is in remote-control mode. + +Parameters +~~~~~~~~~~ + +dashboard/receive_timeout (Required) +"""""""""""""""""""""""""""""""""""" + +Timeout after which a call to the dashboard server will be considered failure if no answer has been received. + +hardware_interface/joints (Required) +"""""""""""""""""""""""""""""""""""" + +Names of the joints. Usually, this is given in the controller config file. + +headless_mode (Required) +"""""""""""""""""""""""" + +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_file (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. Should only be used with combined_robot_hw. Disables error generated when read returns without any data, sets the read timeout to zero, and synchronises read/write operations. Enabling this when not used with combined_robot_hw can suppress important errors and affect real-time performance. + +output_recipe_file (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_file (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 gain for servoing to position in joint space. A higher gain can sharpen the trajectory. + +servoj_lookahead_time (Required) +"""""""""""""""""""""""""""""""" + +Specify lookahead time for servoing to position in joint space. A longer lookahead time can smooth the trajectory. + +tf_prefix (default: "") +""""""""""""""""""""""" + +When the robot's URDF is being loaded with a prefix, we need to know it here, as well, in order to publish correct frame names for frames reported by the robot directly. + +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. + +Published topics +~~~~~~~~~~~~~~~~ + +robot_program_running (\ `std_msgs/Bool `_\ ) +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Whenever the runtime state of the "External Control" program node in the UR-program changes, a message gets published here. So this is equivalent to the information whether the robot accepts commands from ROS side. + +Subscribed topics +~~~~~~~~~~~~~~~~~ + +script_command (\ `std_msgs/String `_\ ) +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Send arbitrary script commands to this topic. Note: On e-Series the robot has to be in remote-control mode. Sending scripts to this will stop program execution unless wrapped in a secondary program: sec myProgram(): set_digital_out(0, True) end + +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. + +robot_state_helper +^^^^^^^^^^^^^^^^^^ + +This node prints the robot- and safety mode to ROS logging and offers an action to set the robot to a specific mode (e.g. for initial startup or recovery after a protective stop or EM-Stop). It should best be started inside the hardware interface's namespace + +Service Clients +~~~~~~~~~~~~~~~ + +dashboard/brake_release (\ `std_srvs/Trigger `_\ ) +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Service to release the robot's brakes + +dashboard/play (\ `std_srvs/Trigger `_\ ) +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Service to start UR program execution on the robot + +dashboard/power_off (\ `std_srvs/Trigger `_\ ) +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Service to power off the robot + +dashboard/power_on (\ `std_srvs/Trigger `_\ ) +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Service to power on the robot + +dashboard/restart_safety (\ `std_srvs/Trigger `_\ ) +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Service to restart safety + +dashboard/stop (\ `std_srvs/Trigger `_\ ) +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Service to stop UR program execution on the robot + +dashboard/unlock_protective_stop (\ `std_srvs/Trigger `_\ ) +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Service to unlock protective stop + +Subscribed topics +~~~~~~~~~~~~~~~~~ + +robot_mode (\ `ur_dashboard_msgs/RobotMode `_\ ) +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Topic on which the robot_mode is published by the driver + +safety_mode (\ `ur_dashboard_msgs/SafetyMode `_\ ) +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Topic on which the safety is published by the driver + +tool_communication +^^^^^^^^^^^^^^^^^^ + +This node is used to start the RS485 tunneling interface on the ROS machine. This requires that the RS485 daemon is running on the robot controller and tool communication is enabled on the robot. + +Parameters +~~~~~~~~~~ + +~device_name (Required) +""""""""""""""""""""""" + +By default, socat will create a pty in /dev/pts/N with n being an increasing number. Additionally, a symlink at the given location will be created. Use an absolute path here. + +~robot_ip (Required) +"""""""""""""""""""" + +IP address of the robot diff --git a/ur_robot_driver/doc/conf.py b/ur_robot_driver/doc/conf.py new file mode 100644 index 000000000..823b382a9 --- /dev/null +++ b/ur_robot_driver/doc/conf.py @@ -0,0 +1,185 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + +import os +import catkin_pkg.package + +catkin_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +catkin_package = catkin_pkg.package.parse_package( + os.path.join(catkin_dir, catkin_pkg.package.PACKAGE_MANIFEST_FILENAME) +) + +# -- Project information ----------------------------------------------------- + +project = "ur_robot_driver" +copyright = "2022, Universal Robots A/S" +author = "Felix Exner" + +# The short X.Y version +version = catkin_package.version +# The full version, including alpha/beta/rc tags +release = catkin_package.version + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = [".templates"] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = ".rst" + +# The master toctree document. +master_doc = "index" + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = [".static"] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = "ur_robot_driver_doc" + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ( + master_doc, + "ur_robot_driver.tex", + "ur\\_robot\\_driver Documentation", + "Felix Exner", + "manual", + ) +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [(master_doc, "ur_robot_driver", "ur_robot_driver Documentation", [author], 1)] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ( + master_doc, + "ur_robot_driver", + "ur_robot_driver Documentation", + author, + "ur_robot_driver", + "One line description of project.", + "Miscellaneous", + ) +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ["search.html"] + diff --git a/ur_robot_driver/doc/controllers.md b/ur_robot_driver/doc/controllers.md deleted file mode 100644 index 66437b55d..000000000 --- a/ur_robot_driver/doc/controllers.md +++ /dev/null @@ -1,190 +0,0 @@ -# ROS-Controllers available for the ur_robot_driver -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.yml` files, e.g. -[`ur10e_controllers.yml`](https://github.com/UniversalRobots/Universal_Robots_ROS_Driver/blob/master/ur_robot_driver/config/ur10e_controllers.yaml) -for the UR10e robot. - -## How do controllers get loaded and started? -As this driver uses ROS-control all controllers are managed by the -[`controller_manager`](http://wiki.ros.org/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 their ROS interfaces are still visible on the command line e.g. by -`rostopic list`. - -For switching controllers, use the methods offered by the -[`controller_manager`](http://wiki.ros.org/controller_manager) e.g. to switch from the default -`scaled_pos_joint_traj_controller` to the `joint_group_vel_controller` : - -```bash -rosservice call /controller_manager/switch_controller "start_controllers: ['joint_group_vel_controller'] -stop_controllers: ['scaled_pos_joint_traj_controller'] -strictness: 2 -start_asap: false -timeout: 0.0" -``` - -For more information on that topic, please refer to the -[`controller_manager`](http://wiki.ros.org/controller_manager)'s documentation. - -## Read-Only controllers -These "controllers" 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_controller` -**Type:** [`joint_state_controller/JointStateController`](http://wiki.ros.org/joint_state_controller) - -Publishes all joints' positions, velocities, and motor currents as -[`sensor_msgs/JointState`](http://docs.ros.org/en/api/sensor_msgs/html/msg/JointState.html) on the -`/joint_states` topic. Note that the `effort` field contains the currents reported by the joints and -not the actual *efforts* in a physical sense. - -### `robot_status_controller` -**Type:** [`industrial_robot_status_controller/IndustrialRobotStatusController`](http://wiki.ros.org/industrial_robot_status_controller) - -Controller that publishes robot/controller state (e-stopped, in motion, etc) as -[`industrial_msgs/RobotStatus`](http://docs.ros.org/en/melodic/api/industrial_msgs/html/msg/RobotStatus.html) -messages on the `/robot_status` topic. - -### `force_torque_sensor_controller` -**Type:** [`force_torque_sensor_controller/ForceTorqueSensorController`](http://wiki.ros.org/force_torque_sensor_controller) - -This controller publishes the wrench measured from the robot at its TCP as -[`geometry_msgs/WrenchStamped`](http://docs.ros.org/en/melodic/api/geometry_msgs/html/msg/WrenchStamped.html) -on the topic `/wrench`. Note that the wrench can be tared to 0 using the -`zero_ftsensor`(https://github.com/UniversalRobots/Universal_Robots_ROS_Driver/blob/master/ur_robot_driver/doc/ROS_INTERFACE.md#zero_ftsensor-std_srvstrigger) -service. - -### `speed_scaling_state_controller` -**Type:** [`scaled_controllers/SpeedScalingStateController`](http://wiki.ros.org/speed_scaling_state_controller) - -Reports the current value of the speed multiplier used from the robot. This is the product of the -speed slider value as it is on the teach pendant and any active speed scaling mechanism. In other -words, this represents the factor of the real slowdown relative to the commanded motion. - -## Commanding controllers -The commanding controllers control the robot's motions. They all claim all joints and therefore only -one of the following can be active at one time. You can define your own controllers with only a -subset of all joints, but this won't be covered here. - -### `scaled_pos_joint_traj_controller` (Default motion controller) -**Type:** [`position_controllers/ScaledJointTrajectoryController`](http://wiki.ros.org/scaled_joint_trajectory_controller) - -Similar to the non-scaled version it implements the -[`control_msgs/FollowJointTrajectory`](http://docs.ros.org/en/latest/api/control_msgs/html/action/FollowJointTrajectory.html) -interface. For controlling the robot it will send joint position commands. - -In contrast to the non-scaled version, the speed slider position or any other speed-modifying action -such as pausing, EM-Stop or speed scaling due to limits configured on the robot will be respected by -this controller. If a trajectory is given with time constraints and the trajectory is slowed down -during execution, the action fails. If no time constraints are set and the motion is slowed down -during execution, the actual action call will succeed. - -### `joint_group_vel_controller` -**Type:** [`velocity_controllers/JointGroupVelocityController`](http://wiki.ros.org/forward_command_controller) - -Directly command joint velocities though a topic interface. This controller is useful when doing -things like servoing in joint space. - -### `twist_controller` -**Type:** [`ros_controllers_cartesian/TwistController`](http://wiki.ros.org/twist_controller) - -Similar to the `joint_group_vel_controller` this controller allows directly sending speeds via a -topic interface to the robot. However, this controller expects a Cartesian TCP twist (linear and -angular velocity). This is useful in Cartesian servoing applications such as visual servoing or -teleoperation. - -Note that this controller does not check for configuration changes in the robot's kinematics, twist -commands are sent for execution to the robot. Therefore, commanded motions can result in protective -stops, e.g. when leaving the robot's operation space or forcing it to change its configuration. - ---- -Controllers below this line are probably less useful for the majority of applications, but can be -used nevertheless. - -### `pos_joint_traj_controller` -**Type:** [`position_controllers/JointTrajectoryController`](http://wiki.ros.org/joint_trajectory_controller) - -This is the most commonly used ROS controller implementing the -[`control_msgs/FollowJointTrajectory`](http://docs.ros.org/en/latest/api/control_msgs/html/action/FollowJointTrajectory.html) -interface. For controlling the robot it will send joint position commands. - -**We do not recommend using this controller, as it does not respect the robot's speed scaling value. -Setting the speed slider at another position than 100% or pausing the robot will lead to unexpected -side-effects! Use the scaled version of this controller instead.** - -### `vel_joint_traj_controller` -**Type:** [`velocity_controllers/JointTrajectoryController`](http://wiki.ros.org/joint_trajectory_controller) - -Implements the -[`control_msgs/FollowJointTrajectory`](http://docs.ros.org/en/latest/api/control_msgs/html/action/FollowJointTrajectory.html) -interface. For controlling the robot it will send joint velocity commands. - -As this controller uses closed-loop velocity control, it requires tuned PID parameters. Currently, -they are not optimized, see -[#119](https://github.com/UniversalRobots/Universal_Robots_ROS_Driver/issues/119). - -### `scaled_vel_joint_traj_controller` -**Type:** [`velocity_controllers/ScaledJointTrajectoryController`](http://wiki.ros.org/scaled_joint_trajectory_controller) - -Similar to the non-scaled version it implements the -[`control_msgs/FollowJointTrajectory`](http://docs.ros.org/en/latest/api/control_msgs/html/action/FollowJointTrajectory.html) -interface. For controlling the robot it will send joint velocity commands. - -In contrast to the non-scaled version, the speed slider position or any other speed-modifying action -such as pausing, EM-Stop or speed scaling due to limits configured on the robot will be respected by -this controller. If a trajectory is given with time constraints and the trajectory is slowed down -during execution, the action fails. If no time constraints are set and the motion is slowed down -during execution, the actual action call will succeed. - -### `forward_joint_traj_controller` -**Type:** [`pass_through_controllers/JointTrajectoryController`](http://wiki.ros.org/pass_through_controllers) - -This controller implements the -[`control_msgs/FollowJointTrajectory`](http://docs.ros.org/en/latest/api/control_msgs/html/action/FollowJointTrajectory.html) -interface. Instead of interpolating the trajectory on ROS side, this forwards the complete -trajectory to the robot for execution leaving the robot in charge of calculating accelerations and -speeds. Therefore, this will lead to motions most similar to what you could configure on the teach -pendant. - -As this uses the robot controller's trajectory execution, trajectories will be slightly different to -the streaming controllers such as the `scaled_pos_joint_traj_controller`. Each setpoint will be -blended with a (currently [hard coded]()https://github.com/UniversalRobots/Universal_Robots_Client_Library/blob/125f4f7a48b299b07e298cf479e3ba6882c3af3a/include/ur_client_library/ur/ur_driver.h#L203) blend radius. - -### `forward_cartesian_traj_controller` -**Type:** [`pass_through_controllers/JointTrajectoryController`](http://wiki.ros.org/pass_through_controllers) - -This controller implements the -[`cartesian_control_msgs/FollowCartesianTrajectory`](http://docs.ros.org/en/noetic/api/cartesian_control_msgs/html/action/FollowCartesianTrajectory.html) -interface. Instead of interpolating the trajectory on ROS side, this forwards the complete -trajectory to the robot for execution leaving the robot in charge of calculating accelerations and -speeds. Therefore, this will lead to motions most similar to what you could configure on the teach -pendant. - -Note that this controller does not check for configuration changes in the robot's kinematics, so -trajectories executed with this controller can potentially result in a protective stop. - -As this uses the robot controller's trajectory execution, trajectories will be slightly different to -the streaming controllers such as the `scaled_pos_joint_traj_controller`. Each setpoint will be -blended with a (currently [hard coded]()https://github.com/UniversalRobots/Universal_Robots_Client_Library/blob/125f4f7a48b299b07e298cf479e3ba6882c3af3a/include/ur_client_library/ur/ur_driver.h#L203) blend radius. - -### `pose_based_cartesian_traj_controller` -**Type:** [`pose_controllers/CartesianTrajectoryController`](http://wiki.ros.org/ros_controllers_cartesian) - -This controller implements the -[`cartesian_control_msgs/FollowCartesianTrajectory`](http://docs.ros.org/en/noetic/api/cartesian_control_msgs/html/action/FollowCartesianTrajectory.html) -interface. Cartesian motion commands are continuously streamed to the robot hardware for execution, -where it uses the robot's own inverse kinematics for calculating the joint commands. - -### `joint_based_cartesian_traj_controller` -**Type:** [`position_controllers/CartesianTrajectoryController`](http://wiki.ros.org/ros_controllers_cartesian) - -This controller implements the -[`cartesian_control_msgs/FollowCartesianTrajectory`](http://docs.ros.org/en/noetic/api/cartesian_control_msgs/html/action/FollowCartesianTrajectory.html) -interface. The continuously generated Cartesian motion commands are transformed to joint commands -using an inverse kinematics method on the ROS side. The robot itself receives joint commands. The IK -method used is interchangeable, see the controller's documentation for details. diff --git a/ur_robot_driver/doc/controllers.rst b/ur_robot_driver/doc/controllers.rst new file mode 100644 index 000000000..0f6fa681b --- /dev/null +++ b/ur_robot_driver/doc/controllers.rst @@ -0,0 +1,231 @@ +.. _controllers: + +ROS-Controllers available for the ur_robot_driver +================================================= + +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.yml`` files, e.g. +`ur10e_controllers.yml `_ +for the UR10e robot. + +How do controllers get loaded and started? +------------------------------------------ + +As this driver uses ROS-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 their ROS interfaces are still visible on the command line e.g. by +``rostopic list``. + +For switching controllers, use the methods offered by the +`controller_manager `_ e.g. to switch from the default +``scaled_pos_joint_traj_controller`` to the ``joint_group_vel_controller`` : + +.. code-block:: bash + + rosservice call /controller_manager/switch_controller "start_controllers: ['joint_group_vel_controller'] + stop_controllers: ['scaled_pos_joint_traj_controller'] + strictness: 2 + start_asap: false + timeout: 0.0" + +For more information on that topic, please refer to the +`controller_manager `_\ 's documentation. + +Read-Only controllers +--------------------- + +These "controllers" 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_controller`` +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Type:** `joint_state_controller/JointStateController `_ + +Publishes all joints' positions, velocities, and motor currents as +`sensor_msgs/JointState `_ on the +``/joint_states`` topic. Note that the ``effort`` field contains the currents reported by the joints and +not the actual *efforts* in a physical sense. + +``robot_status_controller`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Type:** `industrial_robot_status_controller/IndustrialRobotStatusController `_ + +Controller that publishes robot/controller state (e-stopped, in motion, etc) as +`industrial_msgs/RobotStatus `_ +messages on the ``/robot_status`` topic. + +``force_torque_sensor_controller`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Type:** `force_torque_sensor_controller/ForceTorqueSensorController `_ + +This controller publishes the wrench measured from the robot at its TCP as +`geometry_msgs/WrenchStamped `_ +on the topic ``/wrench``. Note that the wrench can be tared to 0 using the +`zero_ftsensor `_ +service. + +``speed_scaling_state_controller`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Type:** `scaled_controllers/SpeedScalingStateController `_ + +Reports the current value of the speed multiplier used from the robot. This is the product of the +speed slider value as it is on the teach pendant and any active speed scaling mechanism. In other +words, this represents the factor of the real slowdown relative to the commanded motion. + +Commanding controllers +---------------------- + +The commanding controllers control the robot's motions. They all claim all joints and therefore only +one of the following can be active at one time. You can define your own controllers with only a +subset of all joints, but this won't be covered here. + +``scaled_pos_joint_traj_controller`` (Default motion controller) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Type:** `position_controllers/ScaledJointTrajectoryController `_ + +Similar to the non-scaled version it implements the +`control_msgs/FollowJointTrajectory `_ +interface. For controlling the robot it will send joint position commands. + +In contrast to the non-scaled version, the speed slider position or any other speed-modifying action +such as pausing, EM-Stop or speed scaling due to limits configured on the robot will be respected by +this controller. If a trajectory is given with time constraints and the trajectory is slowed down +during execution, the action fails. If no time constraints are set and the motion is slowed down +during execution, the actual action call will succeed. + +``joint_group_vel_controller`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Type:** `velocity_controllers/JointGroupVelocityController `_ + +Directly command joint velocities though a topic interface. This controller is useful when doing +things like servoing in joint space. + +``twist_controller`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +**Type:** `ros_controllers_cartesian/TwistController `_ + +Similar to the ``joint_group_vel_controller`` this controller allows directly sending speeds via a +topic interface to the robot. However, this controller expects a Cartesian TCP twist (linear and +angular velocity). This is useful in Cartesian servoing applications such as visual servoing or +teleoperation. + +Note that this controller does not check for configuration changes in the robot's kinematics, twist +commands are sent for execution to the robot. Therefore, commanded motions can result in protective +stops, e.g. when leaving the robot's operation space or forcing it to change its configuration. + +---- + +Controllers below this line are probably less useful for the majority of applications, but can be +used nevertheless. + +``pos_joint_traj_controller`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Type:** `position_controllers/JointTrajectoryController `_ + +This is the most commonly used ROS controller implementing the +`control_msgs/FollowJointTrajectory `_ +interface. For controlling the robot it will send joint position commands. + +**We do not recommend using this controller, as it does not respect the robot's speed scaling value. +Setting the speed slider at another position than 100% or pausing the robot will lead to unexpected +side-effects! Use the scaled version of this controller instead.** + +``vel_joint_traj_controller`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Type:** `velocity_controllers/JointTrajectoryController `_ + +Implements the +`control_msgs/FollowJointTrajectory `_ +interface. For controlling the robot it will send joint velocity commands. + +As this controller uses closed-loop velocity control, it requires tuned PID parameters. Currently, +they are not optimized, see +`#119 `_. + +``scaled_vel_joint_traj_controller`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Type:** `velocity_controllers/ScaledJointTrajectoryController `_ + +Similar to the non-scaled version it implements the +`control_msgs/FollowJointTrajectory `_ +interface. For controlling the robot it will send joint velocity commands. + +In contrast to the non-scaled version, the speed slider position or any other speed-modifying action +such as pausing, EM-Stop or speed scaling due to limits configured on the robot will be respected by +this controller. If a trajectory is given with time constraints and the trajectory is slowed down +during execution, the action fails. If no time constraints are set and the motion is slowed down +during execution, the actual action call will succeed. + +``forward_joint_traj_controller`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Type:** `pass_through_controllers/JointTrajectoryController `_ + +This controller implements the +`control_msgs/FollowJointTrajectory `_ +interface. Instead of interpolating the trajectory on ROS side, this forwards the complete +trajectory to the robot for execution leaving the robot in charge of calculating accelerations and +speeds. Therefore, this will lead to motions most similar to what you could configure on the teach +pendant. + +As this uses the robot controller's trajectory execution, trajectories will be slightly different to +the streaming controllers such as the ``scaled_pos_joint_traj_controller``. Each setpoint will be +blended with a (currently `hard coded `_ blend radius. + +``forward_cartesian_traj_controller`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Type:** `pass_through_controllers/JointTrajectoryController `_ + +This controller implements the +`cartesian_control_msgs/FollowCartesianTrajectory `_ +interface. Instead of interpolating the trajectory on ROS side, this forwards the complete +trajectory to the robot for execution leaving the robot in charge of calculating accelerations and +speeds. Therefore, this will lead to motions most similar to what you could configure on the teach +pendant. + +Note that this controller does not check for configuration changes in the robot's kinematics, so +trajectories executed with this controller can potentially result in a protective stop. + +As this uses the robot controller's trajectory execution, trajectories will be slightly different to +the streaming controllers such as the ``scaled_pos_joint_traj_controller``. Each setpoint will be +blended with a (currently `hard coded `_ blend radius. + +``pose_based_cartesian_traj_controller`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Type:** `pose_controllers/CartesianTrajectoryController `_ + +This controller implements the +`cartesian_control_msgs/FollowCartesianTrajectory `_ +interface. Cartesian motion commands are continuously streamed to the robot hardware for execution, +where it uses the robot's own inverse kinematics for calculating the joint commands. + +``joint_based_cartesian_traj_controller`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Type:** `position_controllers/CartesianTrajectoryController `_ + +This controller implements the +`cartesian_control_msgs/FollowCartesianTrajectory `_ +interface. The continuously generated Cartesian motion commands are transformed to joint commands +using an inverse kinematics method on the ROS side. The robot itself receives joint commands. The IK +method used is interchangeable, see the controller's documentation for details. diff --git a/ur_robot_driver/doc/features.md b/ur_robot_driver/doc/features.md deleted file mode 100644 index ed1de33a6..000000000 --- a/ur_robot_driver/doc/features.md +++ /dev/null @@ -1,38 +0,0 @@ -# Quick feature overview - -| Feature | this_driver | -| --- | --- | -| joint-position-based control | yes | -| scaled joint-position-based control | yes | -| joint-velocity-based control | yes | -| Cartesian position-based control | yes | -| Cartesian twist-based control | yes | -| Trajectory forwarding for execution on robot | yes | -| reporting of tcp wrench | yes | -| pausing of programs | yes | -| continue trajectories after EM-Stop resume | yes | -| continue trajectories after protective stop | yes | -| panel interaction in between possible | yes | -| get and set IO states | yes | -| use tool communication on e-series | yes1 | -| use the driver without a teach pendant necessary | yes | -| support of CB1 and CB2 robots | no | -| trajectory extrapolation on robot on missing packages | yes | -| use ROS as drop-in for TP-programs | yes2 | -| headless mode | yes | -| extract calibration from robot | yes | -| send custom script commands to robot | yes | -| ROS 2 support | (yes)3 | -| Reconnect on a disconnected robot | yes | - -1 Requires URCap (included in -[resources](https://github.com/UniversalRobots/Universal_Robots_ROS_Driver/tree/master/ur_robot_driver/resources)): -[https://github.com/UniversalRobots/Universal_Robots_ToolComm_Forwarder_URCap](https://github.com/UniversalRobots/Universal_Robots_ToolComm_Forwarder_URCap) - -2 Requires URCap (included in -[resources](https://github.com/UniversalRobots/Universal_Robots_ROS_Driver/tree/master/ur_robot_driver/resources)): -[https://github.com/UniversalRobots/Universal_Robots_ExternalControl_URCap](https://github.com/UniversalRobots/Universal_Robots_ExternalControl_URCap) - -3 The ROS2 driver lives in its own repository: -[https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver](https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver) - diff --git a/ur_robot_driver/doc/features.rst b/ur_robot_driver/doc/features.rst new file mode 100644 index 000000000..ba730574d --- /dev/null +++ b/ur_robot_driver/doc/features.rst @@ -0,0 +1,68 @@ +.. role:: raw-html-m2r(raw) + :format: html + + +Quick feature overview +====================== + +.. list-table:: + :header-rows: 1 + + * - Feature + - this_driver + * - joint-position-based control + - yes + * - scaled joint-position-based control + - yes + * - joint-velocity-based control + - yes + * - Cartesian position-based control + - yes + * - Cartesian twist-based control + - yes + * - Trajectory forwarding for execution on robot + - yes + * - reporting of tcp wrench + - yes + * - pausing of programs + - yes + * - continue trajectories after EM-Stop resume + - yes + * - continue trajectories after protective stop + - yes + * - panel interaction in between possible + - yes + * - get and set IO states + - yes + * - use tool communication on e-series + - yes\ :raw-html-m2r:`1` + * - use the driver without a teach pendant necessary + - yes + * - support of CB1 and CB2 robots + - no + * - trajectory extrapolation on robot on missing packages + - yes + * - use ROS as drop-in for TP-programs + - yes\ :raw-html-m2r:`2` + * - headless mode + - yes + * - extract calibration from robot + - yes + * - send custom script commands to robot + - yes + * - ROS 2 support + - (yes)\ :raw-html-m2r:`3` + * - Reconnect on a disconnected robot + - yes + + +:raw-html-m2r:`1` Requires URCap (included in +`resources `_\ ): +`https://github.com/UniversalRobots/Universal_Robots_ToolComm_Forwarder_URCap `_ + +:raw-html-m2r:`2` Requires URCap (included in +`resources `_\ ): +`https://github.com/UniversalRobots/Universal_Robots_ExternalControl_URCap `_ + +:raw-html-m2r:`3` The ROS2 driver lives in its own repository: +`https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver `_ diff --git a/ur_robot_driver/doc/index.rst b/ur_robot_driver/doc/index.rst new file mode 100644 index 000000000..b907256e0 --- /dev/null +++ b/ur_robot_driver/doc/index.rst @@ -0,0 +1,14 @@ +############################################# +Universal Robots ROS driver (ur_robot_driver) +############################################# + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + features + installation/toc + setup_tool_communication + controllers + usage_example + ROS_INTERFACE diff --git a/ur_robot_driver/doc/installation/build.rst b/ur_robot_driver/doc/installation/build.rst new file mode 100644 index 000000000..210df4352 --- /dev/null +++ b/ur_robot_driver/doc/installation/build.rst @@ -0,0 +1,61 @@ +Building +======== + +**Note:** The driver consists of a `C++ +library `_ that abstracts the +robot's interfaces and a ROS driver on top of that. As the library can be built without ROS support, +it is not a catkin package and therefore requires a different treatment when being built inside the +workspace. See The alternative build method below if you'd like to build the library from source. + +If you don't want to build the library from source, it is available as a binary package through the +ROS distribution of ROS melodic and noetic. It will be installed automatically if you +follow the steps below. If you'd like to also build the library from source, please follow the steps +explained in the [next section](#alternative-all-source-build). + +.. code:: bash + + # source global ros + $ source /opt/ros//setup.bash + + # create a catkin workspace + $ mkdir -p catkin_ws/src && cd catkin_ws + + # clone the driver + $ git clone https://github.com/UniversalRobots/Universal_Robots_ROS_Driver.git src/Universal_Robots_ROS_Driver + + # clone fork of the description. This is currently necessary, until the changes are merged upstream. + $ git clone -b calibration_devel https://github.com/fmauch/universal_robot.git src/fmauch_universal_robot + + # install dependencies + $ sudo apt update -qq + $ rosdep update + $ rosdep install --from-paths src --ignore-src -y + + # build the workspace + $ catkin_make + + # activate the workspace (ie: source it) + $ source devel/setup.bash + + +Alternative: All-source build +----------------------------- + +If you would like to also build the library from source, clone the library into your workspace, as +well and build it using either ``catkin_make_isolated`` or `catkin +build `_. + +.. code:: bash + + $ source /opt/ros//setup.bash + $ mkdir -p catkin_ws/src && cd catkin_ws + $ git clone -b boost https://github.com/UniversalRobots/Universal_Robots_Client_Library.git src/Universal_Robots_Client_Library + $ git clone https://github.com/UniversalRobots/Universal_Robots_ROS_Driver.git src/Universal_Robots_ROS_Driver + $ git clone -b calibration_devel https://github.com/fmauch/universal_robot.git src/fmauch_universal_robot + $ sudo apt update -qq + $ rosdep update + $ rosdep install --from-paths src --ignore-src -y + $ catkin_make_isolated + $ source devel_isolated/setup.bash + + diff --git a/ur_robot_driver/doc/initial_setup_images/cb3_01_welcome.png b/ur_robot_driver/doc/installation/initial_setup_images/cb3_01_welcome.png similarity index 100% rename from ur_robot_driver/doc/initial_setup_images/cb3_01_welcome.png rename to ur_robot_driver/doc/installation/initial_setup_images/cb3_01_welcome.png diff --git a/ur_robot_driver/doc/initial_setup_images/cb3_05_urcaps_installed.png b/ur_robot_driver/doc/installation/initial_setup_images/cb3_05_urcaps_installed.png similarity index 100% rename from ur_robot_driver/doc/initial_setup_images/cb3_05_urcaps_installed.png rename to ur_robot_driver/doc/installation/initial_setup_images/cb3_05_urcaps_installed.png diff --git a/ur_robot_driver/doc/initial_setup_images/cb3_07_installation_excontrol.png b/ur_robot_driver/doc/installation/initial_setup_images/cb3_07_installation_excontrol.png similarity index 100% rename from ur_robot_driver/doc/initial_setup_images/cb3_07_installation_excontrol.png rename to ur_robot_driver/doc/installation/initial_setup_images/cb3_07_installation_excontrol.png diff --git a/ur_robot_driver/doc/initial_setup_images/cb3_10_prog_structure_urcaps.png b/ur_robot_driver/doc/installation/initial_setup_images/cb3_10_prog_structure_urcaps.png similarity index 100% rename from ur_robot_driver/doc/initial_setup_images/cb3_10_prog_structure_urcaps.png rename to ur_robot_driver/doc/installation/initial_setup_images/cb3_10_prog_structure_urcaps.png diff --git a/ur_robot_driver/doc/initial_setup_images/cb3_11_program_view_excontrol.png b/ur_robot_driver/doc/installation/initial_setup_images/cb3_11_program_view_excontrol.png similarity index 100% rename from ur_robot_driver/doc/initial_setup_images/cb3_11_program_view_excontrol.png rename to ur_robot_driver/doc/installation/initial_setup_images/cb3_11_program_view_excontrol.png diff --git a/ur_robot_driver/doc/initial_setup_images/e-Series.jpg b/ur_robot_driver/doc/installation/initial_setup_images/e-Series.jpg similarity index 100% rename from ur_robot_driver/doc/initial_setup_images/e-Series.jpg rename to ur_robot_driver/doc/installation/initial_setup_images/e-Series.jpg diff --git a/ur_robot_driver/doc/initial_setup_images/es_01_welcome.png b/ur_robot_driver/doc/installation/initial_setup_images/es_01_welcome.png similarity index 100% rename from ur_robot_driver/doc/initial_setup_images/es_01_welcome.png rename to ur_robot_driver/doc/installation/initial_setup_images/es_01_welcome.png diff --git a/ur_robot_driver/doc/initial_setup_images/es_05_urcaps_installed.png b/ur_robot_driver/doc/installation/initial_setup_images/es_05_urcaps_installed.png similarity index 100% rename from ur_robot_driver/doc/initial_setup_images/es_05_urcaps_installed.png rename to ur_robot_driver/doc/installation/initial_setup_images/es_05_urcaps_installed.png diff --git a/ur_robot_driver/doc/initial_setup_images/es_07_installation_excontrol.png b/ur_robot_driver/doc/installation/initial_setup_images/es_07_installation_excontrol.png similarity index 100% rename from ur_robot_driver/doc/initial_setup_images/es_07_installation_excontrol.png rename to ur_robot_driver/doc/installation/initial_setup_images/es_07_installation_excontrol.png diff --git a/ur_robot_driver/doc/initial_setup_images/es_10_prog_structure_urcaps.png b/ur_robot_driver/doc/installation/initial_setup_images/es_10_prog_structure_urcaps.png similarity index 100% rename from ur_robot_driver/doc/initial_setup_images/es_10_prog_structure_urcaps.png rename to ur_robot_driver/doc/installation/initial_setup_images/es_10_prog_structure_urcaps.png diff --git a/ur_robot_driver/doc/initial_setup_images/es_11_program_view_excontrol.png b/ur_robot_driver/doc/installation/initial_setup_images/es_11_program_view_excontrol.png similarity index 100% rename from ur_robot_driver/doc/initial_setup_images/es_11_program_view_excontrol.png rename to ur_robot_driver/doc/installation/initial_setup_images/es_11_program_view_excontrol.png diff --git a/ur_robot_driver/doc/install_urcap_cb3.md b/ur_robot_driver/doc/installation/install_urcap_cb3.rst similarity index 70% rename from ur_robot_driver/doc/install_urcap_cb3.md rename to ur_robot_driver/doc/installation/install_urcap_cb3.rst index 600b7c848..31c450621 100644 --- a/ur_robot_driver/doc/install_urcap_cb3.md +++ b/ur_robot_driver/doc/installation/install_urcap_cb3.rst @@ -1,9 +1,12 @@ -# Installing a URCap on a CB3 robot +.. _install-urcap-cb3: + +Installing a URCap on a CB3 robot +================================= For using the *ur_robot_driver* with a real robot you need to install the **externalcontrol-1.0.5.urcap** which can be found inside the **resources** folder of this driver. -**Note**: For installing this URCap a minimal PolyScope version of 3.7 is necessary. +**Note**\ : For installing this URCap a minimal PolyScope version of 3.7 is necessary. To install it you first have to copy it to the robot's **programs** folder which can be done either via scp or using a USB stick. @@ -11,7 +14,10 @@ via scp or using a USB stick. On the welcome screen select *Setup Robot* and then *URCaps* to enter the URCaps installation screen. - ![Welcome screen of a CB3 robot](initial_setup_images/cb3_01_welcome.png) + +.. image:: initial_setup_images/cb3_01_welcome.png + :alt: Welcome screen of a CB3 robot + There, click the little plus sign at the bottom to open the file selector. There you should see all urcap files stored inside the robot's programs folder or a plugged USB drive. Select and open @@ -19,25 +25,36 @@ the **externalcontrol-1.0.5.urcap** file and click *open*. Your URCaps view shou **External Control** in the list of active URCaps and a notification to restart the robot. Do that now. - ![URCaps screen with installed urcaps](initial_setup_images/cb3_05_urcaps_installed.png) + +.. image:: initial_setup_images/cb3_05_urcaps_installed.png + :alt: URCaps screen with installed urcaps + After the reboot you should find the **External Control** URCaps inside the *Installation* section. For this select *Program Robot* on the welcome screen, select the *Installation* tab and select **External Control** from the list. - ![Installation screen of URCaps](initial_setup_images/cb3_07_installation_excontrol.png) + +.. image:: initial_setup_images/cb3_07_installation_excontrol.png + :alt: Installation screen of URCaps + Here you'll have to setup the IP address of the external PC which will be running the ROS driver. Note that the robot and the external PC have to be in the same network, ideally in a direct connection with each other to minimize network disturbances. The custom port should be left untouched for now. - ![Insert the external control node](initial_setup_images/cb3_10_prog_structure_urcaps.png) + +.. image:: initial_setup_images/cb3_10_prog_structure_urcaps.png + :alt: Insert the external control node + To use the new URCaps, create a new program and insert the **External Control** program node into the program tree - ![Program view of external control](initial_setup_images/cb3_11_program_view_excontrol.png) +.. image:: initial_setup_images/cb3_11_program_view_excontrol.png + :alt: Program view of external control + If you click on the *command* tab again, you'll see the settings entered inside the *Installation*. Check that they are correct, then save the program. Your robot is now ready to be used together with diff --git a/ur_robot_driver/doc/install_urcap_e_series.md b/ur_robot_driver/doc/installation/install_urcap_e_series.rst similarity index 69% rename from ur_robot_driver/doc/install_urcap_e_series.md rename to ur_robot_driver/doc/installation/install_urcap_e_series.rst index db26cc2c4..c0a7bc1ec 100644 --- a/ur_robot_driver/doc/install_urcap_e_series.md +++ b/ur_robot_driver/doc/installation/install_urcap_e_series.rst @@ -1,16 +1,23 @@ -# Installing a URCap on a e-Series robot +.. _install-urcap-e-series: + +Installing a URCap on a e-Series robot +====================================== For using the *ur_robot_driver* with a real robot you need to install the **externalcontrol-1.0.5.urcap** which can be found inside the **resources** folder of this driver. -**Note**: For installing this URCap a minimal PolyScope version of 5.1 is necessary. +**Note**\ : For installing this URCap a minimal PolyScope version of 5.1 is necessary. To install it you first have to copy it to the robot's **programs** folder which can be done either via scp or using a USB stick. On the welcome screen click on the hamburger menu in the top-right corner and select *Settings* to enter the robot's setup. There select *System* and then *URCaps* to enter the URCaps installation screen. - ![Welcome screen of an e-Series robot](initial_setup_images/es_01_welcome.png) + +.. image:: initial_setup_images/es_01_welcome.png + :width: 800 + :alt: Welcome screen of an e-Series robot + There, click the little plus sign at the bottom to open the file selector. There you should see all urcap files stored inside the robot's programs folder or a plugged USB drive. Select and open @@ -18,25 +25,37 @@ the **externalcontrol-1.0.5.urcap** file and click *open*. Your URCaps view shou **External Control** in the list of active URCaps and a notification to restart the robot. Do that now. - ![URCaps screen with installed urcaps](initial_setup_images/es_05_urcaps_installed.png) +.. image:: initial_setup_images/es_05_urcaps_installed.png + :width: 800 + :alt: URCaps screen with installed urcaps + After the reboot you should find the **External Control** URCaps inside the *Installation* section. For this select *Program Robot* on the welcome screen, select the *Installation* tab and select **External Control** from the list. - ![Installation screen of URCaps](initial_setup_images/es_07_installation_excontrol.png) +.. image:: initial_setup_images/es_07_installation_excontrol.png + :width: 800 + :alt: Installation screen of URCaps + Here you'll have to setup the IP address of the external PC which will be running the ROS driver. Note that the robot and the external PC have to be in the same network, ideally in a direct connection with each other to minimize network disturbances. The custom port should be left untouched for now. - ![Insert the external control node](initial_setup_images/es_10_prog_structure_urcaps.png) +.. image:: initial_setup_images/es_10_prog_structure_urcaps.png + :width: 800 + :alt: Insert the external control node + To use the new URCaps, create a new program and insert the **External Control** program node into the program tree - ![Program view of external control](initial_setup_images/es_11_program_view_excontrol.png) +.. image:: initial_setup_images/es_11_program_view_excontrol.png + :width: 800 + :alt: Program view of external control + If you click on the *command* tab again, you'll see the settings entered inside the *Installation*. Check that they are correct, then save the program. Your robot is now ready to be used together with diff --git a/ur_robot_driver/doc/installation/real_time_kernel.rst b/ur_robot_driver/doc/installation/real_time_kernel.rst new file mode 100644 index 000000000..cee9ceb65 --- /dev/null +++ b/ur_robot_driver/doc/installation/real_time_kernel.rst @@ -0,0 +1,312 @@ +.. _real-time-kernel: + +Setting up Ubuntu with a PREEMPT_RT kernel +========================================== + +In order to run the ``universal_robot_driver``\ , we highly recommend to setup a ubuntu system with +real-time capabilities. Especially with a robot from the e-Series the higher control frequency +might lead to non-smooth trajectory execution if not run using a real-time-enabled system. + +You might still be able to control the robot using a non-real-time system. This is, however, not recommended. + +To get real-time support into a ubuntu system, the following steps have to be performed: + + +#. Get the sources of a real-time kernel +#. Compile the real-time kernel +#. Setup user privileges to execute real-time tasks + +This guide will help you setup your system with a real-time kernel. + +Preparing +--------- + +To build the kernel, you will need a couple of tools available on your system. You can install them +using + +.. code-block:: bash + + $ sudo apt-get install build-essential bc ca-certificates gnupg2 libssl-dev wget gawk flex bison + +Before you download the sources of a real-time-enabled kernel, check the kernel version that is currently installed: + +.. code-block:: bash + + $ uname -r + 4.15.0-62-generic + +To continue with this tutorial, please create a temporary folder and navigate into it. You should +have sufficient space (around 25GB) there, as the extracted kernel sources take much space. After +the new kernel is installed, you can delete this folder again. + +In this example we will use a temporary folder inside our home folder: + +.. code-block:: bash + + $ mkdir -p ${HOME}/rt_kernel_build + $ cd ${HOME}/rt_kernel_build + +All future commands are expected to be run inside this folder. If the folder is different, the ``$`` +sign will be prefixed with a path relative to the above folder. + +Getting the sources for a real-time kernel +------------------------------------------ + +To build a real-time kernel, we first need to get the kernel sources and the real-time patch. + +First, we must decide on the kernel version that we want to use. Above, we +determined that our system has a 4.15 kernel installed. However, real-time +patches exist only for selected kernel versions. Those can be found on the +`linuxfoundation wiki `_. + +In this example, we will select a 4.14 kernel. Select a kernel version close to the +one installed on your system. + +Go ahead and download the kernel sources, patch sources and their signature files: + +.. code-block:: bash + + $ wget https://cdn.kernel.org/pub/linux/kernel/projects/rt/4.14/patch-4.14.139-rt66.patch.xz + $ wget https://cdn.kernel.org/pub/linux/kernel/projects/rt/4.14/patch-4.14.139-rt66.patch.sign + $ wget https://www.kernel.org/pub/linux/kernel/v4.x/linux-4.14.139.tar.xz + $ wget https://www.kernel.org/pub/linux/kernel/v4.x/linux-4.14.139.tar.sign + +To unzip the downloaded files do + +.. code-block:: bash + + $ xz -dk patch-4.14.139-rt66.patch.xz + $ xz -d linux-4.14.139.tar.xz + +Verification +^^^^^^^^^^^^ + +Technically, you can skip this section, it is however highly recommended to verify the file +integrity of such a core component of your system! + +To verify file integrity, you must first import public keys by the kernel developers and the patch +author. For the kernel sources use (as suggested on +`kernel.org `_\ ) + +.. code-block:: bash + + $ gpg2 --locate-keys torvalds@kernel.org gregkh@kernel.org + +and for the patch search for a key of the author listed on +`linuxfoundation wiki `_. + +.. code-block:: text + + $ gpg2 --keyserver hkp://keys.gnupg.net --search-keys zanussi + gpg: data source: http://51.38.91.189:11371 + (1) German Daniel Zanussi + 4096 bit RSA key 0x537F98A9D92CEAC8, created: 2019-07-24, expires: 2023-07-24 + (2) Michael Zanussi + 4096 bit RSA key 0x7C7F76A2C1E3D9EB, created: 2019-05-08 + (3) Tom Zanussi + Tom Zanussi + Tom Zanussi + 4096 bit RSA key 0xDE09826778A38521, created: 2017-12-15 + (4) Riccardo Zanussi + 2048 bit RSA key 0xD299A06261D919C3, created: 2014-08-27, expires: 2018-08-27 (expired) + (5) Zanussi Gianni + 1024 bit DSA key 0x78B89CB020D1836C, created: 2004-04-06 + (6) Michael Zanussi + Michael Zanussi + Michael Zanussi + Michael Zanussi + 1024 bit DSA key 0xB3E952DCAC653064, created: 2000-09-05 + (7) Michael Zanussi + 1024 bit DSA key 0xEB10BBD9BA749318, created: 1999-05-31 + (8) Michael B. Zanussi + 1024 bit DSA key 0x39EE4EAD7BBB1E43, created: 1998-07-16 + Keys 1-8 of 8 for "zanussi". Enter number(s), N)ext, or Q)uit > 3 + +Now we can verify the downloaded sources: + +.. code-block:: text + + $ gpg2 --verify linux-4.14.139.tar.sign + gpg: assuming signed data in 'linux-4.14.139.tar' + gpg: Signature made Fr 16 Aug 2019 10:15:17 CEST + gpg: using RSA key 647F28654894E3BD457199BE38DBBDC86092693E + gpg: Good signature from "Greg Kroah-Hartman " [unknown] + gpg: WARNING: This key is not certified with a trusted signature! + gpg: There is no indication that the signature belongs to the owner. + Primary key fingerprint: 647F 2865 4894 E3BD 4571 99BE 38DB BDC8 6092 693E + + $ gpg2 --verify patch-4.14.139-rt66.patch.sign + gpg: assuming signed data in 'patch-4.14.139-rt66.patch' + gpg: Signature made Fr 23 Aug 2019 21:09:20 CEST + gpg: using RSA key 0x0129F38552C38DF1 + gpg: Good signature from "Tom Zanussi " [unknown] + gpg: aka "Tom Zanussi " [unknown] + gpg: aka "Tom Zanussi " [unknown] + gpg: WARNING: This key is not certified with a trusted signature! + gpg: There is no indication that the signature belongs to the owner. + Primary key fingerprint: 5BDF C45C 2ECC 5387 D50C E5EF DE09 8267 78A3 8521 + Subkey fingerprint: ACF8 5F98 16A8 D5F0 96AE 1FD2 0129 F385 52C3 8DF1 + +Compilation +----------- + +Before we can compile the sources, we have to extract the tar archive and apply the patch + +.. code-block:: bash + + $ tar xf linux-4.14.139.tar + $ cd linux-4.14.139 + linux-4.14.139$ xzcat ../patch-4.14.139-rt66.patch.xz | patch -p1 + +Now to configure your kernel, just type + +.. code-block:: bash + + linux-4.14.139$ make oldconfig + +This will ask for kernel options. For everything else then the ``Preemption Model`` use the default +value (just press Enter) or adapt to your preferences. For the preemption model select ``Fully Preemptible Kernel``\ : + +.. code-block:: text + + Preemption Model + 1. No Forced Preemption (Server) (PREEMPT_NONE) + > 2. Voluntary Kernel Preemption (Desktop) (PREEMPT_VOLUNTARY) + 3. Preemptible Kernel (Low-Latency Desktop) (PREEMPT__LL) (NEW) + 4. Preemptible Kernel (Basic RT) (PREEMPT_RTB) (NEW) + 5. Fully Preemptible Kernel (RT) (PREEMPT_RT_FULL) (NEW) + choice[1-5]: 5 + +Now you can build the kernel. This will take some time... + +.. code-block:: bash + + linux-4.14.139$ make -j `getconf _NPROCESSORS_ONLN` deb-pkg + +After building, install the ``linux-headers`` and ``linux-image`` packages in the parent folder (only +the ones without the ``-dbg`` in the name) + +.. code-block:: bash + + linux-4.14.139$ sudo apt install ../linux-headers-4.14.139-rt66_*.deb ../linux-image-4.14.139-rt66_*.deb + +Setup user privileges to use real-time scheduling +------------------------------------------------- + +To be able to schedule threads with user privileges (what the driver will do) you'll have to change +the user's limits by changing ``/etc/security/limits.conf`` (See `the manpage `_ for details) + +We recommend to setup a group for real-time users instead of writing a fixed username into the config +file: + +.. code-block:: bash + + $ sudo groupadd realtime + $ sudo usermod -aG realtime $(whoami) + +Then, make sure ``/etc/security/limits.conf`` contains + +.. code-block:: text + + @realtime soft rtprio 99 + @realtime soft priority 99 + @realtime soft memlock 102400 + @realtime hard rtprio 99 + @realtime hard priority 99 + @realtime hard memlock 102400 + +Note: You will have to log out and log back in (Not only close your terminal window) for these +changes to take effect. No need to do this now, as we will reboot later on, anyway. + +Setup GRUB to always boot the real-time kernel +---------------------------------------------- + +To make the new kernel the default kernel that the system will boot into every time, you'll have to +change the grub config file inside ``/etc/default/grub``. + +Note: This works for ubuntu, but might not be working for other linux systems. It might be necessary +to use another menuentry name there. + +But first, let's find out the name of the entry that we will want to make the default. You can list +all available kernels using + +.. code-block:: text + + $ awk -F\' '/menuentry |submenu / {print $1 $2}' /boot/grub/grub.cfg + + menuentry Ubuntu + submenu Advanced options for Ubuntu + menuentry Ubuntu, with Linux 4.15.0-62-generic + menuentry Ubuntu, with Linux 4.15.0-62-generic (recovery mode) + menuentry Ubuntu, with Linux 4.15.0-60-generic + menuentry Ubuntu, with Linux 4.15.0-60-generic (recovery mode) + menuentry Ubuntu, with Linux 4.15.0-58-generic + menuentry Ubuntu, with Linux 4.15.0-58-generic (recovery mode) + menuentry Ubuntu, with Linux 4.14.139-rt66 + menuentry Ubuntu, with Linux 4.14.139-rt66 (recovery mode) + menuentry Memory test (memtest86+) + menuentry Memory test (memtest86+, serial console 115200) + menuentry Windows 7 (on /dev/sdc2) + menuentry Windows 7 (on /dev/sdc3) + +From the output above, we'll need to generate a string with the pattern ``"submenu_name>entry_name"``. In our case this would be + +.. code-block:: text + + "Advanced options for Ubuntu>Ubuntu, with Linux 4.14.139-rt66" + +**The double quotes and no spaces around the ``>`` are important!** + +With this, we can setup the default grub entry and then update the grub menu entries. Don't forget this last step! + +.. code-block:: bash + + $ sudo sed -i 's/^GRUB_DEFAULT=.*/GRUB_DEFAULT="Advanced options for Ubuntu>Ubuntu, with Linux 4.14.139-rt66"/' /etc/default/grub + $ sudo update-grub + +Reboot the PC +------------- + +After having performed the above mentioned steps, reboot the PC. It should boot into the correct +kernel automatically. + +Check for preemption capabilities +--------------------------------- + +Make sure that the kernel does indeed support real-time scheduling: + +.. code-block:: bash + + $ uname -v | cut -d" " -f1-4 + #1 SMP PREEMPT RT + +Optional: Disable CPU speed scaling +----------------------------------- + +Many modern CPUs support changing their clock frequency dynamically depending on the currently +requested computation resources. In some cases this can lead to small interruptions in execution. +While the real-time scheduled controller thread should be unaffected by this, any external +components such as a visual servoing system might be interrupted for a short period on scaling +changes. + +To check and modify the power saving mode, install cpufrequtils: + +.. code-block:: bash + + $ sudo apt install cpufrequtils + +Run ``cpufreq-info`` to check available "governors" and the current CPU Frequency (\ ``current CPU +frequency is XXX MHZ``\ ). In the following we will set the governor to "performance". + +.. code-block:: bash + + $ sudo systemctl disable ondemand + $ sudo systemctl enable cpufrequtils + $ sudo sh -c 'echo "GOVERNOR=performance" > /etc/default/cpufrequtils' + $ sudo systemctl daemon-reload && sudo systemctl restart cpufrequtils + +This disables the ``ondemand`` CPU scaling daemon, creates a ``cpufrequtils`` config file and restarts +the ``cpufrequtils`` service. Check with ``cpufreq-info``. + +For further information about governors, please see the `kernel +documentation `_. diff --git a/ur_robot_driver/doc/installation/requirements.rst b/ur_robot_driver/doc/installation/requirements.rst new file mode 100644 index 000000000..44d122c16 --- /dev/null +++ b/ur_robot_driver/doc/installation/requirements.rst @@ -0,0 +1,17 @@ +Requirements +============ + +For using the ``ur_robot_driver`` your setup should fulfill a couple of requirements: + + * ROS should be running as close to real-time as possible. If you use the driver in a VM setup, + expect occasional disconnection problems. For the best experience, please install a real-time + kernel as explained in the :ref:`real-time setup guide `. + * Please use a direct cable connection between the ROS machine and the robot. Using a switch with + other network participants connected might introduce problems on the communication between the + driver and the robot. Especially in cases of high load on the network things will go wrong. + Especially, please **do not use a WIFI connection** for controlling the robot. This will not be + stable and responsive enough to do high-frequency control. + * For this driver to work, please use PolyScope software version >= 3.7 for a CB3 robot and + software >= 5.1 for an e-Series model. + * This driver and all of its resources should work under ROS melodic on Ubuntu 18.04 and ROS noetic + on Ubuntu 20.04. diff --git a/ur_robot_driver/doc/installation/robot_setup.rst b/ur_robot_driver/doc/installation/robot_setup.rst new file mode 100644 index 000000000..caf6f82fa --- /dev/null +++ b/ur_robot_driver/doc/installation/robot_setup.rst @@ -0,0 +1,48 @@ +Setting up a UR robot for ur_robot_driver +========================================= + +Prepare the robot +----------------- + +For using the *ur_robot_driver* with a real robot you need to install the +**externalcontrol-1.0.5.urcap** which can be found inside the **resources** folder of this driver. + +**Note**: For installing this URCap a minimal PolyScope version of 3.7 or 5.1 (in case of e-Series) is +necessary. + +For installing the necessary URCap and creating a program, please see the individual tutorials on +how to :ref:`setup a cb3 robot ` or how to +:ref:`setup an e-Series robot `. + +To setup the tool communication on an e-Series robot, please consider the :ref:`tool communication setup +guide `. + +Prepare the ROS PC +------------------ + +For using the driver make sure it is installed (either by the debian package or built from source +inside a catkin workspace). + +Extract calibration information +------------------------------- + +Each UR robot is calibrated inside the factory giving exact forward and inverse kinematics. To also +make use of this in ROS, you first have to extract the calibration information from the robot. + +Though this step is not necessary to control the robot using this driver, it is highly recommended +to do so, as otherwise endeffector positions might be off in the magnitude of centimeters. + + +For this, there exists a helper script: + +.. code:: bash + + $ roslaunch ur_calibration calibration_correction.launch \ + robot_ip:= target_filename:="${HOME}/my_robot_calibration.yaml" + +For the parameter ``robot_ip`` insert the IP address on which the ROS pc can reach the robot. As +``target_filename`` provide an absolute path where the result will be saved to. + +We recommend keeping calibrations for all robots in your organization in a common package. See the +`package's documentation `_ for details. + diff --git a/ur_robot_driver/doc/installation/toc.rst b/ur_robot_driver/doc/installation/toc.rst new file mode 100644 index 000000000..7321ec5ba --- /dev/null +++ b/ur_robot_driver/doc/installation/toc.rst @@ -0,0 +1,17 @@ +############ +Installation +############ + +This chapter explains how to install the ``ur_robot_driver`` + + +.. toctree:: + :maxdepth: 4 + :caption: Contents: + + requirements + real_time_kernel + build + robot_setup + install_urcap_cb3 + install_urcap_e_series diff --git a/ur_robot_driver/doc/real_time.md b/ur_robot_driver/doc/real_time.md deleted file mode 100644 index c7d02207f..000000000 --- a/ur_robot_driver/doc/real_time.md +++ /dev/null @@ -1,282 +0,0 @@ -# Setting up Ubuntu with a PREEMPT_RT kernel -In order to run the `universal_robot_driver`, we highly recommend to setup a ubuntu system with -real-time capabilities. Especially with a robot from the e-Series the higher control frequency -might lead to non-smooth trajectory execution if not run using a real-time-enabled system. - -You might still be able to control the robot using a non-real-time system. This is, however, not recommended. - -To get real-time support into a ubuntu system, the following steps have to be performed: - 1. Get the sources of a real-time kernel - 2. Compile the real-time kernel - 3. Setup user privileges to execute real-time tasks - -This guide will help you setup your system with a real-time kernel. - -## Preparing -To build the kernel, you will need a couple of tools available on your system. You can install them -using - -``` bash -$ sudo apt-get install build-essential bc ca-certificates gnupg2 libssl-dev wget gawk flex bison -``` - -Before you download the sources of a real-time-enabled kernel, check the kernel version that is currently installed: - -```bash -$ uname -r -4.15.0-62-generic -``` - -To continue with this tutorial, please create a temporary folder and navigate into it. You should -have sufficient space (around 25GB) there, as the extracted kernel sources take much space. After -the new kernel is installed, you can delete this folder again. - -In this example we will use a temporary folder inside our home folder: - -```bash -$ mkdir -p ${HOME}/rt_kernel_build -$ cd ${HOME}/rt_kernel_build -``` - -All future commands are expected to be run inside this folder. If the folder is different, the `$` -sign will be prefixed with a path relative to the above folder. - -## Getting the sources for a real-time kernel -To build a real-time kernel, we first need to get the kernel sources and the real-time patch. - -First, we must decide on the kernel version that we want to use. Above, we -determined that our system has a 4.15 kernel installed. However, real-time -patches exist only for selected kernel versions. Those can be found on the -[linuxfoundation wiki](https://wiki.linuxfoundation.org/realtime/preempt_rt_versions). - -In this example, we will select a 4.14 kernel. Select a kernel version close to the -one installed on your system. - -Go ahead and download the kernel sources, patch sources and their signature files: - -```bash -$ wget https://cdn.kernel.org/pub/linux/kernel/projects/rt/4.14/patch-4.14.139-rt66.patch.xz -$ wget https://cdn.kernel.org/pub/linux/kernel/projects/rt/4.14/patch-4.14.139-rt66.patch.sign -$ wget https://www.kernel.org/pub/linux/kernel/v4.x/linux-4.14.139.tar.xz -$ wget https://www.kernel.org/pub/linux/kernel/v4.x/linux-4.14.139.tar.sign -``` - -To unzip the downloaded files do -```bash -$ xz -dk patch-4.14.139-rt66.patch.xz -$ xz -d linux-4.14.139.tar.xz -``` - -### Verification -Technically, you can skip this section, it is however highly recommended to verify the file -integrity of such a core component of your system! - -To verify file integrity, you must first import public keys by the kernel developers and the patch -author. For the kernel sources use (as suggested on -[kernel.org](https://www.kernel.org/signature.html)) - -```bash -$ gpg2 --locate-keys torvalds@kernel.org gregkh@kernel.org -``` - -and for the patch search for a key of the author listed on -[linuxfoundation wiki](https://wiki.linuxfoundation.org/realtime/preempt_rt_versions). - -```bash -$ gpg2 --keyserver hkp://keys.gnupg.net --search-keys zanussi -gpg: data source: http://51.38.91.189:11371 -(1) German Daniel Zanussi - 4096 bit RSA key 0x537F98A9D92CEAC8, created: 2019-07-24, expires: 2023-07-24 -(2) Michael Zanussi - 4096 bit RSA key 0x7C7F76A2C1E3D9EB, created: 2019-05-08 -(3) Tom Zanussi - Tom Zanussi - Tom Zanussi - 4096 bit RSA key 0xDE09826778A38521, created: 2017-12-15 -(4) Riccardo Zanussi - 2048 bit RSA key 0xD299A06261D919C3, created: 2014-08-27, expires: 2018-08-27 (expired) -(5) Zanussi Gianni - 1024 bit DSA key 0x78B89CB020D1836C, created: 2004-04-06 -(6) Michael Zanussi - Michael Zanussi - Michael Zanussi - Michael Zanussi - 1024 bit DSA key 0xB3E952DCAC653064, created: 2000-09-05 -(7) Michael Zanussi - 1024 bit DSA key 0xEB10BBD9BA749318, created: 1999-05-31 -(8) Michael B. Zanussi - 1024 bit DSA key 0x39EE4EAD7BBB1E43, created: 1998-07-16 -Keys 1-8 of 8 for "zanussi". Enter number(s), N)ext, or Q)uit > 3 -``` - -Now we can verify the downloaded sources: -```bash -$ gpg2 --verify linux-4.14.139.tar.sign -gpg: assuming signed data in 'linux-4.14.139.tar' -gpg: Signature made Fr 16 Aug 2019 10:15:17 CEST -gpg: using RSA key 647F28654894E3BD457199BE38DBBDC86092693E -gpg: Good signature from "Greg Kroah-Hartman " [unknown] -gpg: WARNING: This key is not certified with a trusted signature! -gpg: There is no indication that the signature belongs to the owner. -Primary key fingerprint: 647F 2865 4894 E3BD 4571 99BE 38DB BDC8 6092 693E - -$ gpg2 --verify patch-4.14.139-rt66.patch.sign -gpg: assuming signed data in 'patch-4.14.139-rt66.patch' -gpg: Signature made Fr 23 Aug 2019 21:09:20 CEST -gpg: using RSA key 0x0129F38552C38DF1 -gpg: Good signature from "Tom Zanussi " [unknown] -gpg: aka "Tom Zanussi " [unknown] -gpg: aka "Tom Zanussi " [unknown] -gpg: WARNING: This key is not certified with a trusted signature! -gpg: There is no indication that the signature belongs to the owner. -Primary key fingerprint: 5BDF C45C 2ECC 5387 D50C E5EF DE09 8267 78A3 8521 - Subkey fingerprint: ACF8 5F98 16A8 D5F0 96AE 1FD2 0129 F385 52C3 8DF1 -``` - -## Compilation -Before we can compile the sources, we have to extract the tar archive and apply the patch - -```bash -$ tar xf linux-4.14.139.tar -$ cd linux-4.14.139 -linux-4.14.139$ xzcat ../patch-4.14.139-rt66.patch.xz | patch -p1 -``` - -Now to configure your kernel, just type -```bash -linux-4.14.139$ make oldconfig -``` - -This will ask for kernel options. For everything else then the `Preemption Model` use the default -value (just press Enter) or adapt to your preferences. For the preemption model select `Fully Preemptible Kernel`: - -```bash -Preemption Model - 1. No Forced Preemption (Server) (PREEMPT_NONE) -> 2. Voluntary Kernel Preemption (Desktop) (PREEMPT_VOLUNTARY) - 3. Preemptible Kernel (Low-Latency Desktop) (PREEMPT__LL) (NEW) - 4. Preemptible Kernel (Basic RT) (PREEMPT_RTB) (NEW) - 5. Fully Preemptible Kernel (RT) (PREEMPT_RT_FULL) (NEW) -choice[1-5]: 5 -``` - -Now you can build the kernel. This will take some time... - -```bash -linux-4.14.139$ make -j `getconf _NPROCESSORS_ONLN` deb-pkg -``` - -After building, install the `linux-headers` and `linux-image` packages in the parent folder (only -the ones without the `-dbg` in the name) - -```bash -linux-4.14.139$ sudo apt install ../linux-headers-4.14.139-rt66_*.deb ../linux-image-4.14.139-rt66_*.deb -``` - -## Setup user privileges to use real-time scheduling -To be able to schedule threads with user privileges (what the driver will do) you'll have to change -the user's limits by changing `/etc/security/limits.conf` (See [the manpage](https://manpages.ubuntu.com/manpages/bionic/man5/limits.conf.5.html) for details) - -We recommend to setup a group for real-time users instead of writing a fixed username into the config -file: - -```bash -$ sudo groupadd realtime -$ sudo usermod -aG realtime $(whoami) -``` - -Then, make sure `/etc/security/limits.conf` contains -``` -@realtime soft rtprio 99 -@realtime soft priority 99 -@realtime soft memlock 102400 -@realtime hard rtprio 99 -@realtime hard priority 99 -@realtime hard memlock 102400 -``` - -Note: You will have to log out and log back in (Not only close your terminal window) for these -changes to take effect. No need to do this now, as we will reboot later on, anyway. - -## Setup GRUB to always boot the real-time kernel -To make the new kernel the default kernel that the system will boot into every time, you'll have to -change the grub config file inside `/etc/default/grub`. - -Note: This works for ubuntu, but might not be working for other linux systems. It might be necessary -to use another menuentry name there. - -But first, let's find out the name of the entry that we will want to make the default. You can list -all available kernels using - -```bash -$ awk -F\' '/menuentry |submenu / {print $1 $2}' /boot/grub/grub.cfg - -menuentry Ubuntu -submenu Advanced options for Ubuntu - menuentry Ubuntu, with Linux 4.15.0-62-generic - menuentry Ubuntu, with Linux 4.15.0-62-generic (recovery mode) - menuentry Ubuntu, with Linux 4.15.0-60-generic - menuentry Ubuntu, with Linux 4.15.0-60-generic (recovery mode) - menuentry Ubuntu, with Linux 4.15.0-58-generic - menuentry Ubuntu, with Linux 4.15.0-58-generic (recovery mode) - menuentry Ubuntu, with Linux 4.14.139-rt66 - menuentry Ubuntu, with Linux 4.14.139-rt66 (recovery mode) -menuentry Memory test (memtest86+) -menuentry Memory test (memtest86+, serial console 115200) -menuentry Windows 7 (on /dev/sdc2) -menuentry Windows 7 (on /dev/sdc3) -``` - -From the output above, we'll need to generate a string with the pattern `"submenu_name>entry_name"`. In our case this would be - -``` -"Advanced options for Ubuntu>Ubuntu, with Linux 4.14.139-rt66" -``` -**The double quotes and no spaces around the `>` are important!** - -With this, we can setup the default grub entry and then update the grub menu entries. Don't forget this last step! - -```bash -$ sudo sed -i 's/^GRUB_DEFAULT=.*/GRUB_DEFAULT="Advanced options for Ubuntu>Ubuntu, with Linux 4.14.139-rt66"/' /etc/default/grub -$ sudo update-grub -``` - -## Reboot the PC -After having performed the above mentioned steps, reboot the PC. It should boot into the correct -kernel automatically. - -## Check for preemption capabilities -Make sure that the kernel does indeed support real-time scheduling: - -```bash -$ uname -v | cut -d" " -f1-4 -#1 SMP PREEMPT RT -``` - -## Optional: Disable CPU speed scaling -Many modern CPUs support changing their clock frequency dynamically depending on the currently -requested computation resources. In some cases this can lead to small interruptions in execution. -While the real-time scheduled controller thread should be unaffected by this, any external -components such as a visual servoing system might be interrupted for a short period on scaling -changes. - -To check and modify the power saving mode, install cpufrequtils: -```bash -$ sudo apt install cpufrequtils -``` - -Run `cpufreq-info` to check available "governors" and the current CPU Frequency (`current CPU -frequency is XXX MHZ`). In the following we will set the governor to "performance". - -```bash -$ sudo systemctl disable ondemand -$ sudo systemctl enable cpufrequtils -$ sudo sh -c 'echo "GOVERNOR=performance" > /etc/default/cpufrequtils' -$ sudo systemctl daemon-reload && sudo systemctl restart cpufrequtils -``` - -This disables the `ondemand` CPU scaling daemon, creates a `cpufrequtils` config file and restarts -the `cpufrequtils` service. Check with `cpufreq-info`. - -For further information about governors, please see the [kernel -documentation](https://www.kernel.org/doc/Documentation/cpu-freq/governors.txt). diff --git a/ur_robot_driver/doc/rosdoc.yaml b/ur_robot_driver/doc/rosdoc.yaml index d27dced12..113b8c1cb 100644 --- a/ur_robot_driver/doc/rosdoc.yaml +++ b/ur_robot_driver/doc/rosdoc.yaml @@ -1,3 +1,5 @@ +- builder: sphinx + sphinx_root_dir: doc - builder: doxygen name: C++ API output_dir: c++ diff --git a/ur_robot_driver/doc/setup_tool_communication.md b/ur_robot_driver/doc/setup_tool_communication.rst similarity index 55% rename from ur_robot_driver/doc/setup_tool_communication.md rename to ur_robot_driver/doc/setup_tool_communication.rst index d4aeeea71..13f7caf6a 100644 --- a/ur_robot_driver/doc/setup_tool_communication.md +++ b/ur_robot_driver/doc/setup_tool_communication.rst @@ -1,4 +1,8 @@ -# Setting up the tool communication on an e-Series robot +.. _setup-tool-communication: + +Setting up the tool communication on an e-Series robot +====================================================== + The Universal Robots e-Series provides an rs485 based interface at the tool flange that can be used to attach an rs485-based device to the robot's tcp without the need to wire a separate cable along the robot. @@ -9,40 +13,43 @@ to start a device's ROS driver on a remote PC. This document will guide you through installing the URCap needed for this and setting up your ROS launch files to utilize the robot's tool communication. -## Robot setup +Robot setup +----------- + For setting up the robot, please install the **rs485-1.0.urcap** found in the **resources** folder. -Installing a URCap is explained in the [setup guide](install_urcap_e_series.md) for the **external-control** URCap. +Installing a URCap is explained in the :ref:`setup guide ` for the **external-control** URCap. After installing the URCap the robot will expose its tool communication device to the network. -## Setup the ROS side +Setup the ROS side +------------------ + In order to use the tool communication in ROS, simply pass the correct parameters to the bringup launch files: -```bash -$ roslaunch ur_robot_driver ur<3|5|10>e_bringup.launch \ - use_tool_communication:=true \ - tool_voltage:=24 \ # can be 0, 12 or 24 - tool_parity:=0 \ # 0: none, 1: odd, 2: even - tool_baud_rate:=115200 \ - tool_stop_bits:=1 \ - tool_rx_idle_chars:=1.5 \ - tool_tx_idle_chars:=3.5 \ - tool_device_name:=/tmp/ttyUR # remember that your user needs to have the rights to write that file handle -``` - -The `tool_device_name` is an arbitrary name for the device file at which the device will be +.. code-block:: bash + + $ roslaunch ur_robot_driver ur<3|5|10>e_bringup.launch \ + use_tool_communication:=true \ + tool_voltage:=24 # can be 0, 12 or 24 + tool_parity:=0 # 0: none, 1: odd, 2: even + tool_baud_rate:=115200 \ + tool_stop_bits:=1 \ + tool_rx_idle_chars:=1.5 \ + tool_tx_idle_chars:=3.5 \ + tool_device_name:=/tmp/ttyUR # remember that your user needs to have the rights to write that file handle + +The ``tool_device_name`` is an arbitrary name for the device file at which the device will be accessible in the local file system. Most ROS drivers for rs485 devices accept an argument to -specify the device file path. With the example above you could run the `rs485_node` from the package -`imaginary_drivers` using the following command: +specify the device file path. With the example above you could run the ``rs485_node`` from the package +``imaginary_drivers`` using the following command: -```bash -$ rosrun imaginary_drivers rs485_node device:=/tmp/ttyUR +.. code-block:: bash -``` + $ rosrun imaginary_drivers rs485_node device:=/tmp/ttyUR You can basically choose any device name, but your user has to have the correct rights to actually -create a new file handle inside this directory. Therefore, we didn't use the `/dev` folder in the +create a new file handle inside this directory. Therefore, we didn't use the ``/dev`` folder in the example, as users usually don't have the access rights to create new files there. For all the other tool parameters seen above, please refer to the Universal Robots user manual. diff --git a/ur_robot_driver/doc/usage_example.md b/ur_robot_driver/doc/usage_example.rst similarity index 52% rename from ur_robot_driver/doc/usage_example.md rename to ur_robot_driver/doc/usage_example.rst index 95c7a15d2..4cb59733b 100644 --- a/ur_robot_driver/doc/usage_example.md +++ b/ur_robot_driver/doc/usage_example.rst @@ -1,56 +1,72 @@ -# Using the ur_robot_driver -This tutorial should help you getting started to use the `ur_robot_driver` in your application. It +Using the ur_robot_driver +========================= + +This tutorial should help you getting started to use the ``ur_robot_driver`` in your application. It explains how to start the robot driver and how to control the robot using either MoveIt! or a simple python script. -## Prerequisites +Prerequisites +------------- + In order to use the driver you will need a working robot to test with. This can be either a real robot, connected with an ethernet cable to your ROS machine, or it can be a simulated robot using URSim. In this tutorial we assume the following IP settings: -| Machine | IP address | -|-------------|----------------| -| Robot / VM | 192.168.56.101 | -| ROS machine | 192.168.56.1 | +.. list-table:: + :header-rows: 1 + + * - Machine + - IP address + * - Robot / VM + - 192.168.56.101 + * - ROS machine + - 192.168.56.1 + If your setup is different, modify the IP addresses in the following sections accordingly. -Furthermore, we will assume that you already [built](https://github.com/UniversalRobots/Universal_Robots_ROS_Driver#building) the driver successfully and sourced your +Furthermore, we will assume that you already `built `_ the driver successfully and sourced your workspace containing the built driver. -For this tutorial we will also skip using a calibrated robot description. See the [main setup -guide](https://github.com/UniversalRobots/Universal_Robots_ROS_Driver/blob/master/README.md#extract-calibration-information) +For this tutorial we will also skip using a calibrated robot description. See the `main setup +guide `_ on how to do that. -### Real robot +Real robot +^^^^^^^^^^ + If you have a real robot and want to use it for testing, make sure it is connected to the ROS machine on which you'd like to run the driver. We recommend a direct connection between the robot and the control PC so that other network participants will not disturb the network traffic. Make sure that the network is configured, such that both, the robot and the ROS machine are in the same subnet. See the robot's user manual how to setup a static IP address on the robot. -### Using a simulated robot +Using a simulated robot +^^^^^^^^^^^^^^^^^^^^^^^ + For simulation we recommend running URSim in a virtual machine. You can directly download a virtual -machine image containing a preconfigured URSim from Universal Robot's [download -page](https://www.universal-robots.com/download/?filters[]=98759&query=). Please note, that you will -have to select "**Non-Linux Offline simulator**" in order to get the virtual machine. +machine image containing a preconfigured URSim from Universal Robot's `download +page `_. Please note, that you will +have to select "\ **Non-Linux Offline simulator**\ " in order to get the virtual machine. The following will assume that you have VirtualBox installed on your machine. If not, you can -install it by calling `sudo apt install virtualbox` in a terminal. +install it by calling ``sudo apt install virtualbox`` in a terminal. -Once downloaded, extract the archive and open the file `URSim_VIRTUAL-.vbox`. It should +Once downloaded, extract the archive and open the file ``URSim_VIRTUAL-.vbox``. It should right open in VirtualBox. -#### Network setup +Network setup +~~~~~~~~~~~~~ + Next, setup a host network that will be used for the machine. For this, click **File** > **Host Network Manager**. A dialog will open in which you can click the **create** button which will add an entry to the list. It should automatically get the static IP -address `192.168.56.1`. If not, set it up manually in the dialog. Once done, you can close the +address ``192.168.56.1``. If not, set it up manually in the dialog. Once done, you can close the dialog again to go back to your VirtualBox main window. There, select the URSim_VIRTUAL... machine and click on **Settings**. Select the **Network** point in the list on the left and activate at least one network adapter, setting the **Attached to** dropdown menu to **Host-only Adapter**. @@ -62,7 +78,9 @@ easiest. If you consider using another networking mode, make sure that the virtu reachable via its own IP address from the host machine and that it can reach the host machine as well. -#### Starting a robot +Starting a robot +~~~~~~~~~~~~~~~~ + To start a simulated robot, select your URSim virtual machine and click on the **Start button**. The machine should boot and finally present a desktop with a shortcut for every robot model. Simply double click on the robot model that you want to use for testing. No further network setup for the @@ -70,7 +88,9 @@ simulated robot is necessary. In this tutorial we will assume that you start a UR5 robot from a URSim version > 5.8. -## Starting the driver and visualizing the robot in RViz +Starting the driver and visualizing the robot in RViz +----------------------------------------------------- + In order to start the driver it is not strictly necessary to install the **External Control** URCap. If you only want to connect to the robot and visualize the robot in RViz, nothing has to be changed on the robot. You should, however, make sure that is is running, as otherwise no joint data will be @@ -78,63 +98,71 @@ sent. To start the driver run the following command in a terminal: -``` -roslaunch ur_robot_driver ur5e_bringup.launch robot_ip:=192.168.56.101 -``` +.. code-block:: bash + + roslaunch ur_robot_driver ur5e_bringup.launch robot_ip:=192.168.56.101 In another terminal, run -``` -roslaunch ur_robot_driver example_rviz.launch -``` +.. code-block:: bash + + roslaunch ur_robot_driver example_rviz.launch This should open up an RViz window showing the robot. Try moving around the robot's joints using the teach panel and watch how it also moves inside ROS. -![RViz window](resources/usage_example/rviz.png "RViz window showing a UR5 robot") -## Control the robot +.. image:: resources/usage_example/rviz.png + :target: resources/usage_example/rviz.png + :alt: RViz window + + +Control the robot +----------------- + For controlling the robot you'll need a special program running on the robot that will interpret and execute the commands coming from ROS. This can be either done by installing the **External Control** URCap as explained -[here](https://github.com/UniversalRobots/Universal_Robots_ROS_Driver/blob/master/README.md#setting-up-a-ur-robot-for-ur_robot_driver) -or by using the [headless -mode](https://github.com/UniversalRobots/Universal_Robots_ROS_Driver/blob/master/ur_robot_driver/README.md#headless-mode). +`here `_ +or by using the `headless +mode `_. We assume the use of the URCap in the following. Before any control of the robot can happen, a program containing the **External Control** program -node must be running on the robot. You should see the output `Robot ready to receive control -commands.` in the terminal where you launched the driver. See [this troubleshooting -entry](https://github.com/UniversalRobots/Universal_Robots_ROS_Driver/blob/master/README.md#i-started-everything-but-i-cannot-control-the-robot) +node must be running on the robot. You should see the output ``Robot ready to receive control +commands.`` in the terminal where you launched the driver. See `this troubleshooting +entry `_ if you experience problems in this step. -### Control the robot using the `test_move` script +Control the robot using the ``test_move`` script +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Once you've setup the robot for getting controlled by ROS, you can move it around using the -[`test_move`](https://github.com/UniversalRobots/Universal_Robots_ROS_Driver/blob/master/ur_robot_driver/scripts/test_move) script. +`test_move `_ script. Start the driver and an RViz window as before. Then, in a third terminal run -``` -rosrun ur_robot_driver test_move -``` +.. code-block:: bash + + rosrun ur_robot_driver test_move This script will guide you through the different trajectory controllers available. For informations -about the different controllers, please see [TODO: Change once merged #423](https://github.com/UniversalRobots/Universal_Robots_ROS_Driver/pull/423). +about the different controllers, please see :ref:`the controller documentation `. It will first ask about the controller to be used: -``` -Available trajectory controllers: -0 (joint-based): scaled_pos_joint_traj_controller -1 (joint-based): scaled_vel_joint_traj_controller -2 (joint-based): pos_joint_traj_controller -3 (joint-based): vel_joint_traj_controller -4 (joint-based): forward_joint_traj_controller -5 (Cartesian): pose_based_cartesian_traj_controller -6 (Cartesian): joint_based_cartesian_traj_controller -7 (Cartesian): forward_cartesian_traj_controller -Please choose a controller by entering its number (Enter '0' if you are unsure / don't care): 0 -``` +.. code-block:: text + + Available trajectory controllers: + 0 (joint-based): scaled_pos_joint_traj_controller + 1 (joint-based): scaled_vel_joint_traj_controller + 2 (joint-based): pos_joint_traj_controller + 3 (joint-based): vel_joint_traj_controller + 4 (joint-based): forward_joint_traj_controller + 5 (Cartesian): pose_based_cartesian_traj_controller + 6 (Cartesian): joint_based_cartesian_traj_controller + 7 (Cartesian): forward_cartesian_traj_controller + Please choose a controller by entering its number (Enter '0' if you are unsure / don't care): 0 After that, you'll have to confirm that the motions the robot is about to make, can safely be executed the way your robot is mounted. If you're running a simulated robot, you can confirm this @@ -142,57 +170,80 @@ without thinking twice. However, if a real robot is connected, please make sure actually free of any obstacles inside the space where the motion is taking place. See the images below for a visualization of the setpoints: -**Joint-based motions**: (The cable leaving the base to the back on an e-Series robot) -![joint_based motion 1](resources/usage_example/joint_based_motion.png "setpoints of joint-based motion") +**Joint-based motions**\ : (The cable leaving the base to the back on an e-Series robot) + +.. image:: resources/usage_example/joint_based_motion.png + :target: resources/usage_example/joint_based_motion.png + :alt: joint_based motion 1 + -**Cartesian motions**: (The cable leaving the base to the back on an e-Series robot) +**Cartesian motions**\ : (The cable leaving the base to the back on an e-Series robot) **Please note: Depending on your starting configuration there might also be a valid elbow-down configuration for each of the poses!** -![cartesian motion 1](resources/usage_example/cartesian_motion.png "Setpoints of a Cartesian motion") + +.. image:: resources/usage_example/cartesian_motion.png + :target: resources/usage_example/cartesian_motion.png + :alt: cartesian motion 1 + You can play around by changing the trajectories inside the python code, if you like. You can also setup velocities in each waypoint to get a smooth motion through all waypoints. -### Control the robot using MoveIt! +Control the robot using MoveIt! +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + For controlling the robot using MoveIt! start the following three launch files (Each in a separate terminal window): -``` -roslaunch ur_robot_driver ur5e_bringup.launch robot_ip:=192.168.56.101 -``` +.. code-block:: bash + + roslaunch ur_robot_driver ur5e_bringup.launch robot_ip:=192.168.56.101 -``` -roslaunch ur5e_moveit_config ur5e_moveit_planning_execution.launch -``` +.. code-block:: bash -``` -roslaunch ur5e_moveit_config moveit_rviz.launch rviz_config:=$(rospack find ur5e_moveit_config)/launch/moveit.rviz -``` + roslaunch ur5e_moveit_config ur5e_moveit_planning_execution.launch + +.. code-block:: bash + + roslaunch ur5e_moveit_config moveit_rviz.launch rviz_config:=$(rospack find ur5e_moveit_config)/launch/moveit.rviz You should get an RViz window showing the robot overlayed with an orange version of the robot: -![MoveIt RViz window](resources/usage_example/moveit_1.png "Moveit RViz window after startup") + +.. image:: resources/usage_example/moveit_1.png + :target: resources/usage_example/moveit_1.png + :alt: MoveIt RViz window + You can change the tcp target by dragging around the blue ball. The orange robot will show the configuration used to reach the target pose. -![MoveIt RViz window planning](resources/usage_example/moveit_2.png "Moveit RViz window showing planning result") +.. image:: resources/usage_example/moveit_2.png + :target: resources/usage_example/moveit_2.png + :alt: MoveIt RViz window planning -By clicking on the `Plan` button in the left panel a path from the current pose to the target pose + +By clicking on the ``Plan`` button in the left panel a path from the current pose to the target pose is calculated. On success, it gets animated using a semi-transparent version of the robot: -![MoveIt RViz window path](resources/usage_example/moveit_3.png "Moveit RViz window showing planned path") +.. image:: resources/usage_example/moveit_3.png + :target: resources/usage_example/moveit_3.png + :alt: MoveIt RViz window path + + +By clicking on the ``Execute`` button in the left panel the robot executes the planned motion: -By clicking on the `Execute` button in the left panel the robot executes the planned motion: +.. image:: resources/usage_example/moveit_4.png + :target: resources/usage_example/moveit_4.png + :alt: MoveIt RViz window execution -![MoveIt RViz window execution](resources/usage_example/moveit_4.png "Moveit RViz window showing planned path execution") -In a real-world application you would not use the `ur5e_moveit_config` package but create your own +In a real-world application you would not use the ``ur5e_moveit_config`` package but create your own moveit configuration matching your actual workcell with all obstacles and sensors. See the -[setup_assistant -tutorial](https://ros-planning.github.io/moveit_tutorials/doc/setup_assistant/setup_assistant_tutorial.html) +`setup_assistant +tutorial `_ for more information on that. From fdc31c000fcf12bb9f810776f037fcd03280047c Mon Sep 17 00:00:00 2001 From: Felix Exner Date: Thu, 10 Mar 2022 14:54:16 +0100 Subject: [PATCH 2/2] use percentage image with for e-series images --- .../doc/installation/install_urcap_e_series.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/ur_robot_driver/doc/installation/install_urcap_e_series.rst b/ur_robot_driver/doc/installation/install_urcap_e_series.rst index c0a7bc1ec..a833390b2 100644 --- a/ur_robot_driver/doc/installation/install_urcap_e_series.rst +++ b/ur_robot_driver/doc/installation/install_urcap_e_series.rst @@ -15,7 +15,7 @@ On the welcome screen click on the hamburger menu in the top-right corner and se .. image:: initial_setup_images/es_01_welcome.png - :width: 800 + :width: 100% :alt: Welcome screen of an e-Series robot @@ -26,7 +26,7 @@ the **externalcontrol-1.0.5.urcap** file and click *open*. Your URCaps view shou now. .. image:: initial_setup_images/es_05_urcaps_installed.png - :width: 800 + :width: 100% :alt: URCaps screen with installed urcaps @@ -35,7 +35,7 @@ For this select *Program Robot* on the welcome screen, select the *Installation* **External Control** from the list. .. image:: initial_setup_images/es_07_installation_excontrol.png - :width: 800 + :width: 100% :alt: Installation screen of URCaps @@ -45,7 +45,7 @@ connection with each other to minimize network disturbances. The custom port sho untouched for now. .. image:: initial_setup_images/es_10_prog_structure_urcaps.png - :width: 800 + :width: 100% :alt: Insert the external control node @@ -53,7 +53,7 @@ To use the new URCaps, create a new program and insert the **External Control** the program tree .. image:: initial_setup_images/es_11_program_view_excontrol.png - :width: 800 + :width: 100% :alt: Program view of external control