设置参考
本文档列出了端点所使用的所有设置 /settings/ 将被退回，连同其 Schlüssel, 她的 Typ （摘自 type_hint) 以及她们的 限制 （摘自 metadata.constraint.range + locked（如适用）。
Eine 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 对象，该映射将设置键映射到覆盖值。键必须是有效的设置键，且由 HTTP 路由 /settings/ 将被退回（参见 API 参考). 对于未指定的每个键，将使用该服务的默认值。
例如，覆盖网络配置：
{
"communication/http/port": 8400,
"communication/websocket/port": 8500,
"communication/events/port": 9000,
"communication/bind_all_interfaces": true
}
可见性与过滤
列表端点 /settings (GET /settings, GET /settings/) 默认情况下仅提供 基础- 恢复设置。请输入 ?advanced=true, 包含标记为“高级”的设置，以及 ?deprecated=true，以包含过时的别名。隐藏设置仅供内部使用；只有当 misc/hidden_settings über POST /settings/misc/hidden_settings 将被设置（对此没有查询参数）。过滤标志将通过“AND”进行组合——一个同时满足 advanced 以及 hidden 标记为“已选中”的操作需要两个已打开的网关。针对已知密钥的 POST 和 DELETE 操作不受网关限制。
对单个键的读取操作（GET /settings/<key>) 如果您使用精确的规范密钥，即可绕过“高级/已弃用”检查——这对具备先验知识的客户端非常有用。隐藏密钥仍将被锁定。
三个运行时间开关用于初始化门；其值在服务整个生命周期内保持不变：
| Schlüssel | Typ | 限制 | 描述 |
|---|---|---|---|
misc/advanced_settings | bool | — | Als advanced 已标记的设置在 GET /settings-启用收听（默认） false). 相当于传递 ?advanced=true 每次查询时。 |
misc/deprecated_settings | bool | — | Als deprecated 已标记的设置在 GET /settings-启用收听（默认） false). 相当于传递 ?deprecated=true 每次查询时。 |
类型映射
API 返回的类型提示将映射到以下 JSON 结构中：
STRING→stringBOOL→boolINT→intFLOAT→floatARR_STRING→string[]VEC3→vec3(对象带有{x, y, z})GENERIC→json（任意结构化值）
communication/…
HTTP、WebSocket 和 Event-Stream 服务器的网络端口和绑定地址。大多数条目仅在启动时生效。
| Schlüssel | Typ | 限制 | 描述 |
|---|---|---|---|
communication/serial/enabled | bool | — | 启用或禁用串行设备通信。 |
communication/bind_address | string | 开始 | 服务器绑定到该IP地址以处理HTTP和WebSocket请求。 |
communication/bind_all_interfaces | bool | 开始 | 服务器 an 0.0.0.0 而不是绑定到 localhost。 |
communication/http/port | int | 开始 | HTTP-REST-API-端口（标准 10000). |
communication/websocket/port | int | 开始 | WebSocket v3.1 的主端口（标准 10001). |
communication/websocket/legacy_port | int | 开始 | WebSocket v3.0 的兼容端口（标准 10000). |
communication/events/port | int | 开始 | WebSocket 事件流端口（标准 10020). |
devices/…
devices/detection/…
串行端口扫描指南。所有条目均标记为“扩展”。
| Schlüssel | Typ | 限制 | 描述 |
|---|---|---|---|
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 | 在再次记录识别错误之前所需的延迟时间（s）。 |
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 系列所有设备的全局默认值。会话级别的覆盖设置具有优先级。
在 3.5.1 中更名为
在 3.5.0 版本中，该模式如下： devices/inverse*/…; 领先的 * 现在面临 inverse. 3.5.1 版本不再正确导入采用旧写法配置的配置文件——请进行相应调整。除此之外，键本身保持不变。
| Schlüssel | Typ | 限制 | 描述 |
|---|---|---|---|
devices/*inverse/filters/force_scale/gain | float | 范围 0.0–2.0 | 适用于所有设备的全球功率输出乘数。 |
devices/*inverse/filters/force_gate/gain | float | 范围 0.0–1.0 | 新会话中Kraft-Gate的标准增益。 |
devices/*inverse/control_timeout_ms | int | 范围 50–10000 | 在解除设备控制锁定之前的时间超时（毫秒）。 |
devices/*inverse/query_orientation_on_idle | bool | — | 当设备处于空闲状态时，从固件中查询设备本体的朝向。 |
devices/*inverse/safeties/expose_in_snapshot | bool | — | 将每个设备的安全标志纳入 GET /devices/{id} 录制。 |
devices/presets
| Schlüssel | Typ | 限制 | 描述 |
|---|---|---|---|
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/…
| Schlüssel | Typ | 限制 | 描述 |
|---|---|---|---|
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对准的“一欧元滤镜”配置。 |
features/…
features/calibration/…
| Schlüssel | Typ | 限制 | 描述 |
|---|---|---|---|
features/calibration/hall_threshold | int | 范围 1–32 | 霍尔传感器电平，当校准时，当电平达到该值时，即视为插头已插入。 |
features/grip_hook/…
自动抓取钩行为——只要持续按住抓取键，光标就会被锁定。
| Schlüssel | Typ | 限制 | 描述 |
|---|---|---|---|
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-该行为首次被激活时。各字段的运行时语义请参见页面 导航模块.
| Schlüssel | Typ | 限制 | 描述 |
|---|---|---|---|
features/navigation/bubble/center | vec3 | — | 膀胱中心的标准位置。 |
features/navigation/bubble/center_enabled | bool | — | 已配置的 center 在首次启用气泡效果时应用。 |
features/navigation/bubble/rotation_enabled | bool | — | 将工作空间的旋转应用于导航方向。 |
features/navigation/bubble/scale_enabled | bool | — | 将工作区的标尺应用于导航速度。 |
features/navigation/bubble/center_drift_speed | float | ≥ 0 | 中心模式下的漂移速度（m/s） auto_follow. |
features/navigation/bubble/max_velocity | float | — | 该限速区域内的最高行驶速度（米/秒）。 |
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/navigation/bubble/stop_at_collision | bool | — | 防止在碰撞激活时，气泡中心沿碰撞方向漂移。 |
features/navigation/bubble/collision_threshold | float | > 0 | 检测到碰撞时的外力大小（N）。 |
features/navigation/bubble/collision_inflate_scale | float | ≥ 1 | 在碰撞活跃期间起作用的乘数，用于 velocity_zone_width 被应用。 |
features/navigation/bubble/collision_exit_ratio | float | 区间 (0,1] | 滞后比——当满足以下条件时退出碰撞 |ext_force| unter collision_threshold × this fällt。 1.0 禁用迟滞。 |
features/navigation/bubble/avatar_boundary_enabled | bool | — | 将阿凡达的世界坐标转换为配置好的SDF模型 avatar_boundary begrenzen。 |
features/safe_trajectory/…
末端执行器运动的速度限制器。
| Schlüssel | Typ | 限制 | 描述 |
|---|---|---|---|
features/safe_trajectory/enabled | bool | — | 启用速度限制器以确保行驶轨迹安全。 |
features/safe_trajectory/max_vel | float | 范围 0.01–2.0 | 末端执行器最大允许速度（m/s）。 |
features/screensaver/…
当没有会话控制时，在Inverse3 设备上播放的空闲动画。
| Schlüssel | Typ | 限制 | 描述 |
|---|---|---|---|
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）的触觉效果模块。
| Schlüssel | Typ | 限制 | 描述 |
|---|---|---|---|
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耦合界面的基础。
| Schlüssel | Typ | 限制 | 描述 |
|---|---|---|---|
features/verse_grip_pairing/enabled | bool | — | 启用连接功能以及安装和拆卸的检测。 |
features/verse_grip_pairing/hall_threshold_vg | int | 范围 1–32 | Hall-Pegel，从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 设置并绕过霍尔传感器（硬件故障时的解决方法）。 |
session/serialization/…
Transform 输出的格式化——涉及 WebSocket 和 HTTP JSON 的有效载荷。这些键在 3.5.1 版本中由 serialization/* nach session/serialization/* 已重定位，以反映其与会话相关的作用域。旧路径将继续通过过时的别名进行解析。
| Schlüssel | Typ | 限制 | 描述 |
|---|---|---|---|
session/serialization/explicit_fields | bool | — | 将符合身份默认值的Transform-Felder包含在序列化输出中（例如： position: {0,0,0}, rotation: {w:1,…}). 当您的客户端要求每个字段都必须明确存在时，此功能非常有用。默认值： false. |
session/serialization/force_complete_transforms | bool | — | Immer position, rotation und scale 在每次 Transform 输出中都显示，即使对于仅能检测方向的设备（Verse Grip、Wireless Verse Grip）也是如此，此外仅 rotation 输出。关闭 session/serialization/explicit_fields ein. 标准： false. |
serialization/explicit_fields （过时） | bool | — | 请改用 session/serialization/explicit_fields. 读写操作将透明地转发到规范键上。 |
serialization/force_complete_transforms （过时） | bool | — | 请改用 session/serialization/force_complete_transforms. 读写操作将透明地转发到规范键上。 |
session/…
会话调度器。
| Schlüssel | Typ | 限制 | 描述 |
|---|---|---|---|
session/min_simulation_rate_hz | int | 范围 20–500 | 在触发警报之前，设备模拟速率的最低可接受值（Hz）。 |
rate/…
服务节拍。在3.5.1节中引入——下文列出的四项 rate/websocket/*-钥匙之前放在 session/commands/*; 旧路径将继续通过过时的别名进行解析。
| Schlüssel | Typ | 限制 | 描述 |
|---|---|---|---|
rate/websocket/zoh_window_ms | int | — | 零阶保持窗口——在此窗口内接收到的探针信号将被抑制（毫秒）。 |
rate/websocket/drop_warning_threshold | int | — | 在触发警告之前，该窗口内被丢弃的命令数量。 |
rate/websocket/drop_warning_window_ms | int | — | 用于统计被丢弃指令的滑动窗口大小（毫秒）。 |
rate/websocket/tick_on_empty_batch | bool | 高级 | Einen main_loop-即使整个 WebSocket 批次被丢弃，也要安排该操作。 |
session/commands/zoh_window_ms （过时） | int | — | 请改用 rate/websocket/zoh_window_ms. 读写访问会被透明地转发。 |
session/commands/drop_warning_threshold （过时） | int | — | 请改用 rate/websocket/drop_warning_threshold. 读写访问会被透明地转发。 |
session/commands/drop_warning_window_ms （过时） | int | — | 请改用 rate/websocket/drop_warning_window_ms. 读写访问会被透明地转发。 |
session/commands/tick_on_empty_batch （过时） | bool | — | 请改用 rate/websocket/tick_on_empty_batch. 读写访问会被透明地转发。 |
仅供内部使用的设置
在 3.5.1 版中，多个设置组被定义为 hidden 已交付，仅供内部使用 — rate/dispatch/* (AIMD——发送速率上限和背压阈值)， session/freeform/* （行为指纹识别）以及 session/serialization/preview/* （发布前的序列化实验，例如欧拉四元数的输出以及无线 VerseGrip 的路由）。这些实验可通过 misc/hidden_settings 虽然目前可用，但预计它们会在以后的次要版本中被迁移、重命名或移除——请不要让您的客户端的行为依赖于它们。