Update and thin down README (#494)

Felix Exner (fexner) · web-flow · commit d7743035a1c1 · 2022-11-23T16:34:34.000+01:00
Avoid duplication between README and package doc.

* Updated documentation about fake_hardware and MoveIt!
* Remove trailing WS
* [documentation] do not suggest -r for rosdep install
* Added note about tool0_controller to docs.
* Add additional part about calibration to toplevel README.
* Added note about sourcing ROS in build instructions
diff --git a/README.md b/README.md
@@ -117,7 +117,8 @@ Check also [presentations and videos](ur_robot_driver/doc/resources/README.md) a
 
 **NOTE**: There are three build stages checking current and future compatibility of the driver.
 
-1. Binary builds - against released packages (main and testing) in ROS distributions. Shows that direct local build is possible.
+1. Binary builds - against released packages (main and testing) in ROS distributions. Shows that
+   direct local build is possible and is the most relevant workflow for users.
 
    Uses repos file: `src/Universal_Robots_ROS2_Driver/Universal_Robots_ROS2_Driver-not-released.<ros-distro>.repos`
 
@@ -143,35 +144,85 @@ Deprecation: The `ur_bringup` package is deprecated and will be removed from Iro
 
 ## Getting Started
 
-1. [Install ROS2 Rolling](https://docs.ros.org/en/rolling/Installation/Ubuntu-Install-Debians.html).
+For getting started, you'll basically need three steps:
+
+1. **Install the driver** (see below). You can either install this driver from binary packages or build it from source. We recommend a
+binary package installation unless you want to join development and submit changes.
+
+2. **Start & Setup the robot**. Once you've installed the driver, [setup the
+robot](https://docs.ros.org/en/ros2_packages/rolling/api/ur_robot_driver/installation/robot_setup.html)
+
+Please do this step carefully and extract the calibration as explained
+[here](https://docs.ros.org/en/ros2_packages/rolling/api/ur_robot_driver/installation/robot_setup.html#extract-calibration-information).
+Otherwise the TCP's pose will not be correct inside the ROS ecosystem.
+
+If no real robot is required, you can [use a simulated
+robot](https://docs.ros.org/en/ros2_packages/rolling/api/ur_robot_driver/usage.html#usage-with-official-ur-simulator)
+that will behave almost exactly like the real robot.
+
+
+3. **Start the driver**. See the [usage
+   documentation](https://docs.ros.org/en/ros2_packages/rolling/api/ur_robot_driver/usage.html) for
+   details.
+
+### Install from binary packages
+1. [Install ROS2](https://docs.ros.org/en/rolling/Installation/Ubuntu-Install-Debians.html). This
+      branch supports only ROS2 Humble and Rolling. For other ROS2 versions, please see the respective
+      branches.
+2. Install the driver using
+   ```
+   sudo apt-get install ros-${ROS_DISTRO}-ur-robot-driver
+   ```
+
+### Build from source
+Before building from source please make sure that you actually need to do that. Building from source
+might require some special treatment, especially when it comes to dependency management.
+Dependencies might change from time to time. Upstream packages (such as the library) might change
+their features / API which require changes in this repo. Therefore, this repo's source builds might
+require upstream repositories to be present in a certain version as otherwise builds might fail.
+Starting from scratch following exactly the steps below should always work, but simply pulling and
+building might fail occasionally.
+
+1. [Install ROS2](https://docs.ros.org/en/rolling/Installation/Ubuntu-Install-Debians.html).
    For using this driver with ROS2 `foxy`. Checkout [foxy
    branch](https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/tree/foxy), for using it
    with ROS2 ``galactic``, use the [galactic branch](https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/tree/galactic), for using it
    with ROS2 ``humble``, use the [galactic branch](https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/tree/humble).
 
-2. Make sure that `colcon`, its extensions and `vcs` are installed:
+   Once installed, please make sure to actually [source ROS2](https://docs.ros.org/en/rolling/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.html#source-the-setup-files) before proceeding.
+
+3. Make sure that `colcon`, its extensions and `vcs` are installed:
    ```
    sudo apt install python3-colcon-common-extensions python3-vcstool
    ```
 
-3. Create a new ROS2 workspace:
+4. Create a new ROS2 workspace:
    ```
    export COLCON_WS=~/workspace/ros_ur_driver
    mkdir -p $COLCON_WS/src
    ```
 
-4. Pull relevant packages, install dependencies, compile, and source the workspace by using:
+5. Clone relevant packages, install dependencies, compile, and source the workspace by using:
    ```
    cd $COLCON_WS
    git clone https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver.git src/Universal_Robots_ROS2_Driver
    vcs import src --skip-existing --input src/Universal_Robots_ROS2_Driver/Universal_Robots_ROS2_Driver-not-released.${ROS_DISTRO}.repos
    rosdep update
-   rosdep install --ignore-src --from-paths src -y -r
+   rosdep install --ignore-src --from-paths src -y
    colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release
    source install/setup.bash
    ```
 
-## Using MoveIt
+6. When consecutive pulls leads to build errors, please make sure to update the upstream packages before
+   filing an issue:
+   ```
+   cd $COLCON_WS
+   vcs import src --skip-existing --input src/Universal_Robots_ROS2_Driver/Universal_Robots_ROS2_Driver-not-released.${ROS_DISTRO}.repos
+   rosdep update
+   rosdep install --ignore-src --from-paths src -y
+   ```
+
+## MoveIt! support
 
 [MoveIt!](https://moveit.ros.org) support is built-in into this driver already.
 Watch MoveIt in action with the Universal Robots ROS2 driver:
@@ -180,161 +231,10 @@ Watch MoveIt in action with the Universal Robots ROS2 driver:
 
   *The video shows free-space trajectory planning around a modeled collision scene object using the MoveIt2 MotionPlanning widget for Rviz2.*
 
-
-### Real robot / URSim
-To test the driver with the example MoveIt-setup, first start the driver as described
-[below](#connect-to-external-control-via-urcap).
-```
-ros2 launch ur_moveit_config ur_moveit.launch.py ur_type:=ur5e launch_rviz:=true
-```
-Now you should be able to use the MoveIt Plugin in rviz2 to plan and execute trajectories with the
-robot as explained [here](https://moveit.picknik.ai/galactic/doc/tutorials/quickstart_in_rviz/quickstart_in_rviz_tutorial.html).
-
-## Network Setup
-
-There are many possible ways to connect a UR robot. This section describes a good example using static IP addresses and a direct connection from the PC to the Robot to minimize latency introduced by network hardware. Though a good network switch usually works fine, as well.
-
-1. Connect the UR control box directly to the remote PC with an ethernet cable.
-
-2. Open the network settings from the UR teach pendant (Setup Robot -> Network) and enter these settings:
-
-```
-IP address: 192.168.1.102
-Subnet mask: 255.255.255.0
-Default gateway: 192.168.1.1
-Preferred DNS server: 192.168.1.1
-Alternative DNS server: 0.0.0.0
-```
-
-3. On the remote PC, turn off all network devices except the "wired connection", e.g. turn off wifi.
-
-4. Open Network Settings and create a new Wired connection with these settings. You may want to name this new connection `UR` or something similar:
-
-```
-IPv4
-Manual
-Address: 192.168.1.101
-Netmask: 255.255.255.0
-Gateway: 192.168.1.1
-```
-
-5. Verify the connection from the PC with e.g. ping.
-
-```
-ping 192.168.1.102
-```
-
-## Connect to External Control via URCap
-
-This section describes installation and launching of the URCap program from the pendant. It allows ROS to control the robot externally. Generally, you will launch the driver via ROS then start URCap from the pendant.
-
-1. To enable external control of the UR robot from a remote PC you need to install the [**externalcontrol-1.0.5.urcap**](/ur_robot_driver/resources) which can be downloaded from [Universal_Robots_ExternalControl_URCap](https://github.com/UniversalRobots/Universal_Robots_ExternalControl_URCap/releases).
-
-**Note:** For installing this URCap a minimal PolyScope version of 3.7 or 5.1 (in case of e-Series) is necessary.
-
-2. For installing the necessary URCap and creating a program, please see the individual tutorial on how to [setup a CB3 robot](/ur_robot_driver/doc/installation/install_urcap_cb3.rst) or how to [setup an e-Series robot](/ur_robot_driver/doc/installation/install_urcap_e_series.rst)
-
-3. On the remote PC, launch the suitable launch file which starts the robot driver and controllers (see details in [Usage](#usage) section).
-
-4. From the Program Robot tab of the teach pendant, load `external_control.urp`. Click on the "Control by..." section of the program to check the Host IP of the external PC. If it needs to be modified, make the modification under the Installation tab (as prompted on screen). You do not need to modify the Custom Port.
-
-5. When the Host IP is correct, click the play button to connect with the external PC.
-
-## Usage
-
-For starting the driver there are two main launch files in the `ur_robot_driver` package.
-
-  - `ur_control.launch.py` - starts ros2_control node including hardware interface, joint state broadcaster and a controller. This launch file also starts `dashboard_client` if real robot is used.
-  - `ur_dashboard_client.launch.py` - start the dashboard client for UR robots.
-
-Also, there are predefined launch files for all supported types of UR robots.
-
-The arguments for launch files can be listed using `ros2 launch ur_robot_driver <launch_file_name>.launch.py --show-args`.
-The most relevant arguments are the following:
-
-  - `ur_type` (*mandatory*) - a type of used UR robot (*ur3*, *ur3e*, *ur5*, *ur5e*, *ur10*, *ur10e*, or *ur16e*).
-  - `robot_ip` (*mandatory*) - IP address by which the root can be reached.
-  - `use_fake_hardware` (default: *false*) - use simple hardware emulator from ros2_control.
-    Useful for testing launch files, descriptions, etc. See explanation below.
-  - `initial_positions` (default: dictionary with all joint values set to 0) - Allows passing a dictionary to set the initial joint values for the fake hardware from [ros2_control](http://control.ros.org/).  It can also be set from a yaml file with the `load_yaml` commands as follows:
-      ```
-      <xacro:property name="initial_positions" value="${load_yaml(initial_positions_file)}"/>
-      ```
-      In this example, the **initial_positions_file** is a xacro argument that contains the absolute path to a yaml file. An example of the initial positions yaml file is as follows:
-      ```
-      elbow_joint: 1.158
-      shoulder_lift_joint: -0.953
-      shoulder_pan_joint: 1.906
-      wrist_1_joint: -1.912
-      wrist_2_joint: -1.765
-      wrist_3_joint: 0.0
-      ```
-
-  - `fake_sensor_commands` (default: *false*) - enables setting sensor values for the hardware emulators.
-    Useful for offline testing of controllers.
-  - `robot_controller` (default: *joint_trajectory_controller*) - controller for robot joints to be started.
-    Available controllers: *joint_trajectory_controller*, *scaled_joint_trajectory_controller*.
-    Note: *joint_state_broadcaster*, *speed_scaling_state_broadcaster*, *force_torque_sensor_broadcaster*, and *io_and_status_controller* will always start.
-
-    *HINT*: list all loaded controllers using `ros2 control list_controllers` command.
-
-**NOTE**: The package can simulate hardware with the ros2_control `FakeSystem`. This emulator enables an environment for testing of "piping" of hardware and controllers, as well as testing robot's descriptions. For more details see [ros2_control documentation](https://ros-controls.github.io/control.ros.org/) for more details.
-
-### Example Commands for Testing the Driver
-
-Allowed UR-Type strings: `ur3`, `ur3e`, `ur5`, `ur5e`, `ur10`, `ur10e`, `ur16e`.
-
-##### 1. Start hardware, simulator or mockup
-
-- To do test with hardware, use:
-  ```
-  ros2 launch ur_robot_driver ur_control.launch.py ur_type:=<UR_TYPE> robot_ip:=<IP_OF_THE_ROBOT> launch_rviz:=true
-  ```
-  For more details check the argument documentation with `ros2 launch ur_robot_driver ur_control.launch.py --show-arguments`
-
-  After starting the launch file start the external_control URCap program from the pendant, as described above.
-
-- To do an offline test with URSim check details about it in [this section](#usage-with-official-ur-simulator)
-
-- To use mocked hardware (capability of ros2_control), use `use_fake_hardware` argument, like:
-  ```
-  ros2 launch ur_robot_driver ur_control.launch.py ur_type:=ur5e robot_ip:=yyy.yyy.yyy.yyy use_fake_hardware:=true launch_rviz:=true
-  ```
-
-  **NOTE**: Instead of using the global launch file for control stack, there are also prepeared launch files for each type of UR robots named. They accept the same arguments are the global one and are used by:
-  ```
-  ros2 launch ur_robot_driver <ur_type>.launch.py
-  ```
-
-##### 2. Sending commands to controllers
-
-Before running any commands, first check the controllers' state using `ros2 control list_controllers`.
-
-- Send some goal to the Joint Trajectory Controller by using a demo node from [ros2_control_demos](https://github.com/ros-controls/ros2_control_demos) package by starting  the following command in another terminal:
-   ```
-   ros2 launch ur_robot_driver test_joint_trajectory_controller.launch.py
-   ```
-   After a few seconds the robot should move.
-
-- To test another controller, simply define it using `initial_joint_controller` argument, for example when using fake hardware:
-   ```
-   ros2 launch ur_robot_driver ur_control.launch.py ur_type:=ur5e robot_ip:=yyy.yyy.yyy.yyy initial_joint_controller:=joint_trajectory_controller use_fake_hardware:=true launch_rviz:=true
-   ```
-   And send the command using demo node:
-   ```
-   ros2 launch ur_robot_driver test_scaled_joint_trajectory_controller.launch.py
-   ```
-   After a few seconds the robot should move (or jump when using emulation).
-
-
-##### 3. Using only robot description
-
-If you just want to test description of the UR robots, e.g., after changes you can use the following command:
-   ```
-   ros2 launch ur_description view_ur.launch.py ur_type:=ur5e
-   ```
-## Usage with official UR simulator
-For using the driver with the URSim docker image please follow instructions [here](https://docs.ros.org/en/ros2_packages/rolling/api/ur_robot_driver/usage.html#usage-with-official-ur-simulator).
+See the [MoveIt!
+section](https://docs.ros.org/en/ros2_packages/rolling/api/ur_robot_driver/usage.html#using-moveit)
+of the [Usage
+guide](https://docs.ros.org/en/ros2_packages/rolling/api/ur_robot_driver/usage.html) for details.
 
 ## Expected Changes in the Near Future
 
@@ -352,14 +252,3 @@ Prepare the pre-commit formatting to run like this:
   ```
   pre-commit install`
   ```
-
-## CI setup
-
-There are three build stages checking current and future compatibility of the driver.
-
-1. Binary builds - against released packages (main and testing) in ROS distributions. Shows that direct local build is possible.
-
-1. Semi-binary builds - against released core ROS packages (main and testing), but the immediate dependencies are pulled from source.
-   Shows that local build with dependencies is possible and if fails there we can expect that after the next package sync we will not be able to build.
-
-1. Source build - also core ROS packages are build from source. It shows potential issues in the mid future.
diff --git a/ur_robot_driver/doc/installation/robot_setup.rst b/ur_robot_driver/doc/installation/robot_setup.rst
@@ -71,6 +71,8 @@ inside a colcon workspace).
 Extract calibration information
 -------------------------------
 
+.. _calibration_extraction:
+
 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.
 
diff --git a/ur_robot_driver/doc/usage.rst b/ur_robot_driver/doc/usage.rst
@@ -191,52 +191,26 @@ To test the driver with the example MoveIt-setup, first start the driver as desc
 Now you should be able to use the MoveIt Plugin in rviz2 to plan and execute trajectories with the
 robot as explained `here <https://moveit.picknik.ai/galactic/doc/tutorials/quickstart_in_rviz/quickstart_in_rviz_tutorial.html>`_.
 
-Fake hardware on ROS2 Galactic
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Fake hardware
+^^^^^^^^^^^^^
 
-Currently, the ``scaled_joint_trajectory_controller`` does not work on ROS2 Galactic. There is an
-`upstream Merge-Request <https://github.com/ros-controls/ros2_control/pull/635>`_ pending to fix that. Until this is merged and released, please change the
-default controller in the `controllers.yaml <ur_moveit_config/config/controllers.yaml>`_ file. Make
-sure that the ``default`` field is assigned ``true`` for the ``joint_trajectory_controller`` and ``false``
-for the
-``scaled_joint_trajectory_controller``.
-
-.. code-block::
-
-   controller_names:
-     - scaled_joint_trajectory_controller
-     - joint_trajectory_controller
-
-
-   scaled_joint_trajectory_controller:
-     action_ns: follow_joint_trajectory
-     type: FollowJointTrajectory
-     default: false
-     joints:
-       - shoulder_pan_joint
-       - shoulder_lift_joint
-       - elbow_joint
-       - wrist_1_joint
-       - wrist_2_joint
-       - wrist_3_joint
-
-
-   joint_trajectory_controller:
-     action_ns: follow_joint_trajectory
-     type: FollowJointTrajectory
-     default: true
-     joints:
-       - shoulder_pan_joint
-       - shoulder_lift_joint
-       - elbow_joint
-       - wrist_1_joint
-       - wrist_2_joint
-       - wrist_3_joint
-
-Then start
+Currently, the ``scaled_joint_trajectory_controller`` does not work with ros2_control fake_hardware. There is an
+`upstream Merge-Request <https://github.com/ros-controls/ros2_control/pull/822>`_ pending to fix that. Until this is merged and released, you'll have to fallback to the ``joint_trajectory_controller`` by passing ``initial_controller:=joint_trajectory_controller`` to the driver's startup. Also, you'll have to tell MoveIt! that you're using fake_hardware as it then has to map to the other controller:
 
 .. code-block::
 
    ros2 launch ur_robot_driver ur_control.launch.py ur_type:=ur5e robot_ip:=yyy.yyy.yyy.yyy use_fake_hardware:=true launch_rviz:=false initial_joint_controller:=joint_trajectory_controller
    # and in another shell
-   ros2 launch ur_moveit_config ur_moveit.launch.py ur_type:=ur5e launch_rviz:=true
+   ros2 launch ur_moveit_config ur_moveit.launch.py ur_type:=ur5e launch_rviz:=true use_fake_hardware:=true
+
+Robot frames
+------------
+
+While most tf frames come from the URDF and are published from the ``robot_state_publisher``, there
+are a couple of things to know:
+
+- The ``base`` frame is the robot's base as the robot controller sees it.
+- The ``tool0_controller`` is the tool frame as published from the robot controller. If there is no
+  additional tool configured on the Teach pendant (TP), this should be equivalent to ``tool0`` given that
+  the URDF uses the specific robot's :ref:`calibration <calibration_extraction>`. If a tool is
+  configured on the TP, then the additional transformation will show in ``base`` -> ``tool0``.
