From 1e48ae3f087bab1b91771f117840ab1052cadeb1 Mon Sep 17 00:00:00 2001 From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com> Date: Tue, 16 Apr 2024 13:55:16 +0200 Subject: [PATCH] Move installation instructions to subpage (backport #870) (#884) * Move installation instructions to subpage (#870) Apparently, having the build instructions so prominent on the main page seems to motivate people to build from source instead of installing the binary packages. This change simplifies the main repo page in order to show how to install and quickstart directly, linking to the full instructions from our sphinx doc. * More explicit copy_paste example This example should be ready-to-go when using the URSim example. * Make things equal to main branch --------- Co-authored-by: Felix Exner (fexner) --- README.md | 158 ++++++------------ .../doc/installation/installation.rst | 71 ++++++++ ur_robot_driver/doc/installation/toc.rst | 1 + 3 files changed, 122 insertions(+), 108 deletions(-) create mode 100644 ur_robot_driver/doc/installation/installation.rst diff --git a/README.md b/README.md index 581e159f4..600fdd5ff 100644 --- a/README.md +++ b/README.md @@ -13,14 +13,15 @@ The driver is compatible across the entire line of UR robots -- from 3 kg payloa Check also [presentations and videos](ur_robot_driver/doc/resources/README.md) about this driver. -## Build Status +## Release Status - - + + + @@ -28,69 +29,52 @@ Check also [presentations and videos](ur_robot_driver/doc/resources/README.md) a + - + +
ROS2 DistroFoxyGalacticFoxy (EOL)Galactic (EOL) HumbleIron Rolling
foxy galactic humbleiron main
Build StatusRelease status Foxy Binary Build
- - Foxy Semi-Binary Build - 		Galactic Binary Build
- - Galactic Semi-Binary Build - 		- - Humble Binary Build -
- - Humble Semi-Binary Build - +
+ + + + 		- - Rolling Binary Build -
- - Rolling Semi-Binary Build - +
+ + + + + 		+
+ + + +
+The table above shows the build status for each package of this repo from the [ROS buildfarm](https://build.ros2.org/). For end-of-life (EOL) distributions the nightly binary builds from our CI are shown. EOL distributions will receive no more updates and may be lacking features. -**NOTE**: There are two 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. - - Uses repos file: `src/Universal_Robots_ROS2_Driver/Universal_Robots_ROS2_Driver-not-released..repos` - -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. - - Uses repos file: `src/Universal_Robots_ROS2_Driver/Universal_Robots_ROS2_Driver.repos` - -Each of these stages also performs integration tests using ursim. In order to execute these tests locally, they have to be enabled: - ``` - colcon build --packages-select ur_robot_driver --cmake-args -DUR_ROBOT_DRIVER_BUILD_INTEGRATION_TESTS=On - ``` +A more [detailed build status](ci_status.md) shows the state of all CI workflows inside this repo. +Please note that the detailed view is intended for developers, while the one here should give end +users an overview of the current released state. ## Packages in the Repository: @@ -105,83 +89,45 @@ Each of these stages also performs integration tests using ursim. In order to ex Deprecation: The `ur_bringup` package is deprecated and will be removed from Iron Irwini on. +## System Requirements + +Please see the [requirements for the Universal_Robots_Client_Library](https://github.com/UniversalRobots/Universal_Robots_Client_Library#requirements), as this driver is build on top of Universal_Robots_Client_Library. + ## Getting Started 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. +1. **Install the driver** + ```bash + sudo apt-get install ros-humble-ur + ``` + See the [installation instructions](https://docs.ros.org/en/ros2_packages/humble/api/ur_robot_driver/installation/installation.html) for more details and source-build instructions. 2. **Start & Setup the robot**. Once you've installed the driver, [setup the robot](https://docs.ros.org/en/ros2_packages/humble/api/ur_robot_driver/installation/robot_setup.html) + and [create a program for external + control](https://docs.ros.org/en/ros2_packages/humble/api/ur_robot_driver/installation/install_urcap_e_series.html). -Please do this step carefully and extract the calibration as explained -[here](https://docs.ros.org/en/ros2_packages/humble/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/humble/api/ur_robot_driver/usage.html#usage-with-official-ur-simulator) -that will behave almost exactly like the real robot. + Please do this step carefully and extract the calibration as explained + [here](https://docs.ros.org/en/ros2_packages/humble/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/humble/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/humble/api/ur_robot_driver/usage.html) for details. -### Install from binary packages -1. [Install ROS2](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debians.html). This - branch supports only ROS2 Humble. For other ROS2 versions, please see the respective - branches. -2. Install the driver using + ```bash + # Replace ur5e with one of ur3, ur3e, ur5, ur5e, ur10, ur10e, ur16e, ur20, ur30 + # Replace the IP address with the IP address of your actual robot / URSim + ros2 launch ur_robot_driver ur_control.launch.py ur_type:=ur5e robot_ip:=192.168.56.101 ``` - sudo apt-get install ros-${ROS_DISTRO}-ur - ``` - -### 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/humble/Installation/Ubuntu-Install-Debians.html). - branch supports only ROS2 Humble. For other ROS2 versions, please see the respective - branches. - - Once installed, please make sure to actually [source ROS2](https://docs.ros.org/en/humble/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 - ``` +4. Unless started in [headless mode](https://docs.ros.org/en/ros2_packages/humble/api/ur_robot_driver/ROS_INTERFACE.html#headless-mode): Run the external_control program by **pressing `play` on the teach pendant**. -4. Create a new ROS2 workspace: - ``` - export COLCON_WS=~/workspace/ros_ur_driver - mkdir -p $COLCON_WS/src - ``` - -5. Clone relevant packages, install dependencies, compile, and source the workspace by using: - ``` - cd $COLCON_WS - git clone -b humble 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 - colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release - source install/setup.bash - ``` - -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 @@ -197,16 +143,12 @@ section](https://docs.ros.org/en/ros2_packages/humble/api/ur_robot_driver/usage. of the [Usage guide](https://docs.ros.org/en/ros2_packages/humble/api/ur_robot_driver/usage.html) for details. -## Expected Changes in the Near Future - -- Trajectory control currently only supports position commands. In the future, velocity control will be added. ## Contributor Guidelines -Code is auto-formatted with clang-format 14 whenever a git commit is made. Please ensure these dependencies are installed: +pre-commit is used to run a couple of checks before committing. To install it, run: ``` pip3 install pre-commit - sudo apt install clang-format-14 ``` Prepare the pre-commit formatting to run like this: diff --git a/ur_robot_driver/doc/installation/installation.rst b/ur_robot_driver/doc/installation/installation.rst new file mode 100644 index 000000000..eed955798 --- /dev/null +++ b/ur_robot_driver/doc/installation/installation.rst @@ -0,0 +1,71 @@ +Installation of the ur_robot_driver +=================================== + +You can either install this driver from binary packages as shown above or build it from source. We +recommend a binary package installation unless you want to join development and submit changes. + +Install from binary packages +---------------------------- + +1. `Install ROS2 `_. This + branch supports only ROS2 Rolling. For other ROS2 versions, please see the respective branches. +2. Install the driver using + + .. code-block:: bash + + sudo apt-get install ros-${ROS_DISTRO}-ur + + +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 `_. This + branch supports only ROS2 Rolling. For other ROS2 versions, please see the respective branches. + + Once installed, please make sure to actually `source ROS2 `_ before proceeding. + +3. Make sure that ``colcon``, its extensions and ``vcs`` are installed: + + .. code-block:: bash + + sudo apt install python3-colcon-common-extensions python3-vcstool + + +4. Create a new ROS2 workspace: + + .. code-block:: bash + + export COLCON_WS=~/workspace/ros_ur_driver + mkdir -p $COLCON_WS/src + +5. Clone relevant packages, install dependencies, compile, and source the workspace by using: + + .. code-block:: bash + + 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 + colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release + source install/setup.bash + +6. When consecutive pulls lead to build errors it is possible that you'll have to build an upstream + package from source, as well. See the [detailed build status](ci_status.md). When the binary builds are red, but + the semi-binary builds are green, you need to build the upstream dependencies from source. The + easiest way to achieve this, is using the repos file: + + .. code-block:: bash + + cd $COLCON_WS + vcs import src --skip-existing --input src/Universal_Robots_ROS2_Driver/Universal_Robots_ROS2_Driver.${ROS_DISTRO}.repos + rosdep update + rosdep install --ignore-src --from-paths src -y diff --git a/ur_robot_driver/doc/installation/toc.rst b/ur_robot_driver/doc/installation/toc.rst index 926be1acd..2ee60aae8 100644 --- a/ur_robot_driver/doc/installation/toc.rst +++ b/ur_robot_driver/doc/installation/toc.rst @@ -9,6 +9,7 @@ This chapter explains how to install the ``ur_robot_driver`` :maxdepth: 4 :caption: Contents: + installation real_time robot_setup install_urcap_cb3