CRAM installation

If you get into problems, please consult the Support page.

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.

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

The core components of CRAM should also work on newer Ubuntu versions under ROS Jade, as well as on older systems 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

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

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

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

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

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

CRAM is a big system that has some external dependencies. Most of them are automatically installed as Debian packages, one you need to install from source: the knowledge processing system KnowRob. We recommend to create separate chained (overlaid) ROS workspaces for different components to make compilation faster and easier. (KnowRob is partly written in rosjava and if you will have it in the same workspace with another 10 packages its sole presence in the workspace will make the compilation of your 10 packages many times longer.) You can read more on workspace overlaying here.

(If you don't like the idea of having a separate workspace for KnowRob and you're well familiar with ROS the only thing you will need to install CRAM is this .rosinstall file.)

We recommend to create 3 new workspaces chained as following:

bottom -> knowledge base workspace -> cram workspace -> your cram development or top-level workspace

where bottom is either your current workspace, or if you don't have one, the ROS preinstalled workspace in /opt/ros/….

To make sure your bottom workspace exists, execute $ roscd in the shell. If that doesn't work, go through ROS installation page again (specifically, the part with sourcing /opt/ros/indigo/setup.bash ;) ).

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

$ mkdir -p ~/workspace/ros_kb/src # kb for knowledge base
$ cd ~/workspace/ros_kb
$ catkin_make
$ source devel/setup.bash
 
$ mkdir -p ~/workspace/ros_lisp/src
$ cd ~/workspace/ros_lisp
$ catkin_make
$ source devel/setup.bash
 
$ mkdir -p ~/workspace/ros_top/src
$ cd ~/workspace/ros_top
$ catkin_make
$ source devel/setup.bash

Now if you execute roscd you will end up in ros_top/devel. In this workspace you can put your own packages that are based on CRAM. You can also omit the part with ros_top and just use the ros_lisp workspace for your own roslisp packages.

In any case, don't forget to change the corresponding entry of your ~/.bashrc:

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

The knowledge base workspace will be used for installing KnowRob, which is a knowledge management system that CRAM uses for retrieving knowledge mostly about the environment, sometimes common-sense knowledge etc. We only need the basic installation from the official Knowrob installation webpage. It comes down to, first, installing rosjava, which can be done through apt-get, and then checking out and compiling KnowRob code:

$ sudo apt-get install ros-DISTRO-rosjava # where DISTRO is Indigo or Jade etc.
$ rosdep update
$ cd ~/workspace/ros_kb/src
$ wstool init
$ wstool merge https://raw.github.com/knowrob/knowrob/master/rosinstall/knowrob-base.rosinstall
$ wstool update
$ rosdep install --ignore-src --from-paths stacks/
$ cd ~/workspace/ros_kb
$ catkin_make

Check out and compile all the necessary repositories.

$ cd ~/workspace/ros_lisp/src
$ wstool init
$ wstool merge https://raw.githubusercontent.com/cram2/cram_projection_demos/master/cram-with-projection.rosinstall
$ wstool update
$ cd ~/workspace/ros_lisp
$ 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. Before executing this step you can edit your ~/workspace/ros_lisp/src/.rosinstall file and comment out the CRAM repositories that you don't expect to be using. See the comments inside the file for more details.

If the compilation went through 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.

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).

You'll have to perform the following steps:

If you don't have the latest version of ROS, install it. (The desktop non-full version should be enough.)
Currently supported versions of ROS in CRAM are Hydro and Groovy.
Don't forget to

$ sudo rosdep init
$ rosdep update

Install roslisp_common and roslisp_repl:

$ sudo apt-get install ros-hydro-roslisp-common
$ sudo apt-get install ros-hydro-roslisp-repl

The source code can be found on GitHub:
roslisp_common: https://github.com/ros/roslisp_common
roslisp_repl: https://github.com/ros/roslisp_repl

  sudo apt-get install ros-hydro-cram-core

The source code is hosted on GitHub:
cram_core: https://github.com/cram-code/cram_core

You're done.

If you're planning to participate in the development of CRAM or to write your own CRAM packages, in addition to the above-mentioned steps do the following:

Install the wstool and rosinstall, they are available as Debians:

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

Set up your ROS workspaces. Until all the CRAM packages get catkinized, you will need both catkin and rosbuild workspaces (need more details: check here). However, if you are only going to use the core of CRAM, the catkin workspace would be sufficient.

Go to your catkin workspace and use wstool to pull the source of the core CRAM packages from GIT: cram_core and it's dependency cram_3rdparty.

$ cd MY_CATKIN_WORKSPACE_PATH/src
$ wstool init
$ wstool set cram_core --git https://github.com/cram-code/cram_core.git
$ wstool set cram_3rdparty --git https://github.com/cram-code/cram_3rdparty.git

where MY_CATKIN_WORKSPACE_PATH is, e.g., ~/workspace/catkin.
If you already called wstool init before, skip this particular command.

wstool is nothing more than a tool for getting updates from all your Git repositories at once, so that you could call wstool update once instead of cd MY_GIT_REPO && git pull multiple times. For more information about wstool check out its page on ROS wiki.

Finally, let ROS acknowledge the new packages, and build them:

$ wstool update
$ rospack profile
$ source ~/.bashrc

