超文本传输协定
默认情况下,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} und {id_or_index} 识别目标设备。
| 示例路径段 | 含义 |
|---|---|
inverse3/0 | 根据索引(从0开始)查找首个Inverse3 设备 |
inverse3/A14 | Inverse3 附设备 ID A14 |
inverse3/* | 所有Inverse3 设备(占位符) |
verse_grip/0 | 根据索引查找第一节诗句 |
wireless_verse_grip/* | 所有无线Verse握把 |
*inverse/* | Inverse 系列的所有设备(Inverse3 、Inverse3x、Minverse ) |
*verse_grip/* | Verse-Grip 系列的所有设备(Verse Grip、Wireless VG) |
占位符规则:
GET不支持多义或占位符选择器(返回400).POSTundDELETE接受占位符——该操作将应用于所有符合条件的设备。
会议选择器
与会话相关的端点(basis、mount、preset、transform、filters)需要查询参数 ?session=<expr>,用于识别会话。
| 打印 | 含义 |
|---|---|
| (省略) | 所有会话(仅限DELETE) |
#123 oder简体中文(大陆) 123 | 编号为 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 und status.
您可以选择 ?session=<expr> 传递该参数,以将快照过滤为特定会话的视图(此时,该会话的基础、挂载和转换将应用于返回的值)。
答题示例:
{
"inverse3": [
{
"device_id": "04BA",
"config": { "...": "..." },
"state": { "...": "..." },
"status": { "...": "..." }
}
]
}
会议
| Methode | Pfad | 描述 |
|---|---|---|
| 获取 | /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 )
| Methode | Pfad | 正文 | 回答 |
|---|---|---|---|
| 获取 | /{device_type}/{id}/config/handedness | -- | "left" oder简体中文(大陆) "right" |
| POST | /{device_type}/{id}/config/handedness | "left" oder简体中文(大陆) "right" | 返回值 |
| 删除 | /{device_type}/{id}/config/handedness | -- | "right" (标准) |
扭矩缩放(仅限Inverse3 )
| Methode | Pfad | 正文 | 回答 |
|---|---|---|---|
| 获取 | /{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 )
| Methode | Pfad | 正文 | 回答 |
|---|---|---|---|
| 获取 | /{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 } |
依据(所有设备,按会话计算)
| Methode | Pfad | 正文 | 回答 |
|---|---|---|---|
| 获取 | /{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" } |
安装(所有设备,按会话计)
| Methode | Pfad | 正文 | 回答 |
|---|---|---|---|
| 获取 | /{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 }
}
}
预设(所有设备,按会话区分)
| Methode | Pfad | 正文 | 回答 |
|---|---|---|---|
| 获取 | /{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-Body 中必须至少包含一个字段。
| Methode | Pfad | 正文 | 回答 |
|---|---|---|---|
| 获取 | /{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 } oder简体中文(大陆) { "vector": {...} } 或者两者兼而有之 | 返回值 |
| 删除 | /{device_type}/{id}/config/filters/damping?session= | -- | 两者均重置为零 |
力量之门
| Methode | Pfad | 正文 | 回答 |
|---|---|---|---|
| 获取 | /{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= | -- | 利用默认设置 |
设备状态
转换(所有设备,基于会话)
工作域转换(从设备域到应用域)。
| Methode | Pfad | 正文 | 回答 |
|---|---|---|---|
| 获取 | /{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
}
设置
以下设置的端点将自动生成:
- 列出所有设置(包括元数据)
- 读取单个设置值
- 应用设置(单个或批量)
- 将密钥重置为默认值
所有关于设置密钥的参考信息,请参见此处
Routen
| Methode | 路线 | 描述 |
|---|---|---|
| 获取 | /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 版迁移指南
有关过时路径 → 替代路线的完整映射表。