Websocket Connectors

The first thing to do when writing a Buttplug application is figuring out how to talk to a Buttplug Server. For sake of simplicity, we'll cover the most common option in this part of the manual, with other solutions covered in the cookbook section.

In the websocket case, you'll allow the user to connect to a Buttplug server they're running on their system, outside of your application (this usually means the user will be running Intiface Central or Intiface Engine). In almost all cases, your app will connect via websockets, most likely provided by the Buttplug Client implementation you are using.

For using Websocket servers, you'll need to provide the user a way to pass in the server address, then you just create the connector object using that address.

The Accidental Standard Port of 12345

When Buttplug's first public server came out in 2017, it used port 12345 as a test value. This stuck with the system, so now most applications that use Intiface or Buttplug use port 12345 for connection by default. Some client applications have gone as far as to hardcore the value, but this is not recommended.

This can sometimes be an issue for users running certain software that collides with the port. We have some recommended fixes on our forums.

Rust

use buttplug::{
  client::ButtplugClient,
  core::{
    connector::{ButtplugRemoteConnector, ButtplugWebsocketClientTransport, new_json_ws_client_connector},
    message::serializer::ButtplugClientJSONSerializer,
  },
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
  // To create a Websocket Connector, you need the websocket address and some generics fuckery.
  let connector = new_json_ws_client_connector("ws://192.168.123.103:12345/buttplug");

  let client = ButtplugClient::new("Example Client");
  client.connect(connector).await?;

  Ok(())
}

C#

using System;
using System.Threading.Tasks;
using Buttplug.Client;

namespace RemoteConnectorExample
{
    class Program
    {
        static async Task ConnectWebsocket()
        {
            // Creating a Websocket Connector is as easy as using the right
            // options object.
            var connector = new ButtplugWebsocketConnector(
                new Uri("ws://localhost:12345/buttplug"));
            var client = new ButtplugClient("Example Client");
            await client.ConnectAsync(connector);
        }

        static void Main(string[] args)
        {
            ConnectWebsocket().Wait();
        }
    }
}

Javascript

// This example assumes Buttplug is brought in as a root namespace, via
// inclusion by a script tag, i.e.
//
// <script lang="javascript" 
//   src="https://cdn.jsdelivr.net/npm/buttplug@3.0.0/dist/web/buttplug.min.js">
// </script>
//
// If you're trying to load this, change the version to the latest available.

const runWebsocketConnectionExample = async () => {
  // This is the default insecure address for Intiface Central (https://intiface.com/central). You
  // can connect to it via most browsers.
  let address = "ws://localhost:12345"

  // After you've created a connector, the connection looks the same no matter what, though the
  // errors thrown may be different.
  let connector = new Buttplug.ButtplugBrowserWebsocketClientConnector(address);

  let client = new Buttplug.ButtplugClient("Websocket Connection Example");

  // Now we connect. If anything goes wrong here, we'll either throw
  //
  // - A ButtplugClientConnectionException if there's a problem with
  //   the Connector, like the network address being wrong, server not
  //   being up, etc.
  // - A ButtplugHandshakeException if there is a client/server version
  //   mismatch.
  try {
    await client.connect(connector);
  }
  catch (ex)
  {
    // If our connection failed, because the server wasn't turned on, SSL/TLS
    // wasn't turned off, etc, we'll just print and exit here. This will most
    // likely be a wrapped exception.
    //
    // This could also mean our client is newer than our server, and we need to
    // upgrade the server we're connecting to.
    console.log(ex);
  }

  // We're connected, yay!
  console.log("Connected!");

  setTimeout(async () => {
    // And now we disconnect as usual
    console.log("Disconnecting");
    await client.disconnect();
  }, 3000);
  
};