Skip to main content

dsh-toy

58Stars6Forks1Issues0Watchers

DSH plugin connects Bluetooth toys to AI agents, automatically selects the connection method and applies time and intensity limits, with automatic stop at 30 seconds by default.

Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki
Language
TypeScript
License
BSD-3-Clause
Branch
main
dsh-plugin

Install

cmdweb profile
$ dsh plugin --profile web add github:c3ll256/dsh-toy

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin c3ll256/dsh-toy for me: review the repository at https://github.com/c3ll256/dsh-toy first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

One-Line Description

dsh-toy is a DSH plugin that connects hardware toys supporting Bluetooth, serial, or USB to an AI agent, enabling the agent to query models, automatically select connection methods, and enforce duration and intensity limits with automatic stop after 30 seconds.

Core Capabilities

  • Automatic connection method selection: Connects via known path when user provides model; on macOS, performs read-only raw BLE scan first, then decides between Intiface or share link channels
  • On-demand Intiface Engine startup: Downloads and verifies Buttplug official fixed version with SHA-256 if not installed locally; reuses existing installation if available
  • Direct device connection via share links: Implements proprietary protocol, supporting known models from AnKeni, Miji, ZuiQingFeng, and other brands
  • Intensity-limited scalar control: Exposes only vibration, oscillation, contraction, inflation, and suction actions, with values restricted to 0-100%
  • Mandatory automatic stop: Each control command auto-stops after 30 seconds by default, maximum 300 seconds; new commands replace old command timers
  • One-click emergency stop: Can pause individual devices or stop all devices at once

Technical Implementation

  • Language: TypeScript
  • Key dependencies: @deepseek-ai/schemastery (configuration and JSON Schema), @deepseek-ai/dsh-tools (tool registration), ws (WebSocket client)
  • Architecture pattern: Main entry registers 7 tools; runtime layer ToyRuntime serializes backend calls and performs duration/intensity boundary checks on each command; backend layer AutoToyBackend combines Buttplug and MonsterParty connection implementations as needed
  • Entry file: src/index.ts

Use Cases

When DSH users want the agent to control their existing hardware toys, they only need to tell the agent the brand and model—no need to install Intiface, select Bluetooth protocols, or manually start relay services. The plugin handles hardware connection, device discovery, and safety boundary enforcement. If users are concerned about accidental operation, the default 30-second auto-stop and intensity limits keep risks within reasonable bounds.

Prerequisites and Compatibility

DependencyMinimum VersionDescription
DSH>=0.1.0-rc.6peerDependencies declaration, optional dependency
Node.js>=22.19.0engines field requirement
PlatformmacOS / Linux / WindowsIntiface auto-download covers macOS ARM64, Linux x64/ARM64, Windows x64
Xcode Command Line ToolsRequired for macOS raw BLE scanProvides Swift compiler; otherwise falls back to Intiface
Native modulesNoneNo native dependencies referenced

Installation

dsh plugin --profile web add github:c3ll256/dsh-toy

Configuration Options

ConfigTypeDescriptionDefault
buttplugUrlstringWebSocket address for local Intifacews://127.0.0.1:12345
buttplugProtocolVersion3 or 4Use 3 for legacy Intiface4
monsterPartySessionTokenstringTemporary control credential extracted from share link; sourced only from plugin config, never appears in tool parametersunset
monsterPartyApiUrlstringParse endpoint for share link servicehttps://api.monsterparty.cc/main/v1/remote
monsterPartyOriginstringOrigin header for share link requestshttps://www.monsterparty.cn
clientNamestringClient identity announced during handshake to both endsdsh-toy
connectionTimeoutMsnumberHTTP or WebSocket connection timeout10000
requestTimeoutMsnumberSingle request timeout waiting for response5000
intifaceExecutablestringIntiface executable filename or absolute pathintiface-engine
intifaceStartupTimeoutMsnumberTimeout waiting for auto-started Intiface to begin listening10000
intifaceAutoDownloadbooleanWhether to download official fixed version when Intiface is not found locallytrue
readyTimeoutMsnumberShare link channel timeout waiting for device to be ready20000
heartbeatIntervalMsnumberShare link channel application-layer heartbeat interval9000
scanDurationMsnumberIntiface device discovery window5000
rawBleScanDurationMsnumbermacOS raw BLE discovery window10000
defaultDurationSecondsnumberDefault seconds when toy control command omits duration30
maxDurationSecondsnumberHard upper limit for command duration; rejected if exceeded300
maxIntensityPercentnumberHard upper limit for intensity percentage; rejected if exceeded100
allowHoldbooleanWhether to allow duration 0 for continuous operation; defaults to rejectfalse

