.. include:: alias.rst

.. _tools:

|racecom| Tools Documentation
=============================

The |racecom| library provides a number of binary tools. For the
end-user, the most important tools are ``race-master`` and
``racecom``.

``race-master``
---------------

``race-master`` is a stand-alone implementation of the |racecom|
master process which acts as a central name service to find all
currently registered services, its operations and events. Although the
``core`` also runs a |racecom| master process, it can be quite
convenient to not require to start it and use a light-weight
stand-alone process during development of a service.

``racecom``
-----------

``racecom`` is a small tool for interacting with the |racecom|
master. In particular, it can be used for listing all known services,
its operations as well as all events and the corresponding types that
are currently registered at the |racecom| master process. In addition,
it allows to echo event messages and make operation calls from the
command line or from shell scripts.

The following block shows the output of ``racecom --help``, displaying
all possible ``racecom`` commands:

.. code-block:: bash

    Usage: racecom [-m|--master ARG] COMMAND

    Available options:
      -h,--help                Show this help text
      -v,--version             Show version
      -m,--master ARG          Master URI (default: 'tcp://localhost:11511')

    Available commands:
      list-services            List all services
      list-operations          List all operations of a service
      list-events              List all events of a service
      call                     Call an operation
      echo                     Echo events

Tab completion
````````````````

In addition to the ``--help`` command, ``racecom`` also supports
tab completion for both bash and zsh. This means you can press ``<tab>``
for having the current command autocompleted.

If you type ``racecom list-o<tab>``, your shell will autocomplete it to
``racecom list-operations``. Similarily this also works for service-,
operation-, and event-names. E.g. ``racecom list-operations g<tab>``
will complete to ``racecom list-operations gripper`` when the gripper
service is connected  to the racecom master.
Even a default value for an operation call can be autocompleted:
``racecom call gripper move "{<tab>`` will be completed to
``racecom call gripper move "{ speed: 0.0; width: 0.0; }"``.

Listing services
````````````````

All currently registered services can be shown with ``racecom list-services``.

Listing operations
``````````````````

All operations provided by a specific service can be listed by calling
``racecom list-operations <service>``. The following example shows the
output for the ``dummy-service`` that has been developed in the
context of the |racecom| tutorial in this document.

.. code-block:: bash

    $ racecom list-operations dummy

    dummy.addTwoInts:
      request type: { int a; int b; }
      response type: int
      error type: string
      address: tcp://127.0.0.1:41960

As can be seen, the listing includes the operation name as well as the
request, response and error types of the operation. The address field
is mainly internal information for debugging purposes. It contains the
host and port under which the operation is reachable.

Listing events
``````````````

All events provided by a specific service can be listed by calling
``racecom list-events <service>``. The following example shows the
output for the ``dummy-service``:

.. code-block:: bash

   $ racecom list-events dummy

   dummy.ping: int tcp://127.0.0.1:39198

As can be seen, the output shows the data type of the event (``int``)
as well as the internal address.

Calling operations from the command line
````````````````````````````````````````

Besides querying information, ``racecom`` also allows to call
operation calls using the ``call`` sub-command:

.. code-block:: bash

   racecom call <service> <operation> <value>

The value specifies the request parameter in a format similar to the
value format used in state machines. The following list shows a few
examples for race values and should make the value format clear:

 * Integer numbers, declared type ``int``: A number, not containing a
   dot, e.g. ``42``.

 * Floating point numbers, declared type ``float``: A number
   containing a single dot, e.g.: ``12.34`` or ``1.0``.

 * Arrays, e.g. of type ``[]float``: ``[1.0, 2.0, 3.0]``.

 * Structs, e.g. of type ``{ { float x; float y; } pos; { float angle; } rot; }``:

.. code-block:: cpp

   { pos: { x: 1.0; y: 2.0; }; rot: { angle: 123.4; }; }

The following example shows a call to the ``addTwoInts`` operation
provided by the dummy service:

.. code-block:: bash

   $ racecom call dummy addTwoInts '{ a: 1; b: 2; }'
   3

As can be seen, the result of the operation call is printed to
stdout. If an error occurs, it is also printed and the ``racecom``
tool returns with a non-zero return value.

Echoing event values
````````````````````

The ``racecom`` tool also allows to print continuously published event
values with the ``echo`` sub-command:

.. code-block:: bash

   racecom echo <service> <event>

The following example shows the output generated by echoing the
``ping`` event provided by the dummy service:

.. code-block:: bash

   $ racecom echo dummy ping
   { count: 2; }
   { count: 3; }
   { count: 4; }
   { count: 5; }

``racecom echo`` listens for event messages and keeps printing them as
they arrive until the user presses CTRL-C to terminate it. Since event
messages, for instance the robot state, can become quite big,
``racecom echo`` also allows to only print sub-messages. For instance,
suppose a service ``foo`` which publishes an event of the following
type:

.. code-block:: none

   { { int x } a; int b; }

Then, an access path to a specific field can be specified when calling
``racecom echo``:

.. code-block:: bash

   $ racecom echo foo a.x

This only prints the values of the field ``x`` in the field ``a`` of
the event message.