$ cd ..                 (i.e. cd MY_CATKIN_WORKSPACE_PATH)
$ catkin_make
$ catkin_make install

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 enjoy the repl animation ;)

$ 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 Lisp programming. Check out the Getting Started section if you need more info.

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).

If you need more than just the core functionality of CRAM but also the other major components, in addition to the above-mentioned steps do the following:

Go to your catkin workspace (or rosbuild workspace depending on the package) and use wstool to pull the CRAM stacks from GIT. We recommend you to get the code from the following major CRAM repos: cram_highlevel, cram_physics, cram_pr2, cram_bridge.
Please note that they are currently in active development.
cram_highlevel is a catkinized metapackege, the rest is rosbuild at the moment.

$ cd ~/workspace/rosbuild              (or cd ~/workspace/catkin)
$ wstool set cram_NAME --git https://github.com/cram-code/cram_NAME.git
$ wstool update
$ rospack profile
$ source setup.bash

where NAME: highlevel, physics, pr2, …

Rosmake and install the CRAM packages you want to use:

$ rosdep install cram_NAME
$ rosmake cram_NAME
$ rosdep install --from-paths src -i -y # in the workspace root

The above commands might not work on the catkin metapackages that you've put into your workspace just now, so you might want to build them using catkin:

$ cd ~/workspace/catkin
$ catkin_make

Some of the CRAM packages have external dependencies. Most of them will be resolved using the rosdep install command, it will install all the system dependencies needed for your packages. The command might not work recursively, so you might need to call it on separate packages of the metapackage.

The rosmake command is essential for some packages, as in some cases the source code of the 3rd party package is being downloaded using the make scripts.

Don't forget to compile the package in Lisp after using the rosmake:

  (ros-load:load-system "cram_NAME" "cram-NAME")

Sometimes a restart of your Lisp environment is necessary after a rosmake recompilation.

If your package didn't compile continue reading to get the missing dependencies.

The packages in cram_highlevel that use a knowledge base have dependencies on the package json_prolog from KnowRob. To install KnowRob you will also need rosjava_jni and cmake_modules.

$ sudo apt-get install ros-hydro-cmake-modules
$ roscd
$ wstool set rosjava_jni --git https://github.com/gheorghelisca/rosjava_jni.git
$ rosws merge https://raw.github.com/knowrob/knowrob/master/rosinstall/knowrob-all.rosinstall
$ wstool update
$ rospack profile
$ source ~/.bashrc
$ rosdep install rosjava_jni
$ rosmake rosjava_jni
$ rosdep install knowrob
$ rosmake knowrob

In order to use json_prolog from knowrob and other java using packages you need to have JAVA_HOME set up in your environment. For that add export JAVA_HOME=/usr/lib/jvm/java-MY_NEWEST_VERSION_OF_JAVA_HERE to your ~/.bashrc.

One of the major features of KnowRob utilized in CRAM are the semantic maps of the environment. The main maps used for the indoor scenarios in the CRAM development team can be found in the iai_maps Git repo under code-iai. They have a dependency on the robot_state_chain_publisher and map_server, so you'll need that too.

$ cd MY_CATKIN_WORKSPACE/src
$ wstool set robot_state_chain_publisher --git https://github.com/code-iai/robot_state_chain_publisher.git
$ wstool update
$ cd ..
$ catkin_make

$ sudo apt-get install ros-hydro-map-server
$ roscd
$ wstool set iai_maps --git https://github.com/code-iai/iai_maps.git
$ wstool update iai_maps
$ rospack profile
$ source ~/.bashrc
$ rosmake iai_maps

The iai_maps package needs the official navigation stack for displaying the collision map, so you might need that as well at some point:

$ sudo apt-get install ros-hydro-navigation

If you have a problem with rosdep, you can as well install the missing dependencies manually. Use rosdep check STACK_NAME to find out what's needed.

If you're getting autoconf error messages, do sudo apt-get install autoconf. (← this should go into FAQ)

If there will be a problem with json_prolog, you might want to try using java-6 instead of java-7. For that you'd have to add the following lines to your ~/.bashrc:

  JAVA_HOME=/usr/lib/jvm/java-6-openjdk
  export JAVA_HOME
  PATH=$PATH:$JAVA_HOME
  export PATH

Another set of dependencies is on moveit_msgs (arm_navigation_msgs in the past). You will also need an inverse kinematics solver to do grasping in the simulation (or on the real robot, why not). So you might want to install MoveIt:

$ sudo apt-get install ros-hydro-moveit-full-pr2
$ rospack profile
$ source ~/.bashrc

bullet_reasoning has a dependency on the household objects database messages from ROS, the corresponding package is ros-hydro-household-objects-database-msgs.

pr2_reachability_costmap has a dependency on iai_kinematics_msgs. They can be found on github:

$ cd MY_CATKIN_WORKSPACE/src
$ wstool set iai_common_msgs --git https://github.com/code-iai/iai_common_msgs.git
$ wstool update iai_common_msgs
$ cd ..
$ catkin_make

If you for some reason will want to have the sources of the ROS Lisp packages, they can be found here: https://github.com/ros/roslispNAME.git, where NAME: _common, _repl or nil. You can clone and compile them in your catkin workspace just like you did with the catkinized CRAM packages.

The .rosinstall file you could use to speed up the installation is described here.