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:

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.

$ 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:

$ 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:

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; }:

{ 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:

$ 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:

racecom echo <service> <event>

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

$ 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:

{ { int x } a; int b; }

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

$ racecom echo foo a.x

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