跳转至主要内容

超文本传输协定

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

路径段示例含义
inverse3/0根据索引(0为基准)显示的Inverse3
inverse3/A14Inverse3 设备标识符是 A14
inverse3/*所有Inverse3 设备(通配符)
verse_grip/0根据食指选择最佳握法
wireless_verse_grip/*所有 Wireless Verse Grip 产品
*inverse/*Inverse 系列的所有设备(Inverse3 、Inverse3x、Minverse )
*verse_grip/*Verse Grip 系列的所有设备(Verse Grip、Wireless VG)

关于通配符的规则:

  • GET 拒绝模棱两可或包含通配符的选择器(返回 400).
  • POST et DELETE 支持通配符:该操作将应用于所有匹配的设备。

会话选择器​

会话范围内的端点(basis、mount、preset、transform、filters)需要一个请求参数 ?session=<expr> 用于标识会话。

表达含义
(省略)所有会话(仅限 DELETE)
#123 ou 123会话的数字标识符为 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 et status.

您也可以转发 ?session=<expr> 用于根据特定会话的视角过滤快照(将该会话的基向量、挂载和变换应用于返回的值)。

答案示例:

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

会话​

方法Chemin说明
获取/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 )​

方法Chemin军团回复
获取/{device_type}/{id}/config/handedness--"left" ou "right"
POST/{device_type}/{id}/config/handedness"left" ou "right"返回值
删除/{device_type}/{id}/config/handedness--"right" (默认)

扭矩标定(仅限Inverse3 )​

方法Chemin军团回复
获取/{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 )​

方法Chemin军团回复
获取/{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 }

基础(所有设备,会话范围内)​

方法Chemin军团回复
获取/{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" }

挂载(所有设备,在会话范围内)​

方法Chemin军团回复
获取/{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 }
}
}

预设(所有设备,仅限当前会话)​

方法Chemin军团回复
获取/{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请求正文中必须至少包含一个字段。

方法Chemin军团回复
获取/{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 } ou { "vector": {...} } 你们两个返回值
删除/{device_type}/{id}/config/filters/damping?session=--两次重置

强行门​

方法Chemin军团回复
获取/{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=--在设置中定义的默认增益

设备状态​

转换(所有设备,仅限当前会话)​

工作空间的转换(从设备空间到应用程序空间)。

方法Chemin军团回复
获取/{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 版迁移指南 有关已弃用的路径与替代路径之间的完整对应表。