-
Notifications
You must be signed in to change notification settings - Fork 14
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #170 from open-dynamic-robot-initiative/fkloss/doc
doc: Link to trifinger_docs
- Loading branch information
Showing
3 changed files
with
5 additions
and
281 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 <robot_interfaces:doc/real_time>` | ||
|
|
||
|
|
||
| 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 [email protected]: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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 <https://github.com/apptainer/apptainer/releases/>`_. | ||
|
|
||
| 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 | ||
| <https://github.com/open-dynamic-robot-initiative/trifinger_singularity>`_ | ||
|
|
||
|
|
||
| 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 | ||
| <trifinger_docs:about_apptainer>`. |