参见设置
本文是 /settings/ 端点返回的所有设置 键, 类型(type_hint 标准), 约束条件(metadata.constraint.range 以及(如适用) locked 与(标准)一起列出。
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 路由返回的有效配置键(API 参考文档 (参见)。未指定的键将使用服务的默认值。
例如,网络配置的重新定义如下:
{
"communication/http/port": 8400,
"communication/websocket/port": 8500,
"communication/events/port": 9000,
"communication/bind_all_interfaces": true
}
类型映射
API 返回的类型提示映射到以下 JSON 格式:
STRING→stringBOOL→boolINT→intFLOAT→floatARR_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 | 启动时 | 代替 localhost 0.0.0.0将其绑定到服务器上。 |
communication/http/port | int | 启动时 | HTTP REST API 端口(默认值 10000)是。 |
communication/websocket/port | int | 启动时 | 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(如蒙特变换(mount transform)、基等)。 |
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/…
“抓取钩”功能为自动运行。在将抓取钩竖直握持期间,光标将保持静止。
| 键 | 类型 | 约束条件 | 说明 |
|---|---|---|---|
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 | — | 这是该速度区间内的最大导航速度(m/s)。 |
features/navigation/bubble/velocity_zone_width | float | — | 这是气泡表面外侧速度区域的宽度(米)。 |
features/navigation/bubble/reset_velocity_on_entry | bool | — | 当光标进入气泡时,将速度重置为0。 |
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/…
这是带符号距离场(Signed-distance-field)触觉效果模块(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 | — | 当施加的力接近0时,会自动探测SDF场。 |
features/sdf/probe_on_zero_force/delay | float | 范围 0.001–60.0 | 这是能量降至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 | — | 在序列化输出中,与恒等默认值相同的 transform 字段(例如: position: {0,0,0}, rotation: {w:1,…})也包含在内。当客户端需要显式指定所有字段时,此选项非常有用。默认值: false. |
serialization/force_complete_transforms | bool | — | 包括仅输出方向的设备(Verse Grip、Wireless Verse Grip)在内的所有变换输出中 position, rotation, 还有 scale始终包含。否则,这些设备 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。 |