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

HTTP

デフォルトでは、HTTP サービスは http://localhost:10001 で起動します。

ポート番号は、サービスの設定で変更できます。

概要​

このセクションでは、サービスが公開している HTTP ルートについて説明します。

以下のすべてのルートは、デフォルトのベースURL http://localhost:10001 を前提としています。

標準応答エンベロープ​

すべてのエンドポイントは、次の2種類のエンベロープのいずれかを返します:

データなしのレスポンス(更新専用エンドポイントで使用):

{ "ok": true }
{ "ok": false, "error": "reason string" }

データ付きレスポンス(GETのほか、設定エンドポイントへのPOST/DELETEで適用された値を返す場合に使用):

{ "ok": true, "data": { "..." : "..." } }
{ "ok": false, "error": "reason string" }

デバイスセレクタの構文​

デバイスレベルのルートは /{device_type}/{id_or_index}/... のパターンを使用します。{device_type} と {id_or_index} のパスセグメントで、対象のデバイスを指定します。

例のパスセグメント意味
inverse3/0インデックス(0から始まる)で指定した最初のInverse3
inverse3/A14デバイスID A14 のInverse3
inverse3/*すべての「Inverse3 」デバイス(ワイルドカード)
verse_grip/0インデックスで指定された最初のVerse Grip
wireless_verse_grip/*すべての Wireless Verse Grip
*inverse/*Inverse ファミリーのすべてのデバイス(Inverse3、Inverse3x、Minverse)
*verse_grip/*Verse Grip ファミリーのすべてのデバイス(Verse Grip、Wireless VG)

ワイルドカードの規則:

  • GET は、曖昧なセレクタやワイルドカードを含むセレクタを拒否します(400 を返します)。
  • POST と DELETE ワイルドカードが使用できます。この操作は、一致するすべてのデバイスに適用されます。

セッションセレクタ​

セッションスコープのエンドポイント(basis、mount、preset、transform、filters)では、セッションを特定するために ?session=<expr> クエリパラメータが必要です。

式意味
(省略)すべてのセッション(DELETE のみ)
#123 または 123ID 123 のセッション
:-1インデックスによる最後のセッション
:0インデックスによる最初のセッション

例: GET /inverse3/0/config/basis?session=:0


バージョン​

メソッド: GET
URL: http://localhost:10001/version

回答例:

{
"build_time": "2024-08-07T16:01:53Z",
"git_branch": "main",
"git_describe": "3.5.0-2-gce34c39e",
"git_hash": "ce34c39e",
"git_tag": "3.5.0",
"project_name": "haply-inverse-service",
"project_version": "3.5.0"
}

エキスパート ステータス​

メソッド: GET
URL: http://localhost:10001/expert/status

検出、デバイス、セッション、グローバル設定を含む詳細なステータス情報を返します。


デバイス​

メソッド: GET
URL: http://localhost:10001/devices

config、state、status を含む、現在のデバイス一覧を返します。

必要に応じて ?session=<expr> を指定すると、スナップショットを特定のセッションの視点に絞り込むことができます(そのセッションの basis、mount、transform を返される値に適用します)。

回答例:

{
"inverse3": [
{
"device_id": "04BA",
"config": { "...": "..." },
"state": { "...": "..." },
"status": { "...": "..." }
}
]
}

セッション​

メソッドパス説明
取得/sessionsアクティブな v3.1 セッションをすべて一覧表示する
取得/sessions/{session_id}単一のセッションを取得する
取得/sessions/{session_id}/profileセッションのプロファイル名を取得する
投稿/sessions/{session_id}/profileセッションのプロファイルを設定する
削除/sessions/{session_id}/profileプロファイルを "default" にリセット

投稿 /sessions/{session_id}/profile のボディ:

{
"name": "my_profile"
}

ポート​

メソッド: POST
URL: http://localhost:10001/ports/{port}/reset

ブロックされたシリアルポートをクリアします。{ "ok": true } を返します。


デバイス設定​

すべての設定エンドポイントは /{device_type}/{id_or_index}/config/{setting} のパターンを使用します。

セッションスコープのエンドポイント(basis、mount、preset)では、さらに ?session=<expr> クエリパラメータが必要です。

利き手(Inverse3 のみ)​

メソッドパスボディレスポンス
取得/{device_type}/{id}/config/handedness--"left" または "right"
投稿/{device_type}/{id}/config/handedness"left" または "right"エコーされた値
削除/{device_type}/{id}/config/handedness--"right"(デフォルト)

トルクス・スケーリング(Inverse3 のみ)​

メソッドパスボディレスポンス
取得/{device_type}/{id}/config/torque_scaling--{ "enabled": bool }
投稿/{device_type}/{id}/config/torque_scaling{ "enabled": bool }エコーされた値
削除/{device_type}/{id}/config/torque_scaling--{ "enabled": false }

重力補正(Inverse3 のみ)​

メソッドパスボディレスポンス
取得/{device_type}/{id}/config/gravity_compensation--{ "enabled": bool, "scaling_factor": float }
投稿/{device_type}/{id}/config/gravity_compensation{ "enabled": bool, "scaling_factor": float }エコーされた値
削除/{device_type}/{id}/config/gravity_compensation--{ "enabled": true, "scaling_factor": 1.0 }

Basis(すべてのデバイス、セッションスコープ)​

メソッドパスボディレスポンス
取得/{device_type}/{id}/config/basis?session=--{ "permutation": "XYZ" }
投稿/{device_type}/{id}/config/basis?session={ "permutation": "ZXY" }エコーされた値
削除/{device_type}/{id}/config/basis?session=--{ "permutation": "XYZ" }

マウント(すべてのデバイス、セッションスコープ)​

メソッドパスボディレスポンス
取得/{device_type}/{id}/config/mount?session=--{ "transform": {...} }
投稿/{device_type}/{id}/config/mount?session={ "transform": {...} }エコーされた値
削除/{device_type}/{id}/config/mount?session=--恒等変換(identity transform)

Transform の構造(mount および state/transform で使用):

{
"transform": {
"position": { "x": 0, "y": 0, "z": 0 },
"rotation": { "x": 0, "y": 0, "z": 0, "w": 1 },
"scale": { "x": 1, "y": 1, "z": 1 }
}
}

プリセット(全デバイス、セッション単位)​

メソッドパスボディレスポンス
取得/{device_type}/{id}/config/preset?session=--{ "preset": "arm_front_centered" }
投稿/{device_type}/{id}/config/preset?session={ "preset": "arm_front_centered" }エコーされた値
削除/{device_type}/{id}/config/preset?session=--{ "preset": "device_defaults" }

利用可能な値: device_defaults, arm_front, arm_front_centered, led_front, led_front_centered, custom。


デバイスフィルター(Inverse3 のみ、セッション単位)​

フィルターのエンドポイントは /{device_type}/{id}/config/filters/{filter}?session=<expr> を使用します。

ダンピング​

均一ダンピングと方向性ダンピングの両方を制御します。POST の本文には、少なくとも 1 つのフィールドを含める必要があります。

メソッドパスボディレスポンス
取得/{device_type}/{id}/config/filters/damping?session=--{ "scalar": float, "vector": { "x": f, "y": f, "z": f } }
投稿/{device_type}/{id}/config/filters/damping?session={ "scalar": float } または { "vector": {...} } 、あるいはその両方エコーされた値
削除/{device_type}/{id}/config/filters/damping?session=--両方をゼロにリセットする

フォースゲート​

メソッドパスボディレスポンス
取得/{device_type}/{id}/config/filters/force_gate?session=--{ "gain": float }
投稿/{device_type}/{id}/config/filters/force_gate?session={ "gain": float }エコーされた値
削除/{device_type}/{id}/config/filters/force_gate?session=--設定のデフォルト値であるゲイン

デバイスの状態​

トランスフォーム(全デバイス、セッション単位)​

ワークスペースの変換(デバイス空間からアプリケーション空間への変換)。

メソッドパスボディレスポンス
取得/{device_type}/{id}/state/transform?session=--{ "transform": {...} }
投稿/{device_type}/{id}/state/transform?session={ "transform": {...} }エコーされた値
削除/{device_type}/{id}/state/transform?session=--恒等変換

保存の設定​

Inverse3 この機能はデバイス上でのみ動作します。警告:設定の保存は頻繁に行わないでください。 任意のデバイスに適用できる保存回数には上限があります(EEPROMへの書き込みは約10,000回)。

メソッド: POST
URL: http://localhost:10001/save_configuration

ボディの例:

{
"device_id": "049D"
}

応答の例:

{
"ok": true
}

設定​

以下の設定のエンドポイントは、自動的に生成されます:

  • すべての設定の一覧を取得(メタデータを含む)
  • 単一の設定値の読み取り
  • 設定の適用(個別または一括)
  • キーのデフォルト値へのリセット

設定キーの一覧はこちらにあります。

ルート​

メソッドルート説明
取得/settings/すべての設定キー、値、メタデータを取得します。
投稿/settings/複数の設定を一括で適用します。
取得/settings/{key}特定の設定キーの現在の値を取得します。
投稿/settings/{key}特定のキーに新しい値を適用します。
削除/settings/{key}キーをデフォルト値にリセットします。

応答の形式​

取得 /settings/(すべての設定)​

設定キーをキーとするオブジェクトを返します。各エントリには以下の内容が含まれます:

  • value: 現在の値
  • metadata: 型 + 制約 + ロック状態

エントリの例:

{
"devices/detection/timeout": {
"metadata": {
"constraint": {
"range": {
"max": 15,
"min": 1,
"step": 0
}
},
"locked": false,
"type_hint": "INT"
},
"value": 5
}
}

取得 /settings/{key}(単一の設定)​

指定されたキーの値のみ(メタデータなし)を返します。

設定の適用​

投稿 /settings/(一括適用)​

複数のキーをまとめて適用します。

推奨されるボディの形式:キーと値の対応関係を表す JSON オブジェクト。

{
"devices/detection/timeout": 5,
"devices/detection/advanced/wvg_description_filter": ["Haply USB Transceiver", "Haply Handle"]
}

投稿 /settings/{key}(単一の適用)​

単一のキーに新しい値を適用します。

推奨されるボディの形式:生のJSON値、またはラップされた値のいずれか(分かりやすさのため、ラップされた形式を推奨)。

{
"value": 5
}

設定のリセット​

削除 /settings/{key}​

キーをデフォルト値に戻します。

これは「デフォルト値にリセット」と同じです。

型ヒント​

サービスは type_hint を自動的に推定します。複雑な型については、フォールバックとして GENERIC が使用されます。

対応しているヒント:

  • BOOL
  • INT
  • FLOAT
  • STRING
  • VEC2
  • VEC3
  • VEC4
  • TRANSFORM
  • ARR_INT
  • ARR_FLOAT
  • ARR_STRING
  • GENERIC

非推奨のレガシーエンドポイント​

いくつかの POST エンドポイントは引き続き受け付けられますが、非推奨である旨の警告が表示されます。 これらは 4.0 で削除される予定です。 非推奨のパスから置き換え先への完全な対応表については、3.5 移行ガイドをご覧ください。