本文へスキップ
バージョン: 3.5.x

v3.5.0

1年前のAPI再設計以来、最大規模のリリースとなります。バージョン3.5.0では、統一された3D数学レイヤー、Minverse 、型付きイベントストリーム、包括的な設定API、そしてより洗練されたHTTPインターフェースを導入するとともに、1年間にわたるバグ修正や利便性向上の改善も盛り込まれています。

見どころ​

  • 統合3D数学レイヤー— デバイス基準（フレーム）、マウント変換、ワークスペース変換、ナビゲーション変換のための第一級プリミティブを備えた、組み合わせ可能な変換パイプライン。さらに、ローカル空間、セッション空間、アプリケーション空間、内部空間間の明示的な変換機能も備えています。
  • バブルナビゲーション— 形状ゾーン（SDFプリミティブ）を通じて大規模な仮想ワークスペースをナビゲートします。速度マッピングによる速度制御、ヒステリシスを考慮した衝突検出、およびオプションのカーソルへのドリフト機能を備えています。アプリとサーバー間の往復通信により、HTTPおよびWebSocket経由で完全に設定可能です。
  • タイプ付きイベントストリーム— デバイスのライフサイクル、安全アラート、キャリブレーション、バッテリー、制御レートに関する警告、および非推奨の通知専用のWebSocketイベントチャネル。
  • Settings API— HTTP CRUD、型ヒント、範囲制約、説明機能を備えた完全なキーバリュー型設定システムであり、従来のネストされた設定ファイルに代わるものです。
  • 一貫性のあるデバイス設定 — デバイスごとに1セットのHTTPルート： basis, mount, preset, transform, filters, handedness, torque_scaling, gravity_compensation, home_return.
  • Minverse 同期キャリブレーション— デバイスとペンが同時にキャリブレーションされるようになりました。グリップが物理的に装着されるまで、キャリブレーション設定は固定されたままになります。
  • 生活の質（QoL）とHTTP — インデックスベースのデバイスセレクタ（インデックスでデバイスを指定するため、IDは不要）、WebSocketと共通の統一されたリクエスト／レスポンス形式、オプトイン {ok, error, data} 封筒 (?format=json)、およびワイルドカード・セッション・セレクタ。

新機能​

デバイス​

  • Minverse — 本リリースで提供される公式サポート：検出、準備シーケンス、安全通知、および同期化されたキャリブレーションワークフロー。
  • 「ルコ」と「キングフィッシャー」が公式グリップ製品として認定されました。
  • デバイスシミュレータのサポート— 実際のハードウェアと並行して、ソフトウェアでシミュレートされたデバイスを検出し、通信を行う。
  • 接続ループ保護 — 不正な動作をするポートは自動的にブロックされます。リセットするには POST /ports/{port}/reset.
  • ペンアタッチメントのハートビート— デバウンス機能付きの高精度なグリップ着脱検出。

セッション、コマンド、およびWebSocket​

  • セッションプロファイルのフィルタリングと永続化— セッションはプロファイル名と必要なSDKバージョンを宣言し、サービスは再接続時にもその情報を保持します。クライアントや監視ツールは、そのプロファイルに基づいてセッションをフィルタリングしたり、対象を絞り込んだりすることができます。
  • セッションごとのコマンドバッファ— 1つの処理が遅くても、他のセッションの処理が滞ることはなくなりました。
  • 明示的 configure ワンショットコマンド用マップ — basis, preset, mount, force_gate, damping 1台あたり、さらに profile そして basis 1回あたり、現在はすべて configure — 出力設定マップと整合が取れているため、送信した内容と読み取った内容が一致します。
  • カスタマイズ可能なデバイス用マウント — 組み込みのワークスペースプリセットを選択する (defaults, arm_front, arm_front_centered, led_front, led_front_centered) または明示的な変換を送信する；手動でのマウント変更により、プリセットは自動的に custom.
  • 名前付きコマンドフィールド — position, vector, angles, torques 汎用的なものを置き換える values 配列。
  • set_angular_torques 置き換える set_angular_torque （単数形は非推奨）。
  • セッションフレームの拡張 — v3.0 および v3.1 のセッションフレームは、拡張可能な config, stateそして 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) マウント、ワークスペース変換、およびナビゲーション形状について。

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 どのルートでも； /settings* そして GET /home_return デフォルトでは {ok, error, data}. 使用する ?format=plain 元の形状について。
  • セッションセレクタのワイルドカード — * （任意のシーケンス）および ? プロフィール名に（1文字）が含まれる。
  • パーセント記法によるセレクタ — %2A, %3A、などについては、ルーティングの前にデコードされます。

イベント​

  • 専用のWebSocketイベントストリームを有効にする communication/events/port.
  • デバイスのライフサイクル、安全性（電子ブレーキ、異物検知、ストール）、キャリブレーションの失敗、バッテリーアラート、セッション警告、制御レートの低下／臨界状態、入力検証、および非推奨の通知など、24種類のイベントカテゴリ。

可観測性​

  • プロファイリング時に、レベルに応じた色分けが施されたログメッセージがTracyに転送されます。
  • TracyはすべてのHTTPハンドラーを監視します。
  • メインループのタイミング統計イベント。
  • ログディレクトリとサーバーのホスト名を設定可能（Docker対応）。

