Merge branch 'update_documentation' into release

README.md

@@ -74,59 +74,12 @@ For using the *ur_rtde_driver* with a real robot you need to install the
 **Note**: For installing this URCap a minimal PolyScope version of 3.7 or 5.1 (in case of eSeries) is
 necessary.
 
-To install it you first have to copy it to the robot's **programs** folder which can be done either
+For installing the necessary URCap and creating a program, please see the individual tutorials on
-via scp or using a USB stick. The installation process is similar for CB3 and eSeries robots and
+how to [setup a CB3 robot](ur_rtde_driver/doc/install_urcap_cb3.md) or how to [setup an e-Series
-will be shown side-to-side in this guide.
+robot](ur_rtde_driver/doc/install_urcap_e_series.md).
 
-<tr>
+To setup the tool communication on an e-Series robot, please consider the [tool communication setup
-<td> <img src="ur_rtde_driver/doc/initial_setup_images/cb3_01_welcome.png" alt="Welcome screen of CB3" style="width: 45%;"/> </td>
+guide](ur_rtde_driver/doc/setup_tool_communication.md).
-<td> <img src="ur_rtde_driver/doc/initial_setup_images/es_01_welcome.png" alt="Welcome screen of eSeries" style="width: 45%;"/> </td>
-</tr>
-
-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.
-
-<tr>
-<td> <img src="ur_rtde_driver/doc/initial_setup_images/cb3_05_urcaps_installed.png" alt="URCaps screen with installed
-urcaps" style="width: 45%;"/> </td>
-<td> <img src="ur_rtde_driver/doc/initial_setup_images/es_05_urcaps_installed.png" alt="URCaps screen with installed
-urcaps" style="width: 45%;"/> </td>
-</tr>
-
-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.
-
-<tr>
-<td> <img src="ur_rtde_driver/doc/initial_setup_images/cb3_07_installation_excontrol.png" alt="Installation screen of URCaps" style="width: 45%;"/> </td>
-<td> <img src="ur_rtde_driver/doc/initial_setup_images/es_07_installation_excontrol.png" alt="Installation screen of URCaps" style="width: 45%;"/> </td>
-</tr>
-
-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:
-
-<tr>
-<td> <img src="ur_rtde_driver/doc/initial_setup_images/cb3_10_prog_structure_urcaps.png" alt="Insert the external control node" style="width: 45%;"/> </td>
-<td> <img src="ur_rtde_driver/doc/initial_setup_images/es_10_prog_structure_urcaps.png" alt="Insert the external control node" style="width: 45%;"/> </td>
-</tr>
-
-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.
-
-<tr>
-<td> <img src="ur_rtde_driver/doc/initial_setup_images/cb3_11_program_view_excontrol.png" alt="Program view of external control" style="width: 45%;"/> </td>
-<td> <img src="ur_rtde_driver/doc/initial_setup_images/es_11_program_view_excontrol.png" alt="Program view of external control" style="width: 45%;"/> </td>
-</tr>
 
 ### Prepare the ROS PC
 For using the driver make sure it is installed (either by the debian package or built from source
@@ -178,15 +131,24 @@ To create a new package, go to your catkin_workspace's src folder and call
 
 It is recommended to adapt the new package's *package.xml* with a meaningful description.
 
-#### Start the robot driver
+#### Quick start
+Once the driver is built and the **externalcontrol** URCap is installed on the robot, you are good
+to go ahead starting the driver. (**Note**: We do recommend, though, to calibrate your robot first.)
+
 To actually start the robot driver use one of the existing launchfiles
 
     $ roslaunch ur_rtde_driver <robot_type>_bringup.launch robot_ip:=192.168.56.101 \
+
+where **<robot_type>** 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 you calibrated your robot before, pass that calibration to the launch file:
+
+    $ roslaunch ur_rtde_driver <robot_type>_bringup.launch robot_ip:=192.168.56.101 \
     kinematics_config:=$(rospack find ur_calibration)/etc/ur10_example_calibration.yaml
 
-where **<robot_type>** is one of *ur3, ur5, ur10, ur3e, ur5e, ur10e*. Note that in this example we
+If the parameters in that file don't match the ones reported from the robot, the driver will output
-load the calibration parameters for the robot "ur10_example". If the parameters in that file don't
+an error during startup, but will remain usable.
-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.
 
@@ -195,16 +157,14 @@ execute it. From that moment on the robot is fully functional. You can make use
 function or even stop the program. Simply press the play button again and the ROS driver will
 reconnect.
 
-#### Use the action server
+To control the robot using ROS, use the action server on
-After starting up the robot as described in the last section a scaled position based trajectory
-controller is started. It's action-server is located at
 
 ```bash
 /scaled_pos_traj_controller/follow_joint_trajectory
 ```
 
-Use this with any client interface such as MoveIt! or simply the joint_trajectory_controller rqt
+Use this with any client interface such as [MoveIt!](https://moveit.ros.org/) or simply the
-gui:
+`rqt_joint_trajectory_controller` gui:
 
 ```
 rosrun rqt_joint_trajectory_controller rqt_joint_trajectory_controller

ur_rtde_driver/doc/features.md

@@ -0,0 +1,34 @@
+# Feature comparison and roadmap
+
+| Feature                                               | ur_modern_driver | this_driver           |
+| ---                                                   | ---              | ---                   |
+| position-based control                                | yes              | yes                   |
+| scaled position-based control                         | -                | yes                   |
+| velocity-based control                                | yes              | planned               |
+| reporting of tcp wrench                               | yes              | yes                   |
+| reporting of tcp wrench in tcp link                   | -                | yes                   |
+| pausing of programs                                   | -                | yes                   |
+| continue trajectories after EM-Stop resume            | -                | yes                   |
+| continue trajectories after protective stop           | -                | yes                   |
+| panel interaction in between possible                 | no<sup>1</sup>   | yes                   |
+| get and set IO states                                 | yes              | yes               |
+| use tool communication on e-series                    | -                | yes                   |
+| use the driver without a teach pendant necessary      | -                | planned               |
+| support of CB2 robots                                 | yes              | -                     |
+| trajectory extrapolation on robot on missing packages | no<sup>2</sup>   | yes                   |
+| use ROS as drop-in for TP-programs                    | -                | yes   |
+| extract calibration from robot                        | -                | yes                   |
+| send custom script commands to robot                  | yes              | yes               |
+| ROS 2 support                                         | ?                | (planned)<sup>3</sup> |
+| Reconnect on a disconnected robot                     | yes              | yes           |
+
+<sup>1</sup> Depending on the mode the driver is running the panel won't react or using the panel
+will stop the program without notifying the ROS user.
+
+<sup>2</sup> In velocity mode this is implicitly given.
+
+<sup>3</sup> There is no specific plan to do this inside of the first driver development. However,
+it is structured in a way so that a ROS2 driver should be developed as easy as possible by keeping
+as much as possible in a ros-independent library.
+
+

ur_rtde_driver/doc/install_urcap_cb3.md

@@ -0,0 +1,44 @@
+# Installing a URCap on a CB3 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.
+
+**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.
+
+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)
+
+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](initial_setup_images/cb3_05_urcaps_installed.png)
+
+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)
+
+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)
+
+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)
+
+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
+this driver.

ur_rtde_driver/doc/install_urcap_e_series.md

@@ -0,0 +1,43 @@
+# Installing a URCap on a s-Series 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.
+
+**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)
+
+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](initial_setup_images/es_05_urcaps_installed.png)
+
+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)
+
+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)
+
+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)
+
+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
+this driver.

ur_rtde_driver/doc/setup_tool_communication.md

@@ -0,0 +1,48 @@
+# 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.
+
+This driver enables forwarding this tool communication interface to an external machine for example
+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
+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.
+
+After installing the URCap the robot will expose its tool communication device to the network.
+
+## 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_rtde_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:
+
+```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
+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.