跳过至主要内容

设置参考

在本文档中,/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启动不是 localhost,而是 0.0.0.0 将服务器绑定到该地址。
communication/http/portint启动HTTP REST API 的端口(默认是 10000)。
communication/websocket/portint启动Main v3.1 WebSocket 端口(默认值为 10001)。
communication/websocket/legacy_portint启动Legacy 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 (如面向特定设备的安装适配器、basis 等)。

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 Filter 设置。

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 当操作首次被启用时,该参数将传递给会话。

键型制约说明
features/navigation/bubble/centervec3—气泡中心位置的默认值。
features/navigation/bubble/max_velocityfloat—速度区域内的最大导航速度(m/s)。
features/navigation/bubble/velocity_zone_widthfloat—气泡表面外侧速度带的宽度(米)。
features/navigation/bubble/reset_velocity_on_entrybool—当光标进入气泡时,将速度重置为零。
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—气泡表面触觉凸起的宽度(米)。
features/navigation/bubble/bump_stiffnessfloat—气泡表面触觉凸起的刚度(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这是从力降至零到开始自动探针检测之间的延迟时间(s)。

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—在序列化后的输出中包含一个与单位元(identity)默认值相等的变换字段(例如: position: {0,0,0}、rotation: {w:1,…})。当客户端要求显式指定所有字段时,此选项非常有用。默认值: false。
serialization/force_complete_transformsbool—包括仅处理方向的设备(Verse Grip、Wireless Verse Grip)在内,所有变换输出中 position、rotation、以及 scale 始终输出。通常情况下 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 安排该任务。