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 }。
設備構成
すべての配置エンドポイントでは、 /{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= | -- | 恒等変換 |
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 デバイスにのみ適用されます。警告: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 移行ガイド,
廃止されたパスと代替ルートの完全な対応表をご覧ください。