Table of Contents

CRAM installation

Quickstart with Docker

For a quick peek into CRAM, check out the Docker setup and the visual setup procedure.

Prerequisites

OS and ROS

The recommended setup is Ubuntu 20.04 LTS with ROS Noetic.
This is the setup under which the CRAM team is working and it is best supported.

Most CRAM components should also work on older Ubuntu versions under ROS Kinetic etc. but with no guarantee. If you encounter any incompatibilities / bugs, please let us know.

If you don't have the latest version of ROS, install it (the desktop non-full version should be enough).
Don't forget to source the environment setup file and

$ sudo rosdep init
$ rosdep update
IDE and the interactive shell

Your chance to get a bit acquainted with Emacs if you've never used it before.

$ sudo apt-get install ros-DISTRO-roslisp-repl

where DISTRO is your ROS version, e.g., melodic or noetic

For information on how to use the IDE check the Setup and IDE page.

ROS workspace management tools

You will need those for setting up the ROS workspace and checking out code.

18.04 / Melodic:

$ sudo apt-get install python-rosinstall python-wstool

20:04 / Noetic:

$ sudo apt-get install python3-wstool

Installation

This is a guide for installing the main CRAM packages. It covers installing the packages you need to get the system up and running to the point where you can run and test it in a simulation mode. Setting up the system on a real robot is more complex (mostly involving the usual ROS-based platform setup) and is out of scope of this guide.

Nevertheless, CRAM is a big system that has some external dependencies. Most of them are automatically installed as Debian packages, some you need to install from source.

ROS workspace setup

Skip this part if you already have a ROS workspace.

If you don't have a ROS workspace, please create one. For example, you can do the following:

$ mkdir -p ~/workspace/ros/src
$ cd ~/workspace/ros
$ catkin_make
$ source devel/setup.bash

We create the workspace in the $HOME/workspace directory. Make sure you adjust the paths if you want to create them somewhere else.

If during catkin_make you got an error that it is not defined, it means that you didn't finish the ROS installation. Here is a hint: you need to source the ROS environment for catkin_make to work:

$ source /opt/ros/DISTRO/setup.bash

where DISTRO is, e.g., kinetic.

Execute these commands and continue from the catkin_make step.

Now if you execute roscd you will end up in ros/devel.

Don't forget to add the corresponding entry to the bottom of your ~/.bashrc:

  source $HOME/workspace/ros/devel/setup.bash

CRAM and dependencies installation (ROS Noetic Ubuntu 20.04)

Please checkout the README on the devel branch of the CRAM github repository for the most recent installation instructions. The noetic support is currently still in development.

$ sudo apt install ros-noetic-roslisp-repl
$ sudo apt-get install python-rosinstall python-wstool
$ cd ~/workspace/src
$ wstool init
$ wstool merge https://raw.githubusercontent.com/cram2/cram/devel/cram-20.04.rosinstall
$ wstool update
$ cd ~/workspace/
$ rosdep update
$ rosdep install --ignore-src --from-paths src/ -r
$ catkin_make

CRAM and dependencies installation (ROS Melodic Ubuntu 18.04)

Check out and compile all the necessary repositories:

$ cd ~/workspace/ros/src
$ wstool init
$ wstool merge https://raw.githubusercontent.com/cram2/cram/master-melodic/cram-18.04.rosinstall
$ wstool update
$ cd ~/workspace/ros
$ rosdep update
$ rosdep install --ignore-src --from-paths src/ -r
$ catkin_make

Note that the wstool update command is the one that downloads the source code of CRAM and its dependencies.

For ROS melodic and the current packages, one thing needs to be fixed. The package octomap contains a dependency to a ROS2 package, which can be ignored. Open the package.xml of octomap.

roscd octomap
sudo nano package.xml

Now remove the following line within:

<exec_depend condition="$ROS_VERSION == 2">ament_cmake</exec_depend>

The installation is finished, please continue to the section Get ready for development down below.

If something went wrong consult the Support page or feel free to drop an email to the person maintaining this page (check the “Last edited by” part of the footer).

CRAM and dependencies installation (ROS Kinetic Ubuntu 16.04)

Check out and compile all the necessary repositories:

$ cd ~/workspace/ros/src
$ wstool init
$ wstool merge https://raw.githubusercontent.com/cram2/cram/master/cram-16.04.rosinstall
$ wstool update
$ touch iai_maps/iai_dlr_cutting_demo/CATKIN_IGNORE
$ cd ~/workspace/ros
$ rosdep update
$ rosdep install --ignore-src --from-paths src/ -r
$ catkin_make

Note that the wstool update command is the one that downloads the source code of CRAM and its dependencies.

If something went wrong consult the Support page or feel free to drop an email to the person maintaining this page (check the “Last edited by” part of the footer).

CRAM and dependencies installation (ROS Indigo Ubuntu 14.04)

CRAM uses the newest version of the Lisp compiler which is not available on 14.04. That is not a problem as we can install it ourselves. For that please download the SBCL version 1.3.1 from the SBCL webpage. You will most likely need the 64 bit Linux version. Then extract the archive (in Nautilus, the file browser, it will be right clickextract here). Then go to the place where you extracted the archive in the terminal and execute the install script:

$ cd ~/Downloads/sbcl-1.3.1-x86-64-linux && sh install.sh

Next step is to check out and compile all the necessary repositories:

$ cd ~/workspace/ros/src
$ wstool init
$ wstool merge https://raw.githubusercontent.com/cram2/cram/master/cram-14.04.rosinstall
$ wstool update
$ cd ~/workspace/ros
$ rosdep update
$ rosdep install --ignore-src --from-paths src/
$ catkin_make

Note that the wstool update command is the one that downloads the source code of CRAM and its dependencies such as KnowRob.

If something went wrong consult the Support page or feel free to drop an email to the person maintaining this page (check the “Last edited by” part of the footer).

Windows Install

  1. Enable Hardware Virtualization in your BIOS settings
  2. Enable the WSL 2 feature in Turn Windows features on or off
  3. Set Firewall to allow WSL comunication. Easiest way is by disabling Firewall for public networks, or add a rule for WSL.
  4. Import the image into WSL from Powershell with
     wsl --import Ubuntu-20.04-Cram C:\Users\$env:UserName\Documents\Ubuntu-20.04-Cram C:\Users\$env:UserName\Downloads\Ubuntu2004RosCramJupyter.tar 
  5. Set the image as default with
    wsl --set-default Ubuntu-20.04-Cram
  6. Launch Ubuntu-20.04 from the windows menu. The username and password is cram
  7. glxgears will test the x-forwarding to VcXsrv. If nothing happens, check the VcXsrv setup and Firewall rules.
  8. roslisp_repl & will launch Emacs.

Happy hacking!

How to launch the Jupyter Notebook

  1. roslaunch cram_pr2_pick_place_demo sandbox.launch &
  2. jupyter-lab –allow-root –no-browser –port 8888
  3. Open the URL in your browser

Get ready for development

Before you open emacs you might want to configure it, at least set up the clipboard properly to enable copy/paste from/to other apps. That is described in the Setup and IDE and Emacs Initialization File pages and there is also more than enough material available online.

Open your emacs and wait until “ROS welcomes you”:

$ roslisp_repl &

Compiling packages using the ROS build system is not enough for code written in Lisp. To compile the CRAM packages that you want to use in Lisp, type the following in the REPL in your Emacs:

  ,
  r-l-s
  cram_NAME
  RET

where NAME is e.g. language.

You're ready for some awesome programming! We recommend to go through the tutorials first. You might also find some useful links on the Getting Started page.