Merge pull request #75 from atom-robotics-lab/sani/wiki_updates

markdown/ros/ROS_installation/ROS_index.rst

@@ -0,0 +1,139 @@
+ROS 2 Installation
+================
+This section serves as an installation guide for setting up the ``ROS 2 Humble`` on **Linux** operating system.
+``ROS 2`` is a widely used framework for [email protected]:atom-robotics-lab/wiki.giteloping robotics software.
+
+This guide provides step-by-step instructions for installing ``ROS 2``, allowing developers and enthusiasts to get started
+with building robotic applications.
+
+-  This Document assumes that the reader has installed Ubuntu 22.04.
+   However, if you haven’t installed Ubuntu 22.04 yet make sure to
+   install it before proceeding.
+-  There are tons of resources available on the Internet to get this
+   done.
+-  You can download Ubuntu 22.04 ISO (Desktop Image) file from
+   `here <https://releases.ubuntu.com/jammy/>`__.
+
+ROS 2 Humble Installation
+-----------------------
+
+Set locale
+----------
+
+Make sure you have a locale which supports ``UTF-8``.
+If you are in a minimal environment (such as a docker container), the locale may be something minimal like ``POSIX``.
+We test with the following settings. However, it should be fine if you're using a different UTF-8 supported locale.
+
+.. code-block:: bash
+
+   locale  # check for UTF-8
+
+   sudo apt update && sudo apt install locales
+   sudo locale-gen en_US en_US.UTF-8
+   sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
+   export LANG=en_US.UTF-8
+
+   locale  # verify settings
+
+Setup Sources
+-------------
+
+You will need to add the ROS 2 apt repository to your system.
+
+First ensure that the `Ubuntu Universe repository <https://help.ubuntu.com/community/Repositories/Ubuntu>`_ is enabled.
+
+.. code-block:: bash
+
+   sudo apt install software-properties-common
+   sudo add-apt-repository universe
+
+Now add the ROS 2 GPG key with apt.
+
+.. code-block:: bash
+
+   sudo apt update && sudo apt install curl -y
+   sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
+
+Then add the repository to your sources list.
+
+.. code-block:: bash
+
+   echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null
+
+Install ROS 2 packages
+----------------------
+
+Update your apt repository caches after setting up the repositories.
+
+.. code-block:: bash
+
+   sudo apt update
+
+.. include:: _Apt-Upgrade-Admonition.rst
+
+.. warning::
+
+   Due to early updates in Ubuntu 22.04 it is important that ``systemd`` and ``udev``-related packages are updated before installing ROS 2.
+   The installation of ROS 2's dependencies on a freshly installed system without upgrading can trigger the **removal of critical system packages**.
+
+   Please refer to `ros2/ros2#1272 <https://github.com/ros2/ros2/issues/1272>`_ and `Launchpad #1974196 <https://bugs.launchpad.net/ubuntu/+source/systemd/+bug/1974196>`_ for more information.
+
+Desktop Install (Recommended): ROS, RViz, demos, tutorials.
+
+.. code-block:: bash
+
+   sudo apt install ros-{DISTRO}-desktop
+
+ROS-Base Install (Bare Bones): Communication libraries, message packages, command line tools.
+No GUI tools.
+
+.. code-block:: bash
+
+   sudo apt install ros-{DISTRO}-ros-base
+
+Development tools: Compilers and other tools to build ROS packages
+
+.. code-block:: bash
+
+   sudo apt install ros-dev-tools
+
+Environment setup
+-----------------
+
+Sourcing the setup script
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Set up your environment by sourcing the following file.
+
+.. code-block:: bash
+
+   # Replace ".bash" with your shell if you're not using bash
+   # Possible values are: setup.bash, setup.sh, setup.zsh
+   source /opt/ros/{DISTRO}/setup.bash
+
+Try some examples
+-----------------
+
+Talker-listener
+^^^^^^^^^^^^^^^
+
+If you installed ``ros-{DISTRO}-desktop`` above you can try some examples.
+
+In one terminal, source the setup file and then run a C++ ``talker``\ :
+
+.. code-block:: bash
+
+   source /opt/ros/{DISTRO}/setup.bash
+   ros2 run demo_nodes_cpp talker
+
+In another terminal source the setup file and then run a Python ``listener``\ :
+
+.. code-block:: bash
+
+   source /opt/ros/{DISTRO}/setup.bash
+   ros2 run demo_nodes_py listener
+
+You should see the ``talker`` saying that it's ``Publishing`` messages and the ``listener`` saying ``I heard`` those messages.
+This verifies both the C++ and Python APIs are working properly.
+Hooray!
+

