跳至主要内容

超文本传输协定

默认情况下,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
网址: 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
网址: http://localhost:10001/expert/status

返回详细的状态信息,包括检测、设备、会话以及全局设置。


设备​

方法: GET
网址: 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
网址: 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"(默认)

扭矩缩放(仅限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=--恒等变换

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=--两者均重置为零

力门控​

方法路径请求正文回复
获取/{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
网址: 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 迁移指南, 查看完整的已弃用路径与替代路由对照表。