Racecom API documentation
*************************

The Key-Int-Map and Key-Pose-Map functionality of the OPC UA service can be accessed via racecom operation calls. The following example creates a new Key-Integer-Pair on the OPC UA server and then requests its value.
::

  racecom -m tcp://<robot-ip>:11511 call opcua replaceInt '{key: "my key"; value: 123;}'
  racecom -m tcp://<robot-ip>:11511 call opcua readInt '{key: "my key"; timeout: 0.0;}'

List of all Operations
======================

A list of all operations of the OPC UA service running on the robot with the IP address ``<robot-ip>`` can be generated via racecom using the following command:
::

  $ racecom -m tcp://<robot-ip>:11511 list-operations opcua
    Operation opcua.clearIntMap
      request type: {}
      result type: {}
      error type: string
    Operation opcua.clearPoseMap
      request type: {}
      result type: {}
      error type: string
    Operation opcua.deleteInt
      request type: { string key; }
      result type: bool
      error type: string
    Operation opcua.deletePose
      request type: { string key; }
      result type: bool
      error type: string
    Operation opcua.readInt
      request type: { string key; float timeout; }
      result type: int
      error type: string
    Operation opcua.readIntMap
      request type: {}
      result type: []{ string key; int value; }
      error type: string
    Operation opcua.readIntMapKeys
      request type: {}
      result type: []string
      error type: string
    Operation opcua.readPose
      request type: { string key; float timeout; }
      result type: [16]float
      error type: string
    Operation opcua.readPoseMap
      request type: {}
      result type: []{ string key; [16]float value; }
      error type: string
    Operation opcua.readPoseMapKeys
      request type: {}
      result type: []string
      error type: string
    Operation opcua.replaceInt
      request type: { string key; int value; }
      result type: {}
      error type: string
    Operation opcua.replacePose
      request type: { string key; [16]float value; }
      result type: {}
      error type: string
    Operation opcua.takeInt
      request type: { string key; float timeout; }
      result type: int
      error type: string
    Operation opcua.takePose
      request type: { string key; float timeout; }
      result type: [16]float
      error type: string

Timeout
=======

For certain operations, a timeout, i.e. a maximum waiting time for the key to exist can be specified. If timeout is negative, the execution will wait indefinitely.

Read vs. Take
=============

Separate operations exist for *reading* and *taking* Key-Value-Pairs. With *read* operations, the Key-Value-Pair will remain on the server. With *take* operations, the Key-Value-Pair will get deleted immediately after the operation has been executed.

.. tabularcolumns:: |\Y{0.175}|\Y{0.15}|\Y{0.15}|\Y{0.1}|\Y{0.425}|

