版本：3.5.x

设置参考

本文档列出了由 /settings/ 端点与他们的键, 类型（摘自 type_hint)，以及限制（摘自 metadata.constraint.range + locked （如适用）。

A 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 路由（参见应用程序接口参考). 未指定的键将使用服务的默认值。

例如，网络配置覆盖：

{
  "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`	启动	Main 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设备。按会话设置的覆盖项具有优先级。

关键	类型	制约因素	说明
`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`	—	按设备类型设置的默认设备配置预设（挂载转换、基底等，用于 `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 该行为首先被激活。

关键	类型	制约因素	说明
`features/navigation/bubble/center`	`vec3`	—	气泡默认中心位置。
`features/navigation/bubble/max_velocity`	`float`	—	速度区域内的最大航行速度（米/秒）。
`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/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 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 配对界面提供支持。

关键	类型	制约因素	说明
`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`	—	预约 `main_loop` 即使整个 WebSocket 批次丢失，计数器仍会继续计数。

配置​

类型映射​

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/…​

配置