bhaptics-http 0.1.0__tar.gz

bhaptics_http-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+*.egg
+MANIFEST
+.pytest_cache/
+.mypy_cache/
+tact-config.json

bhaptics_http-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MissCrispenCakes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bhaptics_http-0.1.0/PKG-INFO

@@ -0,0 +1,294 @@
+Metadata-Version: 2.4
+Name: bhaptics-http
+Version: 0.1.0
+Summary: HTTP REST bridge for bHaptics haptic hardware — raw dot patterns, no Studio required
+Project-URL: Homepage, https://github.com/MissCrispenCakes/bhaptics-http
+Project-URL: Documentation, https://github.com/MissCrispenCakes/bhaptics-http#readme
+Project-URL: Issues, https://github.com/MissCrispenCakes/bhaptics-http/issues
+Author: MissCrispenCakes
+License: MIT License
+        
+        Copyright (c) 2026 MissCrispenCakes
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: TactSuit,VR,WSL2,XR,api,bhaptics,bridge,haptics,rest,tactile,wearables
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: bhaptics-python>=0.2.0
+Provides-Extra: dev
+Requires-Dist: aiohttp[speedups]; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# bhaptics-http
+
+**HTTP REST bridge for bHaptics haptic hardware.**
+
+Wraps the [`bhaptics-python`](https://github.com/bhaptics/bhaptics-python) SDK in a lightweight [aiohttp](https://docs.aiohttp.org/) 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:
+
+| SDK | Works in | Raw dot patterns? |
+|-----|----------|------------------|
+| tact-js | Browser only (WASM) | No (needs Studio) |
+| bhaptics-python | Windows Python | Yes — but no HTTP |
+| bHaptics REST API | Via Player | No raw dot control |
+
+**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
+
+```bash
+pip install bhaptics-http
+```
+
+> **Windows only** — must run on the same machine as bHaptics Player.
+
+---
+
+## Quick start
+
+```bash
+# 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:
+
+```bash
+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.
+
+```json
+{"ok": true, "backend": "bhaptics-python", "player": true}
+```
+
+---
+
+### `POST /haptic`
+
+Play a named pattern registered in bHaptics Studio.
+
+```json
+{ "event": "HeartBeat", "deviceIndex": 0 }
+```
+
+---
+
+### `POST /haptic/dot`
+
+**Play raw per-motor intensities — no Studio required.**
+
+```json
+{
+  "deviceType": 0,
+  "duration":   300,
+  "motors": [
+    {"index": 0, "intensity": 100},
+    {"index": 4, "intensity":  60}
+  ]
+}
+```
+
+**Device type reference:**
+
+| deviceType | Device |
+|-----------|--------|
+| 0 | TactSuit X16 / X40 (chest vest) |
+| 1 | Tactosy2 left arm |
+| 2 | Tactosy2 right arm |
+| 3 | TactVisor head |
+| 6 | Tactosy feet left |
+| 7 | Tactosy feet right |
+| 8 | TactGlove left |
+| 9 | TactGlove right |
+
+`intensity` range: `0`–`100`
+
+---
+
+### `POST /haptic/stop`
+
+Stop all currently playing haptic patterns.
+
+```json
+{"ok": true}
+```
+
+---
+
+## Configuration
+
+| Environment variable | Default | Description |
+|---------------------|---------|-------------|
+| `BHAPTICS_HTTP_PORT` | `15883` | Port to listen on |
+| `BHAPTICS_APP_ID`   | `BHapticsHTTP` | App ID for bHaptics Player auth |
+| `BHAPTICS_API_KEY`  | `""` | API key (usually empty for local Player) |
+
+Or place a `tact-config.json` next to the server:
+
+```json
+{ "appId": "MyApp", "apiKey": "" }
+```
+
+---
+
+## WSL2 / cross-machine setup
+
+Run the server on **Windows**, then call it from WSL2 or another machine.
+
+```bash
+# 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
+# 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
+
+```js
+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`](examples/client.js) for a full demo.
+
+---
+
+## Python library usage
+
+```python
+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](https://github.com/bhaptics/bhaptics-python) — official Python SDK (this package wraps it)
+- [bHaptics Developer Portal](https://developer.bhaptics.com/)
+- [VR Ecology Project](https://github.com/MissCrispenCakes/VR_ECOLOGY_PROJECT) — research context where this was first developed
+
+---
+
+## License
+
+MIT © MissCrispenCakes

bhaptics_http-0.1.0/README.md

@@ -0,0 +1,242 @@
+# bhaptics-http
+
+**HTTP REST bridge for bHaptics haptic hardware.**
+
+Wraps the [`bhaptics-python`](https://github.com/bhaptics/bhaptics-python) SDK in a lightweight [aiohttp](https://docs.aiohttp.org/) 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:
+
+| SDK | Works in | Raw dot patterns? |
+|-----|----------|------------------|
+| tact-js | Browser only (WASM) | No (needs Studio) |
+| bhaptics-python | Windows Python | Yes — but no HTTP |
+| bHaptics REST API | Via Player | No raw dot control |
+
+**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
+
+```bash
+pip install bhaptics-http
+```
+
+> **Windows only** — must run on the same machine as bHaptics Player.
+
+---
+
+## Quick start
+
+```bash
+# 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:
+
+```bash
+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.
+
+```json
+{"ok": true, "backend": "bhaptics-python", "player": true}
+```
+
+---
+
+### `POST /haptic`
+
+Play a named pattern registered in bHaptics Studio.
+
+```json
+{ "event": "HeartBeat", "deviceIndex": 0 }
+```
+
+---
+
+### `POST /haptic/dot`
+
+**Play raw per-motor intensities — no Studio required.**
+
+```json
+{
+  "deviceType": 0,
+  "duration":   300,
+  "motors": [
+    {"index": 0, "intensity": 100},
+    {"index": 4, "intensity":  60}
+  ]
+}
+```
+
+**Device type reference:**
+
+| deviceType | Device |
+|-----------|--------|
+| 0 | TactSuit X16 / X40 (chest vest) |
+| 1 | Tactosy2 left arm |
+| 2 | Tactosy2 right arm |
+| 3 | TactVisor head |
+| 6 | Tactosy feet left |
+| 7 | Tactosy feet right |
+| 8 | TactGlove left |
+| 9 | TactGlove right |
+
+`intensity` range: `0`–`100`
+
+---
+
+### `POST /haptic/stop`
+
+Stop all currently playing haptic patterns.
+
+```json
+{"ok": true}
+```
+
+---
+
+## Configuration
+
+| Environment variable | Default | Description |
+|---------------------|---------|-------------|
+| `BHAPTICS_HTTP_PORT` | `15883` | Port to listen on |
+| `BHAPTICS_APP_ID`   | `BHapticsHTTP` | App ID for bHaptics Player auth |
+| `BHAPTICS_API_KEY`  | `""` | API key (usually empty for local Player) |
+
+Or place a `tact-config.json` next to the server:
+
+```json
+{ "appId": "MyApp", "apiKey": "" }
+```
+
+---
+
+## WSL2 / cross-machine setup
+
+Run the server on **Windows**, then call it from WSL2 or another machine.
+
+```bash
+# 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
+# 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
+
+```js
+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`](examples/client.js) for a full demo.
+
+---
+
+## Python library usage
+
+```python
+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](https://github.com/bhaptics/bhaptics-python) — official Python SDK (this package wraps it)
+- [bHaptics Developer Portal](https://developer.bhaptics.com/)
+- [VR Ecology Project](https://github.com/MissCrispenCakes/VR_ECOLOGY_PROJECT) — research context where this was first developed
+
+---
+
+## License
+
+MIT © MissCrispenCakes

bhaptics_http-0.1.0/examples/client.js

@@ -0,0 +1,123 @@
+/**
+ * bhaptics-http — Node.js client example
+ *
+ * Demonstrates how to drive bHaptics hardware from Node.js (or any
+ * environment with fetch) once bhaptics-http is running on Windows.
+ *
+ * Setup:
+ *   1. On Windows: pip install bhaptics-http && python -m bhaptics_http
+ *   2. On WSL2/Linux/Mac: set HOST to your Windows IP (see WSL2 note below)
+ *   3. node examples/client.js
+ *
+ * WSL2 note:
+ *   Your Windows host IP is typically 172.x.x.1 — find it with:
+ *     cat /etc/resolv.conf | grep nameserver
+ *   Set HOST below (or export BHAPTICS_HTTP_HOST=172.x.x.1 in your shell).
+ */
+
+const HOST = process.env.BHAPTICS_HTTP_HOST ?? "localhost";
+const PORT = process.env.BHAPTICS_HTTP_PORT ?? "15883";
+const BASE = `http://${HOST}:${PORT}`;
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+async function health() {
+  const res = await fetch(`${BASE}/health`);
+  return res.json();
+}
+
+/**
+ * Play a named Studio event (must be registered in bHaptics Studio first).
+ * @param {string} event        Pattern name as registered in Studio
+ * @param {number} deviceIndex  0 = first device of this type
+ */
+async function playEvent(event, deviceIndex = 0) {
+  const res = await fetch(`${BASE}/haptic`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ event, deviceIndex }),
+  });
+  return res.json();
+}
+
+/**
+ * Play raw motor intensities — no Studio pre-registration required.
+ *
+ * @param {number} deviceType   Device type ID (see device table below)
+ * @param {number} duration     Duration in milliseconds
+ * @param {Array}  motors       Array of {index, intensity} objects
+ *
+ * Device types:
+ *   0  = TactSuit X16/X40 (chest vest), 16 or 40 motors
+ *   1  = Tactosy2 left arm,  6 motors
+ *   2  = Tactosy2 right arm, 6 motors
+ *   3  = TactVisor head,     4 motors
+ *   6  = Tactosy feet left,  3 motors
+ *   7  = Tactosy feet right, 3 motors
+ *   8  = TactGlove left,     6 motors
+ *   9  = TactGlove right,    6 motors
+ */
+async function playDot(deviceType, duration, motors) {
+  const res = await fetch(`${BASE}/haptic/dot`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ deviceType, duration, motors }),
+  });
+  return res.json();
+}
+
+/** Stop all playing patterns. */
+async function stopAll() {
+  const res = await fetch(`${BASE}/haptic/stop`, { method: "POST" });
+  return res.json();
+}
+
+// ── demo ─────────────────────────────────────────────────────────────────────
+
+async function demo() {
+  console.log("1. Health check …");
+  const h = await health();
+  console.log("   ", h);
+
+  if (!h.ok) {
+    console.error("bHaptics Player not connected. Is it running on Windows?");
+    process.exit(1);
+  }
+
+  // -- Raw dot pattern: vest upper-front row (motors 0-3), full intensity
+  console.log("2. Vest upper-front row — 300 ms …");
+  await playDot(0, 300, [
+    { index: 0, intensity: 100 },
+    { index: 1, intensity: 100 },
+    { index: 2, intensity: 100 },
+    { index: 3, intensity: 100 },
+  ]);
+  await new Promise((r) => setTimeout(r, 500));
+
+  // -- Raw dot pattern: left arm full, then right arm full
+  console.log("3. Left arm — 200 ms …");
+  await playDot(1, 200, [
+    { index: 0, intensity: 80 },
+    { index: 1, intensity: 80 },
+    { index: 2, intensity: 80 },
+  ]);
+  await new Promise((r) => setTimeout(r, 300));
+
+  console.log("4. Right arm — 200 ms …");
+  await playDot(2, 200, [
+    { index: 0, intensity: 80 },
+    { index: 1, intensity: 80 },
+    { index: 2, intensity: 80 },
+  ]);
+  await new Promise((r) => setTimeout(r, 300));
+
+  // -- Named Studio event (uncomment if you have a pattern registered)
+  // console.log("5. Named event …");
+  // await playEvent("HeartBeat");
+
+  console.log("5. Stop all.");
+  await stopAll();
+  console.log("Done.");
+}
+
+demo().catch(console.error);

