跳转至主要内容

v3.5.0

这是自一年前重写 API 以来最重要的版本。3.5.0 版本引入了统一的 3D 数学层、对 `Minverse` 的全面支持、类型化的事件流、完整的参数 API 以及更简洁的 HTTP 接口——此外，还包含过去一年中积累的 bug 修复和用户体验优化。

优势​

  • 统一的 3D 数学层——一个模块化变换管道，具备针对设备基坐标系（frame）、装配变换、工作空间变换和导航变换的原生基元，以及在局部空间、会话空间、应用程序空间和内部空间之间的显式转换。
  • 气泡导航——通过具有固定形状的区域（SDF 基本图形）在广阔的虚拟工作空间中穿行，支持基于速度的控制、考虑滞后效应的碰撞检测，以及可选的向光标偏移功能。可通过 HTTP 和 WebSocket 进行完全配置，并支持在应用程序空间内进行双向交互。
  • 类型化事件流——一个专用于设备生命周期、安全警报、校准、电池状态、检查频率提醒及过时提示的 WebSocket 事件通道。
  • 参数 API——一个功能齐全的键值参数系统，支持 HTTP CRUD 操作、类型提示、范围约束和描述，取代了旧版的嵌套配置文件。
  • 一致的设备配置 — 每台设备仅有一组 HTTP 路由： basis, mount, preset, transform, filters, handedness, torque_scaling, gravity_compensation, home_return.
  • Minverse 与触控笔的同步校准——设备及其触控笔现可同步校准；只要未实际安装手柄，校准状态将保持锁定。
  • HTTP 的人机工程学改进 — 按索引选择设备（无需标识符，仅通过索引定位设备），与 WebSocket 通用的统一请求和响应格式，封装层 {ok, error, data} 可激活的 (?format=json) 以及通配符会话选择器。

新功能​

设备​

  • Minverse — 此版本中包含的官方支持功能：检测、启动流程、安全通知以及同步校准流程。
  • Ruko和Kingfisher被公认为官方手柄类型。
  • 设备模拟器的支持——在与真实硬件并行运行的同时，检测由软件模拟的设备并与之通信。
  • 防止连接循环 — 行为异常的端口会被自动封锁；请使用以下命令重置它们： POST /ports/{port}/reset.
  • 笔尖固定状态信号——可靠检测笔柄的安装与拔出，并具有防反弹功能。

会话、命令和 WebSocket​

  • 会话配置文件的筛选与持久化——会话会声明一个配置文件名称和所需的 SDK 版本，服务会在两次重新连接之间记住这些信息；客户端和监控工具可以根据该配置文件对会话进行筛选和定位。
  • 按会话分批处理命令——一个运行缓慢的会话不再会阻塞另一个会话。
  • 词典 configure 明确适用于单次订单 — basis, preset, mount, force_gate, damping 按设备计算，以及 profile et basis 按会话分类，现已全部汇总到 configure. 该词典与输出词典保持一致，因此您发送的内容在回读时将完全一致。
  • 可自定义的设备组装 — 选择一个内置的工作区预设（defaults, arm_front, arm_front_centered, led_front, led_front_centered) 或发送一个显式转换；对剪辑进行任何手动修改都会自动将预设切换为 custom.
  • 命名控制字段 — position, vector, angles et torques 替换通用表格 values.
  • set_angular_torques 替换 set_angular_torque （单数形式已过时）。
  • 会话帧扩展 — v3.0 和 v3.1 会话帧现在可传输可扩展对象 config, state et status; 新增的输出字段包括 current_cursor_force, current_cursor_position, current_angular_torques, current_angular_position, control_domain, control_mode, transform, transform_velocity, 田野 config.* 丰富了并 status.safety （默认隐藏）。
  • 变换的部分更新 — 请仅发送需要修改的子字段（position, rotation, scale) 用于剪辑、工作空间的调整以及导航方式。

超文本传输协定​

  • GET / — 服务版本。
  • GET/POST/DELETE /settings et /settings/* — 完整的键值对参数 API。
  • GET /sessions/{session} et GET/POST/DELETE /sessions/{session}/profile.
  • GET /devices?session=<selector> — 将设备坐标转换为给定会话的应用空间。
  • 按索引分类的设备选择器 — 只需用食指指向任意设备，无需知道其标识符（/inverse3/0/... 关于第一篇Inverse3 ； /inverse*/*/... （适用于 Inverse 系列的所有设备）。
  • 统一的请求和响应结构 — POST/GET 请求体使用相同的结构 command_data 无论是 JSON 还是 WebSocket，为一种传输方式编写的代码都能在另一种传输方式上运行。
  • 可激活信封 来源： ?format=json 在任何道路上； /settings* et GET /home_return utilisent {ok, error, data} 默认情况下。请使用 ?format=plain 以获得原始结构。
  • 会话选择器的通配符 — * (任何片段) 和 ? （仅一个字符）出现在个人资料名称中。
  • 选择器的百分比解析 — %2A, %3A, 等在路由之前会被解码。

活动​

  • 专用的 WebSocket 事件流，位于 communication/events/port.
  • 24类典型事件，包括设备生命周期、安全（电子制动、异物检测、锁死）、校准失败、电池警报、会话警告、检查频率过低或处于临界状态、输入验证以及贬值提示。

可观测性​

  • 已将日志消息转发给Tracy，并在分析时根据严重级别进行了颜色标注。
  • 每个HTTP管理器上的Tracy区域。
  • 主循环的时间统计事件。
  • 可配置日志目录和服务器主机名（兼容 Docker）。

3.6 版本即将推出​

  • SDF 触觉效果（SDF HFX）——其基础架构已在 3.5 版中就绪（包括模块、生命周期以及模块提供的命令和状态序列化），公共 API 将在 3.6 版中随附完整的文档一并发布。

