v3.5.0

1年前のAPI再設計以来、最大のリリースとなります。バージョン3.5.0では、統合された3D数学レイヤー、Minverse の完全なサポート、型指定されたイベントストリーム、完全な設定API、そしてより整理されたHTTPインターフェースが導入されています。これに加え、この1年間に実施されたバグ修正や使いやすさの改善も含まれています。

主な内容

• 統合3D数学レイヤー— デバイスベース（フレーム）、マウント変換、ワークスペース変換、ナビゲーション変換のための第一級プリミティブを備えた組み合わせ可能な変換パイプラインであり、ローカル、セッション、アプリケーション、内部空間間の明示的な変換を統合して提供します。
• Bubble Navigation— 形状が定義された領域（SDFプリミティブ）を通じて大規模な仮想作業空間をナビゲートし、速度マッピングに基づく速度制御、ヒステリシスを考慮した衝突検出、および選択可能なカーソル方向のドリフト機能を提供します。HTTPおよびWebSocketを基盤として全設定が可能で、アプリ空間との双方向変換をサポートしています。
• タイプが指定されたイベントストリーム— デバイスのライフサイクル、安全に関する通知、校正、バッテリー、制御サイクルの警告、サポート終了の通知専用のWebSocketイベントチャネルです。
• 設定 API— HTTP CRUD、型ヒント、範囲制限、説明をサポートする完全なキー・バリュー型設定システムであり、従来のネストされた設定ファイルに代わるものです。
• 一貫したデバイス構成 — すべてのデバイスに対して、1つのHTTPルートセットを提供します： basis, mount, preset, transform, filters, handedness, torque_scaling, gravity_compensation, home_return.
• Minverse の同期化とペンのキャリブレーション —デバイスとペンは現在、一緒にキャリブレーションされ、グリップが物理的に装着されるまで、キャリブレーション状態はロックされたまま維持されます。
• ユーザビリティの改善 HTTP — インデックスベースのデバイスセレクタ（ID ではなくインデックスでデバイスを指定）、WebSocket 間で共有される統一されたリクエスト／レスポンス形式、オプションで使用可能な {ok, error, data} エンベロープ（?format=json), ワイルドカード・セッション・セレクタを提供します。

新機能

デバイス

• Minverse — 今回のリリースに伴い、以下の機能が正式にサポートされます：デバイス検出、準備（ready）シーケンス、安全通知、同期化されたキャリブレーションワークフロー。
• RukoおよびKingfisherは、公式のグリップ製品タイプとして認定されています。
• デバイスシミュレータのサポート— 実際のハードウェアに加え、ソフトウェアでシミュレートされたデバイスも検出して通信することができます。
• 接続ループ保護 — 正常に動作しないポートは自動的にブロックされ、 POST /ports/{port}/resetにリセットします。
• ペン装着時のハートビート— デバウンス処理を適用し、グリップの装着・取り外しを確実に検知します。

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

• セッションプロファイルのフィルタリングと永続性— セッションは、サービスが再接続後も記憶するプロファイル名と必要なSDKバージョンを宣言しており、クライアントやモニタリングツールは、そのプロファイルに基づいてセッションをフィルタリングし、対象として指定することができます。
• セッションごとのコマンドバッファ— 1つのセッションの処理が遅くても、他のセッションの処理がそれ以上遅くなることはありません。
• 単発命令用の明示的 configure マップ — デバイス別 basis, preset, mount, force_gate, dampingおよびセッション別 profile, basisこれで全部 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の場合、 /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種類のタイプが指定されたイベントカテゴリがあり、これにはデバイスのライフサイクル、安全性（e-brake、異物検知、ストール）、校正失敗、バッテリー通知、セッション警告、制御サイクル低/閾値、入力検証、サポート終了のヒントなどが含まれます。

観測性

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

3.6 予定されている機能

• SDF ハプティックエフェクト（SDF HFX）に基づく機能は、バージョン 3.5 に実装されました（モジュール、ライフサイクル、モジュールが提供するコマンド／状態のシリアライズ）。公開 API は、完全なドキュメントとともにバージョン 3.6 でリリースされる予定です。

改善点

• 力振動フィルタリング— 軸ごとの振動検出、8段階の漸進的復元、ヒステリシスを適用したエントリー投票、非対称解除区間を含みます。
• ランタイム・フォースゲート・フィルター — WebSocket または HTTP から configure.force_gate.gainで構成することができ、永続的に保存されるデフォルト値を提供します。
• メインループの最大周波数を32 kHzに引き上げ（高精度用途向け）。
• より小さなWebSocketペイロード — デフォルトの恒等（identity）変換のサブフィールド（position = 0, rotation = identity, scale = 1)は、基本的に出力から省略されます。これにより、ペイロードサイズが縮小され、4 KBのメッセージ制限がある以前のUnityパッケージとの互換性が回復されます。2つの詳細設定（serialization/explicit_fields, serialization/force_complete_transforms)を使用すれば、これを必要とする消費者のために、すべてのフィールドを再度含めることができます。
• メインループのジッター低減— JSONの解析やネットワーク通信中も、WebSocketメッセージの処理がメインループのティックをブロックすることがなくなり、セッションティックのスケジューリングが応答のシリアライズよりも前倒しされました。
• サーバーはデフォルトでlocalhost専用です — communication/bind_all_interfaces 設定からネットワークへのアクセスを有効にすることができます。
• デバイスセレクタのワイルドカードでの接頭辞構文の使用 （例： inverse*（Inverseシリーズのすべてのデバイスと互換性があります）。
• ダンピング指令これ force_gateとともに configure マップに移動しました。
• ローテーションファイルロガーが以前のロガーに取って代わり、ディレクトリを構成することができます。
• モジュールが提供するコマンドと状態— モジュールは、コアスキーマを変更することなく、独自のコマンドを挿入したり、フィールドを構成したり、状態出力をWebSocketフレームに追加したりすることができます。

