Skip to main content

Architecture

Protocol

The Buttplug Standard defines a message based protocol between a client and a server. Note that the use of client and server here does not explicitly denote network connection. These terms are used as a generic way to denote different communication endpoints.

Client are expected to request information from the server about devices that are connected, and to send information to those devices via the server. Servers will handle device enumeration, connection management to hardware, and failure recoveries (for instance, stopping all connected devices on client disconnect).

While serialization formats are not yet standardized, current references implementations of the Standard use JSON for serialization. More information on this is available in the Messages section.

Stages

Buttplug sessions consist of 3 stages. While these stages need not be discrete, due to the way Buttplug will likely be used, they will usually end up being so. Applications may hide or combine some of the stages depending on requirements.

Identification

During the identification stage, a client will establish connection with the server, and send over its identifying information. The server may trigger some sort of UI event at this point to ask if the user will allow the client to connect and interact.

Enumeration

After the client/server connection is set up, device enumeration can begin. The client can ask the server to scan for devices on various busses or media (serial, usb, bluetooth, network, etc), and return a list of devices it can communicate with.

Consummation

Once devices are found and selected, we can assume the user will begin interacting with connected devices. At this point, the client will mostly be sending and receiving device commands. There may also be more enumeration during usage, as devices can disconnect and will need to reconnect.

Example lifecycle

The following lifecycle covers the general message flow expected between a Buttplug client and a Buttplug server.

ClientServerOnce a connection is established, perform the protocol handshake,which exchanges informationabout identification, versions,ping times, etc...If the server has a non-zeroPingTimeout, the client must senda ping message to theserverbefore the specified timeout.A common strategy is to setthe client Ping time to 1/2 therequested server ping time.loop[[PingTime/2]]The client calls RequestDeviceListto get a list of already connecteddevices.To discover new devices, the clientinstructs the server to startscanning.While the server is scanning, theserver will notify the client of newdevices.Once devices have been discovered, the client instruct the server to</br> stop scanning. Once all devicemanagers have stopped scanning,the server will notify the client.Devices may disconnect at any time.The server will notify the clientwhen this happens.The client may instruct devices toperform actions. Actions vary perdevice. Device capabilities arerelayed as part of DeviceAdded andDeviceList messages.The client may instruct the server tostop a device from whatever itmay be doing.The client may instruct the server tostop all devices. This is considered good form for a client that isshutting down.RequestServerInfo Id=1ServerInfo Id=1Ping ID=N++Ok ID=N++RequestDeviceList Id=2DeviceList Id=2StartScanning Id=3Ok Id=3DeviceAdded Id=0DeviceAdded Id=0StopScanning Id=4Ok Id=4ScanningFinished Id=0DeviceRemoved Id=0VibrateCmd Id=5Ok Id=5StopDeviceCmd Id=6Ok Id=6StopAllDevices Id=7Ok Id=7ClientServer