参数参考
本文档列出了该端点返回的所有参数 /settings/ 与他们的 clé, 他们的 类型 (来源: type_hint) 及其 约束条件 (来源: metadata.constraint.range + locked(如有必要)。
一个参数 locked est 仅在执行时读取. 可以通过配置文件或从 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 和事件流服务器的网络端口及监听地址。大多数条目仅可在启动时修改。
| Clé | 类型 | 约束条件 | 说明 |
|---|---|---|---|
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 | 启动 | REST HTTP API 端口(默认 10000). |
communication/websocket/port | int | 启动 | 3.1 版本的 WebSocket 主端口(默认) 10001). |
communication/websocket/legacy_port | int | 启动 | 从 3.0 版本继承的 WebSocket 端口(默认 10000). |
communication/events/port | int | 启动 | 事件流的 WebSocket 端口(默认 10020). |
devices/…
devices/detection/…
串行端口扫描策略。所有条目均为高级级别。
| Clé | 类型 | 约束条件 | 说明 |
|---|---|---|---|
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 | — | 在检测过程中应忽略“Chemins des ports”系列。 |
devices/detection/additional_ports | string[] | — | 需要系统性扫描的其他串行端口路径。 |
devices/detection/allowed_vendor_id_filter | string[] | — | 在端口枚举过程中允许的 USB 供应商标识符。 |
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 系列中每台设备的全局默认值。各会话的特定替换设置具有更高优先级。
| Clé | 类型 | 约束条件 | 说明 |
|---|---|---|---|
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
| Clé | 类型 | 约束条件 | 说明 |
|---|---|---|---|
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/…
| Clé | 类型 | 约束条件 | 说明 |
|---|---|---|---|
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/…
| Clé | 类型 | 约束条件 | 说明 |
|---|---|---|---|
features/calibration/hall_threshold | int | 第1–32页 | 在校准过程中,霍尔效应传感器达到该电平时,即视为触笔已连接。 |
features/grip_hook/…
抓钩的自动行为:当手柄垂直握持时,会锁定滑块。
| Clé | 类型 | 约束条件 | 说明 |
|---|---|---|---|
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.
| Clé | 类型 | 约束条件 | 说明 |
|---|---|---|---|
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/…
末端执行器运动的速度限制器。
| Clé | 类型 | 约束条件 | 说明 |
|---|---|---|---|
features/safe_trajectory/enabled | bool | — | 启用安全行驶速度限制器。 |
features/safe_trajectory/max_vel | float | 范围 0.01–2.0 | 末端执行器的最大允许速度(米/秒)。 |
features/screensaver/…
当Inverse3 设备没有会话控制时,会显示的空闲动画。
| Clé | 类型 | 约束条件 | 说明 |
|---|---|---|---|
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)。
| Clé | 类型 | 约束条件 | 说明 |
|---|---|---|---|
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 Hub的配对接口供电。
| Clé | 类型 | 约束条件 | 说明 |
|---|---|---|---|
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 有效载荷。
| Clé | 类型 | 约束条件 | 说明 |
|---|---|---|---|
serialization/explicit_fields | bool | — | 将值等于默认恒等值的转换字段包含在序列化输出中(例如 position: {0,0,0}, rotation: {w:1,…}). 当您的客户要求每个字段都必须明确存在时,此选项非常有用。默认值: false. |
serialization/force_complete_transforms | bool | — | 始终发送 position, rotation et scale 在每个转换输出端,包括仅支持方向控制的设备(Verse Grip、Wireless Verse Grip),这些设备通常仅输出 rotation. Englobe简体中文(大陆) serialization/explicit_fields. 默认值: false. |
session/…
会话计划程序和命令处理管道的限制。
| Clé | 类型 | 约束条件 | 说明 |
|---|---|---|---|
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 数据包已被拒绝。 |