Haply Inverse SDK

The Haply Inverse SDK is a language-agnostic WebSocket + HTTP interface to Haply haptic devices — the Inverse3, Inverse3x, Minverse, VerseGrip, and Wireless VerseGrip. It runs as a local service that handles device discovery, serial communication, safety monitoring, and state streaming — so your application only has to speak JSON over a socket.

Its functionalities include:

• Device discovery and management — lists and configures connected Haply devices automatically over an HTTP REST API.
• Real-time state streaming — delivers device state at haptic control rates (multi-kHz) over WebSockets.
• Command processing — executes force and position commands with high fidelity for precise haptic feedback.
• Background operation — runs as a local service, keeping devices ready without user intervention.

Install with the Haply Hub

The easiest way to get started is the Haply Hub — a desktop application to install, run, configure, test, and monitor your Haply devices. It keeps firmware up to date, bundles the Inverse Service, and ships demos so you can verify your hardware before writing a line of code.

Haply Hub

Download the latest version of the Haply Hub

Download and install the Hub, plug in your device, and the Hub will guide you through any firmware updates. Once installed, the Inverse Service runs automatically in the background whenever the Hub is open.

Prefer a standalone install?

You can also install a specific version of the Inverse Service as a system service (Windows) or daemon (Linux / macOS) without the Hub. See Running the service for the installer link and instructions.

Quick Example

Connect to the service, read the cursor position of the first Inverse3, and send a zero-force keepalive so the service keeps streaming state frames:

Python

import asyncio, json, websockets

async def main():
    async with websockets.connect("ws://localhost:10001") as ws:
        # Handshake: register profile and send a zero-force keepalive
        first_state = json.loads(await ws.recv())
        device_id = first_state["inverse3"][0]["device_id"]
        keepalive = {"inverse3": [{
            "device_id": device_id,
            "commands": {"set_cursor_force": {"vector": {"x": 0, "y": 0, "z": 0}}}
        }]}
        while True:
            state = json.loads(await ws.recv())
            pos = state["inverse3"][0]["state"]["cursor_position"]
            print(f"pos: {pos}")
            await ws.send(json.dumps(keepalive))

asyncio.run(main())

JavaScript (Node)

import WebSocket from 'ws'

const ws = new WebSocket('ws://localhost:10001')
let keepalive

ws.on('message', (msg) => {
  const state = JSON.parse(msg)
  if (!keepalive) {
    const deviceId = state.inverse3[0].device_id
    keepalive = JSON.stringify({
      inverse3: [
        {
          device_id: deviceId,
          commands: { set_cursor_force: { vector: { x: 0, y: 0, z: 0 } } },
        },
      ],
    })
  }
  console.log('pos:', state.inverse3[0].state.cursor_position)
  ws.send(keepalive)
})

C++ (nlohmann)

#include <external/libhv.h>
#include <nlohmann/json.hpp>

int main() {
    hv::WebSocketClient ws;
    nlohmann::json keepalive;

    ws.onmessage = [&](const std::string& msg) {
        auto state = nlohmann::json::parse(msg);
        if (keepalive.is_null()) {
            keepalive = {{"inverse3", nlohmann::json::array({{
                {"device_id", state["inverse3"][0]["device_id"]},
                {"commands", {{"set_cursor_force",
                    {{"vector", {{"x", 0}, {"y", 0}, {"z", 0}}}}}}}
            }})}};
        }
        auto pos = state["inverse3"][0]["state"]["cursor_position"];
        std::cout << "pos: " << pos << "\n";
        ws.send(keepalive.dump());
    };
    ws.open("ws://localhost:10001");
    std::cin.get();
}

C++ (Glaze)

Using Glaze for compile-time JSON reflection. Declare the minimum shape you read and write; the rest is ignored.

#include <external/libhv.h>
#include <glaze/glaze.hpp>

struct vec3 { float x{}, y{}, z{}; };
struct inverse_state { vec3 cursor_position; };
struct inverse_device { std::string device_id; inverse_state state; };
struct devices_message { std::vector<inverse_device> inverse3; };

struct set_cursor_force_cmd { vec3 vector; };
struct device_cmd { std::string device_id;
    struct { std::optional<set_cursor_force_cmd> set_cursor_force; } commands; };
struct commands_message { std::vector<device_cmd> inverse3; };

int main() {
    hv::WebSocketClient ws;
    commands_message keepalive;
    ws.onmessage = [&](const std::string& msg) {
        devices_message state{};
        if (glz::read_json(state, msg)) return;
        if (keepalive.inverse3.empty()) {
            keepalive.inverse3.push_back({state.inverse3[0].device_id});
            keepalive.inverse3[0].commands.set_cursor_force = set_cursor_force_cmd{};
        }
        printf("pos: %f %f %f\n", state.inverse3[0].state.cursor_position.x,
               state.inverse3[0].state.cursor_position.y,
               state.inverse3[0].state.cursor_position.z);
        std::string out; (void)glz::write_json(keepalive, out);
        ws.send(out);
    };
    ws.open("ws://localhost:10001");
    std::cin.get();
}

Rust

Illustrative example using tokio-tungstenite + serde_json.

use futures_util::{SinkExt, StreamExt};
use serde_json::json;
use tokio_tungstenite::{connect_async, tungstenite::Message};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let (mut ws, _) = connect_async("ws://localhost:10001").await?;
    let mut keepalive: Option<String> = None;

    while let Some(Ok(Message::Text(msg))) = ws.next().await {
        let state: serde_json::Value = serde_json::from_str(&msg)?;
        let device_id = state["inverse3"][0]["device_id"].as_str().unwrap();

        if keepalive.is_none() {
            keepalive = Some(json!({
                "inverse3": [{
                    "device_id": device_id,
                    "commands": { "set_cursor_force": { "vector": { "x": 0, "y": 0, "z": 0 } } }
                }]
            }).to_string());
        }
        println!("pos: {}", state["inverse3"][0]["state"]["cursor_position"]);
        ws.send(Message::Text(keepalive.clone().unwrap())).await?;
    }
    Ok(())
}

warning

Change the force values with caution. Sudden high force values can damage the device or cause unexpected behaviour.

info

See the JSON Conventions page for the message envelope, ports, and content-type rules.

More examples

For fully-featured tutorials in Python, C++ (nlohmann), and C++ (Glaze) — covering force feedback, position control, multi-device setups, mount/basis configuration, and event streaming — see the Tutorials page.