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 a package that can be built by colcon. It is also okay to have multiple, separate 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.

Package Type

We use colcon to build the software, so all code should be provided in packages that are supported by colcon. Typically, these are ROS 2 packages (see Creating a ROS 2 package) but vanilla Python or CMake packages should work as well.

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 a ros2 run 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 goal is passed to run encoded as a JSON string. So the actual command looks like this:

./run "[[0, [0.070, -0.025, 0.043]], [30000, [-0.090, 0.003, 0.084]], ...]"

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

Goal Sampling Settings

You repository may contain an optional file goal.json in the root directory in which you can specify a fixed goal.

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

  • “goal”: Optional. Use this to directly specify the goal you want to use for this submission. See the task descriptions for more information.

If no goal.json is found or if it does not contain a “goal” entry, a random one will be sampled.

The expected format of the “goal” field depends on the task and is specified in the description of the corresponding challenge stage. It matches with the format of the goal.json that is generated in the output files of a run (see Complete List of Generated Files).

Example specifying a custom goal for the cube trajectory task:

{
    "goal": [
        [0, [0.070, -0.025, 0.043]],
        [30000, [-0.090, 0.003, 0.084]],
        ...
    ]
}

You can check if your goal.json is valid before making a submission by running the following command, using the Singularity image (replace “move_cube_on_trajectory” with “rearrange_dice” depending on the task):

./rrc2021.sif python3 -m trifinger_simulation.tasks.move_cube_on_trajectory goal_from_config path/to/goal.json

If everything is correct, this will print exactly the goal that is specified in the file. Otherwise it should print an error indicating what is wrong.

Note that in the evaluation phase of the challenge, this file is ignored and your code is run on a set of randomly sampled goals.

Build Your Workspace Locally

You can locally build your workspace using 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 colcon build there:

$ cd workspace
$ singularity shell path/to/rrc2021.sif
Singularity> source /setup.bash  # to find packages from the image
Singularity> colcon build
Singularity> source install/local_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.

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

Singularity> ros2 run <package_name> <exectuable_name>

Note

If your workspace has dependencies which are not yet available in the default “rrc2021.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 packages. However, do not use any of the names already used in our software bundle to avoid conflicts:

  • blmc_drivers

  • mpi_cmake_modules

  • pybind11_opencv

  • 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_utils