mapoi_turtlebot3_example

English version (primary): README.md 本ファイルは日本語スナップショットです。最新の内容は英語版を参照してください。

TurtleBot3 シミュレーション環境で mapoi の動作を確認するためのサンプルパッケージです。 SLAM による地図作成から Navigation2 を用いた自律走行までの一連の手順を試すことができます。

依存パッケージのインストール

rosdep を使用する場合:

# cd path/to/your_ws/
rosdep install --from-paths src --ignore-src -r -y

手動でインストールする場合:

sudo apt install -y \
  ros-${ROS_DISTRO}-turtlebot3-simulations \
  ros-${ROS_DISTRO}-turtlebot3-cartographer \
  ros-${ROS_DISTRO}-turtlebot3-navigation2 \
  ros-${ROS_DISTRO}-mouse-teleop

クイックスタート

export TURTLEBOT3_MODEL=burger
ros2 launch mapoi_turtlebot3_example turtlebot3_navigation.launch.yaml

別ターミナルから POI への自律走行をテスト:

ros2 topic pub -1 /mapoi/nav/goal_pose_poi std_msgs/msg/String "{data: goal}"

機能ごとの demo route (#230)

turtlebot3_world map には mapoi の主な機能を 1 route ずつ確認できる tutorial 系と、全機能を 1 route で踏む tour_full の合計 4 route が定義されています。6 POI で全機能をカバーする抽象命名構成 (自前 robot への流用を想定)。

推奨確認順序:

1. tutorial_01_basic — 基本 navigation health check (start → basic_waypoint → goal を順に走破)
2. WebUI / RViz の map switch / POI 編集 をブラウザで操作 (route 不要)
3. tutorial_02_landmark — landmark 機能の確認 (tutorial_01 と同じ waypoint に route.landmarks: [audio_landmark] を登録)。demo subscriber 起動時は audio_guide_node が audio_landmark の EVENT_ENTER で音声発話 mock、未起動時は ros2 topic echo /mapoi/events で発火確認
4. tutorial_03_pause — pause 機能の確認 (pause_waypoint で自動 pause)。demo subscriber 起動時は camera_node が capture_trigger タグ + pause 中に撮影 mock + resume publish、未起動時は別 shell から手動 ros2 topic pub /mapoi/nav/resume
5. tour_full — 全部入り総合 demo

各 route の起動例:

# 基本: 移動だけの確認
ros2 topic pub -1 /mapoi/nav/route std_msgs/msg/String "{data: tutorial_01_basic}"

# landmark: 別 terminal で `ros2 topic echo /mapoi/events` を流し、
# audio_landmark の EVENT_ENTER が出ることを確認 (demo subscriber 未起動時)
ros2 topic pub -1 /mapoi/nav/route std_msgs/msg/String "{data: tutorial_02_landmark}"

# pause + 手動 resume (demo subscriber 未起動時 / default): 停止後に別 shell から resume
ros2 topic pub -1 /mapoi/nav/route std_msgs/msg/String "{data: tutorial_03_pause}"
ros2 topic pub -1 /mapoi/nav/resume std_msgs/msg/String "{data: ''}"

# pause + auto-resume (opt-in): mapoi_nav2_bridge の auto_resume_timeout_sec を正値で
# 起動した場合のみ、同じ tutorial_03_pause route で N 秒後に bridge が自動 resume
ros2 topic pub -1 /mapoi/nav/route std_msgs/msg/String "{data: tutorial_03_pause}"

# 総合 demo
ros2 topic pub -1 /mapoi/nav/route std_msgs/msg/String "{data: tour_full}"

NOTE: demo subscriber (audio_guide_node / camera_node) は turtlebot3_navigation.launch.yaml には含まれません (#238 で分離)。mapoi_event_samples.launch.yaml を別 shell で起動した時のみ audio_guide / camera の log が出ます。subscriber を立ち上げずに /mapoi/events の発火だけ確認するモードでも、上記コマンドで demo として成立します。

Headless 起動（GUI なし）

CI / SSH 接続環境 / 軽量検証用に RViz2・Gazebo GUI を起動しない形で立ち上げられます。WebUI (http://localhost:8765) は従来どおり使用可能です。

ros2 launch mapoi_turtlebot3_example turtlebot3_navigation.launch.yaml \
  rviz:=false gazebo_gui:=false

個別制御も可能:

gazebo_gui は Humble (Gazebo Classic) と Jazzy (gz-sim) のどちらでも有効です。distro 別の wrapper (gazebo_headless_aware.launch.yaml / gz_sim_headless_aware.launch.yaml) を turtlebot3_navigation.launch.yaml から ROS_DISTRO で使い分けています。rviz:=false は distro によらず動作。

地図の作成（SLAM）

1. シミュレーターの起動

```sh export TURTLEBOT3_MODEL=burger

File truncated at 100 lines see the full file

Changelog for package mapoi_turtlebot3_example

This per-package file lists only the changes affecting mapoi_turtlebot3_example (sample maps, client nodes, and demo launch files), in the flat format expected by bloom / buildfarm. Full project-level narrative: root CHANGELOG.rst / the GitHub Releases page.

Forthcoming

0.6.0 (2026-07-15)

• No changes for this package in this release.

0.5.0 (2026-07-10)

• Launch the demo with waypoint_arrival_mode:=mapoi by default and re-tune the waypoint tolerance.xy to 0.3 m (kept above Nav2's xy_goal_tolerance) (#243, #259, #260, #261, #263, #264, #265, #266).
• Redesign the turtlebot3_world demo into a feature-catalog layout: POIs start / basic_waypoint / pause_waypoint / goal / audio_landmark and routes tutorial_01_basic / tutorial_02_landmark / tutorial_03_pause / tour_full (not a 1:1 rename of the old office-tour sample) (#230, #235).
• Add PoiEvent-driven sample subscribers audio_guide_node (announce on EVENT_ENTER) and camera_node (capture on EVENT_PAUSED, then publish mapoi/nav/resume), launched from a separate mapoi_event_samples.launch.yaml (#88, #238, #248).
• A Gazebo GUI render/driver failure no longer brings down the whole demo; navigation continues headless (#294, #295).

0.4.0 (2026-05-08)

• No changes for this package in this release.

0.3.0 (2026-05-02)

• Sample maps now live only in mapoi_turtlebot3_example (single source of truth) after being removed from mapoi_server (#163).
• Differentiate the sample map_file names per world (e.g. turtlebot3_world.{pgm,yaml} / turtlebot3_dqn_stage1.{pgm,yaml}) to match the directory names (#163).
• Rework the sample YAMLs to cover the full feature matrix (consecutive pause, yaw-agnostic passes, landmark variations, composite-tag hazards); routes renamed (route_1 -> tour_full, route_2 -> tour_short); new custom tags added (#146).
• Add scripts/check_sample_yaml_consistency.py plus CI hookup to validate POI/route/landmark references, tag-exclusion rules, and tolerance minimums in the sample YAMLs (#146).

0.2.0 (2026-04-29)

• Add a gz_sim_headless_aware.launch.yaml wrapper for Jazzy headless launches (#42, #49).
• Rework the turtlebot3_world and turtlebot3_dqn_stage1 example configs with distinct themes and Nav2-aligned radii (#79, #82).