Architecture

Goals

The goals of the Buttplug Protocol are fairly simple:

• Relay information about device connections and disconnects from the Buttplug server to client applications.
• Allow developers to know what features a device presents.
• Allow developers to access those features in a uniform manner.

This goals guide how new messages are added to the protocol, and established messages are changed between versions as developers give us feedback on their specific usages.

Structures

Buttplug define systems it is used in via a few different structures:

• Device
  • In Buttplug terms, a Device is a set of Features. Each feature can have the following attributes:
    • Actuators: Device outputs like vibration, stroking, etc...
    • Sensors: Device inputs like buttons, pressure gauges, accelerometers/IMUs, etc...
    • Raw: A special attribute used for direct device communication without Buttplug as a protocol translation intermediary. Raw attributes are rarely seen, mostly in the context of developer debugging or special requirements for DIY devices.
  • A device may not always directly represent a piece of hardware. For instance, a device may be simulated as part of a developer tool, or act as an intermediary for network access to a remote controller. This distinction matters at the server level, but is usually hidden from clients.
• Server
  • The portion of the system that handles direct device communication. The Buttplug Server handles connections from clients, as well as translating messages from the client into corresponding proprietary commands for devices.
  • Servers are by far the most complicated portion of a Buttplug system, and are expected to be rarely implemented outside of the reference implementation.
• Client
  • An application that integrates a Buttplug Client library or API. These applications (which can be games, music players, movie players, other development tools, etc) use a Buttplug Client library written in a matching programming language/environment to connect to the Buttplug Server and allows developers to gather information about toys and control them in a way that should abstract them from the raw Buttplug Protocol that is presented in this document.
  • Clients will need to be implemented for various programming languages and environments like game engines. A list of those currently available can be found as part of the Buttplug Awesome List.
  • If you are writing a Buttplug implementation library and expecting your user to create Buttplug Messages themselves, you are most likely making life more difficult on your users. If that is your goal, then that is fine, but otherwise more guidance on client creation is given in the Buttplug Developer Guide.

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. Clients and Servers may both be embedded in the same process, or may talk over methods such as network or some form of IPC.

Protocol

The Buttplug Standard defines a message based protocol between a Client and a Server.

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 between the Client and Server 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. Client implementations 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 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 via the Client. 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.