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

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 または 123数値ID 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"
}

Expert ステータス​

メソッド: 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": { "...": "..." }
    }
  ]
}

セッション​

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

POST /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 のみ）​

メソッドパスボディレスポンス
GET/{device_type}/{id}/config/handedness--"left" または "right"
POST/{device_type}/{id}/config/handedness"left" または "right"エコーされた値
DELETE/{device_type}/{id}/config/handedness--"right"（デフォルト）

トルクスケーリング（Inverse3 のみ）​

メソッドパスボディレスポンス
GET/{device_type}/{id}/config/torque_scaling--{ "enabled": bool }
POST/{device_type}/{id}/config/torque_scaling{ "enabled": bool }エコーされた値
DELETE/{device_type}/{id}/config/torque_scaling--{ "enabled": false }

重力補償（Inverse3 のみ）​

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

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

メソッドパスボディレスポンス
GET/{device_type}/{id}/config/basis?session=--{ "permutation": "XYZ" }
POST/{device_type}/{id}/config/basis?session={ "permutation": "ZXY" }エコーされた値
DELETE/{device_type}/{id}/config/basis?session=--{ "permutation": "XYZ" }

Mount（すべてのデバイス、セッションスコープ）​

メソッドパスボディレスポンス
GET/{device_type}/{id}/config/mount?session=--{ "transform": {...} }
POST/{device_type}/{id}/config/mount?session={ "transform": {...} }エコーされた値
DELETE/{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 }
  }
}

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

メソッドパスボディレスポンス
GET/{device_type}/{id}/config/preset?session=--{ "preset": "arm_front_centered" }
POST/{device_type}/{id}/config/preset?session={ "preset": "arm_front_centered" }エコーされた値
DELETE/{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 つのフィールドを含める必要があります。

メソッドパスボディレスポンス
GET/{device_type}/{id}/config/filters/damping?session=--{ "scalar": float, "vector": { "x": f, "y": f, "z": f } }
POST/{device_type}/{id}/config/filters/damping?session={ "scalar": float } または { "vector": {...} } または両方エコーされた値
DELETE/{device_type}/{id}/config/filters/damping?session=--両方ともゼロにリセット

フォースゲート​

メソッドパスボディレスポンス
GET/{device_type}/{id}/config/filters/force_gate?session=--{ "gain": float }
POST/{device_type}/{id}/config/filters/force_gate?session={ "gain": float }エコーされた値
DELETE/{device_type}/{id}/config/filters/force_gate?session=--設定のデフォルト値の gain

デバイスの状態​

Transform（全デバイス、セッション単位）​

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

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

設定の保存​

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

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

ボディの例:

{
  "device_id": "049D"
}

レスポンスの例:

{
  "ok": true
}

設定​

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

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

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

ルート​

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

レスポンスの形式​

GET /settings/（すべての設定）​

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

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

エントリの例:

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

GET /settings/{key}（単一の設定）​

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

設定の適用​

POST /settings/（一括適用）​

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

推奨されるボディの形式: キーから値へのマッピングを表す JSON オブジェクト。

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

POST /settings/{key}（単一の適用）​

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

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

{
  "value": 5
}

設定のリセット​

DELETE /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 移行ガイドをご覧ください。