版本： 3.1.1

Haply 逆向服务

Haply 反向服务是一个基础组件，它将Haply 的触觉设备与交互式应用程序集成在一起，作为后台 Windows 服务运行，以实现实时交互。其功能包括

设备发现和管理：自动识别和配置连接的Haply 设备。
所有权管理：管理多个应用程序的设备访问权限，确保运行顺畅。
实时状态流：高频率更新设备状态，实现精确控制。
指令处理：高保真地执行力或位置指令，增强触觉反馈。
后台运行：在后台运行，无需用户干预即可保持设备就绪状态。

运行、停止、重新启动

在 Windows 上：

打开服务桌面应用程序：按 Windows+R 打开运行框，输入 services.msc然后按 Enter 或选择 OK.

在 Ubuntu 上

开始
- systemctl start haply-inverse-service.service
停止
- systemctl stop haply-inverse-service.service
启用
- systemctl enable haply-inverse-service.service
禁用
- systemctl disable haply-inverse-service.service

重要文件

在 Windows 上：

配置文件位于%PROGRAMDATA%\Haply\Inverse\*-config.json
日志文件位于%PROGRAMDATA%\Haply\Inverse\*-log.log

在 Ubuntu 上

配置文件位于/etc/haply-inverse-service/*-config.json
日志文件位于/var/log/haply-inverse-service/*-log.log

在 OSX 上

配置文件位于$TMPDIR/Haply/Inverse/*-config.json
日志文件位于$TMPDIR/Haply/Inverse/*-log.log

JSON 格式版本

该服务目前支持两种不同的 JSON 格式： 3.0 和 3.1.两个版本同时提供，确保向后兼容。如果您正在使用 3.0 在您的模拟中使用的格式无需更改--它将继续像以前一样工作。不过，我们鼓励您更新到 3.1.x 版本，以利用其增强功能和更高的游戏引擎集成性能。

关键细节

3.0 版本
- 完全记录在 3.0.x 文档页面.
- HTTP 默认情况下可在 http://localhost:10000/3.0.
- Websockets 默认情况下可在 港 10000.
3.1 版本
- 完全记录在 3.1.x 文档页面.
- HTTP 默认情况下可在 http://localhost:10000/3.1.
- Websockets 默认情况下可在 港 10001.
- 改进了功能，并能更快地与游戏引擎集成。

欢迎升级到 3.1 在您方便的时候，您就可以利用它的优势，而不会影响您现有的工作流程。

接口

HTTP 和 Websocket 接口都使用 JSON 格式化的有效载荷。

信息

读取末端执行器的位置时，必须向设备发送力值（即使力值全为零）。

超文本传输协定

默认情况下，HTTP 服务在 http://localhost:10000.注意：端口可在配置中更改。

仪表板

仪表盘可在以下网址获取： http://localhost:10000

版本

方法获取

URL： http://localhost:10000/3.1/version

回复示例：

{
    "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"
}

设备

方法获取

URL： http://localhost:10000/3.1/devices

回复示例：

{
    "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"
            },
            "state": {
                "battery_level": 0.42000008,
                "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
            }
        }
    ]
}

力标尺

方法邮寄

URL： http://localhost:10000/3.1/force_scale

身体示例：

{
    "force_scale": 0.5
}

回复示例：

{
    "ok": true
}

重力补偿

方法邮寄

URL： http://localhost:10000/3.1/gravity_compensation

身体示例：

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

回复示例：

{
    "ok": true
}

扭矩缩放

方法邮寄

URL： http://localhost:10000/3.1/torque_scaling

身体示例：

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

回复示例：

{
    "ok": true
}

设备便携性

方法邮寄

URL： http://localhost:10000/3.1/device_handedness

身体示例：

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

回复示例：

{
    "ok": true
}

保存配置

仅适用于Inverse3 设备。警告：避免过于频繁地保存配置，因为可应用于任何特定设备的保存次数是有限的。

方法邮寄

URL： http://localhost:10000/3.1/save_configuration

身体示例：

{
    "device_id": "049D"
}

回复示例：

{
    "ok": true
}

串行启用

启用或禁用所有串行通信。当串行通信被禁用时，将无法向设备发送命令。

方法邮寄

URL： http://localhost:10000/3.1/serial_enable

身体示例：

{
    "enable": true
}

回复示例：

{
    "ok": true
}

抓握式垂直塞

启用或禁用手柄垂直停止实验功能。该功能将检查无线 VerseGrip 的方向，以检测 VerseGrip 是否掉落。触发时，它会将Inverse3 设置为当前位置的位置控制，这样末端效应器就不会掉落。当再次拿起 VerseGrip 时，该功能将自动关闭。

警告

作为一项试验性功能，它在默认情况下是禁用的，需要明确启用才能激活。

方法邮寄

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

身体示例：

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

回复示例：

{
    "ok": true
}

Websocket

默认 websocket URL 为 ws://localhost:10001.注意：端口可在配置中更改。

初始信息

当连接到 websocket 时，服务会发送一条包含完整设备列表的信息。初始信息如下 JSON 格式：

{
    "inverse3": [
        {
            "device_id": "04BA",
            "config": {
                "type": "inverse3",
                "device_info": {
                    "minor_version": 1,
                    "major_version": 7,
                    "id": "04BA",
                    "model": 4,
                    "uuid": ""
                },
                "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"
            },
            "state": {
                "battery_level": 0.42000008,
                "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
            }
        }
    ]
}

状态更新信息

每收到一条命令信息，服务就会发送一条包含所有设备状态的状态更新信息。

如果您想知道机器的状态，就必须事先向它发送信息，例如力值（即使力值为零）。如果将我们的设备用作输入设备，例如跟踪位置而不施加力，这一点尤为重要。状态更新信息如下 JSON 格式：

{
    "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.42000008,
                "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
            }
        }
    ]
}

指令信息

为了向 inverse3 客户端必须发送命令信息。下面是一个例子：

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

此外，还可以在一条信息中向多个设备发送命令：

{
    "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": []
}

目前可在 inverse3:

设置光标位置

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

设置光标力

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

设置角度位置

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

设置角扭矩

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

探测命令

probe_cursor_position, probe_angular_position inverse3 ，以及 probe_orientation 为诗句所有握柄都不包含指令数据。

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

运行、停止、重新启动​

重要文件​

JSON 格式版本​

关键细节​

接口​

超文本传输协定​

仪表板​

版本​

设备​

力标尺​

重力补偿​

扭矩缩放​

设备便携性​

保存配置​

串行启用​

抓握式垂直塞​

Websocket​

初始信息​

状态更新信息​

指令信息​

设置光标位置​

设置光标力​

设置角度位置​

设置角扭矩​

探测命令​

运行、停止、重新启动

重要文件

JSON 格式版本

关键细节

接口

超文本传输协定

仪表板

版本

设备

力标尺

重力补偿

扭矩缩放

设备便携性

保存配置

串行启用

抓握式垂直塞

Websocket

初始信息

状态更新信息

指令信息

设置光标位置

设置光标力

设置角度位置

设置角扭矩

探测命令