====
ROS2
====

.. include:: ../_templates/constants.rst 

ROS2 is the main software framework for the robot. It handles message passing, timing, and modularity. Each sensor, controller, and algorithm runs as a ROS2 node. These nodes will use one of the following communication methods provided by the framework:

1. *Topics* are used for continuous streams of data. Nodes can publish messages via topics and nodes can subscribe to messages via topics.
:raw-html:`<br />`

2. *Services* are used for call-and-response communication. Many nodes can act as the service client, each capable of sending requests to the node acting as the service server.
:raw-html:`<br />`

3. *Actions* are used for long-term communications that consist of a goal, feedback, and a result. One node acts as the action server that responds to requests about the goal and result, in addition to providing feedback information to the action client, which is another node that sends out the information requests. 
:raw-html:`<br />`


.. figure:: ../_images/fig11_ros2_overview.png
    :align: center
    :loading: link

    Overview of ROS2 Setup



Data Collection
+++++++++++++++

The first step to any autonomous system is to collect all relevant sensor data. In ROS2, we can represent each sensor as a *node* that is within a *package*, which is just a collection of source code, configuration files, and compiler rules. 

These nodes then publish their data to a topic, making it available to any nodes subscribed to said topic. ROS2 supports a wide variety of message types, many of which are conveniently crafted to carry specific sensor data. Message types used in RoboFlock are discussed further in :doc:`../tutorial_docs/roboflock_topics`.

The naming conventions for topics is also important. A topic's name can impact its place in the naming hierarchy. For example, LiDAR data is typically published to a topic named :code:`scan`, which is considered to be *relative* (to its original package), whereas a topic named :code:`/scan` is considered to be *absolute* (to the whole workspace). 

The naming hierarchy can be useful when multiple, independently-developed packages unknowingly reference the same topic name. Since ROS2 is open-source with lots of publically contributed packages, naming conflicts will happen. 

Topic names can also be *remapped*, which is especially useful when working with internal ROS2 packages, such as the Robot Localization package. RoboFlock generally sticks to using absolute names and remappings to avoid conflicts. 



Transformations
+++++++++++++++

An important concept to understand in ROS2's navigation system is the *frame of reference*. Each component on the robot is considered to have its own frame of reference, which is a 3D space at which the component is the origin and the *x*, *y*, and *z* axes are aligned with the component's front, left side, and top, respectively.

In order for the sensor data to be used accurately, it needs to be in the robot's frame of reference. Let's say that RoboFlock's left ultrasonic sensor detects an object 1 meter in front of itself. If taken at face value, then this data is incorrect to the robot because the object is actually 1 meter to the robot's left. The data needs to be transformed from the ultrasonic sensor's frame of reference to the robot's frame of reference. 

Fortunately, ROS2 can handle the translational and rotational math needed to move data between different frames of reference via the :code:`tf2` subsystem; however, it still needs a starting point. This is where the URDF file comes in. It gives a spatial description of each component in the robot relative to the robot's center of mass. 

Using the left ultrasonic example, we might describe its translational offset as being 10 centimeters above and 15 centimeters to the left of the robot's center, and its rotational offset would be 90 degrees about the *z*-axis. 

.. The file can be manually written or automatically generated from CAD models using tools such as **LIST CAD-URDF TOOL HERE**.


Sensor Fusion
+++++++++++++

So now we have all our sensor data publishing to their respective topics and all physical aspects of the robots defined in a URDF file. The next step for ROS2 to perform is fusing all this data together so that calculations for the motor drivers can be made. There are 15 variables that ROS2 cares about:

* *x*, *y*, *z* positions

* roll, pitch, and yaw

* *x*, *y*, *z* velocities

* change in roll, pitch, and yaw

* *x*, *y*, *z* accelerations


Since RoboFlock is (currently) only concered with planar motion, we can disregard any roll, pitch, or *z*-axis values. The remaining variables are ultimately controlled by how the sensor fusion is configured. The :code:`robot_localization` package processes sensor data needed to understand the robot's physical location in the environment. 

In the case of RoboFlock, this data comes from the inertial measurement unit (IMU), LiDAR scanner, and GPS module. The result is an odometry message that contains information on the robot's frame of reference, position on the global map, linear velocity, and angular velocity. The :code:`robot_localization` package also updates the transform between the global frame of reference and the robot's frame of reference, which will be the main transform that data is moved through when navigational calculations are made.


Mapping
+++++++

`SLAM toolbox <https://github.com/SteveMacenski/slam_toolbox>`_ is an open-source ROS2 package that uses the robot's odometry and incoming LiDAR scans to build a map of the surroundings, which gets published alongside a corresponding :code:`map` to :code:`odom` transformation. 

.. figure:: ../_images/flowcharts/slam_toolbox_sync.png
    :align: center
    :loading: link

Navigation
++++++++++

Nav2 is ROS2's navigation stack that takes in a set of `REP-105 <https://www.ros.org/reps/rep-0105.html>`_ compliant TF transformations, a BT (behavior tree) XML file, and any relevant sensor data, which in the case of RoboFlock is the IMU, ultrasonic sensor, and GPS data. 

Transformations and sensor data needed by Nav2 is obtained by configuring it to subscribe to the corresponding topics. This data gets used to build several layers of costmaps, allowing the pathfinding behavior to choose the best, obstacle-free route to its goal. The BT XML file is generated by a set of plugins that is defined when configuring Nav2. See the `RoboFlock GitHub repository <https://github.com/shouvik-d/roboflock_ws/blob/main/src/bring_up/config/nav2_params.yaml>`_ for the Nav2 plugins used in this project.


.. seealso::

    `Introducing tf2 <https://docs.ros.org/en/humble/Tutorials/Intermediate/Tf2/Introduction-To-Tf2.html>`_
        ROS2 Humble tutorial on the :code:`tf2` and the :code:`rviz2` visualization tool

    `robot_localization <https://docs.ros.org/en/noetic/api/robot_localization/html/index.html>`_
        Documentation for the :code:`robot_localization` package

    `geometry/CoordinateFrameConventions <https://wiki.ros.org/geometry/CoordinateFrameConventions#Naming>`_
        Coordinate Frame Naming Conventions

    `REP 103 <https://www.ros.org/reps/rep-0103.html>`_
        Standard Units of Measure and Coordinate Conventions

    `REP 117 <https://www.ros.org/reps/rep-0117.html>`_
        Informational Distance Measurements Conventions

    `REP 144 <https://www.ros.org/reps/rep-0144.html>`_
        Package Naming Conventions

    `REP 145 <https://www.ros.org/reps/rep-0145.html>`_
        IMU Sensor Driver Conventions