diff --git a/doc/breathing_cat.toml b/doc/breathing_cat.toml index d8ec05f..b3e3626 100644 --- a/doc/breathing_cat.toml +++ b/doc/breathing_cat.toml @@ -1,4 +1,5 @@ [intersphinx.mapping] +trifinger_docs = "https://open-dynamic-robot-initiative.github.io/trifinger_docs" robot_interfaces = "https://open-dynamic-robot-initiative.github.io/robot_interfaces" [mainpage] diff --git a/doc/installation.rst b/doc/installation.rst index 877e4f4..7502b06 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -1,146 +1,5 @@ Build Instructions ================== -We provide a Singularity image with all required dependencies to build and run -the software. See :doc:`singularity`. - -You can, of course, also use the package without Singularity. In this case you -need to install all dependencies locally, though. - - -Real-Time Requirements ----------------------- - -To ensure reliable communication with the robot hardware, a real-time Linux -kernel is needed. See :doc:`Real Time Setup in the documentation of -robot_interfaces ` - - -Get the Source --------------- - -**robot_fingers** depends on several other of our packages which are -organized in separate repositories. We therefore use a workspace management -tool called treep_ which allows easy cloning of multi-repository projects. - -treep can be installed via pip:: - - pip install treep - -Clone the treep configuration containing the "ROBOT_FINGERS" project:: - - git clone git@github.com:machines-in-motion/treep_machines_in_motion.git - -**Note:** treep searches for a configuration directory from the current working -directory upwards. So you can use treep in the directory in which you invoked -the ``git clone`` command above or any subdirectory. - -Now clone the project:: - - treep --clone ROBOT_FINGERS - -.. important:: - treep uses SSH to clone from GitHub. So for the above command to work, you - need a GitHub account with a registered SSH key. Further this key needs to - work without asking for a password everytime. To achieve this, run :: - - ssh-add - - first. - - -Build ------ - -With Singularity -~~~~~~~~~~~~~~~~ - -Go to the root directory of your workspace (the one containing the "src" folder) -and run the container in shell mode (see :doc:`singularity`):: - - singularity shell -e --no-home --bind=$(pwd) path/to/image.sif - -The current working directory gets automatically mounted into the container so -you can edit all the files from outside the container using your preferred -editor or IDE and all changes will directly be visible inside the container. -Vice versa modifications done from inside the container will modify the files on -the host system! - -Inside the container first set up the environment:: - - Singularity> source /setup.bash - -This will source the ROS `setup.bash` and do some other environment setup. - -Now you can build with:: - - Singularity> colcon build - - -Without Singularity -~~~~~~~~~~~~~~~~~~~ - -To build, cd into the ``workspace`` directory and build with:: - - colcon build - -This assumes that `colcon` and all build dependencies are installed. - - -Real-Time-Capable Build -~~~~~~~~~~~~~~~~~~~~~~~ - -When running a PREEMPT_RT Linux kernel, this is automatically detected at -build-time and build flags are set accordingly. If you want to make a real-time-capable -build while running a different kernel (e.g. the "lowlatency" kernel or when -cross-compiling), you need to explicity set the ``OS_VERSION``:: - - colcon build --cmake-args -DOS_VERSION=preempt-rt - - -.. note:: - - If you see the following output during initialisation of the robot, this - means you are running a non-real-time build. - - .. code-block:: text - - Warning this thread is not going to be real time. - - -Run Demo --------- - -When the build finished successfully, you can run one of the demos to see if -everything works. - -Before running anything, you need to source the ``setup.bash`` of the -workspace (this needs to be done every time you open a new terminal):: - - source ./install/setup.bash - - -As a first test, you can run the "fake robot" demo (which doesn't need an actual -robot to be connected):: - - ros2 run robot_fingers demo_fake_finger - -It should produce output like this:: - - Position: [299. 598. 897.] - Position: [ 599. 1198. 1797.] - Position: [ 899. 1798. 2697.] - Position: [1199. 2398. 3597.] - Position: [1499. 2998. 4497.] - Position: [1799. 3598. 5397.] - Position: [2099. 4198. 6297.] - -You can cancel it with Ctrl+C. - -For more demos (including the actual robot), see :doc:`getting_started`. - - - - - -.. _treep: https://pypi.org/project/treep/ +The ``robot_fingers`` package is part of the TriFinger software bundle. See +:ref:`trifinger_docs:install_software` in the TriFinger documentation. diff --git a/doc/singularity.rst b/doc/singularity.rst index 0493dd4..aba8685 100644 --- a/doc/singularity.rst +++ b/doc/singularity.rst @@ -1,141 +1,5 @@ About Apptainer/Singularity =========================== -What is Apptainer? ------------------- - -Apptainer (formerly called "Singularity") is a tool to run software inside -containers, similar to Docker. Compared to Docker it has a higher focus on -security and can be used without root permission. Also programs in the -container are executed as the user of the host system which makes it much more -convenient when touching files of the host system (as it is happening when -building a mounted workspace). - -.. note:: - - Singularity was recently renamed to Apptainer (so Apptainer 1.0 is basically - Singularity 3.9). In the following we assume that you are using Apptainer, - however, it probably works the same with recent releases (3.x) of - Singularity. Due to this, we are using the command `singularity` in the - following which should work with all versions (Apptainer installs a - corresponding alias). - - If you are using Apptainer, you can replace `singularity` with `apptainer` - but both should work the same. - - -Install Apptainer ------------------ - -You can download pre-build packages of recent releases from the `Apptainer -GitHub repository `_. - -For example on Ubuntu, download the deb package (called -"apptainer_X.Y.Z_amd64.deb" and install it with:: - - $ sudo apt install ./apptainer_X.Y.Z_amd64.deb - -In the following, we provide some basic information on how to use -Apptainer. For more detailed information, please see the `official -documentation`_. - - -Get our Apptainer Image ------------------------ - -We provide an Apptainer image with Ubuntu 20.04 with all dependencies needed to -build and run the software here. You can download the latest version using:: - - singularity pull oras://ghcr.io/open-dynamic-robot-initiative/trifinger_singularity/trifinger_base:latest - - -In case you prefer to build the image yourself, see the `trifinger_singularity -repository on GitHub -`_ - - -Run Something in the Container ------------------------------- - -To run the container in shell mode (i.e. opening a shell inside the container), -the following is often enough:: - - singularity shell path/to/image.sif - -This will, however, be influenced by your local setup as environment variables -are exported and the home directory is mounted by default. Further the current -working directory from which Apptainer is run is also bound inside the -container. - -This default behaviour is often convenient but can cause issues in some cases. -A typical example would be a Python package installed in your home directory -(which will then be available in the container) which is not compatible with -versions of other packages inside the container. To avoid these kind of issues -it is recommended to use the following command to run the container in a more -isolated way:: - - export SINGULARITYENV_DISPLAY=$DISPLAY - singularity shell -e --no-home --bind=$(pwd) path/to/image.sif - -The arguments explained: - -- The first line makes sure the DISPLAY environment variable is set correctly - inside the container (only needed if you want to run GUI-based applications). -- ``-e`` (short for ``--cleanenv``) prevents environment variables to be - exported. -- ``--no-home`` prevents your home directory from being bound. -- ``--bind=$(pwd)`` explicitly binds the current working directory. This is - needed if the working directory is inside your home directory as otherwise it - is excluded by the ``--no-home``. - -Note that with the above the current working directory is still bound in the -image, so it is possible to build/modify the workspace from the host-system when -Apptainer is run from the root directory of the workspace. - - -Compatibility with Nvidia Drivers -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When you are using Nvidia drivers and want to run a GUI-based application in the -container, you may need to add the ``--nv`` flag:: - - singularity shell --nv ... path/to/image.sif - - -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. - -To extend the image, create *definition file* like the following:: - - # Specify the name of the base image below - Bootstrap: localimage - From: ./base_image.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. Note that the base image -(specified in the ``From:`` line) needs to be present in the directory in -which you call the command. - -:: - - $ singularity build --fakeroot user_image.sif path/to/user_image.def - - -.. _official documentation: https://apptainer.org/docs/ -.. _Documentation for Definition Files: https://apptainer.org/docs/user/1.0/definition_files.html - +The content of this page has been moved to the :ref:`TriFinger documentation +`.