.. _ros-integration:

Integrating SageMotion with ROS
===============================

.. toctree::
   :maxdepth: 2

.. note::  This article assumes that are already familiar with the :ref:`SageMotion Web API<web-api-tutorial>`, and are comfortable making simple nodes in `ROS <https://docs.ros.org/en/galactic/index.html>`_.


Integrating the SageMotion system with ROS will utilize the SageMotion web API. The web API allows complete control of the SageMotion system using language agnostic http commands. A reference for web API commands can be found :ref:`here<web-api>` and a basic tutorial on usage can be found :ref:`here<web-api-tutorial>`.

In this integration example, ROS2 is operating on an independent computation platform with several nodes. The SageMotion Hub is shown on the left.

.. image:: img/ros_integration.png
  :width: 800

In order to control the SageMotion system and process realtime data from the ROS2 system, you must:

#. Create an ethernet connection between the SageMotion Hub and ROS2 computer. This can be done by connecting the included ethernet-to-usb adapter with the ethernet cable plugged into the hub and usb plugged into the ROS2 computer. Once this is done, the SageMotion system will be accessible via the ip address 192.168.137.1.
#. Create a new node on the ROS2 system. Several tutorials doing this can be found on the `ROS2 website <https://docs.ros.org/en/galacticindex.html>`_.
#. Use an http library inside your ROS node to control the SageMotion hub over ethernet. :ref:`This tutorial<web-api>` demonstrates doing this using the Python language and the `Requests <docs.python-requests.org/en/master>`_ http library. Other languages or libraries can be used to exercise the same web API.