参数参考
本文档列出了该端点返回的所有参数 /settings/，以及他们的 clé, 他们的 类型 （摘自 type_hint) 及其 约束条件 （摘自 metadata.constraint.range et de 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
}
可见性与筛选
列表的终结点 /settings (GET /settings, GET /settings/) 仅返回参数 基础 默认。转发 ?advanced=true 以包含标记为“高级”的参数，并且 ?deprecated=true 以包含已弃用的别名。隐藏参数仅供内部使用；它们仅在以下情况下才会显示： misc/hidden_settings 通过以下方式定义： POST /settings/misc/hidden_settings （不存在相应的查询参数）。过滤条件通过逻辑“与”进行组合：每次仅指定一个键 advanced et hidden 要求同时解除这两个过滤器。针对已知键的 POST 和 DELETE 请求不受这些过滤器限制。
单次读取（GET /settings/<key>) 当您使用精确规范键时，这些键会绕过“advanced/deprecated”过滤器，这对已经知道该键的客户端来说非常方便。而隐藏键仍需经过该过滤器。
三个执行开关为过滤器提供数据；其值在服务生命周期内始终保持不变：
| Clé | 类型 | 约束条件 | 说明 |
|---|---|---|---|
misc/advanced_settings | bool | — | 包括已报告的参数 advanced 在列表中 GET /settings （默认值： false). 相当于传达 ?advanced=true 每次请求时。 |
misc/deprecated_settings | bool | — | 包括已报告的参数 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 和事件流服务器的网络端口及连接地址。大多数条目仅可在系统启动时修改。
| 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 API 的 HTTP 端口（默认值： 10000). |
communication/websocket/port | int | 启动 | v3.1 的 WebSocket 主端口（默认值： 10001). |
communication/websocket/legacy_port | int | 启动 | v3.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 系列中每台设备的全局默认值。会话特定的覆盖设置具有更高优先级。
在 3.5.1 版本中重命名
地球是 devices/inverse*/… 在 3.5.0 版本中；该 * “se”现在放在前面 inverse. 在 3.5.1 版本中，使用旧式字面量语法的配置文件将不予支持——请更新这些文件。此外，配置键本身保持不变。
| 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/*inverse/safeties/expose_in_snapshot | bool | — | 将各设备特有的安全指标纳入快照 GET /devices/{id}. |
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 导航模块的默认值——在行为触发时传递给会话 bubble 首次启用。请参阅该页面 导航模块 用于每个字段的运行时语义。
| Clé | 类型 | 约束条件 | 说明 |
|---|---|---|---|
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 | — | 限速区域内的最大航行速度（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/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| descend sous简体中文（大陆） collision_threshold × this. 1.0 禁用迟滞。 |
features/navigation/bubble/avatar_boundary_enabled | bool | — | 将化身的全球位置限制为SDF形式 avatar_boundary 已配置。 |
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，绕过霍尔效应传感器（这是硬件故障时的临时解决方案）。 |
session/serialization/…
转换输出的格式设置——影响 WebSocket 和 HTTP JSON 有效载荷。这些键已从 serialization/* vers session/serialization/* 在 3.5.1 版本中进行了调整，以反映其按会话的适用范围。旧路径仍可通过已弃用的别名正常使用。
| Clé | 类型 | 约束条件 | 说明 |
|---|---|---|---|
session/serialization/explicit_fields | bool | — | 在序列化输出中包含那些等于其默认标识值的转换字段（例如： position: {0,0,0}, rotation: {w:1,…}). 当您的客户端要求每个字段都必须明确存在时，此选项非常有用。默认值： false. |
session/serialization/force_complete_transforms | bool | — | 始终发送 position, rotation et scale 在每个转换输出端，包括仅支持单向操作的设备（Verse Grip、Wireless Verse Grip），这些设备通常仅输出 rotation. 包括 session/serialization/explicit_fields. 默认值： false. |
serialization/explicit_fields (贬值) | bool | — | 请改用 session/serialization/explicit_fields. 读写操作会以透明的方式重定向到规范键。 |
serialization/force_complete_transforms (贬值) | bool | — | 请改用 session/serialization/force_complete_transforms. 读写操作会以透明的方式重定向到规范键。 |
session/…
会话调度器。
| Clé | 类型 | 约束条件 | 说明 |
|---|---|---|---|
session/min_simulation_rate_hz | int | 范围 20–500 | 设备在触发警报前可接受的最低模拟频率（Hz）。 |
rate/…
服务节奏。引入于 3.5.1 版本——四种节奏 rate/websocket/* 以下内容此前位于 session/commands/*; 旧路径仍可通过已弃用的别名正常运行。
| Clé | 类型 | 约束条件 | 说明 |
|---|---|---|---|
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 | avancé | 计划一个 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. 读写操作会以透明的方式进行重定向。 |
仅供内部使用的参数
已标记了多个参数类 hidden 在 3.5.1 版本中，这些功能仅供内部使用 —— rate/dispatch/* （AIMD发送流量上限和背压阈值）， session/freeform/* (行为特征) 和 session/serialization/preview/* （预发布版本中的序列化实验，例如欧拉四元数输出和 Wireless VerseGrip 路由）。可通过以下方式访问： misc/hidden_settings 这些参数仅用于调试目的，但请注意，它们可能会在未来的次要版本中被提升、重命名或删除——请勿将客户端的行为与这些参数绑定。