Getting Started

Prerequisites

Docker
We provide docker images to simplify the installation of all the software dependencies. To use these image, you need to install docker first. Please follow these instructions to install docker.

Git LFS
The repository uses git LFS for large files, in particular for 3D simulation assets. To clone these large files, you need to install git LFS. Please follow these instructions to install git LFS.

Clone

To use this repository, first clone it including the submodules. If you are a contributor with an SSH-key linked, clone via SSH:

git clone --recurse-submodules git@github.com:alliander-opensource/rcdt_robotics.git

If you only want to use the repository without contributing, you can clone via HTTP:

git clone --recurse-submodules https://github.com/alliander-opensource/rcdt_robotics.git

In case you cloned the repository, but forgot to pass the --recurse-submodules flag, this can be fixed by running:

git submodule update --init --recursive

Run the container

To run a container from our Docker image, simply execute the run command in the root of the repository:

. run

This will pull an image from our Docker Hub. If this is the first time, it can take quite some time to pull the image. When pulling is finished, the image is started which can be seen by the user-name changing to white in the terminal. You can now execute commands inside the docker container.

After starting, the terminal is located in the home directory: /home/rcdt. The repository you you cloned is mounted and can be found at /home/rcdt/rcdt_robotics. Got to this directory by executing:

cd rcdt_robotics

Note

The image that is pulled is automatically determined based on your current local branch. If the main branch is selected, it will use rcdt/robotics:latest. If you are on a branch that contains changes in the Docker files and a pull request is made, a corresponding Docker Image is automatically build by Github and pushed to Docker Hub. The run script will now use this new image when available.

Build ROS packages

The ROS packages are located in the ros2_ws/src directory inside the repository. It is recommend to build the ROS package inside the ros2_ws directory. First go to this directory:

cd ros2_ws

To build the ROS packages, we use colcon. We recommend to build with the --symlink-install flag. This will make symlinks between the build files and source files. Changes to Python, YAML or Launch files are now automatically applied without the need of rebuilding. Run the command to build the ROS packages:

colcon build --symlink-install

After building, you need to source the files you build:

source /home/rcdt/ros2_ws/install/setup.bash

Note

With the --symlink-install flag, only changes to files that did exist while building are automatically applied. If you make changes to the file structure (rename or create files), you still need to build again.

Note

To simplify the process of building, you can add an alias to your personal bashrc file in the root of the repository (.personal.bashrc). You could for example add:

alias cb="cd /home/rcdt/rcdt_robotics/ros2_ws; colcon build --symlink-install; source install/setup.bash"

From now on, when you open a new terminal, this alias is available and you can simply build and source using the cb command.

Launch ROS

You can now launch ROS by running a launch file from one of the ROS packages. You could for example start the Franka launch file:

ros2 launch rcdt_franka franka.launch.py

This will start the simulation of the Franka arm. You can stop by pressing CTRL+C in the running terminal.

Note

It is possible to pass launch arguments as additional flags in the format <argument>:=<value>. To see which launch arguments are available, run the launch command with an -s flag:

ros2 launch rcdt_franka franka.launch.py -s