FAQ

Q: What devices can this plugin control?

A: It supports Bluetooth, serial, and USB-type branded toys, as well as some manufacturers using share links (AnKeni, Miji, ZuiQingFeng, etc.). On macOS, it can also perform read-only raw BLE scan first to decide which connection path to take.

Q: Do I need to install Intiface Engine myself?

A: No. The plugin automatically downloads the fixed version from Buttplug's official GitHub Release, verifies SHA-256, and starts it by default. If Intiface is already running, it will reuse the existing instance instead of shutting it down.

Q: Is it safe to use?

A: All control commands undergo duration and intensity limit checks. Default auto-stop is 30 seconds, maximum intensity is 100%, maximum duration is 300 seconds. Only when allowHold is explicitly enabled can commands run continuously; otherwise, they are rejected.

Q: How do I use the MonsterParty share token?

A: Save it to the plugin configuration (commonly read from environment variables). Do not expose it directly to the model. Share tokens are typically single-use and become invalid after disconnection; you'll need to regenerate the link.

Q: What should I do when encountering "spawn intiface-engine ENOENT" error?

A: This means Intiface is not installed and auto-download failed. Update to a version that includes this capability, set intifaceAutoDownload to true, and verify access to GitHub.

Q: Can I use it on Windows / Linux?

A: Yes. Intiface auto-download supports macOS ARM64, Linux x64/ARM64, and Windows x64. Other platforms need to specify their own engine via intifaceExecutable.

Q: How do I stop everything completely?

A: Simply tell the agent to stop all devices, or use the toy controller. The plugin also automatically stops output and closes Intiface processes it started during unload or hot reload.

Q: Why does raw BLE scan only support macOS?

A: It depends on the Swift compiler provided by Xcode Command Line Tools. The scan is read-only—it discovers but doesn't connect or write to characteristics. Other platforms fall back directly to the Intiface path.

Learning Curve

Beginner-friendly — users only need to tell the agent the brand and model, no need to understand Intiface, Bluetooth protocols, or share links. The only manual steps are: macOS users granting Bluetooth permission on first scan, and Linux users installing Xcode Command Line Tools (rare dependency).

Known Issues and Limitations

  • Built-in RoomFun compatibility mapping has only been verified on physical hardware for Bluetooth name RoomFun, model identifier RF_CANNON_PT3, firmware 4.3, with one vibration output; other RoomFun models cannot be assumed compatible
  • Share link channel only implements relay behavior as documented by Chemtrails and AKN_DS_SUCKEGG mapping; if manufacturer protocol changes, the implementation needs updating
  • Intiface only exposes scalar functions mappable to percentages; position, direction, sensors, raw access, and subscription capabilities are outside current scope
  • Raw BLE scan only supports macOS and depends on Swift compiler from Xcode Command Line Tools; it's read-only discovery and cannot serve as a universal control protocol for unknown devices
  • Device IDs may change after reconnection; call toy_list again to refresh
  • Testing uses only local protocol fixtures, no real hardware connection
  • Share link tokens are typically single-use; they become invalid after disconnection and must be regenerated before reconnecting

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/c3ll256/dsh-toy)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory