Haply Inverse SDK 3.5.0 {#haply-inverse-sdk-350}
1年前のAPI刷新以来、最大規模のリリースとなります。バージョン3.5.0では、統合された3D数学レイヤー、Minverseの完全サポート、型付きイベントストリーム、完全な設定API、そしてより整理されたHTTPインターフェースを導入します。併せて、1年間にわたるバグ修正や使い勝手の改善も盛り込まれています。
ハイライト {#highlights}
統合された 3D 数学レイヤー— デバイスの基底（フレーム）、マウント変換、ワークスペース変換、ナビゲーション変換のためのファーストクラスのプリミティブを備えた、組み合わせ可能な変換パイプラインです。さらに、ローカル、セッション、アプリケーション、内部の各空間間で、明示的な変換を行うことができます。バブルナビゲーション— 形状を持つゾーン（SDFプリミティブ）を通じて、大規模な仮想ワークスペース内を移動できます。速度マッピングによる速度制御、ヒステリシスを考慮した衝突検出、そして必要に応じてカーソル方向へのドリフトに対応しています。HTTPおよびWebSocketから完全に設定可能で、アプリ空間内でのラウンドトリップにも対応しています。型付きイベントストリーム— デバイスのライフサイクル、安全アラート、キャリブレーション、バッテリー、制御レートの警告、および非推奨事項に関するヒント専用の WebSocket イベントチャネルです。Settings API— HTTP による CRUD 操作、型ヒント、範囲制約、説明を備えた、完全なキーと値の設定システムです。従来のネストされた設定ファイルに代わるものです。デバイス設定の統一 — すべてのデバイスで共通の HTTP ルートを1セット用意しています： 基準、マウント、プリセット、変える、フィルター、利き手、トルク・スケーリング、重力補正、ホームに戻る。Minverse とペンの同期キャリブレーション— デバイスとそのペンが一緒にキャリブレーションされるようになりました。グリップが物理的に取り付けられるまで、キャリブレーションはロックされたままです。HTTPの使い勝手の向上 — インデックスベースのデバイスセレクター（ID が不要で、インデックスでデバイスを指定可能）、WebSocket と共通のリクエスト／レスポンス形式、オプトインの {OK、エラー、データ} エンベロープ（?format=json）、およびワイルドカードによるセッションセレクタを提供します。新機能 {#new-features}
デバイス {#devices}
Minverse— 本リリースより正式サポートを開始します。これには、検出、準備完了シーケンス、安全通知、同期キャリブレーションのワークフローが含まれます。「Ruko」と「Kingfisher」を、正式なグリップ製品タイプとして認識するようになりました。デバイスシミュレータのサポート— 実機と並行して、ソフトウェアでシミュレートされたデバイスを検出し、通信することができます。接続ループの保護 — 不正な動作をするポートは自動的にブロックされます。POST /ports/{port}/reset でリセットできます。ペンの装着時のハートビート— デバウンス処理により、グリップの装着・取り外しを確実に検知します。セッション、コマンド、WebSocket {#sessions-commands-websocket}
セッションプロファイルのフィルタリングと永続化— セッションはプロファイル名と必要な SDK バージョンを宣言でき、サービスは再接続後もこれらを記憶します。クライアントや監視ツールは、このプロファイルを使用してセッションをフィルタリングし、対象を指定することができます。セッションごとのコマンドバッファ— 処理が遅いセッションによって、他のセッションが停止してしまうことがなくなりました。単発コマンド用の明示的な `configure` マップ — デバイスごとの 基準、プリセット、マウント、force_gate、減衰、およびセッションごとの プロフィール と 基準 しかし、すべて 設定する に含まれるようになりました。出力の設定マップと一致するように調整されているため、送信した内容と読み取った内容は、ラウンドトリップを通じて一致します。カスタマイズ可能なデバイスマウント — 組み込みのワークスペースプリセット（デフォルト、腕（前面）、腕の正面中央、フロントLED、led_front_centered）から選択するか、明示的な変換を送信できます。マウントを手動で変更すると、プリセットは自動的に カスタム に切り替わります。名前付きコマンドフィールド — 汎用の 価値観 配列の代わりに、位置、ベクトル、角度、トルク を使用します。角トルクを設定する が set_angular_torque に置き換えます（単数形は推奨されません）。セッションフレームの拡張 — v3.0 および v3.1 のセッションフレームに、拡張可能な 設定、状態、ステータス オブジェクトが含まれるようになりました。新しい出力フィールドには、current_cursor_force、現在のカーソル位置、現在の角トルク、現在の角度位置、制御ドメイン、制御モード、変える、変形速度、より詳細な config.*、そして ステータス・安全（デフォルトでは非表示）があります。変換の部分更新 — マウント、ワークスペースの変換、ナビゲーションシェイプにおいて、変更したいサブフィールド（位置、回転、スケール）のみ送信できます。HTTP {#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 を指定して有効にします。/設定* と GET /home_return は、デフォルトでは {OK、エラー、データ} となります。生の形式を使用する場合は ?format=plain を指定します。セッションセレクタのワイルドカード — プロファイル名では、*（任意の文字列）と ?（任意の 1 文字）を使用できます。パーセントデコードされたセレクタ — %2A、%3A などは、ルーティングの前にデコードされます。イベント {#events}
コミュニケーション／イベント／ポート 上記の専用 WebSocket イベントストリーム。デバイスのライフサイクル、安全機能（非常ブレーキ、異物検出、ストール）、キャリブレーションの失敗、バッテリーアラート、セッションに関する警告、制御レートの低下および著しい低下、入力の検証、推奨されないヒントなど、24種類の型付きイベントカテゴリ。オブザーバビリティ {#observability}
プロファイリング時、ログメッセージはレベルに応じた色で Tracy に転送されます。すべての HTTP ハンドラーに Tracy ゾーンを設定しています。メインループのタイミング統計イベント。ログディレクトリとサーバーのホスト名を設定可能（Docker に対応）。3.6 で提供予定の機能 {#coming-in-36}
SDF ハプティックエフェクト（SDF HFX）— 基盤部分は 3.5 に含まれています（モジュール、ライフサイクル、モジュールが提供するコマンドおよび状態のシリアライズ）。公開 API は、完全なドキュメントとともに 3.6 で提供される予定です。改善点 {#improvements}
力振動フィルター— 軸ごとの振動検出、8段階の段階的な回復、ヒステリシスを備えた進入投票、非対称な解除ウィンドウを備えています。ランタイムのフォースゲートフィルター — WebSocket または HTTP 経由で configure.force_gate.gain を使用して設定できます。永続的なデフォルト値も設定できます。メインループの最大周波数を 32 kHz に引き上げ— 高精度なアプリケーション向けです。WebSocket ペイロードの縮小 — デフォルトで恒等値となる変換サブフィールド（位置 = 0、rotation = 単位行列、スケール = 1）は、デフォルトで出力から省略されるようになりました。これにより、ペイロードサイズが小さくなり、古い Unity パッケージの 4 KB というメッセージ上限との互換性も回復します。すべてのフィールドを出力に含めたいコンシューマー向けに、2 つの詳細設定（シリアライズ/明示的なフィールド、シリアライズ/変換の強制完了）が用意されています。メインループのジッター低減— WebSocket のメッセージ処理において、JSON の解析やネットワーク送信が行われている間も、メインループのティックがブロックされなくなりました。セッションのティックスケジューリングは、レスポンスのシリアライズよりも前の段階で行われるようになりました。サーバーはデフォルトで localhost のみです — ネットワークへのアクセスは、通信/すべてのインターフェースをバインド 設定で明示的に有効にすることができます。デバイスセレクタのワイルドカードは、先頭一致構文を使用します（例： inverse （Inverse ファミリーのすべてのデバイスに対応）。ダンピングコマンド を、force_gate 並べて 設定する マップに移動しました。ローテーションするファイルロガーに置き換わり、ディレクトリを設定できるようになりました。モジュールが提供するコマンドと状態— モジュールは、コアスキーマを変更することなく、独自のコマンドを追加したり、フィールドを設定したり、状態出力を WebSocket フレームに組み込んだりすることができます。修正 {#fixes}
1年間に実施されたバグ修正のうち、特に影響の大きかったものは以下の通りです。
セッション速度の不安定化（特定の条件下）。GripHook（Verse Grip Stopper）は、シミュレーションが実行されていない場合、正しく解放されませんでした。Inverse3 タイムアウトが短すぎたため、起動に時間がかかるデバイスで切断ループが発生していました。Windows でのサービス停止時の不完全な終了— シャットダウン時に、HTTPサーバーが必ずしもクリーンアップされていませんでした。再接続ループ（サービスが、古いファームウェアバージョンでは対応していないコマンドを送信した場合）。Bluetooth デバイスの列挙により、Bluetooth アダプターを搭載したシステムで大量のログが出力されていました。サービスを連続して再起動した際のクラッシュ。Wireless Verse Grip ドングルのフリーズ（Ubuntu 搭載ノートPCでスリープ／復帰後に発生）。Linux および macOS における Wireless Verse Grip のハンドシェイクは、最初の検出試行が失敗した場合に正しくフォールバックするようになりました。macOSの設定ファイルの保存場所 — 設定は間違ったパスではなく ~/Library/Application Support/ に保存されるようになりました。Linux および macOS における SIGSEGV シグナルの処理— マルチスレッドのクラッシュキャプチャが有効な場合、致命的なシグナルが発生してもプロセスがループしなくなりました。セッション間のコマンドの上書き— 以前は、あるセッションの設定コマンドが、別のセッションのコマンドによって黙って上書きされることがありましたが、現在は正しくフィルタリングされ、マージされるようになりました。プローブコマンドによる設定の上書き — プローブの位置 送信される監視セッション（例：Haply Hub）が、保留中のbasis／preset／profileの変更を無断で上書きしなくなりました。プロトタイプグリップの表示— プロトタイプのハードウェアが、カスタムグリップではなく標準グリップとして誤って表示されていました。従来の `set_basis` 行列規約が、移行前のクライアントに対して再び適用されるようになりました。Inverse3 強制キックにより、セッション切断時に残留する力の急上昇が発生しなくなりました。WebSocket の接続切断レース（急速な接続・切断の繰り返し中）。WebSocket の `session_id` しかし、一部の送信ペイロードでは 0 としてシリアライズされていました。Windows それでは、--dev と組み合わせた場合でも --ログレベル が尊重されるようになりました（以前は デバッグ （知らぬ間にリセットされていました）。非推奨 {#deprecations}
以下の機能は引き続き動作しますが、将来のメジャーバージョンで削除される予定です。該当する場合は、レスポンスに 非推奨警告 フィールドが含まれます。
| 非推奨 | 置き換え先 |
|---|---|
| POST /force_scale | POSTinverse |
| 投稿 /重力補正 | POST /{device}/{id}/config/gravity_compensation |
| 投稿 /torque_scaling | POST /{device}/{id}/config/torque_scaling |
| 投稿 /デバイスの利き手 | POST /{device}/{id}/config/handedness |
| POST /serial_enable | POST /settings/communication/serial/enabled |
| POST /experimental/features/グリップ脱落シミュレーションストッパー | Settings API |
| POST /experimental/features/screensaver_enable | Settings API |
| WebSocket command_data.values | 位置, ベクトル, 角度, トルク |
| WebSocket set_angular_torque | 角トルクを設定する |
| WebSocket カーソルの位置を取得 | プローブの位置 |
| WebSocket 座標原点を設定する | configure.preset |
| WebSocket セッションレベル 基底を設定する | configure.basis |
互換性に関する注意事項 {#compatibility-notes}
3.4.19 からの互換性を損なう変更はありません。既存の連携に関して、以下の 2 点に注意が必要です：
非推奨の HTTP エンドポイントのレスポンスには、非推奨警告 フィールドが追加されました。レスポンススキーマを厳密に検証しているクライアントでは、この追加フィールドを受け入れるように設定してください。WebSocket の command_data にある 価値観 このフィールドは非推奨ですが、引き続き解析の対象となります。名前付きフィールドの使用を推奨します。チュートリアルとドキュメント {#tutorials-documentation}
新しいチュートリアル：05 位置制御、06 組み合わせ（Inverse3 ＋Verse Grip）、07 Basis と Mount、08 HTTP リモートコンフィギュレータ、09 WebSocket リモートコントロール、10 イベントストリームリスナー。新しい Glaze 版：既存の nlohmann/json 版と並んで、すべての C++ チュートリアルに追加されました（cpp-glz/）。すべてのチュートリアルを書き直す、v3.1 API に対応させました（ポート 10001、configure.preset、名前付きコマンドフィールド、print_state() ヘルパー）。削除— 旧バージョンの「Verse Grip Stopper」チュートリアルは削除され、新しい組み合わせチュートリアルに置き換えられました。公開ドキュメントを更新しました（SDK ガイド、API リファレンス、ハードウェアのページ）。
