メインコンテンツへスキップ

v3.5.0

これは、1年前のAPI刷新以来、最大規模のリリースです。バージョン3.5.0では、統合された3D数学レイヤー、Minverse の完全サポート、型付きイベントストリーム、完全な設定API、そしてよりシンプルになったHTTPインターフェースを導入しました。併せて、1年間にわたるバグ修正や使い勝手の改善も盛り込まれています。

ハイライト​

  • 統合された 3D 数学レイヤー— 合成可能な変換パイプラインを備え、デバイスのベース（フレーム）、マウント変換、ワークスペース変換、ナビゲーション変換のためのファーストクラスのプリミティブを提供するとともに、ローカル、セッション、アプリケーション、内部の各空間間の明示的な変換にも対応しています。
  • バブルナビゲーション— 形状を持つゾーン（SDFプリミティブ）を利用して、大規模な仮想ワークスペース内を移動できます。速度マッピングによる速度制御、ヒステリシスを考慮した衝突検出、オプションでカーソル方向へのドリフトに対応しています。HTTPおよびWebSocketで完全に設定可能であり、アプリ空間内でのラウンドトリップにも対応しています。
  • 型付きイベントストリーム— デバイスのライフサイクル、安全性アラート、キャリブレーション、バッテリー、制御レートの警告、および推奨されない操作に関するヒントに対応する、専用の WebSocket イベントチャネルです。
  • 設定 API— HTTP による CRUD、型ヒント、範囲制約、説明を備えた完全なキーバリュー型設定システムです。従来のネストされた設定ファイルに代わるものです。
  • デバイス設定の一貫性 — すべてのデバイスで共通の HTTP ルートを使用します：basis、mount、preset、transform、filters、handedness、torque_scaling、gravity_compensation、home_return。
  • Minverse ペンとの同期キャリブレーション— デバイスとペンを一緒にキャリブレーションできるようになりました。グリップが物理的に取り付けられるまで、キャリブレーションはロックされたままです。
  • HTTPの使い勝手の向上 — インデックスベースのデバイスセレクタ（ID が不要で、インデックスでデバイスを指定可能）、WebSocket と共通のリクエスト／レスポンス形式、オプトインの {ok, error, data} エンベロープ（?format=json）、ワイルドカード対応のセッションセレクタを搭載しました。

新機能​

デバイス​

  • Minverse — 本リリースでは、検出、準備完了シーケンス、安全通知、同期キャリブレーションのワークフローに対する公式サポートが追加されました。
  • 「Ruko」と「Kingfisher」を、正式なグリップ製品タイプとして認識するようになりました。
  • デバイスシミュレータのサポート— 実機と同様に、ソフトウェアでシミュレートされたデバイスを検出し、通信を行うことができます。
  • 接続ループ保護 — 不正な動作をするポートは自動的にブロックされます。POST /ports/{port}/reset でリセットできます。
  • ペン装着ハートビート— チャタリング防止（デバウンス）機能を搭載し、グリップの装着・取り外しを確実に検知します。

