Buttplug Protocol Specification

# Generic Sensor Messages

Messages for requesting and receiving information about generic sensors on devices, including batteries, radio levels, accelerometers, buttons, etc.

# BatteryLevelCmd

Description: Requests that a device send its battery level.

Introduced In Spec Version: 2

Last Updated In Spec Version: 2

Fields:

  • Id (unsigned int): Message Id
  • DeviceIndex (unsigned int): Index of device to query for battery reading.

Expected Response:

  • BatteryLevelReading message with matching Id on successful request.
  • Error message on value or message error.

Flow Diagram:

sequenceDiagram Client->>Server: BatteryLevelCmd Id=1 DeviceIndex=0 Server->>Client: BatteryLevelReading Id=1 DeviceIndex=0 BatteryLevel=0.5

Serialization Example:

[
  {
    "BatteryLevelCmd": {
      "Id": 1,
      "DeviceIndex": 0
    }
  }
]

# BatteryLevelReading

Description: Message containing a battery level reading from a device, as requested by BatteryLevelCmd.

Introduced In Spec Version: 2

Last Updated In Spec Version: 2

Fields:

  • Id (unsigned int): Message Id
  • DeviceIndex (unsigned int): Index of device battery reading is from.
  • BatteryLevel (double): Battery Level with a range of [0.0-1.0]

Expected Response:

  • None. Server-to-Client message only.

Flow Diagram:

sequenceDiagram Client->>Server: BatteryLevelCmd Id=1 DeviceIndex=0 Server->>Client: BatteryLevelReading Id=1 DeviceIndex=0 BatteryLevel=0.5

Serialization Example:

[
  {
    "BatteryLevelReading": {
      "Id": 1,
      "DeviceIndex": 0,
      "BatteryLevel": 0.5
    }
  }
]

# RSSILevelCmd

Description: Requests that a device send its RSSI level.

Introduced In Spec Version: 2

Last Updated In Spec Version: 2

Fields:

  • Id (unsigned int): Message Id
  • DeviceIndex (unsigned int): Index of device to query for RSSI level.

Expected Response:

  • RSSILevelReading message with matching Id on successful request.
  • Error message on value or message error.

Flow Diagram:

sequenceDiagram Client->>Server: RSSILevelCmd Id=1 DeviceIndex=0 Server->>Client: RSSILevelReading Id=1 DeviceIndex=0 RSSILevel=-40

Serialization Example:

[
  {
    "RSSILevelCmd": {
      "Id": 1,
      "DeviceIndex": 0
    }
  }
]

# RSSILevelReading

Description: Message containing a RSSI level reading from a device, as requested by RSSILevelCmd.

Introduced In Spec Version: 2

Last Updated In Spec Version: 2

Fields:

  • Id (unsigned int): Message Id
  • DeviceIndex (unsigned int): Index of device the reading is from.
  • RSSILevel (int): RSSI Level, usually expressed as db gain, usually [-100:0]

Expected Response:

  • None. Server-to-Client message only.

Flow Diagram:

sequenceDiagram Client->>Server: RSSILevelCmd Id=1 DeviceIndex=0 Server->>Client: RSSILevelReading Id=1 DeviceIndex=0 RSSILevel=-40

Serialization Example:

[
  {
    "RSSILevelReading": {
      "Id": 1,
      "DeviceIndex": 0,
      "RSSILevel": -40
    }
  }
]

← Deprecated Messages →