.. _RosApi:

Auto-generated ROS API
######################
For each of the defined tasks, a ROS API made of topics, services, and actions
is automatically generated by CartesIO. This is a convenient way to integrate
CartesIO inside a distributed control system, and to monitor its behavior
remotely.

.. note::

    By default, the whole ROS API resides under the namespace ``/cartesian``.
    Task specific topics/services/actions will be under the additional namespace
    given by the task name.

    The ROS API of a task with name ``mytask`` will be available under the namespace
    ``/cartesian/mytask``

Contents:

.. contents:: :local:

Solver API
==========
The following services and topics are available to monitor and customize the solver state.

Services
--------

get_task_list
^^^^^^^^^^^^^
Returns the list of all defined tasks, with their names and types.

reset
^^^^^
Resets the solver state to the robot state (if available) or to the homing state.

reset_world
^^^^^^^^^^^
TBD

load_controller
^^^^^^^^^^^^^^^
TBD

Topics
------

solution
^^^^^^^^
The current solver solution, as a ``sensor_msgs/JointState`` message.

tf
^^
Current solution TF tree. Tf messages are published with a TF prefix (default is ``ci/``),
to avoid conflicts with other robot state publishers.


Common task API
===============
All task types inherit a common *Task ROS API*, made of **services** and **topics**, as described below.

Services
--------

get_task_properties
^^^^^^^^^^^^^^^^^^^
Returns all task properties.

.. list-table:: Service description
   :widths: 8 30
   :header-rows: 0
   :stub-columns: 1


   * - Name
     - get_task_properties
   * - Type
     - ``cartesian_interface::GetTaskInfo``
   * - Request
     - --
   * - Response
     - .. code-block:: yaml

            string name
            string[] type
            float32 lambda
            float32 lambda2
            string activation_state
            float32[] weight
            uint32[] indices
            uint32 size
            string[] disabled_joints


.. note::

    The type hierarchy of the C++ task representation is reflected into
    a list of types.

    For instance, the C++ ``InteractionTask`` class derives
    from ``CartesianTask``, which in turns derives from ``TaskDescription``.

    Therefore, the type field will be ``type = [Interaction, Cartesian, Task]``.


set_active
^^^^^^^^^^
Activates/deactivates the task. Returns a success flag and a status message.

.. list-table:: Service description
   :widths: 8 30
   :header-rows: 0
   :stub-columns: 1


   * - Name
     - set_active
   * - Type
     - ``cartesian_interface::SetTaskActive``
   * - Request
     - .. code-block:: yaml

            bool activation_state

   * - Response
     - .. code-block:: yaml

            bool success
            string message


set_lambda and set_lambda2
^^^^^^^^^^^^^^^^^^^^^^^^^^
Sets the task lambda value. Returns a success flag and a status message.

.. list-table:: Service description
   :widths: 8 30
   :header-rows: 0
   :stub-columns: 1


   * - Name
     - set_lambda
   * - Type
     - ``cartesian_interface::SetLambda``
   * - Request
     - .. code-block:: yaml

            float32 lambda

   * - Response
     - .. code-block:: yaml

            bool success
            string message


set_weight
^^^^^^^^^^
Sets the task weight value. Returns a success flag and a status message.
The weight can be expressed as:

  - a scalar
  - a vector specifying the weight as a diagonal matrix
  - the full weight matrix

.. list-table:: Service description
   :widths: 8 30
   :header-rows: 0
   :stub-columns: 1


   * - Name
     - set_weight
   * - Type
     - ``cartesian_interface::SetWeight``
   * - Request
     - .. code-block:: yaml

            float32[] weight

   * - Response
     - .. code-block:: yaml

            bool success
            string message

Topics
------

task_changed_event
^^^^^^^^^^^^^^^^^^
A message is published on this topic whenever a task property has changed. The
message contains a string identifier of the actual property changed.

.. list-table:: Topic description
   :widths: 8 30
   :header-rows: 0
   :stub-columns: 1


   * - Name
     - set_weight
   * - Type
     - ``std_msgs::String``


Supported tasks API
===================

.. toctree::
   :maxdepth: 1

   tasks/cartesianros
   tasks/posturalros
   tasks/limitsros