这是自一年前重写 API 以来我们发布的最大规模更新。3.5.0 版本引入了统一的 3D 数学层、对 Minverse 的全面支持、带类型的事件流、完整的设置 API 以及更简洁的 HTTP 接口——此外还包含过去一年中积累的 bug 修复和体验优化。
亮点
统一的 3D 数学层——一个可组合的变换管道,包含用于设备基底(帧)、安装变换、工作空间变换和导航变换的一流基元,并支持本地、会话、应用程序和内部空间之间的显式转换。气泡导航——通过形状区域(SDF 基元)在大型虚拟工作空间中进行导航,支持基于速度映射的速率控制、考虑滞后效应的碰撞检测,以及可选的“向光标漂移”功能。可通过 HTTP 和 WebSocket 进行全面配置,并支持应用空间往返通信。类型化事件流——一个专用的 WebSocket 事件通道,用于处理设备生命周期、安全警报、校准、电池状态、控制速率警告以及弃用提示。设置 API—— 一个功能齐全的键值设置系统,支持 HTTP CRUD 操作、类型提示、范围限制和描述,取代了旧版的嵌套配置文件。一致的设备配置 — 每个设备对应一组 HTTP 路由: 基础, 安装, 预设, 变, 过滤器, 惯用手, 扭矩缩放, 重力补偿, 首页_返回.同步 Minverse + 笔校准— 设备及其笔现在将一同进行校准;校准状态将保持锁定,直到物理连接笔握柄为止。生活质量 HTTP — 基于索引的设备选择器(通过索引定位设备,无需 ID),与 WebSocket 共享的统一请求/响应格式,以及一种选择加入机制 {成功、错误、数据} 信封 (?format=json),以及通配符会话选择器。新功能
设备
Minverse— 本版本已正式支持以下功能:检测、就绪序列、安全通知以及同步校准工作流。Ruko和Kingfisher已被认定为官方握把产品类型。设备模拟器支持——在检测和与真实硬件通信的同时,也能检测和与软件模拟的设备通信。连接回路保护 — 行为异常的端口将被自动封锁;使用以下命令重置: POST /ports/{port}/reset.笔身连接状态检测——带防抖功能的可靠握持连接/断开检测。会话、命令与 WebSocket
会话配置文件过滤与持久化——会话会声明一个配置文件名称和所需的 SDK 版本,服务会在多次重连过程中记住这些信息;客户端和监控工具可以根据该配置文件对会话进行过滤和定位。按会话划分的命令缓冲区——一个运行缓慢的会话不再会阻塞另一个会话。针对一次性命令的显式 `configure` 映射 — 基础, 预设, 安装, force_gate, 阻尼 每台设备,外加 个人资料 和 基础 每次,现在全部位于 配置 — 与输出配置映射保持一致,因此您发送的数据与读取回来的数据完全一致。可定制设备支架 — 选择一个内置的工作区预设(默认值, 前臂, 臂部前侧居中, 前大灯, led_front_centered) 或发送明确的转换指令;手动挂载更改会自动将预设切换为 自定义.命名命令字段 — 位置, 向量, 角度, 扭矩 替换通用名称 价值观 数组。设置角扭矩 替换 set_angular_torque (单数形式已弃用)。会话帧扩展 — v3.0 和 v3.1 会话帧现在支持可扩展 配置, 状态和 状态 对象;新增的输出字段包括 current_cursor_force, 当前光标位置, 当前角扭矩, 当前角位置, 控制域, 控制模式, 变, transform_velocity, 更丰富 config.*和 状态.安全 (默认隐藏)。部分转换更新 — 仅发送您想要修改的子字段(位置, 旋转, 比例尺) 涉及挂载、工作区变换和导航形状。HTTP
GET / — 服务版本。GET/POST/DELETE /settings 和 /settings/* — 完整的键值设置 API。GET /sessions/{session} 和 GET/POST/DELETE /sessions/{session}/profile.GET /devices?session=<selector> — 将设备坐标转换为指定会话的应用程序空间。基于索引的设备选择器 — 无需知道设备 ID,即可通过索引定位任意设备 (/inverse3/0/... 对于第一个 Inverse3; inverse... (适用于所有Inverse设备)。统一的请求/响应格式 — POST/GET 请求体使用相同的 command_data JSON 作为 WebSocket 的载体;针对一种传输方式编写的代码同样适用于另一种。预付邮资信封 通过 ?format=json 在任何航线上; /设置* 和 GET /home_return 默认设置为 {成功、错误、数据}. 使用 ?format=plain 用于原始形状。会话选择器通配符 — * (任意序列)和 ? (单个字符)在个人资料名称中。百分比解码选择器 — %2A, %3A等在路由之前会被解码。活动
启用专用 WebSocket 事件流 沟通/活动/港口.24 类预定义事件,包括设备生命周期、安全(电子刹车、异物检测、失速)、校准失败、电池警报、会话警告、控制速率过低/临界、输入验证以及弃用提示。可观测性
在进行性能分析时,将日志消息转发至 Tracy,并根据级别显示不同颜色。Tracy 会监听每个 HTTP 处理程序。主循环的定时统计事件。可配置日志目录和服务器主机名(支持 Docker)。即将于3.6版本推出
SDF 触觉效果(SDF HFX)——其基础功能已在 3.5 版本中实现(模块、生命周期、模块提供的命令/状态序列化),而公开 API 及完整文档将于 3.6 版本发布。改进
经过滤波的力振荡——按轴检测振荡、8级渐进式恢复、带滞后效应的输入确认,以及非对称释放windows。运行时强制门控滤波器 — 可通过 configure.force_gate.gain 通过 WebSocket 或 HTTP 传输,并默认保持连接。主循环最高频率已提升至 32 kHz,以满足高精度应用的需求。更小的 WebSocket 数据包 — identity-default 转换子字段 (position = 0, 旋转 = 单位矩阵, 比例 = 1) 默认情况下不会包含在输出中,这样既能缩小有效载荷大小,又能恢复与旧版 Unity 包 4 KB 消息限制的兼容性。两个高级设置(序列化/显式字段, 序列化/强制完成转换) 为有需要的用户恢复所有字段。降低主循环抖动——WebSocket 消息处理在 JSON 解析和网络发送期间不再阻塞主循环的 tick;会话 tick 的调度被移至响应序列化之前。服务器默认仅限本地主机访问 — 通过以下方式启用网络访问: 通信/绑定所有接口 设置。设备选择器的通配符使用前缀语法 (例如: inverse (适用于所有Inverse 系列设备)。阻尼指令 搬进了 配置 附图 force_gate.轮换文件记录器取代了之前的版本,并支持自定义目录。模块提供的命令和状态— 模块可以在不触及核心模式的情况下,将自身的命令、配置字段和状态输出注入 WebSocket 帧中。修复
过去一年中修复了诸多问题;最具影响力的修复如下。
在某些条件下,会话速度不稳定。当未运行任何模拟时,GripHook(Verse Grip Stopper)无法顺利释放。Inverse3 的超时设置过于严格,导致启动缓慢的设备出现断连循环。 Windows上的未清理服务停止— 关机时 HTTP 服务器并非总能被正确清理。当服务向旧版固件发送不支持的命令时,会触发重连循环。蓝牙设备枚举导致配备蓝牙适配器的系统日志被淹没。连续多次重启服务时发生崩溃。在 Ubuntu 笔记本电脑上,Wireless Verse Grip 适配器在睡眠/恢复后会卡死。在 Linux 和 macOS 上,当首次检测尝试失败时,Wireless Verse Grip 的握手过程现在会正确地进行回退。MacOS 配置文件的位置 — 配置现已存储在 ~/Library/Application Support/ 而不是走错路。Linux 和 macOS 上的 SIGSEGV 信号处理——当启用多线程崩溃捕获时,进程在收到致命信号后不再陷入循环。跨会话命令覆盖— 以前,一个会话中的配置命令可能会被另一个会话中的命令悄然替换;现在,这些命令会被正确过滤并合并。Probe 命令覆盖了配置 — 监控会话(例如Haply )发送 探针位置 不再默认覆盖待处理的基础设置/预设/配置文件更改。原型握把显示——原型硬件被错误地显示为标准握把,而非定制握把。对于尚未迁移的客户端,再次遵循旧版 `set_basis` 矩阵约定。在会话断开时,Inverse3 力反馈踢腿不再产生残留力突增。在快速连接/断开循环过程中,WebSocket 连接因竞态条件而丢失。WebSocket `session_id` 曾以连载形式发表 0 在某些发出的有效载荷中。在Windows 上, --日志级别 现在,当与……结合使用时,该设置将被采纳 --dev (此前已静默重置为 调试).折旧
目前仍可正常使用,但将在未来的重大版本中移除。响应包括一个 弃用警告 (如适用,请填写此处)。
| 已弃用 | 替代方案 |
|---|---|
| POST /force_scale | POSTinverse |
| POST /重力补偿 | POST /{device}/{id}/config/gravity_compensation |
| POST /torque_scaling | POST /{device}/{id}/config/torque_scaling |
| POST /device_handedness | POST /{device}/{id}/config/handedness |
| POST /serial_enable | POST /settings/communication/serial/enabled |
| POST /experimental/features/grip_dropped_simulation_stopper | 设置 API |
| POST /experimental/features/screensaver_enable | 设置 API |
| WebSocket command_data.values | 位置, 向量, 角度, 扭矩 |
| WebSocket set_angular_torque | 设置角扭矩 |
| WebSocket 获取光标位置 | 探针位置 |
| WebSocket 设置坐标原点 | 配置预设 |
| WebSocket 会话级 set_basis | configure.basis |
兼容性说明
与 3.4.19 相比,没有重大兼容性变更。针对现有集成有两点需注意:
已弃用的 HTTP 端点现在包含一个 弃用警告 响应中的字段——严格验证响应模式的客户端应允许该额外字段。"(《世界人权宣言》) 价值观 WebSocket 中的字段 command_data 该写法已弃用,但仍会被解析;建议使用命名字段。教程与文档
新教程:05 位置控制,06 组合(Inverse3 + Verse Grip),07 基座与安装,08 HTTP 远程配置器,09 WebSocket 远程控制,10 事件流监听器。新釉色款式 在每个 C++ 教程中(cpp-glz/) 与现有的 nlohmann/json 变体并存。所有教程均已重写 适用于 v3.1 API(端口 10001, 配置预设, 命名的命令字段, print_state() (助手)。已删除旧版的Verse Grip Stopper教程——现已替换为新版综合教程。已更新 SDK 指南、API 参考和硬件页面中的公开文档。