|
|
| Line 1: |
Line 1: |
| 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 [https://developers.google.com/protocol-buffers/ Protocol Buffers]. The [https://developers.google.com/protocol-buffers/docs/overview overview] and [https://developers.google.com/protocol-buffers/docs/encoding data encoding] pages describe the specifics of the serialization process.
| | This page has moved to http://docs.openlighting.org/doc/rpc_system.html. |
| | |
| 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 [https://code.google.com/p/protobuf/wiki/ThirdPartyAddOns many languages].
| |
| | |
| == OLA Messages ==
| |
| | |
| The protocol buffers that describe the messages sent and received by olad are in [https://github.com/OpenLightingProject/ola/blob/master/common/protocol/Ola.proto 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 [https://github.com/OpenLightingProject/ola/blob/master/common/rpc/Rpc.proto 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.
| |
| | |
| <pre>
| |
| message RpcMessage {
| |
| required Type type = 1;
| |
| optional uint32 id = 2;
| |
| optional string name = 3;
| |
| optional bytes buffer = 4;
| |
| }
| |
| </pre>
| |
| | |
| ;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
| |
| <pre>
| |
| // 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
| |
