Buttplug sex toy control library
buttplug.io
1# Buttplug
2
3[](https://www.patreon.com/qdot)
4[](https://www.github.com/sponsors/qdot)
5[](https://discuss.buttplug.io)
6[](https://discord.buttplug.io)
7[](https://twitter.com/buttplugio)
8[](https://bsky.app/profile/buttplug.io)
9
10[](https://crates.io/crates/buttplug)
11[](https://crates.io/crates/buttplug)
12[](https://crates.io/crates/buttplug)
13
14<div align="center">
15 <h3>
16 <a href="https://docs.rs/buttplug">
17 Rust API Documentation
18 </a>
19 <span> | </span>
20 <a href="https://docs.buttplug.io/docs/dev-guide">
21 Developer Guide
22 </a>
23 <span> | </span>
24 <a href="https://docs.buttplug.io/docs/spec">
25 Protocol Spec
26 </a>
27 <span> | </span>
28 <a href="https://awesome.buttplug.io">
29 Apps and Games List
30 </a>
31 </h3>
32</div>
33
34<p align="center">
35 <picture>
36 <source media="(prefers-color-scheme: light)" srcset="images/buttplug_rust_docs.png">
37 <source media="(prefers-color-scheme: dark)" srcset="images/buttplug_rust_docs_light.png">
38 <img src="https://raw.githubusercontent.com/buttplugio/buttplug/master/images/buttplug_rust_docs.png">
39 </picture>
40</p>
41
42## Are you in the right place?
43
44If you're just looking to hook your hardware up to something that says it "supports Buttplug/Intiface" (like one of the many apps/games in [our awesome list](https://awesome.buttplug.io)), you're in the wrong place. For that you'll most likely want to go check out [Intiface Central](https://intiface.com/central).
45
46This is where we store all of the source code for the libraries that run your hardware. If you're a developer and interesting in that sort of thing, read on...
47
48## Introduction
49
50[Buttplug](https://buttplug.io) is a framework for hooking up hardware to interfaces, where:
51
52- hardware usually means sex toys, but could honestly be just about anything
53- interfaces usually means media players or games, but could also be just about anything
54
55It's basically a userland HID manager for things that may not specifically support formal HID.
56
57In more concrete terms, think of Buttplug as something like [osculator](http://www.osculator.net/)
58or [VRPN](https://vrpn.github.io), but for sex toys. Instead of wiimotes and control surfaces, we
59interface with vibrators, strokers, fucking machines, and other [hardware that can communicate with computers](https://iostindex.com) (though we do actually support vibration in gamepads, joycons, and more).
60
61This repo contains all of the core libraries for the framework, as well as Intiface Engine, the command line utility for setting up Buttplug Servers.
62
63[Intiface Central](https://intiface.com/central) is recommended for end users. It is a Flutter based GUI on top of Buttplug and Intiface Engine that runs on all desktop and popular mobile platforms.
64
65We also produce [btleplug](https://github.com/deviceplug/btleplug), the host-side Bluetooth LE library that Buttplug uses to communicate with BLE devices.
66
67## Apps, Games, and More!
68
69For a list of applications using Buttplug and Intiface, see the [awesome-buttplug repo](https://github.com/buttplugio/awesome-buttplug).
70
71## Beta on main branch?! REALLY?
72
73We've been working on the next version of our message spec for the better part of 3 years now, which has come with massive changes to the library. Rather than let this sit on our `dev` branch for another few months while we run through the beta process, we decided to promote beta to our main branch so it gets visibility. We'll still be marking beta versions in crates and releases, so package installs will still default to pre-beta version until we've released.
74
75Also I hadn't updated the README on the project in several years and didn't want to have to rewrite for both the old and new libraries. So here we are.
76
77## Hardware Support
78
79Buttplug-rs is currently capable of controlling toys via:
80
81- Bluetooth LE (Desktop and Android/iOS)
82- Serial Ports (Desktop)
83- USB HID (Desktop)
84- Lovense Devices via the Lovense Dongle (HID and Serial dongles, Desktop)
85- Lovense Connect App (Desktop and Android/iOS)
86- Websockets (for simulated and DIY devices, Desktop and Android/iOS)
87- XInput gamepads (Windows only)
88
89See [IOSTIndex](https://iostindex.com) for a full list of supported hardware (Filter on "Buttplug Rust").
90
91## Documentation and Examples
92
93To learn how to use the Buttplug Library, check out the [Buttplug Developer Guide](https://docs.buttplug.io/docs/dev-guide).
94
95Examples are included in the [examples](examples/) portion of this repo.
96
97## Crates
98
99This project consists of the following crates:
100
101| Crate Name | Description |
102| ---- | ----------- |
103| buttplug | meta-crate that's just a rehost on buttplug_client, see README for more info |
104| buttplug_client | Buttplug Rust Client, useful for building application that will access Intiface Engine or Intiface Central. We recommend most developers use this. See crate README for more info. |
105| buttplug_client_in_process | Buttplug Rust Client w/ integrated Buttplug Server. Useful for building standalone applications and examples. |
106| buttplug_core | Contains the protocol message schema, message class implementations, and structures shared by the client and server implementations. Will be rarely needed as a direct dependency. |
107| buttplug_derive | Procedural macros used in the Buttplug rust implementation. Will be rarely needed as a direct dependency. |
108| buttplug_server | The core server implementation, including server and device structures, all protocol implementations, etc... |
109| buttplug_server_device_config | Device configuration file loading and database implementation. |
110| buttplug_server_hwmgr_btleplug | Bluetooth LE device communication support |
111| buttplug_server_hwmgr_hid | HID device communication support |
112| buttplug_server_hwmgr_lovense_connect | Lovense Connect device communication support (soon to be deprecated) |
113| buttplug_server_hwmgr_lovense_dongle | Lovense Dongle device communication support (soon to be deprecated) |
114| buttplug_server_hwmgr_serial | Serial device communication support |
115| buttplug_server_hwmgr_websocket | Websocket device communication suppor, used for devices that may connect in ways not directly supported by other formats |
116| buttplug_server_hwmgr_xinput | XInput gamepad support (windows only) |
117| buttplug_tests | For tests that need the whole framework |
118| buttplug_transport_websocket_tungstenite | Communications transport for clients/servers using tokio-tungstenite |
119| intiface_engine | Command line interface for running a Buttplug server |
120
121For more information on each crate, check the README in its directory in this repo.
122
123## Compiling
124
125On Windows and macOS, running `cargo build` should suffice for building the project. All
126dependencies are vendored in.
127
128On Linux, the following packages will be needed to build with default features:
129
130- `libudev-dev` (Required for serial port/HID support)
131- `libusb-1.0-0-dev` (Required for serial port/HID support)
132
133The package names are listed as their Debian requirements, and may be different for other
134distributions. Removing the `lovense-dongle-manager` and `serial-manager` features should stop these
135from being required.
136
137## Usage
138
139To use Buttplug in your Rust application or library, check out the
140[buttplug package on crates.io](https://crates.io/crates/buttplug).
141
142The following crate features are available
143
144| Feature | Other Features Used | Description |
145| --------- | ----------- | ----------- |
146| `client` | None | Buttplug client implementation (in-process connection only) |
147| `server` | None | Buttplug server implementation (in-process connection only) |
148| `websockets` | `tokio-runtime` | Websocket connectors, used to connect remote clients (Clear/SSL)/servers (Clear Only) |
149| `btleplug-manager` | `server` | Bluetooth hardware support on Windows >=10, macOS, Linux, iOS, Android |
150| `lovense-dongle-manager` | `server` | Lovense USB Dongle support on Windows >=7, macOS, Linux |
151| `serial-manager` | `server` | Serial Port hardware support on Windows >=7, macOS, Linux |
152| `xinput-manager` | `server` | XInput Gamepad support on Windows >=7 |
153| `lovense-connect-service-manager` | `server` | Lovense Connect App support (all platforms) |
154| `websocket-server-manager` | `websockets` | Support for connecting devices via Websockets (all platforms) |
155| `dummy-runtime` | None | Runtime that panics on any spawn. Only used for tests. |
156| `tokio-runtime` | None | Uses tokio for futures |
157| `wasm-bindgen-runtime` | None | Uses the wasm-bindgen executor as a runtime (WASM only) |
158
159Default features are enough to build a full desktop system:
160
161- `tokio-runtime`
162- `client`
163- `server`
164- `websocket`
165- `websocket-server-manager`
166- `btleplug-manager` (feature builds as noop on WASM)
167- `serial-manager` (feature builds as noop on iOS, Android)
168- `lovense-dongle-manager` (feature builds as noop on iOS, Android)
169- `xinput-manager` (feature is only relevant on windows, but builds as a noop on all
170 other platforms).
171
172## Filing Issues and Contributing
173
174If you have issues or feature requests, please feel free to [file an
175issue](https://github.com/buttplugio/buttplug-rs/issues).
176
177**We are not looking for unsolicited code contributions or pull requests, and will not accept
178pull requests that do not have a matching issue where the matter was previously discussed in an issue on this repo or in one of our communication channels, listed below.**
179
180Pull requests should only be submitted after talking to [qdot](https://github.com/qdot) via issues
181(or on [Discord](https://discord.buttplug.io), [our forums](https://discuss.buttplug.io), or via DMs
182on one of our social media accounts if you would like to stay anonymous and out of recorded info on
183the repo) and receiving approval to develop code based on an issue. Any random or non-issue pull
184requests will most likely be closed without merging.
185
186If you'd like to contribute in a non-technical way, we need money to keep up with supporting the
187latest and greatest hardware. We have multiple ways to donate!
188
189- [Patreon](https://patreon.com/qdot)
190- [Github Sponsors](https://github.com/sponsors/qdot)
191- [Ko-Fi](https://ko-fi.com/qdot76367)
192
193## Other Language Implementations
194
195See the [awesome-buttplug repo](https://github.com/buttplugio/awesome-buttplug#development-and-libraries) for a full list of client implementations in other programming languages.
196
197## License
198
199Buttplug is BSD 3-Clause licensed.
200
201```text
202
203Copyright (c) 2016-2025, Nonpolynomial, LLC
204All rights reserved.
205
206Redistribution and use in source and binary forms, with or without
207modification, are permitted provided that the following conditions are met:
208
209* Redistributions of source code must retain the above copyright notice, this
210 list of conditions and the following disclaimer.
211
212* Redistributions in binary form must reproduce the above copyright notice,
213 this list of conditions and the following disclaimer in the documentation
214 and/or other materials provided with the distribution.
215
216* Neither the name of buttplug nor the names of its
217 contributors may be used to endorse or promote products derived from
218 this software without specific prior written permission.
219
220THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
221AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
222IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
223DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
224FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
225DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
226SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
227CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
228OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
229OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
230```
231