Version: 3.3.x

Haply Inverse Service

The Haply Inverse Service is a foundational component that integrates Haply's tactile devices with interactive applications, running as a background Windows service to enable real-time interactions. Its functionalities include:

Device Discovery and Management: Identifies and configures connected Haply devices automatically.
Ownership Management: Manages access to devices across multiple applications, ensuring smooth operation.
Real-Time State Streaming: Provides updates on device states at high frequencies for precise control.
Command Processing: Executes commands for force or position with high fidelity, enhancing the haptic feedback.
Background Operation: Runs in the background, maintaining device readiness without user intervention.

Run, stop, restart

tip

Use the Haply Device Manager to easily manage the service and see the connected devices.

On Windows:

Open the Services desktop app: Press Windows+R to open the Run box, enter services.msc, and then press Enter or select OK.

On Ubuntu:

Start
- systemctl start haply-inverse-service.service
Stop
- systemctl stop haply-inverse-service.service
Enable
- systemctl enable haply-inverse-service.service
Disable
- systemctl disable haply-inverse-service.service

JSON Format Versions

The service currently supports two different JSON formats: 3.0 and 3.x. Both versions are available concurrently, ensuring backward compatibility. If you are using the 3.0 format in your simulations, no changes are required—it will continue to work as before. However, you are encouraged to update to the 3.x version to take advantage of its enhancements and improved performance for game engine integration.

Key Details

3.0 Version API
- Fully documented in the 3.0.x documentation pages.
- HTTP accessible by default on ****http://localhost:10000/3.0/..
- Websockets accessible by default on port 10000.
3.x Version API
- Fully documented in the 3.x documentation pages.
- HTTP accessible by default on http://localhost:10000/.
- Websockets accessible by default on port 10001.
- Offers improvements in functionality and faster integration with game engines.

Feel free to upgrade to the latest format at your convenience to leverage its benefits without any disruption to your existing workflows.

Interfaces

Both the HTTP and Websocket interfaces use JSON formatted payloads.

info

When reading the position of the end-effector, you must send a force value to the device (even if the force values are all zeros).

HTTP

By default, the HTTP service starts on: http://localhost:10000. Note: the port can be changed in the configuration.

Version

Method: GET

URL: http://localhost:10000/version

Response example:

{
  "build_time": "2024-08-07T16:01:53Z",
  "git_branch": "main",
  "git_describe": "3.0.0-2-gce34c39e",
  "git_hash": "ce34c39e",
  "git_tag": "3.0.0",
  "project_name": "haply-inverse-service",
  "project_version": "3.0.0.0"
}

Devices

Method: GET

URL: http://localhost:10000/devices

Response example:

{
  "inverse3": [
    {
      "device_id": "04BA",
      "config": {
        "type": "inverse3",
        "device_info": {
          "minor_version": 1,
          "major_version": 7,
          "id": "04BA",
          "device_type": 4,
          "uuid": "2D35F80DD9005F599B68F49944CB04BA"
        },
        "port": "COM13",
        "extended_device_id": "2D35F80DD9005F599B68F49944CB04BA",
        "extended_firmware_version": "8C20FDC8010AA1E15AA133CDA2534874",
        "gravity_compensation": {
          "enabled": true,
          "scaling_factor": 1
        },
        "handedness": "right",
        "torque_scaling": {
          "enabled": true
        }
      },
      "state": {
        "angular_position": {
          "a0": -69.31704,
          "a1": 137.62952,
          "a2": 19.832787
        },
        "angular_velocity": {
          "a0": 0,
          "a1": 0,
          "a2": 0
        },
        "body_orientation": {
          "x": -0.01940918,
          "y": 0.7026367,
          "z": 0.00048828125,
          "w": 0.7113037
        },
        "cursor_position": {
          "x": 0.07842738,
          "y": -0.14836666,
          "z": 0.14297646
        },
        "cursor_velocity": {
          "x": -0.011969013,
          "y": 0.0012009288,
          "z": -0.043197
        },
        "mode": "idle"
      },
      "status": {
        "calibrated": false,
        "in_use": false,
        "power_supply": true,
        "ready": true,
        "started": true
      }
    }
  ],
  "verse_grip": [
    {
      "device_id": "61548",
      "config": {
        "port": "COM3",
        "type": "verse_grip"
      },
      "state": {
        "button": false,
        "hall": 0,
        "orientation": {
          "x": -0.5019531,
          "y": 0.8632202,
          "z": -0.048095703,
          "w": -0.022338867
        }
      },
      "status": {
        "error": 0,
        "ready": true
      }
    }
  ],
  "wireless_verse_grip": [
    {
      "device_id": "0",
      "config": {
        "port": "COM6",
        "type": "wireless_verse_grip",
        "major_version": 1,
        "minor_version": 4,
        "hardware_version": 1
      },
      "state": {
        "battery_level": 0.816,
        "battery_voltage": 3.77,
        "buttons": {
          "a": false,
          "b": false,
          "c": false
        },
        "hall": 16,
        "orientation": {
          "x": -0.019866943,
          "y": -0.017486572,
          "z": 0.05508423,
          "w": -0.9963989
        }
      },
      "status": {
        "connected": true,
        "awake": true,
        "ready": true
      }
    }
  ]
}

