Skip to content
This repository was archived by the owner on Aug 15, 2024. It is now read-only.

v hsc_simulator_api_draft2の和訳

Jump to bottom
Yasuo Hayashibara edited this page Apr 24, 2021 · 7 revisions

バーチャルサッカー競技のAPI仕様【暫定版

このドキュメントは予備的なものであり、次回のメジャーアップデートは4月19日に公開される予定です。次のバージョンでは、選択したサーバーの性能に合わせて、帯域幅や更新頻度を変更する可能性があります。このドキュメントに記載されていない要素をサポートする必要があると思われる場合は、できるだけ早くTCに連絡してください。

本ドキュメントは、各チームのソースコードと競技用シミュレータとのインターフェースについて説明する。より正確には、以下の点に焦点を当てています。

  • シミュレーターに指示を出すためにチームが提供する設定ファイルの定義
  • ロボットを制御するプログラムとシミュレータの間の通信を可能にするためのプロトコル

以下では、この用語を使用します。

  • ロボット」または「ロボットモデル」とは、シミュレートされた環境内で行動し、感知する仮想のロボットのことであり
  • ロボット制御ソフトウェアとは、チームによって実装され、シミュレータ環境の外で動作するロボットの動作ソフトウェアを指します。

一般的な側面

ゲーム中のロボットの制御は、シミュレータとロボット制御ソフトウェアの間のカスタムTCPプロトコルに基づく非同期通信によって行われます。

このプロトコルはproto3メッセージをベースにしています。現在のprotobufファイルはWebotsのgithubで見ることができます。

物理シミュレーションの各ステップの後、シミュレータはセンサーから得られるすべての新しいデータを含むメッセージを送信します。

2つのセンサーが更新されるまでの最小ステップは以下のように選択されます。

  • カメラデータ：2つの連続したフレーム間の最小時間はminFrameStepと表記され、16msとなります。
  • 他のセンサー：2つの更新の間の最小時間はminControlStepと呼ばれ、シミュレーションに使用される物理的なタイムステップに応じて4msまたは8msになります。

ROSとROS2のブリッジ

TCPプロトコルとROSまたはROS2トピックとの間のブリッジを可能にするシンプルなパッケージが提供されます。このパッケージは、ロボット制御ソフトウェアの一部として実行する必要があります。そのため、これらのブリッジを使用すると、処理に若干の遅れが生じます。

設定ファイル

シミュレータは、JSON形式で書かれたチームごとの設定ファイルを必要とします。そのような設定ファイルの例は、付録で提供されています。設定ファイルには、2つのエントリを持つ辞書が含まれています。

  • name: string 12文字以内のチームタグ
  • players: Playersの辞書 プレイヤーのリストとそのプロパティ

プレイヤーのエントリーは、ロボットのIDをキーとし、以下のプロパティを値として持っています。

  • robotModelName: string このロボットに使用するモデルの名前です。これはヒューマノイドリーグの投稿システムで投稿されたファイル名と一致する必要があります。
  • dockerImg: string このロボットの制御ソフトウェアを含むdockerイメージ
  • dockerCmd: string dockerImgの起動に使用するCMDです。
  • halfTimeStartingPose: Pose ハーフタイム開始時のロボットのポーズです。
  • reentryStartingPose: Pose Robot pose after a removal penalty.
  • shootoutStartingPose: PK戦でのPose Robotポーズ。

チームは、プレイヤー辞書への登録数を減らすことで、リーグで認められている最大数よりも少ない数のロボットでゲームを開始することができます。ただし、これはゲーム中に変更することはできません。例えば、あるチームが1台のロボットでプレイすることを決め、そのロボットがレッドカードを受けた場合、そのチームはフィールド上にロボットがいない状態でゲームを終えなければなりません。

Poseオブジェクトは、ロボットを配置するためのトランスフォームを定義します。

  • translation: float[3] ロボットがスポーンされるべき[x,y,z]座標です。
  • rotation: float[4] [rx,ry,rz,angle] [rx,ry,rz]は正規化されたベクトルで、angleはラジアン単位の回転角を表します。

