メインコンテンツまでスキップ

v3.5.0

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

ハイライト​

  • 統合された 3D 数学レイヤー — 合成可能な変換パイプラインで、デバイスの basis（フレーム）、マウント変換、ワークスペース変換、ナビゲーション変換のためのファーストクラスのプリミティブを備えるとともに、ローカル、セッション、アプリケーション、内部の各空間間の明示的な変換にも対応しています。
  • Bubble Navigation — 形状を持つゾーン（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_stopperSettings API
POST /experimental/features/screensaver_enableSettings 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 Position Control、06 Combined（Inverse3 + Verse Grip）、07 Basis and Mount、08 HTTP Remote Configurator、09 WebSocket Remote Control、10 Event Stream Listener。
  • 既存のnlohmann/jsonバリアントと並んで、すべてのC++チュートリアルに新しいGlazeバリアント（cpp-glz/）が追加されました。
  • すべてのチュートリアルを書き直し、v3.1 APIに対応しました（ポート10001、configure.preset、名前付きコマンドフィールド、print_state()ヘルパー）。
  • 古いVerse Grip Stopperチュートリアルを削除しました。新しいCombinedチュートリアルに置き換えられています。
  • 公開ドキュメントを更新しました。対象は、SDKガイド、APIリファレンス、ハードウェアページ全体です。