Force Scale

Method: POST

URL: http://localhost:10000/force_scale

Body example:

{
  "force_scale": 0.5
}

Response example:

{
  "ok": true
}

Gravity Compensation

Method: POST

URL: http://localhost:10000/gravity_compensation

Body example:

{
  "device_id": "049D",
  "enable": true,
  "gravity_scaling_factor": 0.8
}

Response example:

{
  "ok": true
}

Torque scaling

Method: POST

URL: http://localhost:10000/torque_scaling

Body example:

{
  "device_id": "049D",
  "enable": true
}

Response example:

{
  "ok": true
}

Device Handedness

Method: POST

URL: http://localhost:10000/device_handedness

Body example:

{
  "device_id": "049D",
  "handedness": "right"
}

Response example:

{
  "ok": true
}

Save Configuration

Only works with Inverse3 devices. Warning: Avoid saving the configuration too often, since there is a limited number of save that can be applied to any given device.

Method: POST

URL: http://localhost:10000/save_configuration

Body example:

{
  "device_id": "049D"
}

Response example:

{
  "ok": true
}

Serial Enable

Enable or disable all the serial communication. When the serial communication is disabled it is impossible to send commands to the devices.

Method: POST

URL: http://localhost:10000/serial_enable

Body example:

{
  "enable": true
}

Response example:

{
  "ok": true
}

Grip Vertical Stopper

Enable or disable the grip vertical stopper experimental feature. This feature will check the wireless VerseGrip orientation to detect when the VerseGrip is dropped. When it triggers, it sets the Inverse3 into position control in its current position so that the end effector doesn't drop. It is disabled automatically when the VerseGrip is picked up again.

warning

As an experimental feature it is disabled by default and needs to be explicitly enabled to activate.

Method: POST

URL: http://localhost:10000/experimental/features/grip_dropped_simulation_stopper

Body example:

{
  "enable": true,
  "hall_effect_threshold": 17
}

Response example:

{
  "ok": true
}

Websocket

The default websocket URL is ws://localhost:10001. Note: the port can be changed in the configuration.

Initial Message

The service sends a message containing the complete device list when a websocket is connected. The initial message has the following JSON format:

{
  "inverse3": [
    {
      "device_id": "04BA",
      "config": {
        "type": "inverse3",
        "device_info": {
          "minor_version": 1,
          "major_version": 7,
          "id": "04BA",
          "model": 4,
          "uuid": "2D35F80DD9005F599B68F49944CB04BA"
        },
        "port": "COM13",
        "extended_device_id": "2D35F80DD9005F599B68F49944CB04BA",
        "extended_firmware_version": "8C20FDC8010AA1E15AA133CDA2534874",
        "gravity_compensation": {
          "enabled": true,
          "scaling_factor": 1
        },
        "handedness": "right",
        "torque_scaling": {
          "enabled": true
        }
      },
      "state": {
        "angular_position": {
          "a0": -69.31704,
          "a1": 137.62952,
          "a2": 19.832787
        },
        "angular_velocity": {
          "a0": 0,
          "a1": 0,
          "a2": 0
        },
        "body_orientation": {
          "x": -0.01940918,
          "y": 0.7026367,
          "z": 0.00048828125,
          "w": 0.7113037
        },
        "cursor_position": {
          "x": 0.07842738,
          "y": -0.14836666,
          "z": 0.14297646
        },
        "cursor_velocity": {
          "x": -0.011969013,
          "y": 0.0012009288,
          "z": -0.043197
        },
        "mode": "idle"
      },
      "status": {
        "calibrated": false,
        "in_use": false,
        "power_supply": true,
        "ready": true,
        "started": true
      }
    }
  ],
  "verse_grip": [
    {
      "device_id": "61548",
      "config": {
        "port": "COM3",
        "type": "verse_grip"
      },
      "state": {
        "button": false,
        "hall": 0,
        "orientation": {
          "x": -0.5019531,
          "y": 0.8632202,
          "z": -0.048095703,
          "w": -0.022338867
        }
      },
      "status": {
        "error": 0,
        "ready": true
      }
    }
  ],
  "wireless_verse_grip": [
    {
      "device_id": "0",
      "config": {
        "port": "COM6",
        "type": "wireless_verse_grip",
        "major_version": 1,
        "minor_version": 4,
        "hardware_version": 1
      },
      "state": {
        "battery_level": 0.816,
        "battery_voltage": 3.77,
        "buttons": {
          "a": false,
          "b": false,
          "c": false
        },
        "hall": 16,
        "orientation": {
          "x": -0.019866943,
          "y": -0.017486572,
          "z": 0.05508423,
          "w": -0.9963989
        }
      },
      "status": {
        "connected": true,
        "awake": true,
        "ready": true
      }
    }
  ]
}

