buttplug 3.2.1 → 4.0.0

package/examples/node/remote-connector-example.ts

@@ -0,0 +1,84 @@
+// Buttplug TypeScript - Remote Connector Example
+//
+// This example demonstrates the explicit WebSocket connector setup.
+// While you can create a connector inline, creating it explicitly
+// gives you more control over the connection parameters.
+//
+// Prerequisites:
+// 1. Install Intiface Central: https://intiface.com/central
+// 2. Start the server in Intiface Central
+// 3. Run: npx ts-node --esm remote-connector-example.ts
+
+import {
+  ButtplugClient,
+  ButtplugNodeWebsocketClientConnector,
+  ButtplugBrowserWebsocketClientConnector,
+} from 'buttplug';
+import * as readline from 'readline';
+
+async function waitForEnter(prompt: string): Promise<void> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    rl.question(prompt, () => {
+      rl.close();
+      resolve();
+    });
+  });
+}
+
+async function main(): Promise<void> {
+  // Method 1: Inline connector creation (most common)
+  // This is the simplest approach for most applications.
+  console.log('Method 1: Inline connector creation');
+  console.log('  const connector = new ButtplugNodeWebsocketClientConnector(url);');
+  console.log('  await client.connect(connector);');
+  console.log('  (Simple and direct)\n');
+
+  // Method 2: Explicit connector creation
+  // Use this when you need to reuse the connector or
+  // configure it before connecting.
+  console.log('Method 2: Explicit connector creation');
+  console.log('  const connector = new ButtplugNodeWebsocketClientConnector(url);');
+  console.log('  // ... configure connector if needed ...');
+  console.log('  await client.connect(connector);');
+  console.log('  (More control over connector lifecycle)\n');
+
+  // Note about environments:
+  // - Node.js: Use ButtplugNodeWebsocketClientConnector (uses 'ws' package)
+  // - Browser: Use ButtplugBrowserWebsocketClientConnector (uses native WebSocket)
+  console.log('Environment-specific connectors:');
+  console.log('  - Node.js: ButtplugNodeWebsocketClientConnector');
+  console.log('  - Browser: ButtplugBrowserWebsocketClientConnector\n');
+
+  // Let's actually connect using the explicit connector method
+  const client = new ButtplugClient('Remote Connector Example');
+  const connector = new ButtplugNodeWebsocketClientConnector(
+    'ws://127.0.0.1:12345'
+  );
+
+  console.log('Connecting using explicit connector...');
+  try {
+    await client.connect(connector);
+    console.log('Connected successfully!');
+    console.log(`  Connected: ${client.connected}`);
+
+    await waitForEnter('\nPress Enter to disconnect...');
+
+    await client.disconnect();
+    console.log('Disconnected.');
+  } catch (e) {
+    if (e instanceof Error) {
+      console.log(`Connection failed: ${e.message}`);
+    }
+    console.log(
+      '\nMake sure Intiface Central is running with the server started.'
+    );
+  }
+
+  await waitForEnter('\nPress Enter to exit...');
+}
+
+main().catch(console.error);

