Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Move installation instructions to subpage (backport #870) #884

Merged
merged 2 commits into from
Apr 16, 2024
Merged

Move installation instructions to subpage (backport #870) #884

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f66c5d1
Move installation instructions to subpage (#870)
fmauch Nov 16, 2023
c8ff0c8
Make things equal to main branch
fmauch Apr 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 50 additions & 108 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,84 +13,68 @@ 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

<table width="100%">
<tr>
<th>ROS2 Distro</th>
<th>Foxy</th>
<th>Galactic</th>
<th>Foxy (EOL)</th>
<th>Galactic (EOL)</th>
<th>Humble</th>
<th>Iron</th>
<th>Rolling</th>
</tr>
<tr>
<th>Branch</th>
<td><a href="https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/tree/foxy">foxy</a></td>
<td><a href="https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/tree/galactic">galactic</a></td>
<td><a href="https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/tree/humble">humble</a></td>
<td><a href="https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/tree/iron">iron</a></td>
<td><a href="https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/tree/main">main</a></td>
</tr>
<tr>
<th>Build Status</th>
<th>Release status</th>
<td>
<a href="https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/actions/workflows/foxy-binary-build.yml?query=event%3Aschedule++">
<img src="https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/actions/workflows/foxy-binary-build.yml/badge.svg?event=schedule"
alt="Foxy Binary Build"/>
</a> <br />
<a href="https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/actions/workflows/foxy-semi-binary-build.yml?query=event%3Aschedule++">
<img src="https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/actions/workflows/foxy-semi-binary-build.yml/badge.svg?event=schedule"
alt="Foxy Semi-Binary Build"/>
</a>
</td>
<td>
<a href="https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/actions/workflows/galactic-binary-build.yml?query=event%3Aschedule++">
<img src="https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/actions/workflows/galactic-binary-build.yml/badge.svg?event=schedule"
alt="Galactic Binary Build"/>
</a> <br />
<a href="https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/actions/workflows/galactic-semi-binary-build.yml?query=event%3Aschedule++">
<img src="https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/actions/workflows/galactic-semi-binary-build.yml/badge.svg?event=schedule"
alt="Galactic Semi-Binary Build"/>
</a>
</td>
<td>
<a href="https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/actions/workflows/humble-binary-build.yml?query=event%3Aschedule++">
<img src="https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/actions/workflows/humble-binary-build.yml/badge.svg?event=schedule"
alt="Humble Binary Build"/>
</a> <br />
<a href="https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/actions/workflows/humble-semi-binary-build.yml?query=event%3Aschedule++">
<img src="https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/actions/workflows/humble-semi-binary-build.yml/badge.svg?event=schedule"
alt="Humble Semi-Binary Build"/>
</a>
<a href='https://build.ros2.org/job/Hbin_uJ64__ur_calibration__ubuntu_jammy_amd64__binary/'><img src='https://build.ros2.org/job/Hbin_uJ64__ur_calibration__ubuntu_jammy_amd64__binary/badge/icon?subject=ur_calibration'></a><br/>
<a href='https://build.ros2.org/job/Hbin_uJ64__ur_controllers__ubuntu_jammy_amd64__binary/'><img src='https://build.ros2.org/job/Hbin_uJ64__ur_controllers__ubuntu_jammy_amd64__binary/badge/icon?subject=ur_controllers'></a>
<a href='https://build.ros2.org/job/Hbin_uJ64__ur_dashboard_msgs__ubuntu_jammy_amd64__binary/'><img src='https://build.ros2.org/job/Hbin_uJ64__ur_dashboard_msgs__ubuntu_jammy_amd64__binary/badge/icon?subject=ur_dashboard_msgs'></a>
<a href='https://build.ros2.org/job/Hbin_uJ64__ur_moveit_config__ubuntu_jammy_amd64__binary/'><img src='https://build.ros2.org/job/Hbin_uJ64__ur_moveit_config__ubuntu_jammy_amd64__binary/badge/icon?subject=ur_moveit_config'></a>
<a href='https://build.ros2.org/job/Hbin_uJ64__ur_robot_driver__ubuntu_jammy_amd64__binary/'><img src='https://build.ros2.org/job/Hbin_uJ64__ur_robot_driver__ubuntu_jammy_amd64__binary/badge/icon?subject=ur_robot_driver'></a>
</td>
<td>
<a href="https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/actions/workflows/rolling-binary-build.yml?query=branch%3Amain+">
<img src="https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/actions/workflows/rolling-binary-build.yml/badge.svg?branch=main"
alt="Rolling Binary Build"/>
</a> <br />
<a href="https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/actions/workflows/rolling-semi-binary-build.yml?query=branch%3Amain+">
<img src="https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/actions/workflows/rolling-semi-binary-build.yml/badge.svg?branch=main"
alt="Rolling Semi-Binary Build"/>
</a>
<a href='https://build.ros2.org/job/Ibin_uJ64__ur_calibration__ubuntu_jammy_amd64__binary/'><img src='https://build.ros2.org/job/Ibin_uJ64__ur_calibration__ubuntu_jammy_amd64__binary/badge/icon?subject=ur_calibration'></a><br/>
<a href='https://build.ros2.org/job/Ibin_uJ64__ur_controllers__ubuntu_jammy_amd64__binary/'><img src='https://build.ros2.org/job/Ibin_uJ64__ur_controllers__ubuntu_jammy_amd64__binary/badge/icon?subject=ur_controllers'></a>
<a href='https://build.ros2.org/job/Ibin_uJ64__ur_dashboard_msgs__ubuntu_jammy_amd64__binary/'><img src='https://build.ros2.org/job/Ibin_uJ64__ur_dashboard_msgs__ubuntu_jammy_amd64__binary/badge/icon?subject=ur_dashboard_msgs'></a>
<a href='https://build.ros2.org/job/Ibin_uJ64__ur_moveit_config__ubuntu_jammy_amd64__binary/'><img src='https://build.ros2.org/job/Ibin_uJ64__ur_moveit_config__ubuntu_jammy_amd64__binary/badge/icon?subject=ur_moveit_config'></a>
<a href='https://build.ros2.org/job/Ibin_uJ64__ur_robot_driver__ubuntu_jammy_amd64__binary/'><img src='https://build.ros2.org/job/Ibin_uJ64__ur_robot_driver__ubuntu_jammy_amd64__binary/badge/icon?subject=ur_robot_driver'></a>
</td>
<td>
<a href='https://build.ros2.org/job/Rbin_uJ64__ur_calibration__ubuntu_jammy_amd64__binary/'><img src='https://build.ros2.org/job/Rbin_uJ64__ur_calibration__ubuntu_jammy_amd64__binary/badge/icon?subject=ur_calibration'></a><br/>
<a href='https://build.ros2.org/job/Rbin_uJ64__ur_controllers__ubuntu_jammy_amd64__binary/'><img src='https://build.ros2.org/job/Rbin_uJ64__ur_controllers__ubuntu_jammy_amd64__binary/badge/icon?subject=ur_controllers'></a>
<a href='https://build.ros2.org/job/Rbin_uJ64__ur_dashboard_msgs__ubuntu_jammy_amd64__binary/'><img src='https://build.ros2.org/job/Rbin_uJ64__ur_dashboard_msgs__ubuntu_jammy_amd64__binary/badge/icon?subject=ur_dashboard_msgs'></a>
<a href='https://build.ros2.org/job/Rbin_uJ64__ur_moveit_config__ubuntu_jammy_amd64__binary/'><img src='https://build.ros2.org/job/Rbin_uJ64__ur_moveit_config__ubuntu_jammy_amd64__binary/badge/icon?subject=ur_moveit_config'></a>
<a href='https://build.ros2.org/job/Rbin_uJ64__ur_robot_driver__ubuntu_jammy_amd64__binary/'><img src='https://build.ros2.org/job/Rbin_uJ64__ur_robot_driver__ubuntu_jammy_amd64__binary/badge/icon?subject=ur_robot_driver'></a>
</td>
</tr>
</table>

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.<ros-distro>.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:
Expand All @@ -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

Expand All @@ -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:
Expand Down
71 changes: 71 additions & 0 deletions ur_robot_driver/doc/installation/installation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <https://docs.ros.org/en/rolling/Installation/Ubuntu-Install-Debians.html>`_. 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 <https://docs.ros.org/en/rolling/Installation/Ubuntu-Install-Debians.html>`_. This
branch supports only ROS2 Rolling. For other ROS2 versions, please see the respective branches.

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:

.. 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
1 change: 1 addition & 0 deletions ur_robot_driver/doc/installation/toc.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading