Getting Started

Installing EAGERx

There are four installation options:

  • Using pip

  • From source

  • Using docker

  • Using conda and robostack

Installation using pip

You can do a minimal installation of EAGERx with:

pip3 install eagerx

Note

To make use of EAGERx’s distributed capabilities (e.g. running on different physical machines), ROS1 should be installed and sourced.

Installation from source

Prerequisites: Install Poetry.

Clone the eagerx repository and go to its root:

git clone git@github.com:eager-dev/eagerx.git
cd eagerx

Install EAGERx:

poetry install

Verify installation:

poetry run python examples/example_openai.py

Note

To make use of EAGERx’s distributed capabilities (e.g. running on different physical machines), ROS1 should be installed and sourced.

Installation using Docker (with distributed support)

Prerequisites: Install Docker and for GPU dockers nvidia-docker.

In total, four docker images are available with EAGERx installed, i.e. two with a minimal installation of EAGERx and its dependencies (CPU and GPU) and two with Stable Baselines 3 installed as well (CPU and GPU). The dockers with Stable Baselines 3 also come with tutorials on EAGERx.

Note

All docker images natively support EAGERx’s distributed capabilities (e.g. running on different physical machines).

GPU Dockers

The GPU dockers require nvidia-docker and can be pulled as follows:

sudo docker pull eagerx/eagerx

or with Stable Baselines 3 and the tutorials:

sudo docker pull eagerx/eagerx-sb

The docker image can be run as follows:

sudo docker run -it --rm --gpus all [image]

where [image] should be replaced with eagerx/eagerx or eagerx/eagerx-sb.

Verify that EAGERx is installed:

python -c 'import eagerx'

CPU Dockers

The CPU only dockers can be pulled as follows:

sudo docker pull [image]

where image should be replaced with eagerx/eagerx-cpu or eagerx/eagerx-sb-cpu.

Run the image with the command

sudo docker run -it --rm [image]

where image should be replaced with eagerx/eagerx-cpu or eagerx/eagerx-sb-cpu.

Verify that EAGERx is installed:

python -c 'import eagerx'

Installation Using Conda (with distributed support)

You first need to download and install Conda (we recommend the miniforge distribution).

Then, follow the instructions of RoboStack to install ROS1:

# if you don't have mamba yet, install it first (not needed when using mambaforge):
conda install mamba -c conda-forge

# now create a new environment
mamba create -n ros_env python=3.8
conda activate ros_env

# this adds the conda-forge channel to the new created environment configuration
conda config --env --add channels conda-forge
# and the robostack channels
conda config --env --add channels robostack
conda config --env --add channels robostack-experimental

# Install the version of ROS you are interested in:
mamba install ros-noetic-desktop

# optionally, install some compiler packages if you want to e.g. build packages in a colcon_ws:
mamba install compilers cmake pkg-config make ninja colcon-common-extensions

# on Linux and osx (but not Windows) for ROS1 you might want to:
mamba install catkin_tools

# on Windows, install Visual Studio 2017 or 2019 with C++ support
# see https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160

# on Windows, install the Visual Studio command prompt:
# mamba install vs2019_win-64

# note that in this case, you should also install the necessary dependencies with conda/mamba, if possible

# IMPORTANT! reload environment to activate required scripts before running anything
# on Windows, please restart the Anaconda Prompt / Command Prompt!
conda deactivate
conda activate ros_env

# if you want to use rosdep, also do:
mamba install rosdep
rosdep init  # IMPORTANT: do not use sudo!
rosdep update

Finally, you can activate your ros_env and install EAGERx:

conda activate ros_env
pip install eagerx

We also provide a Conda environment file which contains ROS1, EAGERx, SB3 and other EAGERx packages. In that case you simply have to do:

conda env create -f ros_env.yml

Extras: GUI

To install the whole set of features, you will need additional packages. There is for example a package available for visualizing the Graph and the EngineGraph.

You can install the gui by running:

pip3 install eagerx-gui

Note

The EAGERx docker images currently do not support gui functionality.

alternate text

The visualisation of an environment via the GUI.

Extras: training visualization

In robotics it is crucial to monitor the robot’s behavior during the learning process. Luckily, all inter-node communication within EAGERx can be listened to externally, so that any relevant information stream can be trivially monitored on-demand (e.g. with rqt_plot). For this, the user must select the Ros1 Backend.

Note

rqt_plot is included in the desktop or desktop-full ROS1 installation. See here for installation instructions. The docker images do not support visualization using rqt_plot.

alternate text

Live plot of the x, y, and z coordinate of the end effector using rqt_plot.

Other Dependencies

Below you find instructions for installing dependencies (optionally) required by EAGERx.

Poetry

Poetry is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you. We advise contributors to use this tool when developing an EAGERx package to leverage the pre-build CI workflow we have setup in the template package. However, this is not a requirement and a simple pip install to install all eagerx package dependencies into your project’s (virtual) Python environment will also work.

For installation on osx / linux / bashonwindows, simply run:

curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -

For more installation instructions, see here.

ROS1

See the ROS1 Installation Options, or do the following. By replacing <DISTRO> with the supported ROS1 distributions (noetic, melodic), and <PACKAGE> with the installation type (ros-base, desktop, desktop-full), a minimal ROS1 installation can be installed with:

Warning

Currently, eagerx only supports ROS1. ROS2 support will be added in future versions.

sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'
sudo apt install curl # if you haven't already installed curl
curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -
sudo apt update
sudo apt install ros-<DISTRO>-<PACKAGE>
sudo apt-get install ros-<DISTRO>-cv-bridge

Make sure to source /opt/ros/<DISTRO>/setup.bash in the environment where you intend to eagerx in. It can be convenient to automatically source this script every time a new shell is launched. These commands will do that for you if you:

echo "source /opt/ros/<DISTRO>/setup.bash" >> ~/.bashrc
source ~/.bashrc

In case you make use of a virtual environment, move to the directory containing the .venv and add source /opt/ros/<DISTRO>/setup.bash to the activation script before activating the environment with this line:

echo "source /opt/ros/<DISTRO>/setup.bash" >> .venv/bin/activate