--- title: 箱庭_examples tags: author: [Shinji Makino](https://docswell.com/user/buildko89) site: [Docswell](https://www.docswell.com/) thumbnail: https://bcdn.docswell.com/page/87DKRMK3JG.jpg?width=480 description: 箱庭シミュレータの基礎を覚えるためのexamplesプログラムの説明資料 published: June 16, 26 canonical: https://docswell.com/s/buildko89/K7N43V-2026-06-16-121943 --- # Page. 1 ![Page Image](https://bcdn.docswell.com/page/87DKRMK3JG.jpg) examples.md 2026-06-15 箱庭コア サンプル解説書 本ドキュメントでは、hakoniwa-core-pro\examples に含まれるサンプルプログラム（hello_world, pdu_communication, service）の機能、構成、および操作手順について解説します。また、Pythonによる外 部連携サンプルについても詳細に補足します。 ソースコードの入手は、以下のサイトからお願いします。 https://github.com/hakoniwalab/hakoniwa-core-pro.git 1. 概要 箱庭コアのサンプルは、箱庭アセットAPIを利用したシミュレーションの構築方法を段階的に学ぶために提供 されています。主にC++で記述されたコアサンプルと、Pythonによる拡張サンプルで構成されています。 主要サンプル一覧 カテゴリ サンプル名 基本 hello_world 通信(PDU) pdu_communication 通信 service 外部連携 external (Service) 2. Hello World 2.1 概要 内容 基本的なアセット 作成 アセット間PDU通 信 クライアント/サー バー通信 からの通信 Python 主な学習項目 アセット登録、ライフサイクル（初期化・ ステップ・リセット） PDU（Protocol Data Unit）による定期的な データ交換 サービス（Request-Response）による非同 期通信 Python bindingsを利用したデータ送受信、 サービス呼び出し サンプル 箱庭アセットの最も基本的な構成を示すサンプルです。一つのアセットが箱庭マスターに登録され、シミュ レーションのライフサイクルイベント（開始、ステップ実行、停止、リセット）を受け取る流れを確認でき ます。 2.2 構成 HelloWorld: 単一のアセット。 主要ファイル ファイル src/hello_world.c 役割 アセットのメインロジック。各種コールバック関数を実装。 1 / 10 # Page. 2 ![Page Image](https://bcdn.docswell.com/page/VJPKWRKPE8.jpg) examples.md 2026-06-15 ファイル custom.json pdutypes.json hello_world.py 役割 アセットの定義ファイル（名前、エンドポイントなど）。 使用するPDUデータの型定義。 同等の機能をPythonで実装した参考コード。 シークエンス図 hako-cmd ( ユーザー操作) 箱庭マスター (内部) アセット HelloWorld アセット登録 (hako_asset_register) WAIT START 状態 hako-cmd start 初期化通知 (on_initialize) loop [ シミュレーションステップ] ステップ実行通知 (on_simulation_step) hako-cmd stop / reset リセット通知 (on_reset) プログラム終了 hako-cmd ( 2.3 ユーザー操作) 箱庭マスター (内部) 操作手順 ビルド済みのバイナリが examples\hello_world にあることを前提とします。 1. アセットの起動 (端末A) .\examples\hello_world\hello_world HelloWorld .\examples\hello_world\custom.json 100 第1引数: アセット名 第2引数: 設定ファイルパス 2 / 10 アセット HelloWorld # Page. 3 ![Page Image](https://bcdn.docswell.com/page/2EVV8RVVEQ.jpg) examples.md 2026-06-15 第3引数: ステップ実行間隔(ミリ秒) ログに WAIT START と表示されれば、箱庭マスターへの登 録成功です。 2. シミュレーション開始 (端末B) hako-cmd start 端末Aで on_simulation_step が定期的に呼ばれ、ログが出力されます。 3. 停止とリセット (端末B) hako-cmd stop hako-cmd reset 端末Aで on_reset が実行され、アセットが終了します。 3. PDU Communication 3.1 概要 サンプル つのアセット（PlantとController）がPDU（共有メモリを介したデータ）を用いて相互に通信するサンプル です。Plantは観測データ（位置）を送信し、Controllerは制御命令（モーター値）を送信する、典型的な制御 システムの構造を模しています。 2 3.2 構成 プラント（物理対象）側アセット。 asset_controller: コントローラ側アセット。 主要ファイル asset_plant: ファイル src/asset_plant.c src/asset_controller.c src/pdu_info.h custom.json 役割 モーター値を読み込み、位置データを書き込むロジック。 位置データを読み込み、モーター値を書き込むロジック。 チャネルID等の定数定義。 PDUチャネルの設定（どのIDがどのデータを指すか） 。 チャネル定義 PDU チャネルID 名前 送信元 送信先 データ型 0 Robot_motor Controller Plant geometry_msgs/Twist 1 Robot_pos Plant Controller geometry_msgs/Twist 3 / 10 # Page. 4 ![Page Image](https://bcdn.docswell.com/page/57GL5ML1EL.jpg) examples.md 2026-06-15 通信構造図 PDU Communication asset_controller Robot_motor (ID:0) Robot_pos (ID:1) asset_plant 3.3 操作手順 1. Plant アセットの起動 (端末A) .\examples\pdu_communication\asset_plant examples\pdu_communication\custom.json アセットの起動 (端末B) 2. Controller .\examples\pdu_communication\asset_controller examples\pdu_communication\custom.json 3. シミュレーション開始 (端末C) hako-cmd start 端末AにControllerからの受信データ、端末BにPlantからの受信データがリアルタイムで表示されます。 4. 停止とリセット (端末C) hako-cmd stop hako-cmd reset 4 / 10 # Page. 5 ![Page Image](https://bcdn.docswell.com/page/4EQYZRYNJP.jpg) examples.md 2026-06-15 4. Service 4.1 概要 サンプル クライアント/サーバー型の非同期通信（Service）を扱うサンプルです。PDUのような定期的・ストリーミン グ的な通信ではなく、「依頼（Request）に対して応答（Response）を返す」オンデマンドな通信を実現しま す。本サンプルでは、2つの数値を加算する AddTwoInts サービスを実装しています。 4.2 構成 加算処理を行うサーバー側アセット。 asset_client: 加算を依頼するクライアント側アセット。 主要ファイル asset_server: ファイル src/asset_server.cpp src/asset_client.cpp service.json custom.json 役割 サービスのリクエストを待ち受け、計算結果を返却。 サービスに対して数値を送り、結果を表示。 サービス名や型名の定義. アセットの共通設定. サービス定義 サービス名 リクエスト型 レスポンス型 内容 Service/Add AddTwoIntsRequest (a, b) AddTwoIntsResponse (sum) a+b シークエンス図 5 / 10 を計算して返す # Page. 6 ![Page Image](https://bcdn.docswell.com/page/KJ4W38W371.jpg) examples.md 2026-06-15 asset_client asset_server シミュレーション開始済み Request (a=1, b=2) 加算処理実行 Response (sum=3) asset_client 4.3 asset_server 操作手順 1. Server アセットの起動 (端末A) .\examples\service\asset_server examples\service\custom.json normal 第3引数に normal を指定することで、通常の加算処理を行います。 2. Clientアセットの起動 (端末B) .\examples\service\asset_client examples\service\custom.json 3. シミュレーション開始 (端末C) hako-cmd start のログに OUT: sum=3 と表示されれば、サービス連携成功です。 4. 停止とリセット (端末C) Client 6 / 10 # Page. 7 ![Page Image](https://bcdn.docswell.com/page/LE1Y12YZ7G.jpg) examples.md 2026-06-15 hako-cmd stop hako-cmd reset 5. external 外部連携サンプル詳細 ディレクトリには、Python bindings (hakoniwa_pdu ライブラリ) を使用して、箱庭の 共有メモリ(SHM)へ直接アクセスするサンプルが含まれています。これにより、C++で記述されたシミュレー タ本体とPythonプログラムの間で高速なデータ交換が可能になります。 examples\external 通信 (external/topic) 5.1 Topic から定期的にデータを送信（Publish）または受信（Subscribe）するサンプルです。 構成と主要ファイル Python ファイル 役割 publisher.py ShmPublisher subscriber.py service.json pdu_config.json を使用し、位置データ(Twist)を定期的に送信。 ShmSubscriber を使用し、データを受信した際にコールバックを実行。 通信エンドポイントやPDUサイズの設定ファイル。 PDUのメモリレイアウト定義ファイル。 通信構造図 7 / 10 # Page. 8 ![Page Image](https://bcdn.docswell.com/page/GEWG8RG6J2.jpg) examples.md 2026-06-15 Python Topic Communication publisher.py drone2/pos (Topic) 共有メモリ drone2/pos (Topic) subscriber.py 操作手順 の起動 (端末A) 1. Subscriber python .\examples\external\topic\subscriber.py 内部で shm.start_conductor() を実行し、受信待機状態になります。 2. Publisherの起動 (端末B) python .\examples\external\topic\publisher.py 定期的に Twist メッセージが送信され、端末Aに受信データが表示されます。 通信 (external/service) 5.2 Service からRequest-Response形式で非同期通信を行うサンプルです。 Python 8 / 10 # Page. 9 ![Page Image](https://bcdn.docswell.com/page/47ZL8RLRJ3.jpg) examples.md 2026-06-15 構成と主要ファイル ファイル 役割 ext_server.py ShmServiceServer ext_client.py service.json を実装。リクエストに対して加算結果を返却。 ShmServiceClient を使用。サーバーに対して加算をリクエスト。 サービスのチャネル設定ファイル。 シークエンス図 ext_client.py ext_server.py 初期化済み ShmCommon call_async(AddTwoIntsRequest: a=1, b=2) 実行 my_add_handler AddTwoIntsResponse(sum=3) Response: sum=3 を表示 ext_client.py ext_server.py 操作手順 1. Service Server の起動 (端末A) python .\examples\external\service\ext_server.py エンドポイントでリクエストを待ち受けます。 2. Service Clientの実行 (端末B) Service/Add python .\examples\external\service\ext_client.py サーバーに a=1, b=2 を送り、結果を受け取って終了します。 5.3 共通設定項目 (service.json) 9 / 10 # Page. 10 ![Page Image](https://bcdn.docswell.com/page/YJ6WPRW1JV.jpg) examples.md 2026-06-15 以下の各 service.json には、共有メモリへのアクセスに必要な以下の情報が定義されています。 項目 説明 pduMetaDataSize メタデータのサイズ（通常24バイト） 。 pdu_config_path PDU定義ファイルへのパス。 nodes Topic通信を行うノード（アセット）とTopic名の定義。 services サービス通信のエンドポイント名とデータ型の定義。 external 5.4 プログラム実装のポイント 箱庭の共有メモリを管理する基本クラス。初期化 (initialize) や実行制御 (start_conductor, start_service) を行います。 Encoder/Decoder: Pythonのオブジェクトと箱庭のバイナリデータ（PDU）を変換するための関数 （例: py_to_pdu_Twist）を指定する必要があります。 非同期処理: Pythonサンプルは asyncio を利用しており、効率的なI/O待ちを実現しています。 ShmCommon: 10 / 10