From 4c1da599701ab3409a0132883992d94855f1b1b8 Mon Sep 17 00:00:00 2001 From: Felix Mauch Date: Wed, 19 Jun 2019 16:18:22 +0200 Subject: [PATCH] Move all relevant documentation to the entry README --- README.md | 169 +++++++++++++++++++++++++++- ur_rtde_driver/README.md | 46 +------- ur_rtde_driver/doc/initial_setup.md | 115 ------------------- 3 files changed, 169 insertions(+), 161 deletions(-) delete mode 100644 ur_rtde_driver/doc/initial_setup.md diff --git a/README.md b/README.md index de27f4c..a7e7298 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,24 @@ # UR_RTDE_Driver +This driver is forked from the [ur_modern_driver](https://github.com/ros-industrial/ur_modern_driver). + +It works for all CB3 and eSeries robots and uses the RTDE interface for communication, whenever possible. + +## Features + * **Factory calibration** of the robot inside ROS to reach Cartesian + targets precisely. + * **Realtime-enabled** communication structure to robustly cope with the 2ms cycle time of the eSeries. To use this, compile and run it on a kernel with the `PREEMPT_RT` patch enabled. (TODO: Write tutorial on how to compile a realtime kernel for Ubuntu) + * Transparent **integration of the teach-pendant**. Using the URCaps system, a program is running + on the robot that handles control commands sent from ROS side. With this, the robot can be + **paused**, **stopped** and **resumed** without restarting the ROS driver. + This will in the future also enable, the usage of ROS-components as a part of a more complex UR-program + on the teach pendant. This is currently not yet supported, as we are still missing to exit + control from ROS side. Expect this to come in future releases. + * Use the robot's **speed-scaling**. When speed scaling is active due to safety constraints or the + speed slider is used, this gets correctly handled on the ROS side, as well slowing down + trajectory execution accordingly. **Note**: Due to the speed scaling interface, other controllers + than the scaled controllers provided, currently cannot be used. We plan to change this in + upcoming releases. + This repository contains the new **ur_rtde_driver** and a couple of helper packages, such as: * **controller_stopper**: A small external tool that stops and restarts ros-controllers based on @@ -10,5 +30,150 @@ This repository contains the new **ur_rtde_driver** and a couple of helper packa controllers. * **ur_rtde_driver**: The actual driver package. -Please see the individual packages for further information. Especially the [README of the -ur_rtde_driver](ur_rtde_driver/README.md) serves as an entry point to get everything running. +## Building + +```bash +# source global ros +$ source /opt/ros//setup.bash +# create a catkin workspace +$ mkdir -p catkin_ws/src && cd catkin_ws +$ catkin_make +$ cd src +# clone the driver +$ git clone +# clone fork of the description to use the calibration feature +$ git clone -b calibration_devel https://github.com/fmauch/universal_robot.git +# install dependencies +$ rosdep install --from-path . -y --ignore-src +# build the driver +$ cd .. +$ catkin_make +# source the workspace +$ source devel/setup.bash +``` + +## Setting up a UR robot for ur_rtde_driver +### Prepare the robot +For using the *ur_rtde_driver* with a real robot you need to install the +**externalcontrol-1.0.urcap** which can be found inside the **resources** folder of this driver. + +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. The installation process is similar for CB3 and eSeries robots and +will be shown side-to-side in this guide. + + + Welcome screen of CB3 + Welcome screen of eSeries + + +On the welcome screen select *Setup Robot* and then *URCaps* to enter the URCaps installation screen +(For eSeries click on the hamburger menu in the top-right corner to get to the setup menu). 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 the +**externalcontrol-1.0.urcap** file and click *open*. Your URCaps view should now show the +**External Control** in the list of active URCaps and a notification to restart the robot. Do that +now. + + + URCaps screen with installed +urcaps + 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 + 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. + +To use the new URCaps, create a new program and insert the **External Control** program node into +the program tree: + + + Insert the external control node + Insert the external control node + + +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. + + + Program view of external control + Program view of external control + + +### 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 endeffector positions might be off in the magnitude of centimeters. + +For this, there exists a helper script: + + $ roslaunch ur_calibration calibration_correction.launch \ + robot_ip:=192.168.56.101 \ + robot_name:=ur10_example \ + output_package_name:=ur_calibration \ + subfolder_name:=etc + +As soon as you see the output + + [ INFO] [1560953586.352160902]: Calibration correction done + +you can exit the roslaunch by bressing `CTRL+C`. + +For the parameter **robot_ip** insert the ip on which the ROS pc can reach the robot. The +**robot_name** is an arbitrary name you can give to the robot. It is recommended, to choose a unique +name that can be easily matched to the physical robot. + +The script will then extract the calibration information from the robot and convert it to a yaml +syntax that can be used by the robot_description. + +The resulting yaml file is stored in the package specified in the **output_package_name** parameter +inside the folder **subfolder_name** with the name **robot_name***_calibration.yaml*. The parameter +**subfolder_name** is optional and defaults to *etc* if not given. + +In the example above, we use the **ur_calibration** package from this repository. This won't work, +if you use a binary installation of this driver. In that case please create an own ROS package as +described below. + +**Note:** You'll have to provide the name of an existing package. It is recommended to have a +package storing all calibrations of all UR robots inside your organization. This way, the extraction +as described in this package has only to be performed once and the calibration can be reused by +other users. +To create a new package, go to your catkin_workspace's src folder and call + + catkin_create_pkg my_calibrations + +It is recommended to adapt the new package's *package.xml* with a meaningful description. + +#### Start the robot driver +To actually start the robot driver use one of the existing launchfiles + + $ roslaunch ur_rtde_driver _bringup.launch robot_ip:=192.168.56.101 \ + kinematics_config:=$(rospack find ur_calibrations)/etc/ur10_example_calibration.yaml + +where **** is one of *ur3, ur5, ur10, ur3e, ur5e, ur10e*. Note that in this example we +load the calibration parameters for the robot "ur10_example". If the parameters in that file don't +match the ones reported from the robot, the driver will output an error during startup. + +For more information on the launchfile's parameters see its own documentation. + +Once the robot driver is started, load the previously generated program on the robot panel and +execute it. From that moment on the robot is fully functional. You can make use of the pause +function or even stop the program. Simply press the play button again and the ROS driver will +reconnect. diff --git a/ur_rtde_driver/README.md b/ur_rtde_driver/README.md index c3efad3..495f298 100644 --- a/ur_rtde_driver/README.md +++ b/ur_rtde_driver/README.md @@ -1,46 +1,4 @@ # ur_rtde_driver -This driver is forked from the [ur_modern_driver](https://github.com/ros-industrial/ur_modern_driver). - -It works for all CB3 and eSeries robots and uses the RTDE interface for communication, whenever possible. - -## Features - * **Factory calibration** of the robot inside ROS to reach Cartesian - targets precisely. - * **Realtime-enabled** communication structure to robustly cope with the 2ms cycle time of the eSeries. To use this, compile and run it on a kernel with the `PREEMPT_RT` patch enabled. (TODO: Write tutorial on how to compile a realtime kernel for Ubuntu) - * Transparent **integration of the teach-pendant**. Using the URCaps system, a program is running - on the robot that handles control commands sent from ROS side. With this, the robot can be - **paused**, **stopped** and **resumed** without restarting the ROS driver. - This will in the future also enable, the usage of ROS-components as a part of a more complex UR-program - on the teach pendant. This is currently not yet supported, as we are still missing to exit - control from ROS side. Expect this to come in future releases. - * Use the robot's **speed-scaling**. When speed scaling is active due to safety constraints or the - speed slider is used, this gets correctly handled on the ROS side, as well slowing down - trajectory execution accordingly. **Note**: Due to the speed scaling interface, other controllers - than the scaled controllers provided, currently cannot be used. We plan to change this in - upcoming releases. - -## Building - -```bash -# source global ros -$ source /opt/ros//setup.bash -# create a catkin workspace -$ mkdir -p catkin_ws/src && cd catkin_ws -$ catkin_make -$ cd src -# clone the driver -$ git clone -# clone fork of the description to use the calibration feature -$ git clone -b calibration_devel https://github.com/fmauch/universal_robot.git -# install dependencies -$ rosdep install --from-path . -y --ignore-src -# build the driver -$ cd .. -$ catkin_make -# source the workspace -$ source devel/setup.bash -``` - -## Initial robot setup -To setup a new robot with this driver, please see the [initial setup tutorial](doc/initial_setup.md) +The actual driver package. For more information, please see the README in the top-level folder of +this repository. diff --git a/ur_rtde_driver/doc/initial_setup.md b/ur_rtde_driver/doc/initial_setup.md deleted file mode 100644 index 58e3d9c..0000000 --- a/ur_rtde_driver/doc/initial_setup.md +++ /dev/null @@ -1,115 +0,0 @@ -# Setting up a UR robot for ur_rtde_driver -## Prepare the robot -For using the *ur_rtde_driver* with a real robot you need to install the -**externalcontrol-1.0.urcap** which can be found inside the **resources** folder of this driver. - -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. The installation process is similar for CB3 and eSeries robots and -will be shown side-to-side in this guide. - - - Welcome screen of CB3 - Welcome screen of eSeries - - -On the welcome screen select *Setup Robot* and then *URCaps* to enter the URCaps installation screen -(For eSeries click on the hamburger menu in the top-right corner to get to the setup menu). 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 the -**externalcontrol-1.0.urcap** file and click *open*. Your URCaps view should now show the -**External Control** in the list of active URCaps and a notification to restart the robot. Do that -now. - - - URCaps screen with installed -urcaps - 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 - 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. - -To use the new URCaps, create a new program and insert the **External Control** program node into -the program tree: - - - Insert the external control node - Insert the external control node - - -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. - - - Program view of external control - Program view of external control - - -## 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 endeffector positions might be off in the magnitude of centimeters. - -For this, there exists a helper script: - - $ rosrun ur_calibration calibration_correction \ - _robot_ip:=192.168.56.101 \ - _robot_name:=ur10_example \ - _output_package_name:=my_calibrations \ - _subfolder_name:=etc - -For the parameter **robot_ip** insert the ip on which the ROS pc can reach the robot. The -**robot_name** is an arbitrary name you can give to the robot. It is recommended, to choose a unique -name that can be easily matched to the physical robot. - -The script will then extract the calibration information from the robot and convert it to a yaml -syntax that can be used by the robot_description. - -The resulting yaml file is stored in the package specified in the **output_package_name** parameter -inside the folder **subfolder_name** with the name **robot_name***_calibration.yaml*. The parameter -**subfolder_name** is optional and defaults to *etc* if not given. - -**Note:** You'll have to provide the name of an existing package. It is recommended to have a -package storing all calibrations of all UR robots inside your organization. This way, the extraction -as described in this package has only to be performed once and the calibration can be reused by -other users. -To create a new package, go to your catkin_workspace's src folder and call - - catkin_create_pkg my_calibrations - -It is recommended to adapt the new package's *package.xml* with a meaningful description. - -### Start the robot driver -To actually start the robot driver use one of the existing launchfiles - - $ roslaunch ur_rtde_driver _bringup.launch robot_ip:=192.168.56.101 \ - kinematics_config:=$(rospack find my_calibrations)/etc/ur10_example_calibration.yaml - -where **** is one of *ur3, ur5, ur10, ur3e, ur5e, ur10e*. Note that in this example we -load the calibration parameters for the robot "ur10_example". If the parameters in that file don't -match the ones reported from the robot, the driver will output an error during startup. - -For more information on the launchfile's parameters see its own documentation. - -Once the robot driver is started, load the previously generated program on the robot panel and -execute it. From that moment on the robot is fully functional. You can make use of the pause -function or even stop the program. Simply press the play button again and the ROS driver will -reconnect.