设置参考
在本文档中,/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 | 启动 | 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 (如面向特定设备的安装适配器、basis 等)。 |
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 | — | 当光标进入气泡时,将速度重置为零。 |
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)的触觉效果模块(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 | 这是从力降至零到开始自动探针检测之间的延迟时间(s)。 |
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 | — | 在序列化后的输出中包含一个与单位元(identity)默认值相等的变换字段(例如: 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 安排该任务。 |