设置参考
在本文档中，/settings/端点返回的所有配置，请分别在键、型（type_hint（来自），以及制约（metadata.constraint.range、以及（如适用）locked（从……开始）一并列在列表中。
locked的设置是，运行时为只读。可以通过配置文件，或者Haply Hub虽然可以在设置页面进行更改，但要使更改生效，需要完全重启该服务。这些内容在以下表格中启动上面是这样写的。
构成
用于在服务启动时覆盖设置的配置文件位于以下位置：
| 平台 | 地点 |
|---|---|
| Windows | C:\ProgramData\Haply\Inverse\haply-inverse-service-config.json |
| macOS | /Library/Application Support/Haply/Inverse/haply-inverse-service-config.json |
| Linux | /etc/haply-inverse-service/haply-inverse-service-config.json |
配置文件用于将配置键与覆盖值进行映射扁平化的 JSON 对象是。关键在于，/settings/ HTTP 路由（API 参考文档（参见）返回的有效配置键。对于未指定的键，将使用服务的默认值。
例如，网络配置的覆盖设置如下：
{
"communication/http/port": 8400,
"communication/websocket/port": 8500,
"communication/events/port": 9000,
"communication/bind_all_interfaces": true
}
显示与筛选
/settings列表端点（GET /settings、GET /settings/）默认情况下是基本仅返回设置。若要包含高级设置，请?advanced=true若要包含不推荐的别名，请?deprecated=true请指定。隐藏设置专用于内部使用，POST /settings/misc/hidden_settings通过……misc/hidden_settings仅在设置了该选项时才会显示（没有等效的查询参数）。筛选标志将以“AND”条件进行组合。advanced和hidden对于同时标记了这两个标志的密钥，必须打开两个门。针对已知密钥的 POST 和 DELETE 操作不属于门控范围。
如果准确指定了正确的键，则进行单键读取（GET /settings/<key>）可绕过 advanced/deprecated 检查机制。这对具备相关知识的客户端非常有用。隐藏的密钥仍需经过检查机制。
3个运行时开关用于设置网关的初始值。这些值将在服务运行期间一直保持不变：
| 键 | 型 | 制约 | 说明 |
|---|---|---|---|
misc/advanced_settings | bool | — | GET /settings在列表中advanced包括带有标记的设置（默认值为false）。在所有请求中?advanced=true这相当于将其交出。 |
misc/deprecated_settings | bool | — | GET /settings在列表中deprecated包括带有标记的设置（默认值为false）。在所有请求中?deprecated=true这相当于将其交出。 |
类型映射
API 返回的类型提示支持以下 JSON 格式：
STRING→stringBOOL→boolINT→intFLOAT→floatARR_STRING→string[]VEC3→vec3（{x, y, z}（具有该属性的对象）GENERIC→json（任意结构化值）
communication/…
HTTP、WebSocket 以及事件流服务器的网络端口和绑定地址。大多数条目仅在启动时有效。
| 键 | 型 | 制约 | 说明 |
|---|---|---|---|
communication/serial/enabled | bool | — | 启用或禁用串行设备通信。 |
communication/bind_address | string | 启动 | HTTP 和 WebSocket 服务器绑定的 IP 地址。 |
communication/bind_all_interfaces | bool | 启动 | 请将 localhost 替换为服务器0.0.0.0绑定到。 |
communication/http/port | int | 启动 | HTTP REST API 的端口（默认值） 10000）。 |
communication/websocket/port | int | 启动 | 主 v3.1 WebSocket 端口（默认值 10001）。 |
communication/websocket/legacy_port | int | 启动 | Legacy 的 v3.0 WebSocket 端口（默认值 10000）。 |
communication/events/port | int | 启动 | 事件流 WebSocket 端口（默认值 10020）。 |
devices/…
devices/detection/…
这是串行端口的扫描策略。所有条目均为高级设置。
| 键 | 型 | 制约 | 说明 |
|---|---|---|---|
devices/detection/scan_period_ms | int | 范围 100–10000；启动时 | 串行端口的扫描间隔（毫秒）。 |
devices/detection/handshake_timeout_s | int | 范围 1–15 | 每个端口的握手超时时间（秒）。 |
devices/detection/max_retries | int | 范围 1–10 | 每个端口的握手最大重试次数。 |
devices/detection/failure_log_delay_s | int | 范围 1–60 | 在再次将检测失败记录到日志之前所需的延迟（秒）。 |
devices/detection/block_looping_ports | bool | — | 如果检测到存在循环端口，则阻止设备进入就绪状态。 |
devices/detection/excluded_ports | json | — | 检测时要跳过的串行端口路径。 |
devices/detection/additional_ports | string[] | — | 无条件扫描的附加串行端口路径。 |
devices/detection/allowed_vendor_id_filter | string[] | — | 在端口枚举时允许的USB供应商ID。 |
devices/detection/port_name_substring_filter | string[] | — | 用于统一的、平台特有的端口名称子字符串。 |
devices/detection/wireless_verse_grip_description_filter | string[] | — | 用于检测无线VerseGrip的端口说明中的部分字符串。 |
devices/detection/inverse3x_description_filter | string[] | — | 用于检测 Inverse3x 的端口说明中的部分字符串。 |
devices/detection/extra_ports (不建议) | string[] | — | 相反 devices/detection/additional_ports 请使用该功能。读写操作将透明地转发至正规密钥。 |
devices/*inverse/…
这是适用于所有 Inverse3 系列设备的全局默认值。若在会话中进行了覆盖设置，则以会话设置为准。
在 3.5.1 中更名
在 3.5.0 版本中，Grob 是 devices/inverse*/… 是。目前，最前面的 * 但 inverse 将置于其前。由于在 3.5.1 版本中，使用旧式字面量的配置文件会导致绑定失败，请进行更新。除此之外，该键本身没有其他变化。
| 键 | 型 | 制约 | 说明 |
|---|---|---|---|
devices/*inverse/filters/force_scale/gain | float | 范围 0.0–2.0 | 适用于所有设备的全局功率输出系数。 |
devices/*inverse/filters/force_gate/gain | float | 范围 0.0–1.0 | 新会话的默认力门增益。 |
devices/*inverse/control_timeout_ms | int | 范围 50–10000 | 解除设备控制锁定的超时时间（毫秒）。 |
devices/*inverse/query_orientation_on_idle | bool | — | 当设备处于空闲状态时，通过固件查询机身的朝向。 |
devices/*inverse/safeties/expose_in_snapshot | bool | — | 各设备的安全标志 GET /devices/{id} 包含在快照中。 |
devices/presets
| 键 | 型 | 制约 | 说明 |
|---|---|---|---|
devices/presets | json | — | 按设备类型划分的默认设备配置预设（如安装转换和基底等。适用对象为 inverse_arm_front_*、inverse_led_front_*、minverse_*、verse_grip_default、wireless_verse_grip_default、custom_verse_grip_default）。 |
devices/wireless_verse_grip/…
| 键 | 型 | 制约 | 说明 |
|---|---|---|---|
devices/wireless_verse_grip/battery/low_threshold | int | — | 当电池电量（%）低于该数值时，将触发低电量警告。 |
devices/wireless_verse_grip/battery/critical_threshold | int | — | 当电池电量（%）低于该数值时，将触发电池危险警报。 |
devices/wireless_verse_grip/battery/reset_margin | int | — | 解除电池警告所需的迟滞裕度。 |
devices/wireless_verse_grip/filters/orientation_filter | json | 启动时 | 针对无线VerseGrip方向的One Euro Filter设置。 |
features/…
features/calibration/…
| 键 | 型 | 制约 | 说明 |
|---|---|---|---|
features/calibration/hall_threshold | int | 范围 1–32 | 校准过程中，用于判断是否安装了笔的孔传感器所对应的电平。 |
features/grip_hook/…
这是“抓取钩”的自动功能。只要“抓取钩”保持垂直状态，就会锁定光标。
| 键 | 型 | 制约 | 说明 |
|---|---|---|---|
features/grip_hook/enabled | bool | — | 当握把保持垂直时，启用握把挂钩的自动锁定功能。 |
features/grip_hook/use_hall | bool | — | 在检测握持状态时，使用霍尔传感器的阈值，而非方向。 |
features/grip_hook/hall | int | 范围 1–32 | 触发抓握锁定的霍尔传感器值阈值。 |
features/grip_hook/hold_duration | int | 范围 10–1000 | 触发后保持锁定的时间（毫秒）。 |
features/navigation/bubble/…
这是气泡导航模块的默认值。bubble 当该操作首次激活时，它将被传递给会话。关于各字段在运行时的含义，请参见：导航模块 请参阅该页面。
| 键 | 型 | 制约 | 说明 |
|---|---|---|---|
features/navigation/bubble/center | vec3 | — | 气泡中心位置的默认值。 |
features/navigation/bubble/center_enabled | bool | — | 当气泡效果首次启用时，已设置的 center 将……应用于。 |
features/navigation/bubble/rotation_enabled | bool | — | 将工作区旋转应用于导航方向。 |
features/navigation/bubble/scale_enabled | bool | — | 将工作区的缩放比例应用于导航速度。 |
features/navigation/bubble/center_drift_speed | float | ≥ 0 | auto_follow 中心模式下的漂移速度（m/s）。 |
features/navigation/bubble/max_velocity | float | — | 速度区域内的最大导航速度（m/s）。 |
features/navigation/bubble/velocity_zone_width | float | — | 气泡表面外侧速度带的宽度（米）。 |
features/navigation/bubble/reset_velocity_on_entry | bool | — | 当光标进入气泡内时，将速度重置为零。 |
features/navigation/bubble/spring_inner | float | — | 气泡中心的弹性系数（N/m）。 |
features/navigation/bubble/spring_surface | float | — | 气泡表面的弹性系数（N/m）。 |
features/navigation/bubble/spring_outer | float | — | 外侧边界处的弹性系数（N/m）。 |
features/navigation/bubble/damping_inner | float | — | 气泡中心的衰减系数（Ns/m）。 |
features/navigation/bubble/damping_surface | float | — | 气泡表面的衰减系数 (Ns/m)。 |
features/navigation/bubble/damping_outer | float | — | 外侧边界处的衰减系数 (Ns/m)。 |
features/navigation/bubble/wall_stiffness | float | — | 外侧边界上坚硬壁面的刚度（N/m）。 |
features/navigation/bubble/bump_width | float | — | 气泡表面上触觉凸起的宽度（米）。 |
features/navigation/bubble/bump_stiffness | float | — | 气泡表面触觉凸起的刚度（N/m）。 |
features/navigation/bubble/stop_at_collision | bool | — | 在碰撞有效期间，将防止气泡中心沿碰撞方向漂移。 |
features/navigation/bubble/collision_threshold | float | > 0 | 检测碰撞的外力大小（N）。 |
features/navigation/bubble/collision_inflate_scale | float | ≥ 1 | 在冲突有效期间，velocity_zone_width 适用于该项的乘数。 |
features/navigation/bubble/collision_exit_ratio | float | 区间 (0,1] | 滞后比。|ext_force| 但 collision_threshold × this 向下移动即可解除冲突。1.0 在这种情况下，滞后效应将被禁用。 |
features/navigation/bubble/avatar_boundary_enabled | bool | — | 将化身在世界中的位置设置为已设定的 avatar_boundary 限制在 SDF 形状范围内。 |
features/safe_trajectory/…
这是针对末端执行器运动的速度限制器。
| 键 | 型 | 制约 | 说明 |
|---|---|---|---|
features/safe_trajectory/enabled | bool | — | 启用安全轨迹的速度限制器。 |
features/safe_trajectory/max_vel | float | 范围 0.01–2.0 | 末端执行器的最大允许速度（m/s）。 |
features/screensaver/…
当未被会话操作时，Inverse3 设备上会播放的空闲动画。
| 键 | 型 | 制约 | 说明 |
|---|---|---|---|
features/screensaver/enabled | bool | — | Inverse3 在设备处于空闲状态时启用屏幕保护程序动画。 |
features/screensaver/speed | float | 范围 0.001–0.2 | 屏幕保护程序动画的速度。 |
features/screensaver/distracted_speed | float | 范围 0.001–0.2 | 当用户在附近但未进行操作时的动画速度。 |
features/sdf/…
带符号距离场（SDF）的触觉效果模块（SDF HFX）。
| 键 | 型 | 制约 | 说明 |
|---|---|---|---|
features/sdf/enabled | bool | — | 启用或禁用 SDF 触觉效果模块。 |
features/sdf/state_output | bool | — | 默认情况下，设备输出有效载荷中将包含 SDF 的状态。 |
features/sdf/max_count | int | 范围 0–128 | 有效的 SDF 效果的最大数量（0 = 无限制）。 |
features/sdf/events/created | bool | — | 当创建新的 SDF 效果时，会触发该事件。 |
features/sdf/events/deleted | bool | — | 当 SDF 效果被删除时，会触发该事件。 |
features/sdf/events/updated | bool | — | 当 SDF 效果更新时，会触发该事件。 |
features/sdf/probe_on_zero_force/enabled | bool | — | 当印加力接近于零时，将自动探测 SDF 场。 |
features/sdf/probe_on_zero_force/delay | float | 范围 0.001–60.0 | 从力降至零到开始自动探针检测之间的延迟（s）。 |
features/verse_grip_pairing/…
Inverse3 用于跟踪与（有线或无线）Verse Grip 之间的安装/拆卸操作。这是Haply Hub 配对用户界面的基础。
| 键 | 型 | 制约 | 说明 |
|---|---|---|---|
features/verse_grip_pairing/enabled | bool | — | 启用配对以及安装/拆卸的跟踪功能。 |
features/verse_grip_pairing/hall_threshold_vg | int | 范围 1–32 | 判定为已安装有线 VerseGrip 的孔位级别。 |
features/verse_grip_pairing/hall_threshold_wvg | int | 范围 1–32 | 判定为已安装无线 VerseGrip 的孔位级别。 |
features/verse_grip_pairing/detach_debounce_ms | int | 范围 0–1000 | 在确认断开之前所需的防抖时间（毫秒）。 |
features/verse_grip_pairing/heartbeat_ms | int | 范围 100–10000 | 强制性重新通知的间隔（毫秒）。 |
features/verse_grip_pairing/force_attached | bool | — | 绕过霍尔传感器，始终监测安装状态 true 强制执行（硬件故障时的应对措施）。 |
session/serialization/…
Transform 输出格式 — 这会影响 WebSocket 和 HTTP JSON 负载。为了反映会话级作用域，这些键在 3.5.1 版中 serialization/* 从 session/serialization/* 已迁移至此处。旧路径将继续通过已弃用的别名进行解析。
| 键 | 型 | 制约 | 说明 |
|---|---|---|---|
session/serialization/explicit_fields | bool | — | 在序列化后的输出中，包含与默认值“恒等”（identity）相等的 transform 字段（例如： position: {0,0,0}、rotation: {w:1,…}）。当客户端要求所有字段都必须存在时，此选项非常有用。默认值： false。 |
session/serialization/force_complete_transforms | bool | — | 包括仅支持方向控制的设备（Verse Grip、Wireless Verse Grip）在内，所有 transform 输出均 position、rotation、以及 scale 会持续输出。这些设备通常 rotation 仅输出。session/serialization/explicit_fields 是其上位互换，包含其所有功能。默认值： false。 |
serialization/explicit_fields (不建议) | bool | — | 相反 session/serialization/explicit_fields 请使用该功能。读写操作将透明地转发至正规密钥。 |
serialization/force_complete_transforms (不建议) | bool | — | 相反 session/serialization/force_complete_transforms 请使用该功能。读写操作将透明地转发至正规密钥。 |
session/…
会话调度程序。
| 键 | 型 | 制约 | 说明 |
|---|---|---|---|
session/min_simulation_rate_hz | int | 范围 20–500 | 在触发警告之前，设备模拟速率的最小允许值（Hz）。 |
rate/…
服务限流。在 3.5.1 版本中引入——以下 4 个 rate/websocket/* 关键在于，以前 session/commands/* 位于……下方。旧路径将继续通过已弃用的别名进行解析。
| 键 | 型 | 制约 | 说明 |
|---|---|---|---|
rate/websocket/zoh_window_ms | int | — | 零次保持窗口 — 抑制在此窗口内接收到的探针（毫秒）。 |
rate/websocket/drop_warning_threshold | int | — | 在发出警告之前，窗口内被拖放的命令数量。 |
rate/websocket/drop_warning_window_ms | int | — | 用于统计丢失命令的滑动窗口大小（毫秒）。 |
rate/websocket/tick_on_empty_batch | bool | 上级 | 即使整个 WebSocket 批次都被丢弃，main_loop 安排该任务。 |
session/commands/zoh_window_ms (不建议) | int | — | 相反 rate/websocket/zoh_window_ms 请使用该功能。读写操作将以透明方式进行转发。 |
session/commands/drop_warning_threshold (不建议) | int | — | 相反 rate/websocket/drop_warning_threshold 请使用该功能。读写操作将以透明方式进行转发。 |
session/commands/drop_warning_window_ms (不建议) | int | — | 相反 rate/websocket/drop_warning_window_ms 请使用该功能。读写操作将以透明方式进行转发。 |
session/commands/tick_on_empty_batch (不建议) | bool | — | 相反 rate/websocket/tick_on_empty_batch 请使用该功能。读写操作将以透明方式进行转发。 |
内部专用设置
在 3.5.1 中，有几个设置组 hidden 作为……提供，并被保留用于内部使用 — rate/dispatch/*（AIMD 的发送速率上限和背压阈值），session/freeform/*（行为指纹识别），以及 session/serialization/preview/*（如欧拉四元数输出和 Wireless VerseGrip 路由等预发布版的序列化实验）。这些是用于调试的 misc/hidden_settings 虽然目前可以通过该方式访问，但在后续的小版本更新中，这些内容可能会被提升、更名或删除。请勿将客户端的行为依赖于这些内容。