Robotics Service Bus

h1. SpreadProtocol

{{>toc}}

This wiki page describes the protocol used by the spread-based connectors.

h2. Data Format

Data exchanged on spread is encoded using Google protocol buffers. A spread message always contains a notification (source:/trunk/protocol/RSBProtocol/Protocol.proto) as elementary communication unit. Descriptions of the Notification contents are given as comments on the descriptor file.

h2. Fragmentation

Because spread has a message size limit, a single @Notification@ may not be sufficient to transport a whole event with a huge amount of user data. Hence, events may be encoded in several @Notification@ s sent subsequently. In this case the multiple @Notification@ objects are constructed according to the following rules:

* The size of individual fragments (i.e. the values of @Notification.data@) must not exceed 100,000 octets

* Fragment number are in the range [0, NUMBER-OF-FRAGMENTS - 1]

* Most field values are repeated in all @Notification@ s, in particular:

** The id of the event (@Notification.id@ field)

** The number of @Notification@ s into which the event has been split (@Notification.num_data_parts@ field)

* The two fields which differ among @Notification@ s for one event are:

** The index of the data chunk encoded in the Notification (@Notification.data_part@ field).

** The user data (@Notification.data@ field) are split. 

h2. Hierarchical Bus

The hierarchical bus is created by sending each message to a group corresponding to its scope as well as groups corresponding to all super scopes including "/" (multigroup mulitcast).

_Example_

<pre>

super-scopes(/foo/bar/, include-self? = yes) = /, /foo/, /foo/bar/

</pre>

h2. Group Names

Group names are created by applying the following steps to the fully formal scope string representation (*including trailing slash*):

# Hash the scope string using "MD5":http://en.wikipedia.org/wiki/MD5.

# Convert the 16 bytes of output to a 32 character string by concatenating the *zero-padded* hex (base-16) representations of the individual bytes.

  Letters of the hex representation have to be lower case.

# Remove the final character of the hex representation of the hash.

  (Since spread group names can only be 32 bytes long _including the 0-terminator_)

_Example_

<pre>

/         -> "6666cd76f96956469e7be39d750cc7d\0"

/foo/     -> "4f87be8f6e593d167f5fd1ab238cfc2\0"

/foo/bar/ -> "1c184f3891344400380281315d9e738\0"

</pre>

h2. Quality of Service

The following table explains how the 2D RSB QoS settings are mapped to spread message types.

|             |_.UNRELIABLE     |_.RELIABLE     |

|_.UNORDERED  | UNRELIABLE_MESS | RELIABLE_MESS |

|_.ORDERED    | FIFO_MESS       | FIFO_MESS     |

h2. Implementations

|_.Language   |_.File(s)/Directory                                   |

| C++         | source:trunk/cpp/core/src/rsb/transport/spread       |

| Java        | source:trunk/java/core/src/rsb/transport/spread      |

| Python      | source:"trunk/python/core/rsb/rsbspread/__init__.py" |

| Common Lisp | source:trunk/cl/cl-rsb/src/transport/spread          |