箱庭(Hakoniwa) Python-Asset 合同会社箱庭ラボ 森崇

はじめに • この資料では、Pythonで箱庭アセット作るための情報を整理しています。 • 前提とする環境 • GitHubリポジトリ情報 • 箱庭Python環境のインストール⽅法 • 箱庭Python APIの概要説明 • 箱庭Python APIのサンプルプログラム説明 • 箱庭UnityアセットをPythonで制御してみよう 2

前提とする環境 • OS︓Windows、MacOS、Ubuntu • メモリ︓8GB以上 • Python︓version 3.12 以上 • Visual Studio（ネイティブWindowsの場合） • MMAP環境 • １つのパソコンの中で複数の箱庭アセットを通信する場合はMMAPファイルを使います。 • MMAPとは、アプリケーションが通常ファイルをメモリアクセスできるようにするためのOSの機能です。 • そのための通常ファイルをMMAPファイルと呼びます。 • Unityと連携する際の性能改善⽅法 • UnityとPythonを連携させる場合、通常ファイルへのアクセスが性能ネックになる可能性があります。 • その場合は、通常ファイル⾃体をRAMDISKに配置することで⼤幅な改善が⾒込めます。 3

GitHubリポジトリ情報 • URL • https://github.com/toppers/hakoniwa-core-cpp-client • リポジトリ名 • hakoniwa-core-cpp-client • 説明 • 箱庭コア機能のAPI部分を管理しています。 • bindings配下にPython APIがあります。 • ライセンス • TOPPERSライセンス 4

箱庭Python環境のインストール⽅法 • Python環境のインストール⼿順は以下のステップで⾏います。 • 箱庭コア機能のインストール • ネイティブWindowsの場合 • Windows以外の場合 • MMAPファイルの設定 • ネイティブWindowsの場合 • Windows以外の場合 • RAMDISKの作成 • RAMDISKは、Ubuntu、MacOSの場合は標準で備わっている機能です。 • ネイティブWindowsの場合ImDiskというツールを利⽤することで導⼊できます。 • 参考︓ • https://avalon-studio.work/blog/windows/ram-disk-configration/ • ImDiskダウンロード場所︓ • https://sourceforge.net/projects/imdisk-toolkit/ • ⾼速スタートアップの設定︓ • https://www.fmworld.net/cs/azbyclub/qanavi/jsp/qacontents.jsp?PID=2111-3152 5

箱庭Python APIの概要説明 • APIの種類 • シミュレーション管理・制御⽤のAPI(hakopy) • PDUデータI/O⽤のAPI(hako_pdu) • イベントの種類 • 処理フロー • コンフィグファイルの説明 6

callbacks シミュレーション管理・制御⽤のAPI(1/2) • モジュール名︓hakopy 7 箱庭API（C⾔語） 共有メモリ ロボット１ CH1 CH2 CH3 箱庭コア機能 asset_register usleep simulation_time start 箱庭API（C⾔語） PDU I/O イベント プラント モデル 制御 モデル HAKO_ASSET_ MODEL_PLANT HAKO_ASSET_ MODEL_CONTROLLER

シミュレーション管理・制御⽤のAPI(2/2) • モジュール名︓hakopy 8 API名 概要 対応するC API asset_register() 箱庭アセットを登録する hako_asset_register() start() シミュレーションを開始する hako_asset_start() simulation_time() シミュレーション時間を取得する hako_asset_simulation_time() usleep() スリープする hako_asset_usleep()

PDUデータI/O⽤のAPI(1/2) 9 共有メモリ 箱庭API（C⾔語） ロボット１ ロボット２ CH1 CH2 CH3 C H 1 C H 2 CH3 HakoPdu Manager 箱庭アセット コンフィグ get PDUデータ (Dict) HakoPdu︓ ロボット2、CH3 ロボット名︓ロボット２ チャネルID︓CH3 get read write

PDUデータI/O⽤のAPI(2/2) • モジュール名︓hako_pdu 10 クラス API名 概要 HakoPduManager get_pdu() PDUデータを管理するHakoPduインスタンスを取得する PDUデータの指定には、ロボット名とチャネルIDを指定 HakoPdu get() PDUデータのインスタンスを取得する write() PDUデータを共有メモリに書き込みする read() PDUデータを共有メモリから読み込みする