bhaptics_http-0.1.0/examples/client_python.py

@@ -0,0 +1,58 @@
+"""
+bhaptics-http — Python client example (requests)
+
+Shows how to call the server from a separate Python script
+(e.g. from WSL2 or another machine).
+
+Setup:
+    pip install requests
+    # On Windows: python -m bhaptics_http
+    # Then: python examples/client_python.py
+"""
+
+import os
+import time
+import requests
+
+HOST = os.environ.get("BHAPTICS_HTTP_HOST", "localhost")
+PORT = os.environ.get("BHAPTICS_HTTP_PORT", "15883")
+BASE = f"http://{HOST}:{PORT}"
+
+
+def health():
+    return requests.get(f"{BASE}/health").json()
+
+
+def play_dot(device_type: int, duration: int, motors: list[dict]) -> dict:
+    return requests.post(
+        f"{BASE}/haptic/dot",
+        json={"deviceType": device_type, "duration": duration, "motors": motors},
+    ).json()
+
+
+def play_event(event: str, device_index: int = 0) -> dict:
+    return requests.post(
+        f"{BASE}/haptic",
+        json={"event": event, "deviceIndex": device_index},
+    ).json()
+
+
+def stop_all() -> dict:
+    return requests.post(f"{BASE}/haptic/stop").json()
+
+
+if __name__ == "__main__":
+    print("Health:", health())
+
+    print("Left arm sweep …")
+    for i in range(6):
+        play_dot(1, 80, [{"index": i, "intensity": 100}])
+        time.sleep(0.1)
+
+    print("Right arm sweep …")
+    for i in range(6):
+        play_dot(2, 80, [{"index": i, "intensity": 100}])
+        time.sleep(0.1)
+
+    print("Stop all.")
+    stop_all()