State Update Message

The service will send one state update message containing the state of all devices for each command message received.

If you wish to know the state of the machine, you must send it a message beforehand, such as a force value (even if the values are zeros). This is particularly important if using our devices as an input device, such as tracking position and not applying force. The state update message has the following JSON format:

{
  "inverse3": [
    {
      "device_id": "04BA",
      "state": {
        "angular_position": {
          "a0": -69.31704,
          "a1": 137.62952,
          "a2": 19.832787
        },
        "angular_velocity": {
          "a0": 0,
          "a1": 0,
          "a2": 0
        },
        "body_orientation": {
          "x": -0.01940918,
          "y": 0.7026367,
          "z": 0.00048828125,
          "w": 0.7113037
        },
        "cursor_position": {
          "x": 0.07842738,
          "y": -0.14836666,
          "z": 0.14297646
        },
        "cursor_velocity": {
          "x": -0.011969013,
          "y": 0.0012009288,
          "z": -0.043197
        },
        "mode": "idle"
      },
      "status": {
        "calibrated": false,
        "in_use": false,
        "power_supply": true,
        "ready": true,
        "started": true
      }
    }
  ],
  "verse_grip": [
    {
      "device_id": "61548",
      "state": {
        "button": false,
        "hall": 0,
        "orientation": {
          "x": -0.5019531,
          "y": 0.8632202,
          "z": -0.048095703,
          "w": -0.022338867
        }
      },
      "status": {
        "error": 0,
        "ready": true
      }
    }
  ],
  "wireless_verse_grip": [
    {
      "device_id": "0",
      "state": {
        "battery_level": 0.816,
        "battery_voltage": 3.77,
        "buttons": {
          "a": false,
          "b": false,
          "c": false
        },
        "hall": 16,
        "orientation": {
          "x": -0.019866943,
          "y": -0.017486572,
          "z": 0.05508423,
          "w": -0.9963989
        }
      },
      "status": {
        "ready": true
      }
    }
  ],
  "custom_verse_grip": [
    {
      "device_id": "0",
      "state": {
        "battery_level": 0.816,
        "battery_voltage": 3.77,
        "buttons": {
          "a": false,
          "b": false,
          "c": false
        },
        "hall": 16,
        "orientation": {
          "x": -0.019866943,
          "y": -0.017486572,
          "z": 0.05508423,
          "w": -0.9963989
        },
        "extension_data": [
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0
        ]
      },
      "status": {
        "ready": true
      }
    }
  ]
}

Session Commands

Session commands are actions which relates to your current simulation/connection/session. They constitute actions that are not device specific.

Force Render State

Request a state snapshot of all devices.

{
  "session": {
    "force_render_state": {}
  }
}

Set Coordinate Origin

Set the coordinate origin for all devices. The coordinate origin can be set to either device_base or workspace_center. The default is device_base.

If you set the coordinate origin to workspace_center, the (0, 0, 0) position will be moved to the center of the device workspace.

{
  "session": {
    "set_coordinate_origin": {
      "coordinate_origin": "workspace_center"
    }
  }
}

Device Commands

In order to send commands to the inverse3 the client has to send a command message. Here is an example:

{
  "inverse3": [
    {
      "device_id": "049D",
      "commands": {
        "set_cursor_force": {
          "values": {
            "x": 1.0,
            "y": 2.0,
            "z": 3.0
          }
        }
      }
    }
  ],
  "verse_grip": [],
  "wireless_verse_grip": []
}

