超文本传输协定
基本上,HTTP 服务是 http://localhost:10001从……开始。
端口可在服务设置中进行更改。
概述
本节介绍了该服务提供的 HTTP 路由。
以下所有路由均以默认基础 URL http://localhost:10001以此为基准。
标准响应信封
所有端点都会返回以下两种封装之一:
无数据响应(用于仅支持修改的端点):
{ "ok": true }
{ "ok": false, "error": "reason string" }
数据响应(用于 GET 请求以及向配置端点发送的 POST/DELETE 请求,这些请求会原样返回所应用的值):
{ "ok": true, "data": { "..." : "..." } }
{ "ok": false, "error": "reason string" }
设备选择器语法
设备级路径是 /{device_type}/{id_or_index}/... 使用该模式。 {device_type}和 {id_or_index} 路径段用于标识目标设备。
| 示例路径段 | 含义 |
|---|---|
inverse3/0 | 以索引(从0开始)指定的第一个Inverse3 |
inverse3/A14 | 设备 ID 为 A14人Inverse3 |
inverse3/* | 所有Inverse3 设备(通配符) |
verse_grip/0 | 作为索引指定的第一个 Verse Grip |
wireless_verse_grip/* | 所有 Wireless Verse Grip |
*inverse/* | Inverse 系列全线产品(Inverse3 、Inverse3x、Minverse ) |
*verse_grip/* | Verse Grip 系列所有设备(Verse Grip、Wireless VG) |
通配符规则:
GET会拒绝包含模糊或通配符的选择器(400返回)。POST哇DELETE允许使用通配符——该操作将应用于所有匹配的设备。
会话选择器
会话范围端点(basis、mount、preset、transform、filters)用于标识会话, ?session=<expr> 需要查询参数。
| 表达式 | 含义 |
|---|---|
| (省略) | 所有会话(仅限 DELETE) |
#123 或者 123 | ID 为 123 的会话 |
:-1 | 按指数划分的最近一个交易日 |
:0 | 按索引排序的第一场会议 |
示例: GET /inverse3/0/config/basis?session=:0
版本
方法: GET
URL: http://localhost:10001/version
回答示例:
{
"build_time": "2024-08-07T16:01:53Z",
"git_branch": "main",
"git_describe": "3.5.0-2-gce34c39e",
"git_hash": "ce34c39e",
"git_tag": "3.5.0",
"project_name": "haply-inverse-service",
"project_version": "3.5.0"
}
专家状态
方法: GET
URL: http://localhost:10001/expert/status
返回包括检测、设备、会话和全局设置在内的详细状态信息。
设备
方法: GET
URL: http://localhost:10001/devices
config, state, status返回包含该设备的当前设备列表。
有选择地 ?session=<expr>通过传递该参数,可以将快照按特定会话的视角进行过滤(将该会话的 basis、mount 和 transform 应用于返回的值)。
回答示例:
{
"inverse3": [
{
"device_id": "04BA",
"config": { "...": "..." },
"state": { "...": "..." },
"status": { "...": "..." }
}
]
}
会话
| 方法 | 路径 | 说明 |
|---|---|---|
| 获取 | /sessions | 查询活跃 v3.1 会话的完整列表 |
| 获取 | /sessions/{session_id} | 单次会话查询 |
| 获取 | /sessions/{session_id}/profile | 查询会话配置文件名称 |
| POST | /sessions/{session_id}/profile | 会话配置设置 |
| 删除 | /sessions/{session_id}/profile | 个人资料 "default"重置为 |
POST /sessions/{session_id}/profile 正文:
{
"name": "my_profile"
}
港口
方法: POST
URL: http://localhost:10001/ports/{port}/reset
解除被禁用的串行端口的禁用状态。 { "ok": true }返回。
设备配置
所有配置(config)端点都是 /{device_type}/{id_or_index}/config/{setting} 使用该模式。
会话范围端点(basis、mount、preset)还需 ?session=<expr> 需要查询参数。
手部惯性(Handedness,仅限Inverse3 )
| 方法 | 路径 | 正文 | 回复 |
|---|---|---|---|
| 获取 | /{device_type}/{id}/config/handedness | -- | "left" 或者 "right" |
| POST | /{device_type}/{id}/config/handedness | "left" 或者 "right" | 原样返回输入值 |
| 删除 | /{device_type}/{id}/config/handedness | -- | "right" (默认值) |
扭矩缩放(仅限Inverse3 )
| 方法 | 路径 | 正文 | 回复 |
|---|---|---|---|
| 获取 | /{device_type}/{id}/config/torque_scaling | -- | { "enabled": bool } |
| POST | /{device_type}/{id}/config/torque_scaling | { "enabled": bool } | 原样返回输入值 |
| 删除 | /{device_type}/{id}/config/torque_scaling | -- | { "enabled": false } |
重力补偿(仅限Inverse3 )
| 方法 | 路径 | 正文 | 回复 |
|---|---|---|---|
| 获取 | /{device_type}/{id}/config/gravity_compensation | -- | { "enabled": bool, "scaling_factor": float } |
| POST | /{device_type}/{id}/config/gravity_compensation | { "enabled": bool, "scaling_factor": float } | 原样返回输入值 |
| 删除 | /{device_type}/{id}/config/gravity_compensation | -- | { "enabled": true, "scaling_factor": 1.0 } |
基础(所有设备,会话范围)
| 方法 | 路径 | 正文 | 回复 |
|---|---|---|---|
| 获取 | /{device_type}/{id}/config/basis?session= | -- | { "permutation": "XYZ" } |
| POST | /{device_type}/{id}/config/basis?session= | { "permutation": "ZXY" } | 原样返回输入值 |
| 删除 | /{device_type}/{id}/config/basis?session= | -- | { "permutation": "XYZ" } |
挂载(所有设备,会话范围)
| 方法 | 路径 | 正文 | 回复 |
|---|---|---|---|
| 获取 | /{device_type}/{id}/config/mount?session= | -- | { "transform": {...} } |
| POST | /{device_type}/{id}/config/mount?session= | { "transform": {...} } | 原样返回输入值 |
| 删除 | /{device_type}/{id}/config/mount?session= | -- | 恒等变换(identity transform) |
Transform 结构(用于 mount 以及 state/transform):
{
"transform": {
"position": { "x": 0, "y": 0, "z": 0 },
"rotation": { "x": 0, "y": 0, "z": 0, "w": 1 },
"scale": { "x": 1, "y": 1, "z": 1 }
}
}
预设(所有设备,会话范围)
| 方法 | 路径 | 正文 | 回复 |
|---|---|---|---|
| 获取 | /{device_type}/{id}/config/preset?session= | -- | { "preset": "arm_front_centered" } |
| POST | /{device_type}/{id}/config/preset?session= | { "preset": "arm_front_centered" } | 返回值 |
| 删除 | /{device_type}/{id}/config/preset?session= | -- | { "preset": "device_defaults" } |
可用值: device_defaults, arm_front, arm_front_centered, led_front, led_front_centered, custom.
设备过滤器(仅限Inverse3 ,会话范围)
过滤器端点是 /{device_type}/{id}/config/filters/{filter}?session=<expr> 使用该路径。
阻尼
同时控制均匀阻尼和定向阻尼。POST 请求正文中必须至少包含一个字段。
| 方法 | 路径 | 正文 | 回复 |
|---|---|---|---|
| 获取 | /{device_type}/{id}/config/filters/damping?session= | -- | { "scalar": float, "vector": { "x": f, "y": f, "z": f } } |
| POST | /{device_type}/{id}/config/filters/damping?session= | { "scalar": float } 或者 { "vector": {...} } 或者两者兼有 | 返回值 |
| 删除 | /{device_type}/{id}/config/filters/damping?session= | -- | 将两者都重置为0 |
原力之门
| 方法 | 路径 | 正文 | 回复 |
|---|---|---|---|
| 获取 | /{device_type}/{id}/config/filters/force_gate?session= | -- | { "gain": float } |
| POST | /{device_type}/{id}/config/filters/force_gate?session= | { "gain": float } | 返回值 |
| 删除 | /{device_type}/{id}/config/filters/force_gate?session= | -- | 设置中的默认增益值 |
设备状态
转化(所有设备,会话范围)
工作区转换(从设备空间到应用程序空间)。
| 方法 | 路径 | 正文 | 回复 |
|---|---|---|---|
| 获取 | /{device_type}/{id}/state/transform?session= | -- | { "transform": {...} } |
| POST | /{device_type}/{id}/state/transform?session= | { "transform": {...} } | 返回值 |
| 删除 | /{device_type}/{id}/state/transform?session= | -- | 恒等变换 |
保存配置
Inverse3 仅在设备上运行。警告:请勿过于频繁地保存配置,因为单个设备可保存的次数是有限的 (约10,000次EEPROM写入)。
方法: POST
URL: http://localhost:10001/save_configuration
正文示例:
{
"device_id": "049D"
}
回答示例:
{
"ok": true
}
设置
系统会针对以下项目自动生成配置端点:
- 列出所有设置(包括元数据)
- 读取单个设置值
- 应用设置(单个或批量)
- 将密钥重置为默认值
所有设置键的参考信息可在此处查看
Route
| 方法 | Route | 说明 |
|---|---|---|
| 获取 | /settings/ | 获取所有配置键、值和元数据。 |
| POST | /settings/ | 一次性批量应用多项设置。 |
| 获取 | /settings/{key} | 获取特定配置键的当前值。 |
| POST | /settings/{key} | 将新值应用到特定键上。 |
| 删除 | /settings/{key} | 将密钥重置为默认值。 |
答题形式
获取 /settings/ (所有设置)
返回以设置键为键的对象。每个条目包含以下内容:
value: 当前值metadata: 类型 + 约束条件 + 锁定状态
项目示例:
{
"devices/detection/timeout": {
"metadata": {
"constraint": {
"range": {
"max": 15,
"min": 1,
"step": 0
}
},
"locked": false,
"type_hint": "INT"
},
"value": 5
}
}
获取 /settings/{key} (单一设置)
仅返回所请求密钥对应的值(不包括元数据)。
应用设置
POST /settings/ (批量应用)
一次性批量应用多个键。
推荐的正文格式:将键映射到值的 JSON 对象。
{
"devices/detection/timeout": 5,
"devices/detection/advanced/wvg_description_filter": ["Haply USB Transceiver", "Haply Handle"]
}
POST /settings/{key} (单一适用)
将新值应用到单个键上。
推荐的正文格式:原始 JSON 值或封装值(为确保清晰度,建议使用封装值)。
{
"value": 5
}
重置设置
删除 /settings/{key}
将密钥恢复为默认值。
这相当于“重置为默认值”。
类型提示
服务 type_hint自动推断。对于复杂类型,可使用替代值 GENERIC此处使用的是。
支持的提示:
BOOLINTFLOATSTRINGVEC2VEC3VEC4TRANSFORMARR_INTARR_FLOATARR_STRINGGENERIC
已停用的旧版端点
几个 POST 该端点仍然被允许,但会输出停用警告,并且
4.0计划从……中移除。有关停用路线的详细信息 → 替代路线表请参见 3.5 迁移指南请
参阅。