シミュレーション・チャンネル

概要

シミュレーション・チャネルは、デバイスの状態を交換したり、セッションやデバイスのコマンドを送信したりするために使用される、高頻度の双方向WebSocketチャネルです。

デフォルトのURL： ws://localhost:10001

設定でポートを変更できます。

基本契約（重要）：

• クライアントが接続すると、サービスはデバイスの完全なリストを含む初期インベントリメッセージを送信します。
• その後、サーバーはクライアントから受信したメッセージごとに、正確に1つの ステート更新メッセージを送信します。
• 各「ステータス更新」には、すべてのデバイスの状態（およびステータス）が含まれています。

:::info モジュール このページでは、Simulation Channelのプロトコルとコマンドの主要な機能について説明します。

追加のモジュールや機能は、独自のコマンドや状態フィールドを登録してシステムを拡張することができます。これらは「モジュール」のセクションで別途説明されています。 :::

プロトコル規則

クライアントメッセージ1件につき1つの応答

このサービスは、クライアントから受信したメッセージ1件につき、すべてのデバイスの状態を含む1つの「State Update」メッセージを送信します。

これはつまり、

• デバイスの最新の状態を確認したい場合は、何らかのコマンド（セッションコマンド、プローブコマンド、またはデバイスコマンド）を送信する必要があります。
• このチャネルは、クライアントからのメッセージによって駆動される「ティック」ループのように動作します。

力を加えないポーリング（プローブコマンド）

力を加えたりシミュレーションパラメータを変更したりせずに状態の変化を観察したい場合は、プローブコマンドを使用してください：

• probe_position ～のために inverse3
• probe_orientation Verseグリップ用

プローブコマンドにはコマンドデータが含まれておらず、単にデバイス情報の照会を強制するだけであるため、次のステート更新時には位置・姿勢データが最新の状態になります。

構成と状態

• について 初期在庫 メッセージにはデバイスが含まれています config, stateそして status.
• 通常 州の最新情報 メッセージにはデバイスが含まれます state そして status.

設定情報を含むスナップショットを再度必要とする場合は、次のコマンドを使用してください session.force_render_full_state.

座標系

Haply 、デフォルトでZ軸が上向きの右利き座標系がHaply 。

座標の解釈と返却方法に影響を与えるセッションレベルの制御項目は2つあります：

• session.set_coordinate_origin: すべてのデバイスで使用される原点を変更します。
• session.set_basis:Haply アプリケーションの座標系との対応関係を変更します。

メッセージ形式

このセクションでは、概要的なエンベロープとメッセージの種類について説明します。具体的な例については、このドキュメントの後半で紹介します。

デバイスグループ

メッセージは最上位レベルでデバイスタイプごとにグループ化されます（例： inverse3, verse_grip, wireless_verse_grip). 各デバイスタイプのキーは、デバイスごとのオブジェクトの配列に対応付けられています。

初期インベントリ（サーバー → クライアント）

WebSocket接続が確立された直後に1回送信されます。

各項目には以下の内容が含まれます：

• device_id
• config
• state
• status

参照：例：初期在庫ペイロード

ステータス更新（サーバー → クライアント）

クライアントからのメッセージごとに1回送信されます。

各項目には以下の内容が含まれます：

• device_id
• state
• status

参照：例：ステート更新ペイロード

セッションコマンドのエンベロープ（クライアント→サーバー）

セッションコマンドは、現在の接続／セッションに適用されるアクションであり、特定のデバイスに依存するものではありません。

{
  "session": {
    "<command_name>": {
      "...": "..."
    }
  }
}

デバイスコマンドのエンベロープ（クライアント → サーバー）

デバイスコマンドは、デバイスタイプキーの下に配列として送信されるため、1つのメッセージで1つ以上のデバイスにコマンドを送信することができます。

{
  "<device_type>": [
    {
      "device_id": "<id>",
      "commands": {
        "<command_name>": {
          "...": "..."
        }
      }
    }
  ]
}

1つのメッセージに複数のエントリを含めることで、同じ種類の複数のデバイスを制御することができます。 なお、 commands これは辞書であり、特定のデバイスに対して複数のコマンドを扱うことができますが、コマンドの種類ごとに1つしか扱えません。

---

コマンドリファレンス

セッション

状態全体を強制レンダリング

すべてのデバイスの状態と設定のスナップショットを取得してください。

{
  "session": {
    "force_render_full_state": {}
  }
}

座標原点の設定

すべてのデバイスの座標原点を設定します。

{
  "session": {
    "set_coordinate_origin": {
      "coordinate_origin": "workspace_center"
    }
  }
}

使用可能な値：

• device_base (既定値)
• workspace_center

原点を workspace_center、その (0, 0, 0) 位置はデバイスの作業領域の中央に移動します。この位置はデバイスの種類によって異なります。

基本設定

