Hakoniwa-python-asset

箱庭(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

• https://github.com/toppers/hakoniwa-core-cpp-client
• https://www.toppers.jp/license.html

箱庭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

• https://github.com/toppers/hakoniwa-core-cpp-client/tree/main?tab=readme-ov-file
• https://avalon-studio.work/blog/windows/ram-disk-configration/
• https://sourceforge.net/projects/imdisk-toolkit/
• https://www.fmworld.net/cs/azbyclub/qanavi/jsp/qacontents.jsp?PID=2111-3152

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

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

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

• https://github.com/toppers/hakoniwa-core-cpp-client/tree/main?tab=readme-ov-file

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

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

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

処理フロー 12

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

• https://github.com/toppers/hakoniwa-core-cpp-client/tree/main?tab=readme-ov-file

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

• https://github.com/toppers/hakoniwa-core-cpp-client/tree/main/examples/hello_world
• https://github.com/toppers/hakoniwa-core-cpp-client/blob/main/examples/hello_world/hello_world.py
• https://github.com/toppers/hakoniwa-core-cpp-client/blob/main/examples/hello_world/custom.json
• https://github.com/toppers/hakoniwa-core-cpp-client/tree/main/examples/pdu_communication
• https://github.com/toppers/hakoniwa-core-cpp-client/blob/main/examples/pdu_communication/asset_plant.py
• https://github.com/toppers/hakoniwa-core-cpp-client/blob/main/examples/pdu_communication/asset_controller.py
• https://github.com/toppers/hakoniwa-core-cpp-client/blob/main/examples/pdu_communication/custom.json

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

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

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

• https://github.com/toppers/hakoniwa-ros2pdu/blob/main/pdu/json/geometry_msgs/Twist.json
• https://github.com/toppers/hakoniwa-ros2pdu/blob/main/pdu/json/pico_msgs/LightSensor.json
• https://github.com/toppers/hakoniwa-ros2pdu/blob/main/pdu/json/std_msgs/Bool.json

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

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

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

• https://github.com/toppers/hakoniwa-core-cpp-client/blob/main/examples/unity_sample/asset_controller.py

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

• https://github.com/toppers/hakoniwa-core-cpp-client/blob/main/examples/unity_sample/asset_controller.py

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

• https://www.youtube.com/watch?v=caX3SA0ysPA