超文本传输协定
默认情况下,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/A14 | Inverse3 设备标识符是 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).POSTetDELETE支持通配符:该操作将应用于所有匹配的设备。
会话选择器
会话范围内的端点(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 被用作复杂类型的备用方案。
适用适应症:
BOOLINTFLOATSTRINGVEC2VEC3VEC4TRANSFORMARR_INTARR_FLOATARR_STRINGGENERIC
已弃用的旧版端点
多个端点 POST 这些代码仍然被接受,但会触发过时警告,
并且将在下一个版本中被移除 4.0. 请参阅 3.5 版迁移指南
有关已弃用的路径与替代路径之间的完整对应表。