bhaptics_http-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires      = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name        = "bhaptics-http"
+version     = "0.1.0"
+description = "HTTP REST bridge for bHaptics haptic hardware — raw dot patterns, no Studio required"
+readme      = "README.md"
+license     = { file = "LICENSE" }
+authors     = [{ name = "MissCrispenCakes" }]
+keywords    = [
+    "bhaptics", "haptics", "tactile", "XR", "VR", "wearables",
+    "TactSuit", "rest", "api", "bridge", "WSL2"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Human Machine Interfaces",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.9"
+dependencies    = [
+    "bhaptics-python>=0.2.0",
+    "aiohttp>=3.9.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "pytest-asyncio>=0.23",
+    "aiohttp[speedups]",
+]
+
+[project.urls]
+Homepage      = "https://github.com/MissCrispenCakes/bhaptics-http"
+Documentation = "https://github.com/MissCrispenCakes/bhaptics-http#readme"
+Issues        = "https://github.com/MissCrispenCakes/bhaptics-http/issues"
+
+[project.scripts]
+bhaptics-http = "bhaptics_http.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bhaptics_http"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/",
+    "examples/",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]

bhaptics_http-0.1.0/src/bhaptics_http/__init__.py

@@ -0,0 +1,30 @@
+"""
+bhaptics-http
+~~~~~~~~~~~~~
+
+HTTP REST bridge for the bHaptics haptic hardware ecosystem.
+
+Wraps the bhaptics-python SDK in a lightweight aiohttp server so that
+any language or environment (Node.js, browser fetch, WSL2, Docker, …)
+can drive bHaptics vests, arm bands, gloves, and other devices over
+plain HTTP — including raw per-motor dot patterns that require no
+bHaptics Studio pre-registration.
+
+Quick start:
+    pip install bhaptics-http
+    python -m bhaptics_http          # starts on port 15883
+
+    # then from anywhere:
+    curl http://localhost:15883/health
+    curl -X POST http://localhost:15883/haptic/dot \\
+         -H 'Content-Type: application/json' \\
+         -d '{"deviceType":0,"duration":200,"motors":[{"index":0,"intensity":100}]}'
+"""
+
+__version__ = "0.1.0"
+__author__  = "MissCrispenCakes"
+__license__ = "MIT"
+
+from bhaptics_http.server import make_app, load_config, init_bhaptics
+
+__all__ = ["make_app", "load_config", "init_bhaptics", "__version__"]

