跳到主要内容

HTTP

默认情况下，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 或 123数字 ID 为 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"
}

Expert 状态​

方法： 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": { "...": "..." }
    }
  ]
}

会话​

方法路径说明
GET/sessions列出所有活动的 v3.1 会话
GET/sessions/{session_id}获取单个会话
GET/sessions/{session_id}/profile获取会话配置文件名称
POST/sessions/{session_id}/profile设置会话配置文件
DELETE/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）​

方法路径请求体响应
GET/{device_type}/{id}/config/handedness--"left" 或 "right"
POST/{device_type}/{id}/config/handedness"left" 或 "right"回显值
DELETE/{device_type}/{id}/config/handedness--"right"（默认）

扭矩缩放（仅 Inverse3）​

方法路径请求体响应
GET/{device_type}/{id}/config/torque_scaling--{ "enabled": bool }
POST/{device_type}/{id}/config/torque_scaling{ "enabled": bool }回显值
DELETE/{device_type}/{id}/config/torque_scaling--{ "enabled": false }

重力补偿（仅 Inverse3）​

方法路径请求体响应
GET/{device_type}/{id}/config/gravity_compensation--{ "enabled": bool, "scaling_factor": float }
POST/{device_type}/{id}/config/gravity_compensation{ "enabled": bool, "scaling_factor": float }回显值
DELETE/{device_type}/{id}/config/gravity_compensation--{ "enabled": true, "scaling_factor": 1.0 }

Basis（所有设备，会话级）​

方法路径请求体响应
GET/{device_type}/{id}/config/basis?session=--{ "permutation": "XYZ" }
POST/{device_type}/{id}/config/basis?session={ "permutation": "ZXY" }回显值
DELETE/{device_type}/{id}/config/basis?session=--{ "permutation": "XYZ" }

Mount（所有设备，会话级）​

方法路径请求体响应
GET/{device_type}/{id}/config/mount?session=--{ "transform": {...} }
POST/{device_type}/{id}/config/mount?session={ "transform": {...} }回显值
DELETE/{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 }
  }
}

预设（所有设备，会话级）​

方法路径请求体响应
GET/{device_type}/{id}/config/preset?session=--{ "preset": "arm_front_centered" }
POST/{device_type}/{id}/config/preset?session={ "preset": "arm_front_centered" }回显值
DELETE/{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 请求体中至少须包含一个字段。

方法路径请求体响应
GET/{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": {...} }，或两者同时提供回显值
DELETE/{device_type}/{id}/config/filters/damping?session=--两者均重置为零

力门控​

方法路径请求体响应
GET/{device_type}/{id}/config/filters/force_gate?session=--{ "gain": float }
POST/{device_type}/{id}/config/filters/force_gate?session={ "gain": float }回显值
DELETE/{device_type}/{id}/config/filters/force_gate?session=--设置中的默认增益

设备状态​

变换（所有设备，会话级）​

工作空间变换（从设备空间到应用空间）。

方法路径请求体响应
GET/{device_type}/{id}/state/transform?session=--{ "transform": {...} }
POST/{device_type}/{id}/state/transform?session={ "transform": {...} }回显值
DELETE/{device_type}/{id}/state/transform?session=--恒等变换

保存配置​

仅适用于 Inverse3 设备。警告：请避免过于频繁地保存配置，因为单台设备可执行的保存次数有限 （约 10,000 次 EEPROM 写入）。

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

请求体示例：

{
  "device_id": "049D"
}

响应示例：

{
  "ok": true
}

设置​

设置端点自动提供以下功能：

  • 列出所有设置（包括元数据）
  • 读取单个设置的值
  • 应用设置（单个或批量）
  • 将某个键重置为其默认值

所有设置键的说明可在此处查看。

路由​

方法路由描述
GET/settings/获取全部设置键、值和元数据。
POST/settings/一次批量应用多个设置。
GET/settings/{key}获取指定设置键的当前值。
POST/settings/{key}为指定键应用新值。
DELETE/settings/{key}将某个键重置为其默认值。

响应结构​

GET /settings/（所有设置）​

返回以设置键为键的对象。每个条目包含：

  • value：当前值
  • metadata：类型 + 约束 + 锁定状态

条目示例：

{
  "devices/detection/timeout": {
    "metadata": {
      "constraint": {
        "range": {
          "max": 15,
          "min": 1,
          "step": 0
        }
      },
      "locked": false,
      "type_hint": "INT"
    },
    "value": 5
  }
}

GET /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
}

重置设置​

DELETE /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 迁移指南， 查看完整的已弃用路径与替代路由对照表。