箱庭_HelloWorld_Guide

HAKONIWA SIMULATOR 箱庭シミュレータ入門 hello_world で学ぶ 箱庭アセットの作り方 コンセプト · アーキテクチャ · ライフサイクル · 時間同期 · 実行手順 hakoniwa-core-pro / examples/hello_world 2026-06-01

WHAT IS HAKONIWA 箱庭とは何か — コンセプト 複数のシミュレーション要素（アセット）を、 アセット PDU 共通の時刻で協調動作させる分散シミュレーション基盤。 参加する1要素。ユーザが作る 交換するデータの単位（ROS互換 型） コンダクタ hako-master 時刻を進める指揮者 時刻管理・データ同期のコア delta_time 世界時刻 1ステップの時間幅 (usec) 全アセット共通の仮想時刻 • ロボット制御・センサ・物理モデル・外部システムを、 独立したプロセスとして実装できる • 各アセットは別プロセス（C / C++ / Python / Unity） で動作 • 共有メモリ (SHM) を介してデータ (PDU) を交換 • 全アセットを同じ仮想時刻で歩調合わせ → 箱庭が時刻 同期を担う hello_world はデータ交換をしない「最小アセット」。ライフサイクルの学習に集中できる。 箱庭入門 · hello_world 02

ARCHITECTURE 全体アーキテクチャ ユーザが書く部分 Asset（hello_world） 読み解きのポイント C / C++ / Python のコールバック実装 API 呼び出し hakoniwa-core-pro libhako / assets アセットAPIを提供 hako-conductor 時刻を進める hako-cmd start / stop / reset • ユーザはアセットを書くだけ • コンダクタは hello_world と 同じプロセス内のスレッド • hako-cmd は別端末・別プロ セス • 通信はすべて共有メモリ上で 行われる 共有メモリ経由で通信 hakoniwa-core-cpp hako-master 時刻管理・共有メモリ・アセット間データ同期 箱庭入門 · hello_world 03

OVERVIEW hello_world の全体像 ディレクトリ構成 hello_world がやること hello_world/ ├─ README.md │ 実行手順（期待ログ付き） ├─ CMakeLists.txt │ 箱庭にアセットとして登録する ビルド定義 ├─ custom.json │ アセット構成 ├─ pdutypes.json │ PDU 型・チャネル定義 ├─ src/hello_world.c │ C 実装（本体） 初期化・1ステップ・リセットの各タイミングで 「ログを出して1秒寝る」だけ └─ hello_world.py Python 実装（等価） 数値計算もデータ交換もしない → ライフサイクルの学習に集中できる 箱庭入門 · hello_world 04

CONFIGURATION 設定ファイルの仕組み custom.json — アセット構成 読み込みの流れ（コア実装） { "paths": [ { "id":"default", "path":"pdutypes.json" } ], "robots": [ { "name":"ROBOT", "pdutypes_id":"default" } ] } custom.json robots を宣言 pdutypes.json channel / size を解決 pdutypes.json — PDU 定義 [ { "channel_id":0, "pdu_size":48, "name":"motor", "type":"geometry_msgs/Twist" } create_pdu_lchannel() 共有メモリ上に PDU を確保 ] hello_world は PDU を読み書きしないが、登録時にこの定義どおり共有メモリ上へチャネルが作られる。 箱庭入門 · hello_world 05

