Rapyuta

A Cloud Robotics Platform

User Tools

Site Tools


Sidebar


News

  • March 15, 2014 | Rapyuta/Roboearth presented at TEDx, Adliswil, Switzerland (video)
  • November 03, 2013 | Rapyuta presented in IROS 2013, Tokyo, Japan.
  • April 12, 2013 | Rapyuta presented in ROSCon2013, Stuttgart, Germany. Successful live demonstration of RGBD mapping on the cloud.
  • April 10, 2013 | Rapyuta presented in invited talk at the ICRA 2013 workshop on long-term autonomy, Karlsruhe, Germany.
communication_protocol

This page defines the message types used in the RoboEarth Cloud Engine. The data type messages use ROS messages.

Initialization

The initialization has two steps. The first step is to retrieve the address of a Robot process from the Master and the second step is to authenticate the user as well as to establish the websocket connection.

Connection to Master

The first step is to send a standard HTTP request to the Master process to retrieve the address of an available Robot process. This request is a simple GET request with two necessary parameters:

  • userID: Unique ID of the user * in general the owner of the robots
  • version: The version of the used protocol/client
http://[domain]?userID=[userID]&version=[version]

The user ID is intended to be used to optimize the assignment of an appropriate Robot process. The second parameter is used to check whether the client is compatible with Rapyuta. The response of the Master consists of a JSON encoded string and contains the URL which can be used to connect to an appropriate Robot process. Furthermore, in case there is a newer client version available, the newest version number is attached.

{
  "url":"ws://<domain>:<port>",
  "current":"<current version>"  // Only available if there is a newer version
}

Login

The second step is to connect to the Robot process using the URL returned by the Master process. The request to establish the WebSocket connection between the robot and Rapyuta requires the following three parameters:

  • userID: Unique ID of the user; in general the owner of the robots
  • robotID: Unique ID of the robot; has to be unique only in the scope of the user
  • password: The password which will be used together with the user ID to authenticate the user
http://[domain]?userID=[userID]&robotID=[robotID]&password=[password]

In case the user can be authenticated by the cloud engine the connection will be upgraded to a WebSocket connection * therefore, the robot is ready to proceed.

Protocol

The protocol of the websocket communication uses JSON encoded messages.

Basic Structure

{
 "type":"...",  // predefined string
 "data":<...>   // format depended on "type"
}

Any message between the robot and the cloud engine has a collection of two name/value pairs as the toplevel structure. The first pair has the name “type” and a string of length 2 as value, where the value follows the definition of

rce.comm.types

and describes the format of the value of the second pair named “data”. The following types are known:

  • CC - Create container
  • DC - Destroy container
  • CN - Configure components, the components being nodes, parameters, and interfaces
  • CX - Configure connections between interfaces
  • DM - Data messages (i.e. ROS messages)
  • ST - Status messages (at the moment not used)
  • ER - Error messages

Create Container

{
  "type":"CS",
  "data":{
    "containerTag":"containerTag01"
  }
}

The container tag is used to identify the newly created container in subsequent messages. The tag has to be unique in the scope of the user.

Destroy Container

{
  "type":"CS",
  "data":{
    "containerTag":"containerTag01"
  }
}

All components (nodes, parameters, interfaces) which have been created in this container will be removed as well. The container tag as well as the tags of the removed components can be reused again to create new objects after this request.

Configure Components

{
  "type":"CN"
  "data":{
    "addNodes":[<add node structure>],
    "removeNodes":[<remove node structure>],
    "addInterfaces":[<add interface structure>],
    "removeInterfaces":[<remove interface structure>],
    "setParam":[<add parameter structure>],
    "deleteParam":[<remove parameter structure>]
  }
}

The six configure operations (addNodes, removeNodes, addInterfaces, removeInterfaces, setParam, deleteParam) can also be performed separately and an operation can be omitted from the data structure.

Add Node Structure

{
  "containerTag":"containerTag01",
  "nodeTag":"nodeTagHere",
  "pkg":"name of package",
  "exe":"name of executable",
  "args":"arguments which should be passed to the executable",  // Optional argument
  "name":"name (ROS)",                                          // Optional argument
  "namespace":"namespace (ROS)",                                // Optional argument
}

