Attention

This challenge has ended!

This documentation is only for the Real Robot Challenge 2020 which has ended. Following challenges have their own documentation, see the challenge website for more information.

Structure of the User Code Package

In order to be able to execute your code on our robots, you need to follow a few rules regarding the structure:

  • All code needs to be in a single git repository. You may use git submodules to add content of other repositories.

  • Your code should be provided as catkin package(s). It is okay to have multiple, separate catkin packages in the repository.

  • Apart from your code, the repository needs to contain the following files at the root directory:

Note

See rrc_example_package for a example package using Python to control the robot. You can use this package as base for your own one.

Catkin Package

We use catkin to build the software, so all code should be provided as catkin packages. Catkin is the build tool of ROS, so if you worked with robots before, chances are high that you are already familiar with it. If not, please see Creating a ROS package

The run Script

When submitting a job to the robot, the system will look for an executable file called run (without any extension) at the root of your repository and execute it.

So you need to provide such a file and make sure that it is executable, i.e.

  • the executable flag is set (can be done with chmod a+x run), and

  • it contains a valid shebang line at the top (e.g. #!/bin/bash for bash or #!/usr/bin/python3 for Python).

This can, for example, be a Bash script with the rosrun command to run our application or directly some Python script. It can also be a symlink to a script somewhere else inside your repository.

When executed, the script will be passed the goal difficulty level and a JSON string with the goal pose as arguments. So the actual command looks like this:

./run 1 '{"position": [-0.08, 0.09, 0.0325], "orientation": [0, 0, 0, 1]}'

This is the goal which you should try to reach in this run. The difficulty level is passed as it is needed to compute the reward. In your run script, you should always use the goal/difficulty that is passed like this to ensure that your code will work correctly during evaluation. You can specify the difficulty level and optionally set a fixed goal for your traingin/testing in the file goal.json (see Goal Sampling Settings).

Goal Sampling Settings

You repository need to contain a file goal.json in the root directory in which you can configure the difficulty level of your goal and whether you want to use a randomly sample goal or a fixed one.

The file needs to be a JSON file with the following keys:

  • “difficulty”: Mandatory. Difficulty level of the goals (see Details of the Tasks). This is used for sampling a goal if none is specified and for computing the reward.

  • “goal”: Optional. Use this to directly specify the goal you want to use for this submission. The goal consists of two fields “position” (list of x-, y- and z-position) and “orientation” (quaternion of the form [x, y, z, w]).

    If no goal is specified, a random one will be sampled.

Full example specifying a custom goal:

{
    "difficulty": 3,
    "goal": {
        "position": [0, 0.1, 0.06],
        "orientation": [0, 0, 0, 1]
    }
}

There is a tool with which you can check if your goal.json is valid before making a submission. Using the Singularity image, run:

./realrobotchallenge.sif python3 -m trifinger_simulation.tasks \
    move_cube validate_goal_file goal.json

It will print an error and return with a non-zero code in case there is some problem with the file.

Note that in the evaluation phase of the challenge, this file is ignored and your code is run with sampled goals of all difficulty levels.

Build Your Workspace Locally

To locally build your workspace with dependencies on our packages you can use the Singularity image.

Assuming your workspace has the following structure:

workspace
└── src
    ├── your_package_1
    ├── your_package_2
    └── ...

To build the workspace, cd to the workspace, run the Singularity image in shell mode and run catkin there:

$ cd workspace
$ singularity shell path/to/realrobotchallenge.sif
Singularity> source /setup.bash       # to find packages from the image
Singularity> catbuild
Singularity> source devel/setup.bash  # to find packages from your workspace

The call of source /setup.bash is needed to setup the environment so that the packages installed inside the image are found. Further it defines the catbuild alias which is simply short for:

catkin build -DPYTHON_EXECUTABLE=/usr/bin/python3

This ensures that the Python bindings are build for Python 3 (default would be Python 2).

After sourcing devel/setup.bash of your workspace, you can run executables inside Singularity using rosrun:

Singularity> rosrun <package_name> <exectuable_name>

Note

If your workspace has dependencies which are not yet available in the default “realrobotchallenge.sif” image, you can create your own extended image, see Add Custom Dependencies to the Container.

If you want to test your code locally in simulation, using the same setup as on the real robot, see How to Locally Run Your Code in Simulation.

Reserved Package Names

There are no specific rules on how to name your catkin packages. However, do not use any of the names already used in our software bundle to avoid conflicts:

  • ati_ft_sensor

  • blmc_drivers

  • blmc_robots

  • mpi_cmake_modules

  • pybind11

  • pybind11_catkin

  • real_time_tools

  • robot_fingers

  • robot_interfaces

  • robot_properties_fingers

  • serialization_utils

  • shared_memory

  • signal_handler

  • time_series

  • trifinger_cameras

  • trifinger_object_tracking

  • trifinger_simulation

  • yaml_cpp_catkin