跳至主要内容

设置参考

本文档列出了 /settings/ 端点返回的所有设置,以及每个设置的 键、类型(来源: type_hint)和 约束(来源: metadata.constraint.range,以及在适用时 locked)。

locked 在运行时设置为只读。可通过配置文件或 Haply Hub 在“设置”页面进行修改,但更改需完全重启服务。下表中这些设置标注为 启动。

配置​

用于在服务启动时覆盖设置的配置文件位于以下位置:

平台位置
WindowsC:\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/enabledbool—启用或禁用串口设备通信。
communication/bind_addressstring仅在启动时HTTP 和 WebSocket 服务器所绑定的 IP 地址。
communication/bind_all_interfacesbool仅在启动时将服务器绑定到 0.0.0.0 而不是 localhost。
communication/http/portint仅在启动时HTTP REST API 端口(默认 10000)。
communication/websocket/portint仅在启动时v3.1 主 WebSocket 端口(默认 10001)。
communication/websocket/legacy_portint仅在启动时v3.0 旧版 WebSocket 端口(默认 10000)。
communication/events/portint仅在启动时事件流 WebSocket 端口(默认 10020)。

devices/…​

devices/detection/…​

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

键类型约束说明
devices/detection/scan_period_msint范围 100–10000;仅在启动时串口扫描之间的间隔(毫秒)。
devices/detection/handshake_timeout_sint范围 1–15每个端口的握手超时时间(秒)。
devices/detection/max_retriesint范围 1–10每个端口的最大握手重试次数。
devices/detection/failure_log_delay_sint范围 1–60在重新记录检测失败日志之前延迟(秒)。
devices/detection/block_looping_portsbool—检测到循环端口时,阻止设备进入就绪状态。
devices/detection/excluded_portsjson—检测时需要跳过的串口路径。
devices/detection/additional_portsstring[]—无条件扫描的额外串口路径。
devices/detection/allowed_vendor_id_filterstring[]—端口枚举时允许的 USB 制造商 ID。
devices/detection/port_name_substring_filterstring[]—用于匹配的、因平台而异的端口名称子字符串。
devices/detection/wireless_verse_grip_description_filterstring[]—用于无线 VerseGrip 检测的端口描述符字符串。
devices/detection/inverse3x_description_filterstring[]—用于 Inverse3x 检测的端口描述符字符串。
devices/detection/extra_ports (已弃用)string[]—请改用 devices/detection/additional_ports。读写操作将透明地转发至规范键。

devices/inverse*/…​

适用于每台Inverse3 系列设备的全局默认值。会话级覆盖设置具有优先级。

键类型约束说明
devices/inverse*/filters/force_scale/gainfloat范围 0.0–2.0适用于所有设备的全局力输出倍率。
devices/inverse*/filters/force_gate/gainfloat范围 0.0–1.0新会话的默认门控增益。
devices/inverse*/control_timeout_msint范围 50–10000释放设备控制锁之前的超时时间(毫秒)。
devices/inverse*/query_orientation_on_idlebool—当设备空闲时,从固件中查询本体姿态。

devices/presets​

键类型约束说明
devices/presetsjson—各类设备的默认配置预设(安装转换、基函数等),涵盖 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_thresholdint—当电量低于该百分比时,将触发低电量警告。
devices/wireless_verse_grip/battery/critical_thresholdint—当电量低于该百分比时,将触发电量严重不足警报。
devices/wireless_verse_grip/battery/reset_marginint—清除电量警告前的滞后余量。
devices/wireless_verse_grip/filters/orientation_filterjson仅在启动时采用无线 VerseGrip 姿态的 One Euro 滤波器配置。

features/…​

features/calibration/…​

键类型约束说明
features/calibration/hall_thresholdint范围 1–32在校准期间,当霍尔传感器达到该电平时,即判定笔已安装到位。

features/grip_hook/…​

自动握持钩行为——当握把保持直立时锁定光标。

键类型约束说明
features/grip_hook/enabledbool—当握把保持直立时,启用握持钩自动锁定功能。
features/grip_hook/use_hallbool—握持检测改用霍尔传感器的阈值,而非姿态。
features/grip_hook/hallint范围 1–32触发握持锁定的霍尔传感器数值阈值。
features/grip_hook/hold_durationint范围 10–1000触发后保持锁定的时长(毫秒)。

features/navigation/bubble/…​

Bubble 导航模块的默认值,在首次激活时 bubble 执行该操作时,会将会话传入。