現在のセッションの基底マッピングを設定します。 基底マッピングは、セッション全体を通じて、Haplyユーザーの座標系への変換方法を指定します。

基礎を固めた後：

• システムから返されるすべての状態は、その基底で表現される。
• 他のコマンドの一部として送信するすべての値は、その基準に基づいて解釈されます。

このマッピングHaply を基準として定義され、次の順列として表されます。 X, Y, Z、必要に応じて前に + または -. 有効な値の例：

• XYZ, ZYX
• +Y-Z+X, X-ZY

解釈例：

• YZX を意味する Y その通りです、 Z は前方へ、 X 公開されました。

Unrealのような左利き用Z-upシステムの例（X-YZ):

{
  "session": {
    "set_basis": {
      "basis": {
        "permutation": "X-YZ"
      }
    }
  }
}

すべてのデバイスのコマンド

プロービング（すべてのデバイス）

プローブコマンドを使用して、力を加えたりその他のシミュレーション変更を行ったりすることなく、最新の位置・姿勢情報を取得します。

• inverse3: probe_position
• ヴァース・グリップ（verse_grip, wireless_verse_grip): probe_orientation

{
  "inverse3": [
    {
      "device_id": "049D",
      "commands": {
        "probe_position": {}
      }
    }
  ],
  "verse_grip": [
    {
      "device_id": "049D",
      "commands": {
        "probe_orientation": {}
      }
    }
  ],
  "wireless_verse_grip": [
    {
      "device_id": "049D",
      "commands": {
        "probe_orientation": {}
      }
    }
  ]
}

Inverse3

コマンドを送信するには inverse3 デバイスには、一致するエントリを含める device_id ～の下で inverse3 キーだ。

1つのデバイスを操作する：

{
  "inverse3": [
    {
      "device_id": "049D",
      "commands": {
        "set_cursor_force": {
          "values": {
            "x": 1.0,
            "y": 2.0,
            "z": 3.0
          }
        }
      }
    }
  ]
}

1つのメッセージで複数のデバイスを操作する：

{
  "inverse3": [
    {
      "device_id": "049D",
      "commands": {
        "set_cursor_force": {
          "values": {
            "x": 1.0,
            "y": 2.0,
            "z": 3.0
          }
        }
      }
    },
    {
      "device_id": "049E",
      "commands": {
        "set_cursor_force": {
          "values": {
            "x": 1.0,
            "y": 2.0,
            "z": 3.0
          }
        }
      }
    }
  ]
}

カーソル位置の設定

{
  "inverse3": [
    {
      "device_id": "049D",
      "commands": {
        "set_cursor_position": {
          "values": {
            "x": 1.0,
            "y": 2.0,
            "z": 3.0
          }
        }
      }
    }
  ]
}

カーソルフォースの設定

{
  "inverse3": [
    {
      "device_id": "049D",
      "commands": {
        "set_cursor_force": {
          "values": {
            "x": 1.0,
            "y": 2.0,
            "z": 3.0
          }
        }
      }
    }
  ]
}

角度位置の設定

{
  "inverse3": [
    {
      "device_id": "049D",
      "commands": {
        "set_angular_position": {
          "values": {
            "a0": 1.0,
            "a1": 2.0,
            "a2": 3.0
          }
        }
      }
    }
  ]
}

設定角トルク

{
  "inverse3": [
    {
      "device_id": "049D",
      "commands": {
        "set_angular_torque": {
          "values": {
            "a0": 1.0,
            "a1": 2.0,
            "a2": 3.0
          }
        }
      }
    }
  ]
}

エクステンデッド・ヴァース・グリップ

について set_extension_data このコマンドは、Verseグリップ用の拡張プロトコルの一部であり、ボード拡張通信プロトコルを実装したグリップバージョンで使用されます。

セット・グリップ・エクステンション・データ

対応データ長：

• アップストリーム（クライアント→デバイス）は最大20バイト。
• ダウンストリーム（デバイス→クライアント）で最大12バイト。State Updateメッセージ内で以下のように返されます。 state.extension_data.

データ仕様：

• 配列の長さ：20バイト
• 値の範囲：各値は0～255

{
  "wireless_verse_grip": [
    {
      "device_id": "049D",
      "commands": {
        "set_extension_data": {
          "extension_data": [
            0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
          ]
        }
      }
    }
  ]
}

例

初期在庫ペイロード

WebSocketが接続されると、このサービスはデバイスの完全なリストを含むメッセージを送信します。最初のメッセージには以下の内容が含まれます JSON という形式をとっている：