ポーズとは、次のような参照方法で定義されます。

  • 原点はグランドレベルでのフィールドの中心
  • X軸は、相手ゴールの中心を指す
  • Z軸はグラウンドと直交する空の方向を指す

reentryStartingPoseは、yに負の値を指定し、ロボットがフィールドの外で完全にペナルティマークに直面するようにしなければならない。代替ポーズは、XZ平面に沿った鏡面対称性またはX軸に沿ったオフセットを用いて自動的に調整される。

チームは、初期位置がルールに適合していることを確認してください。そうでない場合は、次のような違反を繰り返す危険性があります。

プロトコル

シミュレータへの接続を開始する

シミュレータとの通信を開始するために、ロボット制御ソフトは環境変数ROBOCUP_SIMULATOR_ADDRで定義されたアドレスに接続する必要があります（例：192.168.1.100:10001）。ポートのデフォルトは

  • 10000 + ROBOT_IDで赤チーム
  • 10020 + 青チームのROBOT_ID

シミュレータには、各ロボットのIPアドレスが通知されます。そのため、他のロボットへの接続試行は失敗します。さらに、すべての接続試行はゲーム中に記録されます。万が一、他のチームのロボットへのシステム的な接続試行が記録された場合、不正な接続を行ったチームは制裁を受けることになります。 ゲーム中にロボットが切断された場合は、同じポートに再接続できるようにしなければならない。

通信の終了

クライアントが応答しなくなったり、メッセージの処理が遅かったりして、シミュレータの通信キューがいっぱいになった場合、他のクライアントへのサービスの質を維持し、シミュレーションを適度な速度に保つために、シミュレータはそのクライアントとの接続を中断しなければならない。このような中断は、シミュレータのログに記録されます。 ゲーム終了時には自動的に接続が切断され、GameControllerメッセージによってロボットコントローラソフトウェアにゲームの現在の状態が通知されます。

センサーメッセージ

ロボットは以下の情報を含むSensorMeasurementsメッセージを定期的に受信する。

  • time : 測定が行われたダブルタイムスタンプ（単位：秒
  • message : メッセージ[]
    • message_type: メッセージタイプ エラーまたは警告
    • text: 文字列の説明文
  • accelerometer : 加速度センサー測定値[].
    • name : 文字列
    • value : double[3] [m/sˆ2], x軸, y軸, z軸
  • bumper : バンパー計測値[] (BumperMeasurement[])
    • name : 文字列
    • value : boolean
  • camera : CameraMeasurement[] (カメラ計測)
  • name : 文字列
    • width : int
    • height : int
    • quality : int -1 = 生の画像、100 = 圧縮なし、0 = 高圧縮。現在，圧縮は行われていない．
    • image : char[] 生のRGBデータ（quality<0の場合）、それ以外はJPEGエンコードされたデータ
  • force : ForceMeasurement[]の略。
    • name : 文字列
    • value : double [N]
  • force3d : フォース3DMeasurement[] (フォース3DMeasurement)
    • name : 文字列
    • value : double[3] [N], X軸, Y軸, Z軸
  • gyro : ジャイロ計測値[].
    • name : 文字列
    • value : double[3] [rad/s], X軸, Y軸, Z軸
  • position_sensor : 位置センサー計測値[] : string
    • name : 文字列
    • value : double [rad] or [m]

各チームの通信速度は50MB/sに制限されています。この帯域幅は、チームの設定ファイルで定義されたN台のロボットに均等に分配されます。したがって，各ロボット制御ソフトウェアは，50/N MB/sの帯域幅を個別に持つことになります。ロボットが予算を超えた場合（1秒単位の履歴）、パケットは廃棄されます。

メッセージの送信