バージョン3.6で登場​

  • SDF Haptic Effects (SDF HFX)— 基盤となる機能はバージョン3.5で実装されました（モジュール、ライフサイクル、モジュール提供のコマンド／状態のシリアライズ）。公開APIは、完全なドキュメントとともにバージョン3.6で提供される予定です。

改善点​

  • フィルタ処理されたフォース振動— 軸ごとの振動検出、8段階の段階的回復、ヒステリシスを伴うエントリー投票、および非対称なリリースウィンドウ。
  • 実行時フォースゲートフィルタ — 設定可能 configure.force_gate.gain WebSocketまたはHTTP経由で、永続的な接続をデフォルトとして使用します。
  • 高精度用途向けに、メインループの最大周波数を32 kHzに引き上げました。
  • WebSocketのペイロードを小さくする — identity-default の変換サブフィールド (position = 0, rotation = identity, scale = 1) はデフォルトでは出力から除外され、これによりペイロードサイズが削減され、旧バージョンのUnityパッケージにおける4KBのメッセージ制限との互換性が確保されます。2つの詳細設定（serialization/explicit_fields, serialization/force_complete_transforms) 必要なすべてのフィールドを消費者向けに復元する。
  • メインループのジッターを低減— WebSocketメッセージの処理において、JSONの解析やネットワーク送信中にメインループのティックがブロックされることがなくなりました。また、セッションティックのスケジューリングが、レスポンスのシリアライズ処理の前に移動されました。
  • サーバーはデフォルトでlocalhostのみを対象としています — ネットワークアクセスを有効にするには、 communication/bind_all_interfaces 設定。
  • デバイスセレクタのワイルドカードは接頭辞構文を使用します （例： inverse* （Inverseファミリーのすべてのデバイスに一致します）。
  • 減衰指令 ～に引っ越した configure 横に地図を表示 force_gate.
  • ローテーションファイルロガーは、以前のものを置き換え、ディレクトリの設定が可能です。
  • モジュールが提供するコマンドと状態— モジュールは、コアスキーマを変更することなく、独自のコマンド、設定フィールド、および状態出力をWebSocketフレームに挿入することができます。

修正点​

この1年間のバグ修正について、特に影響の大きかったものを以下に挙げます。

  • 特定の条件下で、セッション速度が不安定になる。
  • シミュレーションが実行されていない状態では、GripHook（Verse Grip Stopper）がスムーズに外れませんでした。
  • Inverse3 厳しすぎたため、起動に時間がかかるデバイスで接続切断のループが発生していました。
  • Windows での不完全なサービス停止— シャットダウン時に HTTP サーバーが常に適切にクリーンアップされるとは限りませんでした。
  • サービスが古いファームウェアバージョンに対して非対応のコマンドを送信した際の再接続ループ。
  • Bluetoothアダプタを搭載したシステムでは、Bluetoothデバイスの列挙処理によりログが溢れかえった。
  • サービスを連続して再起動するとクラッシュする。
  • Ubuntu搭載のノートPCで、スリープ/復帰後にWireless Verse Gripドングルがフリーズする。
  • Linux および macOS におけるWireless Verse Grip のハンドシェイク処理において、最初の検出試行が失敗した場合、正しくフォールバックするようになりました。
  • MacOSの設定ファイルの場所 — 設定は現在、 ~/Library/Application Support/ 間違った道ではなく。
  • Linux および macOS における SIGSEGV シグナルの処理— マルチスレッドクラッシュキャプチャが有効になっている場合、致命的なシグナルが発生してもプロセスがループしなくなりました。
  • セッション間のコマンド上書き— あるセッションの構成コマンドが、別のセッションのコマンドによって黙って上書きされることがありましたが、これらは現在、フィルタリングされ、正しく統合されるようになりました。
  • プローブコマンドが設定を上書きする — モニタリングセッション（例：Haply ）の送信 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_basisconfigure.basis

互換性に関する注意事項​

3.4.19 との互換性を損なう重大な変更はありません。既存の統合機能に関して、以下の2点にご注意ください：

  1. 非推奨となったHTTPエンドポイントには、現在 deprecation_warning レスポンス内のフィールド — レスポンススキーマを厳密に検証するクライアントは、この追加フィールドを許可する必要があります。
  2. について values WebSocketのフィールド command_data 非推奨ですが、依然として解析されます。名前付きフィールドの使用を推奨します。

チュートリアルとドキュメント​

  • 新しいチュートリアル：05 位置制御、06 複合（Inverse3 Verse Grip）、07 ベースとマウント、08 HTTPリモートコンフィギュレータ、09 WebSocketリモートコントロール、10 イベントストリームリスナー。
  • 新しい釉薬の種類 あらゆるC++チュートリアルの（cpp-glz/) 既存の nlohmann/json バリアントと並行して。
  • すべてのチュートリアルを書き直しました v3.1 API（ポート 10001、 configure.preset、名前付きコマンドフィールド、 print_state() （ヘルパー）。
  • 以前の「Verse Grip Stopper」チュートリアルを削除しました。代わりに新しい「Combined」チュートリアルを掲載しています。
  • SDKガイド、APIリファレンス、およびハードウェアページ全体の公開ドキュメントを更新しました。