markdown/ros/colcon_ws.rst

@@ -0,0 +1,140 @@
+Creating a workspace
+====================
+
+**Goal:** Create a workspace and learn how to set up an overlay for development and testing.
+
+.. contents:: Contents
+   :depth: 2
+   :local:
+
+Background
+----------
+
+A workspace is a directory containing ROS 2 packages.
+Before using ROS 2, it's necessary to source your ROS 2 installation workspace in the terminal you plan to work in.
+This makes ROS 2's packages available for you to use in that terminal.
+
+
+
+1 Source ROS 2 environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Your main ROS 2 installation will be your underlay for this tutorial.
+(Keep in mind that an underlay does not necessarily have to be the main ROS 2 installation.)
+
+Depending on how you installed ROS 2 (from source or binaries), and which platform you're on, your exact source command will vary:
+
+
+.. code-block:: console
+
+  source /opt/ros/{DISTRO}/setup.bash
+
+
+.. _new-directory:
+
+2 Create a new directory
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Best practice is to create a new directory for every new workspace.
+The name doesn't matter, but it is helpful to have it indicate the purpose of the workspace.
+Let's choose the directory name ``ros2_ws``, for "development workspace":
+
+
+.. code-block:: console
+
+  mkdir -p ~/ros2_ws/src
+  cd ~/ros2_ws/src
+
+
+
+Another best practice is to put any packages in your workspace into the ``src`` directory.
+The above code creates a ``src`` directory inside ``ros2_ws`` and then navigates into it.
+
+
+3 Build the workspace with colcon
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+From the root of your workspace (``/ros2_ws``), you can now build your packages using the command:
+
+
+
+
+.. code-block:: console
+
+  colcon build
+
+
+The console will return the following message:
+
+.. code-block:: console
+
+  Summary: 0 packages finished [0.28s]
+
+.. note::
+
+  Other useful arguments for ``colcon build``:
+
+  * ``--packages-up-to`` builds the package you want, plus all its dependencies, but not the whole workspace (saves time)
+  * ``--symlink-install`` saves you from having to rebuild every time you tweak python scripts
+  * ``--event-handlers console_direct+`` shows console output while building (can otherwise be found in the ``log`` directory)
+  * ``--executor sequential`` processes the packages one by one instead of using parallelism
+
+Once the build is finished, enter the command in the workspace root (``~/ros2_ws``):
+
+
+
+.. code-block:: console
+
+  ls
+
+And you will see that colcon has created new directories:
+
+.. code-block:: console
+
+  build  install  log  src
+
+The ``install`` directory is where your workspace's setup files are, which you can use to source your overlay.
+
+
+4 Source the overlay
+^^^^^^^^^^^^^^^^^^^^
+
+Before sourcing the overlay, it is very important that you open a new terminal, separate from the one where you built the workspace.
+Sourcing an overlay in the same terminal where you built, or likewise building where an overlay is sourced, may create complex issues.
+
+In the new terminal, source your main ROS 2 environment as the "underlay", so you can build the overlay "on top of" it:
+
+
+
+.. code-block:: console
+
+  source /opt/ros/{DISTRO}/setup.bash
+
+
+
+Go into the root of your workspace:
+
+
+
+.. code-block:: console
+
+  cd ~/ros2_ws
+
+
+In the root, source your overlay:
+
+
+
+.. code-block:: console
+
+  source install/local_setup.bash
+
+
+.. note::
+
+  Sourcing the ``local_setup`` of the overlay will only add the packages available in the overlay to your environment.
+  ``setup`` sources the overlay as well as the underlay it was created in, allowing you to utilize both workspaces.
+
+  So, sourcing your main ROS 2 installation's ``setup`` and then the ``ros2_ws`` overlay's ``local_setup``, like you just did,
+  is the same as just sourcing ``ros2_ws``'s ``setup``, because that includes the environment of its underlay.
+