设置参考
本文档列出了 /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 可包含标记为 advanced 的设置，传入 ?deprecated=true 可包含已弃用的别名。隐藏设置仅供内部使用；只有通过 POST /settings/misc/hidden_settings 设置 misc/hidden_settings 之后才会显示（没有对应的查询参数）。过滤条件之间为逻辑与（AND）关系，即同时标记为 advanced 和 hidden 该键需要同时启用两项限制。对已知键执行 POST 和 DELETE 操作不受上述限制。
使用精确的规范键进行单键读取（GET /settings/<key>）时，将绕过 advanced/deprecated 限制，适合已掌握相关知识的客户端。隐藏键仍受限制。
有三个运行时开关用于初始化这些限制，其值在服务的整个生命周期内始终有效：
| 键 | 类型 | 约束 | 描述 |
|---|---|---|---|
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 | 启动 | 将服务器绑定到 0.0.0.0 而不是 localhost。 |
communication/http/port | int | 启动 | HTTP REST API 端口（默认 10000）。 |
communication/websocket/port | int | 启动 | v3.1 主 WebSocket 端口（默认 10001）。 |
communication/websocket/legacy_port | int | 启动 | v3.0 旧版 WebSocket 端口（默认 10000）。 |
communication/events/port | int | 启动 | 事件流 WebSocket 端口（默认 10020）。 |
devices/…
devices/detection/…
串口扫描策略。所有条目均为高级设置（advanced）。
| 键 | 类型 | 约束 | 描述 |
|---|---|---|---|
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 版本中，通配符模式为 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 | — | 每种设备类型的默认设备配置预设（包括安装转换、basis 等，适用于 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 | — | 当握把保持直立时，启用 grip-hook 自动锁定功能。 |
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 导航模块的默认值，在首次激活时 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 | — | 在序列化输出中包含那些等于默认值的 transform 字段（例如 position: {0,0,0}、rotation: {w:1,…}）。当客户端要求每个字段都必须显式存在时，这非常有用。默认值：false。 |
session/serialization/force_complete_transforms | bool | — | 每个 transform 输出中始终包含 position、rotation 和 scale，包括仅提供姿态数据的设备（Verse Grip、Wireless Verse Grip），这些设备原本只输出 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 起引入——以下四个 rate/websocket/* 该键此前位于 session/commands/* 下；旧路径仍将通过已弃用的别名进行解析。
| 键 | 类型 | 约束 | 说明 |
|---|---|---|---|
rate/websocket/zoh_window_ms | int | — | 零阶保持（ZOH）窗口：抑制在此窗口内接收到的探测消息（毫秒）。 |
rate/websocket/drop_warning_threshold | int | — | 在触发警告之前，窗口内被丢弃的命令数量。 |
rate/websocket/drop_warning_window_ms | int | — | 用于统计被丢弃命令数量的滑动窗口大小（毫秒）。 |
rate/websocket/tick_on_empty_batch | bool | 高级 | 即使整个 WebSocket 批次被丢弃，也会调度一次 main_loop tick。 |
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 这些功能目前仅供调试之用，但请注意，它们可能会在后续的次要版本中转为正式设置、更名或移除——请勿让客户端的行为依赖于它们。