***************** About Singularity ***************** We are using Singularity_ to execute applications on the robots. With the provided image, you can test your code locally with simulation in the exact same environment as will be present on the real robot. The image we provide contains all dependencies to get started with the robot. If you want to use additional libraries in your own code, you can extend the image accordingly. .. _singularity_install: Install Singularity =================== Note that Singularity only runs on Linux. It may work with a virtual machine but it is recommended to use a computer with a native Linux installation (we are testing with Ubuntu but other distributions should also be fine). We are using **Singularity version 3.7.4**. To simplify the installation, we provide a pre-built Debian package: .. admonition:: Download `singularity-container_3.7.4-1.deb `_ SHA256: 1a2b0a8c6d510518cbc28b82e01fadbaec99175b70c23b7814c45ebc0cad1f13 After downloading you can install it with the following command:: $ sudo apt install ./singularity-container_3.7.4-1.deb You may also be able to install Singularity from the official package repositories of your Linux distribution, however, the version you get this way may not be up-to-date. Slightly older version are probably fine, but we cannot guarantee compatibility for those. If none of the above works for you, you can install it from source. For this see the `official installation instructions`_. .. _singularity_download_image: Download the Real Robot Challenge Image ======================================= You can directly pull the image from the Singularity cloud library:: $ singularity pull library://felix.widmaier/rrc/rrc2021:latest The image uses Ubuntu 20.04 and has all dependencies of the robot software and the simulation already installed. For most of the libraries we use the default version provided through the official Ubuntu repositories. To explore the image and to check which libraries and which versions exactly are installed, you can open a shell inside the container, see :ref:`singularity_shell`. Using the Singularity Image =========================== This is a brief introduction to the basic usage of the Singularity image. For more information, see the `official documentation`_. Singularity is a tool to run applications in isolated images (also often called "containers"), similar to the more widely known Docker. We use it as it is an easy way to provide you with a well-defined environment that contains the proper versions of all dependencies, independent of what you have installed locally on your system. This ensures that the applications will run in the same way on different machines. .. important:: By default, Singularity is not fully isolated. For example the whole home directly is bound into the container at run time. This can impair reproducibility. See :ref:`singularity_isolation` on how to make it more isolated. .. _singularity_run: Run a Command using the Singularity Image ----------------------------------------- You can run commands inside the Singularity image. They will have access to everything installed in the image and will be more or less isolated from your host system (see :ref:`singularity_isolation`). :: $ singularity run rrc2021.sif python3 path/to/some/script.py To give a more concrete example, the following runs the simulation with a demo script, moving the robot to random positions (the ``--nv`` flag is only needed if you are using Nvidia drivers, otherwise you have to remove it, see :ref:`singularity_nv`):: $ singularity run --nv rrc2021.sif ros2 run trifinger_simulation demo_trifinger_platform.py .. note:: If the image file is marked as executable, you can also drop ``singularity run`` and directly execute the file. However, this way you cannot pass additional arguments like ``--nv`` to Singularity. .. _singularity_shell: Open a Shell in the Image ------------------------- With the command above, you can only run a single command inside the image environment. If you want to run multiple commands in a row, preserving the environment, you open a shell in the container:: $ singularity shell path/to/rrc2021.sif Once inside the container, run the following commands:: Singularity> source /setup.bash This is mostly needed set up the ROS environment, so the TriFinger-related software packages are found. Now you can again run commands like the demo script (you may need to pass ``--nv`` to ``singularity shell``, see :ref:`singularity_nv`):: Singularity> ros2 run trifinger_simulation demo_trifinger_platform.py .. _singularity_isolation: Ensure Isolation from the Host System ------------------------------------- By default Singularity is not completely isolated from the host system. If run without arguments, it automatically binds the full home directory of the user, the ``/tmp`` directory and a few system directories into the image. While this is usually very convenient, it can cause some trouble. For example, Python may find packages that are installed in your home which may be conflicting with versions installed in the container. Further it can impair reproducability, as your code may unintentionally use some package from your home directory which are not available when executed on a different machine. To avoid these problems, you can run Singularity with the following command, to be more isolated:: $ export SINGULARITYENV_DISPLAY=$DISPLAY $ singularity shell --cleanenv --no-home -B path/to/workspace path/to/rrc2021.sif - ``--cleanenv``: Do not export all environment variables from the host into the image. Since the environment variable ``DISPLAY`` needs to be set in order to run graphical applications, it is still exported into the image by setting ``SINGULARITYENV_DISPLAY`` in the first line. - ``--no-home``: Do not bind the full home directory. Other directories like ``/tmp`` are still bound. You may use ``--contain`` to exclude those as well. - ``-B path/to/workspace``: Explicitly bind your workspace, so it is accessible in the container. You can list multiple directories separated by commas. For more information, please refer to the `official documentation`_ of Singularity. .. _singularity_nv: Running GUI-Applications in Singularity --------------------------------------- When running applications that use GPU-based rendering (e.g. the pyBullet visualisation) on a computer with Nvidia drivers, you may need to add the `--nv` flag when running Singularity. :: $ singularity run --nv rrc2021.sif or :: $ singularity shell --nv rrc2021.sif See the `Singularity documentation on GPU Support`_ for more information. .. _singularity_build_ws: Build and Run Code in Singularity ================================= When developing your code using Singularity, you need to build and run it inside the container. An easy way to do this is to create a workspace on your computer and then open the image in "shell" mode, binding the workspace into the container so it can be accessed/modifed from there. .. admonition:: Set up the Workspace The workspace should have the following structure:: workspace └── src └── my_package To get started with example package:: $ mkdir -p workspace/src $ cd workspace/src $ git clone https://github.com/rr-learning/rrc_example_package.git Open a shell using the Singularity image, binding the workspace into it: .. code-block:: bash $ export SINGULARITYENV_DISPLAY=$DISPLAY # only needed for graphical applications $ singularity shell -e --no-home -B path/to/workspace path/to/rrc2021.sif If you want to run graphical applications (like pyBullet's visualisation) on a machine using Nvidia drivers, you need to add ``--nv`` to the list of arguments, see :ref:`singularity_nv`. Once inside the container, run the following commands to set up the environment and build the workspace:: Singularity> source /setup.bash Singularity> cd path/to/workspace Singularity> colcon build Singularity> source install/local_setup.bash Now you can execute your code inside the container. For example, to run the simulation demos of the example package:: Singularity> ros2 run rrc_example_package sim_move_up_and_down or :: Singularity> ros2 run rrc_example_package sim_trajectory_example_with_gym Some things to keep in mind: - You need to run ``colcon build`` again, after making modifications in the code. - ``colcon build`` always needs to be run from the workspace's root directory (the one containing the ``src`` directory). - I you add custom scripts and want them to be executable with ``ros2 run``, you need to add them as ``entry_points`` in the ``setup.py`` (see the existing examples there). .. _singularity_extend_container: .. _singularity_custom_image: Add Custom Dependencies to the Container ======================================== The image we provide already includes everything needed to run the robot and the simulation. However, you may need additional libraries to use them in our own code, which are not yet present. In this case, you can create your own image which is based on our standard image but extends it with your additional dependencies. Note that you don't need to add your own code for the challenge to the image as this will be provided separately. So you only need to create a custom image if you want to install dependencies that are not yet available in the default image. Create the Custom Image ----------------------- To extend the image, create *definition file* like the following: :: # Use the rrc2021 image as base Bootstrap: library From: felix.widmaier/rrc/rrc2021:latest # alternatively to the above, you can specify the path to a local image: # Bootstrap: localimage # From: ./rrc2021.sif %post # Put commands to install additional dependencies here. # Make sure everything runs automatically without human input (e.g. add # `-y` to automatically say "yes" below). apt-get install -y package_name See the official `Documentation for Definition Files`_ for all options in the definition file. Assuming you called your definition file ``user_image.def``, use the following command to build the image:: $ singularity build --fakeroot user_image.sif path/to/user_image.def .. warning:: To ensure that your custom image is compatible with our setup for executing the code, always use the official image as base and avoid overwriting existing libraries or applications with different versions. Upload the Custom Image ----------------------- To use your custom image on the robot (stages 1 and 2), you will need to upload it and update your configuration. See :ref:`Configuration `. .. _Singularity: https://singularity.hpcng.org .. _official documentation: https://singularity.hpcng.org/user-docs/3.7/ .. _Documentation for Definition Files: https://singularity.hpcng.org/user-docs/3.7/definition_files.html .. _official installation instructions: https://singularity.hpcng.org/user-docs/3.7/quick_start.html#quick-installation-steps .. _Singularity documentation on GPU Support: https://singularity.hpcng.org/user-docs/3.7/gpu.html