Difference between revisions of "RPC Protocol"

Revision as of 09:06, 3 March 2014

A common question that comes up is "How can I communicate with olad using something other than C++, Python or Java?".

Intro

OLA is a client / server architecture. The clients and the server (olad) communicate over a TCP socket. By default olad listens on localhost:9010. Data passed between the client and the server is serialized using Protocol Buffers. The overview and data encoding pages describe the specifics of the serialization process.

To write a new client at the very least you need an implementation of protocol buffers for your language. Luckily there is widespread support for protocol buffers in many languages.

OLA Messages

The protocol buffers that describe the messages sent and received by olad are in common/protocol/Ola.proto. At the end of the file the 'OlaServerService' section lists the remote methods that can be called on olad, along with the request and response message types.

Outer Message

When a call to olad is made, the appropriate request message is constructed (say PluginListRequest ) and then the message is serialized to an array of bytes. The byte array is then wrapped in a second protocol, which contains information about the RPC itself. This outer layer is defined in common/rpc/Rpc.proto.

The outer layer is not OLA specific, it can be used for any type of RPC message, in fact it's also used by the SLP server that comes with OLA.

message RpcMessage {
  required Type type = 1;
  optional uint32 id = 2;
  optional string name = 3;
  optional bytes buffer = 4;
}

type

The type of this RPC message, usually REQUEST or RESPONSE

id

the sequence number of the message. The sequence number of response messages must match the number used in the request.

name

the name of the remote method to call

buffer

the serialized inner protocol buffer.

Simple Example

A quick example in Python style pseudo code

  // connect to socket
  server = socket.connect("127.0.0.1", 9010)

  // Build the request
  DmxData dmx_data
  dmx_data.universe = 1
  dmx_data.data = .....

  // Wrap in the outer layer
  RpcMessage rpc_message
  rpc_message.type = RpcMessage::REQUEST
  rpc_message.id = 1
  rpc_message.name = 'UpdateDmxData'
  rpc_message.buffer = dmx_data.Serialize()

  server.write(rpc_message.Serialize())

  // wait for response on socket