Simulation Channel
General
The default simulation channel websocket URL is ws://localhost:10001. Note: the port can be changed in the configuration.
This is high-frequency bidirectional communication channel where you can expect to receive devices states. We expect to receive session related or device related commands. The system will send a state response message 1:1 for each message received (see state update).
This page document the general commands. We have different modules & features that registers & extends the system with their own commands. There are documented separately in the modules section;
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 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 & configurations.
{
"session": {
"force_render_full_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"
}
}
}
Set Basis
Instruct the mapping from our coordinate system to yours. This mapping is maintained for the entire session.
As mentioned earlier, Haply uses a right-handed coordinate system with Z-Up. This command allows for setting the current session with an alternate coordinate system, which will result all states returned from the system to be represented in that system. It also changes the assumptions coordinate system for all values given as part of other commands. Set cursor position for example.
The coordinate system is instructed relative to ours, and can contain signs characters (+ or -) before the valid X, Y, or Z
letters. This is examples of valid values for example : XYZ, ZYX, +Y-Z+X, X-ZY, etc.
This means that a system defined as "YZX" specifically means "Y is right, Z is forward & X is up".
This is an example for a left-handed Z-up system like Unreal (X-YZ)
{
"session": {
"set_basis": {
"permutation": "X-YZ"
}
}
}
Device Commands
All Devices
Probing commands
probe_position for the inverse3, and probe_orientation for verse grips all contains no command data.
These forces devices information queries to ensure the reported positional information is up to date on the next message.
This is useful if you want to observe changes without sending a command that will apply a force of perform any other actions that might
affect the simulation.
{
"inverse3": [
{
"device_id": "049D",
"commands": {
"probe_position": {}
}
}
],
"verse_grip": [
{
"device_id": "049D",
"commands": {
"probe_orientation": {}
}
}
],
"wireless_verse_grip": [
{
"device_id": "049D",
"commands": {
"probe_orientation": {}
}
}
]
}
Inverse
In order to send commands to a inverse3 device, the client has to send a command message for a given device id. Here is an example:
{
"inverse3": [
{
"device_id": "049D",
"commands": {
"set_cursor_force": {
"values": {
"x": 1.0,
"y": 2.0,
"z": 3.0
}
}
}
}
]
}
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
}
}
}
}
]
}
Set Cursor Position
{
"inverse3": [
{
"device_id": "049D",
"commands": {
"set_cursor_position": {
"values": {
"x": 1.0,
"y": 2.0,
"z": 3.0
}
}
}
}
]
}
Set Cursor Force
{
"inverse3": [
{
"device_id": "049D",
"commands": {
"set_cursor_force": {
"values": {
"x": 1.0,
"y": 2.0,
"z": 3.0
}
}
}
}
]
}
Set Angular Position
{
"inverse3": [
{
"device_id": "049D",
"commands": {
"set_cursor_force": {
"values": {
"x": 1.0,
"y": 2.0,
"z": 3.0
}
}
}
}
]
}
Set Angular Torque
{
"inverse3": [
{
"device_id": "049D",
"commands": {
"set_angular_torque": {
"values": {
"a0": 1.0,
"a1": 2.0,
"a2": 3.0
}
}
}
}
]
}
Extended Verse Grip
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.
{
"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
]
}
}
}
]
}