.. _skills:

ROS4HRI Standard Skills
=======================

.. image:: ../images/skills.webp
   :alt: ROS4HRI skills
   :align: center
   :width: 20%

Overview
--------

**Skills** are capabilities built into your robot. In practice, they are **regular ROS nodes**,
exposing **standard ROS interfaces** (actions, services or topics).

**What  make them special, however, is that they follow a well-defined
interface**, exposed in a manifest file: the **skill definition**. You can find here
the schema of a `valid skill definition <https://www.github.com/ros4hri/architecture_schemas/blob/main/schemas/skill.schema.json>`_.

.. important::
    To facilitate interoperability, **ROS4HRI provides definitions for a set of
    standard skills**, listed :ref:`below <list_of_skills>`. If you plan to implement one of these
    capabilities, please **ensure your implementation is compliant** with the
    corresponding skill definition.


Skills are organised in **domains**, as shown below:

.. mermaid::

   flowchart TB
    subgraph subGraph0["Domains & skill definitions"]
           communication["<b>Communication</b><br><tt>ros4hri/communication_skills</tt>"]
           navigation["<b>Navigation</b><br><tt>ros4hri/navigation_skills</tt>"]
           motions["<b>Motions</b><br><tt>ros4hri/motions_skills</tt>"]
           manipulation["<b>Manipulation</b><br><tt>ros4hri/manipulation_skills</tt>"]
           interaction["<b>Interaction</b><br><tt>ros4hri/interaction_skills</tt>"]
           other["..."]
           ask(["skill <tt>Ask</tt>"])
           chat(["skill <tt>Chat</tt>"])
           anon0(["..."])
           anon1(["..."])
           anon2(["..."])
           place(["..."])
           anon3(["..."])
     end
       communication --> ask & chat & anon0
       navigation --> anon1
       motions --> anon2
       manipulation --> place
       interaction --> anon3
       A["<b>Skills</b>"] --> motions & interaction & manipulation & navigation & communication & other
       ask --> impl1("skill implementation...")
       chat --> n1("skill implementation...")
   
       style communication stroke:#AA00FF
       style navigation stroke:#AA00FF
       style motions stroke:#AA00FF
       style manipulation stroke:#AA00FF
       style interaction stroke:#AA00FF
       style other stroke:#AA00FF
       style ask fill:#E1BEE7
       style chat fill:#E1BEE7
       style anon0 fill:#E1BEE7
       style anon1 fill:#E1BEE7
       style anon2 fill:#E1BEE7
       style place fill:#E1BEE7
       style anon3 fill:#E1BEE7
       style A fill:#FFD600
       style impl1 stroke-width:4px,stroke-dasharray: 5
       style n1 stroke-width:4px,stroke-dasharray: 5
       style subGraph0 fill:#FFFFFF,stroke:#757575
       click communication "#communication"
       click navigation "#navigation"
       click motions "#motions"
       click manipulation "#manipulation"
       click interaction "#interaction"



Working with skills
-------------------

Implementing a skill
~~~~~~~~~~~~~~~~~~~~

Skills are regular ROS nodes, exposing ROS interfaces (actions, services or topics).
To implement a skill, you need to:

1. Implement the ROS interfaces (actions, services or topics) of the skill (see the definitions below).
2. Implement the skill logic.
3. Declare that your package implements the skill by adding the following line in your ``package.xml`` file:
   
   .. code-block:: xml
      
      <export>
        <!-- .... -->

        <!-- adapt the following line to your skill -->
        <implements type="skill" package="communication_skills" id="ask" />
      </export>
   

You can use the :ref:`rpk <rpk>` tool to generate ROS4HRI-compliant skill skeletons.

Making an existing node compliant with ROS4HRI skills
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Since ROS4HRI skills are regular ROS nodes, you can make an existing node compliant with ROS4HRI skills by:

1. Adapting the ROS interfaces (actions, services or topics) of the existing node to the ROS interfaces of the skill (see the definitions below).
2. Declaring that your package implements the skill by adding the following line in your ``package.xml`` file:
   
   .. code-block:: xml
      
      <export>
        <!-- .... -->

        <!-- adapt the following line to your skill -->
        <implements type="skill" package="communication_skills" id="ask" />
      </export>
   
Sharing an open-source skill implementation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

We would be happy to hear about your skill implementations!

As long as your skill is open-source, and publicly available on a forge like GitHub, GitLab, or Codeberg,
we will be happy to reference it in the ROS4HRI documentation.

Once your skill is available, `open a discussion on the ROS4HRI GitHub
organization <https://github.com/orgs/ros4hri/discussions/new?category=ideas>`_
to propose it for inclusion.

Note that we will need to review your skill implementation to ensure it is
compliant with ROS4HRI standards.


Creating a new skill and submitting it to ROS4HRI
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you want to create a new skill and submit it to ROS4HRI, you need to:

1. Create a new skill definition.
2. Create a new ROS package implementing the skill.
3. Submit the skill to the right ROS4HRI repository.

Steps 1 and 2 can easily be done using the :ref:`rpk <rpk>` tool: it will
quickly generate a skeleton for your skill definition and skill implementation
based on ROS4HRI-compliant templates.

Step 3 can be done by submitting your skill to the right ROS4HRI repository.
Each domain has its own repository. Find below the domain that best matches your skill,
and submit your new skill proposal using the provided link.

Your proposal will be openly discussed by the ROS4HRI community, and if
accepted, your skill will be added to the corresponding ROS4HRI repository.

