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

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


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.


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


.. _user_code_goal_json:

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
:ref:`list_of_generated_files`).

Example specifying a custom goal for the :doc:`cube trajectory task
<../task_trajectory>`:

  .. code-block::

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

.. code-block:: bash

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


.. _ROS: http://ros.org
.. _Creating a ROS 2 package: https://docs.ros.org/en/foxy/Tutorials/Creating-Your-First-ROS2-Package.html
.. _colcon: https://colcon.readthedocs.io/en/released/index.html