Merge pull request #179 from UniversalRobots/improve_docs

Improve documentation

Author: Felix Exner

README.md

@@ -246,3 +246,35 @@ This is a known issue and unfortunately we don't have a solution for this. The N
 seems to not compile with every kernel. We recommend to use a multi-machine ROS setup in this
 situation where a realtime-system is running the robot driver and a separate machine is performing
 the computations requiring the graphics card.
+
+### Why can't the driver use the extracted calibration info on startup?
+This is mainly because parameters are loaded onto the parameter server before any nodes are started.
+
+The `robot_description` concept inside ROS is not designed to be changed while a system is running.
+Consumers of the urdf/`robot_description` (in terms of other ROS nodes) will not update the model
+they have been loading initially. While technically the description could be altered during runtime
+and any node that is started AFTER the description was updated, this would lead to an inconsistent
+state inside the system. In other words: It's not the driver that needs/benefits from this
+calibrated urdf, it's the rest of the ROS application.
+
+Additionally: If the calibration doesn't match the expected one, there's a reason for that and it
+should better be explicitly handled by a human. Having to run the calibration
+extraction/transformation as a separate step makes this possible and doesn't hide this step from the
+end user.
+
+### Can this driver be used inside a combined hardware interface?
+Yes, this is possible. However, if used inside a [combined HW
+interface](http://wiki.ros.org/combined_robot_hw) we recommend to enable [non-blocking read
+functinality](https://github.com/UniversalRobots/Universal_Robots_ROS_Driver/blob/master/ur_robot_driver/doc/ROS_INTERFACE.md#non_blocking_read-default-false).
+
+### I sent raw script code to the robot but it is not executed
+On the e-Series the robot has to be in [remote control
+mode](ur-robot-driver/README.md#remote-control-mode) to accept script code from an external source.
+This has to be switched from the Teach-Pendant.
+
+### Using the dashboard doesn't work
+On the e-Series the robot has to be in [remote control
+mode](ur-robot-driver/README.md#remote-control-mode) to accept certain calls on the dashboard server.
+See [Available dashboard
+commands](https://www.universal-robots.com/articles/ur-articles/dashboard-server-cb-series-port-29999/)
+for details.

ur_robot_driver/README.md

@@ -55,3 +55,40 @@ Therefor, it can be used with all position-based controllers available in ROS-Co
 recommend using the controllers from the `ur_controllers` package. See it's
 [documentation](../ur_controllers/README.md) for details. **Note: Speed scaling support will only be
 available using the controllers from `ur_controllers`**
+
+## A note about modes
+The term **mode** is used in different meanings inside this driver.
+
+### Remote control mode
+On the e-series the robot itself can operate in different command modes: It can be either in **local control
+mode** where the teach pendant is the single point of command or in **remote control mode**, where
+motions from the TP, starting & loading programs from the TP activating the freedrive mode are
+blocked. Note that the **remote control mode** has to be explicitly enabled in the robot's settings
+under **Settings** -> **System** -> **Remote Control**. See the robot's manual for details.
+
+The **remote control mode** is needed for many aspects of this driver such as
+ * headless mode (see below)
+ * sending script code to the robot
+ * many dashboard functionalities such as
+   * restarting the robot after protective / EM-Stop
+   * powering on the robot and do brake release
+   * loading and starting programs
+ * the `set_mode` action, as it uses the dashboard calls mentioned above
+
+### Headless mode
+Inside this driver, there's the **headless** mode, which can be either enabled or not. When the
+[headless mode](./doc/ROS_INTERFACE.md#headless_mode-default-false) is activated, required script
+code for external control will be sent to the robot directly when the driver starts. As soon as
+other script code is sent to the robot either by sending it directly through this driver or by
+pressing any motion-related button on the teach pendant, the script will be overwritten by this
+action and has to be restarted by using the
+[resend_robot_program](./doc/ROS_INTERFACE.md#resend_robot_program-std_srvstrigger) service. If this
+is necessary, you will see the output `Connection to robot dropped, waiting for new connection.`
+from the driver. Note that pressing "play" on the TP won't start the external control again, but
+whatever program is currently loaded on the controller. This mode doesn't require the "External
+Control" URCap being installed on the robot as the program is sent to the robot directly. However,
+we recommend to use the non-headless mode and leverage the `set_mode` action to start program
+execution without the teach pendant. The **headless** mode might be removed in future releases.
+
+**Note for the e-Series:** In order to leverage the **headless** mode on the e-Series the robot must
+be in **remote_control_mode** as explained above.