bhaptics_http-0.1.0/src/bhaptics_http/__main__.py

@@ -0,0 +1,75 @@
+"""
+Entry point for:  python -m bhaptics_http
+
+Starts the bhaptics-http REST server.
+All configuration is via environment variables or tact-config.json.
+See `python -m bhaptics_http --help` for options.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+from pathlib import Path
+
+from aiohttp import web
+
+from bhaptics_http.server import make_app, load_config
+
+logging.basicConfig(level=logging.INFO, format="[%(levelname)s] %(message)s")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="python -m bhaptics_http",
+        description="bHaptics HTTP REST bridge — drive haptic hardware over HTTP",
+    )
+    parser.add_argument(
+        "--port", "-p",
+        type=int,
+        default=int(os.environ.get("BHAPTICS_HTTP_PORT", "15883")),
+        help="Port to listen on (default: 15883, env: BHAPTICS_HTTP_PORT)",
+    )
+    parser.add_argument(
+        "--host",
+        default="0.0.0.0",
+        help="Host interface to bind (default: 0.0.0.0)",
+    )
+    parser.add_argument(
+        "--config",
+        type=Path,
+        default=None,
+        help="Path to tact-config.json (default: auto-detect)",
+    )
+    parser.add_argument(
+        "--app-id",
+        default=None,
+        help="bHaptics appId (overrides env / config file)",
+    )
+    parser.add_argument(
+        "--api-key",
+        default=None,
+        help="bHaptics apiKey (overrides env / config file)",
+    )
+    args = parser.parse_args()
+
+    app_id, api_key = load_config(args.config)
+    if args.app_id:
+        app_id = args.app_id
+    if args.api_key:
+        api_key = args.api_key
+
+    print(f"bhaptics-http starting on {args.host}:{args.port}  (appId={app_id})")
+    print("Endpoints:")
+    print(f"  GET  http://{args.host}:{args.port}/health")
+    print(f"  POST http://{args.host}:{args.port}/haptic")
+    print(f"  POST http://{args.host}:{args.port}/haptic/dot")
+    print(f"  POST http://{args.host}:{args.port}/haptic/stop")
+
+    app = make_app(app_id, api_key, config_path=args.config)
+    web.run_app(app, host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+    main()

bhaptics_http-0.1.0/src/bhaptics_http/server.py

@@ -0,0 +1,313 @@
+"""
+bhaptics_http.server
+~~~~~~~~~~~~~~~~~~~~
+
+Lightweight aiohttp HTTP server that wraps the bhaptics-python SDK,
+exposing a language-agnostic REST interface for bHaptics hardware.
+
+Useful when:
+  - You are running in an environment where tact-js (browser WASM) is
+    unavailable (Node.js server, Python script, WSL2, Docker, CI).
+  - You want to drive raw dot/motor patterns without pre-registering
+    .tact files in bHaptics Studio.
+  - You need a single Windows-side process that any language can call
+    over HTTP.
+
+Usage (standalone):
+    pip install bhaptics-http
+    python -m bhaptics_http            # default port 15883
+    python -m bhaptics_http --port 8080
+
+Usage (library):
+    from bhaptics_http.server import make_app
+    app = make_app(app_id="MyApp", api_key="")
+    # pass to aiohttp.web.run_app(app, port=15883)
+
+Environment variables:
+    BHAPTICS_APP_ID       Override appId  (default: from tact-config.json or "BHapticsHTTP")
+    BHAPTICS_API_KEY      Override apiKey (default: from tact-config.json or "")
+    BHAPTICS_HTTP_PORT    Port to listen on (default: 15883)
+
+REST endpoints:
+    GET  /health          Connection status
+    POST /haptic          Play a named Studio event
+    POST /haptic/dot      Play raw motor array (no Studio required)
+    POST /haptic/stop     Stop all haptics
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+from aiohttp import web
+
+# ── bhaptics-python import ────────────────────────────────────────────────────
+try:
+    import bhaptics_python as bh
+except ImportError:
+    print(
+        "[ERROR] bhaptics-python not installed.\n"
+        "        Run:  pip install bhaptics-python\n"
+        "        Docs: https://github.com/bhaptics/bhaptics-python"
+    )
+    sys.exit(1)
+
+log = logging.getLogger("bhaptics_http")
+
+# ── Module-level credential cache ────────────────────────────────────────────
+_app_id: Optional[str] = None
+_api_key: Optional[str] = None
+
+RECONNECT_INTERVAL = 5  # seconds between liveness checks
+
+# ── Config helpers ────────────────────────────────────────────────────────────
+
+def load_config(config_path: Optional[Path] = None) -> tuple[str, str]:
+    """
+    Resolve appId / apiKey from (in priority order):
+      1. Environment variables BHAPTICS_APP_ID / BHAPTICS_API_KEY
+      2. tact-config.json at *config_path* (if provided or auto-detected)
+      3. Built-in defaults ("BHapticsHTTP", "")
+    """
+    app_id  = os.environ.get("BHAPTICS_APP_ID")
+    api_key = os.environ.get("BHAPTICS_API_KEY")
+
+    if not app_id or not api_key:
+        if config_path is None:
+            # Look next to this file, then cwd
+            candidates = [
+                Path(__file__).parent / "tact-config.json",
+                Path.cwd() / "tact-config.json",
+            ]
+            config_path = next((p for p in candidates if p.exists()), None)
+
+        if config_path and config_path.exists():
+            try:
+                cfg = json.loads(config_path.read_text())
+                app_id  = app_id  or cfg.get("appId",  "BHapticsHTTP")
+                api_key = api_key or cfg.get("apiKey", "")
+                log.info(f"Loaded config from {config_path}")
+            except Exception as exc:
+                log.warning(f"Could not parse {config_path}: {exc} — using defaults")
+
+    return (app_id or "BHapticsHTTP"), (api_key or "")
+
+
+# ── SDK connection helpers ────────────────────────────────────────────────────
+
+def _is_connected() -> bool:
+    try:
+        return bool(bh.is_connected())
+    except Exception:
+        return False
+
+
+def _try_reconnect() -> bool:
+    """Attempt reconnect; returns True on success."""
+    global _app_id, _api_key
+    try:
+        bh.retry_initialize()
+        if _is_connected():
+            log.info("[OK] Reconnected via retry_initialize()")
+            return True
+        bh.registry_and_initialize(_app_id, _api_key, "BHapticsHTTP")
+        ok = _is_connected()
+        if ok:
+            log.info("[OK] Reconnected via re-auth")
+        return ok
+    except Exception as exc:
+        log.warning(f"[WARN] Reconnect failed: {exc}")
+        return False
+
+
+def init_bhaptics(app_id: str, api_key: str) -> bool:
+    """Initialise the SDK; returns True if connected."""
+    global _app_id, _api_key
+    _app_id, _api_key = app_id, api_key
+    try:
+        bh.registry_and_initialize(app_id, api_key, "BHapticsHTTP")
+        if _is_connected():
+            log.info(f"[OK] bhaptics-python connected (appId={app_id})")
+            return True
+        log.warning("[WARN] Initialised but not yet connected — is bHaptics Player running?")
+        return False
+    except Exception as exc:
+        log.error(f"[ERROR] Init failed: {exc}")
+        return False
+
+
+async def reconnect_loop() -> None:
+    """Background task: reconnect whenever the SDK loses the Player connection."""
+    was_connected = False
+    while True:
+        await asyncio.sleep(RECONNECT_INTERVAL)
+        try:
+            connected = _is_connected()
+            if not connected:
+                msg = "Lost connection" if was_connected else "Not connected"
+                log.info(f"[...] {msg} — attempting reconnect")
+                _try_reconnect()
+                was_connected = _is_connected()
+            else:
+                was_connected = True
+        except Exception as exc:
+            log.error(f"[ERROR] reconnect_loop: {exc}")
+
+
+# ── Route handlers ────────────────────────────────────────────────────────────
+
+async def handle_health(request: web.Request) -> web.Response:
+    """
+    GET /health
+
+    Response:
+        {"ok": bool, "backend": "bhaptics-python", "player": bool|null}
+    """
+    connected = _is_connected()
+    player = None
+    if hasattr(bh, "is_bhaptics_player_running"):
+        try:
+            result = bh.is_bhaptics_player_running()
+            player = bool(await result) if asyncio.isfuture(result) else bool(result)
+        except Exception:
+            player = None
+    return web.json_response({"ok": connected, "backend": "bhaptics-python", "player": player})
+
+
+async def handle_haptic(request: web.Request) -> web.Response:
+    """
+    POST /haptic
+
+    Play a named tact event previously registered in bHaptics Studio.
+
+    Body:
+        {"event": "PatternName", "deviceIndex": 0}
+
+    Response:
+        {"ok": true, "event": "PatternName"}
+    """
+    try:
+        body = await request.json()
+    except Exception:
+        return web.json_response({"error": "Invalid JSON"}, status=400)
+
+    event = body.get("event")
+    if not event or not isinstance(event, str):
+        return web.json_response({"error": "Missing or invalid 'event' key"}, status=400)
+
+    if not _is_connected():
+        log.warning(f"[WARN] Not connected — reconnecting before play_event '{event}'")
+        if not _try_reconnect():
+            return web.json_response({"error": "Not connected to bHaptics Player"}, status=503)
+
+    try:
+        device_index = int(body.get("deviceIndex", 0))
+        bh.play_event(event, device_index)
+        log.info(f"[>] play_event: {event}")
+        return web.json_response({"ok": True, "event": event})
+    except Exception as exc:
+        log.error(f"[ERROR] play_event '{event}': {exc}")
+        return web.json_response({"error": str(exc)}, status=500)
+
+
+async def handle_haptic_dot(request: web.Request) -> web.Response:
+    """
+    POST /haptic/dot
+
+    Play raw motor intensities without a Studio-registered pattern.
+    This is the key endpoint that bHaptics Player's own REST API does not expose.
+
+    Body:
+        {
+            "deviceType": 0,        // 0=vest, 1=left arm, 2=right arm, ...
+            "duration":   100,      // milliseconds
+            "motors": [             // one entry per motor slot
+                {"index": 0, "intensity": 100},
+                {"index": 4, "intensity": 50}
+            ]
+        }
+
+    Device type reference (bHaptics TactSuit family):
+        0  = TactSuit X16/X40 (chest vest)
+        1  = Tactosy2 left arm
+        2  = Tactosy2 right arm
+        3  = TactVisor head
+        6  = Tactosy feet left
+        7  = Tactosy feet right
+        8  = TactGlove left
+        9  = TactGlove right
+
+    Response:
+        {"ok": true}
+    """
+    try:
+        body = await request.json()
+    except Exception:
+        return web.json_response({"error": "Invalid JSON"}, status=400)
+
+    if not _is_connected():
+        log.warning("[WARN] Not connected — reconnecting before play_dot")
+        if not _try_reconnect():
+            return web.json_response({"error": "Not connected to bHaptics Player"}, status=503)
+
+    try:
+        device_type = int(body.get("deviceType", 0))
+        duration    = int(body.get("duration",   100))
+        motors      = body.get("motors", [])
+        bh.play_dot(device_type, duration, motors)
+        log.info(f"[>] play_dot device={device_type} duration={duration}ms motors={len(motors)}")
+        return web.json_response({"ok": True})
+    except Exception as exc:
+        log.error(f"[ERROR] play_dot: {exc}")
+        return web.json_response({"error": str(exc)}, status=500)
+
+
+async def handle_haptic_stop(request: web.Request) -> web.Response:
+    """
+    POST /haptic/stop
+
+    Stop all currently playing haptic patterns.
+
+    Response:
+        {"ok": true}
+    """
+    try:
+        bh.stop_all()
+        log.info("[>] stop_all")
+        return web.json_response({"ok": True})
+    except Exception as exc:
+        log.error(f"[ERROR] stop_all: {exc}")
+        return web.json_response({"error": str(exc)}, status=500)
+
+
+# ── App factory ───────────────────────────────────────────────────────────────
+
+def make_app(
+    app_id: str,
+    api_key: str,
+    *,
+    config_path: Optional[Path] = None,
+) -> web.Application:
+    """
+    Create and return the aiohttp Application.
+
+    Startup connects to bHaptics Player and launches the background
+    reconnect loop.  Pass the returned app to ``aiohttp.web.run_app()``.
+    """
+    async def on_startup(app: web.Application) -> None:
+        init_bhaptics(app_id, api_key)
+        asyncio.ensure_future(reconnect_loop())
+
+    app = web.Application()
+    app.on_startup.append(on_startup)
+    app.router.add_get( "/health",       handle_health)
+    app.router.add_post("/haptic",       handle_haptic)
+    app.router.add_post("/haptic/dot",   handle_haptic_dot)
+    app.router.add_post("/haptic/stop",  handle_haptic_stop)
+    return app