Skip to content

initial setup

Jump to bottom
Felix von Drigalski edited this page Nov 26, 2019 · 1 revision

Initial Setup

Follow this step-by-step guide to perform the initial setup of the o2as project on a development machine running Ubuntu.

Content:

Note 1: The whole development environment of the o2as project is containerized/virtualized using Docker. This ensures that all the contributors work in the exact same software environment.

Note 2: The o2as robot and simulator interfaces are primarily implemented with ROS.

Note 3: The o2as project relies heavily on both hardware 3D graphic acceleration and Nvidia CUDA, thus a discrete Nvidia GPU is highly recommended. Machines without Nvidia GPUs (including virtual machines) are only partially supported: 3D accelerated tools such as Rviz and Gazebo will most likely crash at runtime.

Note 4: Although this initial setup is meant to be performed only once, you can run it again would you want to reset the development environment as the project evolves. However, make sure to backup your latest changes beforehand.

Step 0: Verify the Prerequisites

Mandatory:

  • A machine running Ubuntu 16.04 LTS (Xenial Xerus) on an AMD64 architecture.
  • Access to administrator privileges (sudo) on the Ubuntu machine.
  • Access to developer privileges on the GitLab project at https://github.com/o2as/ur-o2as.

Recommended:

  • A robot for full operability. If not, the simulator provides support for basic operations.
  • An Nvidia GPU capable of running CUDA 9.0 (compute capability >= 3.0) or newer. If not, 3D accelerated tools will most likely crash (including Rviz and Gazebo).
  • If you have an Nvidia GPU in your machine, make sure that the Nvidia drivers are active instead of the "Nouveau" open-source drivers. You can check this in "System Settings/Software and Drivers/Additional Drivers".

Step 1: Setup the Development Environment

Setup the environment of the development machine with the following instructions.

  1. Install git if necessary:

    sudo apt-get update && sudo apt-get install -y git

  2. Clone the o2as project repository in your home folder:

    cd ~/ && git clone https://github.com/o2as/ur-o2as.git
cd ~/ur-o2as && git checkout develop 
git submodule update --init

    Enter your GitLab developer credentials if prompted.

  3. Configure the system environment:

    cd ~/ur-o2as/ && ./SETUP-DEVEL-MACHINE.sh

    The execution of SETUP-DEVEL-MACHINE.sh requires sudo permissions to install the tools that allow virtualization, i.e. Docker, Docker Compose, and Nvidia Docker 2. System changes made with sudo are kept to a strict minimum.

  4. Reboot the system (or log out and back in) for the changes to users and groups to take effect:

    sudo reboot

Note 5: The SETUP-DEVEL-MACHINE.sh script is actually divided into INCL-SUDO-ENV.sh and INCL-USER-ENV.sh. The execution of INCL-SUDO-ENV.sh makes system-wide changes and thus requires sudo permissions. However, if your system has already all the necessary tools installed, you can directly set up your local user environment with cd ~/ur-o2as/ && ./INCL-USER-ENV.sh which does not require sudo permissions.

Note 6: You do not need to reboot if your local user has already been added to the docker group. If so, executing docker --version should not ask for sudo. In principle, you only need to reboot after the very first time you run SETUP-DEVEL-MACHINE.sh.

Step 2: Build the Docker Image

Create a virtual environment using Docker (= Docker image) on the development machine with the following instructions.

  1. Build the Docker image:

    cd ~/ur-o2as/ && ./BUILD-DOCKER-IMAGE.sh

    This script builds the image following the instructions found in ~/ur-o2as/docker/Dockerfile.

Note 7: Use a wired connection the first time you build the image to greatly accelerate the process. Future builds will reuse cached data whenever possible.

Step 3: Run the Docker Container

Enter a virtual instance of the Docker image (= Docker container) on the development machine with the following instructions.

  1. Run the Docker container:

    cd ~/ur-o2as/ && ./RUN-DOCKER-CONTAINER.sh

    This script creates or updates the container following the instructions found in ~/ur-o2as/docker/docker-compose.yml. It allows the container to share system resources, such as volumes and devices, with the host machine.

  2. Use ctrl+d to exit the container at any time.

Note 8: If no Nvidia drivers are present, the Docker runtime is set to runc, instead of nvidia, to bypass nvidia-docker2 when entering the container. However, 3D accelerated tools, including Gazebo, will most likely not work. You can modify the default runtime in ~/.bashrc.

Note 9: (ignore)

Note 10: Be careful if you need to modify docker-compose.yml as the container will be recreated from scratch the next time you run RUN-DOCKER-CONTAINER.sh.

Step 4: Test the Catkin Workspace

Build and test the ROS environment (= Catkin workspace) inside the Docker container with the following instructions.

  1. Enter the Docker container if necessary:

    cd ~/ur-o2as/ && ./RUN-DOCKER-CONTAINER.sh

  2. Initialize the Catkin workspace:

    cd /root/ && ./scripts/reset-catkin-workspace.sh

    This script will remove any existing Catkin workspace and build a new one inside /root/catkin_ws/.

  3. Make sure that the new Catkin workspace is sourced:

    cd /root/ && source ./catkin_ws/devel/setup.bash

  4. Launch a couple of publisher and subscriber test nodes from the em_chatter package:

    roslaunch em_chatter em_chatter_rqt.launch

    If everything has installed correctly, you should see a node em_listener that subscribes to a publisher node called em_talker in a Rqt GUI.

  5. Launch a 3D-accelerated module to test the graphics drivers. For example, run this command:

    roslaunch o2as_moveit_config demo.launch

    If MoveIt appears, everything is configured correctly. If you receive an error, you might need to install additional drivers as described here. Raise the issue if you get stuck.

Step X: Set udev rules

Follow this guide.

udev rules allow a USB device to be mapped to the same /dev/ port every time it is plugged in (rather than /dev/ttyUSB0 etc.). The o2as_fastening_tools and some other packages require this.

Clone this wiki locally