bhaptics-http

HTTP REST bridge for bHaptics haptic hardware.

Wraps the bhaptics-python SDK in a lightweight aiohttp server, exposing a language-agnostic REST API so that any language or environment can drive bHaptics vests, arm bands, gloves, and other devices over plain HTTP.

Why?

bHaptics hardware is controlled through bHaptics Player (a Windows desktop app). The official SDK options are:

bhaptics-http fills the gap: run it once on Windows alongside bHaptics Player, then call it from Node.js, WSL2, Docker, another machine — or any curl command.

The key feature is /haptic/dot: raw per-motor intensity control with no bHaptics Studio pre-registration required.

Install

pip install bhaptics-http

Windows only — must run on the same machine as bHaptics Player.

Quick start

# Start bHaptics Player, then:
python -m bhaptics_http

bhaptics-http starting on 0.0.0.0:15883  (appId=BHapticsHTTP)
Endpoints:
  GET  http://0.0.0.0:15883/health
  POST http://0.0.0.0:15883/haptic
  POST http://0.0.0.0:15883/haptic/dot
  POST http://0.0.0.0:15883/haptic/stop

Test it:

curl http://localhost:15883/health
# {"ok": true, "backend": "bhaptics-python", "player": true}

curl -X POST http://localhost:15883/haptic/dot \
  -H 'Content-Type: application/json' \
  -d '{"deviceType":0,"duration":300,"motors":[{"index":0,"intensity":100},{"index":1,"intensity":100}]}'
# {"ok": true}

REST API

GET /health

Check connection to bHaptics Player.

{"ok": true, "backend": "bhaptics-python", "player": true}

POST /haptic

Play a named pattern registered in bHaptics Studio.

{ "event": "HeartBeat", "deviceIndex": 0 }

POST /haptic/dot

Play raw per-motor intensities — no Studio required.

{
  "deviceType": 0,
  "duration":   300,
  "motors": [
    {"index": 0, "intensity": 100},
    {"index": 4, "intensity":  60}
  ]
}

Device type reference:

intensity range: 0–100

POST /haptic/stop

Stop all currently playing haptic patterns.

{"ok": true}

Configuration

Or place a tact-config.json next to the server:

{ "appId": "MyApp", "apiKey": "" }

WSL2 / cross-machine setup

Run the server on Windows, then call it from WSL2 or another machine.

# Find your Windows host IP from WSL2:
cat /etc/resolv.conf | grep nameserver
# nameserver 172.22.112.1

# Then call:
curl http://172.22.112.1:15883/health

Windows Firewall: you may need to allow inbound TCP on port 15883:

# PowerShell (as Administrator):
New-NetFirewallRule -DisplayName "bhaptics-http" -Direction Inbound `
  -Protocol TCP -LocalPort 15883 -Action Allow

Or simply run the server and the client on the same Windows machine.

Node.js example

const BASE = "http://localhost:15883";

// Raw dot pattern — vest upper row
await fetch(`${BASE}/haptic/dot`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    deviceType: 0,
    duration: 300,
    motors: [
      { index: 0, intensity: 100 },
      { index: 1, intensity: 100 },
      { index: 2, intensity: 100 },
      { index: 3, intensity: 100 },
    ],
  }),
});

See examples/client.js for a full demo.

Python library usage

from aiohttp import web
from bhaptics_http.server import make_app, load_config

app_id, api_key = load_config()          # reads env / tact-config.json
app = make_app(app_id, api_key)
web.run_app(app, port=15883)

CLI options

python -m bhaptics_http --help

options:
  --port PORT       Port (default: 15883, env: BHAPTICS_HTTP_PORT)
  --host HOST       Bind interface (default: 0.0.0.0)
  --config PATH     Path to tact-config.json
  --app-id ID       bHaptics appId
  --api-key KEY     bHaptics apiKey

Citation

If you use this in academic work, please cite via Zenodo:

Vollmer, S.C. (2026). bhaptics-http: HTTP REST bridge for bHaptics haptic hardware [Software]. Zenodo. https://doi.org/XXXX/zenodo.XXXXXXX

(DOI will be updated after Zenodo deposit.)

Related

• bhaptics-python — official Python SDK (this package wraps it)
• bHaptics Developer Portal
• VR Ecology Project — research context where this was first developed

License

MIT © MissCrispenCakes