Skip to main content
Version: 3.5.x

Haply Inverse Service

Upgrading to 3.5?

Service 3.5 ships an opt-in alternate JSON shape for Wireless Verse Grip entries (including Ruko and Kingfisher). The default is unchanged from 3.4, so existing clients keep working with no action. If your client parses the wireless_verse_grip or custom_verse_grip arrays and you'd like a cleaner config.type / config.sub_type split, see the 3.5 migration guide.

The Inverse Service runs as a background process on your machine, connecting Haply haptic devices to your application in real time. It handles everything below your code: device detection, serial communication, safety monitoring, and state streaming — so you can focus on building the experience.

Requirements & Compatibility​

The service runs on the major desktop platforms and can be driven from any language with a WebSocket client and a JSON parser:

  • Platforms: Windows 10+ (MSVC), Linux (.deb package), macOS
  • Languages: Python, JavaScript / TypeScript, C++, C#, Rust, Go, Java, … anything that speaks WebSocket + JSON

Officially supported integrations​

Haply maintains first-party integrations for the Haply Inverse Unity Package, Toia, Geomagic Freeform, and NVIDIA Isaac Lab.

Beyond those, the service is usable from any platform or runtime that ships a WebSocket client and a JSON parser — we've run it alongside Unreal Engine, TouchDesigner, and other real-time or simulation stacks. If your environment can open a WebSocket, it can drive an Inverse device.

For language-specific examples, see the public sample repositories: C++ and Python.

Communication Interfaces​

The service exposes two communication channels:

ChannelPortTransportPurpose
Simulation10001WebSocketReal-time command / state loop (1 message in → 1 state out)
Events10020WebSocket (read-only)System events: safety, battery, connection, rate warnings
HTTP10001RESTStateless config queries, settings, session management, device inspection

All payloads are JSON. See JSON Conventions for the standard envelope, ports, and content-type rules.

Use Cases​

GoalWhere to start
Send forces or position targets to a haptic deviceRealtime Control
Configure basis, mount, preset, or filtersSession Configuration
Navigate a scene (rate-control locomotion)Navigation Module
Listen to system events (safety, battery, connection)Events & Monitoring
Learn by exampleTutorials

Coordinate System​

Haply's internal frame is right-handed, Z-up (+X right, +Y forward, +Z up). You can remap it to your application's frame with a single basis permutation — once set, all inputs and outputs are automatically converted.

Two transforms position the device in your scene:

  • Mount — the physical offset of the device (set via a preset or explicitly)
  • Workspace — a runtime drift for camera/scene navigation (set manually or via the Navigation module)

See Mount & Workspace for the full coordinate pipeline.

Running the Service​

The Inverse Service can run in two modes:

  • Embedded in the Haply Hub (recommended) — the Haply Hub bundles the latest service version and starts it automatically whenever the Hub is open. No manual setup; you always get the latest fixes.
  • Standalone — install a specific service version as a Windows service or Unix daemon using the Inverse Installer. Useful for CI, headless deployments, or machines where the Hub isn't running.

Managing the standalone service​

Windows — open the Services app: press Win+R, type services.msc, find "Haply Inverse Service", right-click → Start / Stop / Restart.

Linux (systemd):

systemctl start haply-inverse-service.service
systemctl stop haply-inverse-service.service
systemctl restart haply-inverse-service.service
systemctl enable haply-inverse-service.service   # auto-start on boot

Full API Reference​

For the complete machine-readable specification of every endpoint and message: