OpenVibrationsCommunicationsProtocol

From Opendildonics.org

OpenVibrations defines a simple protocol for communicating between compliant applications. The protocol is designed to function over party-line type media where multiple users will be interacting as well as point-to-point connections. In this way the communications used over IRC and direct TCP connections are nearly identical.

This section describes Version 0.1 of the OpenVibrations Communications Protocol.

When communicating over a medium that does not automatically include the name of the user who is sending the message as part of the message (such as TCP), an additional tag should be sent:

  <iam id="dummyuser" versions="0.1"/>                                         
                                                                               

This lets the receiving application know who is connected to it. This is not necessary when communicating over IRC, and so it is ignored for those connections. The versions key specifies a comma-separated list of supported versions of the OpenVibrations Communications Protocol for the application. It is optional - with no versions specified, version 0.1 will be assumed.

Currently, self-naming media (ie: IRC) cannot specify their supported versions, and therefore must default to version 0.1 of the protocol.

Compliant applications must then provide a method for a user to permit and deny other users access to control their devices. The XML used to communicate these states are:

  <target id="ovuser"><accept/></target> <target id="ovuser"><deny/></target>                                                 
                                                                               

The first line notifies ovuser that we'll accept commands from them, and the second that we'll no longer accept their commands.

After notifying a user that we wish to interact with them, each application needs to learn what devices the other has available, so the initiating application will send two more XML messages. The first is a list of motors attached to the current devicegroup (don't send all the devicegroups, just the one that is active):

  <target id="ovuser"><devicegroup id="firstdevice" image="myimage.jpg"><motor id="firstmotor" action="vib" type="onoff" x="80" y="50"/><motor id="secondmotor" type="pwm" x="40" y="115"/></devicegroup></target>                                             
                                                                               

The second message is a request for the other user to send their device list:

  <target id="ovuser"><get type="devices"/></target>                           
                                                                               

Upon receiving a "get devices" message from a permitted user, the application should respond with a list of motors attached to the current device in a similar manner.

When two users initiate an interactive session with each other, the OpenVibrations application for the first user will send its three messages (accept, device list, and get devices) of which only the first will be parsed by the second user if they have not yet told their application they wish to interact with the first user. Once the second user does so, they will send their three messages to the first user who will parse all three and respond to the get devices message with another copy of its device list. At this point both users will have all the information they need to be able to interact.

Sessions that occur over "anonymous" transports (like TCP) must be initiated by each side sending the appropriate "iam" message before any other messages are sent.

The action message to command a user to turn on or off one of their motors, a command similar to the following should be issued. This will cause the application to perform the action on the named motor belonging to the currently active device. Bear in mind that interactive sessions are real-time, so in most cases the "wait" key should be set to 0.

  <target id="ovuser"><motor id="firstmotor"><action type="on" wait="0"/></motor></target>                                                  
                                                                               

The current version of OpenVibrations assumes that the user will choose to use only one of their devicegroups at a time, and therefore does not support the parsing of "get devices" messages containing multiple devicegroups, nor of specifying the devicegroup in addition to the motor in an action message.

Future versions will likely support such functionality by returning multiple devicegroup tags in response to a "get devices" message, and for wrapping the motor tag of an action message with the devicegroup to which it belongs.

If the receiving user has muted the sending user in their software, the receiving user should silently ignore the incoming action messages. They should continue to watch for deny messages indicating that the interaction should cease. If the sending user has muted a receiving user, their software should continue to send action messages as if the user wasn't muted.