セッション、コマンド、WebSocket​

  • セッションプロファイルのフィルタリングと永続化— セッションは、プロファイル名と必要な SDK バージョンを宣言します。サービスは再接続後もこれらを保持し、クライアントや監視ツールは、そのプロファイルに基づいてセッションをフィルタリング・指定することができます。
  • セッションごとのコマンドバッファ— 処理が遅いセッションによって、他のセッションの動作が滞ることがなくなりました。
  • ワンショットコマンド用の明示的な configure マップ — デバイスごとの basis、preset、mount、force_gate、damping、およびセッションごとの profile と basis しかし、すべて configure にまとめられました。出力の設定マップに合わせてあるため、送信した内容を読み戻した際に一致します。
  • カスタマイズ可能なデバイスマウント — 組み込みのワークスペースプリセット（defaults、arm_front、arm_front_centered、led_front、led_front_centered）から選択するか、明示的な変換を送信できます。マウントを手動で変更すると、プリセットは自動的に custom に切り替わります。
  • 名前付きコマンドフィールド — 汎用の values 配列の代わりに、position、vector、angles、torques を使用します。
  • 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 ` は /inverse3/0/...、Inverse 系のすべてのデバイスは /inverse*/*/...）。
  • 統一されたリクエスト／レスポンス形式 — POST/GET のボディは WebSocket と同じです command_data JSON 形式を使用します。一方のトランスポート向けに書かれたコードは、もう一方でも動作します。
  • オプトイン用封筒 — 任意のルートで ?format=json を指定します。/settings* と GET /home_return のデフォルトは {ok, error, data} です。生の形式を使用する場合は ?format=plain を指定します。
  • セッションセレクタのワイルドカード — プロファイル名では、*（任意の文字列）と ?（任意の 1 文字）を使用できます。
  • パーセントデコードされたセレクタ — %2A、%3A などは、ルーティングの前にデコードされます。

イベント​

  • communication/events/port 上記の専用の WebSocket イベントストリーム。
  • デバイスのライフサイクル、安全性（緊急ブレーキ、異物検出、ストール）、キャリブレーションの失敗、バッテリーアラート、セッション警告、低／危険な制御レート、入力の検証、推奨されないヒントなど、24種類の型付きイベントカテゴリ。

可観測性​

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

3.6 での提供予定​

  • SDF 触覚エフェクト（SDF HFX）— 3.5 で基盤が導入されました（モジュール、ライフサイクル、モジュールが提供するコマンド／状態のシリアライズ）。公開 API は、3.6 で完全なドキュメントとともにリリースされる予定です。

改善点​

  • 力の振動フィルタリング— 軸ごとの振動検出、8段階の段階的回復、ヒステリシスを伴うエントリー投票、非対称なリリースウィンドウ。
  • ランタイムのパワーゲートフィルタ — configure.force_gate.gain（WebSocket または HTTP 経由）で設定可能です。永続的なデフォルト値があります。
  • 精密用途向けに、メインループの最大周波数を 32 kHz に引き上げた。
  • WebSocket ペイロードの軽量化 — デフォルトとして恒等変換を設定する変換のサブフィールド（position = 0、rotation = identity、scale = 1）は、デフォルトでは出力から省略されます。これによりペイロードサイズが削減され、古い Unity パッケージの 4 KB というメッセージ上限との互換性が回復します。2 つの高度な設定（serialization/explicit_fields、serialization/force_complete_transforms）を使用すると、必要なコンシューマー向けにすべてのフィールドを復元できます。
  • メインループのジッターを低減— JSON の解析やネットワーク送信中も、WebSocket のメッセージ処理によってメインループのティックがブロックされることがなくなりました。セッションのティックのスケジューリングは、レスポンスのシリアライズよりも前に移動しました。
  • サーバーはデフォルトでローカルホストのみです — ネットワークアクセスを有効にするには、communication/bind_all_interfaces 設定でオプトインしてください。
  • デバイスセレクタのワイルドカードでプレフィックス構文を使用する（例：inverse* （Inverse 系のすべてのデバイスに一致）。
  • ダンピングコマンド を、force_gate それに加えて configure マップに移動しました。
  • ローテーション機能付きのファイルロガーが以前のバージョンに置き換えられ、ディレクトリを設定できるようになりました。
  • モジュールが提供するコマンドと状態— モジュールは、コアスキーマを変更することなく、独自のコマンドやフィールドを設定し、状態出力を WebSocket フレームに組み込むことができます。

修正​

1年分のバグ修正です。影響の大きいものを以下に示します。

  • 特定の条件下でセッション速度が不安定になる問題。
  • シミュレーションが実行されていない場合、**GripHook（Verse Grip Stopper）**が正しく解放されない問題。
  • Inverse3のタイムアウトが短すぎたため、起動に時間がかかるデバイスで切断ループが発生していた問題。
  • Windowsにおけるサービスの不完全な停止— シャットダウン時にHTTPサーバーが必ずしもクリーンアップされない問題。
  • サービスが古いファームウェアバージョンに対して未サポートのコマンドを送信した際に発生する再接続ループ。
  • Bluetoothアダプターを搭載したシステムにおいて、Bluetoothデバイスの列挙により大量のログが出力される問題。
  • サービスを連続して複数回再起動した際に発生するクラッシュ。
  • Ubuntu搭載のノートパソコンで、スリープから復帰した後、Wireless Verse Gripドングルがフリーズする問題。
  • LinuxおよびmacOSにおけるWireless Verse Gripのハンドシェイクは、最初の検出試行が失敗した場合に正しくフォールバックするようになりました。
  • macOSの設定ファイルの保存場所 — 設定は、間違ったパスではなく~/Library/Application Support/に保存されるようになりました。
  • LinuxおよびmacOSにおけるSIGSEGVシグナルの処理— マルチスレッドのクラッシュキャプチャが有効な場合、プロセスが致命的なシグナルによってループしなくなりました。
  • セッションをまたぐコマンドの上書き— あるセッションの設定コマンドが、別のセッションのコマンドによって知らぬ間に上書きされてしまう問題がありましたが、現在は正しくフィルタリングおよびマージされるようになりました。
  • プローブコマンドによる設定の上書き — probe_position送信中の監視セッション（例：Haply Hub）が、保留中のbasis / preset / profileの変更を認識せずに上書きしなくなりました。
  • プロトタイプグリップの表示— プロトタイプのハードウェアが、カスタムグリップではなく標準グリップとして誤って表示されていた問題。
  • 移行していないクライアント向けに、レガシーのset_basis行列の規則が再び有効になりました。
  • セッション切断時のInverse3のフォースキックにより、残留フォーススパイクが発生しなくなりました。
  • 接続と切断を素早く繰り返す過程で発生するWebSocketの接続喪失レース。
  • 一部の送信ペイロードにおいて、**WebSocketのsession_id**が0としてシリアライズされていた問題。
  • Windowsでは、--devと併用した場合でも--log-levelが反映されるようになりました（以前は知らず知らずのうちに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. WebSocketのcommand_dataにあるvaluesこのフィールドは非推奨ですが、引き続き解析の対象となります。名前付きフィールドの使用を推奨します。

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

  • 新しいチュートリアル：05 位置制御、06 複合（Inverse3 ＋Verse Grip）、07 ベースとマウント、08 HTTPリモートコンフィギュレータ、09 WebSocketリモートコントロール、10 イベントストリームリスナー。
  • 既存のnlohmann/jsonバリアントに加え、すべてのC++チュートリアルに新しいGlazeバリアント（cpp-glz/）が追加されました。
  • すべてのチュートリアルを書き直す、v3.1 APIに対応しました（ポート10001、configure.preset、名前付きコマンドフィールド、print_state()ヘルパー）。
  • 古い「Verse Grip Stopper」のチュートリアルを削除しました。新しい「Combined」チュートリアルに置き換えられています。
  • 公開ドキュメントを更新しました。対象は、SDKガイド、APIリファレンス、およびハードウェアページ全体です。