键类型约束说明
features/navigation/bubble/centervec3—Bubble 中心的默认位置。
features/navigation/bubble/max_velocityfloat—速度区域内的最大导航速度(m/s)。
features/navigation/bubble/velocity_zone_widthfloat—气泡表面外侧速度区的宽度(米)。
features/navigation/bubble/reset_velocity_on_entrybool—当光标进入 Bubble 时,将其速度重置为零。
features/navigation/bubble/spring_innerfloat—气泡中心处的弹簧系数(N/m)。
features/navigation/bubble/spring_surfacefloat—气泡表面的弹性系数(N/m)。
features/navigation/bubble/spring_outerfloat—外边界处的弹簧刚度(N/m)。
features/navigation/bubble/damping_innerfloat—气泡中心处的阻尼系数(Ns/m)。
features/navigation/bubble/damping_surfacefloat—气泡表面的阻尼系数(Ns/m)。
features/navigation/bubble/damping_outerfloat—外边界处的阻尼系数(Ns/m)。
features/navigation/bubble/wall_stiffnessfloat—外边界处硬壁的刚度(N/m)。
features/navigation/bubble/bump_widthfloat—Bubble 表面触觉凸起的宽度(米)。
features/navigation/bubble/bump_stiffnessfloat—Bubble 表面触觉凸起的刚度(N/m)。

features/safe_trajectory/…​

末端执行器的运动限速器。

键类型约束说明
features/safe_trajectory/enabledbool—启用安全轨迹限速器。
features/safe_trajectory/max_velfloat范围 0.01–2.0允许的最大末端执行器速度(m/s)。

features/screensaver/…​

当会话未驱动设备时,在Inverse3 设备上播放的空闲动画。

键类型约束说明
features/screensaver/enabledbool—在Inverse3 设备上启用空闲屏保动画。
features/screensaver/speedfloat范围 0.001–0.2屏保动画速度。
features/screensaver/distracted_speedfloat范围 0.001–0.2用户靠近但未主动操作时的动画速度。

features/sdf/…​

符号距离场(SDF)触觉效果模块(SDF HFX)。

键类型约束描述
features/sdf/enabledbool—启用或禁用 SDF 触觉效果模块。
features/sdf/state_outputbool—默认情况下,设备输出负载中包含 SDF 状态。
features/sdf/max_countint范围 0–128同时激活的 SDF 效果数量上限(0 (表示不限)。
features/sdf/events/createdbool—在创建新的 SDF 效果时触发该事件。
features/sdf/events/deletedbool—删除 SDF 效果时触发的事件。
features/sdf/events/updatedbool—在更新 SDF 效果时触发该事件。
features/sdf/probe_on_zero_force/enabledbool—当施加的力接近零时,自动检测 SDF 场。
features/sdf/probe_on_zero_force/delayfloat范围 0.001–60.0力降至零后、自动检测前的延迟(秒)。

features/verse_grip_pairing/…​

Inverse3 跟踪与(有线或无线)Verse Grip 之间的连接/断开状态。支持Haply Hub 的配对界面。

键类型约束描述
features/verse_grip_pairing/enabledbool—启用配对 / 连接-断开跟踪。
features/verse_grip_pairing/hall_threshold_vgint范围 1–32当霍尔电平达到该值时,有线 VerseGrip 即被视为已连接。
features/verse_grip_pairing/hall_threshold_wvgint范围 1–32当霍尔电平达到该值时,即视为无线 VerseGrip 已连接。
features/verse_grip_pairing/detach_debounce_msint范围 0–1000确认断开连接前的去抖窗口(毫秒)。
features/verse_grip_pairing/heartbeat_msint范围 100–10000强制重新通知之间的间隔(毫秒)。
features/verse_grip_pairing/force_attachedbool—将已连接状态永久强制设置为 true,绕过霍尔传感器(这是应对硬件故障的一种变通方案)。

serialization/…​

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

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

session/…​

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

键类型约束描述
session/min_simulation_rate_hzint范围 20–500设备仿真速率(Hz)的最低可接受值,低于该值时将触发警告。
session/commands/zoh_window_msint—零阶保持窗口——抑制在此窗口内接收到的探测(毫秒)。
session/commands/drop_warning_thresholdint—当窗口内被丢弃的命令数量达到此值时,将触发警告。
session/commands/drop_warning_window_msint—用于统计被丢弃命令的滑动窗口大小(毫秒)。
session/commands/tick_on_empty_batchbool—即使整个 WebSocket 批次被丢弃,也会调度一次 main_loop tick。