Device Control

We've connected, we've enumerated, now it's time for the important stuff. Device Control!

Device Capabilities

The devices Buttplug supports can do many different things. They may vibrate, stroke, rotate, stimulate via electricity, some combination of all of these, or possibly something completely different.

In order to trigger these different mechanisms, Command Messages are used. These messages all end in "Cmd". For now we'll just look at vibrating and stopping, but there's descriptions of other messages in the Winning Ways section.

When a device is added, it comes with a list of messages it can accept, as well as certain parameters for those messages. For instance, if you have a vibrating buttplug (an actual buttplug toy), it may accept the following messages

  • VibrateCmd
    • This command can takes speeds from 0.0-1.0, or a list of speeds if a device contains multiple vibrators. For now, we'll assume we just have 1 vibrator.
    • When a device supports this message, it will send info about how many vibrators it has, as well as the number of actual speed steps it can use, so you aren't stuck guessing power values to send and can present the user with options or round to the nearest step in the 0.0-1.0 range.
  • StopDeviceCmd
    • This command takes no arguments, and simply stops the device from whatever its doing. The Buttplug Server has enough information to know what actions a device can perform, so it handles making sure all of those actions are stopped.

You'll usually interact with devices with Device instances, which will be different than the Buttplug Client. While the Client handles things like scanning and device lists, a Device instance will let you command a specific device.

Sending Device Messages

As a user of a Buttplug Client API, you should never be expected to send raw Buttplug Messages. Most Client APIs will provide message sending functions for you, usually attached to device objects or structures. If the device accepts the message type represented by the function you call, it should be sent to the device. Otherwise, you'll receive an error about message compatibility.

  • Rust
  • C#
  • Javascript
use tokio::io::{self, BufReader, AsyncBufReadExt};
use buttplug::{
  client::{device::VibrateCommand, ButtplugClient, ButtplugClientError, ButtplugClientDeviceMessageType},
  connector::ButtplugInProcessClientConnector,
  test::new_bluetoothle_test_device,
};

async fn wait_for_input() {
  BufReader::new(io::stdin()).lines().next_line().await.unwrap();
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
  let connector = ButtplugInProcessClientConnector::default();
  let server = connector.server_ref();
  server.add_test_comm_manager()?;
  let client = ButtplugClient::new("Example Client");
  client.connect(connector).await?;

  // For this example, we'll use the Test device. This is included in Buttplug
  // Rust >= v0.1.0. It emulates how a regular device manager would work,
  // exposing access to a Test Device which can take VibrateCmd messages. This
  // exists as a way to test connection and setup UI without having to use
  // actual hardware.
  let (_, _) = new_bluetoothle_test_device("Test Device").await?;

  println!("Connected!");

  // You usually shouldn't run Start/Stop scanning back-to-back like
  // this, but with TestDevice we know our device will be found when we
  // call StartScanning, so we can get away with it.
  client.start_scanning().await?;
  client.stop_scanning().await?;
  println!("Client currently knows about these devices:");
  for device in client.devices() {
    println!("- {}", device.name);
  }
  wait_for_input().await;

  for device in client.devices() {
    println!("{} supports these messages:", device.name);
    for (r#type, attributes) in &device.allowed_messages {
      println!("- {}", r#type);
      if let Some(count) = attributes.feature_count {
        println!(" - Features: {}", count);
      }
    }
  }

  println!("Sending commands");

  // Now that we know the message types for our connected device, we
  // can send a message over! Seeing as we want to stick with the
  // modern generic messages, we'll go with VibrateCmd.
  //
  // There's a couple of ways to send this message.
  let test_client_device = &client.devices()[0];

  // We can use the convenience functions on ButtplugClientDevice to
  // send the message. This version sets all of the motors on a
  // vibrating device to the same speed.
  test_client_device
    .vibrate(VibrateCommand::Speed(1.0))
    .await?;

  // If we wanted to just set one motor on and the other off, we could
  // try this version that uses an array. It'll throw an exception if
  // the array isn't the same size as the number of motors available as
  // denoted by FeatureCount, though.
  //
  // You can get the vibrator count using the following code, though we
  // know it's 2 so we don't really have to use it.
  let vibrator_count = test_client_device
    .allowed_messages
    .get(&ButtplugClientDeviceMessageType::VibrateCmd)
    .and_then(|attributes| attributes.feature_count);

  println!("{} has {} vibrators.", test_client_device.name, vibrator_count.unwrap_or(0));

  test_client_device
    .vibrate(VibrateCommand::SpeedVec(vec![1.0, 0.0]))
    .await?;

  wait_for_input().await;

  // And now we disconnect as usual.
  client.disconnect().await?;

  // If we try to send a command to a device after the client has
  // disconnected, we'll get an exception thrown.
  let vibrate_result = test_client_device.vibrate(VibrateCommand::Speed(1.0)).await;
  if let Err(ButtplugClientError::ButtplugConnectorError(error)) = vibrate_result {
    println!("Tried to send after disconnection! Error: ");
    println!("{}", error);
  }
  wait_for_input().await;

  Ok(())
}