跳过至主要内容

超文本传输协定

默认情况下,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 } 返回。


设备设置​

所有配置端点都是 /{device_type}/{id_or_index}/config/{setting} 使用该模式。

在会话作用域的端点(basis、mount、preset)中,还 ?session=<expr> 需要查询参数。

惯用手(仅限Inverse3 )​

方法通关车身响应
获取/{device_type}/{id}/config/handedness--"left" 或者 "right"
POST/{device_type}/{id}/config/handedness"left" 或者 "right"回显的值
删除/{device_type}/{id}/config/handedness--"right"(默认)

Torx 刻度(仅限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" }

Mount(所有设备、会话作用域)​

方法通关车身响应
获取/{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=--将两者都重置为零

ForceGate​

方法通关车身响应
获取/{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 仅在设备上运行。警告:请勿频繁保存设置。 每个设备可保存的次数有限(EEPROM 写入次数约为 10,000 次)。

方法: POST
URL: http://localhost:10001/save_configuration

正文示例:

{
"device_id": "049D"
}

响应示例:

{
"ok": true
}

设置​

以下内容的端点将自动生成:

  • 获取所有设置的列表(包括元数据)
  • 读取单个设置值
  • 应用设置(单个或批量)
  • 将键重置为默认值

设置键的列表请参见此处。

路线​

方法路线说明
获取/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 迁移指南请查看。