修正内容

1年間にわたるバグ修正が含まれており、最も影響の大きい項目は以下の通りです。

• 特定の条件下で、セッションの速度にばらつきが生じる問題。
• **GripHook（Verse Grip Stopper）**が、シミュレーションが実行されていないときに正常に解除されないという問題。
• Inverse3 タイムアウトの設定が短すぎたため、起動に時間がかかるデバイスで接続切断のループが発生していた問題。
• Windowsでサービスが正常に終了しない— 終了時にHTTPサーバーが必ずしもクリーンアップされないという問題。
• サービスが以前のファームウェアバージョンではサポートされていないコマンドを送信した際に発生していた再接続ループ。
• Bluetoothアダプタを搭載したシステムにおいて、Bluetoothデバイスの列挙処理によりログが過剰に埋まってしまう問題。
• サービスを連続して複数回再起動した際に発生していたクラッシュ。
• 省電力モードから復帰した後、Ubuntu搭載のノートパソコンで発生していた、ワイヤレスVerse Gripドングルの動作停止現象。
• Linux および macOS において、ワイヤレス Verse Grip のハンドシェイクが最初の検出試行で失敗した場合、現在は正しく代替手順に移行するようになりました。
• macOSの設定ファイルの保存場所 — 設定が間違っているため、そのパスではなく ~/Library/Application Support/に保存されるように変更されました。
• Linux および macOS における SIGSEGV シグナルの処理— マルチスレッド競合の捕捉が有効になっている場合、プロセスは致命的なシグナルを受けても無限ループに陥らなくなります。
• セッション間のコマンドの上書き— 以前は、あるセッションの設定コマンドが別のセッションのコマンドによって黙って上書きされることがありましたが、現在は適切にフィルタリングされ、統合されるようになりました。
• Probe コマンドの設定の上書き — probe_position送信中のモニタリングセッション（例：Haply Hub）は、保留中のbasis / preset / profileの変更を、もはや黙って上書きしなくなりました。
• プロトタイプのグリップ表示— プロトタイプのハードウェアが、カスタムグリップではなく標準グリップとして誤って表示されていた問題。
• 移行していないクライアント向けに レガシー set_basis 行列の法則これが再びサポートされるようになりました。
• セッションの接続を切断した際、「Inverse3 」のパワーキックは、もはや残りのパワースパイクを発生させなくなりました。
• WebSocket接続の確立と切断が繰り返し行われる際に発生していた、接続切断に関する競合状態。
• 一部の発信ペイロードでは、**WebSocket session_id**ガ 0シリアル化されていた問題。
• Windowsでは --devこれと併用する場合、これからは --log-levelこれが適用されます（以前は debug（静かにリセットされました）。

支援中止のお知らせ

現在も動作していますが、今後のメジャーバージョンで削除される予定です。該当する場合は、回答に deprecation_warning フィールドが含まれます。

支援中止の対象	代替項目
POST /force_scale	POST /settings/devices/inverse*/filters/force_scale/gain
POST /gravity_compensation	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	position, vector, angles, torques
WebSocket set_angular_torque	set_angular_torques
WebSocket probe_cursor_position	probe_position
WebSocket set_coordinate_origin	configure.preset
WebSocketのセッションレベル set_basis	configure.basis

互換性に関する注意事項

3.4.19 に向けて、互換性を損なうような重大な変更はありません。既存の連携に関する注意事項は、以下の 2 点です：

1. サポートが終了したHTTPエンドポイントは、応答に deprecation_warning フィールドが含まれます。レスポンススキーマを厳密に検証するクライアントは、この追加フィールドを受け入れる必要があります。
2. WebSocket command_dataの values このフィールドはサポートが終了していますが、依然として解析されます。名前付きフィールドの使用を推奨します。

チュートリアルおよびドキュメント

• 新しいチュートリアル：05 位置制御（Position Control）、06 統合（Inverse3 ＋Verse Grip）、07 ベースおよびマウント（Basis and Mount）、08 HTTP リモートコンフィギュレータ（Remote Configurator）、09 WebSocket リモート制御（Remote Control）、10 イベントストリームリスナー（Event Stream Listener）。
• 新しいGlazeのバリエーション: 既存の nlohmann/json バリエーションに加え、すべての C++ チュートリアル向けの新しい Glaze バリエーション（cpp-glz/)が追加されました。
• すべてのチュートリアルの書き直し: v3.1 APIに合わせて書き直されました（ポート 10001、 configure.preset, 指定されたコマンドフィールド、 print_state() ヘルパー）。
• 削除：従来の「Verse Grip Stopper」チュートリアルは削除され、新しい統合チュートリアルに置き換えられました。
• 公開ドキュメントの更新：SDKガイド、APIリファレンス、ハードウェア関連のページ全体が刷新されました。