跳至主要内容
版本：3.5.x

超文本传输协定

默认情况下，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/0FirstInverse3 索引排序（从 0 开始）
inverse3/A14Inverse3 设备 ID） A14
inverse3/*所有Inverse3 （通配符）
verse_grip/0First Verse Grip 按索引排序
wireless_verse_grip/*全无线 Verse 握把
*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> 将快照过滤为特定会话的视角（将该会话的基础、挂载和转换应用于返回的值）。

回复示例：

{
  "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" (默认)

扭矩缩放（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=--身份转换

转换形状（由“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
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 迁移指南 查看完整的“已弃用路径 → 替代路由”对照表。