Zero prerequisites demo tutorial: Simple fetch and place

This tutorial is from the “Demo Tutorials” category, which assumes no prior knowledge of Linux, ROS, Emacs, Lisp or robotics.

  • The presentation slides give a brief overview and introduction for this lecture and contain the most important informations on Emacs, our IDE for Lisp.
  • The virtual machine (VM) file to run with VirtualBox.
  • An explanation of the setup and first tutorial is also available with voice explanations (around 1h) as download or stream, for those with spare time on another day.


The aim of the tutorial is to give an intuition about the complexity of robot mobile manipulation tasks and about the knowledge that is required to execute actions successfully.

The tutorial:

  1. Gives an intuition of what knowledge does the robot need (and how much knowledge) to execute even a simple fetch and place, e.g., robot needs to answer questions such as “where should I stand?”, “which grasp pose should I use?”, etc.
  2. Shows how many different things can go wrong, and teaches writing simple failure handling strategies.
  3. Teaches how to call existing actions from the CRAM framework, i.e. how to use designators (but not program new ones).

Setting Up

You will need a virtual machine to run this tutorial. We use VirtualBox as a software to run virtual machines. This tutorial comes with a virtual machine (VM) image, which contains all the prerequisites required to run the system already preinstalled and set up. You just need to install VirtualBox, download the VM image and start it, and everything else has already been taken care of in the VM.

Technical Requirements

  • The VM image with VirtualBox has been successfully tested for Windows, MacOS and Ubuntu.
  • Some kind of GPU, dedicated or integrated, is required to visualize the running OS.
  • At least 8GB of excess RAM for the VM is recommended, 4GB minimum. The more the better.


First, download and install VirtualBox on your computer. Here are some hints on how to do that on Ubuntu, Arch, Windows and MacOS

Ubuntu Linux

You can install VirtualBox via the Ubuntu Software Center or through command line like so:

sudo apt update
sudo apt install virtualbox

Follow this tutorial for the install via pacman.


Download version 5.2.42 for Windows Systems, execute the .exe file and follow the installation instructions.

The CPU needs to support virtualization to run a VM on Windows. The virtualization can be enabled in the BIOS. To get into the BIOS settings restart your machine, hit the settings button while booting (try F2, F8 and F10) and go into the CPU settings. There is something like 'Intel Virtual Technology' or 'CPU Virtualization' which needs to be enabled.


Download the .dmg installer for OS X systems, execute the file and follow the instructions. Hint: If the VirtualBox installer fails with The installation failed where it encountered an error that caused the installation to fail. Go to System Preferences > Security & Privacy. Click the ‘Allow’ button at the bottom and re-run the installer.

VirtualBox Setup

First of all, download the Virtual Disk Image cram_vm.vdi here. It contains an Ubuntu 18.04 with ROS melodic pre-installed, as well as CRAM v0.7, the latest dev-version CRAM for Unreal, Urobosim for the Unreal interface, KnowRob as the knowledge hub, and Giskard, the motion planner.

Then, launch VirtualBox, which you installed in the previous step.

Inside VirtualBox, you first want to create a new virtual machine. Click on the 'New' button:

Usually the simplified menu will open. Change to expert mode, it won't get too complicated.

In this view the VM gets

  • the name 'cram-vm'
  • the OS as 'Linux'
  • the version as 'Ubuntu (64-bit)'

Choose the VM's memory size (RAM), depending on your machine's capacity, but less than 8GB will cause performance issues. We recommend to offer as much as possible, when working with unreal. CRAM on it's own can get by with less.

The Virtual Disc Image downloaded before can now be used. Instead of creating a new one, the VM is set to 'Use an existing virtual hard disk file'. Over the button at the right the program opens a file explorer, where the cram-vm.vdi needs to be found (usually in Downloads) and selected. Finally 'Create' the VM.

Settings (optional)

If the VM needs to communicate with the host or other machines in the network, especially when running the UnrealEngine on the host machine, VirtualBox needs to allow Bridged Networking for the VM. Choose the newly created VM and hit 'Settings', then go to 'Network'. With checked 'Enable Network Adapter' choose 'Bridged Adapter' and the preferred network interface. In this case, 'eno1' is the host's ethernet interface.

For better performance the VM could use some of the CPU's power. Go to 'System' and 'Processor' and choose how many processor cores you want to give the VM.

Everything is set up. The VM can now be started. The Ubuntu 18.04 system should start and automatically log into the only account, with the username and password 'cram'.

Last adjustments

There are two versions of CRAM available in the VM. By default, the setup is designed to connect and work with a project from the Unreal Engine, for intricate physics simulation. We don't need any of that for the upcoming tutorials, instead we change to the stable, standalone version of CRAM. In the VM, launch a terminal with Ctrl-Alt-T and open up the file .bashrc.

nano .bashrc

Put a # symbol in front of the source command for day 1 & 2 of the FallSchool, and remove it from the line below, referring to day 3 of the FallSchool. Save and close the file and type source .bashrc to activate the changes in your current terminal. From now on the changes are applied on every newly opened terminal.

By doing so, the terminal uses a different ROS workspace. Sourcing a ROS workspace enables the terminal session to access everything from that workspace, like loading a programming environment, or changing a namespace.

Understanding the Basics

Ubuntu Linux

The operating system installed in our virtual machine is an Ubuntu Linux, which is perhaps the most mainstream Linux version.

Launching a terminal

A terminal is a command line of the operating system. We will use terminals to start our programs.

To launch a terminal, press the Super Key (the windows key on the keyboard) to open a search bar, type in “terminal” and launch the program. Alternatively, you can use a keyboard shortcut for starting a terminal: “Ctrl + Alt + T


ROS stands for Robot Operating System. It is software that makes a robot programmer's life easier. For example, it allows programs written in different programming languages to talk to each other.


We are going to program our robot in the Lisp programming language.

This language has a convenient command line. If you are curious why Lisp, go here.

Tutorial 0: Getting into Emacs

Emacs is one of the oldest text editors and one of the two most popular text editors in the Linux world.

It is older than the Windows operating system, so its shortcuts are the old Unix shortcuts. For example, instead of “Ctrl-C – Ctrl-V” you have “Ctrl-K – Ctrl-Y”, which stands for “killing” and “yanking”. In a Linux terminal, “Ctrl-C – Ctrl-V” also don't exist, but “Ctrl-K – Ctrl-Y” do.

In addition to being a text editor, Emacs has a powerful plugin engine for running programs inside it. For example, with an email plugin you can read and write emails with Emacs, with a chat plugin you can talk to your friends over any common chat protocol, with a music plugin you can listen to radio through Emacs, with a C++ development plugin you can program in C++ with Emacs, etc.

We are going to use Emacs as an Interactive Development Environment (IDE) for programming our robot, so we will be using the Common Lisp programming plugin of Emacs (it is called Slime).

Launching Emacs

To launch Emacs with the IDE plugin, type into a terminal

$ roslisp_repl &

To see useful key shortcuts for your Emacs IDE, follow this link.

These slides contain a few important shortcuts, and introduce you to the popular 'Orc Battle' Lisp example from 'The Land of Lisp'.

Run and play the orc-battle.lisp program to get a feeling for Emacs.

Tutorial 1: Simple Fetch and Place

Tutorial 2 & 3: Failure Handling

When you got the fetch and place plan go to the exercise for failure handling.

Tutorial 4: Alternative Grasping Poses (Advanced)

Picking objects from different angles can be helpful in occluded environments. Go to the exercises on grasping poses to find out more.