跳转至主要内容

超文本传输协定

默认情况下,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} und {id_or_index} 识别目标设备。

示例路径段含义
inverse3/0根据索引(从0开始)查找首个Inverse3 设备
inverse3/A14Inverse3 附设备 ID A14
inverse3/*所有Inverse3 设备(占位符)
verse_grip/0根据索引查找第一节诗句
wireless_verse_grip/*所有无线Verse握把
*inverse/*Inverse 系列的所有设备(Inverse3 、Inverse3x、Minverse )
*verse_grip/*Verse-Grip 系列的所有设备(Verse Grip、Wireless VG)

占位符规则:

  • GET 不支持多义或占位符选择器(返回 400).
  • POST und DELETE 接受占位符——该操作将应用于所有符合条件的设备。

会议选择器​

与会话相关的端点(basis、mount、preset、transform、filters)需要查询参数 ?session=<expr>,用于识别会话。

打印含义
(省略)所有会话(仅限DELETE)
#123 oder简体中文(大陆) 123编号为 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 und status.

您可以选择 ?session=<expr> 传递该参数,以将快照过滤为特定会话的视图(此时,该会话的基础、挂载和转换将应用于返回的值)。

答题示例:

{
"inverse3": [
{
"device_id": "04BA",
"config": { "...": "..." },
"state": { "...": "..." },
"status": { "...": "..." }
}
]
}

会议​

MethodePfad描述
获取/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 )​

MethodePfad正文回答
获取/{device_type}/{id}/config/handedness--"left" oder简体中文(大陆) "right"
POST/{device_type}/{id}/config/handedness"left" oder简体中文(大陆) "right"返回值
删除/{device_type}/{id}/config/handedness--"right" (标准)

扭矩缩放(仅限Inverse3 )​

MethodePfad正文回答
获取/{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 )​

MethodePfad正文回答
获取/{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 }

依据(所有设备,按会话计算)​

MethodePfad正文回答
获取/{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" }

安装(所有设备,按会话计)​

MethodePfad正文回答
获取/{device_type}/{id}/config/mount?session=--{ "transform": {...} }
POST/{device_type}/{id}/config/mount?session={ "transform": {...} }返回值
删除/{device_type}/{id}/config/mount?session=--身份转变

转换结构(由 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 }
}
}

预设(所有设备,按会话区分)​

MethodePfad正文回答
获取/{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-Body 中必须至少包含一个字段。

MethodePfad正文回答
获取/{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 } oder简体中文(大陆) { "vector": {...} } 或者两者兼而有之返回值
删除/{device_type}/{id}/config/filters/damping?session=--两者均重置为零

力量之门​

MethodePfad正文回答
获取/{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=--利用默认设置

设备状态​

转换(所有设备,基于会话)​

工作域转换(从设备域到应用域)。

MethodePfad正文回答
获取/{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
}

设置​

以下设置的端点将自动生成:

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

所有关于设置密钥的参考信息,请参见此处

Routen​

Methode路线描述
获取/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 版迁移指南 有关过时路径 → 替代路线的完整映射表。