Installation Guide

Installation Guide#

Compatability#

PyCRAM is compatible and tested with ROS1 Noetic/ Ubuntu20.04 and ROS2 Jazzy/ Ubuntu24.04. ROS2 Humble/ Ubuntu22.04 is not usable since the creation of messages is more strict and some problems may arise.

Support for ROS1 Noetic/ Ubuntu20.04 will be dropped in July 25

Installation#

The setup of PyCRAM can be divided in four steps:

  • Install ROS

  • Installing Dependencies

  • Cloning the PyCRAM repo

  • Building your ROS workspace

1. Step: Add a GitHub SSH key#

This guide expects you to have a GitHub account with an SSH key (you can read about adding a new ssh key here).

2. Step: Install ROS#

PyCRAM uses ROS for a variety of functionality, for this reason you need a working ROS installation on your machine. For information on how to install ROS please refer to the official documentation here for ROS1 Noetic or here for ROS2 Jazzy.

3. Step: Install General Dependencies#

The dependencies you will need are:

  • vcstool

  • curl

These are available via the Ubuntu apt-repos and can be installed via the terminal:

sudo apt-get install python3-vcstool curl

4. Step: Choose Installation Method#

You can install PyCRAM in two ways:

  • Using the install script

  • Manually

When using the install script, continue with the section install script. Manually installing PyCRAM depends on the version of Ubuntu you are using.

  • For Ubuntu 20.04 (ROS Noetic) follow the instructions in the section manual 20.04.

  • For Ubuntu 24.04 (ROS Jazzy) follow the instructions in the section manual 24.04.

5. Step: Installation with the install script#

The easiest way to install PyCRAM is to use the install script. This script will install all necessary dependencies and clone the PyCRAM repository into your ROS workspace. Furthermore, will it setup the Python environment for PyCRAM and install the necessary Python packages.

Additionally the script can install the IPython startup scripts which come in handy when using PyCRAM in an IPython shell for development.

To run the install script simply past the following command into a terminal:

curl -s https://raw.githubusercontent.com/cram2/pycram/dev/scripts/install.sh | bash

Afterwards continue with the steps under Step 6: Python Dependencies.

5. Step: Manual Install on Ubuntu24.04 (ROS Jazzy)#

Before installing PyCRAM you need to setup a ROS workspace into which PyCRAM can be cloned.

mkdir -p ~/workspace/ros/src
cd workspace/ros
colcon build --symlink-install
source install/setup.bash

If colcon build does not work this probably means that you did not source your ROS installation. Source it by invoking:

source /opt/ros/jazzy/setup.bash

Now you can install PyCRAM into your ROS workspace.

cd ~/workspace/ros/src
vcs import --input https://raw.githubusercontent.com/cram2/pycram/dev/rosinstall/pycram-ros2.rosinstall --recursive
cd ..
colcon build --symlink-install
source install/setup.bash
echo "source ~/workspace/ros/install/setup.bash" >> ~/.bashrc

Afterwards continue with the steps under Step 6: Python Dependencies.

5. Step: Manual Install on Ubuntu 20.04 (ROS Noetic)#

At first you need to install the catkin tools so we can use the ´´´colcon build´´´ command:

apt install python3-catkin-tools

Now we can setup a ROS workspace into which PyCRAM can be cloned.

mkdir -p ~/workspace/ros/src
cd workspace/ros
catkin build
source devel/setup.bash

If catkin build does not work this probably means that you did not source your ROS installation. Source it by invoking:

source /opt/ros/noetic/setup.bash

Now you can install PyCRAM into your ROS workspace.

cd ~/workspace/ros/src
vcs import --input https://raw.githubusercontent.com/cram2/pycram/dev/rosinstall/pycram.rosinstall --recursive
rosdep update
rosdep install --ignore-src --from-paths . -r
cd ..
catkin build
source devel/setup.bash
echo "source ~/workspace/ros/devel/setup.bash" >> ~/.bashrc

The cloning and setting up can take several minutes. After the command finishes you should see a number of repositories in your ROS workspace.

The cloned repository contains the source code for PyCRAM as well as two short demos which demonstrate how to use it.

Step 5.1: Building your ROS workspace#

Building and sourcing your ROS workspace using catkin compiles all ROS packages and manages the appending to the respective PATH variables. This is necessary to be able to import PyCRAM via the Python import system and to find the robot descriptions in the launch file.

If you have been following the tutorial steps until now you can skip this part.

You can build your ROS workspace with the following commands:

cd ~/workspace/ros
catkin build
source devel/setup.bash

Afterwards continue with the steps under Step 6: Python Dependencies.

Step 5.2: Using PyCRAM in ROS1#

If you want to use PyCRAM on a system running ROS1 you need to start a roscore beforehand, you can do this by running the following command in a terminal:

roscore

Step 6: Python Dependencies#

To install the Python dependencies we first need to setup a python-venv, we use the standard Python venv package for this. To start you need to install the respective venv version of the package.

apt install python<version>-venv

Now we need to navigate to the PyCRAM repository, create the Python venv and finally activate the venv.

cd ~/workspace/ros/src/pycram
python -m venv pycram-venv --system-site-packages
source pycram-venv/bin/activate

Now for the final part we can install the Python dependencies of PyCRAM but before we do that we need to update the pip and setuptools version.

pip install -U pip
pip install -U setuptools
pip install -r requirements.txt

Step 7. Verify the Installation#

To verify that the installation was successful, you can run the following command:

cd ~/workspace/ros/src/pycram
source pycram-venv/bin/activate
python -c "import pycram"

To further test the installation you can run the tests for action designator with the following command:

cd ~/workspace/ros/src/pycram
source pycram-venv/bin/activate
pip install pytest
python -m pytest -v test/test_designator/test_action_designator.py

Step 8. Using PyCRAM#

If you are using PyCRAM on a ROS1 system (e.g. Ubuntu20.04) you have to start up a roscore before using PyCRAM to avoid errors. You can start a roscore by typing the following command in a terminal:

roscore

To use PyCRAM you can do this simply by importing PyCRAM in your project.

import pycram

Appendix#

The instructions here are not needed to work with PyCRAM and are just additional info.

Setup your Development Environment#

If you installed PyCRAM and checked that the installation works you can continue with the next step of setting up your development environment by following the link here.

Building the documentation#

The documentation uses jupyter-book as engine. Building the documentation requires Python 3.9 to avoid dependency conflicts. To install Python 3.9 on Ubuntu 20.04, use the following commands:

sudo apt install python3.9

It is recommended to use a virtual environment to avoid conflicts with the system Python.

apt-get install python3-virtualenv
virtualenv -p python3.9 --system-site-packages build-doc
source build-doc/bin/activate

Install the requirements in your python interpreter.

cd ~/workspace/ros/src/pycram/doc
pip install -r requirements.txt

Run pycram and build the docs.

cd ~/workspace/ros
roslaunch pycram ik_and_description.launch
cd src/pycram/doc/source
jupyter-book build .

Show the index.

firefox _build/html/index.html
Contents