The main criteria for accepting a skill proposal are:

- The skill is novel and different from existing ones;
- The skill would be beneficial to a broad range of robots and applications;
- The skill is not tightly coupled to closed-source or proprietary technologies;
- The skill is well-documented.

Proposing a change/extension to a skill
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you want to propose a change/extension to an existing skill, follow the link
in the corresponding section below.

Proposing a new domain
~~~~~~~~~~~~~~~~~~~~~~

To propose a new domain, please `open a discussion on the ROS4HRI GitHub
organization <https://github.com/orgs/ros4hri/discussions/new?category=ideas>`_.

.. _list_of_skills:

List of skills
--------------

This is the list of all skill definitions available in ROS4HRI, organised by
domain (note that some skills can be found in multiple domains).


.. note::
    You can download the complete list of ROS4HRI skills in JSON format from https://ros4hri.github.io/skills.json.
    

.. toctree::
   :maxdepth: 1
   :hidden:

   
   skill-ask_human_for_help
   skill-do_led_effect
   skill-look_for_human
   skill-look_for_object
   skill-set_expression
   skill-look_at
   skill-grasp
   skill-place
   skill-hand_grasp
   skill-ask
   skill-chat
   skill-say
   skill-navigate_to_pose
   skill-navigate_to_waypoint
   skill-navigate_to_zone
   skill-execute_joint_trajectory
   skill-execute_cartesian_trajectory



.. _communication_skills:

Communication
~~~~~~~~~~~~~


* :ref:`skill-ask`: A specialization of the :skill:`chat` where the role 

* :ref:`skill-ask_human_for_help`: Ask a human for help

* :ref:`skill-chat`: Start a dialogue with a defined purpose.

* :ref:`skill-say`: Speak out the provided input text (also executing any 


.. note::

    - You would like to suggest a new communication skill? `Follow this link <https://github.com/ros4hri/communication_skills/issues/new?template=new-skill.md>`_.

    - You want to suggest a change to an existing communication skill? (like
      additional parameters, etc) `Follow this link <https://github.com/ros4hri/communication_skills/issues/new?template=amend-skill.md>`_.



.. _interaction_skills:

Interaction
~~~~~~~~~~~


* :ref:`skill-ask_human_for_help`: Ask a human for help

* :ref:`skill-do_led_effect`: Perform light effects using the robot's LEDs.

* :ref:`skill-look_at`: Defines the gazing direction of the robot. This skill can be used to either look at a specific point 

* :ref:`skill-look_for_human`: Search and localize specific humans

* :ref:`skill-look_for_object`: Search and localize specific objects

* :ref:`skill-set_expression`: Sets the expression of the robot. This might include changing the robot's face, body posture, or other expressive features.


.. note::

    - You would like to suggest a new interaction skill? `Follow this link <https://github.com/ros4hri/interaction_skills/issues/new?template=new-skill.md>`_.

    - You want to suggest a change to an existing interaction skill? (like
      additional parameters, etc) `Follow this link <https://github.com/ros4hri/interaction_skills/issues/new?template=amend-skill.md>`_.



.. _manipulation_skills:

Manipulation
~~~~~~~~~~~~


* :ref:`skill-grasp`: Commands the robot to grasp a specified object.

* :ref:`skill-hand_grasp`: Controls a robotic hand or gripper to either **close** (grasp) or **open**

* :ref:`skill-place`: Commands the robot to place an object at a specified location.


.. note::

    - You would like to suggest a new manipulation skill? `Follow this link <https://github.com/ros4hri/manipulation_skills/issues/new?template=new-skill.md>`_.

    - You want to suggest a change to an existing manipulation skill? (like
      additional parameters, etc) `Follow this link <https://github.com/ros4hri/manipulation_skills/issues/new?template=amend-skill.md>`_.



.. _motions_skills:

Motions
~~~~~~~


* :ref:`skill-execute_cartesian_trajectory`: Execute a trajectory on the robot by specifying

* :ref:`skill-execute_joint_trajectory`: Execute a joint trajectory on the robot by specifying

* :ref:`skill-grasp`: Commands the robot to grasp a specified object.

* :ref:`skill-hand_grasp`: Controls a robotic hand or gripper to either **close** (grasp) or **open**

* :ref:`skill-place`: Commands the robot to place an object at a specified location.


.. note::

    - You would like to suggest a new motions skill? `Follow this link <https://github.com/ros4hri/motions_skills/issues/new?template=new-skill.md>`_.

    - You want to suggest a change to an existing motions skill? (like
      additional parameters, etc) `Follow this link <https://github.com/ros4hri/motions_skills/issues/new?template=amend-skill.md>`_.



.. _navigation_skills:

Navigation
~~~~~~~~~~


* :ref:`skill-navigate_to_pose`: Make the robot autonomously navigate toward the desired pose.

* :ref:`skill-navigate_to_waypoint`: Make the robot autonomously navigate toward the desired waypoint.

* :ref:`skill-navigate_to_zone`: Make the robot autonomously navigate toward the desired zone.


.. note::

    - You would like to suggest a new navigation skill? `Follow this link <https://github.com/ros4hri/navigation_skills/issues/new?template=new-skill.md>`_.

    - You want to suggest a change to an existing navigation skill? (like
      additional parameters, etc) `Follow this link <https://github.com/ros4hri/navigation_skills/issues/new?template=amend-skill.md>`_.