**********************************
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:

  - ``run``:  This is what will be executed on the robot.  See `The run Script`_.
  - ``goal.json``:  Specifies what goals are used when running your code.  See
    `Goal Sampling Settings`_.


.. 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`_


.. _run_script:

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
  :doc:`../simulation_phase/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:

  .. code-block:: json

     {
         "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:

.. code-block:: bash

    $ 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
   :ref:`singularity_extend_container`.

If you want to test your code locally in simulation, using the same setup as on
the real robot, see :doc:`run_in_simulation_locally`.


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


.. _ROS: http://ros.org
.. _Creating a ROS package: http://wiki.ros.org/catkin/Tutorials/CreatingPackage
.. _catkin_tools: https://catkin-tools.readthedocs.io/en/latest/index.html
.. _rrc_example_package: https://github.com/rr-learning/rrc_example_package