package/examples/node/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "./dist",
+    "rootDir": "."
+  },
+  "include": ["*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/examples/web/application-example.js

@@ -0,0 +1,197 @@
+// Buttplug Web - Complete Application Example
+//
+// This is a complete, working example that demonstrates the full workflow
+// of a Buttplug application in a browser. If you're new to Buttplug, start here!
+//
+// Prerequisites:
+// 1. Install Intiface Central: https://intiface.com/central
+// 2. Start the server in Intiface Central (click "Start Server")
+// 3. Include Buttplug via CDN in your HTML:
+//    <script src="https://cdn.jsdelivr.net/npm/buttplug@4.0.0/dist/web/buttplug.min.js"></script>
+// 4. Call runApplicationExample() from your page
+
+async function runApplicationExample() {
+  console.log("===========================================");
+  console.log("  Buttplug Web Application Example");
+  console.log("===========================================\n");
+
+  // Step 1: Create a client
+  // The client name identifies your application to the server.
+  const client = new Buttplug.ButtplugClient("My Buttplug Application");
+
+  // Step 2: Set up event handlers
+  // Always do this BEFORE connecting to avoid missing events.
+  client.addListener("deviceadded", (device) => {
+    console.log(`[+] Device connected: ${device.name}`);
+  });
+
+  client.addListener("deviceremoved", (device) => {
+    console.log(`[-] Device disconnected: ${device.name}`);
+  });
+
+  client.addListener("disconnect", () => {
+    console.log("[!] Server connection lost!");
+  });
+
+  // Step 3: Connect to the server
+  console.log("Connecting to Intiface Central...");
+  try {
+    const connector = new Buttplug.ButtplugBrowserWebsocketClientConnector(
+      "ws://127.0.0.1:12345"
+    );
+    await client.connect(connector);
+  } catch (e) {
+    if (e instanceof Buttplug.ButtplugClientConnectorException) {
+      alert(
+        "Could not connect to Intiface Central!\n\n" +
+        "Make sure Intiface Central is running and the server is started.\n" +
+        "Default address: ws://127.0.0.1:12345"
+      );
+      console.log("ERROR: Could not connect to Intiface Central!");
+      return;
+    }
+    throw e;
+  }
+  console.log("Connected!\n");
+
+  // Step 4: Scan for devices
+  console.log("Scanning for devices...");
+  console.log("Turn on your Bluetooth/USB devices now.\n");
+  await client.startScanning();
+
+  // Wait for devices (using alert/confirm for browser interaction)
+  alert("Scanning for devices...\n\nTurn on your devices, then click OK when ready.");
+  await client.stopScanning();
+
+  // Step 5: Check what devices we found
+  const devices = Array.from(client.devices.values());
+  if (devices.length === 0) {
+    alert(
+      "No devices found!\n\n" +
+      "Make sure your device is:\n" +
+      "- Turned on\n" +
+      "- In pairing/discoverable mode\n" +
+      "- Supported by Buttplug (check https://iostindex.com)"
+    );
+    console.log("No devices found.");
+    await client.disconnect();
+    return;
+  }
+
+  console.log(`\nFound ${devices.length} device(s):\n`);
+
+  // Step 6: Display device capabilities
+  for (const device of devices) {
+    console.log(`  ${device.name}`);
+
+    // Check output capabilities
+    const outputs = [];
+    if (device.hasOutput(Buttplug.OutputType.Vibrate)) outputs.push("Vibrate");
+    if (device.hasOutput(Buttplug.OutputType.Rotate)) outputs.push("Rotate");
+    if (device.hasOutput(Buttplug.OutputType.Oscillate)) outputs.push("Oscillate");
+    if (device.hasOutput(Buttplug.OutputType.Position)) outputs.push("Position");
+    if (device.hasOutput(Buttplug.OutputType.Constrict)) outputs.push("Constrict");
+
+    if (outputs.length > 0) {
+      console.log(`    Outputs: ${outputs.join(", ")}`);
+    }
+
+    // Check input capabilities
+    const inputs = [];
+    if (device.hasInput(Buttplug.InputType.Battery)) inputs.push("Battery");
+    if (device.hasInput(Buttplug.InputType.RSSI)) inputs.push("RSSI");
+
+    if (inputs.length > 0) {
+      console.log(`    Inputs: ${inputs.join(", ")}`);
+    }
+  }
+
+  // Step 7: Interactive device control
+  console.log("\n=== Interactive Control ===");
+  console.log("Use the prompts to control devices.");
+
+  let running = true;
+  while (running) {
+    const input = prompt(
+      "Commands:\n" +
+      "  v <0-100>  - Vibrate all devices at percentage\n" +
+      "  s          - Stop all devices\n" +
+      "  b          - Read battery levels\n" +
+      "  q          - Quit\n\n" +
+      "Enter command:"
+    );
+
+    if (input === null) {
+      // User clicked Cancel
+      running = false;
+      continue;
+    }
+
+    const cmd = input.trim().toLowerCase();
+
+    if (!cmd) continue;
+
+    try {
+      if (cmd.startsWith("v ")) {
+        // Vibrate command
+        const percentStr = cmd.slice(2);
+        const percent = parseInt(percentStr, 10);
+        if (!isNaN(percent) && percent >= 0 && percent <= 100) {
+          const intensity = percent / 100.0;
+          for (const device of devices) {
+            if (device.hasOutput(Buttplug.OutputType.Vibrate)) {
+              await device.runOutput(Buttplug.DeviceOutput.Vibrate.percent(intensity));
+              console.log(`  ${device.name}: vibrating at ${percent}%`);
+            }
+          }
+        } else {
+          alert("Usage: v <0-100>");
+        }
+      } else if (cmd === "s") {
+        // Stop all devices
+        await client.stopAllDevices();
+        console.log("  All devices stopped.");
+      } else if (cmd === "b") {
+        // Read battery levels
+        let batteryInfo = "Battery Levels:\n\n";
+        for (const device of devices) {
+          if (device.hasInput(Buttplug.InputType.Battery)) {
+            try {
+              const battery = await device.battery();
+              const msg = `${device.name}: ${(battery * 100).toFixed(0)}%`;
+              console.log(`  ${msg}`);
+              batteryInfo += msg + "\n";
+            } catch (e) {
+              console.log(`  ${device.name}: could not read battery`);
+              batteryInfo += `${device.name}: could not read battery\n`;
+            }
+          } else {
+            console.log(`  ${device.name}: no battery sensor`);
+            batteryInfo += `${device.name}: no battery sensor\n`;
+          }
+        }
+        alert(batteryInfo);
+      } else if (cmd === "q") {
+        running = false;
+      } else {
+        alert("Unknown command. Use v, s, b, or q.");
+      }
+    } catch (e) {
+      if (e instanceof Buttplug.ButtplugDeviceError) {
+        console.log(`  Device error: ${e.message}`);
+        alert(`Device error: ${e.message}`);
+      } else if (e instanceof Buttplug.ButtplugError) {
+        console.log(`  Error: ${e.message}`);
+        alert(`Error: ${e.message}`);
+      } else {
+        throw e;
+      }
+    }
+  }
+
+  // Step 8: Clean up
+  console.log("\nStopping devices and disconnecting...");
+  await client.stopAllDevices();
+  await client.disconnect();
+  console.log("Goodbye!");
+}

package/examples/web/async-example.js

@@ -0,0 +1,90 @@
+// Buttplug Web - Async Patterns Example
+//
+// This example demonstrates async/await patterns and event handling
+// in the Buttplug library. The library is fully async - all operations
+// that might block (network, device communication) use async/await.
+//
+// Include Buttplug via CDN:
+// <script src="https://cdn.jsdelivr.net/npm/buttplug@4.0.0/dist/web/buttplug.min.js"></script>
+
+async function runAsyncExample() {
+  console.log("Running async example");
+
+  const client = new Buttplug.ButtplugClient("Async Example");
+
+  // Events in buttplug-js use EventEmitter3.
+  // You can use addListener or on to subscribe to events.
+
+  // 'deviceadded' is fired when a new device connects
+  client.addListener("deviceadded", async (device) => {
+    // Note: Event handlers can be async!
+    console.log(`[Event] Device added: ${device.name}`);
+
+    // You can interact with the device in the event handler
+    if (device.hasOutput(Buttplug.OutputType.Vibrate)) {
+      console.log("  Sending welcome vibration...");
+      await device.runOutput(Buttplug.DeviceOutput.Vibrate.percent(0.25));
+      await new Promise(r => setTimeout(r, 200));
+      await device.stop();
+    }
+  });
+
+  // 'deviceremoved' is fired when a device disconnects
+  client.addListener("deviceremoved", (device) => {
+    console.log(`[Event] Device removed: ${device.name}`);
+  });
+
+  // 'scanningfinished' is fired when scanning completes
+  // (some protocols scan continuously until stopped)
+  client.addListener("scanningfinished", () => {
+    console.log("[Event] Scanning finished");
+  });
+
+  // 'disconnect' is fired when the server connection drops
+  client.addListener("disconnect", () => {
+    console.log("[Event] Server disconnected!");
+  });
+
+  // 'inputreading' is fired when subscribed sensor data arrives
+  client.addListener("inputreading", (reading) => {
+    console.log(`[Event] Input reading: ${JSON.stringify(reading)}`);
+  });
+
+  // Connect asynchronously - this may take time due to network
+  console.log("Connecting to server...");
+  const connector = new Buttplug.ButtplugBrowserWebsocketClientConnector("ws://127.0.0.1:12345");
+  await client.connect(connector);
+  console.log("Connected!");
+
+  // Scanning is also async - we start it and wait for events
+  console.log("Starting scan. Turn on devices now...");
+  console.log("(Events will be printed as devices connect)");
+  await client.startScanning();
+
+  // Demonstrate concurrent operations after 5 seconds
+  setTimeout(async () => {
+    console.log("\nDemonstrating concurrent device control...");
+
+    // Convert devices Map to array
+    const devices = Array.from(client.devices.values());
+
+    if (devices.length > 0) {
+      // Send commands to all devices concurrently
+      const tasks = devices
+        .filter((d) => d.hasOutput(Buttplug.OutputType.Vibrate))
+        .map(async (device) => {
+          console.log(`  Vibrating ${device.name}...`);
+          await device.runOutput(Buttplug.DeviceOutput.Vibrate.percent(0.5));
+          await new Promise(r => setTimeout(r, 500));
+          await device.stop();
+          console.log(`  ${device.name} stopped.`);
+        });
+
+      // Wait for all commands to complete
+      await Promise.all(tasks);
+      console.log("All devices stopped.");
+    } else {
+      console.log("No devices connected.");
+    }
+  }, 5000);
+}

package/examples/web/device-control-example.js

@@ -0,0 +1,87 @@
+// Buttplug Web - Device Control Example
+//
+// This example demonstrates how to send commands to devices,
+// query device capabilities, and use the v4 command builder API.
+//
+// Include Buttplug via CDN:
+// <script src="https://cdn.jsdelivr.net/npm/buttplug@4.0.0/dist/web/buttplug.min.js"></script>
+
+async function runDeviceControlExample() {
+  const connector = new Buttplug.ButtplugBrowserWebsocketClientConnector("ws://127.0.0.1:12345");
+  const client = new Buttplug.ButtplugClient("Device Control Example");
+
+  // Set up event handlers before connecting
+  client.addListener("deviceadded", async (device) => {
+    console.log(`Device connected: ${device.name}`);
+
+    // Show currently connected devices (client.devices is a Map in v4)
+    console.log("Currently connected devices:");
+    for (const [index, dev] of client.devices) {
+      console.log(`  - ${dev.name} (Index: ${index})`);
+    }
+
+    // Check if device supports vibration using v4 API
+    if (!device.hasOutput(Buttplug.OutputType.Vibrate)) {
+      console.log("Device does not support vibration, skipping control demo.");
+      return;
+    }
+
+    console.log("Device supports vibration. Sending commands...");
+
+    try {
+      // Use the v4 command builder API
+      console.log("Vibrating at 100%...");
+      await device.runOutput(Buttplug.DeviceOutput.Vibrate.percent(1.0));
+
+      await new Promise(r => setTimeout(r, 1000));
+
+      console.log("Vibrating at 50%...");
+      await device.runOutput(Buttplug.DeviceOutput.Vibrate.percent(0.5));
+
+      await new Promise(r => setTimeout(r, 1000));
+
+      console.log("Stopping device...");
+      await device.stop();
+    } catch (e) {
+      console.log("Error sending command:", e);
+      if (e instanceof Buttplug.ButtplugDeviceError) {
+        console.log("This is a device error - device may have disconnected.");
+      }
+    }
+
+    // Check for battery support using v4 API
+    if (device.hasInput(Buttplug.InputType.Battery)) {
+      try {
+        const level = await device.battery();
+        console.log(`${device.name} Battery Level: ${(level * 100).toFixed(0)}%`);
+      } catch (e) {
+        console.log("Could not read battery level:", e);
+      }
+    }
+
+    // Demonstrate other output types if available
+    if (device.hasOutput(Buttplug.OutputType.Rotate)) {
+      console.log("Device supports rotation. Rotating at 50%...");
+      await device.runOutput(Buttplug.DeviceOutput.Rotate.percent(0.5));
+      await new Promise(r => setTimeout(r, 1000));
+      await device.stop();
+    }
+
+    if (device.hasOutput(Buttplug.OutputType.Position)) {
+      console.log("Device supports position control. Moving...");
+      await device.runOutput(Buttplug.DeviceOutput.PositionWithDuration.percent(1.0, 500));
+      await new Promise(r => setTimeout(r, 1000));
+      await device.runOutput(Buttplug.DeviceOutput.PositionWithDuration.percent(0.0, 500));
+    }
+  });
+
+  client.addListener("deviceremoved", (device) => {
+    console.log(`Device disconnected: ${device.name}`);
+  });
+
+  console.log("Connecting...");
+  await client.connect(connector);
+  console.log("Connected! Scanning for devices...");
+
+  await client.startScanning();
+}

package/examples/web/device-enumeration-example.js

@@ -0,0 +1,49 @@
+// Buttplug Web - Device Enumeration Example
+//
+// This example demonstrates how to scan for devices and handle
+// device connection/disconnection events.
+//
+// Include Buttplug via CDN:
+// <script src="https://cdn.jsdelivr.net/npm/buttplug@4.0.0/dist/web/buttplug.min.js"></script>
+
+async function runDeviceEnumerationExample() {
+  const client = new Buttplug.ButtplugClient("Device Enumeration Example");
+
+  // Set up event handlers BEFORE connecting.
+  // This ensures we don't miss any events, including devices
+  // that are already connected to the server.
+
+  client.addListener("deviceadded", (device) => {
+    console.log(`Device connected: ${device.name}`);
+
+    // The client maintains a Map of all known devices.
+    // In v4, client.devices is a Map<number, ButtplugClientDevice>
+    console.log("Currently connected devices:");
+    for (const [index, dev] of client.devices) {
+      console.log(`  - ${dev.name} (Index: ${index})`);
+    }
+  });
+
+  client.addListener("deviceremoved", (device) => {
+    console.log(`Device disconnected: ${device.name}`);
+  });
+
+  client.addListener("scanningfinished", () => {
+    console.log("Scanning finished.");
+  });
+
+  // Connect to the server (requires Intiface Central running)
+  const connector = new Buttplug.ButtplugBrowserWebsocketClientConnector("ws://localhost:12345");
+
+  console.log("Connecting...");
+  await client.connect(connector);
+  console.log("Connected!");
+
+  // Start scanning for devices.
+  // Devices will be announced via the 'deviceadded' event.
+  console.log("Starting device scan... Turn on your devices now!");
+  await client.startScanning();
+
+  // Note: In a real application, you would call client.stopScanning()
+  // when you're done scanning, and client.disconnect() when finished.
+}

package/examples/web/device-info-example.js

@@ -0,0 +1,100 @@
+// Buttplug Web - Device Info Example
+//
+// This example demonstrates how to introspect device features
+// and capabilities in detail using the v4 API.
+//
+// Include Buttplug via CDN:
+// <script src="https://cdn.jsdelivr.net/npm/buttplug@4.0.0/dist/web/buttplug.min.js"></script>
+
+function printDeviceInfo(device) {
+  console.log("==================================================");
+  console.log(`Device: ${device.name}`);
+  if (device.displayName) {
+    console.log(`Display Name: ${device.displayName}`);
+  }
+  console.log(`Index: ${device.index}`);
+  if (device.messageTimingGap !== undefined) {
+    console.log(`Message Timing Gap: ${device.messageTimingGap}ms`);
+  }
+  console.log("==================================================");
+
+  // Collect output capabilities
+  const outputTypes = [];
+  if (device.hasOutput(Buttplug.OutputType.Vibrate)) outputTypes.push("Vibrate");
+  if (device.hasOutput(Buttplug.OutputType.Rotate)) outputTypes.push("Rotate");
+  if (device.hasOutput(Buttplug.OutputType.Oscillate)) outputTypes.push("Oscillate");
+  if (device.hasOutput(Buttplug.OutputType.Position)) outputTypes.push("Position");
+  if (device.hasOutput(Buttplug.OutputType.Constrict)) outputTypes.push("Constrict");
+  if (device.hasOutput(Buttplug.OutputType.Inflate)) outputTypes.push("Inflate");
+  if (device.hasOutput(Buttplug.OutputType.Temperature)) outputTypes.push("Temperature");
+  if (device.hasOutput(Buttplug.OutputType.Led)) outputTypes.push("LED");
+
+  if (outputTypes.length > 0) {
+    console.log(`\nOutput Capabilities: ${outputTypes.join(", ")}`);
+  }
+
+  // Collect input capabilities
+  const inputTypes = [];
+  if (device.hasInput(Buttplug.InputType.Battery)) inputTypes.push("Battery");
+  if (device.hasInput(Buttplug.InputType.RSSI)) inputTypes.push("RSSI");
+  if (device.hasInput(Buttplug.InputType.Button)) inputTypes.push("Button");
+  if (device.hasInput(Buttplug.InputType.Pressure)) inputTypes.push("Pressure");
+
+  if (inputTypes.length > 0) {
+    console.log(`Input Capabilities: ${inputTypes.join(", ")}`);
+  }
+
+  // Detailed feature breakdown
+  console.log("\nDetailed Features:");
+  for (const [index, feature] of device.features) {
+    // Access the underlying feature definition
+    const def = feature._feature;
+    console.log(`\n  Feature ${index}: ${def.FeatureDescriptor}`);
+
+    if (def.Output) {
+      console.log("    Outputs:");
+      for (const [type, config] of Object.entries(def.Output)) {
+        console.log(`      - ${type}: steps ${config.Value[0]}-${config.Value[1]}`);
+      }
+    }
+
+    if (def.Input) {
+      console.log("    Inputs:");
+      for (const [type, config] of Object.entries(def.Input)) {
+        console.log(`      - ${type}: commands [${config.Command.join(", ")}]`);
+      }
+    }
+  }
+}
+
+async function runDeviceInfoExample() {
+  const client = new Buttplug.ButtplugClient("Device Info Example");
+
+  // Connect to the server
+  const connector = new Buttplug.ButtplugBrowserWebsocketClientConnector("ws://127.0.0.1:12345");
+
+  console.log("Connecting...");
+  await client.connect(connector);
+  console.log("Connected! Scanning for devices...");
+  console.log("Turn on your devices now. Info will be printed as they connect.\n");
+
+  // Set up device event to print info when devices connect
+  client.addListener("deviceadded", (device) => {
+    printDeviceInfo(device);
+  });
+
+  await client.startScanning();
+
+  // After a few seconds, also show summary of all connected devices
+  setTimeout(() => {
+    console.log("\n\n========== SUMMARY ==========");
+    if (client.devices.size === 0) {
+      console.log("No devices connected.");
+    } else {
+      console.log(`Found ${client.devices.size} device(s):`);
+      for (const [index, device] of client.devices) {
+        console.log(`  ${index}: ${device.name}`);
+      }
+    }
+  }, 5000);
+}