Skip to content

protocol definition

Jump to bottom
Tanner Mickelson edited this page Apr 16, 2016 · 34 revisions

RRDTP version 1a (alpha version - subject to change)

Overview

RRDTP version 1 is a data streaming protocol. One host acts as the server, and is the authoritative source for all data values. Multiple clients can connect to the server to send and receive updates to data values. Values can be stored hierarchically in categories. The design of RRDTP draws inspiration from WPI Network Tables, but is designed to be simpler and more easily portable to resource-limited platforms.

Events

Each packet will contain an event type. The currently defined event types are listed below.

  • Create value: sent to create a value if one hasn't been created already. Either a client, or the server can send this type of packet.
  • Update value: sent to indicate that a value was updated. Either a client, or the server can send this type of packet.
  • Delete value: sent to delete a value if it exists. Either a client, or the server can send this type of packet.

Data types

Values can be one of 7 types.

  • int - signed 32-bit integer
  • long - signed 64-bit integer
  • float - single precision floating point number
  • double - double precision floating point number
  • boolean - true/false boolean flag
  • string - string (ASCII or UTF8)
  • unformatted - plain unformatted data. The calling code is responsible for endianness conversion.

Value identifiers

Values are identified by a hierarchical naming scheme similar to Java packages. If the value isn't stored in any category, then it can be referred to simply by its name, such as "value1". If the value is stored within a category and any number of subcategories, then it can be referred to by separating the categories with a period ".", for example "category.sub-category.value1". Valid characters that can be used in category and value names are letters, numbers, underscores "_", and hyphens "-". Identifiers are case sensitive ("Value1" != "VALUE1" != "VaLuE1"). Value identifiers are always specified as ASCII format strings ending in a null terminator.

Protocol

Header

Each RRDTP packet begins with a header containing the 8-bit protocol version number, and the 8-bit event type (see Events section above). The rest of the packet format depends on the event type.

Client handshake

When the client first connects to the server it must send a packet of this type. The client handshake packet contains nothing beyond the header.

Server handshake

Sent by the server in response to the client handshake packet. When the server receives a "client handshake" packet, it will send this packet back along with "create value" packets to synchronize all values to the client.

Create value

Sent to create a value entry. The system that creates the value is considered to own the value, and is (by default) the only system allowed to update that value later. A value creation packet contains the value identifier, the data type (1 byte), the size of the data (2 bytes), and the data itself (variable size).

Update value

Value update packets are sent to all systems in order to update existing values. They contain the same data as value creation packets. The data type must match the type of the initially created value, or else the packet will be ignored.

Delete value

Deletes a value from all systems. The packet contains only the identifier of the value to delete.

Clone this wiki locally