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"
}
専門家のステータス
メソッド: 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 }を返します。
デバイスの構成
すべての構成(config)エンドポイントは /{device_type}/{id_or_index}/config/{setting} パターンを使います。
セッションスコープのエンドポイント(basis、mount、preset)は、さらに ?session=<expr> クエリパラメータが必要です。
利き手(Handedness、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 } |
基準(すべてのデバイス、セッション範囲)
| メソッド | パス | 本文 | 回答 |
|---|---|---|---|
| 取得 | /{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= | -- | 両方を0にリセット |
フォース・ゲート
| メソッド | パス | 本文 | 回答 |
|---|---|---|---|
| 取得 | /{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 この機能はデバイス上でのみ動作します。警告:設定の保存を頻繁に行わないでください。1台のデバイスに適用できる保存回数は制限されているためです (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これを使用します。
利用可能なヒント:
BOOLINTFLOATSTRINGVEC2VEC3VEC4TRANSFORMARR_INTARR_FLOATARR_STRINGGENERIC
使用が中止されたレガシーエンドポイント
いくつか POST エンドポイントは引き続き許可されますが、使用中止の警告が表示されます。
4.0から削除される予定です。詳細な廃止スケジュール → 代替ルート一覧は 3.5 移行ガイドを
参照してください。