设置参考
本文档列出 /settings/ 端点返回的所有设置，以及每项设置的 键、类型（来自 type_hint）和 约束（来自 metadata.constraint.range，并在适用时结合 locked）。
locked 设置在运行时为 只读。可以通过配置文件或 Haply Hub 设置页面进行更改，但更改生效需要 完整重启服务。下方表格中这些设置标记为 boot。
配置
用于在服务启动时覆盖设置的配置文件位于以下位置：
| 平台 | 位置 |
|---|---|
| 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 和事件流服务器的网络端口与绑定地址。大多数条目仅适用于 boot（需重启服务后生效）。
| 键 | 类型 | 约束 | 描述 |
|---|---|---|---|
communication/serial/enabled | bool | — | 启用或禁用串口设备通信。 |
communication/bind_address | string | boot | HTTP 和 WebSocket 服务器绑定的 IP 地址。 |
communication/bind_all_interfaces | bool | boot | 将服务器绑定到 0.0.0.0 而非 localhost。 |
communication/http/port | int | boot | HTTP REST API 端口（默认 10000）。 |
communication/websocket/port | int | boot | v3.1 主 WebSocket 端口（默认 10001）。 |
communication/websocket/legacy_port | int | boot | v3.0 旧版 WebSocket 端口（默认 10000）。 |
communication/events/port | int | boot | 事件流 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/…
自动 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 | — | 气泡表面外侧速度区的宽度（m）。 |
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 | — | 气泡表面触觉凸起的宽度（m）。 |
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 | 确认分离前的防抖时间窗口（ms）。 |
features/verse_grip_pairing/heartbeat_ms | int | 范围 100–10000 | 强制重新通知之间的间隔（ms）。 |
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）窗口：抑制此窗口内收到的探测消息（ms）。 |
rate/websocket/drop_warning_threshold | int | — | 触发警告前，窗口内被丢弃命令的数量。 |
rate/websocket/drop_warning_window_ms | int | — | 用于统计被丢弃命令数量的滑动窗口大小（ms）。 |
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 访问以便调试，但请预计它们会在后续的次要版本中被转为正式设置、重命名或移除——请勿让客户端行为依赖于它们。