Unity 内の箱庭ロボットを動かすPython API仕様書

本記事は、パソコン上で Unity 内の箱庭ロボットをPythonプログラムで動かすためのAPIについて解説する記事です。

ベースとなるアーキテクチャの解説はこちらを参照ください。

アーキテクチャ

本記事で解説する範囲は、下図のPythonプログラム（赤枠内）のところです。

そして、上図をより細かくレイヤ分けするとこんな感じになります。

ロボット制御アプリが利用できる API は、以下の３モジュールになります。

• hako_env
• hako_robomodel_any
• hako

hako_env

本モジュールは、箱庭のシミュレーション実行制御を行う機能を提供します。

make(model_name, robo_type, model_filepath = None)

• 機能
  • 箱庭環境を作成します。
• 引数
  • model_name
    • Unity上で作成した箱庭ロボットの名前を指定してください
  • robo_type
    • 常に any を指定してください
  • model_filepath
    • 常に、dev/ai/custom.jsonを指定してください
    • このファイルは、Unity上の箱庭コンフィギュレーションの Generate で自動生成されます。
    • custom.json は、箱庭ロボットの I/O 用のインタフェース仕様が定義されたファイルです。
• 戻り値：HakoEnvオブジェクト

HakoEnv.robo()

• 機能
  • make() の第一引数　model_name で作成した箱庭ロボット制御用のオブジェクトを返します。
• 引数 : なし
• 戻り値 : HakoRoboModelAnyオブジェクト

HakoEnv.reset()

• 機能：
  • 箱庭シミュレーションをリセットします。
• 引数 : なし
• 戻り値 : なし

hako_robomodel_any

本モジュールは、Unity内の箱庭ロボットに対して I/O を行う機能を提供します。

HakoRoboModelAny.get_state(name, obserbation)

• 機能
  • 当該箱庭ロボットのセンシングデータ一式を取得します。
• 引数
  • name
    • センシングデータ名
    • custom.jsonのorg_nameを設定してください。
  • obserbation
    • hakoモジュールの execute() メソッドの戻り値を指定してください。
      • execute()実行結果として、センシングデータ一式が返ってきます。
• 戻り値 :　当該センシングデータ

HakoRoboModelAny.get_action(name, obserbation)

• 機能
  • 当該箱庭ロボットのセンシングデータ一式を取得します。
• 引数
  • name
    • アクチュエータ名
    • custom.jsonのorg_nameを設定してください。
• 戻り値 :　当該アクチュエータ指示データ

hako

本モジュールは、C++版箱庭コア機能のAPIを提供します（Python用に使いやすくしています）。

補足：libshako.so は、hakoc というモジュールでアクセスします。

Hako.execute()

• 機能
  • 箱庭ロボットのシミュレーションを１ステップ進めます。
• 引数：なし
• 戻り値 :　当該ロボットのセンサデータ

Hako.wait_event(ev)

• 機能
  • 箱庭のシミュレーションイベントが発生するのを待ちます。
• 引数
  • ev
    • 待ち合わせしたいイベント
      • HakoEvent['START']
      • HakoEvent['STOP']
      • HakoEvent['RESET']
• 戻り値 :　なし

Hako.wait_state(expect_state)

• 機能
  • 箱庭のシミュレーションイ状態が期待する状態になるのを待ちます。
• 引数
  • expect_state
    • 期待する状態
      • HakoState['STOPPED']
      • HakoState['RUNNABLE']
      • HakoState['RUNNING']
      • HakoState['STOPPING']
      • HakoState['RESTTING']
• 戻り値 :　なし

Hako.write_pdu(channel_id, pdu_json)

• 機能
  • 当該ロボットのアクチュエータ指示値(pdu_json)を書き込みします。アクチュエータは channel_id で指定します。
• 引数
  • channel_id
    • アクチュエータのID
    • 具体的なID値は、custom.jsonで定義されています。
  • pdu_json
    • アクチュエータ指示値
• 戻り値 :　なし

以下、工事中・・・