イベントの種類 • シミュレーションに必要な機能をイベント関数として登録します 11 on_initialize on_simulation_step on_reset on_manual_timing_control 箱庭コ ア機能 asset_register start 箱庭API（C⾔語） callbacks (いずれか⼀⽅) 初期化処理 シミュレーション 実⾏処理 リセット処理

処理フロー 12

コンフィグファイルの説明 • 箱庭アセットを登録する際、PDUデータのメモリ領域を確保します。 • ⼊⼒情報として、箱庭アセットコンフィグファイルを指定します。 • 登録する箱庭アセットの種類に応じて作成するPDUデータが変わります • プラントモデルの場合︓ • rpc_pdu_writers、shm_pdu_writers • 制御モデルの場合︓ • rpc_pdu_readers、shm_pdu_readers 13 プラント モデル 制御 モデル HAKO_ASSET_ MODEL_PLANT HAKO_ASSET_ MODEL_CONTROLLER 共有メモリ ロボット１ CH1 CH2 箱庭アセット コンフィグ rpc_pdu_writers、shm_pdu_writers rpc_pdu_readers、shm_pdu_readers

箱庭Python APIのサンプルプログラム説明 • hello_world • hello_world.py • 箱庭アセットコンフィグファイル • pdu_communication • asset_plant.py • asset_controller.py • 箱庭アセットコンフィグファイル 14

箱庭UnityアセットをPythonで制御してみよう • 利⽤する箱庭Unityアセットの確認 • ロボットの仕様 • ロボットのPDUデータ仕様 • Pythonでの制御内容を検討する • Pythonで制御プログラムを作成する • 動作確認する 15

ロボットの仕様 16 基本機能 ロボット部品 実現⽅法 遠隔操縦 アクチュエータ 作動モーターにタイヤを２個つけて実現する キャスター バックに球形コライダーを２個つける 障害物検出 超⾳波センサ センサの有効範囲は５mとして、 ４⽅向監視する ・左(-90度)、右(90度) ・斜め左（-10度）、斜め右（10度） 衝突検出 バンパーセンサ 衝突検出︓ON ⾮検出時︓OFF 荷物着脱検出 荷物着脱検出センサ 荷物あり︓ON 荷物なし︓OFF 荷物運搬 荷物運搬⽤BOX コライダーを４⽅につける Body 荷物運搬⽤BOX キャスター アクチュエータ バンパー 超⾳波 センサー 荷物着脱 検出センサ バンパー キャスター 超⾳波 センサー アクチュエータ

ロボットのPDUデータの仕様 17 部品 通信データ型 通信データ名 送信周期 アクチュエータ geometry_msgs/Twist cmd_vel - 超⾳波センサ pico_msgs/LightSensor ultrasonic_sensor 20msec バンパーセンサ std_msgs/Bool bumper_sensor 20msec 荷物着脱検出センサ std_msgs/Bool baggage_sensor 20msec

Pythonでの制御内容を検討する • 制御内容 • 荷物をロボットが置かれたら、⽬的位置へ移動し停⽌する • 利⽤するセンサ • 荷物着脱検出センサ • 超⾳波センサ • 制御周期 • 20msec(Unityのデフォルトと同じにする) 18 ⽬的地 Body 荷物運搬⽤BOX 2m ⽬的地を検出する ためのオブジェクト 荷物

Pythonで制御プログラムを作成する(1/3) • 制御設計 19 初期状態 移動状態 停⽌状態 (荷物検出し、３秒経過) (超⾳波センサ・前⽅距離が2.5m以下) 前進指⽰ 停⽌指⽰ 停⽌指⽰ モーター指令 on_initialize on_simulation_step 制御状態 イベント関数

Pythonで制御プログラムを作成する(2/3) • サンプルコード 20

Pythonで制御プログラムを作成する(3/3) • サンプルコード 21

動作確認する 22 https://www.youtube.com/watch?v=caX3SA0ysPA