MAIN FUNCTION プログラムの骨格 — 4ステップ定型 1 conductor_start 時刻を進める担当を起動 2 asset_register 箱庭に自分を登録 int main(int argc, const char* argv[]) { const char* asset_name = argv[1]; const char* config_path = argv[2]; hako_time_t delta = atoi(argv[3]) * 1000; 4 asset_start 実行（コールバック駆動） conductor_stop 後始末 登録時の検証 • step と manual の同時設定は EINVAL • 設定ファイルが無ければ ENOENT • delta が小さすぎると EINVAL • model は PLANT / CONTROLLER // msec→usec hako_conductor_start(delta, delta); // ① hako_asset_register(asset_name, config_path, // ② &my_callback, delta, HAKO_ASSET_MODEL_CONTROLLER); while (1) { hako_asset_start(); // ③ } hako_conductor_stop(); // ④ 箱庭入門 · hello_world 3 06

LIFECYCLE ライフサイクルと 4 つのコールバック hello_world の実装（抜粋） on_initialize 契機: hako-cmd start 直後（1回） 用途: センサ初期化・初期値設定 on_simulation_step 契機: 毎ステップ（同期モード） 用途: 制御計算・状態更新 // step では world時刻を取得: hako_asset_simulation_time(); on_manual_timing_control 契機: 開始後1回（手動モード） static int my_on_initialize( hako_asset_context_t* c) { printf("enter"); usleep(1000*1000); // 1秒 printf("exit"); return 0; // 0 = 正常 } 用途: 自前で時間を進める高度制 御 on_reset 契機: hako-cmd reset 時 箱庭入門 · hello_world 用途: 内部状態のクリア 戻り値 0 が「正常」。step と manual は排他（同時設定不可 ）。 07

TIME SYNCHRONIZATION — 箱庭の核心 時間同期の仕組み 「世界時刻が進むまで、各アセットは次のステップに進めない」 world_time 0 Δ 2Δ 3Δ Asset A Asset B → 同じ時刻で1歩ずつ。プロセス・言語が違っても全アセットがフレーム単位で同期する。 notify_simtime next > world_time ? on_simulation_step 自分の時刻を master に通知 真なら待機（同期点） 偽なら1ステップ実行 箱庭入門 · hello_world 08

STATE & LOGS 状態遷移とログの読み方 起動〜実行のシーケンス 主要ログと意味 1 register() 登録完了 ログ 意味 WAIT START start 待ち WAIT START start を待っている 2 my_on_initialize enter/exit 初期化コールバック実行中 SYNC MODE: true PDU同期モードで動作中 on_simulation_step enter: 100000 ステップ実行（数字=世界時刻 usec） NOT RUNNING: curr = 3 停止指示を検知 WAIT STOP / WAIT RESET 停止／リセット待ち EVENT: reset リセット完了でループ脱出 3 4 5 on_initialize() PDU CREATED 初期化実行 PDU確保完了 on_simulation_step() 箱庭入門 · hello_world 毎ステップ実行 09

EXECUTION MODELS 同期モード vs 手動モード 同期モード 手動モード 起動引数 起動引数 4個（manual なし） 5個（末尾に manual） コールバック コールバック on_simulation_step on_manual_timing_control 時刻の進め方 時刻の進め方 箱庭が毎ステップ呼ぶ hako_asset_usleep() で自前 向いている用途 向いている用途 一般的な周期制御 受信待ち・可変周期 箱庭入門 · hello_world 手動モードの実装 while (result == 0) { // シミュ時刻を進める result = hako_asset_usleep(1000); usleep(1000*1000); } hako_asset_usleep() = 指定マイクロ秒ぶん「シミュレーション時 刻」を進める。実時間スリープではない。 10

HOW TO RUN 実行手順 — 2 端末モデル 端末A — アセット起動 端末B — シミュレーション制御 $ ./hello_world HelloWorld custom.json 100 $ hako-cmd start → 端末Aで初期化〜実行が開始 asset(...) is registered. WAIT START ← 待機 $ hako-cmd stop $ hako-cmd reset → on_reset hako-master + 共有メモリ (SHM) アセットと操作コマンドを別端末で動かし、共有メモリ越しに hako-master が同期する。 箱庭入門 · hello_world 11

C & PYTHON

C 版と Python 版は対称
Python はコールバックを辞書で渡す

処理

C

コンダクタ起動

hako_conductor_start(d,d)

hakopy.conductor_start(d,d)

アセット登録

hako_asset_register(...)

hakopy.asset_register(...)

開始

hako_asset_start()

hakopy.start()

世界時刻取得

hako_asset_simulation_time()

hakopy.simulation_time()

シミュ時刻スリープ

hako_asset_usleep(usec)

hakopy.usleep(usec)

コールバック登録

構造体 callbacks_t

辞書 {'on_initialize':...}

箱庭入門 · hello_world

(hello_world.c)

Python

(hello_world.py)

my_callback = {
'on_initialize':
my_on_initialize,
'on_simulation_step':
my_step,
'on_reset': my_reset,
}

Python サンプルの実行には pip install
hakoniwa-pdu が必要。

12

SUMMARY まとめ 「コンダクタ起動 → 登録 → 開始」の 4 ステップ定型で書ける 本体は 4 つのコールバック（initialize / step / manual / reset） NEXT STEP pdu_communication アセット間のデータ交換 service 設定は custom.json（構成）＋ pdutypes.json（PDU定義）の宣言だけ RPC（要求/応答）通信 external 時刻同期は「世界時刻が進むまで次へ進めない」仕組みで全アセットが歩調合 わせ 実行は 2 端末モデル（アセット / hako-cmd）。C と Python は対称な API hello_world を理解すれば、次のサンプルへ自然に進める。 外部プロセスからの接続