Simple Socket Messaging

Introduction

We provide a socket server to which clients can connect and invoke API functions on a very rudimentary level. Once the client has opened the connection, it sends a string to the server containing the function name and arguments. Specifically, the string has the following format:

function_name;arg1;arg2;arg3;...

The server will execute function_name(arg1, arg2, arg3, *args) and return a message in the following format:

return_type;return_value

The return type is an integer indicating the data type of the response. A list of possible values is shown in the table below. The return type determines how the client must parse the part of the response string following the semicolon ;.

Data type	Code	Remark
Error	-1	Indicates an error during function execution.
String	0
Boolean	1
Pose	2	A list of floats representing a 3D object pose. Minimum length is 6 but can be higher when additional information (e.g., object class, offset) is contained.
None	3	Akin to Python data type for null.
Float	4
Integer	5
Identifier	6	Special string containing an object identifier used for REST calls.

In most cases, the client need not worry about informing the server of the data type of the arguments passed to the function. Looking at the first part of the message, the server knows which function to execute and thus also how its arguments should be interpreted. One exception is the function patch_configuration to change single configuration values described in the introduction of the edge API. Its arguments are a configuration id, the name of the parameter to update, and the desired value. Since the variety of patchable configuration values is too big to delegate type inference to the server, the desired type needs to be made known explicitly by a type identifier from the table above followed by a comma , and the string representation of the actual value. For example, to update a parameter named diameter with a float value of 0.2 in a configuration with id 660152574424f790208f8865, the client would send the following string to the server:

patch_configuration;660152574424f790208f8865;diameter;4,0.2

Client Implementation and Testing

We will make client implementations in different robot control languages available through our Github repository. For those who wish to implement a proprietary client, we host a mockup of the socket server on the web, which will react to all known edge API calls and respond with physically meaningless yet syntactically correct data to verify correct parsing. You can reach the server under port 7052 and domain name staging.api.gke.vathos.net. Testing a basic implementation of get_pose in Python against the cloud endpoint could look like this:

import socket
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
  # connect with the server
  s.connect(('staging.api.gke.vathos.net', 7052))
  # send the RPC
  s.sendall(b'get_pose;votenet;ZYX;1;10')
  # retrieve response buffer
  data = s.recv(1024)
  # decode the buffer into a string
  response_raw = data.decode('utf-8')
  # parse the response data
  response_parsed = response_raw.split(';')
  return_type = int(response_parsed[0])
  logging.debug('Got data type %d', return_type)
  pose_parsed = [float(i) for i in response_parsed[1].split(',')]
  logging.debug('Got data %s', pose_parsed)

If your client does not support domain name resolution, you can connect via the static server IP obtained, e.g., by a ping

ping staging.api.gke.vathos.net

yielding

PING staging.api.gke.vathos.net (34.90.57.211) 56(84) bytes of data.
64 bytes from 211.57.90.34.bc.googleusercontent.com (34.90.57.211): icmp_seq=1 ttl=60 time=18.7 ms

A full unit tests suite for Python is also available on Github.