设置参考

本文档列出了 /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
}

类型映射

API 返回的类型提示对应以下 JSON 数据结构：

STRING → string
BOOL → bool
INT → int
FLOAT → float
ARR_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/…`

串口扫描策略。所有条目均为高级选项。

键	类型	约束	说明
`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 系列设备的全局默认值。会话级覆盖设置优先。

键	类型	约束	说明
`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/presets`

键	类型	约束	说明
`devices/presets`	`json`	—	各设备类型的默认配置预设（安装变换 mount transform、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 滤波器配置。

`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 导航模块的默认值，在首次激活 bubble 行为时传入会话。

键	类型	约束	说明
`features/navigation/bubble/center`	`vec3`	—	Bubble 中心的默认位置。
`features/navigation/bubble/max_velocity`	`float`	—	速度区内的最大导航速度（m/s）。
`features/navigation/bubble/velocity_zone_width`	`float`	—	Bubble 表面外侧速度区的宽度（m）。
`features/navigation/bubble/reset_velocity_on_entry`	`bool`	—	光标进入 Bubble 时将速度重置为零。
`features/navigation/bubble/spring_inner`	`float`	—	Bubble 中心处的弹簧系数（N/m）。
`features/navigation/bubble/spring_surface`	`float`	—	Bubble 表面处的弹簧系数（N/m）。
`features/navigation/bubble/spring_outer`	`float`	—	外边界处的弹簧系数（N/m）。
`features/navigation/bubble/damping_inner`	`float`	—	Bubble 中心处的阻尼系数（Ns/m）。
`features/navigation/bubble/damping_surface`	`float`	—	Bubble 表面处的阻尼系数（Ns/m）。
`features/navigation/bubble/damping_outer`	`float`	—	外边界处的阻尼系数（Ns/m）。
`features/navigation/bubble/wall_stiffness`	`float`	—	外边界处硬壁的刚度（N/m）。
`features/navigation/bubble/bump_width`	`float`	—	Bubble 表面触觉凸起的宽度（m）。
`features/navigation/bubble/bump_stiffness`	`float`	—	Bubble 表面触觉凸起的刚度（N/m）。

`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	力降至零后、自动探测前的延迟（秒）。

`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`，绕过霍尔传感器（用于应对硬件故障的变通方案）。

`serialization/…`

变换输出格式设置——影响 WebSocket 和 HTTP JSON 负载。

键	类型	约束	描述
`serialization/explicit_fields`	`bool`	—	在序列化输出中包含那些等于其恒等默认值的变换字段（例如 `position: {0,0,0}`、`rotation: {w:1,…}`）。当客户端要求每个字段都必须显式存在时很有用。默认值：`false`。
`serialization/force_complete_transforms`	`bool`	—	始终在每个变换输出中包含 `position`、`rotation` 和 `scale`，包括仅有方向信息的设备（Verse Grip、Wireless Verse Grip）——否则这些设备只输出 `rotation`。此设置涵盖 `serialization/explicit_fields` 的功能。默认值：`false`。

`session/…`

会话调度器与命令管线的限制。

键	类型	约束	描述
`session/min_simulation_rate_hz`	`int`	范围 20–500	设备仿真速率（Hz）的最低可接受值，低于该值时触发警告。
`session/commands/zoh_window_ms`	`int`	—	零阶保持窗口——抑制在此窗口内收到的探测（毫秒）。
`session/commands/drop_warning_threshold`	`int`	—	窗口内丢弃的命令数量达到此值时触发警告。
`session/commands/drop_warning_window_ms`	`int`	—	用于统计丢弃命令的滑动窗口大小（毫秒）。
`session/commands/tick_on_empty_batch`	`bool`	—	即使整个 WebSocket 批次被丢弃，也调度一次 `main_loop` tick。

配置​

类型映射​

communication/…​

devices/…​

devices/detection/…​

devices/inverse*/…​

devices/presets​

devices/wireless_verse_grip/…​

features/…​

features/calibration/…​

features/grip_hook/…​

features/navigation/bubble/…​

features/safe_trajectory/…​

features/screensaver/…​

features/sdf/…​

features/verse_grip_pairing/…​

serialization/…​

session/…​

配置