The node tag has to be unique in the scope of the container and is used to identify the node in subsequent messages. The value of the pair named “args” can contain the directives

$(find [package name])

and/or

$(env [environment variable])

which will be evaluated in the container before the node is launched (refer to roslaunch for explanation of the two directives).

Remove Node Structure

{
  "containerTag":"containerTag01",
  "nodeTag":"nodeTagHere"
}

After the removal the node tag can be reused to launch a new node.

Add Interface Structure

{
  "endpointTag":"container tag or robot ID",
  "interfaceTag":"interfaceTagHere",
  "interfaceType":"type",
  "className":"className",  // msgType for Publisher/Subscriber | srvType for ServiceClient, ServiceProvider
  "addr":"rosAddr",         // only used for ROS interfaces  * can be omitted for robot interfaces
}

The interface tag has to be unique in the scope of the endpoint (either a container or a robot) and is used to identify the interface in subsequent messages. The value of the pair named “interfaceType” has to follow the type definition of the cloud engine.

Remove Interface Structure

{
  "endpointTag":"container tag or robot ID",
  "interfaceTag":"interfaceTagHere",
}

All connections in which the removed interface was part of are removed as well. After the removal the interface tag can be reused to launch a new node.

Add Parameter Structure

{
  "containerTag":"containerTag01",
  "name":"parameterName/rosAddr",
  "value":"pValue",
}

The paramter name has to be unique in the scope of the container and is used to identify the parameter in subsequent messages. Additionally, the name is used as the address of the parameter in the ROS parameter server.

Remove Parameter Structure

{
  "containerTag":"containerTag01",
  "name":"parameterName/rosAddr",
}

After the removal the parameter name can be reused to add a new parameter to the server. Warning: Changes done by ROS nodes are not monitored, i.e. one can not remove a parameter which was created by a ROS node.

Configure Connections

{
  "type":"CX",
  "data":{
    "connect":[{
      "tagA":"<endpointTag>/<interface tag>",
      "tagB":"<endpointTag>/<interface tag>"
    }],
    "disconnect":[{
      "tagA":"<endpointTag>/<interface tag>",
      "tagB":"<endpointTag>/<interface tag>"
    }]
  }
}

The two configure operations (connect, disconnect) can also be performed separately and an operation can be omitted from the data structure. A tag consists of the endpoint tag and the interface tag which are concatenated with a '/' as separator in between.

Data Message

{
  "type":"DM",
  "data":{
    "iTag":"interfaceTag",
    "type":"geometry_msgs/Twist",  // Service/Msg type  * this is actually redundant: Interface has all details
    "msgID":"mid",                 // Applicable only to services  * Only to maintain correspondence between request and response.
    "msg":{
      "linear":{
        "x":0.0,
        "y":0.0,
        "z":0.0
      },
      "angular":{
        "x":0.0,
        "y":0.0,
        "z":0.0
      }
    }
  }
}

The value of the pair named “msg” contains the, into JSON format converted, ROS message. As an example the ROS message geometry_msgs/Twist is given which consists of two geometry_msgs/Vector3 messages (linear, angular), which again consists of three float64 (primitive) values (x,y,z). msgID is used for correspondence between request and response messages in case of service interface types.

Handling binary files

The websocket interface supports transportation of binary blobs and for some DM type messages it is better to transport them as binary blobs instead of using their corresponding ROS message types. For example, transporting images as PNG (Lossless data compression) is better than sending the corresponding ROS message encoded in JSON.

To exploit this method of transportation, converters between the binary format and ROS message should be provided. Currently a PNG ↔ sensor_msgs/Image converter is provided as an example to build new converters.

Now, for sending, the binary blob should have a 32 byte header that gives the ID (unique within the current connection) and follow a JSON message (with a '*') that includes the ID. For example:

{
  "type":"DM",
  "data":{
    "iTag":"interfaceTag",
    "type":"sensor_msgs/Image",
    "msgID":"mid",
    "msg*":"f9612e9b3c7945ef8643f9f590f0033a"
  }
}

where the '*' in the 3rd line from the last indicates that the value/resource will follow as a binary blob with the given ID.

[32 byte header (binary ID)][body (binary data)]
communication_protocol.txt · Last modified: 2014/06/03 16:56 by gajan