# 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.

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 | { string key; } | 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.
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 | { string key; float timeout; } | 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.
readIntMap | {} | []{ string key; int value; } | string | Reads and returns the entire key-integer map. Does not return with an error.
readIntMapKeys | {} | []string | string | Reads and returns all keys of the entire key-integer map. Does not return with an error.
readPose | { string key; float timeout; } | [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.
readPoseMap | {} | []{ string key; [16]float value; } | string | Reads and returns the entire key-pose map. Does not return with an error.
readPoseMapKeys | {} | []string | string | Reads and returns all keys of the entire key-pose map. Does not return with an error.
replaceInt | { string key; int value; } | {} | 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.
replacePose | { string key; [16]float value; } | {} | 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.
takeInt | { string key; float timeout; } | 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.
takePose | { string key; float timeout; } | [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.