|
|
| 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
| |
