跳转至正文

超文本传输协定

基本上,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 或者 123ID 为 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此处使用的是。

支持的提示:

  • BOOL
  • INT
  • FLOAT
  • STRING
  • VEC2
  • VEC3
  • VEC4
  • TRANSFORM
  • ARR_INT
  • ARR_FLOAT
  • ARR_STRING
  • GENERIC

已停用的旧版端点​

几个 POST 该端点仍然被允许,但会输出停用警告,并且 4.0计划从……中移除。有关停用路线的详细信息 → 替代路线表请参见 3.5 迁移指南请 参阅。