Also, it is possible to send commands to multiple devices in a single message. here is an example:

{
  "inverse3": [
    {
      "device_id": "049D",
      "commands": {
        "set_cursor_force": {
          "values": {
            "x": 1.0,
            "y": 2.0,
            "z": 3.0
          }
        }
      }
    },
    {
      "device_id": "049E",
      "commands": {
        "set_cursor_force": {
          "values": {
            "x": 1.0,
            "y": 2.0,
            "z": 3.0
          }
        }
      }
    }
  ],
  "verse_grip": [],
  "wireless_verse_grip": []
}

The following commands are currently available on the inverse3:

Set Cursor Position

{
  "inverse3": [
    {
      "device_id": "049D",
      "commands": {
        "set_cursor_position": {
          "values": {
            "x": 1.0,
            "y": 2.0,
            "z": 3.0
          }
        }
      }
    }
  ],
  "verse_grip": [],
  "wireless_verse_grip": []
}

Set Cursor Force

{
  "inverse3": [
    {
      "device_id": "049D",
      "commands": {
        "set_cursor_force": {
          "values": {
            "x": 1.0,
            "y": 2.0,
            "z": 3.0
          }
        }
      }
    }
  ],
  "verse_grip": [],
  "wireless_verse_grip": []
}

Set Angular Position

{
  "inverse3": [
    {
      "device_id": "049D",
      "commands": {
        "set_cursor_force": {
          "values": {
            "x": 1.0,
            "y": 2.0,
            "z": 3.0
          }
        }
      }
    }
  ],
  "verse_grip": [],
  "wireless_verse_grip": []
}

Set Angular Torque

{
  "inverse3": [
    {
      "device_id": "049D",
      "commands": {
        "set_angular_torque": {
          "values": {
            "a0": 1.0,
            "a1": 2.0,
            "a2": 3.0
          }
        }
      }
    }
  ],
  "verse_grip": [],
  "wireless_verse_grip": []
}

Probing commands

probe_cursor_position, probe_angular_position for the inverse3, and probe_orientation for verse grips all contains no command data.

Note: The inverse currently has 2 mode of operations (cartesian & angular). We recommend using probe_cursor_position. Querying both probe_cursor_position & probe_angular_position rapidly with cause the device to switch mode at high-frequency and create instabilities.

{
  "inverse3": [
    {
      "device_id": "049D",
      "commands": {
        "probe_cursor_position": {}
      }
    }
  ],
  "verse_grip": [
    {
      "device_id": "049D",
      "commands": {
        "probe_orientation": {}
      }
    }
  ],
  "wireless_verse_grip": [
    {
      "device_id": "049D",
      "commands": {
        "probe_orientation": {}
      }
    }
  ]
}

Set Grip Extension Data

The set_extension_data command is part of the extended protocol for Verse grips, used with grip versions that implement the board extension communication protocol.

Supported Data Lengths:

Up to 20 bytes upstream.
Outputs up to 12 bytes downstream (refer to State Update Message).

Data Specifications:

Array Length: 20 bytes.
Value Range: Each value ranges from 0 to 255.

{
  "inverse3": [],
  "verse_grip": [],
  "wireless_verse_grip": [
    {
      "device_id": "049D",
      "commands": {
        "set_extension_data": {
          "extension_data": [
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0,
            0
          ]
        }
      }
    }
  ]
}

Run, stop, restart​

JSON Format Versions​

Key Details​

Interfaces​

HTTP​

Version​

Devices​

Force Scale​

Gravity Compensation​

Torque scaling​

Device Handedness​

Save Configuration​

Serial Enable​

Grip Vertical Stopper​

Websocket​

Initial Message​

State Update Message​

Session Commands​

Force Render State​

Set Coordinate Origin​

Device Commands​

Set Cursor Position​

Set Cursor Force​

Set Angular Position​

Set Angular Torque​

Probing commands​

Set Grip Extension Data​

Run, stop, restart

JSON Format Versions

Key Details

Interfaces

HTTP

Version

Devices

Force Scale

Gravity Compensation

Torque scaling

Device Handedness

Save Configuration

Serial Enable

Grip Vertical Stopper

Websocket

Initial Message

State Update Message

Session Commands

Force Render State

Set Coordinate Origin

Device Commands

Set Cursor Position

Set Cursor Force

Set Angular Position

Set Angular Torque

Probing commands

Set Grip Extension Data