+---------------------+--------------------------------------+----------------------------------------+----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| operation           | request type                         | result type                            | error type     | description                                                                                                                                                                                                                                                                                                                          |
+=====================+======================================+========================================+================+======================================================================================================================================================================================================================================================================================================================================+
|   clearIntMap       |   {}                                 |   {}                                   |   string       | Clears the entire key-integer map. Does not return with an error.                                                                                                                                                                                                                                                                    |
+---------------------+--------------------------------------+----------------------------------------+----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|   clearPoseMap      |   {}                                 |   {}                                   |   string       | Clears the entire key-pose map. Does not return with an error.                                                                                                                                                                                                                                                                       |
+---------------------+--------------------------------------+----------------------------------------+----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|   deleteInt         |   {                                  |   bool                                 |   string       | Deletes the key-integer pair with the specified key. Returns true if the key-integer pair has been deleted. Returns false if the key-integer pair does not exist. Does not return with an error.                                                                                                                                     |
|                     |   string key;                        |                                        |                |                                                                                                                                                                                                                                                                                                                                      |
|                     |   }                                  |                                        |                |                                                                                                                                                                                                                                                                                                                                      |
+---------------------+--------------------------------------+----------------------------------------+----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|   deletePose        | { string key; }                      |   bool                                 | string         | Deletes the key-pose pair with the specified key. Returns true if the key-pose pair has been deleted. Returns false if the key-pose pair does not exist. Does not return with an error.                                                                                                                                              |
|                     |                                      |                                        |                |                                                                                                                                                                                                                                                                                                                                      |
|                     |                                      |                                        |                |                                                                                                                                                                                                                                                                                                                                      |
+---------------------+--------------------------------------+----------------------------------------+----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|   readInt           |   {                                  |   int                                  |   string       | Reads and returns the key-integer pair with the specified key. If the key does not exists, the operation will wait for the specified timeout time and return immediately, if a key-integer pair with the specified key is created. If no key is existing within the specified timeout time, the operation will return with an error. |
|                     |   string key;                        |                                        |                |                                                                                                                                                                                                                                                                                                                                      |
|                     |   float timeout;                     |                                        |                |                                                                                                                                                                                                                                                                                                                                      |
|                     |   }                                  |                                        |                |                                                                                                                                                                                                                                                                                                                                      |
+---------------------+--------------------------------------+----------------------------------------+----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|   readIntMap        |   {}                                 |   []{                                  |   string       | Reads and returns the entire key-integer map. Does not return with an error.                                                                                                                                                                                                                                                         |
|                     |                                      |   string key;                          |                |                                                                                                                                                                                                                                                                                                                                      |
|                     |                                      |   int value;                           |                |                                                                                                                                                                                                                                                                                                                                      |
|                     |                                      |   }                                    |                |                                                                                                                                                                                                                                                                                                                                      |
+---------------------+--------------------------------------+----------------------------------------+----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|   readIntMapKeys    |   {}                                 |   []string                             |   string       | Reads and returns all keys of the entire key-integer map. Does not return with an error.                                                                                                                                                                                                                                             |
+---------------------+--------------------------------------+----------------------------------------+----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|   readPose          |   {                                  |   [16]float                            |   string       | Reads and returns the key-pose pair with the specified key. If the key does not exists, the operation will wait for the specified timeout time and return immediately, if a key-pose pair with the specified key is created. If no key is existing within the specified timeout time, the operation will return with an error.       |
|                     |   string key;                        |                                        |                |                                                                                                                                                                                                                                                                                                                                      |
|                     |   float timeout;                     |                                        |                |                                                                                                                                                                                                                                                                                                                                      |
|                     |   }                                  |                                        |                |                                                                                                                                                                                                                                                                                                                                      |
+---------------------+--------------------------------------+----------------------------------------+----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|   readPoseMap       |   {}                                 |   []{                                  |   string       | Reads and returns the entire key-pose map. Does not return with an error.                                                                                                                                                                                                                                                            |
|                     |                                      |   string key;                          |                |                                                                                                                                                                                                                                                                                                                                      |
|                     |                                      |   [16]float value;                     |                |                                                                                                                                                                                                                                                                                                                                      |
|                     |                                      |   }                                    |                |                                                                                                                                                                                                                                                                                                                                      |
+---------------------+--------------------------------------+----------------------------------------+----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|   readPoseMapKeys   |   {}                                 |   []string                             |   string       | Reads and returns all keys of the entire key-pose map. Does not return with an error.                                                                                                                                                                                                                                                |
+---------------------+--------------------------------------+----------------------------------------+----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|   replaceInt        |   {                                  |   {}                                   |   string       | Replaces the key-integer pair with the specified key. If no key-integer pair with the given key exists, a new one will be created. The specified value will be assigned. Does not return with an error.                                                                                                                              |
|                     |   string key;                        |                                        |                |                                                                                                                                                                                                                                                                                                                                      |
|                     |   int value;                         |                                        |                |                                                                                                                                                                                                                                                                                                                                      |
|                     |   }                                  |                                        |                |                                                                                                                                                                                                                                                                                                                                      |
+---------------------+--------------------------------------+----------------------------------------+----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|   replacePose       |   {                                  |   {}                                   |   string       | Replaces the key-integer pair with the specified key. If no key-pose pair with the given key exists, a new one will be created. The specified value will be assigned. Does not return with an error.                                                                                                                                 |
|                     |   string key;                        |                                        |                |                                                                                                                                                                                                                                                                                                                                      |
|                     |   [16]float value;                   |                                        |                |                                                                                                                                                                                                                                                                                                                                      |
|                     |   }                                  |                                        |                |                                                                                                                                                                                                                                                                                                                                      |
+---------------------+--------------------------------------+----------------------------------------+----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|   takeInt           |   {                                  |   int                                  |   string       | Similar to ``readInt``, except that the specified key-integer pair will be taken, i.e. it will be deleted at the end of the operation call.                                                                                                                                                                                          |
|                     |   string key;                        |                                        |                |                                                                                                                                                                                                                                                                                                                                      |
|                     |   float timeout;                     |                                        |                |                                                                                                                                                                                                                                                                                                                                      |
|                     |   }                                  |                                        |                |                                                                                                                                                                                                                                                                                                                                      |
+---------------------+--------------------------------------+----------------------------------------+----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|   takePose          |   {                                  |   [16]float                            |   string       | Similar to ``readPose``, except that the specified key-pose pair will be taken, i.e. it will be deleted at the end of the operation call.                                                                                                                                                                                            |
|                     |   string key;                        |                                        |                |                                                                                                                                                                                                                                                                                                                                      |
|                     |   float timeout;                     |                                        |                |                                                                                                                                                                                                                                                                                                                                      |
|                     |   }                                  |                                        |                |                                                                                                                                                                                                                                                                                                                                      |
+---------------------+--------------------------------------+----------------------------------------+----------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+