{
  "inverse3": [
    {
      "device_id": "04BA",
      "config": {
        "type": "inverse3",
        "device_info": {
          "minor_version": 1,
          "major_version": 7,
          "id": "04BA",
          "model": 4,
          "uuid": "2D35F80DD9005F599B68F49944CB04BA"
        },
        "port": "COM13",
        "extended_device_id": "2D35F80DD9005F599B68F49944CB04BA",
        "extended_firmware_version": "8C20FDC8010AA1E15AA133CDA2534874",
        "gravity_compensation": {
          "enabled": true,
          "scaling_factor": 1
        },
        "handedness": "right",
        "torque_scaling": {
          "enabled": true
        }
      },
      "state": {
        "angular_position": {
          "a0": -69.31704,
          "a1": 137.62952,
          "a2": 19.832787
        },
        "angular_velocity": {
          "a0": 0,
          "a1": 0,
          "a2": 0
        },
        "body_orientation": {
          "x": -0.01940918,
          "y": 0.7026367,
          "z": 0.00048828125,
          "w": 0.7113037
        },
        "cursor_position": {
          "x": 0.07842738,
          "y": -0.14836666,
          "z": 0.14297646
        },
        "cursor_velocity": {
          "x": -0.011969013,
          "y": 0.0012009288,
          "z": -0.043197
        },
        "mode": "idle"
      },
      "status": {
        "calibrated": false,
        "in_use": false,
        "power_supply": true,
        "ready": true,
        "started": true
      }
    }
  ],
  "verse_grip": [
    {
      "device_id": "61548",
      "config": {
        "port": "COM3",
        "type": "verse_grip"
      },
      "state": {
        "button": false,
        "hall": 0,
        "orientation": {
          "x": -0.5019531,
          "y": 0.8632202,
          "z": -0.048095703,
          "w": -0.022338867
        }
      },
      "status": {
        "error": 0,
        "ready": true
      }
    }
  ],
  "wireless_verse_grip": [
    {
      "device_id": "0",
      "config": {
        "port": "COM6",
        "type": "wireless_verse_grip",
        "major_version": 1,
        "minor_version": 4,
        "hardware_version": 1
      },
      "state": {
        "battery_level": 0.816,
        "battery_voltage": 3.77,
        "buttons": {
          "a": false,
          "b": false,
          "c": false
        },
        "hall": 16,
        "orientation": {
          "x": -0.019866943,
          "y": -0.017486572,
          "z": 0.05508423,
          "w": -0.9963989
        }
      },
      "status": {
        "connected": true,
        "awake": true,
        "ready": true
      }
    }
  ]
}

州の最新情報ペイロード

このサービスは、受信したメッセージごとに、すべてのデバイスの状態を含む状態更新メッセージを1つ送信します。

マシンの状態を確認したい場合は、事前にメッセージ（例えば、プローブコマンドや力値など。値がゼロであっても構いません）を送信する必要があります。これは、力を加えることなくデバイスを入力ソース（位置追跡など）として使用する際に、特に重要です。

ステータス更新メッセージには以下の内容が含まれています JSON という形式をとっている：

{
  "inverse3": [
    {
      "device_id": "04BA",
      "state": {
        "angular_position": {
          "a0": -69.31704,
          "a1": 137.62952,
          "a2": 19.832787
        },
        "angular_velocity": {
          "a0": 0,
          "a1": 0,
          "a2": 0
        },
        "body_orientation": {
          "x": -0.01940918,
          "y": 0.7026367,
          "z": 0.00048828125,
          "w": 0.7113037
        },
        "cursor_position": {
          "x": 0.07842738,
          "y": -0.14836666,
          "z": 0.14297646
        },
        "cursor_velocity": {
          "x": -0.011969013,
          "y": 0.0012009288,
          "z": -0.043197
        },
        "mode": "idle"
      },
      "status": {
        "calibrated": false,
        "in_use": false,
        "power_supply": true,
        "ready": true,
        "started": true
      }
    }
  ],
  "verse_grip": [
    {
      "device_id": "61548",
      "state": {
        "button": false,
        "hall": 0,
        "orientation": {
          "x": -0.5019531,
          "y": 0.8632202,
          "z": -0.048095703,
          "w": -0.022338867
        }
      },
      "status": {
        "error": 0,
        "ready": true
      }
    }
  ],
  "wireless_verse_grip": [
    {
      "device_id": "0",
      "state": {
        "battery_level": 0.816,
        "battery_voltage": 3.77,
        "buttons": {
          "a": false,
          "b": false,
          "c": false
        },
        "hall": 16,
        "orientation": {
          "x": -0.019866943,
          "y": -0.017486572,
          "z": 0.05508423,
          "w": -0.9963989
        }
      },
      "status": {
        "ready": true
      }
    }
  ],
  "custom_verse_grip": [
    {
      "device_id": "0",
      "state": {
        "battery_level": 0.816,
        "battery_voltage": 3.77,
        "buttons": {
          "a": false,
          "b": false,
          "c": false
        },
        "hall": 16,
        "orientation": {
          "x": -0.019866943,
          "y": -0.017486572,
          "z": 0.05508423,
          "w": -0.9963989
        },
        "extension_data": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
      },
      "status": {
        "ready": true
      }
    }
  ]
}