各ロボットは、以下のタイプのコマンドのリストを含む1つのメッセージを送信する。

  • motor_positions : MotorPosition[] (モーターポジション)
    • name : 文字列
    • position : double [m] or [rad]
  • motor_velocity : モーターベロシティ[].
    • name : 文字列
    • velocity: 倍 [m/s] または [rad/s]
  • motor_force : MotorForce[] （モーターフォース
    • name : 文字列
    • force : double [N] (力)
  • motor_torque : MotorTorque[] (モータートルク)
    • name : 文字列
    • torque : 2倍 [N.m]
  • motor_pid : MotorPID[] ドキュメント参照
    • name : 文字列
    • PID : double[3] [P,I,D]コントローラ値
  • sensor_time_step : SensorTimeStep[] 参照
    • name : 文字列
    • timeStep : int 2つの測定値の間の時間[ms]、0の場合はセンサーを無効にする
    • リクエストがセンサーの最小タイムステップよりも低い場合（0ではない）、最小タイムステップが使用されます。
    • 注：カメラのセンサーについては、以下の通りです。
      • カメラの解像度を動的に変更することはできませんが、ゲーム中に同じ位置にあるカメラを有効にしたり無効にしたりして、固定された解像度の間で変更することは可能です。同じ位置、同じ向きで同じ視野に配置されたカメラは、ゲームの法則上、別のカメラとしては扱われません。
  • camera_quality : CameraQuality[] (カメラ品質)
    • name : 文字列
    • quality : int -1 = 生画像、100 = 圧縮なし、0 = 高圧縮。現在、圧縮は実装されていません。
  • camera_exposure : CameraExposure[] (カメラエクスポージャー)
    • name : 文字列
    • exposure : float unit: [J/mˆ2]

付録

json構成の例

{
"name": "teamA",
"players": {
"1": {
"robotModelName": "robotA",
"dockerImg": "teamA_robotA",
"dockerCmd": "launchRobot.sh --goalie",
"halfTimeStartingPose": {
"translation": [-3.5, -3.06, 0.24],
"rotation": [0, 0, 1, 1.57]
},
"reentryStartingPose": {
"translation": [-3, -3.11, 0.24],
"rotation": [0.0, 0.707, 0.707, 3.14]
},
"shootoutStartingPose": {
"translation": [2, 0, 0.24],
"rotation": [-0.57735, -0.57735, -0.57735, -2.0944]
}
},
"2": {
"robotModelName": "robotA",
"dockerImg": "teamA_robotA",
"dockerCmd": "launchRobot.sh --fieldPlayer",
"halfTimeStartingPose": {
"translation": [-3.5, 3.06, 0.24],
"rotation": [0, 0, 1, -1.57]
},
"reentryStartingPose": {
"translation": [-3, -3.11, 0.24],
"rotation": [0.0, 0.707, 0.707, 3.14]
},
"shootoutStartingPose": {
"translation": [2, 0, 0.24],
"rotation": [-0.57735, -0.57735, -0.57735, -2.0944]
}
},
"3": {
"robotModelName": "robotB",
"dockerImg": "teamA_robotB",
"dockerCmd": "launchRobot.sh --fieldPlayer",
"halfTimeStartingPose": {
"translation": [-0.75, -3.06, 0.24],
"rotation": [0, 0, 1, 1.57]
},
"reentryStartingPose": {
"translation": [-3, -3.11, 0.24],
"rotation": [0.0, 0.707, 0.707, 3.14]
},
"shootoutStartingPose": {
"translation": [2, 0, 0.24],
"rotation": [-0.57735, -0.57735, -0.57735, -2.0944]
}
},
"4": {
"robotModelName": "robotB",
"dockerImg": "teamA_robotB",
"dockerCmd": "launchRobot.sh --fieldPlayer",
"halfTimeStartingPose": {
"translation": [-0.75, 3.06, 0.24],
"rotation": [0, 0, 1, -1.57]
},
"reentryStartingPose": {
"translation": [-3, -3.11, 0.24],
"rotation": [0.0, 0.707, 0.707, 3.14]
},
"shootoutStartingPose": {
"translation": [2, 0, 0.24],
"rotation": [-0.57735, -0.57735, -0.57735, -2.0944]
}
}
}
}
Clone this wiki locally