{"id":13779899,"url":"https://github.com/runtime-shady-backroom/buttplug-lite","last_synced_at":"2025-05-11T13:31:15.753Z","repository":{"id":47090832,"uuid":"324566170","full_name":"runtime-shady-backroom/buttplug-lite","owner":"runtime-shady-backroom","description":"simplified buttplug.io API for when JSON is infeasible","archived":false,"fork":false,"pushed_at":"2024-07-29T01:10:23.000Z","size":1009,"stargazers_count":19,"open_issues_count":9,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-08-03T18:14:29.022Z","etag":null,"topics":["buttplug","gui","haptics","neos","neosvr","teledildonics","vibrator","vr","websocket"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/runtime-shady-backroom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-26T13:57:36.000Z","updated_at":"2024-07-19T10:24:34.000Z","dependencies_parsed_at":"2024-01-15T22:42:19.374Z","dependency_job_id":"40a964dd-b24c-42e3-b38d-fcd6636c1ce1","html_url":"https://github.com/runtime-shady-backroom/buttplug-lite","commit_stats":null,"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runtime-shady-backroom%2Fbuttplug-lite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runtime-shady-backroom%2Fbuttplug-lite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runtime-shady-backroom%2Fbuttplug-lite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runtime-shady-backroom%2Fbuttplug-lite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/runtime-shady-backroom","download_url":"https://codeload.github.com/runtime-shady-backroom/buttplug-lite/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225056747,"owners_count":17414198,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["buttplug","gui","haptics","neos","neosvr","teledildonics","vibrator","vr","websocket"],"created_at":"2024-08-03T18:01:10.340Z","updated_at":"2025-05-11T13:31:15.683Z","avatar_url":"https://github.com/runtime-shady-backroom.png","language":"Rust","funding_links":[],"categories":["Virtual Worlds"],"sub_categories":["Terraria"],"readme":"# Buttplug Lite\n\nThis application serves a websocket that runs a dramatically simplified version of the [Buttplug Sex Device Control Standard](https://buttplug-spec.docs.buttplug.io/) protocol. This allows commands to be sent to devices with significantly less programming, making integration feasible in more restricted environments where the buttplug.io protocol is difficult or impossible to implement.\n\n## Installation and Usage\n\n1. Download the [latest release](https://github.com/runtime-shady-backroom/buttplug-lite/releases/latest).\n2. Run buttplug-lite-windows.exe (or your operating system's appropriate binary if you aren't on Windows. Builds are also provided for macOS and Linux. See the section below for a way to use this via the Nix package manager)\n3. Add tags for the devices you plan to use.\n4. Press \"apply configuration\" to save your settings and apply them to the current server.\n\n### Install via Nix\n\n1. To use this, you need to make use of the Flake system. If you dont know what that means, look at https://wiki.nixos.org/wiki/Flakes before you continue. You cannot use this without making use of Flakes.\n2. In your flake.nix file, add `buttplug-lite = { url = \"github:runtime-shady-backroom/buttplug-lite?ref=master\"; inputs.nixpkgs.follows = \"nixpkgs\"; };` to your inputs at the top of the file.\n3. Pass `buttplug-lite` through to where ever you want to use the package.\n4. Add the package `buttplug-lite.packages.x86_64-linux.default` to whatever way you use to add packages. Things like `environment.systemPackages`.\n\n## Features\n\n- Extremely simple fire-and-forget protocol\n- Standalone application requiring no other software\n\n![screenshot of GUI](https://raw.githubusercontent.com/wiki/runtime-shady-backroom/buttplug-lite/images/buttplug-lite-2.0.0.png)\n\n## Supported Devices\n\nAll [buttplug.io supported devices](https://iostindex.com/?filter0ButtplugSupport=4) should work. This includes everything from Lovense devices to Xbox controllers.\n\n## Building from Source\n\n1. [Install Rust](https://www.rust-lang.org/tools/install)\n2. Clone the project\n3. `cargo build --release`\n\n## Integrations\n\n### Resonite\n\nA ProtoFlux reference implementation is available in this public folder:  \n`resrec:///U-Lehti/R-78C43B7CC794EE59412305C9A161E9883AA05BF82565325D8C28012018119E00` (paste that link in-game to spawn it).\n\nBelow is a screenshot of the reference implementation.\n\n![screenshot of reference implementation](https://raw.githubusercontent.com/wiki/runtime-shady-backroom/buttplug-lite/images/reference-implementation-resonite-1.0.jpg)\n\nThis implementation is designed to go on an avatar. The top half of the ProtoFlux handles resetting the websocket connection when a new user enters the avatar, and can be omitted if the avatar will only ever be used by one user. The lower half of the ProtoFlux sends updates to the buttplug-lite server at around 7 Hz. If you go too far beyond 7 Hz you may start to run into latency issues. The two float inputs should be between zero and one (inclusive) and represent the desired motor intensity. You could source this from any number of places, such as Nearest User Hand, VirtualHapticPointSampler, or even a simple UI slider.\n\n## Manual\n\n### Sending Commands\n\nSend text-type messages to `ws://127.0.0.1:3031/haptic`. Binary-type messages are not currently supported. Commands should be sent at most at a 10hz rate. Beyond that application performance may begin to degrade.\n\n#### Message Format\n\nThe message format is a list of semicolon (`;`) delimited motor commands. There are three possible types of command: Scalar, Linear, and Rotation. All commands start with a motor tag, which is a user-defined string representing a specific motor on a specific device.\n\n##### Scalar\n\n`tag:strength`\n\nStrength controls motor intensity and ranges from `0.0` to `1.0`.\n\n##### Linear\n\n`tag:duration:position`\n\nPosition controls target position and ranges from `0.0` to `1.0`.  \nDuration controls time in milliseconds the device should take to move to the target position. Duration must be a positive integer.\n\n##### Rotation\n\n`tag:speed`\n\nSpeed controls the speed of rotation and ranges from `-1.0` to `1.0`. Positive numbers are clockwise, negative numbers are counterclockwise.\n\n##### Contraction (Deprecated)\n\n`tag:level`\n\n**Only supported in versions  0.5.3 to 1.1.0**. Starting in version 2, contraction is handled via a scalar command.\n\nContraction controls the pump strength on the Lovense Max. It must be an integer between `0` and `3`, inclusive.\n\n#### An Example Command\n\n| Tag    | Type     | Strength | Duration | Position | Speed | Contraction |\n|--------|----------|---------:|---------:|---------:|------:|------------:|\n| foo    | Scalar   |       0% |          |          |       |             |\n| bar    | Scalar   |      30% |          |          |       |             |\n| baz    | Scalar   |     100% |          |          |       |             |\n| gort   | Linear   |          |     20ms |      25% |       |             |\n| klaatu | Linear   |          |    400ms |      75% |       |             |\n| barada | Rotation |          |          |          | -0.75 |             |\n| nikto  | Rotation |          |          |          |  0.26 |             |\n\n\n```\nfoo:0;bar:0.3;baz:1;gort:20:0.25;klaatu:400:0.75;barada:-0.75;nikto:0.26\n```\n\nNote that you are not required to specify all the tagged motors if you don't want to. The following is also valid, but will of course only drive the `foo` motor.\n```\nfoo:0.1\n```\n\n#### Motor State\n\nMotors will continue running at the vibration and rotation speeds last commanded until another update is received.\n\nIf no command is received for 10 seconds, buttplug-lite will send a stop command to all connected devices. To avoid this, send commands periodically even if your desired motor state has not changed.\n\n### Checking the Application Version\n\nSend an HTTP GET to `http://127.0.0.1:3031/`. A 200 OK will be returned with body containing the application name and version. Example response:\n```\nbuttplug-lite 0.7.0\n```\nPrior to version 0.7.0 this endpoint is a 404.\n\n### Checking the Configuration\n\nSend an HTTP GET to `http://127.0.0.1:3031/deviceconfig`. A 200 OK will be returned with body containing a machine-readable list of configured motors. Example response:\n```\no;Lovense Edge;scalar\nc;Lovense Max;scalar\ni;Lovense Edge;scalar\nm;Lovense Max;scalar\n```\n\nThe response is a newline (LF) delimited list of motor configurations. There is a trailing newline. Each motor configuration line is a semicolon (`;`) delimited list of tag, device name, and motor type. In the case where there are no configured motors the response body will be an empty string.\n\nPossible motors types are: `linear`, `rotation`, and `scalar`.\n\nPrior to version 0.7.0 this endpoint is a 404.\n\n### Checking the Status\n\nSend an HTTP GET to `http://127.0.0.1:3031/hapticstatus`. A 200 OK will be returned with body containing a plain text summary of the connection status and connected devices. **This response is intended for debugging and is not intended to be parsed.** The response structure is subject to change. If you have a use case that requires parsing device status let me know by opening an issue.\n\nExample response:\n```\ndevice server running=true\n  Lovense Edge\n    ScalarCmd: ClientGenericDeviceMessageAttributes { feature_descriptor: \"No description available for feature\", _actuator_type: Vibrate, step_count: 20 }\n    ScalarCmd: ClientGenericDeviceMessageAttributes { feature_descriptor: \"No description available for feature\", _actuator_type: Vibrate, step_count: 20 }\n  Lovense Hush\n    ScalarCmd: ClientGenericDeviceMessageAttributes { feature_descriptor: \"No description available for feature\", _actuator_type: Vibrate, step_count: 20 }\n  Lovense Max\n    ScalarCmd: ClientGenericDeviceMessageAttributes { feature_descriptor: \"Vibrator\", _actuator_type: Vibrate, step_count: 20 }\n    ScalarCmd: ClientGenericDeviceMessageAttributes { feature_descriptor: \"Air Pump\", _actuator_type: Constrict, step_count: 5 }\n  The Handy\n    LinearCmd: ClientGenericDeviceMessageAttributes { feature_descriptor: \"No description available for feature\", _actuator_type: Position, step_count: 100 }\n```\n\n### Checking Battery\nSend an HTTP GET to `http://127.0.0.1:3031/batterystatus`. A 200 OK will be returned with body containing a plain text list of devices and battery levels. Devices are delimited by newlines, battery levels are delimited by `:`. If the device has an unknown battery level a `-1` will be returned. Example:\n```\nLovense Edge:1\nLovense Max:0.45\n```\n\n## Command-Line Arguments\n\nbuttplug-lite is intended to be used as a GUI, but for debugging purposes a few command-line arguments are included.\n\n```\nUsage: buttplug-lite [OPTIONS]\n\nOptions:\n  -v, --verbose...               Sets the level of verbosity. Repeating this argument up to four times will apply increasingly verbose log_filter presets\n  -c, --stdout                   Log to stdout instead of the default log file\n  -f, --log-filter \u003cLOG_FILTER\u003e  Custom logging filter: https://docs.rs/tracing-subscriber/0.3.16/tracing_subscriber/filter/struct.EnvFilter.html. This completely overrides the `--verbose` setting\n      --debug-ticks \u003cSECONDS\u003e    Emit periodic ApplicationStatusEvent ticks every \u003cSECONDS\u003e seconds. These \"ticks\" force the UI to update device state, which for example can be used to poll device battery levels\n      --no-panic-handler         Disables the custom panic handler in the log file. Has no effect if used with `--stdout`\n      --force-panic-handler      Enables the custom panic handler in stdout logs. Has no effect if file logging is used. Note that file logging is the default without an explicit `--stdout`\n  -h, --help                     Print help\n  -V, --version                  Print version\n```\n\n## Files\n\nHere is where buttplug lite stores its various files on your filesystem:\n\n|                             | Windows                                                    | macOS                                                                                   | *nix                                                                           |\n|-----------------------------|------------------------------------------------------------|-----------------------------------------------------------------------------------------|--------------------------------------------------------------------------------|\n| **Configuration Directory** | `%APPDATA%\\runtime-shady-backroom\\buttplug-lite\\config`    | `$HOME/Library/Application Support/io.github.runtime-shady-backroom.buttplug-lite`      | `$XDG_CONFIG_HOME/buttplug-lite` or `$HOME/.config/buttplug-lite`              |\n| **Log Directory**           | `%APPDATA%\\runtime-shady-backroom\\buttplug-lite\\data\\logs` | `$HOME/Library/Application Support/io.github.runtime-shady-backroom.buttplug-lite/logs` | `$XDG_DATA_HOME/buttplug-lite/logs` or `$HOME/.local/share/buttplug-lite/logs` |\n\nNote that once a maximum of 50 log files are reached, old logs will be rotated out.\n\n## Feedback\n\nIf you have bugs to report or ideas to suggest please let me know by opening an [issue](https://github.com/runtime-shady-backroom/buttplug-lite/issues) or starting a [discussion](https://github.com/runtime-shady-backroom/buttplug-lite/discussions).\n\n## License\n\nCopyright 2022-2023 [runtime-shady-backroom](https://github.com/runtime-shady-backroom) and [buttplug-lite contributors](https://github.com/runtime-shady-backroom/buttplug-lite/graphs/contributors).\n\nButtplug Lite is provided under the [AGPL-3.0 license](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruntime-shady-backroom%2Fbuttplug-lite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fruntime-shady-backroom%2Fbuttplug-lite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruntime-shady-backroom%2Fbuttplug-lite/lists"}