改进​

  • 力振荡滤波——按轴检测振荡、8步渐进恢复、带滞后效应的输入投票以及非对称释放窗口。
  • 运行时强制门过滤器 — 可通过 configure.force_gate.gain 通过 WebSocket 或 HTTP，并采用持久化默认值。
  • 为主循环的最大频率提升至32kHz，以满足高精度应用的需求。
  • WebSocket 有效负载减少 — 默认值为恒等变换的子字段（position = 0, rotation = identity, scale = 1) 在默认输出中被省略，这既缩小了有效载荷的大小，又恢复了与旧版 Unity 数据包“每条消息 4 KB”限制的兼容性。两个高级参数（serialization/explicit_fields, serialization/force_complete_transforms) 为有需要的消费者恢复所有字段。
  • 主循环代码已简化——在解析 JSON 和进行网络传输期间，WebSocket 消息的处理不再阻塞主循环；会话循环的调度已被安排在响应序列化之前。
  • 服务器默认仅限于 localhost — 使用该参数启用网络访问 communication/bind_all_interfaces.
  • 设备选择器的通配符采用前缀语法 （例如： inverse* 适用于 Inverse 系列的所有设备）。
  • 减震控制 已在词典中进行了调整 configure, 紧邻 force_gate.
  • 一种新的轮换文件日志系统取代了旧系统，并配备了一个可配置的目录。
  • 模块提供的命令和状态— 模块可以在不修改基础模式的情况下，将自身的命令、配置字段和状态输出注入到 WebSocket 帧中。

更正​

过去一年中修复了诸多漏洞；以下列出了其中最重要的几项。

  • 在某些情况下，会话速度不稳定。
  • 当没有模拟正在运行时，GripHook（Verse Grip Stopper）无法正确释放。
  • Inverse3 的超时设置过于严格，导致启动较慢的设备出现断连循环。
  • Windows 系统上服务未正常停止——停止服务时，HTTP 服务器并非总能被彻底清理。
  • 当服务向旧版本固件发送不支持的命令时，会触发重新连接循环。
  • 在配备蓝牙适配器的系统上，蓝牙设备的枚举会占用日志空间。
  • 当服务连续多次重启时发生死机。
  • 在 Ubuntu 笔记本电脑上，无线适配器 Verse Grip在进入待机状态并恢复后无法正常工作。
  • 在 Linux 和 macOS 系统上，当首次检测尝试失败时，Verse Grip 的无线连接流程现在会正确切换到备用方法。
  • macOS 系统中配置文件的位置 — 配置现已保存至 ~/Library/Application Support/ 而不是以前那条错误的路。
  • Linux 和 macOS 上的 SIGSEGV 信号处理——当启用多线程崩溃捕获时，进程不再因致命信号而陷入循环。
  • 会话间配置命令覆盖问题——一个会话的配置命令可能会被另一个会话的配置命令悄无声息地覆盖；现在这些命令会经过过滤并正确合并。
  • 探头命令会覆盖配置 — 监控会话（例如：Haply Hub）会发送 probe_position 不再悄无声息地覆盖待处理的基础、预设或配置文件中的更改。
  • 原型把手显示问题——原型硬件被错误地显示为标准把手，而非定制把手。
  • 继承矩阵约定 set_basis 对于尚未完成迁移的客户，该功能现已恢复支持。
  • Inverse3在断开会话时施加的冲击力不再产生残余力峰值。
  • 在快速连接和断开循环过程中，WebSocket 连接丢失时的运行条件。
  • WebSocket session_id 曾连载于 0 在某些出站有效载荷中。
  • 在 Windows 上， --log-level 现在，当与……结合使用时，该规则已得到遵守 --dev （此前，它会被默默地重置为 debug).

过时项​

目前仍可正常使用，但将在未来的一个主要版本中被移除。答案包含一个字段 deprecation_warning 在适当的情况下。

过时替换
POST /force_scalePOST /settings/devices/inverse*/filters/force_scale/gain
POST /gravity_compensationPOST /{device}/{id}/config/gravity_compensation
POST /torque_scalingPOST /{device}/{id}/config/torque_scaling
POST /device_handednessPOST /{device}/{id}/config/handedness
POST /serial_enablePOST /settings/communication/serial/enabled
POST /experimental/features/grip_dropped_simulation_stopper参数 API
POST /experimental/features/screensaver_enable参数 API
WebSocket command_data.valuesposition, vector, angles, torques
WebSocket set_angular_torqueset_angular_torques
WebSocket probe_cursor_positionprobe_position
WebSocket set_coordinate_originconfigure.preset
WebSocket set_basis 在会期层面configure.basis

兼容性说明​

与 3.4.19 相比，没有重大不兼容的变更。关于现有集成，有两点 minor 说明：

  1. 过时的 HTTP 端点现在包含一个字段 deprecation_warning 在响应中——严格验证响应模式的客户端必须接受此附加字段。
  2. Le champ values dans WebSocket command_data 该字段已过时，但仍会被解析；请优先使用命名字段。

教程和文档​

  • 新教程：05 位置控制、06 组合（Inverse3 + Verse Grip）、07 基础与安装、08 HTTP 远程配置器、09 WebSocket 远程控制、10 事件流监听器。
  • Glaze 的新变体 每个 C++ 教程的（cpp-glz/)，作为现有 nlohmann/json 变体的补充。
  • 所有教程均已重写 对于 API v3.1（端口 10001， configure.preset, 命名的控件字段、帮助功能 print_state()).
  • 已删除旧版《Verse Grip Stopper》教程——已被新版《组合教程》取代。
  • SDK 指南、API 参考和硬件页面中的公开文档已更新。